olons_server/docs/IM工作台AI接入需求文档.md

# IM 工作台 AI 接入需求文档

> 本文档根据 `docs/ai/` 目录下的工作台 AI 原型图整理，并参照 `docs/IM-产品原型需求文档.md` 的编写方式补充产品流程、前后端接口、服务端任务、数据存储和异常处理要求。原型图路径均相对于本文档所在 `docs/` 目录。

## 产品总体定位

工作台 AI 是 IM 企业工作台中的智能办公能力集合，目标是在不打断原有工作台、日报、月报、会议笔记等业务流程的前提下，为用户提供文本优化、文档生成、表格解读、会议总结和办公应用检索能力。

首版能力聚焦 5 类场景：

1. 工作台入口与应用搜索：在工作台首页展示 AI 能力入口，并支持搜索工作台应用。
2. 智能文档：根据用户输入的核心内容生成结构化文档，并支持保存和查看生成记录。
3. 智能表格：上传 Excel/CSV 报表，由 AI 生成指标、数据预览、异常提醒和核心解读，并支持导出报告。
4. AI 美文：对日报、月报等用户输入内容进行语言润色优化，支持重新生成和使用文案。
5. 会议笔记 AI 总结：基于会议资料、会议笔记或上传文件生成会议结论、关键决策和后续安排。

系统设计上，AI 生成类功能必须采用异步任务模型，保留任务状态、输入内容、文件来源、生成结果、错误原因和用户操作记录；同时必须保证租户隔离、用户权限校验、敏感信息保护和生成结果可追溯。

## 0. 通用约定

### 0.1 入口与鉴权

工作台 AI 接口统一挂载在工作台服务下：

```text
/v1/workbench/ai/*
```

公共请求头沿用工作台接口约定：

```http
Authorization: Bearer <IM token>
X-MeetingIM-APIKey: <api key>
X-IM-Schema: 1
X-Tenant-Code: <tenant code>
X-Request-ID: <uuid>
Idempotency-Key: <uuid>   # 写请求必传
```

服务端从 IM 登录态解析当前用户和租户，不允许前端在请求体中伪造 `tenant_id`、`user_id`、`internal_user_id`。

### 0.2 租户隔离

AI 任务、记录、上传文件和导出文件必须按租户隔离。

要求：

1. 所有 AI 数据表必须包含 `tenant_id`。
2. 查询记录时只能返回当前租户、当前用户有权限查看的数据。
3. 会议总结类任务必须校验当前用户是否可查看该会议笔记。
4. 日报、月报 AI 美文只允许操作当前用户本人正在编辑的草稿内容。
5. 后台管理或运营查询必须走独立内部接口，并记录审计日志。

### 0.3 AI 内容安全

AI 生成内容需要明确展示“由 AI 生成，请核对后使用”一类提示。前端不得默认替用户提交 AI 结果，必须由用户主动点击“使用文案”“保存文档”“提交”“导出”等操作。

服务端要求：

1. 保存原始输入和 AI 输出，便于用户追溯和问题排查。
2. 不把用户输入、AI 输出、文件内容直接写入普通日志。
3. 调用第三方 AI 服务时，按租户和用户记录调用量、token 用量、耗时、状态和错误码。
4. AI 输出失败、超时、内容违规时返回稳定错误码，前端展示可重试提示。
5. 对上传文件做类型、大小、行数和解析安全校验，避免公式注入、超大文件和恶意内容影响服务。

### 0.4 任务状态

AI 生成类任务统一使用如下状态：

| 状态 | 含义 | 前端表现 |
| --- | --- | --- |
| `pending` | 已创建，等待执行 | 显示排队中 |
| `processing` | 正在处理 | 显示进度页或 loading |
| `succeeded` | 生成成功 | 展示结果，可保存/导出/使用 |
| `failed` | 生成失败 | 展示失败原因和重试入口 |
| `canceled` | 用户取消 | 返回上一页或记录为已取消 |
| `expired` | 临时结果过期 | 提示重新生成 |

表格解读可额外返回分阶段进度：

| 阶段 | 含义 |
| --- | --- |
| `read_table` | 读取表格数据 |
| `extract_metrics` | 识别核心指标 |
| `analyze_trends` | 分析趋势变化 |
| `generate_report` | 生成解读报告 |

### 0.5 统一响应

成功响应：

```json
{
  "code": 0,
  "data": {},
  "request_id": "uuid",
  "server_time": "2026-09-25T10:00:00Z"
}
```

失败响应：

```json
{
  "code": 30000,
  "reason": "MALFORMED_REQUEST",
  "message": "malformed request",
  "details": {
    "field": "title"
  },
  "request_id": "uuid",
  "server_time": "2026-09-25T10:00:00Z"
}
```

## 1. 工作台首页与 AI 入口

### 1.1 工作台.png

<img src="ai/工作台.png" alt="工作台" width="360">

功能说明：

工作台首页展示顶部搜索框、AI 欢迎区、常用软件和全部应用。AI 欢迎区使用机器人形象和提示文案“你好，开始高效办公吧 / 整理文档、解读报表，让工作更轻松”，用于引导用户进入智能办公能力。

常用软件首版包含：

1. 打卡
2. 日报
3. 智能文档
4. 智能表格

全部应用首版包含：

1. 部门框架
2. 举报反馈
3. 会议笔记
4. 会议通知
5. 月报

