# 工作流集成文档 (Workflow Integration)

## 概述

本文档描述了外部AI平台工作流与AX文档编辑器前端的集成。通过此集成，用户可以在聊天界面输入自然语言指令（如"生成一个地质报告"），系统会自动触发工作流，生成文档并返回可下载的URL链接。

## 架构设计

### 整体流程图

```
用户输入（聊天）
    ↓
Chat Store (检查是否触发工作流)
    ↓
Workflow Service (调用外部AI平台 v2 API)
    ↓
外部工作流平台 (http://114.242.25.27:3000/api/v2/chat/completions)
    ↓
本地后端 API (http://192.168.0.200:8000/api/v1/export/records)
    ↓
返回导出记录 (Export Record with downloadUrl)
    ↓
在聊天中显示文档卡片
    ↓
用户点击查看/下载文档
```

## 核心组件

### 1. Workflow Service (`src/services/workflowService.ts`)

**作用**: 处理与外部工作流API的通信。

**关键函数**:

#### `shouldTriggerWorkflow(input: string): boolean`
判断用户输入是否应该触发文档生成工作流。

**触发模式**:
- **生成动作**: 生成、创建、制作、编写、generate、create
- **文档类型**: 报告、文档、方案、总结、分析、report、document、doc

**示例**:
```typescript
shouldTriggerWorkflow("生成一个地质报告") // true
shouldTriggerWorkflow("创建技术文档")     // true
shouldTriggerWorkflow("你好")           // false
```

#### `triggerDocumentWorkflow(userInput: string, chatId: string)`
调用工作流API生成文档并返回导出记录。

**API端点**:
```
POST http://114.242.25.27:3000/api/v2/chat/completions
```

**请求头**:
```
Content-Type: application/json
Authorization: Bearer XAgent-mWHBqQw06psUYRqx6PrHWiKdfY05ebt7I9drDBHzaG9QQesIkVEICj
```

**请求体**:
```json
{
  "chatId": "session-uuid",
  "stream": false,
  "detail": false,
  "messages": [
    {
      "role": "user",
      "content": "生成一个地质报告"
    }
  ]
}
```

**响应格式**:
```json
{
  "content": "已为您生成地质报告",
  "exportRecord": {
    "recordId": "rec-e22bbf07350d",
    "userId": "default-user",
    "fileName": "地质报告_1782369497876.doc",
    "fileSize": 39076,
    "downloadUrl": "http://192.168.0.200:8000/api/v1/export/records/rec-e22bbf07350d/download?userId=default-user",
    "documentId": "doc-d2ef5b701b5c",
    "styleId": "default",
    "createdAt": 1782369497764
  }
}
```

或者数组格式：
```json
{
  "content": "已为您生成地质报告",
  "records": [
    {
      "recordId": "rec-e22bbf07350d",
      ...
    }
  ]
}
```

### 2. Chat Store (`src/stores/chatStore.ts`)

**修改内容**:

#### 导入工作流服务
```typescript
import { shouldTriggerWorkflow, triggerDocumentWorkflow } from '../services/workflowService';
```

#### 修改 `sendMessage` 函数
```typescript
// 检查是否需要触发工作流
const shouldUseWorkflow = shouldTriggerWorkflow(content);

if (shouldUseWorkflow) {
  // 使用工作流生成文档
  const workflowResult = await triggerDocumentWorkflow(content, sessionId);
  aiResponse = workflowResult.content;
  exportRecord = workflowResult.exportRecord;
} else {
  // 使用常规AI服务
  const aiResult = await getAIResponse(content, sessionId, get().messages);
  aiResponse = aiResult.response;
}

// 创建AI消息并附加导出记录
const aiMessage: ChatMessage = {
  id: uuidv4(),
  role: 'assistant',
  content: aiResponse,
  timestamp: Date.now(),
  exportRecord: exportRecord, // 附加导出记录
};
```

### 3. Message Item Component (`src/components/ChatPanel/MessageItem.tsx`)

**功能**: 已有支持渲染导出记录为可点击文档卡片。

