Jog/doc/AI助手联调与模型管理冲突分析.md

# AI 助手联调验收 vs 模型管理 — 冲突分析

| 文档版本 | 修订日期   | 说明 |
| :------- | :--------- | :--- |
| V1.0     | 2026-05-23 | 助手功能联调/验收进行中时，与《AI助手模型管理功能需求》V1.2 的差异与冲突梳理 |

**关联文档**：

- [AI助手功能需求.md](./AI助手功能需求.md)（V1.2，联调验收基准）
- [AI助手功能技术实施文档.md](./AI助手功能技术实施文档.md)（待办 23～25：联调 🔄、验收 ⬜）
- [AI助手模型管理功能需求.md](./AI助手模型管理功能需求.md)（V1.2）
- [AI助手模型管理功能技术实施文档.md](./AI助手模型管理功能技术实施文档.md)（V1.1，未实施）

**分析基准**：当前仓库已实现助手 V5 表 + 四接口 + `AiAssistant.vue`，模型管理 **尚未编码**。

---

## 1. 结论摘要

| 类别 | 数量 | 对联调验收的影响 |
| :--- | :--- | :--- |
| **P0 破坏性冲突**（不协同发布会导致助手页异常） | **1** | 必须先完成助手 AC 或做兼容层，再上线模型管理后端 |
| **P1 行为/语义冲突**（验收口径变化，需补充用例） | **4** | 不阻断当前联调，但模型管理上线后原 AC 覆盖不足 |
| **P2 环境与流程冲突**（库表、分支、验收顺序） | **3** | 联调环境执行 V6 后需重跑部分 AC |
| **P3 扩展性差异**（UI/接口增量，无逻辑矛盾） | **5** | 与当前联调并行开发需注意合并顺序 |
| **无冲突（可并存）** | **12+** | 多轮、限流、登录、重试、分页等规则一致 |

**合计需纳入排期的冲突/差异项：8 项（P0×1 + P1×4 + P2×3）**；P3 五项建议在模型管理 PR 中一并交付，但不计入「硬冲突」。

**推荐节奏**：

1. **先** 按《AI助手功能需求》完成待办 23～25（AC-AI-CHAT-*），基线环境 **仅 V5、不部署 V6**。  
2. **再** 实施模型管理；`GET .../messages` 与前端 **同一 PR** 发布，或后端短期兼容旧响应格式。  
3. 模型管理验收使用 **AC-AI-MODEL-***，并 **追加** 4 条 P1 回归（见 §5）。

---

## 2. 冲突项清单

### 2.1 P0 — 破坏性冲突（1 项）

| 编号 | 冲突点 | 助手现状（联调基准） | 模型管理要求 | 影响 |
| :--- | :----- | :------------------- | :----------- | :--- |
| **C-P0-01** | `GET /api/app/ai/sessions/{id}/messages` 响应结构 | `ApiResult.data` 为 **消息数组** `List<AiChatMessageVO>`（需求 FR-AI-CHAT-BE-07）；前端 `messages.value = res.data` | `data` 改为 **包装对象**：`{ messages, modelEnabled, readOnlyReason, roundCount, maxRounds }` | 仅升级后端时，前端把对象当数组渲染 → **消息区空白或报错** |

**缓解**（择一）：

- **A（推荐）**：模型管理前后端同版本发布；联调环境在助手 AC 通过后再合入。  
- **B**：后端过渡期双格式：`?legacy=true` 仍返回数组，默认新格式。  
- **C**：前端先判 `Array.isArray(data)`，兼容两种结构。

---

### 2.2 P1 — 行为 / 语义冲突（4 项）

| 编号 | 冲突点 | 助手现状 | 模型管理要求 | 对联调/验收的影响 |
| :--- | :----- | :------- | :----------- | :---------------- |
| **C-P1-01** | 调用 DashScope 的 `model` 来源 | FR-AI-CHAT-BE-09：`DashScopeProperties.model`（`DASHSCOPE_MODEL`） | FR-AI-MODEL-BE-03：会话绑定 `ai_assistant_model.model_code` | 联调时记录的 `response.model` 来自 yml；上线后来自 **库表**。同一环境改 `DASHSCOPE_MODEL` **不再** 改变已有助手会话行为 |
| **C-P1-02** | 只读条件 | FR-AI-CHAT-FE-05：仅 `roundCount >= 5` → 只读 | 另增 `modelEnabled === false`（D-09）；未满 5 轮也可只读 | AC-AI-CHAT-FE-04/05 **未覆盖**「模型禁用」；模型管理验收需 AC-AI-MODEL-FE-04/05 |
| **C-P1-03** | `POST /chat` 拒绝条件 | 满 5 轮、参数非法、限流、AI 异常 | 绑定模型 `enabled=0` 时 **400 模型已停用**（FR-AI-MODEL-BE-01） | 联调阶段不会出现；管理员禁用模型后，原「未满 5 轮可继续」会话 **不能再发** — 与 FR-AI-CHAT-FE-05 文案/预期 **不一致**（属需求演进，非实现 bug） |
| **C-P1-04** | 创建会话与模型绑定 | `POST /sessions` **无 body**；`ai_chat_session` **无** `model_id` | 可选 `{ modelId }`；表字段 `model_id` 必填（迁移回填） | 联调创建的会话在 V6 后 `model_id` 指向种子默认模型；**不会** 自动等同于当时 yml 中的 model（若种子与 yml 不一致） |