业务规则：

1. 工作台首页应用列表由服务端返回，前端按服务端排序展示。
2. `智能文档` 和 `智能表格` 需要支持开关控制，租户未启用 AI 时不展示或置灰。
3. 首页未读角标沿用工作台既有能力，例如会议通知、工作台入口底部角标。
4. AI 欢迎区仅作为引导，不直接触发生成任务。
5. 页面加载失败时，保留本地缓存应用列表，并提示稍后重试。

建议接口：

```http
GET /v1/workbench/ai/capabilities
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "enabled": true,
    "features": {
      "smart_document": true,
      "smart_table": true,
      "text_polish": true,
      "meeting_summary": true
    },
    "limits": {
      "document_input_max_chars": 1000,
      "text_polish_max_chars": 300,
      "table_file_max_size": 10485760
    }
  }
}
```

## 2. 工作台应用搜索

### 2.1 工作台-搜索页面.png

<img src="ai/工作台-搜索页面.png" alt="工作台-搜索页面" width="360">

功能说明：

用户点击工作台首页搜索框后进入搜索页。页面顶部展示返回按钮、搜索输入框和“取消”按钮；默认展示常用应用宫格，包括打卡、日报、智能文档、智能表格、部门框架、举报反馈、会议笔记、会议通知。

业务规则：

1. 搜索框 placeholder 为“搜索应用”。
2. 未输入关键词时展示常用应用。
3. 点击“取消”或左上角返回按钮回到工作台首页。
4. 点击任一应用进入对应功能页。
5. 搜索结果应只返回当前租户启用、当前用户有权限访问的应用。

### 2.2 工作台-搜索页面-明确展示.png

<img src="ai/工作台-搜索页面-明确展示.png" alt="工作台-搜索页面-明确展示" width="360">

功能说明：

用户输入关键词后展示“搜索结果”卡片。结果项展示应用图标、应用名称和右侧箭头，点击进入对应应用。

业务规则：

1. 支持按应用名称、别名、拼音首字母进行搜索。
2. 搜索关键词前后空格需要 trim。
3. 支持模糊匹配，例如搜索“组织框架”命中“部门框架”或“组织框架”，具体别名由服务端配置。
4. 搜索结果按常用度、名称匹配度、应用排序综合排序。

建议接口：

```http
GET /v1/workbench/apps/search?q=组织框架
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "app_id": "organization",
        "name": "组织框架",
        "icon": "organization",
        "route": "/workbench/organization",
        "enabled": true
      }
    ]
  }
}
```

### 2.3 工作台-搜索页面-无结果.png

<img src="ai/工作台-搜索页面-无结果.png" alt="工作台-搜索页面-无结果" width="360">

功能说明：

无匹配应用时展示空状态插画和“暂无匹配结果”文案。

业务规则：

1. 搜索接口返回空数组时展示该状态。
2. 网络异常不展示“暂无匹配结果”，应展示网络错误或重试提示。
3. 清空关键词后恢复常用应用列表。

## 3. 智能文档

智能文档用于将用户输入的核心内容生成结构化办公文档，适合会议纪要、沟通纪要、任务安排、项目说明等轻量文档场景。

### 3.1 智能文档(2).png

<img src="ai/智能文档(2).png" alt="智能文档输入空状态" width="360">

功能说明：

智能文档首页顶部标题为“智能文档”，右上角展示“文档记录”入口。主体区域为“核心内容”输入框，placeholder 为“请输入”，右下角展示字数计数 `0/1000`，底部固定“生成文档”按钮。

业务规则：

1. 核心内容必填，最大 1000 字。
2. 未输入内容时，“生成文档”按钮可置灰或点击后提示“请输入核心内容”。
3. 输入超过 1000 字时禁止继续输入或提交时返回字段错误。
4. 点击“文档记录”进入当前用户的文档生成记录。
5. 返回按钮退出智能文档页，若有未提交内容，应按产品策略提示是否放弃草稿。

### 3.2 智能文档(1).png

<img src="ai/智能文档(1).png" alt="智能文档输入内容" width="360">

功能说明：

用户输入核心内容后，可点击“生成文档”。输入内容示例为新项目沟通、人员安排、功能范围和待确认事项。

生成规则：

1. AI 应从原始内容中识别主题、沟通事项、功能点、责任人、时间节点和待办事项。
2. 生成内容应使用清晰标题和分段结构。
3. 如果输入中包含人员和时间，应尽量保留并结构化。
4. 不应凭空生成用户未提及的关键事实；可用“待确认”表达不确定项。

建议接口：

```http
POST /v1/workbench/ai/documents/generate
Idempotency-Key: <uuid>
```

请求示例：

```json
{
  "source_text": "今天讨论新项目，确定新增群聊功能和朋友圈两个入口。小林负责设计，下周三交初稿；小陈负责开发，下周五给排期。首版支持手动输入、总结要点和生成文档。导出格式还需要确认。",
  "title_hint": "新项目沟通纪要"
}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_7abc",
    "status": "processing"
  }
}
```

### 3.3 智能文档.png

<img src="ai/智能文档.png" alt="智能文档生成结果" width="360">

功能说明：

