# 开发方案（v4.0：依据 PRD v1.24）

> 本文整合截至 CHG-025 的全部决策：**数值走表、文档走 MD 文件流、状态字段可查询化**。
> 一期 W≈1~2 人日（仅 1 列）；二期立项评估；三期立项评估+口径锁定。

## 0. 文档信息

| 字段 | 内容 |
|---|---|
| 版本 | v4.0 |
| 状态 | 评审中 |
| 作者 | AI（pmassist/tgassist 流程产出） |
| 创建日期 | 2026-07-23 |
| 依据 | outputs/prd.md v1.24 |

### 变更记录

| 版本 | 日期 | 变更编号 | 变更说明 |
|---|---|---|---|
| v4.0 | 2026-07-23 | — | 基于 PRD v1.24 全量重生成（取代 v3.x：融入 CHG-014 MD 文件流、CHG-018 zt_file.url、CHG-019 砍 zt_task_extend、CHG-020 zt_meeting.url、CHG-021~025 zt_story 7 url 列+code_review_status+测试 4 文档字段） |

---

## 1. 架构总览

```mermaid
graph LR
    subgraph AI框架
        A1[pmassist: PRD/纪要/用例] --> M[MD 文件]
        A2[tgassist: 审查报告/工作日志] --> M
        A3[demand-assessor: 指标数值] --> N[/zt-story-expand 已有/]
        A4[tgassist: 任务拆分] --> T[/zt-task/aiBatchAdd 新增/]
    end
    M -->|/common/uploadBind| F[zt_file + url]
    F --> S[zt_story 7 url 列 + code_review_status<br/>zt_meeting.url 自动刷新]
    F --> P[详情页在线渲染 MD]
    F --> C[FR-014 齐备核查·三期]
```

- **数值类**：zt_story_expand（已有+一期加 1 列）；任务工时入 zt_task.estimate（任务级指数豁免）
- **文档类**：一律 MD → zt_file（FileTypes 6 新类）→ url 直取 + 在线渲染
- **状态类**：code_review_status 随审查报告上传写入（SOP 卡点可系统强制）

---

## 2. 一期（极瘦版，W≈1~2 人日）

### 2.1 唯一 DDL（codes/zentao/sql/`20260724_alter_zt_story_expand_add_ai_rate.sql`，含说明头+回滚+可重入）

```sql
SET @c := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
  WHERE TABLE_SCHEMA=DATABASE() AND TABLE_NAME='zt_story_expand' AND COLUMN_NAME='ai_participation_rate');
SET @s := IF(@c=0,
  'ALTER TABLE `zt_story_expand` ADD COLUMN `ai_participation_rate` VARCHAR(16) DEFAULT NULL COMMENT ''AI参与率（只存不算，口径待定）'' AFTER `ai_efficiency_coefficient`',
  'SELECT 1');
PREPARE st FROM @s; EXECUTE st; DEALLOCATE PREPARE st;
-- 回滚：ALTER TABLE zt_story_expand DROP COLUMN ai_participation_rate;
```

### 2.2 实体与测试

- `ZtStoryExpand.java` 加 `private String aiParticipationRate;`（紧随 aiEfficiencyCoefficient）；saveOrUpdate 自动携带，XML 不动；无新 Service/Controller
- 回归测试 1 场景：saveOrUpdate 实体带 aiParticipationRate → 透传到 insert/update（JUnit5+Mockito）

### 2.3 步骤（1 人 1~2 天）

D1 DDL+评审+本地执行+实体加字段 → D2 回归测试+dev_log+送审

### 2.4 检查单

- [ ] 仅此 1 项 DDL；无计算逻辑；无 Controller 泄漏；说明头+回滚+可重入齐全；现有编译/测试不红

---

## 3. 二期：文件流 + 接口 + 页面 + 挂钩（详细规格）

### 3.1 DDL 清单（3 个文件，均含说明头+可重入）

