# 架构设计：AI 开发 SOP × IT 工作台现有功能（v1 待确认）

设计原则：最大复用现有 zt_* 功能；AI 侧数据一律「框架算、平台存」（用户确认的边界）；新增一律沿用 `zt_story_extend` 扩展表先例，不改禅道老表结构（zt_task 等）。

## 一、SOP 流程逐环节映射（证据：SRC-001；代码证据见行号）

| # | SOP 环节 | 提交物 | 现有功能（证据） | 差距 | 方案 | 分期 |
|---|---|---|---|---|---|---|
| 1 | 需求提出→评审激活 | 用户需求 | 全流程已有：`/zt-story-user` userReview 评审通过→active+revieweddate（ZtStoryUserServiceImpl.java:562-578）；前端 userstoryinfo 评审按钮 | `approveddate/activateddate` 死字段（全库无写入） | 小改：userReview 通过时补写 activateddate | 二期 |
| 2 | 初次讨论 | 会议纪要+PRD 附件 | `/zt-meeting` 有 result 富文本纪要、storyIds 关联需求、PDF 导出；后端附件绑定已就绪（FileTypes.meeting，ZtMeetingServiceImpl.java:159） | **前端附件 UI 已引入未渲染**（addDialog/editDialog 无 `<uploads>`） | 前端渲染 uploads 组件 + 详情页附件区块 | 二期 |
| 3-5 | AI 生成 PRD→评审→最终版 | PRD 文档/原型图 | 通用上传 `/common/upload`+zt_file；需求/用户需求附件区块已有（FileTypes.story/userStory） | 无 PRD 版本记录 | 不建版本表：PRD 每版生成时间记入 zt_ai_work_log（log_type=prd_version）——KISS | 一期建表/二期打通 |
| 6 | AI 评估工作量→生成研发需求 | 工作量指标 | **通道已通**：`/zt-story-expand/saveOrUpdate`（demand-assessor 已对接生产）；指标在统计页 /worktime/count 展示 | ①缺 AI 参与率字段 ②storyinfo 详情页无指标区块（孤岛） | ①zt_story_extend 加列 ai_participation_rate ②详情页加 AI 指标区块 | ①一期 ②二期 |
| 7-8 | 架构设计/验收指标/测试用例 | 验收指标、用例文档 | 验收标准=zt_storyspec.verify 富文本；用例=zt_case+story-case 评审链；附件通道通用 | 验收指标无结构化（富文本可承载，暂不结构化） | 本期复用 verify+附件；结构化验收指标表→后续按需 | 复用 |
| 9 | AI 拆分任务/评估工时/分配 | 研发任务 | 任务全流程已有（拆分/指派/zt_effort 工时） | 任务级 AI 工作量指数缺失；zt_task 是禅道老表不宜加列 | **新建 zt_task_extend 扩展表**（沿用 zt_story_extend 先例） | 一期建表 |
| 10-11 | 开发→AI 代码审查（可回炉） | 代码审查报告 | 完全不存在（全库 grep 零命中） | 净新增 | **新建 zt_ai_code_review** + 上传接口（二期） | 一期建表 |
| 12-13 | 测试→BUG→复测→报告 | BUG、测试报告 | BUG 全流程已有（/zt-bug）；测试报告无承载（zt_testtask.report 死字段） | 测试报告无上传入口 | FileTypes 加 testReport + 附件入口 | 二期 |
| 14 | 工作日志/AI 文档更新 | AI 工作日志 | 完全不存在 | 净新增 | **新建 zt_ai_work_log**（8 类 log_type 覆盖 SRC-001 全部日志项） | 一期建表 |

## 二、架构决策

- **AD-1 扩展表模式**：AI 类指标一律进扩展表（zt_story_extend / zt_task_extend / zt_ai_*），不碰 zt_task、zt_story 等禅道老表。依据：zt_story_extend 先例 + 禅道升级兼容。
- **AD-2 AI 数据统一上传模式**：所有 AI 侧数据（W 值、代码审查、工作日志、AI 参与率）由 AI 框架计算后经 saveOrUpdate 类接口写入，zentao 只存不算（用户确认边界）。上传接口鉴权策略待决（Q4-1：现状 saveOrUpdate 无 token 直连，见 itsm_post.py）。
- **AD-3 文档类走 zt_file 通用通道**：PRD/原型图/测试报告不建专用表，FileTypes 扩展 testReport；PRD 版本时间进 zt_ai_work_log。
- **AD-4 展示打通集中二期**：storyinfo 增 AI 区块（指标/审查/日志）、meeting 附件渲染、测试报告入口——均为前端轻改，后端一期仅落模型。
- **AD-5 绩效消费三期**：IZtCountService 目前完全不消费 zt_story_extend（孤岛），三期按 SRC-002 公式接入工作量指数完成率等指标。

## 三、分期方案

| 期 | 内容 | 验收依据 |
|---|---|---|
| **一期（本期 MVP，W=10.2）** | 数据模型：zt_ai_code_review、zt_ai_work_log、zt_task_extend 三张新表 + zt_story_extend 加列；DDL+实体+Mapper+Service+单测 | acceptance v2（AC-1~5），注：任务侧字段落地形式由"加列"细化为"扩展表"，验收条目语义不变 |
| 二期 | 上传接口（/zt-ai-code-review、/zt-ai-work-log）+ 展示打通（storyinfo AI 区块、meeting 附件、测试报告入口）+ activateddate 补写 | 待二期立项评估 |
| 三期 | 绩效消费：IZtCountService 接入 AI 指标，9 岗位考核公式自动化（SRC-002） | 待三期立项评估 |