文档生成完成后，页面展示 AI 生成文档。顶部保留“智能文档”标题和“编辑”入口；内容顶部显示“由 AI 生成”标签，正文包含文档标题“新项目沟通纪要”和分段内容，例如沟通事项、首版功能、任务安排、待办事项。底部展示“由 AI 整理，请核对后使用”提示，并提供“重新生成”和“保存文档”按钮。

业务规则：

1. AI 结果必须标识来源，不允许伪装成用户手写内容。
2. “重新生成”使用同一原始输入创建新一版结果，需要保留版本号。
3. “保存文档”将当前结果保存为文档记录，状态变为 `succeeded`。
4. “编辑”允许用户对 AI 结果进行人工修改，修改后保存的是用户确认后的最终内容。
5. 保存成功后可进入详情或返回工作台，具体交互由客户端确定。
6. 如果 AI 生成失败，展示失败状态和重试按钮。

生成结果查询接口：

```http
GET /v1/workbench/ai/tasks/{task_id}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_7abc",
    "task_type": "smart_document",
    "status": "succeeded",
    "result": {
      "title": "新项目沟通纪要",
      "content_markdown": "一、沟通事项\n\n新增群聊功能和朋友圈两个入口。\n\n二、首版功能\n\n1. 手动输入重点内容。\n2. 智能总结要点。\n3. 生成结构化文档。",
      "ai_disclaimer": "由 AI 整理，请核对后使用"
    }
  }
}
```

保存接口：

```http
POST /v1/workbench/ai/documents
Idempotency-Key: <uuid>
```

请求示例：

```json
{
  "task_id": "aitask_7abc",
  "title": "新项目沟通纪要",
  "content_markdown": "..."
}
```

### 3.4 总结记录(1).png

<img src="ai/总结记录(1).png" alt="文档记录" width="360">

功能说明：

文档记录页展示当前用户保存过的智能文档记录。顶部为关闭按钮、标题“文档记录”和搜索框。列表按日期分组，例如“今天”；每条记录展示 Word 图标、标题、文件类型、时间、状态“已完成”和右侧箭头。

业务规则：

1. 仅展示当前用户本人创建或有权限查看的文档记录。
2. 支持按标题搜索。
3. 记录按创建时间倒序排列。
4. 状态可展示 `已完成`、`生成中`、`失败`。
5. 点击记录进入文档详情。

建议接口：

```http
GET /v1/workbench/ai/records?type=smart_document&query=&cursor=&limit=20
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "record_id": "airec_doc_1",
        "type": "smart_document",
        "title": "8月销售数据分析",
        "file_type": "word",
        "status": "succeeded",
        "display_status": "已完成",
        "created_at": "2026-09-25T02:30:00Z"
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}
```

## 4. 智能表格与报告解读

智能表格用于上传 Excel 或 CSV 报表，AI 自动读取表格数据、识别核心指标、分析趋势变化，并生成解读报告。

### 4.1 智能表格.png

<img src="ai/智能表格.png" alt="智能表格" width="360">

功能说明：

页面标题区包含关闭按钮和“解读记录”入口。主体顶部为报表主题输入区域，placeholder 为“输入报表主题”。下方说明“上传将获得解读以下内容”，并列出 AI 解读能力：

1. 核心指标：快速提取重要业务数据。
2. 异常提醒：定位需要重点关注的数据。
3. 数据预览：分析环比、同比及变化趋势。
4. 核心解读：用简单语言说明数据结论。

底部固定按钮“选择文件”。

业务规则：

1. 报表主题必填，建议最大 50 字。
2. 用户必须选择文件后才能开始分析。
3. 支持 `xls`、`xlsx`、`csv`。
4. 首版每次只支持上传一个文件。
5. 已选择文件后可删除并重新选择。
6. 点击“解读记录”进入表格解读记录页。

### 4.2 选择文件.png

<img src="ai/选择文件.png" alt="选择文件" width="360">

功能说明：

点击“选择文件”后从底部弹出选择报表文件弹窗。可选择：

1. Excel 工作簿：支持 `XLS`、`XLSX`
2. CSV 数据文件：支持 `CSV`

底部提供“取消”按钮。

业务规则：

1. 文件类型必须由前后端共同校验，不能只按文件后缀判断。
2. 文件大小建议首版限制为 10 MB，可由服务端配置。
3. 表格行数、列数超过限制时返回明确错误。
4. 文件上传失败时保留当前页面，提示重新上传。
5. 文件中如存在多个 sheet，服务端默认读取第一个非空 sheet；后续可扩展 sheet 选择。

文件上传建议沿用 IM 文件接口：

```http
POST /v0/file/u/
X-MeetingIM-Auth: token <IM token>
X-MeetingIM-APIKey: <api key>
multipart/form-data
```

表单字段建议：

```text
id=<client request id>
purpose=ai_table_source
file=<xls/xlsx/csv file>
```

文件服务返回 `file_id` 后，再提交给工作台 AI 分析接口。

### 4.3 智能表格-文件上传成功.png

<img src="ai/智能表格-文件上传成功.png" alt="智能表格-文件上传成功 xlsx" width="360">

### 4.4 智能表格-文件上传成功(1).png

<img src="ai/智能表格-文件上传成功(1).png" alt="智能表格-文件上传成功 xls" width="360">

### 4.5 智能表格-文件上传成功(2).png

<img src="ai/智能表格-文件上传成功(2).png" alt="智能表格-文件上传成功 csv" width="360">

功能说明：

