feat: 根目录文档、脚本、gitignore
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
# 验收标准（AC）— 依据 prd.md v1.24，14 条 FR 全覆盖
|
||||
|
||||
> 格式：Given/When/Then；编号 AC-{FR后缀}-{序号}；每条 FR ≥1 正常 + ≥1 异常/边界。
|
||||
> 分期标注同 FR：①一期 ②二期 ③三期。
|
||||
|
||||
## AC-001 用户需求管理（FR-001，复用+②）
|
||||
|
||||
- **AC-001-1（正常路径）**
|
||||
- Given：业务部门在系统创建用户需求并提交评审
|
||||
- When：全员评审通过（userReview）
|
||||
- Then：status=active；revieweddate 落库（=审批时间口径）；二期后 activateddate 同步落库
|
||||
- **AC-001-2（异常路径）**
|
||||
- Given：需求处于 reviewing
|
||||
- When：评审不通过（revieweResult=0）
|
||||
- Then：需求关闭，closedby/closeddate/closedreason 落库
|
||||
|
||||
## AC-002 需求讨论会与纪要 MD（FR-002，②）
|
||||
|
||||
- **AC-002-1（正常路径）**
|
||||
- Given：已创建会议（关联用户需求）
|
||||
- When：上传 .md 会议纪要（可多次）
|
||||
- Then：zt_file(objectType=meeting) 新增附件；列表显示操作人（addedBy）/操作时间（addedDate）/会议人（users）；点击在线渲染；zt_meeting.url 刷新为最新一份
|
||||
- **AC-002-2（边界）**
|
||||
- Given：上传 PDF/图片格式纪要
|
||||
- Then：维持下载查看，不渲染
|
||||
- **AC-002-3（异常/匹配）**
|
||||
- Given：需求 ID=12，存在关联需求 112 的会议
|
||||
- When：查看需求 12 的「需求讨论会议」tab
|
||||
- Then：仅列出 FIND_IN_SET 精确匹配需求 12 的会议，不误中 112
|
||||
|
||||
## AC-003 PRD 文档管理（FR-003，复用+②）
|
||||
|
||||
- **AC-003-1（正常路径）**
|
||||
- Given：PRD 定稿（pmassist 产出 .md）
|
||||
- When：经 /common/upload 上传至需求（FileTypes.story/userStory）
|
||||
- Then：附件列表可见可下载；生成时间记入工作日志 MD（prd_version 类，FR-011）
|
||||
- **AC-003-2（边界）**
|
||||
- Given：同一需求上传多版 PRD
|
||||
- Then：多份按上传时间排列，历史均可下载
|
||||
|
||||
## AC-004 需求级 AI 工作量指标（FR-004，①+②）
|
||||
|
||||
- **AC-004-1（正常路径）**
|
||||
- Given：框架完成评估
|
||||
- When：调 /zt-story-expand/saveOrUpdate（含 aiParticipationRate）
|
||||
- Then：zt_story_expand 落库，含 ai_participation_rate 新列
|
||||
- **AC-004-2（幂等）**
|
||||
- Given：同 storyId 已存在记录
|
||||
- When：再次提交
|
||||
- Then：更新不新增（一行记录）
|
||||
- **AC-004-3（异常）**
|
||||
- Given：需求 requirementStatus=finished
|
||||
- When：再次提交变更
|
||||
- Then：拒绝（沿用现有 finished 锁定规则）
|
||||
|
||||
## AC-005 验收标准与测试用例管理（FR-005，复用）
|
||||
|
||||
- **AC-005-1（验证）**
|
||||
- Given：研发需求已录入验收标准（verify）与用例
|
||||
- Then：详情页展示验收标准富文本；用例评审链（story-case）可流转
|
||||
|
||||
## AC-006 研发任务双通道（FR-006，②）
|
||||
|
||||
- **AC-006-1（正常路径）**
|
||||
- Given：合法 aiBatchAdd 报文（含 devel/test 任务）
|
||||
- When：提交
|
||||
- Then：任务批量创建：status=wait、创建人=ai、estimate=aiEvaluationTime；响应返回 taskIds；测试任务指派测试人员
|
||||
- **AC-006-2（异常路径）*
|
||||
- Given：storyId 不存在或 type 非法
|
||||
- Then：整批拒绝，code≠0，零入库
|
||||
- **AC-006-3（防重）**
|
||||
- Given：同 storyId+name+type 已存在
|
||||
- Then：跳过并记入 skipped，其余正常创建
|
||||
|
||||
## AC-007 任务级 AI 工时（FR-007，豁免验证）
|
||||
|
||||
- **AC-007-1（正常路径）**
|
||||
- When：aiBatchAdd 创建任务
|
||||
- Then：zt_task.estimate=报文 aiEvaluationTime（标准字段直接可用，无扩展表）
|
||||
- **AC-007-2（豁免）**
|
||||
- Then：数据库中不存在 zt_task_extend 表（CHG-019 不建）
|
||||
|
||||
## AC-008 AI 代码审查报告 MD（FR-008，②）
|
||||
|
||||
- **AC-008-1（正常路径）**
|
||||
- Given：需求下全部开发任务完工
|
||||
- When：uploadBind 上传审查 MD（objectType=aiCodeReview）
|
||||
- Then：zt_file 落附件；code_review_url 刷新；code_review_status 写入（pass/reject）；详情页在线查看
|
||||
- **AC-008-2（SOP 卡点）**
|
||||
- Given：code_review_status≠pass（NULL 或 reject）
|
||||
- Then：「提交测试报告」按钮禁用
|
||||
- **AC-008-3（多轮回炉）**
|
||||
- Given：第 1 轮 reject 后修复
|
||||
- When：上传第 2 轮报告
|
||||
- Then：url 刷新为最新；历史多份保留；extra.round 递增
|
||||
- **AC-008-4（异常）**
|
||||
- Given：缺 storyId 或 objectType 非法
|
||||
- Then：拒绝并返回错误
|
||||
|
||||
## AC-009 测试任务与 BUG（FR-009，复用）
|
||||
|
||||
- **AC-009-1（验证）**
|
||||
- Then：BUG 全流程可走通：提交→指派→修复→复测→验收（bugYs）
|
||||
|
||||
## AC-010 测试类文档 4 字段（FR-010，②）
|
||||
|
||||
- **AC-010-1（用例/模版）**
|
||||
- Then：测试用例（testCase）与报告模版（testReport）可查看、可下载，不可上传覆盖
|
||||
- **AC-010-2（提交）**
|
||||
- When：上传填完的报告（testReportSubmit）
|
||||
- Then：test_report_submit_url 刷新；FR-014 判定该项齐备
|
||||
- **AC-010-3（其他文档）**
|
||||
- When：上传其他测试文档（testOther）
|
||||
- Then：test_other_url 刷新，可查看下载
|
||||
|
||||
## AC-011 AI 工作日志 MD（FR-011，②）
|
||||
|
||||
- **AC-011-1（正常路径）**
|
||||
- Given：框架节点产出日志 MD
|
||||
- When：upload_md.py --type aiWorkLog 上传
|
||||
- Then：zt_file(aiWorkLog) 落附件、work_log_url 刷新、在线查看
|
||||
- **AC-011-2（时效）**
|
||||
- Then：事件产生即传，不做月末批量补传；人工按钮为备选通道
|
||||
|
||||
## AC-012 工作量指标完成率统计（FR-012，③）
|
||||
|
||||
- **AC-012-1（正常路径）**
|
||||
- Given：zt_story_month_workload 当月有数据、考勤可用
|
||||
- When：查询完成率
|
||||
- Then：=Σ(月度工作量指数)÷(团队可用工作天数×5)；测试人员不计入产出方
|
||||
|
||||
## AC-013 九岗位绩效报表（FR-013，③）
|
||||
|
||||
- **AC-013-1（规则配置化）**
|
||||
- Given：zt_perf_config 已灌入 7.5 权重规则
|
||||
- Then：✅ 项自动产出；权重/阈值改动仅需改配置
|
||||
- **AC-013-2（对拍验收）**
|
||||
- Given：最近 1~2 个已线下考核月份
|
||||
- Then：系统算分与线下 Excel 一致或差异可解释
|
||||
|
||||
## AC-014 大型需求文档齐备自动核查（FR-014，③）
|
||||
|
||||
- **AC-014-1（正常路径）**
|
||||
- Given：大型需求（指数>20）五类文档齐全
|
||||
- When：月度核查
|
||||
- Then：五类全 ✓、不扣分、写 zt_doc_check 快照
|
||||
- **AC-014-2（扣分）**
|
||||
- Given：缺 2 份
|
||||
- Then：扣 4 分（每份 2 分）写 zt_month_score.scopeJson
|
||||
- **AC-014-3（判定源正确性）**
|
||||
- Then：《需求测试报告》以 zt_file(testReportSubmit) 为准（非 testReport 模版）；《AI 文档更新记录》以 zt_file(aiWorkLog) 中 doc_update 类为准
|
||||
- **AC-014-4（异议）**
|
||||
- Given：对判定结果申诉
|
||||
- When：技术负责人复核撤销
|
||||
- Then：回滚对应扣分并留痕
|
||||
@@ -0,0 +1,344 @@
|
||||
# AI 交互接口文档 —— 禅道 AI SOP 改造（二期）
|
||||
|
||||
> **版本**：v1.0 ｜ **日期**：2026-08-06 ｜ **关联改动**：CHG-039 ~ CHG-070（鉴权落地 CHG-061）
|
||||
> **验证状态**：✅ 已验证（全部字段/分支/错误文案均取自运行代码实证，非推测）
|
||||
> **证据位置**：见文末「证据映射表」；单测 24 绿、8086 三×三鉴权矩阵实测通过（dev_log CHG-061）
|
||||
> **适用范围**：AI 框架通道（demand-assessor / pmassist / tgassist 等技能脚本）与 zentao 后端的全部交互接口
|
||||
|
||||
---
|
||||
|
||||
## 1. 通用约定
|
||||
|
||||
### 1.1 Base URL
|
||||
|
||||
| 环境 | Base URL | 说明 |
|
||||
|---|---|---|
|
||||
| 本地测试 | `http://127.0.0.1:8085/zentao` | 框架脚本（submit_assessment.py / upload_md.py）默认地址（CHG-061 拍板"别用正线的 url"） |
|
||||
| 测试库直连验证 | `192.168.1.161:3306/zentao_dev` | DB 回读校验用，非接口地址 |
|
||||
| 生产 | `http://192.168.1.105:8015/zentao` | ⚠️ [ASSUMPTION] 端口 8015 见 dev_log CHG-070"发布 8015 即可生效"；主机地址以部署实为准 |
|
||||
|
||||
- 所有路径均含上下文根 `/zentao`（部署于域名根路径）。
|
||||
- 字符集 UTF-8；JSON 接口 `produces = application/json; charset=UTF-8`。
|
||||
|
||||
### 1.2 鉴权（CHG-061 落地）
|
||||
|
||||
- 请求头：**`Authorization: {token}`**（JWT，由 `JwtAuthenticationFilter` 解析，写入 `RiskUserThreadLocal`）。
|
||||
- token 获取（人工/调试用）：
|
||||
```
|
||||
POST /zentao/zt-user/login
|
||||
Content-Type: application/json
|
||||
{"account":"admin","password":"<md5(密码)>"}
|
||||
→ 响应 data 即 token
|
||||
```
|
||||
- **AI 通道使用 ai 账户永久 token**（生成于 `.claude/ai_token.txt`，框架两脚本自动携带，无需手工管理）。
|
||||
- token 缺失或无效：过滤器直接返回 `{"code":-1,"message":"请登录"}`，不进入业务层。
|
||||
|
||||
**接口级权限矩阵**：
|
||||
|
||||
| 接口 | 权限要求 | 越权响应 |
|
||||
|---|---|---|
|
||||
| `/zt-story-expand/saveOrUpdate` | **仅 ai 账户 token** | `code:-1` "该接口仅AI框架通道可用（需ai账户token）" |
|
||||
| `/zt-task/aiBatchAdd` | **仅 ai 账户 token** | `code:-1` "aiBatchAdd仅AI框架通道可用（需ai账户token）" |
|
||||
| `/common/uploadBind` | **任意登录态**（AI 带 ai token；UI 带用户 token） | `code:-1` "请登录（上传需携带有效token）" |
|
||||
|
||||
### 1.3 统一响应结构
|
||||
|
||||
```json
|
||||
{ "code": 0, "message": "成功", "data": { } }
|
||||
```
|
||||
|
||||
| code | 含义 | 触发 |
|
||||
|---|---|---|
|
||||
| `0` | 成功 | 正常返回（data 可为 null） |
|
||||
| `-1` | 失败 | 业务校验失败（BusinessException，message 为具体原因）；文件为空；未登录 |
|
||||
| `-2` | 重复添加 | 框架保留码，本三接口未使用 |
|
||||
| `401` | 请登录 | 框架保留码；实际未登录返回 `-1` + "请登录"（过滤器写死） |
|
||||
|
||||
### 1.4 AI 框架典型调用时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Skill as AI 技能脚本<br/>(demand-assessor/tgassist)
|
||||
participant ZT as zentao 后端
|
||||
participant DB as MySQL (zt_*)
|
||||
|
||||
Note over Skill: .claude/ai_token.txt<br/>自动读 ai 永久 token
|
||||
Skill->>ZT: ① POST /zt-story-expand/saveOrUpdate<br/>(W 指标 + 验收标准 MD)
|
||||
ZT->>DB: upsert zt_story_expand（按 story_id）
|
||||
Skill->>ZT: ② POST /zt-task/aiBatchAdd<br/>(拆分 devel/test 任务)
|
||||
ZT->>DB: insert zt_task × N（跳过重复）<br/>+ zt_action 留痕（任务级+需求级）
|
||||
Skill->>ZT: ③ POST /common/uploadBind<br/>(PRD/审查报告/日志等 MD 文件)
|
||||
ZT->>DB: 刷新主表 url 字段 → 插 zt_file<br/>+ zt_action 动态
|
||||
ZT-->>Skill: {"code":0,"data":zt_file 记录}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 接口一览
|
||||
|
||||
| # | 接口 | 方法 | 路径 | Content-Type | 鉴权 | 用途 | 关联 FR |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 1 | AI 评估指标与验收标准提交 | POST | `/zentao/zt-story-expand/saveOrUpdate` | application/json | 仅 ai token | 七步评估结果（S/B/F(T)/G(A)/W）+ 验收标准 MD 落库 | FR-004 |
|
||||
| 2 | AI 批量拆分任务 | POST | `/zentao/zt-task/aiBatchAdd` | application/json | 仅 ai token | 按任务清单批量建 devel/test 任务，防重跳过 | FR-006 |
|
||||
| 3 | 文件上传并绑定业务对象 | POST | `/zentao/common/uploadBind` | multipart/form-data | 任意登录态 | 上传 MD 等文件，同步刷新主表 url 字段 | FR-002/005/008/010/011 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口 1：AI 评估指标与验收标准提交
|
||||
|
||||
```
|
||||
POST /zentao/zt-story-expand/saveOrUpdate
|
||||
Content-Type: application/json
|
||||
Authorization: {ai token}
|
||||
```
|
||||
|
||||
**用途**：demand-assessor 七步评估完成后，将工作量指标与 AI 框架验收标准写入 `zt_story_expand`（按 `story_id` upsert）。生产侧由 `submit_assessment.py` 调用。
|
||||
|
||||
### 3.1 请求体字段（ZtStoryExpand）
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `storyId` | Integer | ✅ | 需求 ID（zt_story.id）。**为空时服务端静默返回成功、不处理**（见 3.2 分支②） |
|
||||
| `numberUnits` | Integer | 评估时✅ | 单元数量 S |
|
||||
| `unitBusinessComplexity` | String | 评估时✅ | 单元业务复杂度 B（如 `"2.2"`） |
|
||||
| `technicalComplexityCoefficient` | String | 评估时✅ | 技术复杂度系数 F(T)（如 `"1.4"`） |
|
||||
| `aiEfficiencyCoefficient` | String | 评估时✅ | AI 效率系数 G(A)（如 `"0.55"`） |
|
||||
| `evaluationTime` | BigDecimal | 评估时✅ | 评估工时 W（人日，如 `5.1`） |
|
||||
| `workloadIndex` | String | 否 | 工作量指数（finished 结算时优先取库内已有值） |
|
||||
| `aiParticipationRate` | String | 否 | AI 参与率（只存不算，口径待定） |
|
||||
| `requirementStatus` | String | 否 | `inProgress`（默认）/ `finished`；**finished 触发月度工作量结算** |
|
||||
| `requirementCompletionDegree` | String | 否 | 需求完成度 `"0"~"100"`；finished 时被强制置 `"100"` |
|
||||
| `acceptanceCriteria` | String | 否 | AI 框架验收指标（Given/When/Then，MD 文本）。与老验收标准 `zt_storyspec.verify` 互不干扰（CHG-022） |
|
||||
| `productPerson` / `developPerson` / `testPerson` | String | 否 | 产品/开发/测试人员（中文名） |
|
||||
| `id` / `createTime` / `updateTime` / `createUser` / `updateUser` | — | 无需传 | 服务端维护（id 自增，时间戳自动写） |
|
||||
| `storyTitle` / `createUserNickname` / `month` / `monthEvaluationTime` | — | 无需传 | 非数据库字段（查询展示/内部结算用） |
|
||||
|
||||
### 3.2 业务规则与分支
|
||||
|
||||
| # | 分支 | 行为 |
|
||||
|---|---|---|
|
||||
| ① | token 非 ai 账户 | 拒绝：`-1` "该接口仅AI框架通道可用（需ai账户token）" |
|
||||
| ② | `storyId` 为空 | **静默返回 `code:0`**，不建不改（注意：不等于参数报错） |
|
||||
| ③ | 该 storyId 无记录 | insert；`requirementStatus` 未传时默认 `inProgress`；create/updateTime=now |
|
||||
| ④ | 已有记录且其状态为 `finished` | **拒绝**："该需求已完成，不可再修改"（守卫：定稿后不可覆写） |
|
||||
| ⑤ | 已有记录（非 finished） | update by id，updateTime=now |
|
||||
| ⑥ | 本次提交 `requirementStatus=finished` | 强制完成度 `"100"`；写当月 `zt_story_month_workload`：增量 = 100 − 历史最高完成度；折算工时 = 工作量指数 × 增量 ÷ 100（2 位小数 HALF_UP）；增量 ≤ 0 记 0 |
|
||||
| ⑦ | 幂等性 | 同 storyId 重复提交 = 覆盖更新，不产生重复行 |
|
||||
|
||||
### 3.3 报文示例
|
||||
|
||||
```json
|
||||
{
|
||||
"storyId": 9130,
|
||||
"numberUnits": 3,
|
||||
"unitBusinessComplexity": "2.2",
|
||||
"technicalComplexityCoefficient": "1.4",
|
||||
"aiEfficiencyCoefficient": "0.55",
|
||||
"evaluationTime": 5.1,
|
||||
"workloadIndex": "5.1",
|
||||
"developPerson": "魏冬霞",
|
||||
"testPerson": "罗勇",
|
||||
"acceptanceCriteria": "## AC-001\n- Given ...\n- When ...\n- Then ..."
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 响应
|
||||
|
||||
```json
|
||||
{ "code": 0, "message": "成功", "data": null }
|
||||
```
|
||||
|
||||
失败：`{ "code": -1, "message": "该接口仅AI框架通道可用（需ai账户token）" }` / `{ "code": -1, "message": "该需求已完成，不可再修改" }`
|
||||
|
||||
---
|
||||
|
||||
## 4. 接口 2：AI 批量拆分任务
|
||||
|
||||
```
|
||||
POST /zentao/zt-task/aiBatchAdd
|
||||
Content-Type: application/json
|
||||
Authorization: {ai token}
|
||||
```
|
||||
|
||||
**用途**：按任务清单为指定需求批量创建研发/测试任务；同需求下重名同类型任务自动跳过。生产侧由任务拆分流程（tasks.md → zentao）调用。
|
||||
|
||||
### 4.1 请求体字段（ZtTaskAiBatchDTO）
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `storyId` | Integer | ✅ | 需求 ID；不存在则整批拒绝 |
|
||||
| `tasks` | Array | ✅ 非空 | 任务项列表 |
|
||||
| `tasks[].name` | String | ✅ | 任务名称（空则整批拒绝） |
|
||||
| `tasks[].type` | String | ✅ | 仅 `devel`（开发）/ `test`（测试）；其他值**整批拒绝** |
|
||||
| `tasks[].assignedTo` | String | 否 | 指派人账号（zt_user.account）；留痕时转中文昵称显示 |
|
||||
| `tasks[].aiEvaluationTime` | Float | 否 | AI 评估工时 → 同时写入 `estimate` 与 `left`，`consumed=0` |
|
||||
| `tasks[].planStartDate` | String | 否 | 预计开始 `yyyy-MM-dd` → `estStarted` |
|
||||
| `tasks[].deadline` | String | 否 | 预计完成 `yyyy-MM-dd` → `deadline`，并写 `deadlineTime`（秒级时间戳） |
|
||||
|
||||
### 4.2 业务规则与分支
|
||||
|
||||
| # | 分支 | 行为 |
|
||||
|---|---|---|
|
||||
| ① | token 非 ai 账户 | 拒绝：`-1` "aiBatchAdd仅AI框架通道可用（需ai账户token）" |
|
||||
| ② | `storyId` 空 / 需求不存在 / `tasks` 空 / 任一 name 空 / 任一 type 非 devel\|test / 日期格式错 | **整批拒绝**（BusinessException，事务回滚，一个都不建） |
|
||||
| ③ | 防重 | 同需求下已存在 `name#type`（未删除）→ 跳过并记入 `skipped`；**批内重复同样防重**（建过的 key 即时入集合） |
|
||||
| ④ | 创建字段 | `status=wait`、`openedby=ai`（token 身份）、`openeddate=now`、`estimate=left=aiEvaluationTime` |
|
||||
| ⑤ | 留痕（CHG-059/060/062） | 任务级：`zt_action`（RW+XJ）每任务一条，与手工建任务同形状；需求级：**一批合并一条**（XQ+BJ），文案含个数、序号、各任务名称/类型/工时/指派中文名、跳过数 |
|
||||
| ⑥ | 日期格式 | 非法日期整批拒绝："日期格式错误，应为yyyy-MM-dd:{任务名}" |
|
||||
|
||||
### 4.3 报文示例
|
||||
|
||||
```json
|
||||
{
|
||||
"storyId": 9130,
|
||||
"tasks": [
|
||||
{"name": "二期 DDL×3 + 自测", "type": "devel", "assignedTo": "guoqibing",
|
||||
"aiEvaluationTime": 8, "planStartDate": "2026-08-10", "deadline": "2026-08-11"},
|
||||
{"name": "后端接口测试：uploadBind/aiBatchAdd", "type": "test", "assignedTo": "zhangfubin",
|
||||
"aiEvaluationTime": 8, "planStartDate": "2026-08-12", "deadline": "2026-08-12"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"created": 2,
|
||||
"taskIds": [18565, 18566],
|
||||
"skipped": ["二期 DDL×3 + 自测"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `created`：本次实际新建数；`taskIds`：新建任务 ID 列表；`skipped`：因重名同类型跳过的任务名列表。
|
||||
- 全部重复时：`created:0`、`taskIds:[]`、`skipped` 全量 —— 仍返回 `code:0`（跳过不算失败）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 接口 3：文件上传并绑定业务对象
|
||||
|
||||
```
|
||||
POST /zentao/common/uploadBind
|
||||
Content-Type: multipart/form-data
|
||||
Authorization: {任意登录态 token}
|
||||
```
|
||||
|
||||
**用途**：上传文件（AI 框架场景为 MD 文档）并一步绑定到业务对象：写磁盘 + 插 `zt_file` + **按 objectType 刷新主表访问链接字段** + 写动态留痕。生产侧由 `upload_md.py` 调用（默认本地 8085、自动带 ai token）。
|
||||
|
||||
### 5.1 表单字段（UploadDTO）
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `file` | File | ✅ | 上传文件（空文件拒绝）；服务端仅保留原扩展名，文件名为 `yyyyMMddHHmmss + UUID` |
|
||||
| `objectType` | String | ✅ | 业务对象类型，**白名单 9 类**（见 5.2）；不在白名单整体拒绝 |
|
||||
| `objectId` | Integer | ✅ | 主表记录 ID（需求/会议）；记录不存在则拒绝 |
|
||||
| `title` | String | 否 | 文件标题；缺省取原始文件名（中文标题落库正确，CHG-061 已验证） |
|
||||
| `reviewResult` | String | 否 | **仅 `objectType=aiCodeReview` 有效**：`pass` / `reject`，非空时同步写 `zt_story.code_review_status` |
|
||||
|
||||
### 5.2 objectType → 主表字段刷新映射（白名单）
|
||||
|
||||
| objectType | 含义 | 刷新主表字段 | 动态留痕 |
|
||||
|---|---|---|---|
|
||||
| `story` | PRD/需求文档 | `zt_story.prd_url` | XQ+BJ |
|
||||
| `aiCodeReview` | 代码审查报告 | `zt_story.code_review_url`（+`code_review_status`，若传 reviewResult） | XQ+BJ |
|
||||
| `aiWorkLog` | 工作日志 | `zt_story.work_log_url` | XQ+BJ |
|
||||
| `aiDocUpdate` | AI 项目文档更新记录 | `zt_story.ai_doc_update_url` | XQ+BJ |
|
||||
| `testCase` | 测试用例 | `zt_story.test_case_url` | XQ+BJ |
|
||||
| `testReport` | 测试报告模版 | `zt_story.test_report_download_url` | XQ+BJ |
|
||||
| `testReportSubmit` | 测试报告提交 | `zt_story.test_report_submit_url` | XQ+BJ |
|
||||
| `testOther` | 其他测试文档 | `zt_story.test_other_url` | XQ+BJ |
|
||||
| `meeting` | 会议纪要 | `zt_meeting.url` | MEET+BJ |
|
||||
|
||||
> FileTypes 枚举另有 task/bug/userStory 等 6 个 code，但 **uploadBind 不支持**——传入会拒绝："uploadBind不支持的objectType:{type}"。
|
||||
|
||||
### 5.3 业务规则与分支
|
||||
|
||||
| # | 分支 | 行为 |
|
||||
|---|---|---|
|
||||
| ① | 无登录态 | `-1` "请登录（上传需携带有效token）" |
|
||||
| ② | file 为空 | `-1` "失败" |
|
||||
| ③ | objectType/objectId 为空 | `-1` "objectType/objectId不能为空" |
|
||||
| ④ | objectType 非枚举值 | "不支持的objectType:{type}"；是枚举但非白名单 → "uploadBind不支持的objectType:{type}" |
|
||||
| ⑤ | objectId 记录不存在 | "需求不存在:{id}" / "会议不存在:{id}" |
|
||||
| ⑥ | 执行顺序（事务） | **先校验并刷新主表 → 失败整体回滚不落盘**；再写磁盘 → 插 `zt_file` → 写 `zt_action`（文案含完整可访问 URL） |
|
||||
| ⑦ | 落库字段 | `zt_file.addedby` = token 身份；`pathname`/`url` = 相对路径 `/zentao/img/{文件名}`（经前端源/代理可达，规避跨域）；`size` 字节数；`extension` 原扩展名 |
|
||||
| ⑧ | 多文件 | 同一 (objectType, objectId) 可多次上传，形成多份列表；主表 url 字段记录**最新一份**，前端列表取 `zt_file` 全集 |
|
||||
|
||||
### 5.4 调用示例
|
||||
|
||||
```bash
|
||||
curl -X POST "http://127.0.0.1:8085/zentao/common/uploadBind" \
|
||||
-H "Authorization: {ai token}" \
|
||||
-F "file=@代码审查报告.md" \
|
||||
-F "objectType=aiCodeReview" \
|
||||
-F "objectId=9130" \
|
||||
-F "title=代码审查报告-v1" \
|
||||
-F "reviewResult=pass"
|
||||
```
|
||||
|
||||
### 5.5 响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 1234,
|
||||
"title": "代码审查报告-v1",
|
||||
"extension": ".md",
|
||||
"size": 5321,
|
||||
"pathname": "/zentao/img/20260806170215a1b2c3....md",
|
||||
"url": "/zentao/img/20260806170215a1b2c3....md",
|
||||
"objecttype": "aiCodeReview",
|
||||
"objectid": 9130,
|
||||
"addedby": "ai",
|
||||
"addeddate": "2026-08-06 17:02:15",
|
||||
"deleted": "0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 失败分支汇总（排障速查）
|
||||
|
||||
| 现象 | code | message | 排查 |
|
||||
|---|---|---|---|
|
||||
| 未带 token / token 失效 | -1 | 请登录 | 检查 `Authorization` 头；ai token 见 `.claude/ai_token.txt` |
|
||||
| 用人工 token 调 saveOrUpdate / aiBatchAdd | -1 | 仅AI框架通道可用（需ai账户token） | 换 ai token；这是设计守卫，非缺陷 |
|
||||
| 需求已 finished 再提交指标 | -1 | 该需求已完成，不可再修改 | 生产 itsm 已有 finished 记录被此守卫拒绝（summary 2026-08-06），属按设计拦截 |
|
||||
| saveOrUpdate 返回 0 但库里没数据 | 0 | 成功 | 检查是否漏传 `storyId`（分支 3.2② 静默成功） |
|
||||
| aiBatchAdd 一个任务都没建 | -1 | （任一校验消息） | 整批拒绝机制：任一任务非法全部回滚；先修非法项 |
|
||||
| aiBatchAdd 成功但 created=0 | 0 | 成功 | 全部命中防重，看 `skipped` |
|
||||
| uploadBind 报类型不支持 | -1 | (uploadBind)不支持的objectType | 对照 5.2 白名单（9 类） |
|
||||
| uploadBind 成功但页面看不到 | 0 | 成功 | 前端列表读 `zt_file`；检查 objectType/objectId 是否传对、前端是否按类型渲染 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 证据映射表
|
||||
|
||||
| 章节 | 关键结论 | 证据来源 |
|
||||
|---|---|---|
|
||||
| 1.2 鉴权 | Authorization 头 JWT 解析、越权文案 | [CODE:codes/zentao/src/main/java/com/sa/zentao/conf/JwtAuthenticationFilter.java:41-66] [CODE:ZtStoryExpandServiceImpl.java:41-45] [CODE:ZtTaskServiceImpl.java:1360-1364] [CODE:CommonsController.java:129-132] |
|
||||
| 1.3 响应结构 | Result/Code 枚举值 | [CODE:codes/zentao/src/main/java/com/sa/zentao/dao/Result.java] [CODE:codes/zentao/src/main/java/com/sa/zentao/dao/Code.java] [CODE:conf/GlobalExceptionHandler.java:28-32] |
|
||||
| 3. 接口1 | 字段集/upsert/finished 守卫与结算 | [CODE:entity/ZtStoryExpand.java] [CODE:ZtStoryExpandServiceImpl.java:40-79,120-150] |
|
||||
| 4. 接口2 | 字段/整批拒绝/防重/留痕形状 | [CODE:dao/ZtTaskAiBatchDTO.java] [CODE:ZtTaskServiceImpl.java:1357-1470] |
|
||||
| 5. 接口3 | 白名单映射/事务顺序/落库字段 | [CODE:CommonsController.java:120-187] [CODE:ZtFileServiceImpl.java:74-154] [CODE:enums/FileTypes.java] [CODE:dao/UploadDTO.java] |
|
||||
| 1.1/运行实证 | 8085 默认地址、token 自动携带、中文标题正确 | [RUNTIME:dev_log CHG-061 闭环记录] [RUNTIME:summary.md 2026-08-06] |
|
||||
|
||||
## 8. 假设与缺口
|
||||
|
||||
| 项 | 状态 | 说明 |
|
||||
|---|---|---|
|
||||
| 生产 Base URL | ⚠️ [ASSUMPTION] | 8015 端口见于 dev_log CHG-070；生产主机/域名以部署实为准，发布时确认 |
|
||||
| `evaluationTime` 单位 | ✅ 已确认 | 人日（demand-assessor W 定义，summary 附录口径一致） |
|
||||
| `deadlineTime` 精度 | ✅ 已验证 | 秒级时间戳（ZtTaskServiceImpl.java:1425） |
|
||||
| ai 永久 token 过期策略 | ✅ 已确认 | 永久 token（CHG-061 决策，存 `.claude/ai_token.txt`） |
|
||||
|
||||
---
|
||||
|
||||
> 下一步（Check）：本文档与 `outputs/dev_plan.md`、`06_test_docs/test_cases.md` §0 环境约定一致；如发现不一致以运行代码为准修正本文档（Runtime 事实优先）。
|
||||
@@ -0,0 +1,210 @@
|
||||
# 开发方案（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）。
|
||||
@@ -0,0 +1,603 @@
|
||||
# AI开发SOP与绩效考核体系落地 PRD
|
||||
|
||||
## 0. 文档信息
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 版本 | v1.24 |
|
||||
| 状态 | 评审中 |
|
||||
| 作者 | pmassist-v3（AI） |
|
||||
| 创建日期 | 2026-07-23 |
|
||||
| 最后更新 | 2026-07-23 |
|
||||
| 适用范围 | IT 工作台（codes/zentao + codes/web_zentao）落地 AI 开发 SOP 全流程 + 9 岗位绩效考核，含三期分期 |
|
||||
|
||||
### 变更记录
|
||||
|
||||
| 版本 | 日期 | 变更编号 | 变更说明 | 影响章节 |
|
||||
|---|---|---|---|---|
|
||||
| v1.0 | 2026-07-23 | CHG-000 | 初稿 | 全部 |
|
||||
| v1.1 | 2026-07-23 | CHG-001 | 自查修正：表名 zt_story_extend→zt_story_expand（11处，以 ZtStoryExpandMapper.xml:34 为准）；ALTER 列名 aiEfficiencyCoefficient→ai_efficiency_coefficient；行号修正 ZtBugServiceImpl:478→463、CommonsController:70→71 | 1/4/5/6/7/12 章 |
|
||||
| v1.2 | 2026-07-23 | CHG-002 | 新增 FR-014 大型需求文档齐备自动核查（③期）：考核只判缺失不判内容（SRC-002 原文），人工抽检退化为月度确认+异议复核，结果复用 zt_month_score；FR-013 剔除文档抽检项；4.1 范围同步 | 4/6 章 |
|
||||
| v1.3 | 2026-07-23 | CHG-004 | 新增 7.5 绩效计算模型：SRC-002 九岗位算分规则全量结构化（通用规则+每岗位权重/扣分/加分表），逐项标注自动化程度（✅/🔶/❌）与数据来源；暴露 2 个待确认缺口（问题管理文档、设计文档质量评审的系统承载）；含 CHG-003 FR-008 规则细化（触发/每轮上传/卡点） | 6/7 章 |
|
||||
| v1.4 | 2026-07-23 | CHG-005 | 7.3 口径表补 5 个任务级公式（任务及时率/测试计划及时率/项目准时率/达标工时/产品缺陷率）；新增 3 项口径待确认（总分算法解读、线上Bug率单位矛盾、检出率申诉流程） | 7 章 |
|
||||
| v1.5 | 2026-07-23 | CHG-006 | FR-006 改双通道：AI 框架批量提交任务（②期接口）+ 人工创建保留；AI 上传任务创建人=专用账户「ai」（zt_user 新建）；覆盖开发+测试任务；AI 指标随任务写 zt_task_extend（后被 CHG-019 取消）；4.1 二期接口清单 2→3 个 | 4/6 章 |
|
||||
| v1.6 | 2026-07-23 | CHG-007 | FR-006 规则 4 定稿：AI 提交任务初始状态=未开始（wait），走现有任务流程，无特殊状态——上一版"是否需确认生效"待确认项关闭 | 6 章 |
|
||||
| v1.7 | 2026-07-23 | CHG-008 | FR-011 补框架侧触发挂钩：二期交付=zentao 接口+各技能上传挂钩两端（照 submit_assessment.py 模式，现状仅 workload_eval 已通，7 类挂钩净新增）；事件即传不补传；日志与内容表分工 | 4/6 章 |
|
||||
| v1.8 | 2026-07-23 | CHG-009 | SOP 符合性核查（用户要求）：流程 18 步、数据模型 6 类、提交动作 8 项全部有落点；修 2 处瑕疵——FR-001 补审批时间口径（=revieweddate，approveddate 闲置字段语义覆盖）、6.3 步骤 10 同步双通道最新规则 | 6 章 |
|
||||
| v1.9 | 2026-07-23 | CHG-010 | 新增 5.6 ID 流转约定：storyId 建单产生→回填 PRD「关联需求ID」+框架工作区→上传以此为键；taskId 由 aiBatchAdd 响应返回；响应示例含 taskIds | 5 章 |
|
||||
| v1.10 | 2026-07-23 | CHG-011 | 5.6 补多人协作前提（用户指出框架非单人使用）：ID 共享载体=PRD 文档非个人工作区；并发由 zentao 状态机约束；ai 账户与使用者解耦；**上传接口鉴权升级为二期必决项** | 5 章 |
|
||||
| v1.11 | 2026-07-23 | CHG-012 | ~~用户补充①：用户需求后台支持上传 MD 且在线查看 → FR-003 扩充~~（理解有误，见 CHG-013） | 4/6 章 |
|
||||
| v1.12 | 2026-07-23 | CHG-013 | 用户澄清补充①真实含义：**MD=会议纪要，在会议纪要页面操作**（可多次上传、在线查看、记录操作人/时间/会议人）→ 改正至 FR-002；FR-003 恢复原样；并给出补充②~⑧（待 4 项澄清后重写开发方案） | 4/6 章 |
|
||||
| v1.13 | 2026-07-23 | CHG-014 | **架构级变更（用户拍板）：AI 文档走 MD 文件流**——不建 zt_ai_code_review/zt_ai_work_log 两表；审查报告/工作日志=MD 文件，研发需求页按钮上传+在线查看；一期缩至 1 表（zt_task_extend）+1 列；FileTypes 扩展 aiCodeReview/aiWorkLog/testReport；FR-014 判定改 zt_file；Q1 维持 ID 回填约定、Q3 测试用例仅看/报告补传、Q4 报告挂研发需求 | 4/5/6/7/8 章 |
|
||||
| v1.14 | 2026-07-23 | CHG-015 | 同步性清扫（用户追问后自查）：修 5 处 CHG-014 残留——4.1 二期接口行、5.6 上传关联、7.4 埋点段、6.3 步骤 4、12 证据映射行；dev_plan 补回 aiBatchAdd 完整规格（原"见 v2.x"引用悬空） | 4/5/6/7/12 章 |
|
||||
| v1.15 | 2026-07-23 | CHG-016 | 全文核对（用户要求）：修 16 处过时/缺失——文档信息版本、2.1 目标截止（一期末→二期末）、2.3 约束、4.3 W=10.2 过时、5.1 方案概述、5.2 zt_ai_* 残留、5.5 补 MD 决策行、FR-003 log_type 残留、6.1 端矩阵、4.1 页面行补全、**补录遗漏的补充⑦（需求详情「需求讨论会议」tab 入 FR-002）**、7.3/7.5 zt_testtask 只读遗留误标、里程碑 M1/M2、证据映射 FR 数与公式数 | 0/2/4/5/6/7/10/12 章 |
|
||||
| v1.16 | 2026-07-23 | CHG-017 | 用户指出 3.2 S-002 未随 CHG-014 修正 → 场景补三种通道区分：指标=saveOrUpdate、任务=aiBatchAdd、审查/日志=MD 文件 | 3 章 |
|
||||
| v1.17 | 2026-07-23 | CHG-018 | 用户指定：zt_file 加 url 字段（varchar512，存 MD 访问链接，在线查看/外链取用；pathname=存储路径）→ 5.4 字段表补录；二期 DDL，uploadBind 写入、MdPreview 优先取用 | 5 章 |
|
||||
| v1.18 | 2026-07-23 | CHG-019 | **砍 zt_task_extend（用户拍板）**：evaluation_time 与 zt_task.estimate 冗余、ai_workload_index 无消费方 → 不建表；AI 工时入 zt_task.estimate；任务级指数豁免（SOP 数据项，三期按需恢复）；一期缩至 1 列（W≈1~2 人日）；FR-007 重写、7.1/4.1/5.x/6.3/8/10/12 章同步 | 4/5/6/7/8/10/12 章 |
|
||||
| v1.19 | 2026-07-23 | CHG-020 | 用户指定：zt_meeting 加 url 字段存纪要 MD 访问链接（直取不绕 zt_file）；多份纪要按"存最新一份"处理（上传刷新，历史份走 zt_file）→ 5.4 字段表补录、FR-002 规则补充 | 5/6 章 |
|
||||
| v1.20 | 2026-07-23 | CHG-021 | 用户指定：zt_story 加 5 个文档 url 字段（prd/code_review/work_log/test_report/test_case，各存最新一份，上传刷新）；FileTypes 增第 4 类 testCase（测试用例=只读文件、测试报告=补传文件）；zt_story 核心表加列破例按用户拍板 | 5/6 章 |
|
||||
| v1.21 | 2026-07-23 | CHG-022 | 用户澄清测试为**三个字段**：测试用例（下载）/测试报告·供下载/测试报告·提交 → zt_story 6 列（test_report 拆为 download/submit 两列）；FileTypes 增 testReportSubmit；FR-010 重写（报告双向：AI 供下载、测完提交）；FR-014 判定=zt_file(testReportSubmit) | 5/6 章 |
|
||||
| v1.22 | 2026-07-23 | CHG-023 | 用户指出缺字段 → 补 **code_review_status**（pass/reject/NULL）：审查结果原只在 MD 内容里系统不可查；上传审查报告时解析写入；支撑卡点强制（未 pass 禁提测试报告）、筛选、状态展示；zt_story 7 列 | 5/6 章 |
|
||||
| v1.23 | 2026-07-23 | CHG-024 | ~~测试第 4 字段=test_report_status~~（误解，见 CHG-025） | 5/6 章 |
|
||||
| v1.24 | 2026-07-23 | CHG-025 | 用户澄清：测试 4 字段全是文档——用例下载/报告模版下载/**模版填完提交**（第3）/**其他测试文档**（第4，testOther）→ zt_story 7 url 列 + code_review_status 共 8 列；撤销 test_report_status（误解产物）；FileTypes 增 testOther | 5/6 章 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 业务背景
|
||||
|
||||
### 1.1 现状与痛点
|
||||
|
||||
- 现状：信息技术部已发布 AI 时代开发 SOP（14 步流程，8 类 AI 工作日志）与 9 岗位绩效考核方案（以工作量指数为核心）[SRC-001][SRC-002]
|
||||
- IT 工作台现状（2026-07-22 代码摸底）：
|
||||
- 用户需求/研发需求/任务/BUG/工时/会议/验收全流程功能已存在 [ZT:controller/ZtStoryUserController.java][ZT:controller/ZtTaskController.java][ZT:controller/ZtBugController.java]
|
||||
- 需求级 AI 工作量指标上传通道已存在（/zt-story-expand，生产已对接 demand-assessor）[ZT:controller/ZtStoryExpandController.java:23]
|
||||
- 核心痛点：
|
||||
1. AI 指标是"孤岛"：zt_story_expand 可录入但绩效统计（IZtCountService）完全不消费 [ZT:service/impl/IZtCountService.java]
|
||||
2. AI 代码审查报告、AI 工作日志、AI 文档更新记录在系统中无任何承载（全库零命中）
|
||||
3. 测试报告无上传入口（zt_testtask.report 为死字段）；会议附件前端组件引入未渲染；用户需求 activateddate/approveddate 死字段 [ZT:entity/ZtStoryUser.java:120,153]
|
||||
4. 绩效考核依赖线下 Excel（codes/zentao 根目录多份考核 xlsx），未自动化 [ASSUMPTION: 以现有文件推断]
|
||||
|
||||
### 1.2 业务目标与问题陈述
|
||||
|
||||
让 SOP 要求的每一类数据在 IT 工作台"有处可存、有入口可传、有页面可看"，并让绩效考核直接消费系统数据，替代线下 Excel。
|
||||
|
||||
### 1.3 相关历史决策
|
||||
|
||||
- AI 指标「框架算、平台存」，zentao 只存不算（用户确认，2026-07-22）
|
||||
- 禅道老表不改结构，扩展走扩展表模式（zt_story_expand 先例）
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与成功指标
|
||||
|
||||
### 2.1 业务目标（可量化）
|
||||
|
||||
| 目标 | 指标 | 当前值 | 目标值 | 截止 |
|
||||
|---|---|---|---|---|
|
||||
| SOP 数据承载完整 | SRC-001 数据模型 9 类数据项系统覆盖率 | 6/9 复用、3 类无承载 | 9/9 | 二期末（MD 附件通道建成后） |
|
||||
| AI 指标可视 | 研发需求详情页展示 AI 指标/审查/日志 | 无（仅统计页） | 详情页可见 | 二期末 |
|
||||
| 绩效自动化 | 9 岗位考核核心指标系统产出 | 线下 Excel | 系统自动算分/导出 | 三期 |
|
||||
|
||||
### 2.2 北极星指标
|
||||
|
||||
工作量指标完成率 = Σ(月度工作量指数) ÷ (团队可用工作天数×5) 可月度自动产出 [SRC-002]
|
||||
|
||||
### 2.3 约束条件与边界
|
||||
|
||||
- 技术约束：不改禅道老表结构；数值上传沿用 saveOrUpdate 幂等模式（参照 /zt-story-expand），文档一律 MD 附件通道（CHG-014）；AI 计算口径不在本系统
|
||||
- 不在本期范围：AI 工作量指数的计算逻辑（AI 框架侧）；绩效权重/公式的管理制度变更
|
||||
- 分期边界：一期=数据模型；二期=上传接口+页面；三期=绩效消费
|
||||
|
||||
---
|
||||
|
||||
## 3. 用户与场景
|
||||
|
||||
### 3.1 目标用户/角色
|
||||
|
||||
| 角色 | 描述 | 典型诉求 |
|
||||
|---|---|---|
|
||||
| 业务部门 | 需求提出方 | 提需求、看进度、验收 |
|
||||
| 产品经理/助理 | 需求管理 | PRD 管理、工作量指标查看、验收跟进 |
|
||||
| 项目经理 | 过程与考核管理 | SOP 文档齐备、绩效数据可信 |
|
||||
| 开发（前/后端） | 任务执行 | 任务与工时清晰、代码审查有记录 |
|
||||
| 测试工程师 | 测试执行 | 用例/BUG/测试报告管理 |
|
||||
| 运维工程师 | 系统保障 | 考核项（巡检/备份）留痕 |
|
||||
| IT 经理 | 考核人 | 9 岗位月度考核自动产出 [SRC-002] |
|
||||
| AI 框架 | 数据生产方（系统角色） | PRD/工作量指数/审查报告/工作日志的上传通道 [SRC-001] |
|
||||
|
||||
### 3.2 关键使用场景
|
||||
|
||||
| 场景编号 | 场景描述 | 涉及角色 | 优先级 |
|
||||
|---|---|---|---|
|
||||
| S-001 | 需求全生命周期流转（SOP 14 步，数据落系统） | 业务/产品/开发/测试/AI框架 | P0 |
|
||||
| S-002 | AI 框架上传：工作量指标（saveOrUpdate 接口）、任务拆分（aiBatchAdd）、审查报告/工作日志（MD 文件经 /common/upload） | AI框架 | P0 |
|
||||
| S-003 | 月度绩效考核：指标自动统计、9 岗位报表 | IT经理/项目经理 | P1 |
|
||||
| S-004 | 大型需求（指数>20）五类文档齐备检查 | 项目经理 | P1 |
|
||||
|
||||
### 3.3 价值链路
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[业务部门] -->|用户需求| B[IT工作台]
|
||||
C[AI框架] -->|PRD/工作量指数/审查报告/工作日志| B
|
||||
B --> D[研发任务/测试/BUG]
|
||||
D --> E[绩效统计]
|
||||
E --> F[9岗位月度考核]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 需求范围
|
||||
|
||||
### 4.1 范围内（In Scope）
|
||||
|
||||
| 模块 | 功能 | 分期 |
|
||||
|---|---|---|
|
||||
| 数据模型 | zt_story_expand 加 AI 参与率列（zt_task_extend 已砍：AI 工时入 zt_task.estimate，指数豁免，见 FR-007/CHG-019） | 一期 |
|
||||
| 上传接口 | 任务批量提交 aiBatchAdd（含开发/测试任务+AI指标）；MD 文件上传复用 /common/upload + uploadBind（审查报告/工作日志/测试报告/纪要）；含框架侧触发挂钩（upload_md.py） | 二期 |
|
||||
| 页面展示 | 需求详情 AI 区块、**需求讨论会议 tab（补充⑦）**、代码审查报告/工作日志按钮+MD 在线查看、会议纪要附件+纪要 MD 在线查看、测试报告入口 | 二期 |
|
||||
| 绩效统计 | IZtCountService 接入工作量指数；9 岗位考核报表；大型需求文档齐备自动核查（FR-014） | 三期 |
|
||||
|
||||
### 4.2 范围外（Out of Scope）
|
||||
|
||||
1. AI 工作量指数/AI 参与率的计算口径与算法（AI 框架侧职责）
|
||||
2. 禅道老表（zt_story/zt_task/zt_bug 等）结构变更
|
||||
3. 考核权重与公式的管理制度调整（以 SRC-002 为准）
|
||||
4. 原型与移动端（skip_flags.prototype=true，用户 2026-07-23 确认暂缓）
|
||||
|
||||
### 4.3 假设与依赖
|
||||
|
||||
| 依赖项 | 类型 | 状态 | 负责方 |
|
||||
|---|---|---|---|
|
||||
| AI 框架上传报文格式 | 内部 | 部分确认（demand-assessor 报文可参照） | AI 框架 |
|
||||
| 生产 DB 变更窗口 | 内部 | 待确认 | 运维 |
|
||||
| SRC-002 考核公式最终版 | 内部 | 已确认（xlsx 为准） | IT 经理 |
|
||||
| zentao 需求单（本 PRD 存档 + W 值补登） | 内部 | **定稿时用户建单并提供 ID → AI 一次完成：W 提交（/zt-story-expand，按 CHG-014 后重估值，原 10.2 已过时）+ PRD 定稿版附件上传（/common/upload）** | 用户 + AI |
|
||||
|
||||
---
|
||||
|
||||
## 5. 整体方案介绍
|
||||
|
||||
### 5.1 方案概述
|
||||
|
||||
最大复用现有 zt_* 功能（需求/任务/BUG/工时/会议/验收链已全），缺口分三类补齐：①需求级 AI 指标加列（zt_story_expand.ai_participation_rate；任务级工时直接入 zt_task.estimate，指数豁免 CHG-019）；②AI 文档（PRD/纪要/审查报告/工作日志/测试报告）走 MD 文件附件通道（CHG-014，FileTypes 扩展）；③绩效统计接入既有 AI 指标。AI 侧数据一律「框架算、平台存」。
|
||||
|
||||
### 5.2 核心机制/策略
|
||||
|
||||
- 扩展表模式：AI 类数值指标进扩展表（zt_story_expand 加列），不碰禅道老表；任务级 AI 工时直接用 zt_task.estimate 标准字段（zt_task_extend 已砍，CHG-019）；AI 文档不进表，走 MD 附件（CHG-014）
|
||||
- 上传通道：saveOrUpdate 幂等模式（按业务键有则更新），参照 /zt-story-expand
|
||||
- 五类文档（大型需求强制）：测试用例=zt_case 复用；测试报告=zt_file(testReport)；AI文档更新记录/代码审查报告/工作日志=**MD 文件附件**（FileTypes: aiCodeReview/aiWorkLog，不建结构化表）[SRC-002][CHG-014]
|
||||
|
||||
### 5.4 字段新增/调整
|
||||
|
||||
| 字段 | 表 | 类型 | 说明 | 证据 |
|
||||
|---|---|---|---|---|
|
||||
| ai_participation_rate | zt_story_expand | varchar(16) | AI 参与率（只存不算，口径待定） | SRC-001 |
|
||||
| aiCodeReview / aiWorkLog / testCase / testReport / testReportSubmit | FileTypes 枚举（二期） | — | 审查报告/工作日志/测试用例（下载）/测试报告（供下载）/测试报告（提交）附件类型（MD 文件方案，不建表） | CHG-014/021/022 |
|
||||
| url | zt_file（二期加列） | varchar(512) | 附件访问链接：pathname=存储路径，url=可访问地址（在线查看/外链取用）；zt_file 为禅道原生表，加列属破例（沿用 zt_* 自研扩展字段惯例） | CHG-018 用户指定 |
|
||||
| url | zt_meeting（二期加列） | varchar(512) | 会议纪要 MD 访问链接（直取，不绕 zt_file 反查）；多份纪要时**存最新一份**（每次上传刷新），历史份仍走 zt_file 列表 | CHG-020 用户指定 |
|
||||
| prd_url / code_review_url / work_log_url / test_case_url / test_report_download_url / test_report_submit_url / test_other_url | zt_story（二期加 7 列 url） | varchar(512)×7 | 研发需求文档链接（各存最新一份，上传刷新）：PRD/审查报告/工作日志/**测试用例下载/报告模版下载/模版填完提交/其他测试文档**；zt_story 为禅道核心表，加列属破例（用户拍板） | CHG-021/022/025 用户指定 |
|
||||
| code_review_status | zt_story（二期加列） | varchar(16) | **审查状态：pass/reject/NULL（未审）**——审查结果原只在 MD 内容里系统不可查，加此字段支撑：卡点强制（未 pass 禁提测试报告）、列表筛选、状态展示；上传审查报告时由报文参数或 MD 头部「结果：pass/reject」解析写入 | CHG-023 用户指出 |
|
||||
|
||||
### 5.5 方案对比与取舍
|
||||
|
||||
| 方案 | 优点 | 缺点 | 结论 |
|
||||
|---|---|---|---|
|
||||
| A：扩展表模式（数值指标） | 不碰老表、升级兼容、有先例 | 关联查询多一层 | ✅ 采用 |
|
||||
| D：MD 文件流（AI 文档） | 不建表、人可直接阅读、上传即看 | 结构化取数弱（需 MD 头部约定） | ✅ 采用（CHG-014 用户拍板） |
|
||||
| B：zt_task 直接加列 | 查询简单 | 污染禅道老表、违背既定先例 | ❌ 放弃 |
|
||||
| C：验收指标结构化新表 | 可机读 | 富文本 verify 已够用，过度设计 | ❌ 放弃（后续按需） |
|
||||
|
||||
### 5.6 ID 流转约定（上传关联的钥匙）
|
||||
|
||||
1. **storyId 先有单后有号**：研发需求单在 zentao 创建（人从用户需求详情页「添加研发需求」；后续可选 AI 创建需求接口）→ ID 由 zentao 分配
|
||||
2. **ID 回填**：storyId 写入 PRD 文档信息表「关联需求ID」字段（demand-assessor 取数规则已支持"优先从 PRD 提取需求ID"）+ 框架工作区 session 记录
|
||||
3. **上传关联**：接口以 storyId 为主键（/zt-story-expand、/zt-task/aiBatchAdd）；MD 文件经 zt_file.objectID 关联需求、objectType 区分类型（aiCodeReview/aiWorkLog/testReport/meeting）
|
||||
4. **taskId 由 zentao 返回**：aiBatchAdd 创建任务后响应携带 taskIds，框架记录后用于任务级关联；审查/日志/指标报文仅需 storyId（taskId 可选）
|
||||
5. 本流程自身即实例：定稿日用户建单提供 ID → W 提交+PRD 附件上传（见 4.3 定稿日约定）
|
||||
6. **多人协作前提**：框架为多人多机使用——ID 的共享载体是 **PRD 文档**（存 zentao 附件，全员可读），个人工作区不作为共享来源；多人并发协作由 zentao 状态机约束；AI 上传统一挂「ai」账户与具体使用者解耦；**上传接口鉴权在多人环境下为必决项**（二期立项前须定：签名/内部 token，不得裸连）
|
||||
|
||||
---
|
||||
|
||||
## 6. 需求内容
|
||||
|
||||
### 6.1 端/渠道覆盖矩阵
|
||||
|
||||
| 端/渠道 | 是否覆盖 | 核心差异点 | 涉及 FR | 证据 |
|
||||
|---|---|---|---|---|
|
||||
| 管理端 Web（Vue2） | ✅ | 唯一用户端；新增 AI 区块/附件入口 | FR-002/004/008/010/011 | ZT:codes/web_zentao |
|
||||
| API（AI 框架上传） | ✅ | 数值=saveOrUpdate 幂等；文档=/common/upload+uploadBind；任务=aiBatchAdd | FR-004/006/007/008/010/011 | ZT:controller/ZtStoryExpandController.java:23 |
|
||||
| 商户/小程序/H5/C端 | ❌ | 内部系统，无此类端 | — | — |
|
||||
|
||||
### 6.2 功能需求列表（FR）
|
||||
|
||||
> 分期标注：①=一期（数据模型）②=二期（接口+页面）③=三期（绩效）。复用=现有功能已满足，无开发量。
|
||||
|
||||
#### FR-001：用户需求管理（提出/评审/激活）— 复用+②补写
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：业务部门、产品经理
|
||||
- **触发**：业务部门提交用户需求
|
||||
- **需求**：系统 SHALL 支持用户需求创建、评审（userReview）、激活、关闭全流程 [ZT:controller/ZtStoryUserController.java:157]
|
||||
- **业务规则**：评审通过即激活（现状无独立激活端点）；激活时间须落库（现状 activateddate 死字段，②补写 [ZT:entity/ZtStoryUser.java:153]）；**审批时间口径 = revieweddate**（userReview 通过时写入，已有 [ZT:ZtStoryUserServiceImpl.java:564]；approveddate 字段闲置，语义由 revieweddate 覆盖）
|
||||
- **边界**：评审不通过→关闭并记录原因
|
||||
- **证据**：[SRC-001][ZT:service/impl/ZtStoryUserServiceImpl.java:562-578] ｜ **AC**：待 Round 2 批量生成
|
||||
|
||||
#### FR-002：需求讨论会与纪要 MD（上传/在线查看）— ②
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：产品经理、项目经理
|
||||
- **触发**：SOP「初次讨论/评审讨论」节点 [SRC-001]
|
||||
- **需求**：系统 SHALL 支持会议创建（时间/参与人/纪要/关联需求）；**会议纪要 MD 文件：可多次上传（多份）、页面内在线查看（无需下载）；展示操作人（上传人）、操作时间、会议人（参与人）**（用户补充①，2026-07-23）
|
||||
- **业务规则**：
|
||||
1. FileTypes.meeting 附件绑定后端已就绪 [ZT:ZtMeetingServiceImpl.java:159]；前端渲染上传组件（已引入未渲染）
|
||||
2. .md 附件点击在线渲染 Markdown；其他格式（PDF/图片）维持下载
|
||||
3. 多份纪要按上传时间排列；操作人/操作时间取 zt_file.addedBy/addedDate，会议人取 zt_meeting.users
|
||||
4. **用户需求详情页右侧 tabs 新增「需求讨论会议」**（补充⑦）：列出 zt_meeting.storyIds 含本需求的会议（主题/类型/时间/参与人），点击跳会议详情
|
||||
5. zt_meeting 加 `url` 字段（二期）：存最新一份纪要 MD 的访问链接，查看直取；历史多份仍走 zt_file 列表（CHG-020）
|
||||
- **证据**：[SRC-001][ZT:controller/ZtMeetingController.java][用户补充①]
|
||||
|
||||
#### FR-003：PRD 文档管理 — 复用+①日志项
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：产品经理、AI 框架
|
||||
- **触发**：AI 生成初版/最终版 PRD [SRC-001]
|
||||
- **需求**：PRD/原型图以附件承载于需求（FileTypes.story/userStory）；每一版 PRD 生成时间记入 AI 工作日志 MD（prd_version 类内容，②FR-011）
|
||||
- **证据**：[SRC-001][ZT:controller/CommonsController.java:71]
|
||||
|
||||
#### FR-004：需求级 AI 工作量指标 — ①字段+②展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（上传）、产品经理（查看）
|
||||
- **触发**：最终版 PRD 定稿后 AI 评估 [SRC-001]
|
||||
- **需求**：系统 SHALL 存储并展示功能单元数量、单元业务复杂度、技术复杂度系数、AI 效率系数、**AI 参与率（新增）**、工作量指数
|
||||
- **业务规则**：上传通道 /zt-story-expand/saveOrUpdate 已有；zt_story_expand 加 ai_participation_rate 列；需求详情页新增 AI 指标区块（②）
|
||||
- **证据**：[SRC-001][ZT:entity/ZtStoryExpand.java]
|
||||
|
||||
#### FR-005：验收标准与测试用例管理 — 复用
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：产品经理、测试工程师
|
||||
- **需求**：验收标准以 zt_storyspec.verify 富文本承载；测试用例 zt_case + 评审链（story-case）复用 [ZT:entity/ZtStoryspec.java:29]
|
||||
- **证据**：[SRC-001] ｜ **AC**：复用无需新增
|
||||
|
||||
#### FR-006：研发任务管理（拆分/分配/工时）— 复用+②AI 提交
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：项目经理、开发/测试工程师、AI 框架
|
||||
- **需求**：任务创建双通道——①人工创建（现有拆分/批量拆分/Excel 导入，保留不变）；②AI 框架批量提交（②期新增接口）：AI 拆分结果（任务清单、类型、建议指派人、AI 评估工时/指数）提交后直接建成任务 [SRC-001]
|
||||
- **业务规则**：
|
||||
1. **AI 上传任务的创建人 = 系统专用账户「ai」**（zt_user 新建 account=ai 的用户，与真人区分，便于追溯任务来源）— 用户指定
|
||||
2. 任务类型覆盖**开发任务与测试任务**：测试任务 type=test，指派测试人员（对应 SRC-001 测试任务数据项：测试人员、测试开始/结束时间）
|
||||
3. AI 评估工时随任务提交写入 `zt_task.estimate`（标准字段；任务级指数豁免，FR-007/CHG-019）
|
||||
4. **AI 提交任务初始状态 = 未开始（wait），后续走现有任务流程**（开始→完成→完工审批→关闭），与人工创建任务完全一致，无特殊状态（用户确认）
|
||||
- **证据**：[SRC-001][ZT:controller/ZtTaskController.java]
|
||||
|
||||
#### FR-007：任务级 AI 工时与指数 — ①工时入 estimate，指数豁免
|
||||
|
||||
- **优先级**：P2 ｜ **角色**：AI 框架（上传）
|
||||
- **触发**：AI 拆分任务并评估每个任务工时 [SRC-001]
|
||||
- **需求（CHG-019 用户拍板）**：**不建 zt_task_extend**——AI 评估工时随 aiBatchAdd 写入 `zt_task.estimate`（标准字段，无需扩展表）；**AI 评估任务工作量指数暂不落地**（SOP 数据项豁免：当前无消费方——绩效取数用需求级指数 zt_story_expand；三期如需「AI 估算准确性」分析再恢复）
|
||||
- **证据**：[SRC-001][用户拍板 2026-07-23]
|
||||
|
||||
#### FR-008：AI 代码审查报告（MD 文件）— ②上传+展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（生成/上传）、开发工程师、项目经理
|
||||
- **触发**：需求下所有开发任务完工后（框架内自动/框架外负责人手动）；不通过则回炉重审 [SRC-001]
|
||||
- **需求**：代码审查报告为 **MD 文件**；研发需求详情页新增「代码审查报告」按钮——支持上传 MD（可多份、按轮次）与在线查看；FileTypes 新增 aiCodeReview。**不建结构化表**（用户定 2026-07-23）
|
||||
- **业务规则**：
|
||||
1. 触发时机=该需求全部开发任务完工；通过前不得流转测试（SOP 卡点）[SRC-001]
|
||||
2. 每轮审查完成即上传一个 MD（含未通过轮次，文件名建议含轮次标识）；初审/复审扣分依赖逐轮文件 [SRC-002]
|
||||
3. 大型需求（指数>20）强制 [SRC-002]；FR-014 齐备判定=zt_file(objectType=aiCodeReview)
|
||||
4. 异议由技术负责人复核，复核结论补充上传
|
||||
5. 代码质量扣分取数：建议 MD 头部约定格式（如「严重：N／错误：N」）供系统解析 [建议，三期前确认]；不解析则该项半自动（人读数录入）
|
||||
6. **审查状态字段 code_review_status（pass/reject/NULL）随上传写入 zt_story**（uploadBind 解析报文参数或 MD 头部结果）；用途：未 pass 时「提交测试报告」按钮禁用（SOP 卡点系统级落地，CHG-023）、列表筛选、状态展示
|
||||
- **证据**：[SRC-001][SRC-002][用户定]
|
||||
|
||||
#### FR-009：测试任务与 BUG 管理 — 复用
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：测试工程师、开发工程师
|
||||
- **需求**：BUG 全流程（提交/指派/修复/复测/验收 bugYs）复用 [ZT:controller/ZtBugController.java]
|
||||
- **证据**：[SRC-001]
|
||||
|
||||
#### FR-010：测试报告管理 — ②
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：测试工程师、AI 框架
|
||||
- **触发**：测试完成提交测试报告 [SRC-001]；大型需求强制 [SRC-002]
|
||||
- **需求**：测试类文档四个字段（CHG-025 用户明确）：**测试用例**（FileTypes.testCase，AI 生成供下载）；**测试报告·模版下载**（FileTypes.testReport，AI 生成的模版）；**测试报告·模版填完提交**（FileTypes.testReportSubmit，填完上传，可多次补充）；**其他测试文档**（FileTypes.testOther，其他文档上传位）——均挂研发需求，zt_story 对应 4 个 url 字段各存最新一份
|
||||
- **业务规则**：FR-014 齐备判定：《需求测试报告》=zt_file(testReportSubmit)、《需求测试用例》=zt_case 或 zt_file(testCase)；结构化用例=zt_case 复用（执行/统计）
|
||||
- **证据**：[SRC-001][ZT:entity/ZtTesttask.java（report 为死字段）][用户确认 Q3/Q4]
|
||||
|
||||
#### FR-011：AI 工作日志（MD 文件）— ②上传+展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（生成/上传）、项目经理（查看）
|
||||
- **触发**：SOP 各节点（PRD 版本/工作量评估/架构设计/架构评审/任务拆分/门禁检查/代码审查/文档更新）[SRC-001]
|
||||
- **需求**：工作日志为 **MD 文件**；研发需求详情页新增「工作日志」按钮——上传 MD（可多份）与在线查看；FileTypes 新增 aiWorkLog。**不建结构化表**（用户定 2026-07-23）
|
||||
- **业务规则**：
|
||||
1. 事件产生即上传（不补传）；8 类事件在 MD 中分类记录（或按类分文件）
|
||||
2. 框架侧挂钩：各技能节点产出 MD 后经 /common/upload 上传（或人工按钮上传），二期交付含挂钩
|
||||
3. FR-014 齐备判定=zt_file(objectType=aiWorkLog)；《AI 文档更新记录》同通道（doc_update 类记录）
|
||||
- **证据**：[SRC-001][用户定]
|
||||
|
||||
#### FR-012：工作量指标完成率统计 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：IT 经理、项目经理
|
||||
- **需求**：IZtCountService 接入 zt_story_expand.workloadIndex，按 SRC-002 公式产出完成率 = Σ(月度工作量指数) ÷ (团队可用工作天数×5)
|
||||
- **业务规则**：测试人员不计入工作量产出方 [SRC-002]
|
||||
- **证据**：[SRC-002][ZT:service/impl/IZtCountService.java（现不消费 AI 指标）]
|
||||
|
||||
#### FR-013：九岗位绩效考核报表 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：IT 经理
|
||||
- **需求**：按 SRC-002 九岗位 sheet 的权重/公式/评分标准，产出月度考核报表（版本计划完成率、线上 Bug 率、Bug 密度、缺陷检出率等；文档齐备核查由 FR-014 承担）
|
||||
- **业务规则**：大型需求判定=AI 评估工作量指数>20；普通/重大 Bug 分级定义以 SRC-002 为准
|
||||
- **证据**：[SRC-002]
|
||||
|
||||
#### FR-014：大型需求文档齐备自动核查 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：系统（自动）、项目经理（月度确认）、技术负责人（异议复核）
|
||||
- **触发**：每月考核周期；大型需求=AI 评估工作量指数>20 [SRC-002]
|
||||
- **需求**：系统 SHALL 自动生成「大型需求 × 五类文档」齐备清单，按规则自动计算缺失扣分并写入 zt_month_score；提供异议复核入口与项目经理月度确认
|
||||
- **业务规则**：
|
||||
1. 五类文档判定来源：《需求测试用例》=zt_case 有无关联用例；《需求测试报告》=zt_file(testReport) 附件（②期）；《AI代码审查报告》=zt_file(aiCodeReview) 附件（②期 MD）；《AI工作日志》=zt_file(aiWorkLog) 附件（②期 MD）；《AI项目文档更新记录》=zt_file(aiWorkLog) 附件中 doc_update 类内容（②期 MD）
|
||||
2. 考核只判「缺失」不判内容质量：每缺失一份扣 2 分，扣完截止 [SRC-002]
|
||||
3. 内容争议不走人工抽检：异议由技术负责人复核并留痕
|
||||
4. 结果落库 zt_month_score（account+月份+scopeJson 明细，现有表复用，不建新表）[ZT:entity/ZtMonthScore.java]
|
||||
- **证据**：[SRC-002][ZT:entity/ZtMonthScore.java]
|
||||
|
||||
### 6.3 SOP 步骤 × 现有工作流映射（代码级）
|
||||
|
||||
现有系统已实现的研发需求工作流主线：`zt_story.status`（reviewing/active/draft/finished/closed）+ `zt_story.stage`（wait→projected→developing→developed→testing→tested→released→verified，含自研 productWaitVerified/productVerified 产品内部验收）[ZT:enums/StoryStageEnums.java]；前端「需求的一生」基于 zt_action 动态流展示。SOP 14 步逐步映射如下：
|
||||
|
||||
| SOP 步骤 [SRC-001] | 现有工作流节点（证据） | 结论 |
|
||||
|---|---|---|
|
||||
| 1 业务部门提用户需求 | `/zt-story-user/addStory` 创建用户需求，openeddate 落库 [ZT:ZtStoryUserServiceImpl.java:135] | 复用 |
|
||||
| 2 评审需求、激活 | `/zt-story-user/userReview` 全员通过→status=active + revieweddate [ZT:ZtStoryUserServiceImpl.java:562]；无独立激活端点，activateddate 死字段 | 复用 + ②补写激活时间（FR-001） |
|
||||
| 3 初次讨论、会议纪要 | `/zt-meeting/add`（type=story，storyIds 关联用户需求，result=纪要） [ZT:ZtMeeting.java:72-73] | 复用 + ②附件 UI（FR-002） |
|
||||
| 4 AI 生成初版 PRD+原型 | 附件通道 `/common/upload` 绑定需求（FileTypes.userStory） [ZT:CommonsController.java:71] | 通道复用；版本时间记 AI 工作日志 MD（②FR-003/011，zt_file(aiWorkLog)） |
|
||||
| 5 评审讨论、偏差回炉 | 会议迭代 + 附件更新；偏差判断为人工环节，无系统流转 | 复用（系统外判断） |
|
||||
| 6 生成最终版 PRD | 同步骤 4 | 同上 |
|
||||
| 7 AI 评估工作量→生成研发需求+指定完成时间 | 前端「添加研发需求」按钮从用户需求建 zt_story；指标经 `/zt-story-expand/saveOrUpdate` 上传；完成时间=zt_story.planEndDate/endDate | 复用 + ①AI参与率加列（FR-004） |
|
||||
| 8 AI 生成架构设计/验收指标/测试用例 | 验收标准=zt_storyspec.verify 富文本 [ZT:ZtStoryspec.java:29]；用例=zt_case + 评审（/zt-story-case）；架构文档=附件 | 复用（FR-005） |
|
||||
| 9 评审确认各文档 | 用例评审链（story-case psUser/psDate/status）；文档评审为人工 | 复用 |
|
||||
| 10 AI 拆分任务/评估工时/分配 | **双通道（FR-006）**：②AI 批量提交接口（创建人=ai 账户，覆盖开发任务+测试任务 type=test）；人工拆分/批量/Excel 创建保留；AI 工时入 zt_task.estimate（指数豁免，FR-007/CHG-019） | 复用 + ②新增接口 |
|
||||
| 11 开发实施 | 任务生命周期 startTask→finishTask→approval 完工审批；工时 `/zt-effort/batchAdd` 回写 consumed/left [ZT:ZtEffortServiceImpl.java:41] | 复用（FR-006） |
|
||||
| 12 开发完成→AI 代码审查（不过回炉） | **系统无此节点**（全库零命中）；回炉可借任务重开/bug 流程 | ②MD 文件方案（FR-008）：FileTypes.aiCodeReview + 按钮上传+在线查看 |
|
||||
| 13 测试/BUG/复测/测试报告 | `/zt-story/testSubmitVerified` 测试提交 [ZT:ZtStoryController.java:238]→zt_case execCase 执行→zt_bug 全流程→bugYs 验收 [ZT:ZtBugServiceImpl.java:463] | 复用 + ②测试报告 testReport 附件（FR-010） |
|
||||
| 14 报告→更新AI文档→AI工作日志→结束 | 内部验收链：storyProductUserYs [ZT:ZtStoryController.java:248]→发布 zt_release→storyYs 验收（ysFlag/ysDate→status=finished，联动用户需求完成）[ZT:ZtStoryServiceImpl.java:2119] | 复用验收链 + ②AI 工作日志 MD 文件（FR-011，FileTypes.aiWorkLog + 按钮上传+在线查看） |
|
||||
|
||||
**映射结论**：SOP 14 步中 11 步可由现有工作流节点承载；缺口集中在步骤 12（AI 代码审查）与步骤 4/14 的 AI 侧留痕（工作日志）——按 CHG-014 走 MD 文件附件方案（二期）；步骤 10 的任务级 AI 工时直接入 zt_task.estimate（指数豁免 CHG-019）——一期仅余 zt_story_expand 加 1 列；步骤 2/3/13 的附件与时间补写属二期小改。
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据与埋点
|
||||
|
||||
### 7.1 数据模型（建议结构，一期交付 DDL）
|
||||
|
||||
```sql
|
||||
-- 【CHG-014 已取消】zt_ai_code_review / zt_ai_work_log 两表不建——
|
||||
-- AI 审查报告与工作日志改为 MD 文件附件方案（FileTypes: aiCodeReview/aiWorkLog，见 FR-008/011）
|
||||
-- 【CHG-019 已取消】zt_task_extend 不建——AI 工时入 zt_task.estimate，任务级指数豁免（见 FR-007）
|
||||
|
||||
-- 一期仅此一项：zt_story_expand 加列（可重入）
|
||||
ALTER TABLE `zt_story_expand`
|
||||
ADD COLUMN `ai_participation_rate` VARCHAR(16) DEFAULT NULL COMMENT 'AI参与率（只存不算，口径待定）' AFTER `ai_efficiency_coefficient`;
|
||||
```
|
||||
|
||||
### 7.3 数据口径
|
||||
|
||||
| 指标名 | 计算方式 | 来源 | 备注 |
|
||||
|---|---|---|---|
|
||||
| 工作量指标完成率 | Σ(月度需求工作量指数) ÷ (团队可用工作天数×5) | zt_story_expand.workloadIndex | 测试人员不计入产出方 [SRC-002] |
|
||||
| 版本计划完成率 | Σ(按时发布需求工时) ÷ Σ(所有需求工时) ≥95% | zt_release/zt_task | [SRC-002] |
|
||||
| 线上 Bug 率 | Σ(当月上线需求线上Bug数) ÷ Σ(上线需求开发工时) ≤5‰ | zt_bug/zt_task | 普通/重大分级 [SRC-002] |
|
||||
| Bug 密度 | Σ(当月完成任务Bug数) ÷ Σ(完成任务分配工时) ≤15% | zt_bug/zt_task | 连续3月达标可返还 [SRC-002] |
|
||||
| 缺陷检出率 | (普通Bug×1+重大Bug×5) ÷ 测试需求开发工时 >20% | zt_bug | [SRC-002] |
|
||||
| 大型需求判定 | AI 评估工作量指数 > 20 | zt_story_expand | 触发五类文档强制 [SRC-002] |
|
||||
| 任务及时完成率 | Σ(按时完成任务的分配工时) ÷ Σ(所有任务的分配工时) =100% | zt_task | 开发/UI [SRC-002] |
|
||||
| 测试计划及时完成率 | Σ(按时完成的测试工作分配工时) ÷ Σ(所有测试工作分配工时) =100% | zt_task(type=test) | 测试；zt_testtask 为只读遗留不取 [SRC-002] |
|
||||
| 项目准时率 | Σ(当月准时上线需求量) ÷ Σ(当月规划上线需求总量) ≥95% | zt_story | 产品经理 [SRC-002] |
|
||||
| 月度达标工时（饱和度基准） | 团队总工作天数 × 5 ÷ 开发人员数（后端+前端） | zt_effort+考勤 | 开发；测试人员不计入产出方 [SRC-002] |
|
||||
| 产品缺陷率 | Σ(当月上线需求线上Bug数) ÷ Σ(上线需求开发分配工时) ≤5‰ | zt_bug/zt_task | 与线上Bug率同口径 [SRC-002] |
|
||||
|
||||
**口径待确认（5 项，三期开工前须与 IT 经理核对）**：
|
||||
1. **总分算法**：xlsx 各项仅见权重与「=100%得满分」规则，未明写总分公式；本 PRD 按「每项 0~100 分 × 权重求和」理解 [ASSUMPTION]
|
||||
2. **线上 Bug 率单位**：xlsx 原文「×100% ≤5‰」自相矛盾（百分数 vs 千分号），本 PRD 按 ‰ 理解 [待确认]
|
||||
3. **缺陷检出率申诉**：无 Bug 检出可申诉不扣分、上线后发现加倍扣——需人工裁定流程，系统只留申诉入口与记录 [待确认]
|
||||
4. **普通/重大 Bug 映射**（数据盘点新发现）：SRC-002 业务定义（影响上游回传/财务/大面积）如何映射 zt_bug.severity(1-4)/type，无规则则相关 5 项指标（线上Bug/缺陷率/检出率等）无法自动分级 [待确认]
|
||||
5. **产品助理「需求部门及时验收」数据链**（新发现）：zt_story_user 验收字段（ysFlag/ysDate）为闲置字段、无端点写入，验收时间链断裂；需二期补写或改走 zt_story 侧验收时间 [待确认]
|
||||
|
||||
### 7.4 统计/埋点需求
|
||||
|
||||
无新增埋点；AI 侧事件以 MD 文件经 zt_file 落地（zt_file.addedDate=入库时间，事件发生时间记于 MD 内容中）。
|
||||
|
||||
### 7.5 绩效计算模型（FR-012/013/014 完整规则，SRC-002 全量映射）
|
||||
|
||||
**通用规则** [SRC-002]：
|
||||
1. 加权扣分制：每项满分 100×权重，项内扣分「扣完截止」；总分=Σ各项
|
||||
2. 普通 Bug=程序/数据/样式明显错误，不影响业务运营；重大 Bug=影响上游回传数据、财务数据、线上大面积影响
|
||||
3. 大型需求=AI 评估工作量指数>20；工作量产出方统计不含测试人员
|
||||
4. 自动化标注：✅=系统可算（数据源已在系统/一二期落地）；🔶=半自动（系统出数+人工裁定）；❌=人工评分
|
||||
|
||||
#### 项目经理
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化/数据来源 |
|
||||
|---|---|---|---|
|
||||
| 需求PRD工作量指标完成率 | 0.2 | =100%满分；每减1%扣1分 | ✅ zt_story_expand.workloadIndex |
|
||||
| 团队工作量指标完成率 | 0.3 | =100%满分；每减2%扣1分 | ✅ 同上 |
|
||||
| 版本计划完成率 | 0.1 | ≥95%满分；每减1%扣2分 | ✅ zt_release/zt_task 工时 |
|
||||
| 线上Bug | 0.1 | ≤5‰满分；普通Bug每个扣3分、重大扣10分 | ✅ zt_bug |
|
||||
| 文档齐备（大型需求五类） | 0.1 | 每缺失一份扣2分 | ✅ FR-014 自动核查 |
|
||||
| 问题管理（《项目问题和处理》《系统运行问题和处理》） | 0.05 | 每遗漏一项扣1分 | ❌ 两类文档系统无承载，暂线下 [待确认：是否建承载] |
|
||||
| 系统运行稳定性 | 0.1 | 场景1扣10/场景2扣5/场景3满分 | 🔶 系统出故障记录+人工定级 |
|
||||
| 专业技能提升 | 0.05 | IT经理打分 | ❌ 人工 |
|
||||
|
||||
（项目经理-王宇航版：无 PRD 项；团队完成率 0.4；稳定性 0.2；其余相同）[SRC-002]
|
||||
|
||||
#### 产品经理 / 产品助理
|
||||
|
||||
| 评分事项 | 权重（经理/助理） | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 需求PRD工作量指标完成率 | 0.4 / 0.5 | 每减1%扣2分 | ✅ |
|
||||
| 团队工作量指标完成率 | 0.2 / — | 每减1%扣1分 | ✅ |
|
||||
| 需求部门及时验收（两周内） | — / 0.2 | 每超期一项扣5分 | ✅ zt_story_user 验收时间链 |
|
||||
| 项目准时率 | 0.1 / — | ≥95%满分；90~95%每减1%扣1分；<90%每减1%扣2分 | ✅ zt_story 上线时间 |
|
||||
| 产品缺陷率 | 0.15 / 0.15 | ≤5‰满分；普通3分/重大10分 | ✅ zt_bug |
|
||||
| 问题响应和解决 | 0.1 / 0.1 | 内部投诉扣5分/次、外部扣10分/次 | ❌ 人工登记 |
|
||||
| 主动性与责任感 | 0.05 / 0.05 | 上级按事例评 5/3/0 | ❌ 人工 |
|
||||
|
||||
#### 后端 / 前端开发工程师
|
||||
|
||||
| 评分事项 | 权重（后端/前端） | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 任务及时完成率 | 0.25 / 0.25 | =100%满分；95~100%每减1%扣1分；≤94%每减1%扣2分 | ✅ zt_task |
|
||||
| Bug密度 | 0.3 / 0.3 | ≤15%满分；每增1%扣3分；连续3月达标返还半年扣分 | ✅ zt_bug/zt_task |
|
||||
| 代码质量 | 0.1 / 0.1 | 后端：初审严重1处扣3分、错误超6处扣3分；复审严重1处扣5分、错误1处扣1分。前端：评审每发现1问题扣3分 | 🔶 后端=审查报告 MD 头部计数解析（约定格式，三期前确认；不解析则人工读数）；前端=评审记录 |
|
||||
| 设计文档质量 | 0.1 / — | 评审每发现1问题扣5分 | 🔶 评审记录系统无独立承载 [待确认] |
|
||||
| 工作量饱和度 | 0.2 / 0.3 | 月度达标工时=团队总工作天数×5÷开发人员数；每减1%扣2分 | ✅ zt_effort+考勤（IZtCountService 已有考勤接入） |
|
||||
| 不规范行为 | 0.05 / 0.05 | 迟到/失联/推诿/弄虚作假等着装扣1~5分 | ❌ 人工 |
|
||||
| 加分项 | — | 优质分享+5分/次；全月Bug<6且绩效≥95 +10分 | 🔶 分享人工认定，其余自动 |
|
||||
|
||||
#### 测试工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 测试计划及时完成 | 0.2 | 每减1%扣2分 | ✅ zt_task(type=test)/zt_effort |
|
||||
| 测试文档齐备 | 0.25 | 10%抽检，每缺一份扣3分 | ✅ FR-014 同机制（zt_case+zt_file(testReport)） |
|
||||
| 缺陷检出率 | 0.3 | (普通Bug×1+重大Bug×5)÷测试需求开发工时>20%满分；每减1%扣2分；无检出可申诉、上线后发现加倍扣 | ✅ zt_bug |
|
||||
| 线上Bug | 0.2 | 无满分；普通每个扣5分；重大该项0分 | ✅ zt_bug |
|
||||
| 不规范行为 | 0.05 | 同开发 | ❌ 人工 |
|
||||
| 加分项 | — | 测试创新+5分；全月无Bug且≥95 +10分 | 🔶 |
|
||||
|
||||
#### UI 工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 任务及时完成 | 0.5 | =100%满分；90~100%得40分；<90%得0分 | ✅ zt_task |
|
||||
| 设计质量 | 0.4 | 6 维度评审（受众理解/布局/创意/交互建议/切图配合/审核严谨） | ❌ 人工评审 |
|
||||
| 不规范行为 | 0.1 | 同开发 | ❌ 人工 |
|
||||
| 加分项 | — | 工作量超平均每10%加2分；创新建议最高+10分 | 🔶 |
|
||||
|
||||
#### 运维工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 运维大项任务及时完成 | 0.2 | 及时完成率×20 | ✅ zt_yw* 运维任务表（现有） |
|
||||
| 系统运维监控（每周2次） | 0.15 | 缺一次扣3分 | ✅ zt_yw* 记录 |
|
||||
| 职场巡检（每周1次） | 0.1 | 缺一次扣5分 | ✅ 同上 |
|
||||
| 数据库备份（每项目每周全量） | 0.1 | 缺一个扣3分 | ✅ 同上 |
|
||||
| 其他运维工作 | 0.15 | 及时性与质量 | 🔶 人工 |
|
||||
| 系统稳定性 | 0.2 | 场景1扣10/场景2扣5/场景3满分/运维失误致故障该项0分 | 🔶 |
|
||||
| 不规范行为 | 0.1 | 含填报虚假任务扣5分 | ❌ 人工 |
|
||||
| 加分项 | — | 创新建议最高+10分 | 🔶 |
|
||||
|
||||
**落地说明**：✅ 项三期由 IZtCountService 自动产出；🔶 项系统出数、考核人裁定；❌ 项保留人工录入入口（zt_month_score.scopeJson 承载所有项）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 差异点清单（现状 vs 目标）
|
||||
|
||||
| 维度 | 现状 | 目标 | 影响范围 | 涉及 FR | 证据 |
|
||||
|---|---|---|---|---|---|
|
||||
| 数据结构 | AI 代码审查/工作日志/任务级指标无承载 | 1 加列（需求级 AI 参与率）+ FileTypes 扩展 3 类附件（MD 文件流）；任务级工时入 zt_task.estimate、指数豁免（CHG-019） | DB/附件 | FR-004/007/008/010/011 | 全库 grep 零命中 |
|
||||
| 口径 | 绩效不消费 AI 指标（孤岛） | IZtCountService 接入 workloadIndex | 统计层 | FR-012/013 | ZT:IZtCountService.java |
|
||||
| UI/交互 | 需求详情无 AI 区块；会议附件未渲染；测试报告无入口 | 详情页 AI 区块+附件渲染+报告入口 | 前端 3 处 | FR-002/004/008/010/011 | ZT:web_zentao 摸底 |
|
||||
| 数据完整性 | activateddate/approveddate 死字段 | 评审通过补写激活时间 | 用户需求流 | FR-001 | ZT:ZtStoryUser.java:153 |
|
||||
| 权限 | 无新增权限项设计 | 沿用 base_role 菜单权限（$userHasPermission） | — | 全部 | [ASSUMPTION] |
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险确认与应对
|
||||
|
||||
| 编号 | 风险 | 类型 | 等级 | 应对 |
|
||||
|---|---|---|---|---|
|
||||
| R-001 | 无迁移工具，DDL 手工执行 | 技术 | 中 | DDL 可重入+变更说明头；生产执行前备份评审 |
|
||||
| R-002 | 项目单测覆盖率<20%，回归无安全网 | 技术 | 中 | 新 Service 强制单测（正常+异常路径） |
|
||||
| R-003 | 上传接口无鉴权先例（saveOrUpdate 直连） | 技术/安全 | 中 | 二期前决策：沿用/签名/JWT |
|
||||
| R-004 | 考核公式与权重理解偏差 | 业务 | 中 | 三期开工前与 IT 经理逐 sheet 核对 SRC-002 |
|
||||
| R-005 | 一期仅数据模型，无可视成果 | 体验 | 低 | 已在分期中明示；二期即有页面产出 |
|
||||
|
||||
### 9.1 回滚策略
|
||||
|
||||
一期 DDL 为存量表加列，回滚=DROP 新列，不影响存量数据与功能。
|
||||
|
||||
---
|
||||
|
||||
## 10. 里程碑与发布计划
|
||||
|
||||
| 里程碑 | 交付物 | 时间 | 负责方 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| M0 需求确认 | PRD Final（本文档定稿） | 待定 | PM | 进行中 |
|
||||
| M1 一期：数据模型 | 1 项 DDL（zt_story_expand 加列）+实体加字段+回归测试（W≈1~2 人日，CHG-019 砍表后重估） | 定稿后 1~2 天 | Dev | 未开始 |
|
||||
| M2 二期：文件流+接口+页面 | aiBatchAdd+uploadBind+FileTypes 扩展+MD 渲染+页面清单（会议 tab/纪要 MD/需求详情 6 区块）+框架挂钩 | 立项时评估 | Dev | 未开始 |
|
||||
| M3 三期：绩效消费 | 完成率统计+9 岗位报表 | 立项时评估 | Dev | 未开始 |
|
||||
| M4 验收 | 对照本 PRD 与考核方案验收 | — | QA/IT经理 | 未开始 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 其他需求 / 备注
|
||||
|
||||
### 11.2 待后续决策事项
|
||||
|
||||
1. AI 上传接口鉴权策略（二期前）
|
||||
2. 绩效考核与现有 ZtMonthScore/ZtCountController 体系的关系：替换/并存/渐进（三期前，见 Q1-2）
|
||||
3. 验收指标是否结构化（当前结论：富文本够用，后续按需）
|
||||
|
||||
---
|
||||
|
||||
## 12. 证据映射表
|
||||
|
||||
| 章节 | 关键结论 | 证据 | 状态 |
|
||||
|---|---|---|---|
|
||||
| 1 背景 | 6/9 数据项可复用、3 类无承载、AI 指标孤岛 | ZT 代码摸底（2026-07-22，文件:行号） | ✅ |
|
||||
| 3 角色 | 9 岗位+业务方+AI框架 | [SRC-002] 9 sheet、[SRC-001] | ✅ |
|
||||
| 5 方案 | 扩展表模式 | zt_story_expand 先例 [ZT:entity/ZtStoryExpand.java] | ✅ |
|
||||
| 6 FR | 14 条 FR 与 SOP 环节一一对应 | [SRC-001] 流程图+思维导图 | ✅ |
|
||||
| 7 数据模型 | 1 加列+FileTypes 扩展 3 类（MD 文件流 CHG-014；zt_task_extend 已砍 CHG-019） | [SRC-001] 数据模型节 | ✅ |
|
||||
| 7.3 口径 | 11 项指标公式+5 项待确认 | [SRC-002] | ✅ |
|
||||
| 2.2 北极星 | 完成率公式 | [SRC-002] | ✅ |
|
||||
| 3.1 角色诉求 | 各角色考核侧重点 | [SRC-002][ASSUMPTION 部分] | ⚠️ 部分假设 |
|
||||
|
||||
---
|
||||
|
||||
## 13. FR → AC 覆盖矩阵
|
||||
|
||||
| FR | 标题 | AC 数量 | 覆盖状态 |
|
||||
|---|---|---|---|
|
||||
| FR-001 | 用户需求管理 | 2（AC-001-1/2） | ✅ |
|
||||
| FR-002 | 需求讨论会与纪要 MD | 3（AC-002-1/2/3） | ✅ |
|
||||
| FR-003 | PRD 文档管理 | 2（AC-003-1/2） | ✅ |
|
||||
| FR-004 | 需求级 AI 工作量指标 | 3（AC-004-1/2/3） | ✅ |
|
||||
| FR-005 | 验收标准与测试用例管理 | 1（AC-005-1） | ✅ |
|
||||
| FR-006 | 研发任务双通道 | 3（AC-006-1/2/3） | ✅ |
|
||||
| FR-007 | 任务级 AI 工时（豁免） | 2（AC-007-1/2） | ✅ |
|
||||
| FR-008 | AI 代码审查报告 MD | 4（AC-008-1/2/3/4） | ✅ |
|
||||
| FR-009 | 测试任务与 BUG | 1（AC-009-1） | ✅ |
|
||||
| FR-010 | 测试类文档 4 字段 | 3（AC-010-1/2/3） | ✅ |
|
||||
| FR-011 | AI 工作日志 MD | 2（AC-011-1/2） | ✅ |
|
||||
| FR-012 | 工作量指标完成率统计 | 1（AC-012-1） | ✅ |
|
||||
| FR-013 | 九岗位绩效考核报表 | 2（AC-013-1/2） | ✅ |
|
||||
| FR-014 | 大型需求文档齐备自动核查 | 4（AC-014-1/2/3/4） | ✅ |
|
||||
|
||||
**合计：33 条 AC，覆盖 14/14 FR（100%），每 FR ≥1 正常 + ≥1 异常/边界/验证。** 详见 `outputs/acceptance.md`。
|
||||
|
||||
---
|
||||
|
||||
## 14. 系统资产引用
|
||||
|
||||
| 资产类型 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| CodeMap | assets/codemap/ | 已核查：属 fly-home-flow 项目，与本系统无关，不引用 |
|
||||
| DomainMap | assets/domainmap/ | 同上 |
|
||||
| 目标系统代码 | codes/zentao、codes/web_zentao | 直接摸底证据（[ZT:...]），2026-07-22 两轮探查 |
|
||||
|
||||
---
|
||||
|
||||
## 15. 参考资料与索引
|
||||
|
||||
- 来源索引：见 `materials_index.md`（SRC-001 SOP 流程、SRC-002 考核方案）
|
||||
- 代码证据：文中 [ZT:...] 标注（相对 codes/zentao/src/main/java/com/sa/zentao/ 或 codes/web_zentao/）
|
||||
|
||||
---
|
||||
|
||||
## 图表要求自检
|
||||
|
||||
- [x] mermaid 图 ×1（3.3 价值链路）
|
||||
- [x] 表格多张
|
||||
- [x] 端覆盖矩阵已填写（6.1）
|
||||
- [x] 差异点清单已填写（8）
|
||||
- [x] FR→AC 覆盖矩阵已填写（第 13 章，33 条 AC）
|
||||
@@ -0,0 +1,645 @@
|
||||
# AI开发SOP与绩效考核体系落地 PRD
|
||||
|
||||
## 0. 文档信息
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 版本 | v1.24 |
|
||||
| 状态 | 评审中 |
|
||||
| 作者 | pmassist-v3（AI） |
|
||||
| 创建日期 | 2026-07-23 |
|
||||
| 最后更新 | 2026-07-23 |
|
||||
| 适用范围 | IT 工作台（codes/zentao + codes/web_zentao）落地 AI 开发 SOP 全流程 + 9 岗位绩效考核，含三期分期 |
|
||||
|
||||
### 变更记录
|
||||
|
||||
| 版本 | 日期 | 变更编号 | 变更说明 | 影响章节 |
|
||||
|---|---|---|---|---|
|
||||
| v1.0 | 2026-07-23 | CHG-000 | 初稿 | 全部 |
|
||||
| v1.1 | 2026-07-23 | CHG-001 | 自查修正：表名 zt_story_extend→zt_story_expand（11处，以 ZtStoryExpandMapper.xml:34 为准）；ALTER 列名 aiEfficiencyCoefficient→ai_efficiency_coefficient；行号修正 ZtBugServiceImpl:478→463、CommonsController:70→71 | 1/4/5/6/7/12 章 |
|
||||
| v1.2 | 2026-07-23 | CHG-002 | 新增 FR-014 大型需求文档齐备自动核查（③期）：考核只判缺失不判内容（SRC-002 原文），人工抽检退化为月度确认+异议复核，结果复用 zt_month_score；FR-013 剔除文档抽检项；4.1 范围同步 | 4/6 章 |
|
||||
| v1.3 | 2026-07-23 | CHG-004 | 新增 7.5 绩效计算模型：SRC-002 九岗位算分规则全量结构化（通用规则+每岗位权重/扣分/加分表），逐项标注自动化程度（✅/🔶/❌）与数据来源；暴露 2 个待确认缺口（问题管理文档、设计文档质量评审的系统承载）；含 CHG-003 FR-008 规则细化（触发/每轮上传/卡点） | 6/7 章 |
|
||||
| v1.4 | 2026-07-23 | CHG-005 | 7.3 口径表补 5 个任务级公式（任务及时率/测试计划及时率/项目准时率/达标工时/产品缺陷率）；新增 3 项口径待确认（总分算法解读、线上Bug率单位矛盾、检出率申诉流程） | 7 章 |
|
||||
| v1.5 | 2026-07-23 | CHG-006 | FR-006 改双通道：AI 框架批量提交任务（②期接口）+ 人工创建保留；AI 上传任务创建人=专用账户「ai」（zt_user 新建）；覆盖开发+测试任务；AI 指标随任务写 zt_task_extend（后被 CHG-019 取消）；4.1 二期接口清单 2→3 个 | 4/6 章 |
|
||||
| v1.6 | 2026-07-23 | CHG-007 | FR-006 规则 4 定稿：AI 提交任务初始状态=未开始（wait），走现有任务流程，无特殊状态——上一版"是否需确认生效"待确认项关闭 | 6 章 |
|
||||
| v1.7 | 2026-07-23 | CHG-008 | FR-011 补框架侧触发挂钩：二期交付=zentao 接口+各技能上传挂钩两端（照 submit_assessment.py 模式，现状仅 workload_eval 已通，7 类挂钩净新增）；事件即传不补传；日志与内容表分工 | 4/6 章 |
|
||||
| v1.8 | 2026-07-23 | CHG-009 | SOP 符合性核查（用户要求）：流程 18 步、数据模型 6 类、提交动作 8 项全部有落点；修 2 处瑕疵——FR-001 补审批时间口径（=revieweddate，approveddate 闲置字段语义覆盖）、6.3 步骤 10 同步双通道最新规则 | 6 章 |
|
||||
| v1.9 | 2026-07-23 | CHG-010 | 新增 5.6 ID 流转约定：storyId 建单产生→回填 PRD「关联需求ID」+框架工作区→上传以此为键；taskId 由 aiBatchAdd 响应返回；响应示例含 taskIds | 5 章 |
|
||||
| v1.10 | 2026-07-23 | CHG-011 | 5.6 补多人协作前提（用户指出框架非单人使用）：ID 共享载体=PRD 文档非个人工作区；并发由 zentao 状态机约束；ai 账户与使用者解耦；**上传接口鉴权升级为二期必决项** | 5 章 |
|
||||
| v1.11 | 2026-07-23 | CHG-012 | ~~用户补充①：用户需求后台支持上传 MD 且在线查看 → FR-003 扩充~~（理解有误，见 CHG-013） | 4/6 章 |
|
||||
| v1.12 | 2026-07-23 | CHG-013 | 用户澄清补充①真实含义：**MD=会议纪要，在会议纪要页面操作**（可多次上传、在线查看、记录操作人/时间/会议人）→ 改正至 FR-002；FR-003 恢复原样；并给出补充②~⑧（待 4 项澄清后重写开发方案） | 4/6 章 |
|
||||
| v1.13 | 2026-07-23 | CHG-014 | **架构级变更（用户拍板）：AI 文档走 MD 文件流**——不建 zt_ai_code_review/zt_ai_work_log 两表；审查报告/工作日志=MD 文件，研发需求页按钮上传+在线查看；一期缩至 1 表（zt_task_extend）+1 列；FileTypes 扩展 aiCodeReview/aiWorkLog/testReport；FR-014 判定改 zt_file；Q1 维持 ID 回填约定、Q3 测试用例仅看/报告补传、Q4 报告挂研发需求 | 4/5/6/7/8 章 |
|
||||
| v1.14 | 2026-07-23 | CHG-015 | 同步性清扫（用户追问后自查）：修 5 处 CHG-014 残留——4.1 二期接口行、5.6 上传关联、7.4 埋点段、6.3 步骤 4、12 证据映射行；dev_plan 补回 aiBatchAdd 完整规格（原"见 v2.x"引用悬空） | 4/5/6/7/12 章 |
|
||||
| v1.15 | 2026-07-23 | CHG-016 | 全文核对（用户要求）：修 16 处过时/缺失——文档信息版本、2.1 目标截止（一期末→二期末）、2.3 约束、4.3 W=10.2 过时、5.1 方案概述、5.2 zt_ai_* 残留、5.5 补 MD 决策行、FR-003 log_type 残留、6.1 端矩阵、4.1 页面行补全、**补录遗漏的补充⑦（需求详情「需求讨论会议」tab 入 FR-002）**、7.3/7.5 zt_testtask 只读遗留误标、里程碑 M1/M2、证据映射 FR 数与公式数 | 0/2/4/5/6/7/10/12 章 |
|
||||
| v1.16 | 2026-07-23 | CHG-017 | 用户指出 3.2 S-002 未随 CHG-014 修正 → 场景补三种通道区分：指标=saveOrUpdate、任务=aiBatchAdd、审查/日志=MD 文件 | 3 章 |
|
||||
| v1.17 | 2026-07-23 | CHG-018 | 用户指定：zt_file 加 url 字段（varchar512，存 MD 访问链接，在线查看/外链取用；pathname=存储路径）→ 5.4 字段表补录；二期 DDL，uploadBind 写入、MdPreview 优先取用 | 5 章 |
|
||||
| v1.18 | 2026-07-23 | CHG-019 | **砍 zt_task_extend（用户拍板）**：evaluation_time 与 zt_task.estimate 冗余、ai_workload_index 无消费方 → 不建表；AI 工时入 zt_task.estimate；任务级指数豁免（SOP 数据项，三期按需恢复）；一期缩至 1 列（W≈1~2 人日）；FR-007 重写、7.1/4.1/5.x/6.3/8/10/12 章同步 | 4/5/6/7/8/10/12 章 |
|
||||
| v1.19 | 2026-07-23 | CHG-020 | 用户指定：zt_meeting 加 url 字段存纪要 MD 访问链接（直取不绕 zt_file）；多份纪要按"存最新一份"处理（上传刷新，历史份走 zt_file）→ 5.4 字段表补录、FR-002 规则补充 | 5/6 章 |
|
||||
| v1.20 | 2026-07-23 | CHG-021 | 用户指定：zt_story 加 5 个文档 url 字段（prd/code_review/work_log/test_report/test_case，各存最新一份，上传刷新）；FileTypes 增第 4 类 testCase（测试用例=只读文件、测试报告=补传文件）；zt_story 核心表加列破例按用户拍板 | 5/6 章 |
|
||||
| v1.21 | 2026-07-23 | CHG-022 | 用户澄清测试为**三个字段**：测试用例（下载）/测试报告·供下载/测试报告·提交 → zt_story 6 列（test_report 拆为 download/submit 两列）；FileTypes 增 testReportSubmit；FR-010 重写（报告双向：AI 供下载、测完提交）；FR-014 判定=zt_file(testReportSubmit) | 5/6 章 |
|
||||
| v1.22 | 2026-07-23 | CHG-023 | 用户指出缺字段 → 补 **code_review_status**（pass/reject/NULL）：审查结果原只在 MD 内容里系统不可查；上传审查报告时解析写入；支撑卡点强制（未 pass 禁提测试报告）、筛选、状态展示；zt_story 7 列 | 5/6 章 |
|
||||
| v1.23 | 2026-07-23 | CHG-024 | ~~测试第 4 字段=test_report_status~~（误解，见 CHG-025） | 5/6 章 |
|
||||
| v1.24 | 2026-07-23 | CHG-025 | 用户澄清：测试 4 字段全是文档——用例下载/报告模版下载/**模版填完提交**（第3）/**其他测试文档**（第4，testOther）→ zt_story 7 url 列 + code_review_status 共 8 列；撤销 test_report_status（误解产物）；FileTypes 增 testOther | 5/6 章 |
|
||||
| v1.25 | 2026-07-29 | CHG-027 | 用户拍板：老验收标准（zt_storyspec.verify）不动，AI 框架验收指标走**新字段+接口**——zt_story_expand 加 acceptance_criteria 列（MEDIUMTEXT，Given/When/Then MD），经 /zt-story-expand/saveOrUpdate 上传，与 verify 双通道并存互不干扰 | 5/6 章 |
|
||||
| v1.26 | 2026-07-29 | CHG-028 | 用户拍板：饱和度达标工时实现对齐 xlsx/§7.3 并补请假规则——（当月工作天数 − 请假小时÷8）×5（半天=0.5 天）；分子=zt_effort.consumed 实际登记工时；修正实现原误用老系统（8h−请假）×0.75 口径 | 7 章 |
|
||||
| v1.27 | 2026-07-29 | CHG-034 | 用户拍板严格按 xlsx 字面：达标工时（每人）=（工作天数×团队人数 − 团队请假天数）×5÷团队人数（团队=后端+前端 KFZ，请假全团队平摊每人相同）；替代 CHG-028 的"谁请假扣谁"；老模块（月报/地盘/明细/汇总）同步 teamExamineTime 统一 | 7 章 |
|
||||
| v1.28 | 2026-07-30 | CHG-037 | 老绩效弹窗（月报「绩效」按钮）全岗位切新 Excel 口径：项目经理/产品经理/产品助理/运维得分改由新绩效引擎（zt_perf_config，score×weight）产出，王宇航按 account 走 projectManagerWyh 变体（无 PRD 项、团队40/稳定性20）；测试计划及时/UI 任务及时规则入 PerfScoreRules；前端弹窗 XMGLY/CPJL/XMZL 区块重写+运维区块新增+王宇航变体块 | 7 章 |
|
||||
| v1.29 | 2026-07-30 | CHG-038 | KFZ 前后端工程师分流：zt_user 加 dev_direction 列（frontend/backend，NULL 按后端口径），用户新增/编辑表单「用户属性=开发者」时显示「开发方向」下拉；buildKFZScore 按方向分流（前端：饱和度满分 30、无文档质量项、代码质量 flat）；绩效弹窗 KFZ 按方向双区块渲染；现有 KFZ 人员待名单一次性初始化 | 5/7 章 |
|
||||
| v1.30 | 2026-07-30 | CHG-039 | 需求PRD工作量指标完成率取数修复：zt_story_expand.product_person 实际存中文姓名，计算器按 account 匹配恒空导致该项得分恒 0 → 改按昵称匹配（account 兜底）；影响项目经理/产品经理/产品助理三岗位 | 7 章 |
|
||||
| v1.31 | 2026-07-31 | CHG-040/041 | CHG-040：运维大项任务同 CHG-039 类姓名匹配修复（belong_to_user 按昵称）；CHG-041：绩效弹窗「绩效数据」列补指标过程值（分子/分母/率），计算器经 rawDetail 透出至 scope/DTO，五岗位区块 19 行绑定展示 | 7 章 |
|
||||
| v1.32 | 2026-07-31 | CHG-042 | 项目经理（含王宇航变体）需求PRD工作量指标完成率改团队口径（范围=全部需求、分母=工作天数×5×产出人数），用户拍板"项目管理员衡量项目所有人"；产品经理/助理维持个人口径 | 7 章 |
|
||||
| v1.33 | 2026-07-31 | CHG-043 | 替代 CHG-042：项目经理两项完成率改**项目口径**（用户拍板"按照迭代来"）——分子=他当月窗口内（begin/end 落当月）执行关联产品的需求指数和，分母=工作天数×5×执行内 KFZ 成员去重数（不含他本人）；产品经理/助理个人口径、其余岗位部门口径不变 | 7 章 |
|
||||
| v1.34 | 2026-07-31 | CHG-044/045 | CHG-044：KFZ 弹窗饱和度行展示达标工时全链（实绩/团队总工作天数/团队达标总工时/人均达标工时/饱和度）；CHG-045：版本计划完成率加权源 estimate → zt_story_expand.workload_index（用户拍板），无指数按 0 权重 | 7 章 |
|
||||
| v1.35 | 2026-07-31 | CHG-046 | 《AI项目文档更新记录》独立承载：zt_story 加 ai_doc_update_url，FileTypes 增 aiDocUpdate（uploadBind 刷新该列），研发详情新增对应文档区块；FR-014 该类判定源由 aiWorkLog-doc_update 类改 zt_file(aiDocUpdate) | 5/6 章 |
|
||||
| v1.36 | 2026-07-31 | CHG-047 | 文档齐备（项目经理 10%）改**实时字段判定**：大型需求五个 url 字段非空即在，不依赖 zt_doc_check 快照/月末 job；归属由 assignedTo 改项目口径（项目经理当月窗口内执行关联产品的大型需求） | 7 章 |
|
||||
| v1.37 | 2026-07-31 | CHG-048 | 需求PRD工作量指标完成率项目口径扩到**产品经理/产品助理**（用户拍板"跟项目管理员一样的方案"）：四角色（项目经理/王宇航/产品经理/产品助理）统一按在窗执行关联产品+执行内 KFZ 成员计；product_person 个人口径转兜底 | 7 章 |
|
||||
| v1.38 | 2026-07-31 | CHG-049 | 版本计划完成率改**项目口径**（用户拍板"孙世超是飞侠的为啥不区分"）：只统计项目经理当月窗口内执行关联产品的发布需求（指数加权不变）；孙世超按 150 单产品 92.35% 计 | 7 章 |
|
||||
| v1.39 | 2026-07-31 | CHG-050 | 线上Bug率/产品缺陷率 5‰ 豁免分母：zt_story.estimate → **上线需求 devel 任务 estimate 合计**（用户拍板"需求工时是任务sum"）；四角色上线需求改项目口径（∩在窗执行关联产品） | 7 章 |
|
||||
| v1.40 | 2026-07-31 | CHG-051 | **扣分尺度统一为加权尺度**（用户拍板"10分满分 10-2"）：所有扣分项按 xlsx 字面从权重分值直接扣（10 分项缺 1 份=扣 2），替代原 100 分制扣分×权重；涉及 rate/Bug率/运维频次/文档齐备四类规则 | 7 章 |
|
||||
| v1.41 | 2026-07-31 | CHG-053 | 绩效弹窗**跟随月报选中产品集**（用户拍板"按照当前选择产品"）：下拉 program 透传至 myWorkScore，任务/需求范围与引擎项目口径指标均按选中产品集计算，未选中回退本人项目口径 | 7 章 |
|
||||
| v1.42 | 2026-07-31 | CHG-054 | 缺陷检出率（测试）的测试需求范围：assignedTo ∪ **zt_story_expand.test_person 指定**（用户拍板"先修复"）；修正"指定该测试但指派给开发"的需求被漏算 | 7 章 |
|
||||
| v1.43 | 2026-08-10 | CHG-056 | 绩效导出换新版式：9 岗位新模版自 SRC-002 生成（含王宇航变体/前后端分离/新增运维），generator 重写+运维导出分支；修复 openpyxl inlineStr 单元格导致占位符替换失效；合并还原并行会话覆盖的 CHG-036/038/054/055 改动 | 7 章 |
|
||||
| v1.44 | 2026-08-10 | CHG-057 | 测试文档齐备（CS 25%）改实时字段判定（用户拍板）：范围=test_person∪assignedTo 本月发布需求，判定=test_case_url+test_report_submit_url 提交件非空（AI 模版不计），缺一份扣 3 扣完截止，本月无需求满分 | 7 章 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 业务背景
|
||||
|
||||
### 1.1 现状与痛点
|
||||
|
||||
- 现状：信息技术部已发布 AI 时代开发 SOP（14 步流程，8 类 AI 工作日志）与 9 岗位绩效考核方案（以工作量指数为核心）[SRC-001][SRC-002]
|
||||
- IT 工作台现状（2026-07-22 代码摸底）：
|
||||
- 用户需求/研发需求/任务/BUG/工时/会议/验收全流程功能已存在 [ZT:controller/ZtStoryUserController.java][ZT:controller/ZtTaskController.java][ZT:controller/ZtBugController.java]
|
||||
- 需求级 AI 工作量指标上传通道已存在（/zt-story-expand，生产已对接 demand-assessor）[ZT:controller/ZtStoryExpandController.java:23]
|
||||
- 核心痛点：
|
||||
1. AI 指标是"孤岛"：zt_story_expand 可录入但绩效统计（IZtCountService）完全不消费 [ZT:service/impl/IZtCountService.java]
|
||||
2. AI 代码审查报告、AI 工作日志、AI 文档更新记录在系统中无任何承载（全库零命中）
|
||||
3. 测试报告无上传入口（zt_testtask.report 为死字段）；会议附件前端组件引入未渲染；用户需求 activateddate/approveddate 死字段 [ZT:entity/ZtStoryUser.java:120,153]
|
||||
4. 绩效考核依赖线下 Excel（codes/zentao 根目录多份考核 xlsx），未自动化 [ASSUMPTION: 以现有文件推断]
|
||||
|
||||
### 1.2 业务目标与问题陈述
|
||||
|
||||
让 SOP 要求的每一类数据在 IT 工作台"有处可存、有入口可传、有页面可看"，并让绩效考核直接消费系统数据，替代线下 Excel。
|
||||
|
||||
### 1.3 相关历史决策
|
||||
|
||||
- AI 指标「框架算、平台存」，zentao 只存不算（用户确认，2026-07-22）
|
||||
- 禅道老表不改结构，扩展走扩展表模式（zt_story_expand 先例）
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与成功指标
|
||||
|
||||
### 2.1 业务目标（可量化）
|
||||
|
||||
| 目标 | 指标 | 当前值 | 目标值 | 截止 |
|
||||
|---|---|---|---|---|
|
||||
| SOP 数据承载完整 | SRC-001 数据模型 9 类数据项系统覆盖率 | 6/9 复用、3 类无承载 | 9/9 | 二期末（MD 附件通道建成后） |
|
||||
| AI 指标可视 | 研发需求详情页展示 AI 指标/审查/日志 | 无（仅统计页） | 详情页可见 | 二期末 |
|
||||
| 绩效自动化 | 9 岗位考核核心指标系统产出 | 线下 Excel | 系统自动算分/导出 | 三期 |
|
||||
|
||||
### 2.2 北极星指标
|
||||
|
||||
工作量指标完成率 = Σ(月度工作量指数) ÷ (团队可用工作天数×5) 可月度自动产出 [SRC-002]
|
||||
|
||||
### 2.3 约束条件与边界
|
||||
|
||||
- 技术约束：不改禅道老表结构；数值上传沿用 saveOrUpdate 幂等模式（参照 /zt-story-expand），文档一律 MD 附件通道（CHG-014）；AI 计算口径不在本系统
|
||||
- 不在本期范围：AI 工作量指数的计算逻辑（AI 框架侧）；绩效权重/公式的管理制度变更
|
||||
- 分期边界：一期=数据模型；二期=上传接口+页面；三期=绩效消费
|
||||
|
||||
---
|
||||
|
||||
## 3. 用户与场景
|
||||
|
||||
### 3.1 目标用户/角色
|
||||
|
||||
| 角色 | 描述 | 典型诉求 |
|
||||
|---|---|---|
|
||||
| 业务部门 | 需求提出方 | 提需求、看进度、验收 |
|
||||
| 产品经理/助理 | 需求管理 | PRD 管理、工作量指标查看、验收跟进 |
|
||||
| 项目经理 | 过程与考核管理 | SOP 文档齐备、绩效数据可信 |
|
||||
| 开发（前/后端） | 任务执行 | 任务与工时清晰、代码审查有记录 |
|
||||
| 测试工程师 | 测试执行 | 用例/BUG/测试报告管理 |
|
||||
| 运维工程师 | 系统保障 | 考核项（巡检/备份）留痕 |
|
||||
| IT 经理 | 考核人 | 9 岗位月度考核自动产出 [SRC-002] |
|
||||
| AI 框架 | 数据生产方（系统角色） | PRD/工作量指数/审查报告/工作日志的上传通道 [SRC-001] |
|
||||
|
||||
### 3.2 关键使用场景
|
||||
|
||||
| 场景编号 | 场景描述 | 涉及角色 | 优先级 |
|
||||
|---|---|---|---|
|
||||
| S-001 | 需求全生命周期流转（SOP 14 步，数据落系统） | 业务/产品/开发/测试/AI框架 | P0 |
|
||||
| S-002 | AI 框架上传：工作量指标（saveOrUpdate 接口）、任务拆分（aiBatchAdd）、审查报告/工作日志（MD 文件经 /common/upload） | AI框架 | P0 |
|
||||
| S-003 | 月度绩效考核：指标自动统计、9 岗位报表 | IT经理/项目经理 | P1 |
|
||||
| S-004 | 大型需求（指数>20）五类文档齐备检查 | 项目经理 | P1 |
|
||||
|
||||
### 3.3 价值链路
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[业务部门] -->|用户需求| B[IT工作台]
|
||||
C[AI框架] -->|PRD/工作量指数/审查报告/工作日志| B
|
||||
B --> D[研发任务/测试/BUG]
|
||||
D --> E[绩效统计]
|
||||
E --> F[9岗位月度考核]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 需求范围
|
||||
|
||||
### 4.1 范围内（In Scope）
|
||||
|
||||
| 模块 | 功能 | 分期 |
|
||||
|---|---|---|
|
||||
| 数据模型 | zt_story_expand 加 AI 参与率列（zt_task_extend 已砍：AI 工时入 zt_task.estimate，指数豁免，见 FR-007/CHG-019） | 一期 |
|
||||
| 上传接口 | 任务批量提交 aiBatchAdd（含开发/测试任务+AI指标）；MD 文件上传复用 /common/upload + uploadBind（审查报告/工作日志/测试报告/纪要）；含框架侧触发挂钩（upload_md.py） | 二期 |
|
||||
| 页面展示 | 需求详情 AI 区块、**需求讨论会议 tab（补充⑦）**、代码审查报告/工作日志按钮+MD 在线查看、会议纪要附件+纪要 MD 在线查看、测试报告入口 | 二期 |
|
||||
| 绩效统计 | IZtCountService 接入工作量指数；9 岗位考核报表；大型需求文档齐备自动核查（FR-014） | 三期 |
|
||||
|
||||
### 4.2 范围外（Out of Scope）
|
||||
|
||||
1. AI 工作量指数/AI 参与率的计算口径与算法（AI 框架侧职责）
|
||||
2. 禅道老表（zt_story/zt_task/zt_bug 等）结构变更
|
||||
3. 考核权重与公式的管理制度调整（以 SRC-002 为准）
|
||||
4. 原型与移动端（skip_flags.prototype=true，用户 2026-07-23 确认暂缓）
|
||||
|
||||
### 4.3 假设与依赖
|
||||
|
||||
| 依赖项 | 类型 | 状态 | 负责方 |
|
||||
|---|---|---|---|
|
||||
| AI 框架上传报文格式 | 内部 | 部分确认（demand-assessor 报文可参照） | AI 框架 |
|
||||
| 生产 DB 变更窗口 | 内部 | 待确认 | 运维 |
|
||||
| SRC-002 考核公式最终版 | 内部 | 已确认（xlsx 为准） | IT 经理 |
|
||||
| zentao 需求单（本 PRD 存档 + W 值补登） | 内部 | **定稿时用户建单并提供 ID → AI 一次完成：W 提交（/zt-story-expand，按 CHG-014 后重估值，原 10.2 已过时）+ PRD 定稿版附件上传（/common/upload）** | 用户 + AI |
|
||||
|
||||
---
|
||||
|
||||
## 5. 整体方案介绍
|
||||
|
||||
### 5.1 方案概述
|
||||
|
||||
最大复用现有 zt_* 功能（需求/任务/BUG/工时/会议/验收链已全），缺口分三类补齐：①需求级 AI 指标加列（zt_story_expand.ai_participation_rate；任务级工时直接入 zt_task.estimate，指数豁免 CHG-019）；②AI 文档（PRD/纪要/审查报告/工作日志/测试报告）走 MD 文件附件通道（CHG-014，FileTypes 扩展）；③绩效统计接入既有 AI 指标。AI 侧数据一律「框架算、平台存」。
|
||||
|
||||
### 5.2 核心机制/策略
|
||||
|
||||
- 扩展表模式：AI 类数值指标进扩展表（zt_story_expand 加列），不碰禅道老表；任务级 AI 工时直接用 zt_task.estimate 标准字段（zt_task_extend 已砍，CHG-019）；AI 文档不进表，走 MD 附件（CHG-014）
|
||||
- 上传通道：saveOrUpdate 幂等模式（按业务键有则更新），参照 /zt-story-expand
|
||||
- 五类文档（大型需求强制）：测试用例=zt_case 复用；测试报告=zt_file(testReport)；AI文档更新记录/代码审查报告/工作日志=**MD 文件附件**（FileTypes: aiCodeReview/aiWorkLog，不建结构化表）[SRC-002][CHG-014]
|
||||
|
||||
### 5.4 字段新增/调整
|
||||
|
||||
| 字段 | 表 | 类型 | 说明 | 证据 |
|
||||
|---|---|---|---|---|
|
||||
| ai_participation_rate | zt_story_expand | varchar(16) | AI 参与率（只存不算，口径待定） | SRC-001 |
|
||||
| aiCodeReview / aiWorkLog / testCase / testReport / testReportSubmit | FileTypes 枚举（二期） | — | 审查报告/工作日志/测试用例（下载）/测试报告（供下载）/测试报告（提交）附件类型（MD 文件方案，不建表） | CHG-014/021/022 |
|
||||
| url | zt_file（二期加列） | varchar(512) | 附件访问链接：pathname=存储路径，url=可访问地址（在线查看/外链取用）；zt_file 为禅道原生表，加列属破例（沿用 zt_* 自研扩展字段惯例） | CHG-018 用户指定 |
|
||||
| url | zt_meeting（二期加列） | varchar(512) | 会议纪要 MD 访问链接（直取，不绕 zt_file 反查）；多份纪要时**存最新一份**（每次上传刷新），历史份仍走 zt_file 列表 | CHG-020 用户指定 |
|
||||
| prd_url / code_review_url / work_log_url / test_case_url / test_report_download_url / test_report_submit_url / test_other_url | zt_story（二期加 7 列 url） | varchar(512)×7 | 研发需求文档链接（各存最新一份，上传刷新）：PRD/审查报告/工作日志/**测试用例下载/报告模版下载/模版填完提交/其他测试文档**；zt_story 为禅道核心表，加列属破例（用户拍板） | CHG-021/022/025 用户指定 |
|
||||
| code_review_status | zt_story（二期加列） | varchar(16) | **审查状态：pass/reject/NULL（未审）**——审查结果原只在 MD 内容里系统不可查，加此字段支撑：卡点强制（未 pass 禁提测试报告）、列表筛选、状态展示；上传审查报告时由报文参数或 MD 头部「结果：pass/reject」解析写入 | CHG-023 用户指出 |
|
||||
|
||||
### 5.5 方案对比与取舍
|
||||
|
||||
| 方案 | 优点 | 缺点 | 结论 |
|
||||
|---|---|---|---|
|
||||
| A：扩展表模式（数值指标） | 不碰老表、升级兼容、有先例 | 关联查询多一层 | ✅ 采用 |
|
||||
| D：MD 文件流（AI 文档） | 不建表、人可直接阅读、上传即看 | 结构化取数弱（需 MD 头部约定） | ✅ 采用（CHG-014 用户拍板） |
|
||||
| B：zt_task 直接加列 | 查询简单 | 污染禅道老表、违背既定先例 | ❌ 放弃 |
|
||||
| C：验收指标结构化新表 | 可机读 | 富文本 verify 已够用，过度设计 | ❌ 放弃（后续按需） |
|
||||
|
||||
### 5.6 ID 流转约定（上传关联的钥匙）
|
||||
|
||||
1. **storyId 先有单后有号**：研发需求单在 zentao 创建（人从用户需求详情页「添加研发需求」；后续可选 AI 创建需求接口）→ ID 由 zentao 分配
|
||||
2. **ID 回填**：storyId 写入 PRD 文档信息表「关联需求ID」字段（demand-assessor 取数规则已支持"优先从 PRD 提取需求ID"）+ 框架工作区 session 记录
|
||||
3. **上传关联**：接口以 storyId 为主键（/zt-story-expand、/zt-task/aiBatchAdd）；MD 文件经 zt_file.objectID 关联需求、objectType 区分类型（aiCodeReview/aiWorkLog/testReport/meeting）
|
||||
4. **taskId 由 zentao 返回**：aiBatchAdd 创建任务后响应携带 taskIds，框架记录后用于任务级关联；审查/日志/指标报文仅需 storyId（taskId 可选）
|
||||
5. 本流程自身即实例：定稿日用户建单提供 ID → W 提交+PRD 附件上传（见 4.3 定稿日约定）
|
||||
6. **多人协作前提**：框架为多人多机使用——ID 的共享载体是 **PRD 文档**（存 zentao 附件，全员可读），个人工作区不作为共享来源；多人并发协作由 zentao 状态机约束；AI 上传统一挂「ai」账户与具体使用者解耦；**上传接口鉴权在多人环境下为必决项**（二期立项前须定：签名/内部 token，不得裸连）
|
||||
|
||||
---
|
||||
|
||||
## 6. 需求内容
|
||||
|
||||
### 6.1 端/渠道覆盖矩阵
|
||||
|
||||
| 端/渠道 | 是否覆盖 | 核心差异点 | 涉及 FR | 证据 |
|
||||
|---|---|---|---|---|
|
||||
| 管理端 Web（Vue2） | ✅ | 唯一用户端；新增 AI 区块/附件入口 | FR-002/004/008/010/011 | ZT:codes/web_zentao |
|
||||
| API（AI 框架上传） | ✅ | 数值=saveOrUpdate 幂等；文档=/common/upload+uploadBind；任务=aiBatchAdd | FR-004/006/007/008/010/011 | ZT:controller/ZtStoryExpandController.java:23 |
|
||||
| 商户/小程序/H5/C端 | ❌ | 内部系统，无此类端 | — | — |
|
||||
|
||||
### 6.2 功能需求列表（FR）
|
||||
|
||||
> 分期标注：①=一期（数据模型）②=二期（接口+页面）③=三期（绩效）。复用=现有功能已满足，无开发量。
|
||||
|
||||
#### FR-001：用户需求管理（提出/评审/激活）— 复用+②补写
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：业务部门、产品经理
|
||||
- **触发**：业务部门提交用户需求
|
||||
- **需求**：系统 SHALL 支持用户需求创建、评审（userReview）、激活、关闭全流程 [ZT:controller/ZtStoryUserController.java:157]
|
||||
- **业务规则**：评审通过即激活（现状无独立激活端点）；激活时间须落库（现状 activateddate 死字段，②补写 [ZT:entity/ZtStoryUser.java:153]）；**审批时间口径 = revieweddate**（userReview 通过时写入，已有 [ZT:ZtStoryUserServiceImpl.java:564]；approveddate 字段闲置，语义由 revieweddate 覆盖）
|
||||
- **边界**：评审不通过→关闭并记录原因
|
||||
- **证据**：[SRC-001][ZT:service/impl/ZtStoryUserServiceImpl.java:562-578] ｜ **AC**：待 Round 2 批量生成
|
||||
|
||||
#### FR-002：需求讨论会与纪要 MD（上传/在线查看）— ②
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：产品经理、项目经理
|
||||
- **触发**：SOP「初次讨论/评审讨论」节点 [SRC-001]
|
||||
- **需求**：系统 SHALL 支持会议创建（时间/参与人/纪要/关联需求）；**会议纪要 MD 文件：可多次上传（多份）、页面内在线查看（无需下载）；展示操作人（上传人）、操作时间、会议人（参与人）**（用户补充①，2026-07-23）
|
||||
- **业务规则**：
|
||||
1. FileTypes.meeting 附件绑定后端已就绪 [ZT:ZtMeetingServiceImpl.java:159]；前端渲染上传组件（已引入未渲染）
|
||||
2. .md 附件点击在线渲染 Markdown；其他格式（PDF/图片）维持下载
|
||||
3. 多份纪要按上传时间排列；操作人/操作时间取 zt_file.addedBy/addedDate，会议人取 zt_meeting.users
|
||||
4. **用户需求详情页右侧 tabs 新增「需求讨论会议」**（补充⑦）：列出 zt_meeting.storyIds 含本需求的会议（主题/类型/时间/参与人），点击跳会议详情
|
||||
5. zt_meeting 加 `url` 字段（二期）：存最新一份纪要 MD 的访问链接，查看直取；历史多份仍走 zt_file 列表（CHG-020）
|
||||
- **证据**：[SRC-001][ZT:controller/ZtMeetingController.java][用户补充①]
|
||||
|
||||
#### FR-003：PRD 文档管理 — 复用+①日志项
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：产品经理、AI 框架
|
||||
- **触发**：AI 生成初版/最终版 PRD [SRC-001]
|
||||
- **需求**：PRD/原型图以附件承载于需求（FileTypes.story/userStory）；每一版 PRD 生成时间记入 AI 工作日志 MD（prd_version 类内容，②FR-011）
|
||||
- **证据**：[SRC-001][ZT:controller/CommonsController.java:71]
|
||||
|
||||
#### FR-004：需求级 AI 工作量指标 — ①字段+②展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（上传）、产品经理（查看）
|
||||
- **触发**：最终版 PRD 定稿后 AI 评估 [SRC-001]
|
||||
- **需求**：系统 SHALL 存储并展示功能单元数量、单元业务复杂度、技术复杂度系数、AI 效率系数、**AI 参与率（新增）**、工作量指数
|
||||
- **业务规则**：上传通道 /zt-story-expand/saveOrUpdate 已有；zt_story_expand 加 ai_participation_rate 列；需求详情页新增 AI 指标区块（②）
|
||||
- **证据**：[SRC-001][ZT:entity/ZtStoryExpand.java]
|
||||
|
||||
#### FR-005：验收标准与测试用例管理 — 复用
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：产品经理、测试工程师
|
||||
- **需求**：验收标准以 zt_storyspec.verify 富文本承载；测试用例 zt_case + 评审链（story-case）复用 [ZT:entity/ZtStoryspec.java:29]
|
||||
- **变更（CHG-027，2026-07-29 用户拍板）**：老验收标准 verify 不动；**AI 框架验收指标走新字段 `zt_story_expand.acceptance_criteria`**（MEDIUMTEXT，Given/When/Then MD），经 `/zt-story-expand/saveOrUpdate` 随框架指标通道上传，与 verify 双通道并存
|
||||
- **证据**：[SRC-001] ｜ **AC**：复用无需新增
|
||||
|
||||
#### FR-006：研发任务管理（拆分/分配/工时）— 复用+②AI 提交
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：项目经理、开发/测试工程师、AI 框架
|
||||
- **需求**：任务创建双通道——①人工创建（现有拆分/批量拆分/Excel 导入，保留不变）；②AI 框架批量提交（②期新增接口）：AI 拆分结果（任务清单、类型、建议指派人、AI 评估工时/指数）提交后直接建成任务 [SRC-001]
|
||||
- **业务规则**：
|
||||
1. **AI 上传任务的创建人 = 系统专用账户「ai」**（zt_user 新建 account=ai 的用户，与真人区分，便于追溯任务来源）— 用户指定
|
||||
2. 任务类型覆盖**开发任务与测试任务**：测试任务 type=test，指派测试人员（对应 SRC-001 测试任务数据项：测试人员、测试开始/结束时间）
|
||||
3. AI 评估工时随任务提交写入 `zt_task.estimate`（标准字段；任务级指数豁免，FR-007/CHG-019）
|
||||
4. **AI 提交任务初始状态 = 未开始（wait），后续走现有任务流程**（开始→完成→完工审批→关闭），与人工创建任务完全一致，无特殊状态（用户确认）
|
||||
5. **工时匹配（CHG-031 用户拍板）**：需求评估工时与任务工时同源——框架上传需求时已确定评估工时（zt_story_expand.evaluation_time），拆任务时**Σ任务 aiEvaluationTime 必须 = 需求评估工时**（全量分摊，可分批提交逐批逼近）；**匹配纪律在框架侧执行，禅道不做校验**（用户明确）
|
||||
- **证据**：[SRC-001][ZT:controller/ZtTaskController.java]
|
||||
|
||||
#### FR-007：任务级 AI 工时与指数 — ①工时入 estimate，指数豁免
|
||||
|
||||
- **优先级**：P2 ｜ **角色**：AI 框架（上传）
|
||||
- **触发**：AI 拆分任务并评估每个任务工时 [SRC-001]
|
||||
- **需求（CHG-019 用户拍板）**：**不建 zt_task_extend**——AI 评估工时随 aiBatchAdd 写入 `zt_task.estimate`（标准字段，无需扩展表）；**AI 评估任务工作量指数暂不落地**（SOP 数据项豁免：当前无消费方——绩效取数用需求级指数 zt_story_expand；三期如需「AI 估算准确性」分析再恢复）
|
||||
- **证据**：[SRC-001][用户拍板 2026-07-23]
|
||||
|
||||
#### FR-008：AI 代码审查报告（MD 文件）— ②上传+展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（生成/上传）、开发工程师、项目经理
|
||||
- **触发**：需求下所有开发任务完工后（框架内自动/框架外负责人手动）；不通过则回炉重审 [SRC-001]
|
||||
- **需求**：代码审查报告为 **MD 文件**；研发需求详情页新增「代码审查报告」按钮——支持上传 MD（可多份、按轮次）与在线查看；FileTypes 新增 aiCodeReview。**不建结构化表**（用户定 2026-07-23）
|
||||
- **业务规则**：
|
||||
1. 触发时机=该需求全部开发任务完工；通过前不得流转测试（SOP 卡点）[SRC-001]
|
||||
2. 每轮审查完成即上传一个 MD（含未通过轮次，文件名建议含轮次标识）；初审/复审扣分依赖逐轮文件 [SRC-002]
|
||||
3. 大型需求（指数>20）强制 [SRC-002]；FR-014 齐备判定=zt_file(objectType=aiCodeReview)
|
||||
4. 异议由技术负责人复核，复核结论补充上传
|
||||
5. 代码质量扣分取数：建议 MD 头部约定格式（如「严重：N／错误：N」）供系统解析 [建议，三期前确认]；不解析则该项半自动（人读数录入）
|
||||
6. **审查状态字段 code_review_status（pass/reject/NULL）随上传写入 zt_story**（uploadBind 解析报文参数或 MD 头部结果）；用途：未 pass 时「提交测试报告」按钮禁用（SOP 卡点系统级落地，CHG-023）、列表筛选、状态展示
|
||||
- **证据**：[SRC-001][SRC-002][用户定]
|
||||
|
||||
#### FR-009：测试任务与 BUG 管理 — 复用
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：测试工程师、开发工程师
|
||||
- **需求**：BUG 全流程（提交/指派/修复/复测/验收 bugYs）复用 [ZT:controller/ZtBugController.java]
|
||||
- **证据**：[SRC-001]
|
||||
|
||||
#### FR-010：测试报告管理 — ②
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：测试工程师、AI 框架
|
||||
- **触发**：测试完成提交测试报告 [SRC-001]；大型需求强制 [SRC-002]
|
||||
- **需求**：测试类文档四个字段（CHG-025 用户明确）：**测试用例**（FileTypes.testCase，AI 生成供下载）；**测试报告·模版下载**（FileTypes.testReport，AI 生成的模版）；**测试报告·模版填完提交**（FileTypes.testReportSubmit，填完上传，可多次补充）；**其他测试文档**（FileTypes.testOther，其他文档上传位）——均挂研发需求，zt_story 对应 4 个 url 字段各存最新一份
|
||||
- **业务规则**：FR-014 齐备判定：《需求测试报告》=zt_file(testReportSubmit)、《需求测试用例》=zt_case 或 zt_file(testCase)；结构化用例=zt_case 复用（执行/统计）
|
||||
- **证据**：[SRC-001][ZT:entity/ZtTesttask.java（report 为死字段）][用户确认 Q3/Q4]
|
||||
|
||||
#### FR-011：AI 工作日志（MD 文件）— ②上传+展示
|
||||
|
||||
- **优先级**：P0 ｜ **角色**：AI 框架（生成/上传）、项目经理（查看）
|
||||
- **触发**：SOP 各节点（PRD 版本/工作量评估/架构设计/架构评审/任务拆分/门禁检查/代码审查/文档更新）[SRC-001]
|
||||
- **需求**：工作日志为 **MD 文件**；研发需求详情页新增「工作日志」按钮——上传 MD（可多份）与在线查看；FileTypes 新增 aiWorkLog。**不建结构化表**（用户定 2026-07-23）
|
||||
- **业务规则**：
|
||||
1. 事件产生即上传（不补传）；8 类事件在 MD 中分类记录（或按类分文件）
|
||||
2. 框架侧挂钩：各技能节点产出 MD 后经 /common/upload 上传（或人工按钮上传），二期交付含挂钩
|
||||
3. FR-014 齐备判定=zt_file(objectType=aiWorkLog)；《AI 文档更新记录》同通道（doc_update 类记录）
|
||||
- **证据**：[SRC-001][用户定]
|
||||
|
||||
#### FR-012：工作量指标完成率统计 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：IT 经理、项目经理
|
||||
- **需求**：IZtCountService 接入 zt_story_expand.workloadIndex，按 SRC-002 公式产出完成率 = Σ(月度工作量指数) ÷ (团队可用工作天数×5)
|
||||
- **业务规则**：测试人员不计入工作量产出方 [SRC-002]
|
||||
- **证据**：[SRC-002][ZT:service/impl/IZtCountService.java（现不消费 AI 指标）]
|
||||
|
||||
#### FR-013：九岗位绩效考核报表 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：IT 经理
|
||||
- **需求**：按 SRC-002 九岗位 sheet 的权重/公式/评分标准，产出月度考核报表（版本计划完成率、线上 Bug 率、Bug 密度、缺陷检出率等；文档齐备核查由 FR-014 承担）
|
||||
- **业务规则**：大型需求判定=AI 评估工作量指数>20；普通/重大 Bug 分级定义以 SRC-002 为准
|
||||
- **证据**：[SRC-002]
|
||||
|
||||
#### FR-014：大型需求文档齐备自动核查 — ③
|
||||
|
||||
- **优先级**：P1 ｜ **角色**：系统（自动）、项目经理（月度确认）、技术负责人（异议复核）
|
||||
- **触发**：每月考核周期；大型需求=AI 评估工作量指数>20 [SRC-002]
|
||||
- **需求**：系统 SHALL 自动生成「大型需求 × 五类文档」齐备清单，按规则自动计算缺失扣分并写入 zt_month_score；提供异议复核入口与项目经理月度确认
|
||||
- **业务规则**：
|
||||
1. 五类文档判定来源：《需求测试用例》=zt_case 有无关联用例；《需求测试报告》=zt_file(testReport) 附件（②期）；《AI代码审查报告》=zt_file(aiCodeReview) 附件（②期 MD）；《AI工作日志》=zt_file(aiWorkLog) 附件（②期 MD）；《AI项目文档更新记录》=zt_file(aiWorkLog) 附件中 doc_update 类内容（②期 MD）
|
||||
2. 考核只判「缺失」不判内容质量：每缺失一份扣 2 分，扣完截止 [SRC-002]
|
||||
3. 内容争议不走人工抽检：异议由技术负责人复核并留痕
|
||||
4. 结果落库 zt_month_score（account+月份+scopeJson 明细，现有表复用，不建新表）[ZT:entity/ZtMonthScore.java]
|
||||
- **证据**：[SRC-002][ZT:entity/ZtMonthScore.java]
|
||||
|
||||
### 6.3 SOP 步骤 × 现有工作流映射（代码级）
|
||||
|
||||
现有系统已实现的研发需求工作流主线：`zt_story.status`（reviewing/active/draft/finished/closed）+ `zt_story.stage`（wait→projected→developing→developed→testing→tested→released→verified，含自研 productWaitVerified/productVerified 产品内部验收）[ZT:enums/StoryStageEnums.java]；前端「需求的一生」基于 zt_action 动态流展示。SOP 14 步逐步映射如下：
|
||||
|
||||
| SOP 步骤 [SRC-001] | 现有工作流节点（证据） | 结论 |
|
||||
|---|---|---|
|
||||
| 1 业务部门提用户需求 | `/zt-story-user/addStory` 创建用户需求，openeddate 落库 [ZT:ZtStoryUserServiceImpl.java:135] | 复用 |
|
||||
| 2 评审需求、激活 | `/zt-story-user/userReview` 全员通过→status=active + revieweddate [ZT:ZtStoryUserServiceImpl.java:562]；无独立激活端点，activateddate 死字段 | 复用 + ②补写激活时间（FR-001） |
|
||||
| 3 初次讨论、会议纪要 | `/zt-meeting/add`（type=story，storyIds 关联用户需求，result=纪要） [ZT:ZtMeeting.java:72-73] | 复用 + ②附件 UI（FR-002） |
|
||||
| 4 AI 生成初版 PRD+原型 | 附件通道 `/common/upload` 绑定需求（FileTypes.userStory） [ZT:CommonsController.java:71] | 通道复用；版本时间记 AI 工作日志 MD（②FR-003/011，zt_file(aiWorkLog)） |
|
||||
| 5 评审讨论、偏差回炉 | 会议迭代 + 附件更新；偏差判断为人工环节，无系统流转 | 复用（系统外判断） |
|
||||
| 6 生成最终版 PRD | 同步骤 4 | 同上 |
|
||||
| 7 AI 评估工作量→生成研发需求+指定完成时间 | 前端「添加研发需求」按钮从用户需求建 zt_story；指标经 `/zt-story-expand/saveOrUpdate` 上传；完成时间=zt_story.planEndDate/endDate | 复用 + ①AI参与率加列（FR-004） |
|
||||
| 8 AI 生成架构设计/验收指标/测试用例 | 验收标准=zt_storyspec.verify 富文本 [ZT:ZtStoryspec.java:29]；用例=zt_case + 评审（/zt-story-case）；架构文档=附件 | 复用（FR-005） |
|
||||
| 9 评审确认各文档 | 用例评审链（story-case psUser/psDate/status）；文档评审为人工 | 复用 |
|
||||
| 10 AI 拆分任务/评估工时/分配 | **双通道（FR-006）**：②AI 批量提交接口（创建人=ai 账户，覆盖开发任务+测试任务 type=test）；人工拆分/批量/Excel 创建保留；AI 工时入 zt_task.estimate（指数豁免，FR-007/CHG-019） | 复用 + ②新增接口 |
|
||||
| 11 开发实施 | 任务生命周期 startTask→finishTask→approval 完工审批；工时 `/zt-effort/batchAdd` 回写 consumed/left [ZT:ZtEffortServiceImpl.java:41] | 复用（FR-006） |
|
||||
| 12 开发完成→AI 代码审查（不过回炉） | **系统无此节点**（全库零命中）；回炉可借任务重开/bug 流程 | ②MD 文件方案（FR-008）：FileTypes.aiCodeReview + 按钮上传+在线查看 |
|
||||
| 13 测试/BUG/复测/测试报告 | `/zt-story/testSubmitVerified` 测试提交 [ZT:ZtStoryController.java:238]→zt_case execCase 执行→zt_bug 全流程→bugYs 验收 [ZT:ZtBugServiceImpl.java:463] | 复用 + ②测试报告 testReport 附件（FR-010） |
|
||||
| 14 报告→更新AI文档→AI工作日志→结束 | 内部验收链：storyProductUserYs [ZT:ZtStoryController.java:248]→发布 zt_release→storyYs 验收（ysFlag/ysDate→status=finished，联动用户需求完成）[ZT:ZtStoryServiceImpl.java:2119] | 复用验收链 + ②AI 工作日志 MD 文件（FR-011，FileTypes.aiWorkLog + 按钮上传+在线查看） |
|
||||
|
||||
**映射结论**：SOP 14 步中 11 步可由现有工作流节点承载；缺口集中在步骤 12（AI 代码审查）与步骤 4/14 的 AI 侧留痕（工作日志）——按 CHG-014 走 MD 文件附件方案（二期）；步骤 10 的任务级 AI 工时直接入 zt_task.estimate（指数豁免 CHG-019）——一期仅余 zt_story_expand 加 1 列；步骤 2/3/13 的附件与时间补写属二期小改。
|
||||
|
||||
---
|
||||
|
||||
## 7. 数据与埋点
|
||||
|
||||
### 7.1 数据模型（建议结构，一期交付 DDL）
|
||||
|
||||
```sql
|
||||
-- 【CHG-014 已取消】zt_ai_code_review / zt_ai_work_log 两表不建——
|
||||
-- AI 审查报告与工作日志改为 MD 文件附件方案（FileTypes: aiCodeReview/aiWorkLog，见 FR-008/011）
|
||||
-- 【CHG-019 已取消】zt_task_extend 不建——AI 工时入 zt_task.estimate，任务级指数豁免（见 FR-007）
|
||||
|
||||
-- 一期仅此一项：zt_story_expand 加列（可重入）
|
||||
ALTER TABLE `zt_story_expand`
|
||||
ADD COLUMN `ai_participation_rate` VARCHAR(16) DEFAULT NULL COMMENT 'AI参与率（只存不算，口径待定）' AFTER `ai_efficiency_coefficient`;
|
||||
```
|
||||
|
||||
### 7.3 数据口径
|
||||
|
||||
| 指标名 | 计算方式 | 来源 | 备注 |
|
||||
|---|---|---|---|
|
||||
| 工作量指标完成率 | Σ(月度需求工作量指数) ÷ (团队可用工作天数×5) | zt_story_expand.workloadIndex | 测试人员不计入产出方 [SRC-002] |
|
||||
| 版本计划完成率 | Σ(按时发布需求工时) ÷ Σ(所有需求工时) ≥95% | zt_release/zt_task | [SRC-002] |
|
||||
| 线上 Bug 率 | Σ(当月上线需求线上Bug数) ÷ Σ(上线需求开发工时) ≤5‰ | zt_bug/zt_task | 普通/重大分级 [SRC-002] |
|
||||
| Bug 密度 | Σ(当月完成任务Bug数) ÷ Σ(完成任务分配工时) ≤15% | zt_bug/zt_task | 连续3月达标可返还 [SRC-002] |
|
||||
| 缺陷检出率 | (普通Bug×1+重大Bug×5) ÷ 测试需求开发工时 >20% | zt_bug | [SRC-002] |
|
||||
| 大型需求判定 | AI 评估工作量指数 > 20 | zt_story_expand | 触发五类文档强制 [SRC-002] |
|
||||
| 任务及时完成率 | Σ(按时完成任务的分配工时) ÷ Σ(所有任务的分配工时) =100% | zt_task | 开发/UI [SRC-002] |
|
||||
| 测试计划及时完成率 | Σ(按时完成的测试工作分配工时) ÷ Σ(所有测试工作分配工时) =100% | zt_task(type=test) | 测试；zt_testtask 为只读遗留不取 [SRC-002] |
|
||||
| 项目准时率 | Σ(当月准时上线需求量) ÷ Σ(当月规划上线需求总量) ≥95% | zt_story | 产品经理 [SRC-002] |
|
||||
| 月度达标工时（饱和度基准） | 团队总工作天数 × 5 ÷ 开发人员数（后端+前端，zt_user.user_type=KFZ）；请假按 小时÷8 折算工作日、**全团队平摊**（CHG-034：每人达标工时相同=（工作天数×人数 − 团队请假天数）×5÷人数） | zt_effort+考勤 | 开发；测试人员不计入产出方 [SRC-002] |
|
||||
| 产品缺陷率 | Σ(当月上线需求线上Bug数) ÷ Σ(上线需求开发分配工时) ≤5‰ | zt_bug/zt_task | 与线上Bug率同口径 [SRC-002] |
|
||||
|
||||
**口径待确认（5 项，三期开工前须与 IT 经理核对）**：
|
||||
1. **总分算法**：xlsx 各项仅见权重与「=100%得满分」规则，未明写总分公式；本 PRD 按「每项 0~100 分 × 权重求和」理解 [ASSUMPTION]
|
||||
2. **线上 Bug 率单位**：xlsx 原文「×100% ≤5‰」自相矛盾（百分数 vs 千分号），本 PRD 按 ‰ 理解 [待确认]
|
||||
3. **缺陷检出率申诉**：无 Bug 检出可申诉不扣分、上线后发现加倍扣——需人工裁定流程，系统只留申诉入口与记录 [待确认]
|
||||
4. **普通/重大 Bug 映射**（数据盘点新发现）：SRC-002 业务定义（影响上游回传/财务/大面积）如何映射 zt_bug.severity(1-4)/type，无规则则相关 5 项指标（线上Bug/缺陷率/检出率等）无法自动分级 [已决 2026-08-04：以老弹窗 getBugFindScore 为准，severity 1=重大、2/3/4=普通；撤销 07-28 锁定的 1~2=重大]
|
||||
5. **产品助理「需求部门及时验收」数据链**（新发现）：zt_story_user 验收字段（ysFlag/ysDate）为闲置字段、无端点写入，验收时间链断裂；需二期补写或改走 zt_story 侧验收时间 [待确认]
|
||||
|
||||
### 7.4 统计/埋点需求
|
||||
|
||||
无新增埋点；AI 侧事件以 MD 文件经 zt_file 落地（zt_file.addedDate=入库时间，事件发生时间记于 MD 内容中）。
|
||||
|
||||
### 7.5 绩效计算模型（FR-012/013/014 完整规则，SRC-002 全量映射）
|
||||
|
||||
**通用规则** [SRC-002]：
|
||||
1. 加权扣分制：每项满分 100×权重，项内扣分「扣完截止」；总分=Σ各项
|
||||
2. 普通 Bug=程序/数据/样式明显错误，不影响业务运营；重大 Bug=影响上游回传数据、财务数据、线上大面积影响
|
||||
3. 大型需求=AI 评估工作量指数>20；工作量产出方统计不含测试人员
|
||||
4. 自动化标注：✅=系统可算（数据源已在系统/一二期落地）；🔶=半自动（系统出数+人工裁定）；❌=人工评分
|
||||
|
||||
#### 项目经理
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化/数据来源 |
|
||||
|---|---|---|---|
|
||||
| 需求PRD工作量指标完成率 | 0.2 | =100%满分；每减1%扣1分 | ✅ zt_story_expand.workloadIndex |
|
||||
| 团队工作量指标完成率 | 0.3 | =100%满分；每减2%扣1分 | ✅ 同上 |
|
||||
| 版本计划完成率 | 0.1 | ≥95%满分；每减1%扣2分 | ✅ zt_release/zt_task 工时 |
|
||||
| 线上Bug | 0.1 | ≤5‰满分；普通Bug每个扣3分、重大扣10分 | ✅ zt_bug |
|
||||
| 文档齐备（大型需求五类） | 0.1 | 每缺失一份扣2分 | ✅ FR-014 自动核查 |
|
||||
| 问题管理（《项目问题和处理》《系统运行问题和处理》） | 0.05 | 每遗漏一项扣1分 | ❌ 两类文档系统无承载，暂线下 [待确认：是否建承载] |
|
||||
| 系统运行稳定性 | 0.1 | 场景1扣10/场景2扣5/场景3满分 | 🔶 系统出故障记录+人工定级 |
|
||||
| 专业技能提升 | 0.05 | IT经理打分 | ❌ 人工 |
|
||||
|
||||
（项目经理-王宇航版：无 PRD 项；团队完成率 0.4；稳定性 0.2；其余相同）[SRC-002]
|
||||
|
||||
#### 产品经理 / 产品助理
|
||||
|
||||
| 评分事项 | 权重（经理/助理） | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 需求PRD工作量指标完成率 | 0.4 / 0.5 | 每减1%扣2分 | ✅ |
|
||||
| 团队工作量指标完成率 | 0.2 / — | 每减1%扣1分 | ✅ |
|
||||
| 需求部门及时验收（两周内） | — / 0.2 | 每超期一项扣5分 | ✅ zt_story_user 验收时间链 |
|
||||
| 项目准时率 | 0.1 / — | ≥95%满分；90~95%每减1%扣1分；<90%每减1%扣2分 | ✅ zt_story 上线时间 |
|
||||
| 产品缺陷率 | 0.15 / 0.15 | ≤5‰满分；普通3分/重大10分 | ✅ zt_bug |
|
||||
| 问题响应和解决 | 0.1 / 0.1 | 内部投诉扣5分/次、外部扣10分/次 | ❌ 人工登记 |
|
||||
| 主动性与责任感 | 0.05 / 0.05 | 上级按事例评 5/3/0 | ❌ 人工 |
|
||||
|
||||
#### 后端 / 前端开发工程师
|
||||
|
||||
| 评分事项 | 权重（后端/前端） | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 任务及时完成率 | 0.25 / 0.25 | =100%满分；95~100%每减1%扣1分；≤94%每减1%扣2分 | ✅ zt_task |
|
||||
| Bug密度 | 0.3 / 0.3 | ≤15%满分；每增1%扣3分；连续3月达标返还半年扣分 | ✅ zt_bug/zt_task |
|
||||
| 代码质量 | 0.1 / 0.1 | 后端：初审严重1处扣3分、错误超6处扣3分；复审严重1处扣5分、错误1处扣1分。前端：评审每发现1问题扣3分 | 🔶 后端=审查报告 MD 头部计数解析（约定格式，三期前确认；不解析则人工读数）；前端=评审记录 |
|
||||
| 设计文档质量 | 0.1 / — | 评审每发现1问题扣5分 | 🔶 评审记录系统无独立承载 [待确认] |
|
||||
| 工作量饱和度 | 0.2 / 0.3 | 月度达标工时=团队总工作天数×5÷开发人员数；每减1%扣2分 | ✅ zt_effort+考勤（IZtCountService 已有考勤接入） |
|
||||
| 不规范行为 | 0.05 / 0.05 | 迟到/失联/推诿/弄虚作假等着装扣1~5分 | ❌ 人工 |
|
||||
| 加分项 | — | 优质分享+5分/次；全月Bug<6且绩效≥95 +10分 | 🔶 分享人工认定，其余自动 |
|
||||
|
||||
#### 测试工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 测试计划及时完成 | 0.2 | 每减1%扣2分 | ✅ zt_task(type=test)/zt_effort |
|
||||
| 测试文档齐备 | 0.25 | 10%抽检，每缺一份扣3分 | ✅ FR-014 同机制（zt_case+zt_file(testReport)） |
|
||||
| 缺陷检出率 | 0.3 | (普通Bug×1+重大Bug×5)÷测试需求开发工时>20%满分；每减1%扣2分；无检出可申诉、上线后发现加倍扣 | ✅ zt_bug |
|
||||
| 线上Bug | 0.2 | 无满分；普通每个扣5分；重大该项0分 | ✅ zt_bug |
|
||||
| 不规范行为 | 0.05 | 同开发 | ❌ 人工 |
|
||||
| 加分项 | — | 测试创新+5分；全月无Bug且≥95 +10分 | 🔶 |
|
||||
|
||||
#### UI 工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 任务及时完成 | 0.5 | =100%满分；90~100%得40分；<90%得0分 | ✅ zt_task |
|
||||
| 设计质量 | 0.4 | 6 维度评审（受众理解/布局/创意/交互建议/切图配合/审核严谨） | ❌ 人工评审 |
|
||||
| 不规范行为 | 0.1 | 同开发 | ❌ 人工 |
|
||||
| 加分项 | — | 工作量超平均每10%加2分；创新建议最高+10分 | 🔶 |
|
||||
|
||||
#### 运维工程师
|
||||
|
||||
| 评分事项 | 权重 | 规则要点 | 自动化 |
|
||||
|---|---|---|---|
|
||||
| 运维大项任务及时完成 | 0.2 | 及时完成率×20 | ✅ zt_yw* 运维任务表（现有） |
|
||||
| 系统运维监控（每周2次） | 0.15 | 缺一次扣3分 | ✅ zt_yw* 记录 |
|
||||
| 职场巡检（每周1次） | 0.1 | 缺一次扣5分 | ✅ 同上 |
|
||||
| 数据库备份（每项目每周全量） | 0.1 | 缺一个扣3分 | ✅ 同上 |
|
||||
| 其他运维工作 | 0.15 | 及时性与质量 | 🔶 人工 |
|
||||
| 系统稳定性 | 0.2 | 场景1扣10/场景2扣5/场景3满分/运维失误致故障该项0分 | 🔶 |
|
||||
| 不规范行为 | 0.1 | 含填报虚假任务扣5分 | ❌ 人工 |
|
||||
| 加分项 | — | 创新建议最高+10分 | 🔶 |
|
||||
|
||||
**落地说明**：✅ 项三期由 IZtCountService 自动产出；🔶 项系统出数、考核人裁定；❌ 项保留人工录入入口（zt_month_score.scopeJson 承载所有项）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 差异点清单（现状 vs 目标）
|
||||
|
||||
| 维度 | 现状 | 目标 | 影响范围 | 涉及 FR | 证据 |
|
||||
|---|---|---|---|---|---|
|
||||
| 数据结构 | AI 代码审查/工作日志/任务级指标无承载 | 1 加列（需求级 AI 参与率）+ FileTypes 扩展 3 类附件（MD 文件流）；任务级工时入 zt_task.estimate、指数豁免（CHG-019） | DB/附件 | FR-004/007/008/010/011 | 全库 grep 零命中 |
|
||||
| 口径 | 绩效不消费 AI 指标（孤岛） | IZtCountService 接入 workloadIndex | 统计层 | FR-012/013 | ZT:IZtCountService.java |
|
||||
| UI/交互 | 需求详情无 AI 区块；会议附件未渲染；测试报告无入口 | 详情页 AI 区块+附件渲染+报告入口 | 前端 3 处 | FR-002/004/008/010/011 | ZT:web_zentao 摸底 |
|
||||
| 数据完整性 | activateddate/approveddate 死字段 | 评审通过补写激活时间 | 用户需求流 | FR-001 | ZT:ZtStoryUser.java:153 |
|
||||
| 权限 | 无新增权限项设计 | 沿用 base_role 菜单权限（$userHasPermission） | — | 全部 | [ASSUMPTION] |
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险确认与应对
|
||||
|
||||
| 编号 | 风险 | 类型 | 等级 | 应对 |
|
||||
|---|---|---|---|---|
|
||||
| R-001 | 无迁移工具，DDL 手工执行 | 技术 | 中 | DDL 可重入+变更说明头；生产执行前备份评审 |
|
||||
| R-002 | 项目单测覆盖率<20%，回归无安全网 | 技术 | 中 | 新 Service 强制单测（正常+异常路径） |
|
||||
| R-003 | 上传接口无鉴权先例（saveOrUpdate 直连） | 技术/安全 | 中 | 二期前决策：沿用/签名/JWT |
|
||||
| R-004 | 考核公式与权重理解偏差 | 业务 | 中 | 三期开工前与 IT 经理逐 sheet 核对 SRC-002 |
|
||||
| R-005 | 一期仅数据模型，无可视成果 | 体验 | 低 | 已在分期中明示；二期即有页面产出 |
|
||||
|
||||
### 9.1 回滚策略
|
||||
|
||||
一期 DDL 为存量表加列，回滚=DROP 新列，不影响存量数据与功能。
|
||||
|
||||
---
|
||||
|
||||
## 10. 里程碑与发布计划
|
||||
|
||||
| 里程碑 | 交付物 | 时间 | 负责方 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| M0 需求确认 | PRD Final（本文档定稿） | 待定 | PM | 进行中 |
|
||||
| M1 一期：数据模型 | 1 项 DDL（zt_story_expand 加列）+实体加字段+回归测试（W≈1~2 人日，CHG-019 砍表后重估） | 定稿后 1~2 天 | Dev | 未开始 |
|
||||
| M2 二期：文件流+接口+页面 | aiBatchAdd+uploadBind+FileTypes 扩展+MD 渲染+页面清单（会议 tab/纪要 MD/需求详情 6 区块）+框架挂钩 | 立项时评估 | Dev | 未开始 |
|
||||
| M3 三期：绩效消费 | 完成率统计+9 岗位报表 | 立项时评估 | Dev | 未开始 |
|
||||
| M4 验收 | 对照本 PRD 与考核方案验收 | — | QA/IT经理 | 未开始 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 其他需求 / 备注
|
||||
|
||||
### 11.2 待后续决策事项
|
||||
|
||||
1. AI 上传接口鉴权策略（二期前）
|
||||
2. 绩效考核与现有 ZtMonthScore/ZtCountController 体系的关系：替换/并存/渐进（三期前，见 Q1-2）
|
||||
3. 验收指标是否结构化（当前结论：富文本够用，后续按需）
|
||||
|
||||
---
|
||||
|
||||
## 12. 证据映射表
|
||||
|
||||
| 章节 | 关键结论 | 证据 | 状态 |
|
||||
|---|---|---|---|
|
||||
| 1 背景 | 6/9 数据项可复用、3 类无承载、AI 指标孤岛 | ZT 代码摸底（2026-07-22，文件:行号） | ✅ |
|
||||
| 3 角色 | 9 岗位+业务方+AI框架 | [SRC-002] 9 sheet、[SRC-001] | ✅ |
|
||||
| 5 方案 | 扩展表模式 | zt_story_expand 先例 [ZT:entity/ZtStoryExpand.java] | ✅ |
|
||||
| 6 FR | 14 条 FR 与 SOP 环节一一对应 | [SRC-001] 流程图+思维导图 | ✅ |
|
||||
| 7 数据模型 | 1 加列+FileTypes 扩展 3 类（MD 文件流 CHG-014；zt_task_extend 已砍 CHG-019） | [SRC-001] 数据模型节 | ✅ |
|
||||
| 7.3 口径 | 11 项指标公式+5 项待确认 | [SRC-002] | ✅ |
|
||||
| 2.2 北极星 | 完成率公式 | [SRC-002] | ✅ |
|
||||
| 3.1 角色诉求 | 各角色考核侧重点 | [SRC-002][ASSUMPTION 部分] | ⚠️ 部分假设 |
|
||||
|
||||
---
|
||||
|
||||
## 13. FR → AC 覆盖矩阵
|
||||
|
||||
| FR | 标题 | AC 数量 | 覆盖状态 |
|
||||
|---|---|---|---|
|
||||
| FR-001 | 用户需求管理 | 2（AC-001-1/2） | ✅ |
|
||||
| FR-002 | 需求讨论会与纪要 MD | 3（AC-002-1/2/3） | ✅ |
|
||||
| FR-003 | PRD 文档管理 | 2（AC-003-1/2） | ✅ |
|
||||
| FR-004 | 需求级 AI 工作量指标 | 3（AC-004-1/2/3） | ✅ |
|
||||
| FR-005 | 验收标准与测试用例管理 | 1（AC-005-1） | ✅ |
|
||||
| FR-006 | 研发任务双通道 | 3（AC-006-1/2/3） | ✅ |
|
||||
| FR-007 | 任务级 AI 工时（豁免） | 2（AC-007-1/2） | ✅ |
|
||||
| FR-008 | AI 代码审查报告 MD | 4（AC-008-1/2/3/4） | ✅ |
|
||||
| FR-009 | 测试任务与 BUG | 1（AC-009-1） | ✅ |
|
||||
| FR-010 | 测试类文档 4 字段 | 3（AC-010-1/2/3） | ✅ |
|
||||
| FR-011 | AI 工作日志 MD | 2（AC-011-1/2） | ✅ |
|
||||
| FR-012 | 工作量指标完成率统计 | 1（AC-012-1） | ✅ |
|
||||
| FR-013 | 九岗位绩效考核报表 | 2（AC-013-1/2） | ✅ |
|
||||
| FR-014 | 大型需求文档齐备自动核查 | 4（AC-014-1/2/3/4） | ✅ |
|
||||
|
||||
**合计：33 条 AC，覆盖 14/14 FR（100%），每 FR ≥1 正常 + ≥1 异常/边界/验证。** 详见 `outputs/acceptance.md`。
|
||||
|
||||
---
|
||||
|
||||
## 14. 系统资产引用
|
||||
|
||||
| 资产类型 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| CodeMap | assets/codemap/ | 已核查：属 fly-home-flow 项目，与本系统无关，不引用 |
|
||||
| DomainMap | assets/domainmap/ | 同上 |
|
||||
| 目标系统代码 | codes/zentao、codes/web_zentao | 直接摸底证据（[ZT:...]），2026-07-22 两轮探查 |
|
||||
|
||||
---
|
||||
|
||||
## 15. 参考资料与索引
|
||||
|
||||
- 来源索引：见 `materials_index.md`（SRC-001 SOP 流程、SRC-002 考核方案）
|
||||
- 代码证据：文中 [ZT:...] 标注（相对 codes/zentao/src/main/java/com/sa/zentao/ 或 codes/web_zentao/）
|
||||
|
||||
---
|
||||
|
||||
## 图表要求自检
|
||||
|
||||
- [x] mermaid 图 ×1（3.3 价值链路）
|
||||
- [x] 表格多张
|
||||
- [x] 端覆盖矩阵已填写（6.1）
|
||||
- [x] 差异点清单已填写（8）
|
||||
- [x] FR→AC 覆盖矩阵已填写（第 13 章，33 条 AC）
|
||||
---
|
||||
|
||||
## 定稿信息
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 定稿版本 | v1.24 Final（基于 prd.md v1.24） |
|
||||
| 定稿时间 | 2026-07-23 |
|
||||
| 审核人 | 用户（逐轮审查 v1.0→v1.24，共 17 轮变更） |
|
||||
| 完整性检查 | P0 全部关闭 ✅；P1×2 按约定延后（Q1-2 三期前、Q1-3 二期前）；每章证据/ASSUMPTION ✅；mermaid+表格 ✅；FR 14 条连续且全有 AC（33 条）✅；端覆盖矩阵 ✅；差异点清单 ✅ |
|
||||
| 配套文档 | dev_plan.md v4.0（开发方案）、acceptance.md（33 条 AC） |
|
||||
| 定稿日待办 | ① 用户建 zentao 需求单给 ID → AI 提交 W（重评后=3.2，见下）+ 上传本 PRD 附件；② 一期开工（zt_story_expand 加 1 列，1~2 天） |
|
||||
|
||||
## 一期工作量重评（demand-assessor 七步，定稿日执行）
|
||||
|
||||
- 功能单元：S=2（zt_story_expand 加列、实体字段+回归测试）
|
||||
- 单元复杂度：B=1.0（1/1/1/1/1）
|
||||
- 技术复杂度：T=4（DB 变更）→ F(T)=1.6
|
||||
- AI 效率：P=17、N1=0、N2=1（老表变更）、N3=1（测试欠账）→ A=15；安全门（覆盖率<20%）→ G(A)=1.0
|
||||
- **W = 1.0 × 2 × 1.6 × 1.0 = 3.2 人日**（原 10.2 因 CHG-014/019 范围缩减作废）
|
||||
Reference in New Issue
Block a user