当消息中包含 `exportRecord` 时，会显示一个文档卡片：
- Word图标
- 文件名
- "点击预览文档"文本
- 眼睛图标

用户点击卡片会触发 `onDocumentClick` 回调。

### 4. App Component (`src/App.tsx`)

**功能**: 处理文档点击事件，在编辑器中打开文档。

```typescript
const handleDocumentClick = useCallback((exportRecord: ExportRecordInfo) => {
  setPreviewDocument({
    downloadUrl: exportRecord.downloadUrl,
    fileName: exportRecord.fileName,
    recordId: exportRecord.recordId,
    userId: exportRecord.userId,
    documentId: exportRecord.documentId,
  });
  setPreviewMode('editor');
}, []);
```

## 配置

### 环境变量

在 `.env` 文件中添加：

```bash
# 工作流API配置
# 工作流API URL（v2 - 带工作流）
VITE_WORKFLOW_API_URL=http://114.242.25.27:3000/api/v2/chat/completions

# 工作流API密钥
VITE_WORKFLOW_API_KEY=XAgent-mWHBqQw06psUYRqx6PrHWiKdfY05ebt7I9drDBHzaG9QQesIkVEICj
```

在 `.env.example` 文件中添加（示例）：

```bash
# 工作流API配置
VITE_WORKFLOW_API_URL=http://114.242.25.27:3000/api/v2/chat/completions
VITE_WORKFLOW_API_KEY=your_workflow_api_key_here
```

## 使用方法

### 终端用户使用

1. **打开聊天面板**
2. **输入文档生成请求**，例如：
   - "生成一个地质报告"
   - "创建技术文档"
   - "制作项目分析报告"
   
3. **系统自动处理**：
   - 检测到文档生成请求
   - 触发工作流
   - 调用外部AI平台
   - 生成文档
   - 返回导出记录
   
4. **查看结果**：
   - AI回复消息
   - 文档卡片出现在消息下方
   - 显示文件名和预览按钮
   
5. **点击文档卡片**：
   - 在编辑器中打开文档
   - 或在新标签页下载文档

### 触发条件示例

✅ **会触发工作流**:
- "生成一个地质报告"
- "创建技术文档"
- "制作项目分析报告"
- "编写总结文档"
- "generate a report"

❌ **不会触发工作流**:
- "你好" (无生成动作或文档类型)
- "生成图片" (无文档类型关键词)
- "打开文档" (无生成动作)
- "分析一下数据" (无生成动作)

## 错误处理

### 优雅降级

工作流集成设计为优雅降级：

1. **API密钥未配置**:
   - 跳过工作流
   - 控制台警告
   - 返回提示消息

2. **工作流API调用失败**:
   - 错误记录到控制台
   - 返回错误消息给用户
   - 不中断聊天体验

3. **工作流未返回导出记录**:
   - 控制台警告
   - 显示AI响应
   - 不显示文档卡片

### 调试日志

在浏览器控制台可以看到工作流执行日志：

- `🔄 Using workflow for document generation` - 开始使用工作流
- `🔄 Triggering document generation workflow...` - 触发工作流
- `📝 User input: 生成一个地质报告` - 用户输入
- `✅ Workflow response received:` - 收到工作流响应
- `📄 Export record extracted:` - 提取导出记录
- `⚠️ No export record found in workflow response` - 未找到导出记录
- `❌ Workflow API error:` - 工作流API错误

## 测试

### 手动测试步骤

1. **启动开发服务器**:
   ```bash
   cd d:\work space\ax-shell\ax-frontend-app
   npm run dev
   ```

2. **打开应用**: 浏览器访问 `http://localhost:5173`

3. **创建新会话**: 点击聊天面板

4. **输入文档生成请求**:
   ```
   生成一个地质报告
   ```

5. **验证工作流**:
   - 检查浏览器控制台日志
   - 等待AI响应
   - 查看消息下方的文档卡片
   - 验证文件名显示正确

6. **测试文档下载**:
   - 点击文档卡片
   - 文档应在编辑器中打开
   - 或在新标签页下载

### 预期行为