文件上传成功后，页面展示报表主题，例如“8月销售数据分析”；展示已选择报表卡片，包括文件类型图标、文件名、文件大小、上传成功状态和删除按钮。底部按钮变为“开始分析”。

业务规则：

1. 上传成功后展示真实文件名和大小。
2. 删除按钮用于移除当前文件，回到未选择文件状态。
3. 点击“开始分析”创建 AI 表格解读任务。
4. 同一个 `Idempotency-Key` 重复提交应返回同一个任务，避免重复扣费和重复生成。

创建分析任务接口：

```http
POST /v1/workbench/ai/table-analyses
Idempotency-Key: <uuid>
```

请求示例：

```json
{
  "title": "8月销售数据分析",
  "file_id": "DDd-DJUhRUA",
  "file_name": "8月销售数据分析.xlsx",
  "file_type": "xlsx"
}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_table_1",
    "status": "processing",
    "progress": 0,
    "current_step": "read_table"
  }
}
```

### 4.6 会议总结-识别中.png

<img src="ai/会议总结-识别中.png" alt="智能解读报告处理中" width="360">

功能说明：

表格分析过程中展示“智能解读报告”进度页。页面包含“正在智能解读”标题、说明“分析报表数据，请稍候...”、进度条、百分比、文件信息卡片和步骤时间轴。

步骤包括：

1. 读取表格数据：已完成
2. 识别核心指标：已完成
3. 分析趋势变化：进行中
4. 生成解读报告：等待中

底部提供“取消分析”按钮。

业务规则：

1. 前端可轮询任务状态，也可后续升级为 WebSocket/SSE 推送。
2. 进度值由服务端返回，不允许前端假进度超过服务端状态。
3. 用户点击“取消分析”后，服务端将任务标记为 `canceled`；如果第三方 AI 调用不可中断，也应停止后续结果写入。
4. 任务处理中退出页面，再进入记录页应能看到“生成中”状态。
5. 任务超时后进入 `failed`，错误原因展示为“分析超时，请稍后重试”。

查询任务接口：

```http
GET /v1/workbench/ai/tasks/{task_id}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_table_1",
    "task_type": "smart_table",
    "status": "processing",
    "progress": 68,
    "current_step": "analyze_trends",
    "steps": [
      {"key": "read_table", "name": "读取表格数据", "status": "succeeded"},
      {"key": "extract_metrics", "name": "识别核心指标", "status": "succeeded"},
      {"key": "analyze_trends", "name": "分析趋势变化", "status": "processing"},
      {"key": "generate_report", "name": "生成解读报告", "status": "pending"}
    ],
    "source_file": {
      "file_id": "DDd-DJUhRUA",
      "file_name": "8月销售数据.xlsx",
      "file_size": 3355443,
      "file_type": "xlsx"
    }
  }
}
```

取消接口：

```http
POST /v1/workbench/ai/tasks/{task_id}/cancel
Idempotency-Key: <uuid>
```

### 4.7 报告解读.png

<img src="ai/报告解读.png" alt="报告解读" width="360">

功能说明：

表格分析完成后进入“报告解读”页面。页面展示：

1. 报告标题：例如“8月销售数据”。
2. 元信息：今天 10:30、Excel 报表。
3. 核心指标卡片：销售额、订单量、退款率，包含指标值和涨跌幅。
4. 数据预览表：月份、销售额、订单量、退款率等核心列。
5. 异常提醒：例如“退款率连续两周上升，华南区域增幅明显”。
6. 核心解读：自然语言总结业务结论和建议。
7. 底部按钮：导出解读报告。

业务规则：

1. 指标卡最多展示 3 个核心指标，超过时由 AI 选取最重要指标。
2. 数据预览最多展示 10 行、6 列，完整文件仍通过原文件查看或导出查看。
3. 异常提醒为空时隐藏该模块或展示“暂无明显异常”。
4. 核心解读必须以用户能理解的业务语言输出，避免只重复表格数字。
5. 导出报告应生成 Word 或 PDF，首版建议 Word。
6. 导出文件应记录到文件系统，支持下载和在解读记录中查看。

结果结构示例：

```json
{
  "title": "8月销售数据",
  "source_type": "excel",
  "metrics": [
    {"name": "销售额", "value": "286万", "change": "+18%", "trend": "up"},
    {"name": "订单量", "value": "12,680", "change": "+12%", "trend": "up"},
    {"name": "退款率", "value": "3.6%", "change": "+0.8%", "trend": "up"}
  ],
  "preview": {
    "columns": ["月份", "销售额", "订单量", "退款率"],
    "rows": [
      ["3月", "98万", "8,620", "+5.8%"],
      ["4月", "198万", "9,450", "+8.6%"]
    ]
  },
  "warnings": [
    "退款率连续两周上升，华南区域增幅明显"
  ],
  "summary": "本月销售额比上月增长 18%，华东区域表现最好；订单量稳步提升，但退款率略有上升，建议重点关注华南区域的售后问题。"
}
```

导出接口：

```http
POST /v1/workbench/ai/table-analyses/{record_id}/export
Idempotency-Key: <uuid>
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "export_task_id": "aitask_export_1",
    "status": "processing"
  }
}
```

导出完成后返回：

```json
{
  "code": 0,
  "data": {
    "file_id": "file_abc",
    "file_name": "8月销售数据解读报告.docx",
    "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "file_size": 123456
  }
}
```