---

### 2.3 P2 — 环境 / 流程冲突（3 项）

| 编号 | 冲突点 | 说明 | 建议 |
| :--- | :----- | :--- | :--- |
| **C-P2-01** | Flyway V6 与联调库 | 联调库若已跑 V5 并产生会话，执行 V6 会 `ALTER` + 种子 + `UPDATE model_id` | 助手 AC 在 **V5-only** 环境签字；V6 后重跑：刷新恢复、历史点选、发送（C-P0-01 相关） |
| **C-P2-02** | 验收清单并行 | 《AI助手功能技术实施文档》待办 25：`AC-AI-CHAT-*`；《模型管理》`AC-AI-MODEL-*` | 分两轮签字，避免混在同一表格未标注版本 |
| **C-P2-03** | 默认模型双配置 | 助手联调看 `application.yml` / `DASHSCOPE_MODEL`；模型管理运行看库内 `is_default` | 部署检查清单增加：**种子 `model_code` 与 yml 一致**（见模型管理需求 §3.4） |

---

### 2.4 P3 — 扩展差异（非硬冲突，5 项）

| 编号 | 差异点 | 助手现状 | 模型管理增量 | 说明 |
| :--- | :----- | :------- | :----------- | :--- |
| **C-P3-01** | 新接口 | 4 个 app 接口 | `GET /api/app/ai/models` | 纯增量，不影响联调 |
| **C-P3-02** | 会话列表字段 | `id, title, roundCount, lastMessageAt` | + `modelDisplayName`, `modelEnabled` | 向后兼容，旧前端可忽略 |
| **C-P3-03** | 创建会话 body | 空 POST | 可选 `modelId` | 旧客户端不传即可 |
| **C-P3-04** | 页面布局 | 标题栏仅「会话标题 + 轮次」 | 增加模型 `el-select`（FR-AI-MODEL-FE） | 布局扩展，不推翻 FR-AI-CHAT-FE 分栏 |
| **C-P3-05** | localStorage | FR-AI-CHAT-FE-14：不存对话正文 | 仅存 `jog_ai_assistant_model_id` | 不冲突 |

---

### 2.5 无冲突项（联调可继续，12 项代表）

以下规则在两份需求中 **一致或模型管理显式不改**：

| 领域 | 助手需求编号 | 说明 |
| :--- | :----------- | :--- |
| 多轮上限 5 轮 | FR-AI-CHAT-BE-02、FE-05/06 | 模型管理未改 `MAX_ROUNDS` |
| 失败重试不重复 user | FR-AI-CHAT-BE-15 | 不变 |
| 限流 10 次/分钟 | FR-AI-CHAT-BE-12 | FR-AI-MODEL-BE-08 明确不按模型分限流 |
| 登录与鉴权 | FR-AI-CHAT-FE-10、BE-01 | 不变 |
| 会话列表分页 50 | FR-AI-CHAT-FE-16、D-07 | 不变 |
| 历史全文回看 | FR-AI-CHAT-FE-04、D-01 | 不变（仅多只读原因） |
| 新会话不删旧数据 | FR-AI-CHAT-FE-02、D-03 | 不变 |
| 进入页默认最近会话 | D-06 | 不变 |
| System Prompt / max-input 截断 | FR-AI-CHAT-BE-03/04/10 | 不变 |
| 会话软删除预留 | FR-AI-CHAT-BE-14 | 模型管理不强制前端删会话 |
| 润色/标签/摘要模型来源 | D-10、§1.6 | 与助手联调无关 |
| `POST /chat` 请求体核心字段 | `sessionId` + `message` | 仍必填；`modelId` 可选且可忽略 |

---

## 3. 接口契约对照表

| 接口 | 联调中契约 | 模型管理后契约 | 冲突级别 |
| :--- | :--------- | :------------- | :------- |
| `POST /sessions` | 无 body → `{ sessionId }` | 可选 body `{ modelId }` → 同上 | 兼容 |
| `GET /sessions` | 分页 + 4 字段 | +2 字段 | 兼容 |
| `GET /sessions/{id}/messages` | `data`: **数组** | `data`: **对象** | **C-P0-01** |
| `POST /chat` | `{ sessionId, message }` | +可选 `modelId`（忽略） | 兼容 |
| `GET /models` | 不存在 | 新增 | 无 |

