nojava/Jog

Files

T

2026-05-24 00:39:10 +08:00

11 KiB

Raw Blame History

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

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

关联文档：

AI助手功能需求.md（V1.2，联调验收基准）
AI助手功能技术实施文档.md（待办 23～25：联调 🔄、验收 ⬜）
AI助手模型管理功能需求.md（V1.2）
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 中一并交付，但不计入「硬冲突」。

推荐节奏：

先按《AI助手功能需求》完成待办 23～25（AC-AI-CHAT-*），基线环境 仅 V5、不部署 V6。
再实施模型管理；GET .../messages 与前端 同一 PR 发布，或后端短期兼容旧响应格式。
模型管理验收使用 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

11 KiB Raw Blame History Unescape Escape