### 4.8 总结记录.png

<img src="ai/总结记录.png" alt="表格解读记录" width="360">

功能说明：

表格解读记录页标题为“总结记录”，顶部提供搜索框。列表按日期分组展示已分析文件，包括文件类型图标、标题、原始文件类型、时间、状态“已完成”和右侧箭头。

业务规则：

1. 支持按标题、文件名搜索。
2. 点击记录进入报告解读详情。
3. 记录状态包括 `已完成`、`解读中`、`失败`、`已取消`。
4. 文件被删除或过期时，报告记录仍可查看文本结果；原文件下载入口置灰。

建议接口：

```http
GET /v1/workbench/ai/records?type=smart_table&query=&cursor=&limit=20
```

## 5. AI 美文

AI 美文用于优化用户输入文案，使内容更通顺、正式、完整，可嵌入日报、月报等表单，也可作为独立文本润色能力复用。

### 5.1 AI美文.png

<img src="ai/AI美文.png" alt="AI美文" width="360">

功能说明：

页面标题为“AI美文”。上方展示“原文”输入框，示例内容为“今天下班后和朋友去吃火锅，聊了很多最近的事，感觉很开心，希望以后能经常聚聚。”，右下角显示 `0/300`。下方展示“AI优化的文案”，输出优化后的文案。底部提供“重新生成”和“使用文案”按钮。

业务规则：

1. 原文最大 300 字。
2. 原文为空时不允许生成。
3. 点击“重新生成”基于同一原文重新调用 AI，并生成新版本。
4. 点击“使用文案”将 AI 优化文案回填到来源表单字段。
5. 若从日报/月报进入，返回时应保留原表单其他字段。
6. AI 输出不得自动覆盖原文，必须由用户确认。

建议接口：

```http
POST /v1/workbench/ai/text/polish
Idempotency-Key: <uuid>
```

请求示例：

```json
{
  "source": "daily_report",
  "field": "summary",
  "text": "今天下班后和朋友去吃火锅，聊了很多最近的事，感觉很开心，希望以后能经常聚聚。",
  "style": "formal"
}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_polish_1",
    "status": "succeeded",
    "result": {
      "text": "下班后的快乐，是和朋友围坐在热气腾腾的火锅旁。聊聊近况，分享日常的小事，疲惫也在欢声笑语里慢慢散去。愿这样的相聚多一些，让平凡的日子多一点温暖。"
    }
  }
}
```

## 6. 日报 AI 接入

### 6.1 日报.png

<img src="ai/日报.png" alt="日报" width="360">

功能说明：

日报表单中增加“AI美文”按钮。页面包含日报起止时间、今日工作总结输入框和提交按钮。用户可在“今日工作总结”输入后点击“AI美文”进行文案优化。

业务规则：

1. 日报原有提交逻辑保持不变。
2. AI 美文只处理“今日工作总结”字段，不影响起止时间。
3. 用户点击“使用文案”后，将优化文案回填到“今日工作总结”输入框。
4. 若用户未输入今日工作总结，点击 AI 美文提示“请输入今日工作总结”。
5. AI 优化后的日报仍需用户主动点击“提交”。
6. 日报已有冲突规则时，AI 优化不绕过冲突校验。

建议和日报接口关系：

```text
日报表单保存/提交仍使用原日报接口。
AI 美文只提供文本优化，不直接提交日报。
```

## 7. 月报 AI 接入

### 7.1 月报-发布中.png

<img src="ai/月报-发布中.png" alt="月报发布中" width="360">

功能说明：

月报发布页增加“AI美文”按钮。页面包含“本月工作总结”和“其他事项”两个输入框，均有 `0/1000` 字数限制，底部为提交按钮。

业务规则：

1. `本月工作总结` 为必填字段，`其他事项` 可选。
2. AI 美文默认优化当前聚焦或最近编辑的文本框；如无法判断，应弹出字段选择。
3. 单字段最大 1000 字，但 AI 美文原型最大 300 字；首版建议：
   - 日报/月报入口提交给 AI 时限制 300 字，超过时提示精简。
   - 或服务端支持 `max_chars=1000` 的办公文案优化模式。
4. 使用 AI 文案后回填对应字段，不自动提交月报。
5. 月报提交时仍执行原有必填、重复提交、月份唯一性等校验。

建议请求：

```json
{
  "source": "monthly_report",
  "field": "monthly_summary",
  "text": "本月完成了工作台 AI 原型梳理和接口方案设计...",
  "style": "formal"
}
```

## 8. 会议笔记 AI 总结

会议笔记 AI 总结基于会议基础信息、上传的会议笔记文件、人工笔记内容或语音识别文本生成会议总结。

### 8.1 会议笔记- AI总结.png

<img src="ai/会议笔记- AI总结.png" alt="会议笔记 AI总结" width="360">

功能说明：

会议详情页展示会议基础信息，包括会议主题、状态、发起人、时间、地点、会议记录员、参会人和会议时长。下方有页签“全部笔记（文件）”和“AI总结”。AI 总结内容包括：

1. 会议结论
2. 关键决策
3. 后续安排表格

底部展示“由AI自动生成，如有不准确可手动编辑”，并提供“编辑”入口。

业务规则：

