# IM 工作台 AI 后端概要设计文档

> 版本：V1.0  
> 日期：2026-09-25  
> 关联文档：[IM 工作台 AI 接入需求文档](./IM工作台AI接入需求文档.md) · [IM 工作台 AI 前后端对接文档](./IM工作台AI前后端对接文档.md) · [IM 前后端对接文档](./IM-前后端对接文档.md)  
> DeepSeek 依据：[DeepSeek 首次调用 API](https://api-docs.deepseek.com/zh-cn/) · [DeepSeek Chat Completions API](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion/)  
> 说明：本文描述 IM 工作台 AI 能力的后端概要设计，覆盖智能文档、智能表格、AI 美文、日报/月报 AI 接入、会议笔记 AI 总结、AI 任务、AI 记录、DeepSeek 接入、配置、异步处理、数据表、安全和发布回滚。

---

## 一、设计目标

IM 工作台在现有日报、月报、会议、文件和组织能力基础上新增 AI 能力。后端需要在不破坏原 workbench 业务接口的前提下，提供统一的 AI 能力接入层、任务调度层、记录存储层和 DeepSeek Provider 适配层。

后端需要完成以下核心能力：

1. **工作台 AI 入口**：按租户、用户、功能开关返回可用 AI 能力、用量限制和入口配置。
2. **智能文档**：根据用户输入生成结构化文档，支持重新生成、编辑保存、记录查询。
3. **智能表格**：接收已上传表格文件，解析数据、识别核心指标、生成报告解读，支持记录查询和导出。
4. **AI 美文**：为普通文案、日报、月报提供同步润色能力，只回填业务表单，不替代原业务提交。
5. **会议 AI 总结**：基于会议笔记附件和会议上下文生成结论、决策、后续安排，支持编辑保存。
6. **DeepSeek 接入**：通过 DeepSeek OpenAI 兼容 Chat Completions API 接入模型，统一处理 prompt、超时、重试、错误映射、审计、脱敏和用量统计。
7. **可靠性**：支持幂等、异步任务、失败重试、并发限制、租户隔离、内容安全和灰度开关。

### 设计原则

- AI 能力放在 `im_workbench` 服务内建设，登录、租户、用户、组织、文件、会议仍复用 IM 与 workbench 既有能力。
- 所有 AI 业务表统一使用 `wb_ai_` 前缀。
- 所有业务数据必须带 `tenant_id`、`tenant_code`、`user_id`；用户身份由 IM Token 解析，客户端不得传入并覆盖身份。
- 所有对外 ID 统一按字符串返回，包括 `task_id`、`record_id`、`meeting_id`、`file_id`、`user_id`。
- AI Provider 必须抽象为接口，首版实现 DeepSeek，后续可切换到其他模型供应商。
- DeepSeek API Key、base_url、model、超时、并发、用量限制全部配置化，不写死在代码里。
- AI 输入、输出、文件解析内容、prompt 和模型响应都可能包含敏感信息，日志只记录摘要、hash、长度、token 用量和错误码。
- 同步接口只用于短文本 AI 美文；文档、表格、会议总结统一按异步任务处理。
- AI 输出默认不作为最终事实，前端必须展示“由 AI 生成，请核对后使用”。

---

## 二、系统架构

### 2.1 服务边界

首版建议直接在 `im_workbench` 中新增 AI 模块，避免多服务联调成本。模块内部按 Provider、任务、记录、业务适配做清晰边界，后续可平滑拆成独立 AI Worker 服务。

```text
移动端 / Web
  |
  v
IM Gateway / Workbench API
  |
  +--------------------> IM Auth / Tenant
  |                       Token、租户、用户上下文
  |
  v
im_workbench
  ├─ Workbench API         AI HTTP 路由、参数校验、响应转换
  ├─ AI Application        智能文档、智能表格、AI 美文、会议总结用例
  ├─ AI Task Domain        任务状态机、幂等、进度、取消、重试
  ├─ AI Record Domain      文档记录、表格记录、会议总结记录
  ├─ AI Provider Adapter   DeepSeek 适配、Prompt 编排、错误映射
  ├─ File Adapter          IM 文件下载、表格解析、导出文件上传
  ├─ Meeting Adapter       会议、会议笔记、权限和附件
  ├─ Worker                Kafka/Redis/MySQL 任务消费
  └─ MySQL / Redis / Kafka
       |
       +---------------> DeepSeek API
       |                 Chat Completions
       +---------------> IM File Service
       |                 文件上传、下载、导出
       +---------------> IM User/Org
                         用户、租户、权限、组织信息
```

### 2.2 推荐代码分层

```text
workbench/ai/
├── api/                         HTTP Handler、DTO、参数校验
├── application/
│   ├── capability/              AI 能力开关和配额
│   ├── document/                智能文档用例
│   ├── table/                   智能表格用例
│   ├── polish/                  AI 美文用例
│   └── meeting/                 会议 AI 总结用例
├── domain/
│   ├── task/                    AI 任务状态机、幂等、取消、重试
│   ├── record/                  AI 记录模型
│   ├── quota/                   用量限制、并发限制
│   └── prompt/                  Prompt 模板、变量、输出 Schema
├── repository/                  MySQL/Redis 数据访问
├── integration/
│   ├── deepseek/                DeepSeek Provider 实现
│   ├── file/                    IM 文件服务与导出文件
│   ├── meeting/                 会议和会议笔记权限
│   ├── user/                    用户显示名、组织信息
│   └── safety/                  内容安全检查
├── worker/                      AI 异步任务消费
├── parser/                      Excel/CSV 解析和采样
├── exporter/                    DOCX/PDF 导出
└── migrations/                  wb_ai_ 表结构和增量脚本
```

目录名称可按实际项目框架调整，但 AI Provider、任务状态机、业务用例和基础设施适配层必须解耦，不能在 Handler 中直接拼 prompt 调 DeepSeek。

### 2.3 请求上下文

Gateway 或中间件鉴权成功后向 AI 模块传递可信上下文：

| 字段 | 来源 | 用途 |
| --- | --- | --- |
| `request_id` | `X-Request-ID` 或服务端生成 | 全链路追踪 |
| `tenant_id` | Token/租户解析结果 | 数据隔离和联合索引 |
| `tenant_code` | `X-Tenant-Code`/Token | 日志、配置、文件服务路由 |
| `user_id` | Token | 当前操作用户 |
| `device_id` | Token/请求头 | 多端诊断和风控 |
| `api_key` | `X-MeetingIM-APIKey` | 复用 IM 客户端鉴权 |
| `locale` | 请求头/用户配置 | Prompt 语言和返回文案 |

### 2.4 外部依赖

| 依赖 | 用途 | 失败策略 |
| --- | --- | --- |
| IM Auth/Tenant | Token、租户和用户上下文 | 鉴权失败直接拒绝 |
| IM User/Org | 用户名、组织、参与人展示 | 展示可降级为用户 ID，写权限不可绕过 |
| Workbench Meeting | 会议、会议笔记、附件权限 | 无权限直接拒绝 |
| IM File | 表格源文件下载、会议附件读取、导出文件上传 | 文件不可用则任务失败 |
| DeepSeek API | 文案生成、结构化总结和报告解读 | 超时/失败按策略重试，最终任务失败 |
| MySQL | 任务、记录、用量、幂等、审计 | 核心状态最终一致来源 |
| Redis | 短期配额、并发锁、任务进度缓存 | MySQL 兜底，Redis 失败不放宽限制 |
| Kafka | 异步任务分发 | 不可用时写入任务但保持 `queued`，恢复后补偿扫描 |

---

## 三、DeepSeek 接入方案

### 3.1 接入方式

DeepSeek 支持 OpenAI 兼容的 Chat Completions API。服务端封装 `AIProvider` 接口，首版实现 `DeepSeekProvider`。

推荐配置：

| 配置项 | 示例 | 说明 |
| --- | --- | --- |
| `AI_PROVIDER` | `deepseek` | 当前 AI Provider |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容接口 base URL |
| `DEEPSEEK_API_KEY` | `******` | DeepSeek API Key，只放密钥系统 |
| `DEEPSEEK_DEFAULT_MODEL` | `deepseek-flash` | 默认模型，适合 AI 美文、智能文档 |
| `DEEPSEEK_COMPLEX_MODEL` | `deepseek-v4-pro` | 复杂表格分析、会议总结可选 |
| `DEEPSEEK_TIMEOUT_MS` | `60000` | 单次请求超时 |
| `DEEPSEEK_MAX_RETRIES` | `2` | 供应商 429/5xx/网络错误重试次数 |
| `DEEPSEEK_TEMPERATURE` | `0.2` | 结构化输出建议较低温度 |
| `DEEPSEEK_MAX_OUTPUT_TOKENS` | `4096` | 输出上限 |

不建议使用旧模型名 `deepseek-chat`、`deepseek-reasoner` 作为新接入默认值。模型名必须配置化，方便 DeepSeek 后续升级时只改配置。

### 3.2 Provider 接口

```go
type AIProvider interface {
    Generate(ctx context.Context, req GenerateRequest) (GenerateResponse, error)
}

type GenerateRequest struct {
    Feature       string
    TaskID        string
    TenantID      string
    UserID        string
    Model         string
    SystemPrompt  string
    UserPrompt    string
    ResponseSchema string
    Temperature   float64
    MaxTokens     int
    Timeout       time.Duration
}

type GenerateResponse struct {
    ProviderRequestID string
    Model             string
    Content           string
    PromptTokens      int
    CompletionTokens  int
    TotalTokens       int
    FinishReason      string
    LatencyMs         int64
}
```

业务层只依赖 `AIProvider`，不得直接依赖 DeepSeek HTTP Client。这样后续切换 Provider 或增加备用模型时不影响业务用例。

### 3.3 DeepSeek 请求格式

请求 DeepSeek 时统一调用：

```http
POST /chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer ${DEEPSEEK_API_KEY}
Content-Type: application/json
```

示例请求：

```json
{
  "model": "deepseek-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是 IM 工作台的企业办公助手。请严格按 JSON 输出，不要输出额外解释。"
    },
    {
      "role": "user",
      "content": "请将以下日报原文润色为专业、简洁的工作总结..."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 800,
  "stream": false
}
```

首版后端不使用流式输出，统一 `stream=false`。原因是前端当前交互以按钮生成、任务轮询、结果页展示为主；非流式更容易做幂等、审计、失败重试和结构化解析。后续如要做逐字生成，可在 Provider 层扩展流式接口。

### 3.4 输出结构化处理

DeepSeek 输出必须经过服务端解析和校验，不能直接原样入库给前端。

处理流程：

1. Prompt 明确要求模型只输出 JSON。
2. Provider 返回文本后，先截取 JSON 主体，去除 Markdown code fence。
3. 按当前 feature 的 schema 反序列化。
4. 校验必填字段、数组长度、字符串长度和枚举值。
5. 校验失败时最多执行一次“修复 JSON”请求，仍失败则任务失败，reason=`AI_TASK_FAILED`。
6. 校验通过后，生成标准化业务结果并入库。

示例：智能文档输出 Schema。

```json
{
  "title": "string",
  "sections": [
    {"heading": "string", "content": "string"}
  ],
  "summary": "string"
}
```

示例：会议总结输出 Schema。

```json
{
  "conclusions": ["string"],
  "decisions": ["string"],
  "action_items": [
    {
      "owner_name": "string",
      "content": "string",
      "due_text": "string"
    }
  ]
}
```

### 3.5 Prompt 模板管理

Prompt 不应散落在业务代码中，建议以数据库配置或内置模板文件管理。首版可内置在代码，并预留版本字段。

| 模板 | 用途 | 推荐模型 | 输出 |
| --- | --- | --- | --- |
| `smart_document_v1` | 智能文档生成 | `deepseek-flash` | JSON + markdown |
| `smart_table_v1` | 表格报告解读 | `deepseek-v4-pro` 或 `deepseek-flash` | JSON |
| `text_polish_v1` | AI 美文 | `deepseek-flash` | JSON |
| `meeting_summary_v1` | 会议 AI 总结 | `deepseek-v4-pro` 或 `deepseek-flash` | JSON |

模板变量示例：

| 变量 | 说明 |
| --- | --- |
| `{{language}}` | 输出语言 |
| `{{source_text}}` | 用户输入原文 |
| `{{document_type}}` | 文档类型 |
| `{{table_schema}}` | 表头、字段类型、样例数据 |
| `{{table_stats}}` | 服务端预计算统计 |
| `{{meeting_title}}` | 会议标题 |
| `{{meeting_files_text}}` | 会议附件抽取文本 |
| `{{participants}}` | 参会人展示名 |

Prompt 版本必须写入 `wb_ai_task.prompt_version` 和 `wb_ai_record.prompt_version`，方便回溯同一条记录由哪个模板生成。

### 3.6 错误映射

| DeepSeek/网络错误 | 服务端 reason | 处理 |
| --- | --- | --- |
| 401/403 | `AI_PROVIDER_AUTH_FAILED` | 配置错误，告警，不重试 |
| 400 | `AI_PROVIDER_BAD_REQUEST` | Prompt 或参数错误，任务失败 |
| 429 | `AI_PROVIDER_RATE_LIMITED` | 按退避重试，仍失败返回 `RATE_LIMITED` |
| 5xx | `AI_PROVIDER_FAILED` | 重试，仍失败任务失败 |
| 网络超时 | `AI_TIMEOUT` | 重试，仍失败任务失败 |
| 输出为空 | `AI_TASK_FAILED` | 可重试一次 |
| JSON 解析失败 | `AI_TASK_FAILED` | 修复 JSON 一次，仍失败则失败 |

Provider 原始错误只允许写入内部审计表的脱敏字段，不直接返回给前端。

### 3.7 超时、重试和熔断

- AI 美文同步接口总耗时目标小于 8 秒，超过直接返回 `AI_TIMEOUT`。
- 智能文档单任务超时 60 秒。
- 智能表格和会议总结单任务超时 120 秒。
- 重试仅针对网络错误、429、5xx、输出为空；内容安全、参数错误、权限错误不重试。
- 重试采用指数退避，例如 1 秒、3 秒。
- 连续失败率超过阈值时开启 Provider 熔断，新的异步任务保持 `queued` 或快速失败，AI 美文返回“服务繁忙”。

### 3.8 安全与脱敏

发送 DeepSeek 前必须做最小必要原则：

1. 智能文档只发送用户输入，不附带用户 Token、手机号、设备信息。
2. 智能表格只发送表头、数据类型、聚合统计、异常点和必要样例，不发送完整大表。
3. 会议总结只发送会议标题、附件抽取文本、参会人展示名；不发送内部权限字段。
4. 日志只记录输入长度、输出长度、hash、模型、耗时、token 用量、错误 reason。
5. API Key 只从密钥系统或环境变量读取，不入库、不打印、不下发前端。

---

## 四、数据库设计

### 4.1 数据库公共约定

- 数据库建议使用 MySQL 8.0，字符集 `utf8mb4`。
- 所有 AI 表名使用 `wb_ai_` 前缀，主键可使用 `BIGINT UNSIGNED` 或字符串 ID，接口统一返回字符串。
- 所有租户业务表必须包含 `tenant_id`、`tenant_code`、`user_id`。
- `created_at`、`updated_at` 使用 `DATETIME(3)`；服务端写 UTC。
- JSON 字段保存低频扩展内容；状态、类型、时间、用户、任务 ID 必须拆列建索引。
- AI 原始输入和模型原始输出可按合规要求加密存储或只保存摘要，默认不保存完整供应商响应。

### 4.2 表清单

| 表名 | 领域 | 用途 |
| --- | --- | --- |
| `wb_ai_capability_config` | 配置 | 租户级 AI 能力开关、模型、限额 |
| `wb_ai_task` | 任务 | AI 异步任务主表 |
| `wb_ai_task_step` | 任务 | 表格等多步骤任务进度 |
| `wb_ai_record` | 记录 | 通用 AI 记录索引 |
| `wb_ai_document` | 智能文档 | 文档保存内容 |
| `wb_ai_table_analysis` | 智能表格 | 表格解读报告 |
| `wb_ai_meeting_summary` | 会议总结 | 会议 AI 总结内容 |
| `wb_ai_usage_log` | 用量 | AI 调用、token、耗时、结果 |
| `wb_ai_idempotency_record` | 通用 | 写接口幂等请求和结果摘要 |
| `wb_ai_prompt_template` | Prompt | Prompt 模板和版本，可后续管理后台维护 |

### 4.3 `wb_ai_capability_config` — AI 能力配置

保存租户维度或默认维度的 AI 能力开关、模型、配额和限制。

关键字段：

| 字段 | 说明 |
| --- | --- |
| `tenant_id` | 租户 ID，默认配置可使用 `0` |
| `feature` | `smart_document`、`smart_table`、`text_polish`、`meeting_summary` |
| `enabled` | 是否开启 |
| `model` | 默认模型，例如 `deepseek-flash` |
| `daily_limit` | 单用户每日次数 |
| `concurrency_limit` | 单用户并发任务数 |
| `max_input_chars` | 输入字符上限 |
| `max_file_size_mb` | 文件大小上限 |
| `config_json` | 扩展配置 |

关键索引：

- `uk_tenant_feature(tenant_id, feature)`。
- 查询时先查租户配置，查不到再用默认配置。

### 4.4 `wb_ai_task` — AI 任务主表

智能文档、智能表格、会议总结都创建任务。AI 美文首版可同步处理，不强制落任务，但仍写 `wb_ai_usage_log`。

关键字段：

| 字段 | 说明 |
| --- | --- |
| `task_id` | 对外任务 ID，例如 `aitask_xxx` |
| `tenant_id`、`tenant_code`、`user_id` | 数据隔离 |
| `feature` | AI 能力类型 |
| `status` | `queued`、`processing`、`succeeded`、`failed`、`canceled`、`expired` |
| `progress` | 0～100 |
| `source_type` | `text`、`file`、`meeting` |
| `source_ref_id` | 关联文件、会议或业务对象 ID |
| `input_hash` | 输入内容 hash，用于审计和幂等诊断 |
| `input_snapshot` | 脱敏后的输入快照，可按合规决定是否为空 |
| `prompt_version` | Prompt 模板版本 |
| `model` | 实际调用模型 |
| `result_ref_id` | 成功后的记录 ID |
| `error_reason`、`error_message` | 失败原因 |
| `retry_count` | 已重试次数 |
| `started_at`、`finished_at` | 执行时间 |

关键索引：

- `uk_task_id(task_id)`。
- `idx_user_feature_time(tenant_id, user_id, feature, created_at)`。
- `idx_status_time(status, created_at)`，用于 Worker 拉取和补偿。

### 4.5 `wb_ai_task_step` — AI 任务步骤

用于智能表格进度展示，也可复用到会议总结。

字段包括 `task_id`、`step`、`title`、`status`、`progress`、`started_at`、`finished_at`、`error_reason`。

智能表格固定步骤：

1. `read_file`：读取表格数据。
2. `detect_metrics`：识别核心指标。
3. `analyze_trends`：分析趋势变化。
4. `generate_report`：生成解读报告。

### 4.6 `wb_ai_record` — AI 记录索引

保存智能文档、智能表格等记录列表所需公共字段。

关键字段：

| 字段 | 说明 |
| --- | --- |
| `record_id` | 对外记录 ID，例如 `airec_doc_xxx` |
| `record_type` | `smart_document`、`smart_table`、`meeting_summary` |
| `title` | 标题 |
| `summary` | 摘要 |
| `status` | `succeeded`、`deleted` 等 |
| `detail_table` | 详情表名或类型 |
| `detail_id` | 详情表 ID |
| `task_id` | 来源任务 |
| `created_at`、`updated_at`、`deleted_at` | 时间 |

关键索引：

- `uk_record_id(record_id)`。
- `idx_user_type_time(tenant_id, user_id, record_type, created_at)`。
- `idx_title_search(tenant_id, user_id, title)`，实际搜索可接全文索引或外部搜索。

### 4.7 `wb_ai_document` — 智能文档详情

保存用户确认保存后的智能文档。

关键字段：

- `record_id`
- `document_type`
- `title`
- `content_markdown`
- `content_plain`
- `sections_json`
- `source_excerpt`
- `prompt_version`
- `model`

智能文档生成成功但未保存时，只保留在 `wb_ai_task.result_json` 或短期缓存中；过期后不可保存。

### 4.8 `wb_ai_table_analysis` — 表格解读详情

保存表格报告解读结果。

关键字段：

- `record_id`
- `file_id`、`file_name`、`file_type`、`file_size`
- `topic`
- `metrics_json`
- `preview_json`
- `alerts_json`
- `interpretation`
- `export_file_id`
- `prompt_version`
- `model`

文件解析结果不建议完整入库。大表只保存字段统计、样例行和 AI 输出，完整源文件仍在 IM 文件服务中。

### 4.9 `wb_ai_meeting_summary` — 会议 AI 总结

保存会议维度的 AI 总结，一个会议默认只有一份当前有效总结。

关键字段：

- `summary_id`
- `meeting_id`
- `task_id`
- `conclusions_json`
- `decisions_json`
- `action_items_json`
- `source_file_ids_json`
- `edited_by`
- `edited_at`
- `version`

关键索引：

- `uk_tenant_meeting(tenant_id, meeting_id)`。
- `idx_user_time(tenant_id, user_id, updated_at)`。

编辑保存时使用 `version` 做乐观锁，避免多端同时编辑覆盖。

### 4.10 `wb_ai_usage_log` — AI 用量日志

每次调用 DeepSeek，无论成功失败都写用量日志。

字段包括：

- `tenant_id`、`tenant_code`、`user_id`
- `feature`
- `task_id`
- `provider=deepseek`
- `model`
- `provider_request_id`
- `prompt_tokens`、`completion_tokens`、`total_tokens`
- `latency_ms`
- `status`
- `error_reason`
- `input_hash`
- `output_hash`
- `created_at`

用量统计优先从该表聚合，日配额可用 Redis 加速、MySQL 兜底。

### 4.11 `wb_ai_idempotency_record` — 幂等记录

写接口统一记录幂等键、请求 hash 和响应摘要。

关键约束：

- `uk_idempotency(tenant_id, user_id, idempotency_key)`。
- 同一 key 请求 hash 相同，直接返回第一次响应。
- 同一 key 请求 hash 不同，返回 `IDEMPOTENCY_CONFLICT`。

---

## 五、核心业务设计

### 5.1 AI 能力配置读取

`GET /v1/workbench/ai/capabilities` 流程：

1. 解析 IM Token，得到租户和用户。
2. 读取租户 AI 配置；租户没有配置时读取默认配置。
3. 查询用户当天各 feature 已使用次数。
4. 组装 `features[]`，返回开关、入口名、每日限制、剩余次数、输入限制、文件限制。

配置建议缓存 1 分钟。配置变化后可通过后台主动清缓存，首版可接受短延迟。

### 5.2 AI 美文同步流程

AI 美文用于短文本润色，流程：

```text
请求进入
  -> 鉴权和租户解析
  -> 参数校验 source_text <= 300
  -> 能力开关、日配额、频控校验
  -> 内容安全预检查
  -> 构造 text_polish_v1 prompt
  -> 调用 DeepSeek
  -> 解析 JSON 输出 polished_text
  -> 内容安全后检查
  -> 写 usage_log
  -> 返回 polished_text
```

失败处理：

- DeepSeek 超时：返回 `AI_TIMEOUT`。
- 输出解析失败：重试一次；仍失败返回 `AI_TASK_FAILED`。
- 内容安全失败：返回 `AI_CONTENT_REJECTED`。
- 用量超限：返回 `AI_QUOTA_EXCEEDED`。

AI 美文不自动提交日报/月报，原业务提交接口保持不变。

### 5.3 智能文档流程

创建任务：

1. 校验输入长度、能力开关、配额和幂等。
2. 写 `wb_ai_task(status=queued, feature=smart_document)`。
3. 投递 Kafka 消息或写入本地任务队列。
4. 返回 `task_id` 给前端轮询。

Worker 执行：

1. 将任务置为 `processing`。
2. 构造 `smart_document_v1` prompt。
3. 调用 DeepSeek。
4. 解析 `title`、`sections`、`content_markdown`、`summary`。
5. 结果写入 `wb_ai_task.result_json`，任务置为 `succeeded`。
6. 用户点击保存后，写 `wb_ai_record` 和 `wb_ai_document`。

注意：

- 生成成功不等于保存成功。
- 未保存结果可设置 2 小时过期。
- 重新生成创建新任务，不覆盖旧任务。

### 5.4 智能表格流程

智能表格必须先上传文件，再创建任务。

创建任务：

1. 校验 `file_id` 属于当前租户和用户。
2. 校验文件类型为 `xlsx/xls/csv`，大小不超过配置。
3. 写 `wb_ai_task`、`wb_ai_task_step`，预生成 `record_id`。
4. 投递任务，返回 `task_id`、`record_id`。

Worker 执行：

```text
read_file
  -> 从 IM 文件服务下载文件
  -> 解析 xlsx/xls/csv
  -> 抽取表头、字段类型、样例行、总行数
detect_metrics
  -> 服务端先做基础统计：合计、均值、最大最小、环比、空值、异常点
analyze_trends
  -> 将表结构、统计摘要、异常点输入 DeepSeek
generate_report
  -> 解析模型 JSON，生成指标、预览、异常提醒、核心解读
  -> 写 wb_ai_record、wb_ai_table_analysis
```

表格数据处理原则：

- 不把完整大表直接发给 DeepSeek。
- 优先由服务端计算确定性统计，再让 AI 解释。
- 样例行数量限制，例如最多 20 行。
- 敏感列可按列名规则脱敏，例如手机号、身份证、邮箱。

### 5.5 会议 AI 总结流程

会议 AI 总结必须复用会议笔记权限。

流程：

1. 校验当前用户可查看该会议笔记。
2. 获取会议标题、时间、组织者、参会人、附件列表。
3. 校验 `file_ids` 均属于该会议且当前用户可读。
4. 抽取附件文本；若附件为空，可基于会议描述和已有笔记文本生成，但必须有有效输入。
5. 创建 `meeting_summary` AI 任务。
6. Worker 调用 DeepSeek 生成结论、关键决策、后续安排。
7. 写入或更新 `wb_ai_meeting_summary`。

编辑保存：

- 校验会议笔记编辑权限。
- 使用 `version` 乐观锁。
- 保存用户编辑内容，记录 `edited_by`、`edited_at`。

### 5.6 导出报告流程

表格报告导出流程：

1. 校验记录属于当前用户。
2. 读取 `wb_ai_table_analysis`。
3. 使用服务端模板生成 DOCX 或 PDF。
4. 上传到 IM 文件服务，得到 `file_id`。
5. 返回下载 URL 和过期时间。

导出不再调用 DeepSeek，避免同一报告重复生成内容不一致。

### 5.7 应用搜索接入

工作台应用列表和搜索本质不是 AI Provider 调用，但需要接入 AI 能力配置。

处理方式：

- 应用注册表增加 AI 应用：`smart_document`、`smart_table`。
- 返回应用列表前读取 capabilities。
- 未开启的 AI 应用不返回，或返回 `enabled=false`，由产品决定。
- 搜索只搜索当前用户可见应用。

---

## 六、关键技术方案

### 6.1 事务边界

需要事务的场景：

- 创建 AI 任务和幂等记录。
- 表格任务成功后写记录索引和详情。
- 智能文档保存时写记录索引和详情。
- 会议总结更新和版本递增。
- 用量日志和日配额计数。

不应放入同一事务的场景：

- 调用 DeepSeek。
- 下载文件和解析大文件。
- 导出文件上传。
- 发送 WebSocket 或系统通知。

外部调用必须在事务外执行，事务只保护本地状态变更。

### 6.2 幂等与弱网

所有写接口都要求 `Idempotency-Key`：

1. 请求进入后计算规范化请求体 hash。
2. 查询 `wb_ai_idempotency_record`。
3. 不存在则插入 `processing` 记录并继续。
4. 已存在且 hash 相同，返回首次响应。
5. 已存在且 hash 不同，返回 `IDEMPOTENCY_CONFLICT`。
6. 业务成功后更新响应摘要。

异步任务的幂等响应应返回同一个 `task_id`，不能重复创建任务。

### 6.3 任务调度

首选 Kafka：

| Topic | 用途 |
| --- | --- |
| `workbench.ai.task.created` | AI 任务创建 |
| `workbench.ai.task.retry` | AI 任务重试 |
| `workbench.ai.task.completed` | AI 任务完成事件，可选 |

消息体：

```json
{
  "task_id": "aitask_tbl_2Fh9aQx73K",
  "tenant_id": "1",
  "tenant_code": "system",
  "user_id": "usrABAAnqj42BU",
  "feature": "smart_table",
  "created_at": "2026-09-25T08:30:15.123Z"
}
```

消费要求：

- Consumer 收到消息后先按 `task_id` 查询 DB，只有 `queued` 可执行。
- 任务置为 `processing` 使用条件更新，避免多 Consumer 重复执行。
- 执行失败按错误类型决定是否重试。
- 服务重启后通过补偿任务扫描 `queued` 和超时 `processing`。

如果首版 Kafka 未就绪，可用 MySQL 轮询表兜底，但接口设计保持不变。

### 6.4 并发与配额

配额维度：

- 租户总开关。
- 单用户每日次数。
- 单用户并发任务数。
- 单租户并发任务数。
- Provider 全局并发数。

实现建议：

- Redis 维护短期计数和并发锁。
- MySQL `wb_ai_usage_log` 做最终用量统计。
- Redis 不可用时，使用 MySQL 当天聚合兜底，宁可保守拒绝，不放宽限制。

### 6.5 表格解析

解析规则：

- `xlsx/xls`：读取第一个非空 sheet；如果前端指定 `sheet_name`，必须校验存在。
- `csv`：自动识别 UTF-8/GBK，分隔符支持逗号，必要时兼容制表符。
- 空行、合并单元格、公式结果需要规范化。
- 超过最大行数时只采样前 N 行，并计算全量统计时注意内存限制。

输出给 DeepSeek 的内容建议：

```json
{
  "topic": "8月销售数据",
  "columns": [
    {"name": "日期", "type": "date"},
    {"name": "销售额", "type": "number"},
    {"name": "订单量", "type": "number"}
  ],
  "row_count": 31,
  "sample_rows": [
    ["8/1", "42300", "126"]
  ],
  "stats": {
    "销售额": {"sum": 1286000, "max": 62000, "min": 32100},
    "订单量": {"sum": 3842}
  },
  "outliers": [
    {"row": 15, "column": "订单量", "description": "较前一日下降 18%"}
  ]
}
```

### 6.6 内容安全

内容安全分为前置检查和后置检查：

- 前置检查：用户输入、表格标题、会议附件抽取文本。
- 后置检查：DeepSeek 输出结果。

首版如没有独立内容安全服务，可先做基础敏感词、长度、HTML/script 清理和文件类型校验，同时预留 `safety` adapter。命中安全规则返回 `AI_CONTENT_REJECTED`。

### 6.7 缓存策略

| 缓存 | Key | TTL | 说明 |
| --- | --- | --- | --- |
| AI 能力配置 | `wb:ai:cap:{tenant_id}` | 60s | 能力开关和限制 |
| 用户日用量 | `wb:ai:quota:{tenant_id}:{user_id}:{date}` | 当天 | 快速判断剩余次数 |
| 任务进度 | `wb:ai:task:{task_id}` | 2h | 轮询加速 |
| Provider 熔断 | `wb:ai:provider:deepseek:circuit` | 30s | 熔断标记 |

缓存不可作为唯一事实来源。任务最终状态以 MySQL 为准。

### 6.8 错误处理

对前端统一返回 workbench 错误包：

```json
{
  "code": 30050,
  "reason": "AI_TIMEOUT",
  "message": "ai timeout",
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWB",
  "server_time": "2026-09-25T08:30:15.123Z"
}
```

错误分层：

- 参数和权限错误：接口同步返回。
- 异步任务执行错误：任务置为 `failed`，轮询接口返回 `error`。
- Provider 配置错误：接口返回失败并触发告警。
- Kafka 不可用：任务保持 `queued`，补偿扫描重投。

### 6.9 可观测性

日志字段：

- `request_id`
- `tenant_code`
- `user_id_hash`
- `feature`
- `task_id`
- `provider`
- `model`
- `status`
- `latency_ms`
- `prompt_tokens`
- `completion_tokens`
- `error_reason`

指标：

- AI 请求数、成功数、失败数。
- DeepSeek 调用耗时 P50/P90/P99。
- 任务排队时长、执行时长。
- 任务失败率、重试次数。
- 每租户 token 用量。
- Provider 429/5xx/超时次数。

告警：

- DeepSeek 连续 5 分钟失败率超过阈值。
- 任务积压超过阈值。
- Kafka 消费延迟超过阈值。
- API Key 鉴权失败。
- 单租户用量异常增长。

---

## 七、C 端与管理后台需求

### 7.1 C 端职责边界

C 端负责：

- 输入长度和文件类型的第一层校验。
- 调用任务创建接口并轮询。
- 展示 AI 结果、失败、重试、取消和空态。
- 在日报/月报中使用 AI 美文结果回填字段。
- 展示“由 AI 生成，请核对后使用”提示。

C 端不负责：

- 判断最终权限。
- 控制真实用量。
- 保存 DeepSeek Key。
- 拼接最终 prompt。
- 解析供应商原始响应。

### 7.2 管理后台能力

建议后续在 manager 或 workbench admin 增加 AI 配置：

| 能力 | 说明 |
| --- | --- |
| 租户 AI 总开关 | 控制某租户是否开放 AI |
| 功能开关 | 分别控制智能文档、智能表格、AI 美文、会议总结 |
| 模型配置 | 每个功能选择默认模型 |
| 每日限额 | 单用户每日次数、租户每日总次数 |
| 文件限制 | 表格文件大小、行数、类型 |
| Prompt 版本 | 查看当前模板版本，灰度新模板 |
| 用量统计 | 按租户、用户、功能统计 token 和次数 |
| 失败日志 | 查看脱敏后的失败原因和任务 ID |

### 7.3 运维配置

Kubernetes/Gitea Secrets 中需要配置：

```text
AI_PROVIDER=deepseek
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=<deepseek api key>
DEEPSEEK_DEFAULT_MODEL=deepseek-flash
DEEPSEEK_COMPLEX_MODEL=deepseek-v4-pro
DEEPSEEK_TIMEOUT_MS=60000
DEEPSEEK_MAX_RETRIES=2
DEEPSEEK_TEMPERATURE=0.2
```

注意：

- `DEEPSEEK_API_KEY` 只能放 Secret，不放 ConfigMap，不提交 Git。
- 发版前确认 Pod 环境变量或配置文件最终生效。
- 模型名必须和 DeepSeek 当前可用模型一致。
- 不同环境可使用不同 Key 和限额。

---

## 八、开发阶段与依赖

### 8.1 开发阶段

#### 阶段一：基础框架和 AI 美文

目标：

- 建表：能力配置、用量日志、幂等。
- 实现 DeepSeek Provider。
- 实现 AI 美文接口。
- 接入日报/月报回填流程。

验收：

- 能通过 DeepSeek 返回润色文案。
- 超时、Key 错误、用量超限有明确错误。
- 日报/月报原业务提交不受影响。

#### 阶段二：智能文档

目标：

- 实现 AI 任务表、任务轮询、智能文档生成、保存、记录列表。
- 接入 Kafka 或 MySQL 任务队列。

验收：

- 能生成文档、重新生成、保存、查询记录。
- 弱网重复提交不创建重复任务。

#### 阶段三：智能表格

目标：

- 文件归属校验、Excel/CSV 解析、统计摘要、DeepSeek 报告生成、记录详情。
- 实现导出 DOCX/PDF。

验收：

- xlsx/xls/csv 都能分析。
- 大文件不会把完整内容发给 DeepSeek。
- 任务进度和失败状态可见。

#### 阶段四：会议 AI 总结

目标：

- 接入会议笔记权限和附件。
- 生成会议结论、关键决策、后续安排。
- 支持编辑保存。

验收：

- 无权限不能生成或查看。
- 会议附件不可用时有明确失败原因。
- 编辑保存不会被任务结果覆盖。

### 8.2 开发依赖

| 依赖 | 负责人 | 说明 |
| --- | --- | --- |
| DeepSeek API Key | 运维/后端 | 测试、生产分别配置 |
| Kafka | 后端/运维 | AI 异步任务队列 |
| Redis | 后端/运维 | 配额、进度缓存、并发锁 |
| 文件服务 | IM 后端 | 表格源文件下载、导出文件上传 |
| 会议笔记接口 | workbench 后端 | 会议权限、附件列表 |
| 前端页面 | 前端 | AI 入口、轮询、结果、记录 |

---

## 九、发布与回滚

### 9.1 发布顺序

1. 发布数据库 migration。
2. 配置 DeepSeek Secret、AI Provider、模型和限额。
3. 发布后端代码，默认租户 AI 开关关闭。
4. 验证 Provider 健康检查和 AI 美文测试接口。
5. 灰度开启测试租户 AI 美文。
6. 依次开启智能文档、智能表格、会议总结。
7. 前端打开入口。

### 9.2 发布检查

- Pod 中 `DEEPSEEK_API_KEY` 已注入，但日志不打印明文。
- `DEEPSEEK_BASE_URL` 为 `https://api.deepseek.com`。
- 默认模型可调用。
- Kafka consumer 正常消费。
- Redis 可写入配额 key。
- MySQL 表和索引已创建。
- 文件服务可下载测试表格。
- 任务失败告警已配置。

### 9.3 回滚策略

| 问题 | 回滚方式 |
| --- | --- |
| DeepSeek 大面积失败 | 关闭租户 AI 开关或 Provider 熔断 |
| AI 美文影响日报/月报 | 隐藏 AI 美文入口，原提交接口不回滚 |
| 智能文档失败率高 | 关闭 `smart_document` 功能 |
| 智能表格解析异常 | 关闭 `smart_table` 功能，保留历史记录只读 |
| 会议总结权限问题 | 关闭 `meeting_summary` 功能，保留会议笔记原能力 |
| 新表结构问题 | 代码回滚到不访问新表版本；migration 回滚需单独评估 |

回滚时不删除已生成记录。前端入口关闭后，历史记录可按产品要求保留只读或隐藏。

---

## 附录 A：MySQL 8.0 建表草案

```sql
CREATE TABLE wb_ai_capability_config (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL DEFAULT 0,
  tenant_code VARCHAR(64) NOT NULL DEFAULT '',
  feature VARCHAR(64) NOT NULL,
  enabled TINYINT(1) NOT NULL DEFAULT 0,
  model VARCHAR(64) NOT NULL DEFAULT 'deepseek-flash',
  daily_limit INT NOT NULL DEFAULT 0,
  concurrency_limit INT NOT NULL DEFAULT 1,
  max_input_chars INT NOT NULL DEFAULT 0,
  max_file_size_mb INT NOT NULL DEFAULT 0,
  config_json JSON NULL,
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_tenant_feature (tenant_id, feature)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_task (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  task_id VARCHAR(64) NOT NULL,
  tenant_id BIGINT UNSIGNED NOT NULL,
  tenant_code VARCHAR(64) NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  feature VARCHAR(64) NOT NULL,
  status VARCHAR(32) NOT NULL,
  progress INT NOT NULL DEFAULT 0,
  source_type VARCHAR(32) NOT NULL DEFAULT '',
  source_ref_id VARCHAR(128) NOT NULL DEFAULT '',
  input_hash VARCHAR(128) NOT NULL DEFAULT '',
  input_snapshot JSON NULL,
  prompt_version VARCHAR(64) NOT NULL DEFAULT '',
  model VARCHAR(64) NOT NULL DEFAULT '',
  result_ref_id VARCHAR(64) NOT NULL DEFAULT '',
  result_json JSON NULL,
  error_reason VARCHAR(64) NOT NULL DEFAULT '',
  error_message VARCHAR(255) NOT NULL DEFAULT '',
  retry_count INT NOT NULL DEFAULT 0,
  started_at DATETIME(3) NULL,
  finished_at DATETIME(3) NULL,
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_task_id (task_id),
  KEY idx_user_feature_time (tenant_id, user_id, feature, created_at),
  KEY idx_status_time (status, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_task_step (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  task_id VARCHAR(64) NOT NULL,
  step VARCHAR(64) NOT NULL,
  title VARCHAR(128) NOT NULL,
  status VARCHAR(32) NOT NULL,
  progress INT NOT NULL DEFAULT 0,
  error_reason VARCHAR(64) NOT NULL DEFAULT '',
  started_at DATETIME(3) NULL,
  finished_at DATETIME(3) NULL,
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_task_step (task_id, step)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_record (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  record_id VARCHAR(64) NOT NULL,
  tenant_id BIGINT UNSIGNED NOT NULL,
  tenant_code VARCHAR(64) NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  record_type VARCHAR(64) NOT NULL,
  title VARCHAR(128) NOT NULL,
  summary VARCHAR(512) NOT NULL DEFAULT '',
  status VARCHAR(32) NOT NULL,
  detail_id VARCHAR(64) NOT NULL DEFAULT '',
  task_id VARCHAR(64) NOT NULL DEFAULT '',
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  deleted_at DATETIME(3) NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_record_id (record_id),
  KEY idx_user_type_time (tenant_id, user_id, record_type, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_document (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  record_id VARCHAR(64) NOT NULL,
  tenant_id BIGINT UNSIGNED NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  document_type VARCHAR(64) NOT NULL,
  title VARCHAR(128) NOT NULL,
  content_markdown MEDIUMTEXT NOT NULL,
  content_plain MEDIUMTEXT NULL,
  sections_json JSON NULL,
  source_excerpt VARCHAR(1024) NOT NULL DEFAULT '',
  prompt_version VARCHAR(64) NOT NULL DEFAULT '',
  model VARCHAR(64) NOT NULL DEFAULT '',
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_record_id (record_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_table_analysis (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  record_id VARCHAR(64) NOT NULL,
  tenant_id BIGINT UNSIGNED NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  file_id VARCHAR(128) NOT NULL,
  file_name VARCHAR(255) NOT NULL,
  file_type VARCHAR(16) NOT NULL,
  file_size BIGINT UNSIGNED NOT NULL DEFAULT 0,
  topic VARCHAR(128) NOT NULL,
  metrics_json JSON NULL,
  preview_json JSON NULL,
  alerts_json JSON NULL,
  interpretation MEDIUMTEXT NULL,
  export_file_id VARCHAR(128) NOT NULL DEFAULT '',
  prompt_version VARCHAR(64) NOT NULL DEFAULT '',
  model VARCHAR(64) NOT NULL DEFAULT '',
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_record_id (record_id),
  KEY idx_file_id (tenant_id, file_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_meeting_summary (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  summary_id VARCHAR(64) NOT NULL,
  tenant_id BIGINT UNSIGNED NOT NULL,
  tenant_code VARCHAR(64) NOT NULL,
  meeting_id VARCHAR(128) NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  task_id VARCHAR(64) NOT NULL DEFAULT '',
  conclusions_json JSON NULL,
  decisions_json JSON NULL,
  action_items_json JSON NULL,
  source_file_ids_json JSON NULL,
  prompt_version VARCHAR(64) NOT NULL DEFAULT '',
  model VARCHAR(64) NOT NULL DEFAULT '',
  edited_by VARCHAR(64) NOT NULL DEFAULT '',
  edited_at DATETIME(3) NULL,
  version INT NOT NULL DEFAULT 1,
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_summary_id (summary_id),
  UNIQUE KEY uk_tenant_meeting (tenant_id, meeting_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_usage_log (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  tenant_code VARCHAR(64) NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  feature VARCHAR(64) NOT NULL,
  task_id VARCHAR(64) NOT NULL DEFAULT '',
  provider VARCHAR(32) NOT NULL,
  model VARCHAR(64) NOT NULL,
  provider_request_id VARCHAR(128) NOT NULL DEFAULT '',
  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_reason VARCHAR(64) NOT NULL DEFAULT '',
  input_hash VARCHAR(128) NOT NULL DEFAULT '',
  output_hash VARCHAR(128) NOT NULL DEFAULT '',
  created_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  KEY idx_user_feature_day (tenant_id, user_id, feature, created_at),
  KEY idx_provider_time (provider, model, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE wb_ai_idempotency_record (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT UNSIGNED NOT NULL,
  user_id VARCHAR(64) NOT NULL,
  idempotency_key VARCHAR(128) NOT NULL,
  request_hash VARCHAR(128) NOT NULL,
  response_code INT NOT NULL DEFAULT 0,
  response_body JSON NULL,
  status VARCHAR(32) NOT NULL,
  created_at DATETIME(3) NOT NULL,
  updated_at DATETIME(3) NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY uk_idempotency (tenant_id, user_id, idempotency_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

## 附录 B：DeepSeek 调用伪代码

```go
func (p *DeepSeekProvider) Generate(ctx context.Context, req GenerateRequest) (GenerateResponse, error) {
    body := map[string]any{
        "model": req.Model,
        "messages": []map[string]string{
            {"role": "system", "content": req.SystemPrompt},
            {"role": "user", "content": req.UserPrompt},
        },
        "temperature": req.Temperature,
        "max_tokens": req.MaxTokens,
        "stream": false,
    }

    httpReq := NewJSONRequest(ctx, "POST", p.baseURL+"/chat/completions", body)
    httpReq.Header.Set("Authorization", "Bearer "+p.apiKey)

    resp, err := p.httpClient.Do(httpReq)
    if err != nil {
        return GenerateResponse{}, mapNetworkError(err)
    }
    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        return GenerateResponse{}, mapDeepSeekStatus(resp.StatusCode, resp.Body)
    }

    parsed := parseChatCompletion(resp.Body)
    return GenerateResponse{
        ProviderRequestID: parsed.ID,
        Model: parsed.Model,
        Content: parsed.Choices[0].Message.Content,
        PromptTokens: parsed.Usage.PromptTokens,
        CompletionTokens: parsed.Usage.CompletionTokens,
        TotalTokens: parsed.Usage.TotalTokens,
        FinishReason: parsed.Choices[0].FinishReason,
        LatencyMs: elapsed.Milliseconds(),
    }, nil
}
```

## 附录 C：已确认产品与技术决策

| 决策 | 说明 |
| --- | --- |
| AI Provider | 首版接入 DeepSeek |
| 接口形态 | DeepSeek 走 OpenAI 兼容 Chat Completions |
| 默认模型 | `deepseek-flash` |
| 复杂任务模型 | 可配置为 `deepseek-v4-pro` |
| 流式输出 | 首版不做流式，统一非流式和任务轮询 |
| 表格处理 | 服务端先解析和统计，不把完整大表直接发给模型 |
| 日报/月报 | AI 只润色文案，不改变原提交接口 |
| 会议总结 | 必须复用会议笔记权限 |
| 日志 | 不打印完整输入、输出、Token、API Key |