646 lines
57 KiB
Markdown
646 lines
57 KiB
Markdown
# 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 范围缩减作废）
|