1. 只有有会议笔记查看权限的用户可以查看 AI 总结。
2. 会议记录员、发起人或具备笔记维护权限的用户可以触发 AI 总结生成和编辑。
3. 普通参会人是否可查看 AI 总结由会议笔记权限决定。
4. AI 总结需要绑定会议 ID。
5. AI 总结来源应包括会议基础信息、会议笔记文件、人工补充内容和已有文件 OCR/文本解析结果。
6. AI 总结结果必须允许人工编辑，编辑后保留编辑人和编辑时间。
7. 如果会议没有任何笔记文件或文本来源，应提示“暂无可总结内容”。

建议接口：

```http
POST /v1/workbench/meetings/{meeting_id}/ai-summary
Idempotency-Key: <uuid>
```

请求示例：

```json
{
  "source_file_ids": ["file_note_1", "file_note_2"],
  "extra_text": "补充说明：预算方案需要下周前确认。"
}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_meeting_1",
    "status": "processing"
  }
}
```

查询会议 AI 总结：

```http
GET /v1/workbench/meetings/{meeting_id}/ai-summary
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "summary_id": "msum_1",
    "meeting_id": "mtg_1",
    "status": "succeeded",
    "sections": [
      {
        "title": "会议结论",
        "content": "本次会议围绕合作方案细节优化、时间节点调整及预算评估进行了讨论，并达成初步共识。"
      },
      {
        "title": "关键决策",
        "items": [
          "整体合作方向确认，细节需要优化",
          "第一阶段交付时间提前到 7月10日",
          "市场部重新评估预算成本"
        ]
      }
    ],
    "actions": [
      {"item": "整理合作方案细节", "owner": "李明", "due_date": "2026-06-25"},
      {"item": "输出新的时间计划表", "owner": "张婷", "due_date": "2026-06-25"}
    ],
    "ai_generated": true,
    "editable": true,
    "updated_at": "2026-09-25T10:00:00Z"
  }
}
```

编辑会议 AI 总结：

```http
PUT /v1/workbench/meetings/{meeting_id}/ai-summary
Idempotency-Key: <uuid>
```

业务规则：

1. 编辑后 `ai_generated` 仍可保留为 true，但需要增加 `edited_by`、`edited_at`。
2. 编辑内容需要版本控制，便于恢复和审计。
3. 编辑不重新消耗 AI 调用额度。

## 9. AI 记录中心

### 9.1 记录类型

AI 记录包括：

| 类型 | 来源 | 原型 |
| --- | --- | --- |
| `smart_document` | 智能文档生成 | 文档记录 |
| `smart_table` | 智能表格解读 | 总结记录 |
| `text_polish` | AI 美文 | 可选，不一定首版展示 |
| `meeting_summary` | 会议笔记 AI 总结 | 会议详情页 |

### 9.2 通用记录字段

```json
{
  "record_id": "airec_1",
  "type": "smart_table",
  "title": "8月销售数据分析",
  "status": "succeeded",
  "display_status": "已完成",
  "file_type": "xlsx",
  "created_at": "2026-09-25T10:00:00Z",
  "updated_at": "2026-09-25T10:01:00Z"
}
```

### 9.3 记录权限

1. 默认记录仅创建人可见。
2. 会议 AI 总结按会议笔记权限可见。
3. 后续如支持分享，需要显式分享给用户或群组，不默认企业内公开。
4. 记录删除只删除工作台 AI 记录，不应直接删除原始文件，除非文件只被该记录引用且过期策略允许清理。

## 10. 服务端架构要求

### 10.1 模块划分

建议在 `im_workbench` 中增加 AI 业务模块：

```text
internal/ai
internal/ai/provider
internal/ai/prompts
internal/ai/tasks
internal/httpapi/ai.go
internal/store/ai_mysql.go
```

职责：

| 模块 | 职责 |
| --- | --- |
| HTTP API | 参数校验、鉴权、幂等、响应包装 |
| AI service | 编排任务、调用 provider、组织结果 |
| Provider | 对接具体大模型服务，封装重试、超时、错误 |
| Store | 保存任务、记录、结果、用量、导出文件 |
| Worker | 异步执行 AI 任务 |

### 10.2 同步与异步

建议：

1. AI 美文可以同步返回，但仍建议保存轻量任务记录。
2. 智能文档可同步或短异步，首版建议异步，便于统一处理失败和重试。
3. 智能表格必须异步，因为涉及文件解析和 AI 分析。
4. 会议总结必须异步，因为涉及文件读取、OCR/文本抽取和总结生成。

### 10.3 队列

工作台服务当前已有 Kafka 配置，可用于 AI 任务异步执行；如果首版不引入 Kafka 消费，也可使用数据库任务表 + 后台 worker 轮询。

建议优先级：

1. 简化首版：数据库任务表 + 本服务 worker。
2. 后续增强：Kafka 投递 `workbench.ai.task.created`，worker 消费执行。

无论采用哪种方式，都需要：

1. 幂等任务创建。
2. 任务超时控制。
3. 失败重试次数限制。
4. 服务重启后可恢复 `pending/processing` 超时任务。

## 11. 数据库设计建议

### 11.1 AI 任务表