1. 用户输入："生成一个地质报告"
2. 聊天显示加载指示器
3. 工作流在后台触发
4. AI响应显示
5. 文档卡片出现，显示：
   - 文件图标
   - 文件名（例如："地质报告_1782369497876.doc"）
   - "点击预览文档"文本
6. 点击卡片在编辑器中打开文档
7. 显示成功提示："✅ 文档已生成，点击下方卡片查看"

## 后端集成

### 导出记录API

工作流内部调用本地后端导出记录API：

```
GET http://192.168.0.200:8000/api/v1/export/records?userId=default-user&page=1&pageSize=20
```

此API返回生成的导出记录列表，工作流将其转发给前端。

### 文档下载

文档通过以下端点下载：

```
GET http://192.168.0.200:8000/api/v1/export/records/{recordId}/download?userId={userId}
```

## 工作流平台配置

### 工作流设置

在外部AI平台 (http://114.242.25.27:3000) 中，工作流应该配置为：

1. **接收用户输入**: 从聊天消息中提取文档生成请求
2. **处理请求**: 根据请求类型（地质报告、技术文档等）生成文档
3. **调用后端API**: 调用 `http://192.168.0.200:8000/api/v1/export/records`
4. **返回结果**: 将导出记录数据返回给前端

### API响应格式

工作流API应该返回以下格式之一：

**格式1：单个导出记录**
```json
{
  "content": "AI响应文本",
  "exportRecord": {
    "recordId": "rec-xxx",
    "fileName": "地质报告_xxx.doc",
    "downloadUrl": "http://192.168.0.200:8000/api/v1/export/records/rec-xxx/download?userId=xxx",
    "documentId": "doc-xxx",
    "userId": "default-user",
    "fileSize": 39076,
    "styleId": "default",
    "createdAt": 1782369497764
  }
}
```

**格式2：导出记录数组**
```json
{
  "content": "AI响应文本",
  "records": [
    {
      "recordId": "rec-xxx",
      "fileName": "地质报告_xxx.doc",
      "downloadUrl": "http://...",
      ...
    }
  ]
}
```

## 安全考虑

1. **API密钥存储**: 
   - 存储在环境变量中
   - 不提交到版本控制
   - `.env.example` 中使用占位符

2. **身份验证**:
   - 使用 `Bearer` token 进行工作流认证
   - 每个请求包含用户ID用于授权

3. **CORS**:
   - 工作流API必须允许来自前端源的CORS
   - 后端API必须允许来自前端源的CORS

## 故障排查

### 问题：工作流未触发

**检查**:
1. `.env` 中是否设置了 `VITE_WORKFLOW_API_KEY`？
2. 输入是否匹配触发模式？
3. 检查浏览器控制台错误
4. 验证工作流API可访问性

### 问题：未显示文档链接

**检查**:
1. 工作流是否返回了记录？检查控制台日志
2. `exportRecord` 是否正确附加到消息？
3. 检查网络标签中的工作流API响应
4. 验证响应格式是否匹配预期结构

### 问题：文档下载失败

**检查**:
1. 后端API是否运行？
2. 下载URL是否包含正确的记录ID？
3. 检查后端日志错误
4. 验证文件在服务器上存在

## 未来增强

1. **多文档生成**: 
   - 支持一次请求生成多个文档
   - 显示多个文档卡片

2. **文档模板**:
   - 允许用户在生成前选择模板
   - 将模板ID传递给工作流

3. **进度指示**:
   - 显示文档生成进度条
   - 显示预计剩余时间

4. **重试逻辑**:
   - 工作流失败时自动重试
   - 指数退避策略

5. **文档预览**:
   - 聊天中内联文档预览
   - 下载前预览

## 相关文档

- [导出记录API](../../ax-backend-shell/docs/text-editor-backend-api.md)
- [聊天面板架构](./text-editor-architecture.md)
- [导出服务设计](./export-doc-content-mapping.md)

## 版本历史

- **v1.0** (2026-06-25): 工作流集成初始实现
  - 添加工作流服务
  - 集成到聊天store
  - 更新消息渲染
  - 添加环境配置