211 lines
10 KiB
Markdown
211 lines
10 KiB
Markdown
# 开发方案（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）。
|