```sql
CREATE TABLE im_ai_tasks (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id BIGINT NOT NULL,
  task_id VARCHAR(64) NOT NULL,
  task_type VARCHAR(32) NOT NULL,
  user_id BIGINT NOT NULL,
  source_type VARCHAR(32) NOT NULL DEFAULT '',
  source_id VARCHAR(128) NOT NULL DEFAULT '',
  status VARCHAR(32) NOT NULL,
  progress INT NOT NULL DEFAULT 0,
  current_step VARCHAR(64) NOT NULL DEFAULT '',
  input_json JSON NULL,
  result_json JSON NULL,
  error_code VARCHAR(64) NOT NULL DEFAULT '',
  error_message VARCHAR(512) NOT NULL DEFAULT '',
  idempotency_key VARCHAR(128) NOT NULL DEFAULT '',
  started_at DATETIME NULL,
  finished_at DATETIME NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_im_ai_tasks_task(task_id),
  UNIQUE KEY uk_im_ai_tasks_idem(tenant_id,user_id,task_type,idempotency_key),
  KEY idx_im_ai_tasks_user(tenant_id,user_id,task_type,created_at),
  KEY idx_im_ai_tasks_status(status,updated_at)
);
```

### 11.2 AI 记录表

```sql
CREATE TABLE im_ai_records (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id BIGINT NOT NULL,
  record_id VARCHAR(64) NOT NULL,
  task_id VARCHAR(64) NOT NULL DEFAULT '',
  record_type VARCHAR(32) NOT NULL,
  user_id BIGINT NOT NULL,
  title VARCHAR(200) NOT NULL,
  content_json JSON NULL,
  source_file_id VARCHAR(128) NOT NULL DEFAULT '',
  export_file_id VARCHAR(128) NOT NULL DEFAULT '',
  status VARCHAR(32) NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  deleted_at DATETIME NULL,
  UNIQUE KEY uk_im_ai_records_record(record_id),
  KEY idx_im_ai_records_user(tenant_id,user_id,record_type,created_at),
  KEY idx_im_ai_records_task(task_id)
);
```

### 11.3 AI 用量日志表

```sql
CREATE TABLE im_ai_usage_logs (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  task_id VARCHAR(64) NOT NULL,
  provider VARCHAR(64) NOT NULL,
  model VARCHAR(128) NOT NULL,
  prompt_tokens INT NOT NULL DEFAULT 0,
  completion_tokens INT NOT NULL DEFAULT 0,
  total_tokens INT NOT NULL DEFAULT 0,
  latency_ms INT NOT NULL DEFAULT 0,
  status VARCHAR(32) NOT NULL,
  error_code VARCHAR(128) NOT NULL DEFAULT '',
  created_at DATETIME NOT NULL,
  KEY idx_im_ai_usage_tenant(tenant_id,created_at),
  KEY idx_im_ai_usage_user(tenant_id,user_id,created_at),
  KEY idx_im_ai_usage_task(task_id)
);
```

### 11.4 会议 AI 总结表

```sql
CREATE TABLE im_meeting_ai_summaries (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id BIGINT NOT NULL,
  summary_id VARCHAR(64) NOT NULL,
  meeting_id VARCHAR(64) NOT NULL,
  task_id VARCHAR(64) NOT NULL DEFAULT '',
  content_json JSON NULL,
  version INT NOT NULL DEFAULT 1,
  ai_generated TINYINT(1) NOT NULL DEFAULT 1,
  edited_by BIGINT NOT NULL DEFAULT 0,
  edited_at DATETIME NULL,
  created_by BIGINT NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_im_meeting_ai_summary(summary_id),
  UNIQUE KEY uk_im_meeting_ai_summary_meeting(tenant_id,meeting_id),
  KEY idx_im_meeting_ai_summary_task(task_id)
);
```

## 12. AI Provider 配置

建议通过 manager 系统配置或 workbench 运行配置控制 AI Provider。

配置项建议：

| 配置项 | 含义 |
| --- | --- |
| `ai.enabled` | 是否启用 AI |
| `ai.provider` | AI 服务商 |
| `ai.model.text` | 文本生成模型 |
| `ai.model.table` | 表格解读模型 |
| `ai.timeout_seconds` | 调用超时时间 |
| `ai.max_input_chars` | 文本最大输入长度 |
| `ai.table.max_file_size` | 表格最大文件大小 |
| `ai.table.max_rows` | 表格最大行数 |
| `ai.table.max_columns` | 表格最大列数 |
| `ai.daily_quota_per_user` | 单用户每日调用次数 |
| `ai.daily_quota_per_tenant` | 单租户每日调用次数 |

要求：

1. API Key 不允许下发到客户端。
2. API Key 不允许写入 Git。
3. Provider 调用失败需要脱敏记录错误。
4. 支持按租户关闭 AI 能力。

## 13. 错误码建议

| HTTP | code | reason | 场景 |
| --- | --- | --- | --- |
| 400 | 30000 | `MALFORMED_REQUEST` | JSON 格式错误、缺少必填字段 |
| 400 | 30001 | `VALIDATION_FAILED` | 字数、文件类型、文件大小、行列数校验失败 |
| 401 | 30041 | `UNAUTHORIZED` | 未登录或 token 失效 |
| 403 | 30043 | `FORBIDDEN` | 无权限查看会议或记录 |
| 404 | 30044 | `RESOURCE_NOT_FOUND` | 任务、记录、文件不存在 |
| 409 | 30040 | `CONFLICT` | 幂等冲突或重复提交 |
| 429 | 30045 | `RATE_LIMITED` | AI 调用频控或额度耗尽 |
| 502 | 30100 | `AI_PROVIDER_FAILED` | AI 服务商调用失败 |
| 504 | 30101 | `AI_TIMEOUT` | AI 任务超时 |
| 422 | 30102 | `AI_CONTENT_REJECTED` | 输入或输出内容被安全策略拒绝 |
| 500 | 30103 | `AI_TASK_FAILED` | 任务执行失败 |