```sql
-- ① zt_file 加访问链接
ALTER TABLE zt_file ADD COLUMN url VARCHAR(512) DEFAULT NULL COMMENT '附件访问链接' AFTER pathname;

-- ② zt_meeting 加纪要链接（多份存最新）
ALTER TABLE zt_meeting ADD COLUMN url VARCHAR(512) DEFAULT NULL COMMENT '会议纪要MD访问链接（最新一份）';

-- ③ zt_story 加 8 列
ALTER TABLE zt_story
  ADD COLUMN prd_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN code_review_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN work_log_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN test_case_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN test_report_download_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN test_report_submit_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN test_other_url VARCHAR(512) DEFAULT NULL,
  ADD COLUMN code_review_status VARCHAR(16) DEFAULT NULL COMMENT '审查状态 pass/reject';
```

### 3.2 FileTypes 扩展 6 类 + uploadBind

`enums/FileTypes.java` 新增：`aiCodeReview`、`aiWorkLog`、`testCase`、`testReport`、`testReportSubmit`、`testOther`。

新增 `POST /common/uploadBind`（上传+绑定一步完成；现状 /common/upload 不写 objectType 需业务表单二次绑定，AI 纯上传无表单）。按 objectType 自动刷新主表字段：

| objectType | 附件 | 自动写入 |
|---|---|---|
| story | PRD | zt_story.prd_url |
| aiCodeReview | 审查报告 | code_review_url；**code_review_status**（报文参数或 MD 头部「结果」解析） |
| aiWorkLog | 工作日志 | work_log_url |
| testCase | 测试用例（下载） | test_case_url |
| testReport | 报告模版（下载） | test_report_download_url |
| testReportSubmit | 报告（模版填完提交） | test_report_submit_url |
| testOther | 其他测试文档 | test_other_url |
| meeting | 会议纪要 | zt_meeting.url（刷新为最新一份） |

**MD 附件字段**：zt_file(objectType/objectID/title/pathname/url/extension/addedBy 操作人/addedDate 操作时间/extra)；extra 约定：审查报告 {"round":N}、工作日志 {"logType":"8类之一"}、测试报告 {"reviewRound":N}；审查报告 MD 头部约定「严重：N／错误：N」（三期取数）。

### 3.3 MD 在线渲染

引入 markdown-it，封装 MdPreview 组件：.md 附件点击→按 url（空则 pathname 拼接）拉取→页面内渲染；其他格式维持下载；上传组件放开 .md 类型。

### 3.4 接口（2 新增 + 2 小改 + 前置）

1. `POST /common/uploadBind`：见 3.2
2. `POST /zt-task/aiBatchAdd`：

```json
{"storyId": 8319, "tasks": [
  {"name": "建表与实体生成", "type": "devel", "assignedTo": "zhangsan", "aiEvaluationTime": "6", "planStartDate": "2026-07-27", "deadline": "2026-07-29"},
  {"name": "接口联调测试", "type": "test", "assignedTo": "lisi", "aiEvaluationTime": "2"}
]}
```

   事务：storyId 不存在或 type 非 devel/test → 整批拒绝；同 storyId+name+type 重复 → 跳过记 skipped；建 zt_task（status=wait、create_user=`ai`、estimate=aiEvaluationTime）。响应含 taskIds：`{"code":0,"data":{"created":2,"taskIds":[12001,12002],"skipped":[]}}`

3. `ZtStoryUserServiceImpl.java:562` 附近补写 `activateddate`（1 行）
4. 鉴权**必决**（多人环境）：签名/内部 token，不得裸连
5. 前置：`zt_user` 建 `ai` 账户

### 3.5 页面改动（web_zentao）

**用户需求详情**：右侧 tabs 加「需求讨论会议」——列出 zt_meeting.storyIds 含本需求的会议（主题/类型/时间/参与人/创建人），点击跳详情；查询用 FIND_IN_SET（防 12 误中 112）；关系多对多。

**会议纪要页**：add/editDialog 渲染 uploads（objectType=meeting）；多份 MD 按时间排列，显示操作人（addedBy）/操作时间（addedDate）/会议人（users）；.md 点击 MdPreview；查看直取 zt_meeting.url（最新一份）。