---

## 4. 前端实现差异（当前代码）

| 文件 | 联调实现 | 模型管理需改 |
| :--- | :------- | :----------- |
| `api/aiChat.js` | `createAiChatSession()` 无参；messages 按数组解析 | 传 `modelId`；解析 `payload.messages` |
| `AiAssistant.vue` | `readOnly = roundCount >= 5`；`res.data` 作消息列表 | 合并 `modelEnabled`；处理 `readOnlyReason` |
| `AiChatPanel.vue` | 仅满 5 轮 `readonly-banner` | 增加模型停用提示条 |
| （无） | 无模型选择器 | 标题栏 `el-select` + `listAppAiModels` |

---

## 5. 验收用例冲突与合并建议

### 5.1 当前联调应完成的范围（不受模型管理阻塞）

以下用例 **仅依赖 V5 + 现有代码**，与模型管理无硬冲突：

- AC-AI-CHAT-NAV-*、AC-AI-CHAT-FE-01～03、06～07  
- AC-AI-CHAT-FE-04、05（**仅满 5 轮只读**）  
- AC-AI-CHAT-BE-01～05  

对应技术文档待办：**23、24、25（助手部分）**。

### 5.2 模型管理上线后必须追加的回归（原 AC 未覆盖）

| 追加编号 | 场景 | 对应冲突 |
| :------- | :--- | :------- |
| REG-MODEL-01 | V6 迁移后，旧会话可加载消息且可对话（默认模型启用） | C-P1-04、C-P2-01 |
| REG-MODEL-02 | 禁用绑定模型后，未满 5 轮会话只读且 chat 400 | C-P1-02、C-P1-03 |
| REG-MODEL-03 | 切换模型 + 新会话，DashScope 使用新 `model_code` | C-P1-01 |
| REG-MODEL-04 | 前端 messages 包装结构渲染正常 | C-P0-01 |

### 5.3 不必在助手联调阶段执行的用例

- AC-AI-MODEL-ADM-*、AC-AI-MODEL-FE-01～05、AC-AI-MODEL-BE-*（属模型管理专项验收）

---

## 6. 测试与自动化影响

| 资产 | 联调基准 | 模型管理后 |
| :--- | :------- | :--------- |
| `AiChatServiceImplTest` | Mock `properties.getModel()` | 需 Mock `AiAssistantModelMapper` / Service |
| `AiChatServiceIntegrationTest` | 内存实现，无 model_id | 补 model 绑定与禁用用例 |
| `AiChatServiceLiveIT` | 打印 `model` 来自配置 | 可能为库表 `model_code` |
| 前端 E2E（若有） | 无模型下拉 | 需新场景 |

**冲突项计数**：自动化需 **显著改动** 的约 **2 处**（Service 单测 + 集成测），计入 P1 维护成本，不单列新编号。

---

## 7. 分支与发布策略建议

```
main ──┬── [阶段1] 助手联调验收（V5 only，签 AC-AI-CHAT-*）
       │
       └── [阶段2] feature/ai-model-mgmt（V6 + 模型 CRUD + 助手改造）
                 └── 同一 PR 合并：后端 messages 包装 + 前端兼容/新 UI
                 └── 签 AC-AI-MODEL-* + REG-MODEL-01～04
```

- **避免**：阶段 1 未完成时合入仅含 V6 + 后端 messages 改动的 PR。  
- **允许**：阶段 1 期间在独立分支开发模型管理，但不部署到联调验收环境。

---

## 8. 冲突项统计（速查）

| 级别 | 编号 | 计数 |
| :--- | :--- | :--- |
| P0 | C-P0-01 | 1 |
| P1 | C-P1-01 ～ C-P1-04 | 4 |
| P2 | C-P2-01 ～ C-P2-03 | 3 |
| P3 | C-P3-01 ～ C-P3-05 | 5（扩展，非阻断） |
| **需协调的硬冲突合计** | P0 + P1 + P2 | **8** |

---

## 9. 文档修订建议（可选）

| 文档 | 建议 |
| :--- | :--- |
| 《AI助手功能需求》 | 在 §3.3.3 增加脚注：「消息列表响应以模型管理上线版为准，见《AI助手联调与模型管理冲突分析》C-P0-01」 |
| 《AI助手模型管理功能需求》 | §3.3.3 标明对 FR-AI-CHAT-BE-07 的 **替代关系** |
| 《AI助手功能技术实施文档》 | 待办 25 备注：验收环境 Flyway ≤ V5 |

---

**编写人：** AI 助手  
**评审人：** 待评审  
**生效日期：** 2026-05-23