错误响应示例：

```json
{
  "code": 30001,
  "reason": "VALIDATION_FAILED",
  "message": "validation failed",
  "details": {
    "field": "source_text",
    "max_length": 1000
  }
}
```

## 14. 前端交互要求

### 14.1 生成按钮状态

1. 输入为空时，生成按钮置灰或点击后提示必填。
2. 生成中按钮进入 loading，不允许重复点击。
3. 生成失败后恢复按钮，并展示失败原因。
4. 使用文案/保存文档/导出报告成功后给出 Toast。

### 14.2 草稿保护

智能文档、日报、月报编辑中离开页面时，应保护用户输入：

1. 返回前提示是否放弃编辑。
2. 页面短暂切后台不应丢失输入。
3. AI 生成失败不应清空原文。

### 14.3 记录刷新

1. 任务创建后立即进入处理页或结果页。
2. 处理页轮询间隔建议 1～2 秒。
3. 任务完成后停止轮询。
4. 记录列表进入时刷新最新状态。

### 14.4 文件上传

1. 上传前校验文件类型。
2. 上传中展示进度。
3. 上传失败允许重试。
4. 上传成功展示文件名、大小、类型和删除按钮。

## 15. 服务端验收标准

### 15.1 工作台入口

1. 首页能按配置展示智能文档和智能表格。
2. 未启用 AI 时，AI 入口隐藏或置灰。
3. 搜索应用可命中智能文档、智能表格、日报、会议笔记等应用。
4. 无结果时返回空数组，前端展示“暂无匹配结果”。

### 15.2 智能文档

1. 输入 1～1000 字可创建生成任务。
2. 超过 1000 字返回 `VALIDATION_FAILED`。
3. 生成成功后返回标题和结构化正文。
4. 重新生成会创建新版本或新任务。
5. 保存文档后可在文档记录中查询。

### 15.3 智能表格

1. 支持上传 `xls`、`xlsx`、`csv`。
2. 非法类型、超大文件、空文件返回明确错误。
3. 创建分析任务后可查询进度。
4. 分析完成后返回核心指标、数据预览、异常提醒和核心解读。
5. 点击导出后生成可下载文件。
6. 解读记录列表能查到已完成记录。

### 15.4 AI 美文

1. 原文为空不能生成。
2. 文本超长返回明确错误。
3. 生成结果不自动覆盖原文。
4. 使用文案后能回填来源页面。
5. 重新生成返回不同版本或刷新结果。

### 15.5 会议笔记 AI 总结

1. 有权限用户可生成会议 AI 总结。
2. 无权限用户返回 `FORBIDDEN`。
3. 无可总结内容时返回明确提示。
4. 生成结果包含会议结论、关键决策和后续安排。
5. 支持人工编辑，并保留编辑人和编辑时间。

## 16. 非功能要求

### 16.1 性能

1. AI 美文同步响应建议 10 秒内完成；超过 10 秒走异步或提示稍后查看。
2. 智能文档生成建议 30 秒内完成。
3. 智能表格解读建议 60 秒内完成，超时进入失败状态。
4. 记录列表接口 P95 响应时间不超过 500 ms，不包含 AI 生成耗时。

### 16.2 稳定性

1. AI provider 异常不得影响 IM 聊天主链路。
2. AI 任务失败不得造成文件丢失或日报/月报草稿丢失。
3. 服务重启后，未完成任务可恢复或标记失败。
4. 对 provider 做熔断和限流，避免拖垮 workbench 服务。

### 16.3 安全

1. AI 输入、输出和上传文件均按租户隔离。
2. 不在日志中打印用户原文、AI 输出、文件内容、provider key。
3. 导出文件下载必须鉴权。
4. 上传文件必须做大小、MIME、扩展名和内容解析校验。
5. 会议总结必须校验会议权限。

### 16.4 审计

需要记录：

1. 谁发起 AI 任务。
2. 发起时间、完成时间、耗时。
3. 任务类型和来源。
4. provider、model、token 用量。
5. 成功或失败原因。
6. 导出文件和下载行为。

## 17. 首版范围与后续扩展

### 17.1 首版必须实现

1. 工作台展示智能文档和智能表格入口。
2. 工作台应用搜索。
3. 智能文档生成、保存、记录列表。
4. 智能表格上传、分析、进度、报告解读、记录列表。
5. AI 美文用于日报和月报。
6. 会议笔记 AI 总结生成和查看。
7. 统一 AI 任务表、记录表、用量日志。
8. 租户级 AI 开关和基础额度限制。

### 17.2 可后续扩展

1. AI 文档导出 Word/PDF。
2. AI 表格多 sheet 选择。
3. 解读报告分享给同事或群聊。
4. 会议语音转写后自动总结。
5. 按部门、角色配置 AI 使用额度。
6. 管理后台查看 AI 使用统计。
7. Prompt 模板后台配置。
8. AI 结果人工反馈，用于优化提示词。