**研发需求详情**（对应补充⑧，②~⑥展示位）：

| 区块/按钮 | 内容 | 数据 |
|---|---|---|
| ~~需求 ID 展示~~ | 已按用户验收反馈移除（页面顶部已有 ID+标题，冗余） | — |
| 「AI 指标」区块 | 12 字段只读（含 aiParticipationRate） | zt_story_expand |
| 测试用例 | 查看+下载（不上传覆盖） | zt_file(testCase)+zt_case |
| 测试报告模版 | 查看+下载 | zt_file(testReport) |
| 「提交测试报告」 | 上传+在线查看（**code_review_status≠pass 禁用**——SOP 卡点系统强制） | zt_file(testReportSubmit) |
| 其他测试文档 | 上传+查看 | zt_file(testOther) |
| 「代码审查报告」 | 上传 MD 多份（按轮次）+在线查看+**状态展示（code_review_status）** | zt_file(aiCodeReview)+zt_story |
| 「工作日志」 | 上传 MD+在线查看 | zt_file(aiWorkLog) |

### 3.6 框架挂钩（upload_md.py，模式照 submit_assessment.py）

```bash
python upload_md.py --story-id 8319 --type aiWorkLog --file outputs/work_log.md
```

| 触发点 | --type |
|---|---|
| pmassist 定稿 PRD | story |
| 会议纪要产出 | meeting（objectId=meetingId） |
| 代码审查每轮结束 | aiCodeReview（文件名含轮次，头部带「结果/严重/错误」） |
| 各节点工作日志 | aiWorkLog |
| 用例/报告模版产出 | testCase / testReport |
| 测试报告提交 | testReportSubmit |
| 其他测试文档 | testOther |
| demand-assessor 评估完 | 维持 submit_assessment.py（数值通道已通） |

原则：产生即传、不补传；人工按钮为备选通道。

---

## 4. 三期：绩效消费（要点，承接 v2.2 详细版）

- **FR-014 判定源**：zt_case + zt_file(testReportSubmit / aiCodeReview / aiWorkLog)；《AI 文档更新记录》=zt_file(aiWorkLog) 中 doc_update 类内容
- **代码质量取数**：审查报告 MD 头部「严重：N／错误：N」解析（三期前确认约定；否则人工读数）
- 其余不变：三层架构（指标/规则 zt_perf_config/落库 zt_month_score）、zt_doc_check 快照、13 项自动指标取数表、6 接口 4 页面、人工评分入口、对拍验收（取 1~2 个已考核月份与线下 Excel 对拍）
- 立项前锁定：口径待确认 5 项（PRD 7.3）

---

## 5. 里程碑与风险

| 里程碑 | 内容 | 时间 |
|---|---|---|
| M0 定稿 | PRD Final + 验收标准 | 待确认 |
| M1 一期 | 1 列 DDL+实体+回归（1~2 天） | 定稿后启动 |
| M2 二期 | 3 项 DDL+uploadBind+aiBatchAdd+MD 渲染+页面+挂钩+ai 账户+鉴权 | 立项评估 |
| M3 三期 | 绩效（承接第 4 章） | 立项评估 |
| M4 验收 | 对照 PRD+SRC-002 | — |

| 风险 | 等级 | 应对 |
|---|---|---|
| DDL 手工执行（zt_story 8 列为核心表，需低峰+备份） | 中 | 说明头+可重入+评审 |
| 接口鉴权未决（多人必决） | 中 | 二期立项前定签名/token |
| MD 头部计数约定不被遵守 | 中 | 模板+上传校验提示；降级人工读数 |
| 测试欠账（安全门） | 中 | 新代码强制单测 |
| 挂钩漏接（多技能） | 低 | upload_md.py 单脚本+清单核对 |

---

## 6. FR 对照

一期=FR-004 部分；二期=FR-001/002/003/004/005 部分/006/008/010/011；三期=FR-012/013/014；复用=FR-009；豁免=FR-007 指数部分（CHG-019）。