OA/zentao-flow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 根目录文档、脚本、gitignore

Browse Source
This commit is contained in:
guoqibing
2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
workspace/specs/ai-sop-20260723-1024/00_meta/decision_log.md
+89
View File
@@ -0,0 +1,89 @@
# 决策记录
| 时间 | 变更编号 | 事项 | 决策内容 | 影响 FR | 依据 |
|---|---|---|---|---|---|
| 2026-07-23 | CHG-000 | 范围与分期 | 用户确认：PRD 全链路（SOP+绩效）+三期分期；原型暂缓（skip_flags） | 全部 | 用户答复 |
| 2026-07-23 | CHG-001 | 自查修正 | PRD 表名笔误 zt_story_extend→zt_story_expand（11处）；列名 ai_efficiency_coefficient；行号 2 处。证据：ZtStoryExpandMapper.xml:34 实际 FROM 表名、mapper 列名 snake_case | FR-004/012 | 代码复核 |
| 2026-07-23 | — | 流程映射补强 | 用户质询"是否结合现有代码工作流"后增补 prd.md 6.3 节（SOP 14 步×现有工作流逐步映射） | 全部 | 用户反馈 |
| 2026-07-23 | — | 开发方案产出 | 用户要求出可审查的开发方案 → outputs/dev_plan.md v1.0（一期数据模型：4 DDL+实体+单测 12 场景+评审检查单，W=10.2 分解） | FR-004/007/008/011 | 用户要求 |
| 2026-07-23 | CHG-002 | 新增 FR-014 | 用户质询抽检可行性后明确：考核只判「缺失」不判内容（SRC-002 原文），人工抽检退化为月度确认+异议复核 → 新增 FR-014 大型需求文档齐备自动核查（③期，zt_month_score 复用）；FR-013 剔除该项 | FR-013/014 | 用户反馈+SRC-002 |
| 2026-07-23 | CHG-003 | FR-008 规则细化 | 用户三连问后明确：触发=需求全部开发任务完工（框架内自动/框架外负责人手动）；上传=每轮审完即传含未通过轮次（考核初审/复审扣分依赖逐轮记录）；通过前不得流转测试 | FR-008 | 用户反馈+SRC-001/002 |
| 2026-07-23 | CHG-004 | 补绩效计算模型 | 用户指出"绩效计算 PRD 里没看到"→ 新增 7.5 章：SRC-002 九岗位算分规则全量结构化（权重/扣分/加分/通用规则），逐项标注自动化程度（✅系统可算/🔶半自动/❌人工）与数据来源；暴露 2 个待确认缺口（问题管理文档、设计文档质量评审承载） | FR-012/013/014 | 用户反馈+SRC-002 |
| 2026-07-23 | — | 定稿日约定（用户确认） | 本 PRD 遵循自身 FR-003 规矩：定稿日用户在 zentao 建需求单并提供 ID → AI 一次完成 W=10.2 提交 + PRD 附件上传。（zt_ai_work_log 日志记录待一期表建后可补） | 全部 | 用户确认 |
| 2026-07-23 | CHG-005 | 口径补全与歧义标注 | 用户追问公式是否列清 → 7.3 补 5 个任务级公式；标注 3 项待确认：总分算法（0~100×权重加权为解读）、线上Bug率单位（xlsx「×100%≤5‰」矛盾，按‰）、检出率申诉需人工流程 | FR-012/013 | 用户反馈+SRC-002 |
| 2026-07-23 | CHG-006 | 任务创建双通道（用户拍板） | zentao 支持 AI 框架上传拆分任务（②期新增任务批量提交接口）；AI 上传任务创建人=系统专用账户「ai」（zt_user 新建）；人工建任务保留；覆盖开发任务+测试任务（type=test 指派测试）；AI 指标随任务一并写 zt_task_extend；是否需人确认后生效挂待确认 | FR-006/007 | 用户指定+SRC-001 |
| 2026-07-23 | CHG-007 | AI 任务状态确认 | 用户确认：AI 提交任务初始状态=未开始（wait），走现有任务流程（开始→完成→审批→关闭），无特殊"待确认"状态——CHG-006 遗留问题关闭 | FR-006 | 用户确认 |
| 2026-07-23 | CHG-008 | 框架侧触发挂钩入scope | 用户追问"本框架有没有触发上传的功能"→ 盘点：仅 workload_eval 已通（submit_assessment.py），其余 7 类无触发 → FR-011 补规则：二期交付=zentao 接口+框架各技能挂钩两端，照 submit_assessment.py 模式；事件发生即上传不补传；日志与内容表分工明确 | FR-011 | 用户反馈+现状盘点 |
| 2026-07-23 | CHG-009 | SOP 符合性核查通过 | 用户要求对照 SRC-001 核查 PRD → 流程 18 步/数据模型 6 类/提交动作 8 项全覆盖；修补 2 处：FR-001 审批时间口径（=revieweddate）、6.3 步骤 10 同步双通道表述 | 全部 | 用户要求+SRC-001 |
| 2026-07-23 | — | 开发方案 v2.0 重生成 | 用户要求基于 PRD v1.8 重出方案 → dev_plan.md 全量重写为三期全局实施规格（一期详细+二期接口/挂钩/页面概要+三期绩效概要），替代 v1.x 补丁系列 | 全部 | 用户要求 |
| 2026-07-23 | — | 开发方案 v2.1 深化 | 用户指出不够详细 → 一期深化至施工级（4 个 DDL 全文含说明头/回滚/可重入、实体字段表、Service 完整签名、12 单测 Given/When/Then 明细、D1-D10 按天步骤）；二期深化至接口级（3 接口请求/响应/错误/幂等+挂钩脚本规格+页面字段清单） | 全部 | 用户反馈 |
| 2026-07-23 | CHG-010 | ID 流转约定 | 用户问上传所需 storyId/taskId 从何而来 → PRD 新增 5.6：建单产号→回填 PRD 关联需求ID+框架工作区→上传以此为键；taskId 由 aiBatchAdd 响应返回；dev_plan.md 接口响应示例含 taskIds | 全部 | 用户反馈 |
| 2026-07-23 | — | 开发方案 v2.2 三期补全 | 用户要求三期补全 → dev_plan.md 第 4 章重写为详细规格：三层架构+2 新表（zt_perf_config 规则配置化消化口径歧义、zt_doc_check 核查快照）+13 项指标取数设计+FR-014 全流程+6 接口 4 页面+对拍验收 | 全部 | 用户要求 |
| 2026-07-23 | — | 开发方案文件改名 | 用户要求 → outputs/frd.md 重命名为 outputs/dev_plan.md，引用已同步（decision_log/summary） | 全部 | 用户要求 |
| 2026-07-23 | — | 绩效数据盘点 | 用户问现有数据是否够算绩效 → 四层结论：A 约半数指标存量可算；B 2 个新口径坑（Bug 普通/重大映射、产品助理验收链断裂——zt_story_user 验收字段闲置）；C 一二期建成才够（完成率/文档齐备/代码质量）；D 纯人工项。B 类已补入 PRD 7.3 待确认（3→5 项） | FR-012/013/014 | 代码证据+SRC-002 |
| 2026-07-23 | CHG-011 | 多人协作前提 | 用户指出框架非单人使用 → 5.6 补第 6 条：ID 共享载体=PRD 文档（非个人工作区）；并发由 zentao 状态机约束；ai 账户与使用者解耦；上传接口鉴权从"二期前再定"升级为**二期必决项** | 全部 | 用户反馈 |
| 2026-07-23 | CHG-012 | ~~用户补充①~~（理解有误） | 初解为 PRD-MD（FR-003），用户澄清后作废，见 CHG-013 | — | — |
| 2026-07-23 | CHG-013 | 补充①~⑧接收与①的修正 | ①真实含义：会议纪要 MD（会议页面多次上传+在线查看+操作人/时间/会议人展示）→ 已改正至 FR-002，FR-003 恢复。②~⑧ 见 CHG-014 澄清结果 | FR-002/003 | 用户澄清 |
| 2026-07-23 | CHG-014 | **架构级变更：AI 文档走 MD 文件流（用户定）** | Q1 澄清：提交工时/指标时录入 storyId 并框架保存（维持 5.6 约定，无新建需求接口）；Q2：**不建 zt_ai_work_log/zt_ai_code_review 两表**——工作日志与代码审查报告均为 MD 文件，研发需求页加按钮上传+在线查看；Q3：测试用例=仅查看/下载，测试报告=补充上传（2 个文件）；Q4：测试报告挂研发需求级。一期缩至 1 表+1 列，W 需重估；FileTypes 扩展 aiCodeReview/aiWorkLog/testReport；FR-014 判定改走 zt_file | FR-008/010/011/014、一期范围 | 用户拍板 |
| 2026-07-23 | — | 开发方案 v3.0 重写 | 按 CHG-014 全量重写 dev_plan.md：文件流架构（数值走表/文档走 MD）；一期瘦身（1 表+1 列，W≈3.8，单测 6 场景）；二期=FileTypes 扩展+uploadBind+MD 渲染+页面清单（补充⑦会议 tab、①纪要 MD、⑧需求详情 6 区块）+aiBatchAdd+upload_md.py 挂钩；三期调整 FR-014 判定源与代码质量取数 | 全部 | 用户要求 |
| 2026-07-23 | CHG-015 | 同步性清扫 | 用户问"两份文档都同步了吗"→ 自查抓 5 处残留：PRD 4.1 接口行/5.6 关联/7.4 埋点/6.3 步骤4/12 证据映射；dev_plan 的 aiBatchAdd"见 v2.x"悬空→补回完整规格。grep 复核两文档无旧表名残留 | 全部 | 用户追问 |
| 2026-07-23 | CHG-016 | 全文核对再抓 16 处 | 用户要求"检查 PRD 是否按最新写的"→ 全文通读核对：版本号/目标截止/约束/W 值/方案概述/zt_ai_* 残留/端矩阵/页面行/**补⑦漏录（需求讨论会议 tab）**/zt_testtask 误标/里程碑/证据映射计数。教训：架构级变更后必须全文核对而非局部清扫 | 全部 | 用户要求 |
| 2026-07-23 | CHG-018 | zt_file 加 url 字段（用户指定） | MD 附件需直接可访问链接 → zt_file 二期加列 url varchar(512)（pathname=存储路径、url=访问地址）；zt_file 属禅道原生表，破例按 zt_* 自研扩展字段惯例处理；uploadBind/MdPreview 优先取 url | FR-002/008/010/011 | 用户指定 |
| 2026-07-23 | CHG-019 | 砍 zt_task_extend（用户拍板） | 用户指出该表"没啥用"→ 核实：evaluation_time 与 zt_task.estimate 冗余（aiBatchAdd 已映射）、ai_workload_index 无消费方（绩效用需求级指数）→ 不建表；AI 工时入 estimate；任务级指数豁免（SOP 数据项，三期按需恢复）；一期缩至 1 列 W≈1~2 人日 | FR-007、一期范围 | 用户拍板 |
| 2026-07-23 | CHG-020 | zt_meeting 加 url 字段（用户指定） | 会议表直接存纪要 MD 访问链接（直取不绕 zt_file）；多份纪要冲突按"存最新一份"处理（每次上传刷新，历史份走 zt_file 列表） | FR-002 | 用户指定 |
| 2026-07-23 | CHG-021 | zt_story 加 5 个文档 url 字段（用户指定） | 用户指出测试为 2 个文件 → zt_story 加 5 列；FileTypes 增 testCase；zt_story 属禅道核心表，破例按用户拍板处理 | FR-005/008/010/011 | 用户指定 |
| 2026-07-23 | CHG-022 | 测试三字段澄清（用户纠正） | 测试用例（下载）/测试报告·供下载/测试报告·提交 为三个字段 → zt_story 6 列（test_report 拆 download/submit）；FileTypes 增 testReportSubmit；FR-014 判定用提交件 zt_file(testReportSubmit) | FR-010/014 | 用户纠正 |
| 2026-07-23 | CHG-023 | 补 code_review_status 字段（用户指出） | 审查结果原只在 MD 内容里系统不可查 → zt_story 加 code_review_status（pass/reject/NULL），上传时解析写入；SOP 卡点可系统级强制（未 pass 禁提测试报告）；zt_story 共 7 列 | FR-008 | 用户指出 |
| 2026-07-23 | CHG-024 | ~~补 test_report_status~~（误解） | 用户澄清"第4个是别的文档"非状态字段 → 撤销，见 CHG-025 | — | — |
| 2026-07-23 | CHG-025 | 测试 4 文档字段定稿 | 用例下载/模版下载/模版填完提交（第3）/其他测试文档（第4，testOther+test_other_url）；撤销 test_report_status；FileTypes：testCase/testReport/testReportSubmit/testOther；zt_story=7 url 列+code_review_status | FR-010 | 用户澄清 |
| 2026-07-23 | — | **定稿（v1.24 Final）** | 用户指令定稿 → 完整性检查通过（P0 关闭；P1 Q1-2/Q1-3 按约延后至三期/二期立项前；33 AC 全覆盖）→ outputs/prd_final.md；一期 W 重评=3.2 人日（S=2/B=1.0/F=1.6/G=1.0，原 10.2 作废）；下一步：用户建需求单给 ID → 提交 W+PRD 附件 → 一期开工 | 全部 | 用户指令 |
| 2026-07-28 | — | 三期口径锁定+开工授权 | 用户指示"全跑了"→ PRD 7.3 五项待确认全部按默认锁定：①总分=各项0~100×权重求和；②Bug率按‰；③检出率申诉=系统入口+人工裁定（技术负责人）；④普通/重大 Bug=severity 1~2 重大、3~4 普通；⑤产品助理验收链=补写 zt_story_user 验收字段。另 2 缺口：问题管理文档/设计文档评审均暂不建承载（人工/半自动录入） | FR-012/013/014 | 用户授权 |
| 2026-07-23 | — | 开发方案 v4.0 全量重生成 | 用户要求按最新 PRD 出方案 → dev_plan v4.0（依据 PRD v1.24）：一期 1 列（W≈1~2）；二期 3 项 DDL（zt_file.url/zt_meeting.url/zt_story 8 列）+FileTypes 6 类+uploadBind 字段映射+MD 渲染+aiBatchAdd+页面清单+upload_md.py 挂钩；三期承接 v2.2 详细版 | 全部 | 用户要求 |
| 2026-07-29 | CHG-026 | 线上Bug/产品缺陷率 5‰ 豁免补实现 | 全量公式核对（xlsx 9 岗位 × 61 行规则）发现 PRD §7.3「≤5‰ 满分」未实现（P0）→ AbstractWeightedBugCalculator 加 exemptPerMille 分支（分子=当月上线需求 prod Bug 数、分母=Σestimate），id 4/11/19/24 规则加参数；tester 口径不变；单测+3，perf 54 全绿 | FR-013 | SRC-002 + PRD §7.3 |
| 2026-07-29 | CHG-027 | 框架验收指标新字段+接口（用户拍板） | 老验收标准 zt_storyspec.verify 不动 → zt_story_expand 加 acceptance_criteria（MEDIUMTEXT，Given/When/Then MD），经 /zt-story-expand/saveOrUpdate 上传，双通道并存；DDL 已入 161+sql 迁移文件；单测+1 | FR-005 | 用户拍板 |
| 2026-07-29 | CHG-028 | 饱和度达标工时口径修正（用户拍板） | 实现原误用老系统（工作日×8−请假）×0.75 口径 → 改 xlsx/PRD §7.3 口径：（当月工作天数 − 请假小时÷8）×5，请假半天按 0.5 天扣；分子=zt_effort.consumed 实绩；老月报（分配工时/0.75 口径）不动，两处数值差异属口径并存 | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-29 | CHG-029 | 老模块饱和度口径统一（用户拍板"再老的改"） | 月报列表/地盘绩效/项目组工作量统计三处 saturation 统一为新口径：分子=实绩工时(zt_task.consumed 全状态任务)、分母=(工作天数−请假小时÷8)×5；buildXMZLScore 达标工时显示同步；原口径（分配工时 estimate、(×8−请假)×0.75、地盘含closed/cancel 任务致 91/104 分叉）废弃 | 老月报/地盘绩效 | 用户拍板 |
| 2026-07-29 | CHG-030 | aiBatchAdd 工时预算校验（用户拍板） | 拆任务工时（已有任务 estimate + 本批新增，重复跳过项不计）不得超过需求评估工时 zt_story_expand.evaluation_time，超则整批拒绝并报明细；无评估工时不设防；ZtTaskServiceImpl 注入 storyExpandService 实现 | FR-006 | 用户拍板 |
| 2026-07-29 | CHG-031 | 工时匹配规则归位框架侧（用户纠正） | 用户明确"不是在禅道做"：需求评估工时与任务工时同源（框架产出），拆任务时 Σ任务工时 = 需求评估工时（全量分摊，可分批逼近）；规则写入 PRD FR-006 规则5 + tgassist 技能 PJM 工时匹配纪律；禅道 CHG-030 上限校验仅作兜底保留 | FR-006 | 用户纠正 |
| 2026-07-29 | CHG-032 | 撤销禅道侧工时校验（用户明确"禅道不能做校验"） | CHG-030 代码+4 单测全部回滚（aiBatchAdd 恢复原状，4/4 绿）；工时匹配纪律只在框架侧执行（PRD FR-006 规则5、tgassist PJM 纪律已同步去除"兜底"表述） | FR-006 | 用户明确 |
| 2026-07-29 | CHG-033 | 工时匹配最终定稿：仅框架侧 | 用户复核后拍板"保持现状"：工时匹配纪律只在框架侧执行（拆任务 Σ工时=需求评估工时），禅道 aiBatchAdd 完全无校验；CHG-030 代码不回滚恢复 | FR-006 | 用户拍板 |
| 2026-07-29 | CHG-034 | 达标工时严格按 xlsx 团队口径（用户拍板） | 替代 CHG-028"谁请假扣谁"：达标工时(每人)=（工作天数×团队人数 − 团队请假小时÷8）×5÷团队人数，团队=后端+前端（zt_user.user_type=KFZ，@EnumValue=3），请假全团队平摊每人相同；WorkSaturationCalculator+IZtCountService 共 4 处统一 teamExamineTime；单测 15/15 绿（含 2 人团队请假 4h 平摊用例） | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-29 | CHG-035 | 三期绩效页面下线（用户拍板"不需要这些页面"） | /perf/report、/perf/docCheck、/perf/config 三页面入口下线：2026 库 base_menu 1539-1551+授权 37 行删除（备份 sql/20260729_insert_perf_menu.sql 可恢复）；人工评分走月报「绩效」按钮（现有老流程）；页面代码/表/规则数据保留未删，随时可恢复 | FR-012/013/014 | 用户拍板 |
| 2026-07-29 | CHG-036 | 老绩效弹窗得分改新 Excel（用户拍板"改成新的"、计算只在后端） | 新建 PerfScoreRules 纯函数规则类（SRC-002 后端口径：及时完成25分段/Bug密度30无截断/饱和度20；代码质量10/文档质量10/不规范行为5满分默认人工改）；接入 buildKFZScore（弹窗/月报 myWorkScore 数据源）；buildCsScore 为无调用方死代码顺带对齐；CS 测试分支不动；前端不改（totalScore 行本就前端 sum 六+二项） | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-30 | CHG-037 | 老绩效弹窗全岗位切新 Excel 口径（延续 CHG-036 方向） | 月报「绩效」弹窗 项目经理/王宇航变体/产品经理/产品助理/运维/测试/UI 得分全部由新绩效引擎（zt_perf_config，score×weight）加权产出，人工评审项满分默认弹窗手改；PerformanceDTO+7 字段；buildXMJLScore/buildCPJLScore/buildXMZLScore 重写、buildYwScore 新增（含 YW 调度分支）；测试/UI 及时率规则入 PerfScoreRules；前端 performance.vue XMGLY/CPJL/XMZL 区块重写+YW 区块新增+王宇航 account 变体块+juedgeRole 加 YW；单测+2，8086 API 六账号+8089 四岗位弹窗截图实测 | FR-013 | CHG-036 用户拍板方向延续 + SRC-002 |
| 2026-07-30 | CHG-038 | KFZ 前后端工程师分流（用户拍板：加标识+表单下拉维护） | 新 Excel 前端/后端为两张表（前端饱和度30%、无文档质量项、代码质量 flat），user_type 只有 KFZ → zt_user 加 dev_direction 列（frontend/backend，NULL 按后端）；用户新增/编辑表单在「用户属性=开发者」时显示「开发方向」下拉（必填）；buildKFZScore 按方向分流（PerfScoreRules 饱和度满分参数化 30/20）；performance.vue KFZ 双区块渲染；单测+1，8086 API+弹窗+表单三处截图实测；现有 KFZ 待用户名单一次性初始化 | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-30 | CHG-039 | workloadRatePrd 人员匹配修复（用户质疑魏冬霞 0 分引出） | product_person 列实际存中文姓名，计算器按 account LIKE 恒空 → 得分恒 0 属误判；改按昵称匹配 account 兜底；魏冬霞 6 月实测 0→40（满分）、孙世超 0→20；李语嫣仍 0 系数据缺失（expand 无其行）；8085 需再次重启 | FR-012/013 | 用户质疑 + 代码复核 |
| 2026-07-31 | CHG-040 | 0 分专项排查+opsMajorTask 匹配修复（用户要求全查） | 9 账号全量 0 分下钻：opsMajorTask 同 CHG-039 类匹配 bug（belong_to_user 存姓名）→ 按昵称修复，岑海峰 7 月实测 13.2；版本计划完成率 0 系发布需求 estimate 全空致分母 0（口径待拍板：补数据/按个数算/满分豁免/维持）；其余 0 分均为真 0 或数据缺失（刘圣清无任务、魏冬霞 71%、李语嫣无数据） | FR-013 | 用户要求 + 代码复核 |
| 2026-07-31 | CHG-041 | 绩效弹窗「绩效数据」列补过程值（用户要求给分子分母） | 计算器经 ThreadLocal rawDetail 透出分子/分母/率 → scope Item.rawDetail（随快照落库）→ DTO.perfRawDetail → 弹窗 `#itemKey` 绑定渲染；覆盖工作量指数/版本计划/Bug率/准时率/运维5项/文档齐备共 7 类计算器、五岗位区块 19 行；单测 63 绿，8086 实测孙世超/蒋恒明细正确 | FR-012/013 | 用户要求 |
| 2026-07-31 | CHG-042 | 项目经理 PRD 完成率改团队口径（用户拍板"是项目所有人"） | 项目经理（含王宇航变体）workloadRatePrd：范围=全部需求、分母=工作天数×5×产出人数（与团队完成率同数据源，仅扣分规则不同）；产品经理/助理维持个人口径；孙世超/蒋恒 6 月实测 20→15.6（78.87%×0.2） | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-31 | CHG-043 | 项目经理两项完成率改项目口径（用户拍板"按照迭代来"，替代 CHG-042 部门口径） | workloadRatePrd/workloadRateTeam：分子=他当月窗口内（begin/end 落当月）执行关联产品的需求指数和，分母=工作天数×5×执行内 KFZ 成员去重数；无在窗执行该项 0 分；产品经理/助理个人口径、其余岗位部门口径不变；孙世超 106.06%→双满分、蒋恒 54.99%→10.8/23.1 | FR-013 | 用户拍板 |
| 2026-07-31 | CHG-044 | 达标工时全链路上弹窗（用户要求"分子分母都要列出来"） | DTO+teamWorkDays/teamLeaveDays/teamTargetTime 三字段，fillTeamExamine 统一填充；KFZ 弹窗饱和度行展示 实绩/团队总工作天数/团队达标总工时/人均达标工时/饱和度 全链；郭尚雨 6 月实测 131/273/1365/105/125% | FR-013 | 用户要求 |
| 2026-07-31 | CHG-045 | 版本计划完成率改工作量指数加权（用户拍板"workload_index 用这个"） | 加权源 zt_story.estimate（全线未填失效）→ zt_story_expand.workload_index（String 列容错解析，无指数按 0 权重）；孙世超 6 月实测 0→5.4（477.1/658.21=72.48%）；123 个发布仅 34 个有指数，覆盖率依赖评估流程 | FR-013 | 用户拍板 |
| 2026-07-31 | CHG-046 | 《AI项目文档更新记录》独立承载全链路（用户拍板"加字段+功能完善+前端展示"） | zt_story 加 ai_doc_update_url；FileTypes 增 aiDocUpdate，uploadBind 刷新该列；FR-014 核查判定由 aiWorkLog-doc_update 类（从未产出）改 zt_file(aiDocUpdate)；研发详情新增文档区块（列表+上传）；6566 全链路实测（上传→url 刷新→fileList→区块渲染） | FR-008/011/014 | 用户拍板 |
| 2026-07-31 | CHG-047 | 文档齐备改实时字段判定+项目口径（用户拍板"url 字段直接判断"） | DocReadyScoreCalculator 重写：大型需求五个 url 字段非空即在、缺失×2 扣完截止；归属由 assignedTo（错位，扣分挂 KFZ/CS 头上）改项目口径（∩项目经理当月窗口内执行关联产品）；不再读 zt_doc_check 快照/月末 job；孙世超 6 月实测 10→6（4 需求×5 类全缺=20 份扣 40） | FR-014 | 用户拍板 |
| 2026-07-31 | CHG-048 | PRD 完成率项目口径扩到产品经理/助理（用户拍板"跟项目管理员一样的方案"） | workloadRatePrd 项目口径分支扩至 productManager/productAssistant（四角色统一：范围=在窗执行关联产品、分母=执行内 KFZ 成员）；product_person 个人口径转兜底；魏冬霞 6 月 299.08%→106.06%（556.83/525h）仍 40 满分、李语嫣 0（产品 145 无数据） | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-31 | CHG-049 | 版本计划完成率改项目口径（用户拍板"孙世超是飞侠的为啥不区分"） | versionPlanRate 由全表统计改项目口径（∩在窗执行关联产品的发布需求，指数加权不变）；孙世超 5.4→9.4（150 单产品 92.35%）、王宇航 0（145 覆盖率 1/72 失真，评估流程未覆盖前该项不可用） | FR-013 | 用户拍板 |
| 2026-07-31 | CHG-050 | Bug 率 5‰ 豁免分母改任务工时+项目口径（用户拍板"需求工时是任务sum"） | 豁免分母 zt_story.estimate（全空→恒豁免失效）→ 上线需求 devel 任务 estimate 合计；四角色上线需求∩项目关联产品；车服加测试 Bug（2566）实测：孙世超 10→9.7（6.04‰ 超线扣 3）、魏冬霞 14.55、王宇航 10 豁免 | FR-013 | 用户拍板 + SRC-002 |
| 2026-07-31 | CHG-051 | 引擎扣分统一为加权尺度（用户拍板"10分满分 10-2"） | 原 100 分制扣分×权重（效果=字面 1/10）改 xlsx 字面加权扣分（scaleDeduct 按 1/权重 放大），接入 rate/Bug/运维频次/文档齐备四处；孙世超 6 月预期：文档齐备 6→0、线上Bug 9.7→7、团队完成率 26.7→19.0、版本计划 9.4→4；161 库连接耗尽实测待补 | FR-012/013 | 用户拍板 + SRC-002 |
| 2026-07-31 | CHG-053 | 绩效弹窗跟随月报选中产品集（用户拍板"按照当前选择产品"） | 下拉 program 经 editDialog 透传 performance→myWorkScore(project 参数)；后端 pids 改选中产品集+引擎项目口径走 program 上下文（ThreadLocal，空则回退本人项目）；workloadRateTeam 项目口径同步扩至四角色（魏冬霞 139 下 1365h/0 → 525h/106.06%/20）；孙世超 139=双满分/vp4/bug7/doc0、119=全 0 实测分化 | FR-013 | 用户拍板 |
| 2026-07-31 | CHG-054 | CS 测试需求范围修正（用户拍板"先修复"） | 缺陷检出率的测试需求范围由仅 assignedTo（孙颖 6 月 3 个，漏算）改 assignedTo ∪ zt_story_expand.test_person 指定（24 个）；孙颖 5 月检出率 48%→满分 30（修复前恒 0），6 月真 0（无检出） | FR-013 | 用户拍板 |
| 2026-08-10 | CHG-056 | 绩效导出换新版式（用户拍板"改"） | 9 岗位新模版（含王宇航变体/前后端分离/新增运维）自 SRC-002 生成；7 generator 重写+新增 generatorYwExcel/YW 分支；修复 openpyxl inlineStr 单元格致 POI 占位符替换失效（writeXlsx 先置空再写）；合并还原并行改动覆盖的 CHG-036/038/054/055；导出实测 28 sheet 无残留占位符、前后端模版正确分流 | FR-013 | 用户拍板 |
| 2026-08-10 | CHG-057 | CS 测试文档齐备改实时字段判定（用户拍板口径） | 范围=test_person∪assignedTo 本月发布需求；判定=test_case_url+test_report_submit_url（提交件，AI 模版不计）非空，缺一份扣 3（25 分项扣完）；本月无需求满分；弃写死 25；孙颖 6 月缺失 46→0、无需求月满分 25 实测 | FR-010/013 | 用户拍板 + SRC-002 |
| 2026-08-11 | CHG-058 | 需求文档拆独立区块（用户拍板"可以加类型/入口处改/顺带前端"） | FileTypes 增 storyPrd（uploadBind 刷 prd_url，story 类型不动不影响他人接入）；upload_md.py 入口需求文档改 storyPrd；详情页新增「需求文档」区块；6566 全链路实测；郭其兵提交 dc0b5a5 收编此前前端工作，14 点未提交部分已从 F:\zd 恢复 | FR-002/011 | 用户拍板 |
| 2026-08-04 | CHG-056 | Bug 分级口径以老弹窗为准（用户拍板"老的为准"） | 撤销 07-28 锁定的"severity 1~2 重大、3~4 普通"，恢复老弹窗 getBugFindScore 口径：**severity 1=重大、2/3/4=普通**；同步修三期引擎 AbstractWeightedBugCalculator.countMajor/countNormal、DefectFindRateCalculator major/normal 两处（原按 1~2 重大写）；PRD 7.3 待确认第 4 项标记已决。影响：6 月 sev2 的 99 个 Bug 由重大降为普通，线上 Bug 率/产品缺陷率"重大扣 10 分"命中大幅减少；孙颖 5 月 12 个 sev2 仍按普通（12 加权/148h=8.1%→6 分不变） | FR-012/013 | 用户拍板 + 老弹窗代码 |
| 2026-08-06 | CHG-057 | 需求详情页不展示代码审查通过/不通过状态（用户拍板"代码审查报告不需要通过或者不通过在需求详情页面"） | 「代码审查报告」区块状态徽标（通过/未通过/未审）移除，codeReviewStatusText computed 删除；提交测试报告卡点（FR-008）与 code_review_status 后端字段保留不动 | FR-008 | 用户拍板 |
| 2026-08-06 | CHG-059 | aiBatchAdd 补历史留痕（用户报缺陷"AI 拆的任务没有记录"） | 每个新建任务写需求级 zt_action（沿用 uploadBind 的 XQ+BJ 模式，extra=指派账号）；skipped 不写；单测+1 全绿；8086 实测通过；18563/18564 已补录 | FR-006 | 用户报告 + zt_action 全库零 task 记录证据 |
| 2026-08-06 | CHG-060 | aiBatchAdd 补任务级留痕（用户指出手工拆任务本有历史、AI 未走同一流程） | 每个新建任务增写 task 级 zt_action（RW+XJ/opened，与手工建任务同形状）；单测+断言全绿；8086 实测双写通过；18563/18564 已补录 | FR-006 | 用户指正 + ZtTaskServiceImpl:681 手工流程证据 |
| 2026-08-06 | CHG-061 | AI 通道接口鉴权落地+ai 永久 token（用户拍板"zt_action 创建人、任务创建人都要 token 的"） | saveOrUpdate/aiBatchAdd 限 ai token；uploadBind 需登录态（前端在用）；创建人全部改取 token 身份；token 存 .claude/ai_token.txt；两框架脚本自动带头、默认地址改本地 8085（"别用正线的 url"）；单测 24 全绿；8086 三×三矩阵实测通过 | FR-004/006/008/011 | 用户拍板 + R-003/DT4 二期必决项 |
| 2026-08-06 | CHG-062 | 批拆留痕合并为一条（用户拍板"一次上传多个任务是不是应该就一条记录"） | 需求级每批次一条汇总（个数+序号+各任务名称/类型/工时/指派中文名+跳过数）；任务级维持每任务一条；单测 6/6 绿；8086 实测通过；9130 存量记录已合并 | FR-006 | 用户拍板 |
| 2026-08-06 | CHG-063 | 文档区块归集「需求文档」tab（用户拍板"把文档区块放在需求的一生后面加一个 tab 需求文档"） | 6 文档区块（用例模版/提交报告/其他文档/审查报告/工作日志/更新记录）左栏→右栏新 tab 第三位；左栏保留基础信息区块；编译+断言+页面实测通过 | FR-002/005/008/010/011 | 用户拍板 |
| 2026-08-06 | CHG-064 | 产品助理弹窗前端还原为 git 老版（承接 08-05 拍板"除产品和项目经理其他撤回到 git 版本"） | 08-05 还原了后端未还原前端致 XMZL 前后端错配显示空值；performance.vue XMZL 块还原 HEAD 版；李语嫣弹窗实测渲染正常（总计 80） | FR-013 | 用户报告 + 08-05 拍板 |
| 2026-08-06 | CHG-065 | 产品助理+UI 弹窗改新 Excel 口径（用户拍板"按照新的excel来"+"ui人员的也更新掉"，撤销 CHG-064/08-05 对该两角色的还原） | buildXMZLScore 重建为引擎驱动（PRD50/验收20人工/缺陷率15/响应10/主动5+rawDetail）；buildUiScore 及时率走 PerfScoreRules.uiPunctualityScore（修 90 边界）；前端 XMZL 区块恢复新版；8086 API 实测值与 CHG-037 时期一致；8085 待重编译重启 | FR-013 | 用户拍板 + SRC-002 |
| 2026-08-06 | CHG-066 | XMZL 弹窗列错位修复（用户报"产品缺陷率/问题响应和解决跑到绩效数据列"） | 类目格 v-if 渲染机制下 rowspan=2 覆盖不足致整行左移；rowspan 改 4；实拍验证对齐+数值正确（总计 50） | FR-013 | 用户报告 |
| 2026-08-06 | CHG-067 | Bug 需求关联字段 story→toStory（用户拍板"story 字段应该没用 启用的是toStory"） | 全库证据 story 死字段（prod 0/76、dev 0/2433）；4 处死字段查询修复（豁免计算器/CPJL展示/按需求查Bug/关需求联动关Bug）；王宇航 2 月实测 100→40（2 普通 Bug 5.95‰ 超线）；8085 待重编译重启 | FR-012/013 | 用户拍板 + 全库字段分布证据 |
| 2026-08-06 | CHG-068 | 需求文档 tab 视觉重设计+tab 头间距（用户拍板"tab 靠太近"+"页面太丑优化他"） | App.vue 全局 4rem 定宽致长标题粘连→width:auto+兄弟 margin；六文档区块重设计为分节卡片（标题竖条/份数徽章/文件行/分组/卡点黄条/轮次徽章）；绑定零改动；实拍验证通过 | FR-002/008/010/011 | 用户拍板 |
| 2026-08-06 | CHG-070 | productPageList 性能修复（用户报 5 秒） | zt_bug.steps MEDIUMTEXT 44MB 全字段拉取为主因；三处全量查询修剪 select 列；端到端 5s→0.2~0.5s；jar 已重打 | 性能 | 161 SQL 实测 + 8086 端到端实测 |
| 2026-08-06 | CHG-071 | exportScope 快照三格式兼容+NPE 修复（用户问"要按新修改调整吗"） | scope_json 三格式（老DTO/引擎/docCheck）统一按老DTO解析致 NPE；resolveScoreDto 三格式分流+统计字段回填+人工分覆盖；8086 实测罗勇 6 月导出成功 | FR-013 | 用户报告 + luoyong docCheck 快照实证 |
| 2026-08-06 | CHG-072/073 | myWorkScore 快照分流 + userList 脱敏（用户拍板"1 2 都做，做完打包"） | 弹窗对引擎/docCheck 快照改走新算+人工覆盖，老快照快路径保留；userList 剔除 password 列（按属性名匹配）；8086 双项实测通过；jar 17:54 | FR-013/安全 | 用户拍板 + 8086 实测 |
| 2026-08-17 | CHG-077 | uploadBind 入口 story→storyPrd 归一化 + 8 需求错传修复（用户报 9209 md 落附件，拍板"改"/"一起"） | UploadDTO.normalizeObjectTypeForBind + controller 调用；单测 17/17 绿；200 库 18 文件改 storyPrd + 8 需求 prd_url 校正回 PRD；待郭其兵提交部署 | FR-002/011 | 用户报告 + zt_file/zt_action 实证 |
| 2026-08-17 | CHG-078 | 用户需求导出/分页加「迭代版本」列（用户拍板） | DTO 增 execNames（index=5，后续顺移）；buildExecNames 去重排序拼接；两处填充点接入；前端零改动；单测 4/4 绿；待郭其兵提交部署 | 用户需求列表 | 用户需求 + 列表页已有列实证 |
workspace/specs/ai-sop-20260723-1024/00_meta/evidence_index.md
+36
View File
@@ -0,0 +1,36 @@
# 证据索引
> 归档视角的证据台账。原 PRD 内部证据映射见 `01_input/prd_final.md` 第 12 章。
## 用户资料（SRC）
| ID | 资料 | 位置 | 用途 |
|---|---|---|---|
| SRC-001 | AI下的开发SOP流程（新版） | 01_input/references/AI下的开发SOP流程（新版）.pdf | SOP 14 步流程、8 类 AI 工作日志、数据模型节 |
| SRC-002 | 信息技术部绩效考核标准-新版 | 01_input/references/信息技术部绩效考核标准-新版 - AI下的考核方案.xlsx | 9 岗位算分规则、11 项指标口径、权重表 |
## 代码证据（ZT）
| ID | 位置 | 支撑结论 |
|---|---|---|
| ZT-001 | codes/zentao/src/main/java/com/sa/zentao/controller/ZtStoryExpandController.java:23 | 需求级 AI 指标上传通道既有先例（/zt-story-expand） |
| ZT-002 | codes/zentao/src/main/java/com/sa/zentao/service/IZtCountService.java | 绩效统计现状不消费 AI 指标（痛点 #1） |
| ZT-003 | codes/zentao/src/main/java/com/sa/zentao/entity/ZtStoryExpand.java | 扩展表模式先例（一期加列落点） |
| ZT-004 | codes/zentao/src/main/java/com/sa/zentao/entity/ZtStoryUser.java:120,153 | 死字段 activateddate/approveddate |
> 完整 ZT 文件：行号级证据清单见 prd_final.md 第 12/14 章（2026-07-22 两轮代码摸底）。
## 运行态证据（RUNTIME）
| ID | 位置 | 说明 |
|---|---|---|
| RT-001 | 8085 测试环境回读验证 | 9130 AI 指标上传 code=0，DB 回读一致（summary 2026-08-06） |
| RT-002 | 8085 门禁实测 | 无 token 拒绝「仅AI框架通道可用」；upload_md.py 带 ai token 直传成功（summary 2026-08-06） |
| RT-003 | 生产 itsm 守卫拒绝记录 | finished 状态记录按设计拒绝写入（summary 2026-08-06） |
## 证据缺口（Check 阶段）
| 缺口 | 影响 | 状态 |
|---|---|---|
| 页面级截图（需求详情 AI 区块/会议 tab/MD 在线查看） | G2 门禁不能完全关闭 | 待 8085 重启后采集 |
| 禅道需求单 ID（本 PRD 存档） | 5.6 ID 流转约定闭环 | 待用户建单（summary 遗留） |
workspace/specs/ai-sop-20260723-1024/00_meta/gates.md
+20
View File
@@ -0,0 +1,20 @@
# 阶段门禁（Gates）
> 对应 PRD 第 10 章里程碑 M0-M4。本项目实际执行时未走 tgassist 门禁（回溯归档），下表为事后对照认定。
| 门禁 | 通过标准 | 实际状态 | 证据 |
|---|---|---|---|
| G0 需求确认 | PRD Final 定稿，P0 全关 | ✅ 通过（2026-07-23） | prd_final.md v1.24；session.yaml `status: finalized` |
| G1 一期交付 | DDL 可重入执行 + 回归通过 | ✅ 通过 | summary.md「M1 已交付，W=3.2」 |
| G2 二期交付 | aiBatchAdd/uploadBind/鉴权/页面落地 + 单测绿 | ⚠️ 部分通过 | CHG-061 单测 24 绿、8085 门禁实测；**页面级验证遗留**（8085 重启后补） |
| G3 三期交付 | IZtCountService 接入指数 + 9 岗位报表 | ⏳ 未开始 | — |
| G4 验收 | 对照 PRD+考核方案验收 | ⏳ 未开始 | — |
## 门禁遗留项（进入 G2 完全通过前）
1. 需求详情页代码审查报告区块徽标撤下后的页面级验证（CHG-057 遗留）
2. M2 范围内其余页面的 8085 端到端验证
## 变更说明
- G2 判定从「通过」降级为「部分通过」依据：summary.md 2026-08-06 CHG-057 明确"页面级验证待 8085 启动后补"
workspace/specs/ai-sop-20260723-1024/00_meta/roles.md
+17
View File
@@ -0,0 +1,17 @@
# 角色记录
> tgassist 固定 6 角色。本项目实际由 pmassist-v3 会话产出 + 用户逐轮质询推进，角色职责按下表回溯认定（归档视角）。
| 角色 | 承担方 | 职责履行证据 |
|---|---|---|
| PM | pmassist-v3（AI）+ 用户评审 | PRD v1.0→v1.24 共 25 版迭代（01_input/prd_final.md 变更记录）；FR-001~014 定义 |
| PJM | 用户（ implicitly ） | 分期拍板（CHG-014 MD 文件流、CHG-019 砍 zt_task_extend、CHG-021/022/025 zt_story 8 列）；工作量重评决策 |
| Arch | pmassist-v3（AI） | 5.x 方案设计与取舍（扩展表模式 vs 直接加列 vs 结构化新表）；5.6 ID 流转约定 |
| Dev | AI 辅助 + 用户执行 | dev_log.md、summary.md CHG-039~061；8085/8086 环境验证记录 |
| QA | pmassist-v3（AC 生成）+ 单测 | 02_acceptance/acceptance.md（33 AC）；summary「单测 24 绿」 |
| Council | 用户 | 逐轮质询记录（summary.md 审查迭代段）；对外接口文档拍板（2026-08-07） |
## 备注
- 本项目 Council 职责由用户一人承担，无独立评审团
- 开发过程未走 tgassist 门禁（工作区为回溯补建），后续需求建议从方向 1 初始化起走完整门禁
workspace/specs/ai-sop-20260723-1024/00_meta/rounds/round_1.md
+28
View File
@@ -0,0 +1,28 @@
# Round 1
## Plan
- WWH 填充度：完整（What/Why/How 见 desc.md；架构边界已由用户确认）
- 本轮目标：产出 PRD v1.0 初稿（全链路+分期），13 条 FR 骨架，差异点清单
- 需要读取的资产：SRC-001/002（已读）、codemap/domainmap 索引（核查=无关）、codes/zentao 摸底结论（2026-07-22 两轮探查，沿用）
- 需要提出的问题：FR/分期确认（P0）、绩效体系关系（P1）、鉴权（P1，二期前）
- 本轮 FR 范围：FR-001~013 全新增
## Do
- 资产读取：assets/codemap/_index.yaml、assets/domainmap/_index.yaml（均 fly-home-flow，不引用）
- 分析：SOP 14 步→13 条 FR；缺口三分法（扩展表/附件通道/绩效接入）
- 产出：outputs/prd.md v1.0（15 章齐全：背景/目标/角色/范围/方案/FR/数据模型DDL/口径/差异点/风险/里程碑/证据映射/资产引用）；desc.md；materials_index.md
- 提问：questions/round_1.yaml
## Check
- 目标覆盖：SOP 8 类数据项 → FR 全覆盖（6 复用、4 缺口新建、3 绩效三期）
- 证据充分性：关键结论带 [SRC]/[ZT] 证据；角色诉求部分 [ASSUMPTION] 已标
- 逻辑一致性：FR 分期与第 4 章范围一致；DDL 与 SRC-001 数据项一致
- FR 编号连续（001-013）；AC 覆盖 0/13 → Round 2 批量生成（ac_batch 未跳过）
- 端覆盖矩阵 ✅、差异点清单 ✅、mermaid ✅
## Act
- 更新 session.yaml（round=1、fr_count=13）、summary.md
- 等待人类确认 Q1-1（P0）→ 确认后 Round 2：AC 批量生成（Given/When/Then）+ 章节细化
## 补充（用户质询后）
- 用户问「是否结合了现有代码工作流程」→ 自查结论：复用/缺口判断有代码证据，但 SOP 步骤与系统工作流的逐步映射缺失 → 已在 prd.md 增补 **6.3 SOP 步骤 × 现有工作流映射**（14 步逐步对上 zt_story stage 状态机、userReview、验收链 testSubmitVerified→storyProductUserYs→storyYs、任务生命周期、需求的一生；结论：11/14 步现有可承载，缺口即一期 3 新表）
workspace/specs/ai-sop-20260723-1024/00_meta/rounds/round_2.md
+21
View File
@@ -0,0 +1,21 @@
# Round 2 — AC 批量生成
## Plan
- 前置：Q1-1（P0）已由用户确认关闭（PRD v1.24 + dev_plan v4.0）
- 目标：14 条 FR 全部生成 Given/When/Then 验收标准（每 FR ≥1 正常 + ≥1 异常/边界）
## Do
- 逐 FR 将规则翻译成 AC：FR-001~014 共 33 条 AC（正常 14 + 异常/边界/验证 19），含关键规则点：
- AC-002-3 FIND_IN_SET 防误匹配；AC-004-2 幂等、AC-004-3 finished 锁定
- AC-006-2 整批拒绝、AC-006-3 防重；AC-007-2 zt_task_extend 不存在的豁免验证
- AC-008-2 SOP 卡点（未 pass 禁提测试报告）、AC-008-3 多轮回炉
- AC-013-2 对拍验收；AC-014-3 判定源正确性（testReportSubmit）、AC-014-4 异议回滚
- 产出：outputs/acceptance.md；FR→AC 覆盖矩阵回填 prd.md 第 13 章
## Check
- 覆盖：14/14 FR 有 AC（覆盖率 100%）；每 FR ≥1 正常 + ≥1 异常/边界
- 一致性：AC 与 PRD v1.24 规则逐条对齐（CHG-014~025 已融入）
## Act
- session.yaml：round=2、ac_count=24、ac_coverage=14/14
- 待用户审 AC → 定稿模式（E）：prd_final.md
workspace/specs/ai-sop-20260723-1024/00_meta/status.md
+24
View File
@@ -0,0 +1,24 @@
# 状态快照
> 快照日期：2026-10-08（回溯归档时）
> 规则：每次状态变更追加一条，禁止改写历史
| 日期 | 阶段 | 状态 | 依据 |
|---|---|---|---|
| 2026-07-23 | M0 需求确认 | ✅ PRD v1.24 Final 定稿（pmassist Round 2 闭环） | summary.md 定稿记录 |
| 2026-07-23 | M1 一期数据模型 | ✅ 已交付（zt_story_expand 加列，W=3.2） | summary.md |
| 2026-08-06 | M2 二期（开发中） | ✅ CHG-039~057：页面区块/接口/字段落地，9130 AI 指标传 8085 回读验证 | summary.md CHG-057 |
| 2026-08-06 | M2 二期（开发中） | ✅ CHG-061：AI 三接口鉴权落地（saveOrUpdate/aiBatchAdd 限 ai、uploadBind 需登录），单测 24 绿，8085 门禁实测通过 | summary.md CHG-061 |
| 2026-08-07 | M2 二期（接口交付） | ✅ 禅道AI通道接口文档 v1.0.docx 对外交付 | summary.md |
| 2026-10-08 | 归档 | 📦 回溯归档至本 tgassist Spec Workspace | 本文件 |
## 未决项（继承自 session.yaml）
- Q1-2（P1，三期前）：绩效考核与现有 ZtMonthScore/ZtCountController 体系关系（替换/并存/渐进）
- Q1-3（P1，二期前必决）：上传接口鉴权策略 → 已由 CHG-061 落地（内部 token），**建议关闭**
- Q1-4（P2，三期前）：口径待确认 5 项（见 03_plan/risks.md）
## 下一动作
- M2 剩余页面级验证（待 8085 重启后补，见 summary.md CHG-057 遗留）
- M3 三期立项：绩效消费（IZtCountService 接入 + 9 岗位报表）
workspace/specs/ai-sop-20260723-1024/00_meta/summary.md
+13
View File
@@ -0,0 +1,13 @@
# Summary
- 2026-07-23 [Round 1]: pmassist 启动，工作区 prds/ai-sop-20260723-1024。用户确认：PRD 全链路（SOP+绩效，分期）；原型暂缓（skip_flags）。
- 2026-07-23 [Round 1]: 资产核查 codemap/domainmap=fly-home-flow 无关不引用；PRD v1.0 初稿完成（13 条 FR、4 项 DDL 建议、6 项口径、差异点、三期里程碑）；待用户确认 Q1-1（P0）后进 Round 2 批量生成 AC。
- 2026-07-23 [审查迭代]: 用户逐轮质询 → PRD 迭到 v1.3（6.3 流程映射、FR-014 文档齐备自动核查、FR-008 触发/上传规则、7.5 九岗位算分模型全量）；开发方案 dev_plan.md v1.0 送审版产出。
- ⏳ 定稿日待办（用户确认）：用户建 zentao 需求单给 ID → AI 一次完成 W=10.2 提交 + PRD 附件上传。
- 2026-07-23 [Round 2]: 用户确认 PRD v1.24 + dev_plan v4.0（Q1-1 关闭）→ 生成 outputs/acceptance.md（33 条 AC，14/14 覆盖，含 SOP 卡点/幂等/防重/对拍/判定源正确性等关键验证点）；覆盖矩阵已回填 PRD 第 13 章。待用户审 AC 后定稿。
- 2026-07-23 [**定稿**]: 完整性检查通过（P0 关闭、P1×2 按约延后、证据/图表/AC 齐全）→ outputs/prd_final.md（v1.24 Final）产出；一期 W 按新范围重评=3.2 人日（demand-assessor 七步，记于定稿版附录）。待用户建 zentao 需求单给 ID → 提交 W+PRD 附件 → 一期开工。
- 2026-08-06 [CHG-057]: 需求详情页代码审查报告区块撤下 通过/未通过/未审 状态徽标（卡点与后端字段保留）；两前端副本已同步，页面级验证待 8085 启动后补。另：9130 AI 指标（S=3/B=2.2/F(T)=1.4/G(A)=0.55/W=5.1，魏冬霞/罗勇）已传 8085 测试环境（code=0，DB 回读验证）；生产 itsm 已有 finished 记录被守卫按设计拒绝，未写入。
- 2026-08-06 [CHG-061]: AI 三接口鉴权落地（saveOrUpdate/aiBatchAdd 限 ai、uploadBind 需登录），创建人取 token 身份；ai 永久 token 生成于 .claude/ai_token.txt；submit_assessment.py/upload_md.py 自动带头且默认改本地 8085。单测 24 绿，8086 矩阵实测通过。8085 待重编译重启。
- 2026-08-06 [CHG-061 闭环]: 用户重启 8085 → 门禁实测生效（无 token 拒"仅AI框架通道可用"；upload_md.py 默认本地+自动带 ai token 直传成功，zt_file addedby=ai，中文 title 落库正确）。至此 CHG-039~061 全部改动已在 8085 生效。
- 2026-08-06 [tgassist·接口文档]: outputs/ai_api_interfaces.md v1.0 产出——AI 三通道接口（saveOrUpdate/aiBatchAdd/uploadBind）+ 鉴权矩阵 + 全分支/错误速查 + 证据映射（全部取自运行代码实证，生产 Base URL 唯一 ASSUMPTION 已标注）。
- 2026-08-07 [tgassist·对外交付]: 用户拍板"别人也在用本框架，整理成文档"→ outputs/禅道AI通道接口文档_v1.0.docx（Word 对外版：3 接口 + id=149 ai 永久 token，不含 login；生产地址取 itsm_post.py 实证 https://itsm.sino-assist.com）。生成脚本 tmp/gen_api_doc.py 可复用。
workspace/specs/ai-sop-20260723-1024/01_input/prd_final.md
+645
View File
@@ -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 范围缩减作废）
workspace/specs/ai-sop-20260723-1024/01_input/references/materials_index.md
+14
View File
@@ -0,0 +1,14 @@
# 资料索引
| ID | 名称 | 类型 | 日期 | 路径 | 摘要 |
|---|---|---|---|---|---|
| SRC-001 | AI下的开发SOP流程（新版） | PDF | 2026-07-22 | materials/AI下的开发SOP流程（新版）.pdf | 5页。开发SOP流程图：业务部门提需求→评审激活→初次讨论（会议纪要）→AI生成初版PRD+原型图→评审细化（偏差回炉）→最终版PRD→AI评估工作量指标并生成研发需求→AI生成架构设计/验收指标/测试用例→评审确认→AI拆分任务评估工时→开发→AI代码审查（不过回炉）→测试/BUG→测试报告→更新AI文档→AI工作日志。附需求全生命周期数据模型（用户需求/研发需求/研发任务/测试任务/AI代码审查报告/AI工作日志8类） |
| SRC-002 | 信息技术部绩效考核标准-新版 - AI下的考核方案 | XLSX | 2026-07-22 | materials/信息技术部绩效考核标准-新版 - AI下的考核方案.xlsx | 9岗位考核表（项目经理/项目经理(王宇航)/产品经理/产品助理/后端/前端/测试/UI/运维）。核心公式：工作量指标完成率=Σ(月度工作量指数)÷(团队可用工作天数×5)；版本计划完成率≥95%；线上Bug≤5‰；Bug密度≤15%；缺陷检出率>20%；大型需求（AI评估工作量指数>20）须产出《需求测试用例》《需求测试报告》《AI项目文档更新记录》《AI代码审查报告》《AI工作日志》五类文档 |
# 本地资产核查（pmassist 2.5）
| 资产 | 结论 |
|---|---|
| assets/codemap/_index.yaml | 属 fly-home-flow（得依享家家政平台），与本 PRD 目标系统无关，不引用 |
| assets/domainmap/_index.yaml | 同上，不引用 |
| codes/zentao、codes/web_zentao | 目标系统，证据来自 2026-07-22 两次代码摸底（后端 8 触点 + 前端 7 页面，文件:行号级），引用格式 [ZT:路径:行号] |
workspace/specs/ai-sop-20260723-1024/01_input/requirements.md
+17
View File
@@ -0,0 +1,17 @@
# 原始需求与 WWH 分析
## 原始需求
基于《AI下的开发SOP流程（新版）》[SRC-001] 与《信息技术部绩效考核标准-新版 - AI下的考核方案》[SRC-002]，在 IT 工作台（codes/zentao 后端 + codes/web_zentao 前端，自研，数据本系统自有）落地 AI 开发 SOP 全流程与 9 岗位绩效考核体系，分期实施。
## WWH
- **What**：IT 工作台承载 SOP 全生命周期（用户需求→PRD→AI评估→任务→代码审查→测试→工作日志）+ 以工作量指数为核心的绩效考核自动化
- **Why**：AI 参与开发后需要新效能度量与考核依据（工作量指数=功能单元数量×复杂度×AI系数体系）[SRC-002]；大型需求（指数>20）强制五类文档留痕 [SRC-002]
- **How**：最大复用现有 zt_* 功能；AI 侧数据「框架算、平台存」（上传通道 /zt-story-expand 为既有先例 [ZT:controller/ZtStoryExpandController.java:23]）；缺口按分期补齐：一期数据模型、二期上传接口与页面、三期绩效消费
## 关键架构边界（用户已确认）
1. 工作量指数/AI 指标由 AI 框架计算后上传，zentao 只存不算
2. 目标平台为自研 IT 工作台，绩效数据本系统自有
3. 禅道老表（zt_story/zt_task/zt_bug 等）不改结构，扩展走 zt_story_extend 先例的扩展表模式
workspace/specs/ai-sop-20260723-1024/02_acceptance/acceptance.md
+155
View File
@@ -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：回滚对应扣分并留痕
workspace/specs/ai-sop-20260723-1024/02_acceptance/checklist.md
+38
View File
@@ -0,0 +1,38 @@
# 验收清单（Checklist）
> 派生自 `02_acceptance/acceptance.md`（33 条 AC，14/14 FR 覆盖）。
> 完整 Given/When/Then 与验证步骤见 acceptance.md，本文件为门禁速查表。
## FR → AC 覆盖速查
| FR | 标题 | AC 数 | 覆盖 |
|---|---|---|---|
| FR-001 | 用户需求管理 | 2 | ✅ |
| FR-002 | 需求讨论会与纪要 MD | 3 | ✅ |
| FR-003 | PRD 文档管理 | 2 | ✅ |
| FR-004 | 需求级 AI 工作量指标 | 3 | ✅ |
| FR-005 | 验收标准与测试用例管理 | 1 | ✅ |
| FR-006 | 研发任务双通道 | 3 | ✅ |
| FR-007 | 任务级 AI 工时（豁免） | 2 | ✅ |
| FR-008 | AI 代码审查报告 MD | 4 | ✅ |
| FR-009 | 测试任务与 BUG | 1 | ✅ |
| FR-010 | 测试类文档 4 字段 | 3 | ✅ |
| FR-011 | AI 工作日志 MD | 2 | ✅ |
| FR-012 | 工作量指标完成率统计 | 1 | ✅ |
| FR-013 | 九岗位绩效考核报表 | 2 | ✅ |
| FR-014 | 大型需求文档齐备自动核查 | 4 | ✅ |
## 关键验收点（含异常/边界）
- [ ] AC-004-x：saveOrUpdate 幂等（按业务键有则更新）
- [ ] AC-006-x：aiBatchAdd 双通道（AI 框架批量 + 人工创建保留），创建人=ai 账户，初始状态 wait
- [ ] AC-008-x：审查报告 MD 头部「结果：pass/reject」解析写 code_review_status
- [ ] AC-010-x：测试 4 字段双向（AI 供下载 / 测完提交 testReportSubmit）
- [ ] AC-014-x：大型需求（指数>20）五类文档齐备自动核查，只判缺失不判内容
- [ ] 卡点强制：code_review_status 未 pass 禁提测试报告（CHG-023）
- [ ] 鉴权矩阵：saveOrUpdate/aiBatchAdd 限 ai；uploadBind 需登录（CHG-061）
## 验证状态
- 接口/后端逻辑：✅ 8085 实测通过（单测 24 绿）
- 页面级：⚠️ 待 8085 重启后补验（见 00_meta/gates.md G2 遗留）
workspace/specs/ai-sop-20260723-1024/03_plan/dependencies.md
+29
View File
@@ -0,0 +1,29 @@
# 依赖与假设
> 摘自 PRD 4.3 假设与依赖 + 5.6 ID 流转约定。
## 依赖项
| 依赖 | 类型 | 状态（回填） | 负责方 |
|---|---|---|---|
| AI 框架上传报文格式 | 内部 | ✅ 已落地（saveOrUpdate/aiBatchAdd/uploadBind 三通道，见 04_design/interfaces.md） | AI 框架 |
| 生产 DB 变更窗口 | 内部 | 🟡 一期 DDL 已执行；二期/三期 DDL 待窗口 | 运维 |
| SRC-002 考核公式最终版 | 内部 | ✅ xlsx 为准 | IT 经理 |
| zentao 需求单 ID（PRD 存档 + W 补登） | 内部 | 🔴 仍未建单（summary 遗留，阻塞 5.6 闭环展示） | 用户 + AI |
| AI 框架侧上传挂钩（7 类） | 内部 | ✅ 已落地（summary CHG-039~061） | AI 框架 |
| ai 永久 token | 内部 | ✅ 已生成（.claude/ai_token.txt） | Dev |
## 关键假设（PRD 4.3 / 11.2）
1. 工作量指数/AI 参与率由 AI 框架计算，zentao 只存不算
2. 绩效数据本系统自有，不外流
3. 禅道老表不改结构；扩展走 zt_story_expand 先例 / 用户拍板的 zt_story 加列破例
4. 上传接口鉴权在多人环境下为必决项 → 已由 CHG-061 兑现
## 环境依赖
| 环境 | 用途 | 状态 |
|---|---|---|
| 8085 测试环境 | 集成验证 | ✅ CHG-061 验证通过；页面级验证待重启后补 |
| 8086 | 鉴权矩阵实测 | ✅ 通过 |
| 生产 itsm（https://itsm.sino-assist.com） | 正式上线 | 🟡 守卫已生效（finished 拒绝写入按设计工作） |
workspace/specs/ai-sop-20260723-1024/03_plan/milestones.md
+22
View File
@@ -0,0 +1,22 @@
# 里程碑计划
> 摘自 PRD 第 10 章（prd_final.md），状态列为 2026-10-08 归档时回填。
| 里程碑 | 交付物 | 时间 | 负责方 | 状态（回填） |
|---|---|---|---|---|
| M0 需求确认 | PRD Final | 2026-07-23 定稿 | PM | ✅ 完成 |
| M1 一期：数据模型 | zt_story_expand 加列 ai_participation_rate + 实体加字段 + 回归 | 定稿后 1~2 天 | Dev | ✅ 完成（W=3.2） |
| M2 二期：文件流+接口+页面 | aiBatchAdd + uploadBind + FileTypes 扩展 + MD 渲染 + 页面（会议 tab/纪要 MD/需求详情区块）+ 框架挂钩 + 鉴权 | 立项时评估 | Dev | ⚠️ 主体完成，页面级验证遗留 |
| M3 三期：绩效消费 | 完成率统计 + 9 岗位报表 | 立项时评估 | Dev | ⏳ 未开始 |
| M4 验收 | 对照 PRD 与考核方案验收 | — | QA/IT经理 | ⏳ 未开始 |
## 二期实际交付明细（对照 M2 范围）
| 范围项 | 交付证据 |
|---|---|
| aiBatchAdd 任务批量提交 | CHG-061 鉴权落地，8085 实测 |
| uploadBind + /common/upload | CHG-061 upload_md.py 直传成功，zt_file addedby=ai |
| FileTypes 扩展（aiCodeReview/aiWorkLog/testCase/testReport/testReportSubmit/testOther） | PRD 5.4 表 |
| 需求详情 AI 区块/会议 tab/MD 在线查看 | CHG-057（徽标撤下后页面验证遗留） |
| 框架侧触发挂钩 | summary CHG-039~061「7 类挂钩净新增」 |
| 鉴权（二期必决项 Q1-3） | CHG-061 内部 token，ai 永久 token 存 .claude/ai_token.txt |
workspace/specs/ai-sop-20260723-1024/03_plan/risks.md
+31
View File
@@ -0,0 +1,31 @@
# 风险登记册
> 摘自 PRD 第 9 章 + 7.3 口径待确认项 + session 未决问题，2026-10-08 归档时更新状态。
## 技术/项目风险（PRD 9 章）
| 编号 | 风险 | 等级 | 应对 | 状态（回填） |
|---|---|---|---|---|
| R-001 | 无迁移工具，DDL 手工执行 | 中 | DDL 可重入 + 生产执行前备份评审 | 🟡 随三期 DDL 仍有效 |
| R-002 | 单测覆盖率<20%，回归无安全网 | 中 | 新 Service 强制单测 | 🟡 CHG-061 单测 24 绿（局部改善，整体覆盖率问题仍在） |
| R-003 | 上传接口无鉴权 | 中 | 二期前决策：沿用/签名/JWT | ✅ 已关闭（CHG-061 内部 token 落地） |
| R-004 | 考核公式理解偏差 | 中 | 三期前与 IT 经理逐 sheet 核对 | 🟡 未关闭，三期开工前必做 |
| R-005 | 一期无可视成果 | 低 | 分期明示 | ✅ 已过一期 |
## 口径待确认（PRD 7.3，三期前必决）
| # | 事项 | 状态 |
|---|---|---|
| 1 | 总分算法（各项×权重求和为 ASSUMPTION） | 🟡 待 IT 经理确认 |
| 2 | 线上 Bug 率单位矛盾（×100% vs ‰，按‰理解） | 🟡 待确认 |
| 3 | 缺陷检出率申诉流程（系统只留入口） | 🟡 待确认 |
| 4 | 普通/重大 Bug 映射 | ✅ 已决（2026-08-04：severity 1=重大、2/3/4=普通，以老弹窗 getBugFindScore 为准） |
| 5 | zt_story_user 验收时间链断裂（ysFlag/ysDate 无写入端点） | 🟡 待二期补写或改走 zt_story |
## 未决问题（session.yaml 继承）
| ID | 优先级 | 问题 | 状态 |
|---|---|---|---|
| Q1-2 | P1 三期前 | 绩效与 ZtMonthScore/ZtCountController 关系（替换/并存/渐进） | 🟡 未决 |
| Q1-3 | P1 二期前必决 | 上传接口鉴权策略 | ✅ 已由 CHG-061 落地，建议正式关闭 |
| Q1-4 | P2 三期前 | （并入上方口径待确认） | 🟡 未决 |
workspace/specs/ai-sop-20260723-1024/04_design/architecture.md
+40
View File
@@ -0,0 +1,40 @@
# 架构设计摘要
> 摘自 PRD 第 5 章（prd_final.md），为归档速查版；完整论证见 01_input/prd_final.md。
## 总体方案
最大复用现有 zt_* 功能，缺口分三类补齐：
1. **数值指标加列**：zt_story_expand.ai_participation_rate（一期唯一 DDL）；任务级 AI 工时直接入 zt_task.estimate（zt_task_extend 已砍，CHG-019）
2. **AI 文档走 MD 文件流**（CHG-014 用户拍板）：审查报告/工作日志/测试报告/纪要 = MD 附件，不建结构化表
3. **绩效统计接入**：IZtCountService 消费 zt_story_expand 指标（三期）
## 核心机制
| 机制 | 决策 | 依据 |
|---|---|---|
| 扩展表模式（数值） | ✅ 采用 | zt_story_expand 先例；不碰老表 |
| MD 文件流（文档） | ✅ 采用（CHG-014） | 不建表、人可直接阅读；弱结构化用 MD 头部约定补偿 |
| zt_task 直接加列 | ❌ 放弃 | 污染禅道老表 |
| 验收指标结构化新表 | ❌ 放弃 | 富文本够用，过度设计 |
## 三通道上传架构
| 通道 | 接口 | 模式 | 鉴权（CHG-061） |
|---|---|---|---|
| 数值指标 | /zt-story-expand saveOrUpdate | 幂等（业务键有则更新） | 限 ai 账户 |
| 任务批量 | /zt-task aiBatchAdd | 双通道（AI 框架 + 人工保留） | 限 ai 账户 |
| MD 文档 | /common/upload + uploadBind | 文件+绑定两步 | 需登录 |
## ID 流转约定（5.6）
1. storyId：zentao 建单分配 → 回填 PRD「关联需求ID」→ 上传以此为键
2. taskId：aiBatchAdd 响应返回，框架记录
3. MD 关联：zt_file.objectID=storyId，objectType 区分类型
4. 共享载体 = PRD 文档（非个人工作区）；ai 账户与使用者解耦
## 关键卡点
- code_review_status（pass/reject）未 pass → 禁提测试报告（CHG-023）
- FileTypes 扩展：aiCodeReview / aiWorkLog / testCase / testReport / testReportSubmit / testOther
workspace/specs/ai-sop-20260723-1024/04_design/data_model.md
+38
View File
@@ -0,0 +1,38 @@
# 数据模型
> 摘自 PRD 5.4 字段表 + 7.1 一期 DDL。完整口径见 prd_final.md 第 7 章。
## 一期 DDL（已交付）
```sql
ALTER TABLE `zt_story_expand`
ADD COLUMN `ai_participation_rate` VARCHAR(16) DEFAULT NULL
COMMENT 'AI参与率（只存不算，口径待定）' AFTER `ai_efficiency_coefficient`;
```
## 二期 DDL/字段（已设计，随版本交付）
| 字段 | 表 | 类型 | 说明 | 决策 |
|---|---|---|---|---|
| url | zt_file | varchar(512) | 附件访问链接（pathname=存储路径，url=可访问地址） | CHG-018 |
| url | zt_meeting | varchar(512) | 会议纪要 MD 链接，存最新一份 | 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 | varchar(512)×7 | 研发需求 7 类文档链接，各存最新一份 | CHG-021/022/025 用户拍板 |
| code_review_status | zt_story | varchar(16) | pass/reject/NULL；上传时解析写入 | CHG-023 |
## FileTypes 枚举扩展
aiCodeReview / aiWorkLog / testCase（下载）/ testReport（供下载）/ testReportSubmit（提交）/ testOther
## 已否决的表（决策留痕）
| 表 | 否决原因 | 决策 |
|---|---|---|
| zt_ai_code_review / zt_ai_work_log | MD 文件流替代 | CHG-014 |
| zt_task_extend | evaluation_time 与 zt_task.estimate 冗余；指数无消费方 | CHG-019 |
## 关键口径（7.3 节选）
- 大型需求判定：workloadIndex > 20 → 五类文档强制
- 月度达标工时 =（工作天数×人数 − 团队请假天数）×5÷人数（CHG-034 全团队平摊）
- 普通/重大 Bug：severity 1=重大、2/3/4=普通（2026-08-04 已决）
- 待确认 5 项见 03_plan/risks.md
workspace/specs/ai-sop-20260723-1024/04_design/interfaces.md
+344
View File
@@ -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 事实优先）。
workspace/specs/ai-sop-20260723-1024/05_delivery/change_log.md
+34
View File
@@ -0,0 +1,34 @@
# 变更日志（Changelog）
> 双段式：① PRD 文档期变更（v1.0→v1.24，全部来自 prd_final.md 变更记录）
> ② 开发期变更（CHG-039~061，来自 summary.md，详表见 dev_log.md）
## ① PRD 文档期（2026-07-23 单日 25 版迭代）
| 版本 | 变更要点 |
|---|---|
| v1.0 | 初稿：13 FR、4 项 DDL 建议、6 项口径、三期里程碑 |
| v1.1 | 表名/列名/行号修正（zt_story_expand、ai_efficiency_coefficient） |
| v1.2 | 新增 FR-014 大型需求文档齐备自动核查（三期） |
| v1.3 | 新增 7.5 九岗位绩效计算模型（SRC-002 全量结构化） |
| v1.5~v1.6 | FR-006 双通道定稿；AI 任务初始状态=wait |
| v1.8 | SOP 符合性核查：18 步流程/6 类数据/8 项动作全落点 |
| v1.10 | 上传接口鉴权升级为二期必决项（多人协作前提） |
| **v1.13** | **架构级变更：AI 文档走 MD 文件流，不建 zt_ai_* 两表** |
| v1.15 | 全文核对修 16 处；补遗漏的补充⑦（需求讨论会议 tab） |
| **v1.18** | **砍 zt_task_extend：一期缩至 1 列（W≈1~2 人日）** |
| v1.19 | zt_meeting 加 url 存纪要 MD |
| v1.20~v1.21 | zt_story 加 5→6 文档 url 列；测试字段拆三/四字段澄清 |
| **v1.22** | **新增 code_review_status（pass/reject），支撑卡点强制** |
| v1.24 | 测试 4 字段终版：用例下载/报告模版下载/模版填完提交/其他测试文档；FileTypes 增 testOther |
| Final | 定稿：完整性检查通过；一期 W 重评=3.2 |
## ② 开发期（2026-08-06 ~ 08-07，摘录）
| 变更 | 要点 | 验证 |
|---|---|---|
| CHG-057 | 需求详情页审查报告区块撤下状态徽标（卡点与后端字段保留） | 两前端副本已同步；页面级验证遗留 |
| CHG-061 | AI 三接口鉴权：saveOrUpdate/aiBatchAdd 限 ai，uploadBind 需登录；创建人取 token 身份 | 单测 24 绿；8086 矩阵实测；8085 门禁实测生效 |
| 接口文档 | ai_api_interfaces.md v1.0 + 对外 Word 版（禅道AI通道接口文档_v1.0.docx） | 运行代码实证，生产地址唯一 ASSUMPTION 已标注 |
> 完整开发日志见 `05_delivery/dev_log.md`。
workspace/specs/ai-sop-20260723-1024/05_delivery/dev_log.md
+966
View File
@@ -0,0 +1,966 @@
# 开发交付记录（dev_log）
## 一期：zt_story_expand 加列 ai_participation_rate（2026-07-23，依据 prd_final v1.24 FR-004 / dev_plan v4.0 §2）
### 改动文件
| 文件 | 动作 | 说明 |
|---|---|---|
| codes/zentao/sql/20260724_alter_zt_story_expand_add_ai_rate.sql | 新增 | DDL（说明头+回滚+可重入 INFORMATION_SCHEMA 判断） |
| codes/zentao/src/main/java/com/sa/zentao/entity/ZtStoryExpand.java | 修改 | 加 `private String aiParticipationRate;`（紧随 aiEfficiencyCoefficient） |
| codes/zentao/src/test/java/com/sa/zentao/service/ZtStoryExpandServiceTest.java | 新增 | 回归测试 2 场景 |
### 单元测试记录
| # | 场景 | 结果 |
|---|---|---|
| 1 | 新增路径：实体带 aiParticipationRate 透传到 insert | ✅ 通过 |
| 2 | 更新路径：selectById 命中后透传到 updateById | ✅ 通过 |
执行：`mvn test -Dtest=ZtStoryExpandServiceTest` → **Tests run: 2, Failures: 0, Errors: 0 / BUILD SUCCESS**（JDK 21，tmp/jdk-21.0.2）
### 排障记录（后续跑测试必看）
1. **surefire fork 失败**（Boot Manifest-JAR / 'other' has different root，Windows+JDK21）：需加 `-Dsurefire.useManifestOnlyJar=false`。建议团队在 pom.xml 固化该配置（未擅改团队构建文件）
2. **MyBatis-Plus 单测**：需 `@BeforeAll` 手工 `TableInfoHelper.initTableInfo(...)` 初始化实体缓存
3. **MP 3.5.5 saveOrUpdate 行为**：先 selectById 判断存在性再决定 insert/updateById——mock 需覆盖 selectById
### 未做（按约定）
- git 操作（分支/提交由用户处理）；生产 DDL 执行（待 D2 窗口+备份）；W 值与 PRD 附件上传（待 storyId）
---
## 二期开发（2026-07-23，dev_plan v4.0 §3，任务见 tasks.md）
### 后端（agent-3 实施，DT1-DT4+DT10）
- DT1：`sql/` 新增 3 个 DDL（zt_file.url、zt_meeting.url、zt_story 8 列，含说明头+回滚+可重入）
- DT2：FileTypes +6 类；实体 ZtFile/ZtMeeting/ZtStory 补字段；`POST /common/uploadBind`（上传+绑定+按类型刷新主表 url/status，非法回滚不落盘）
- DT3：`POST /zt-task/aiBatchAdd`（事务/整批拒绝/防重 skipped/status=wait/创建人 ai/estimate 映射/返回 taskIds）
- DT4：userReview 补写 activateddate（:567）；`sql/20260724_insert_ai_user.sql`（可重入，MD5 默认密，注释建议改密）
- DT10 单测：**Tests run: 19, Failures: 0, Errors: 0**（UploadBindRefreshOwnerUrlTest 13 例 + AiBatchAddServiceTest 4 例 + 既有回归 2 例）；编译 BUILD SUCCESS
- 遗留：鉴权未实施（必决项待用户定）；uploadBind 回滚可能留孤儿文件（低危）；insert_ai_user.sql 生产执行前先测试库跑
### 前端（agent-4 实施，DT5-DT8）
- DT5：新增 `components/MdPreview`（markdown-it 渲染，禁注入；**依赖需 npm i markdown-it**）；uploads 组件向后兼容扩展（可切 /common/uploadBind，34 处现有调用零影响）；api/base.js 补 uploadBind
- DT6：用户需求详情加「需求讨论会议」tab（懒加载+storyIds 过滤，TODO 待后端 FIND_IN_SET）；顺手修复了模板引用不存在的方法 handleClick
- DT7：会议 add/editDialog 渲染 uploads（objectType=meeting）；详情附件区块（操作人/时间/.md 在线查看/下载）
- DT8：研发需求详情 7 区块（需求 ID+复制 / AI 指标 12 字段 / 用例+模版查看下载 / 提交测试报告（未 pass 禁用）/ 其他文档 / 代码审查报告（轮次+状态）/ 工作日志）
- 验证：SFC 解析+模板编译+babel 全过；eslint 零新增 error
- 待联调：markdown-it 未装；uploadBind 响应结构假设；会议 pageList 前端兜底过滤；AI 指标当月匹配
### 框架侧（DT9）
- `.claude/skills/tgassist/scripts/upload_md.py`：通用上传脚本（file+objectType+objectId+reviewResult，BASE_URL 可配）
---
## DDL 测试库执行（2026-07-23，192.168.1.161/zentao_dev）
执行 5 个脚本（4 DDL + ai 账户）并逐列验证通过：
| 项 | 验证 |
|---|---|
| zt_story_expand.ai_participation_rate | ✅ |
| zt_file.url / zt_meeting.url | ✅ |
| zt_story 8 列（7 url + code_review_status） | ✅ 8/8 |
| zt_user ai 账户 | ✅ |
**教训记录**：首次用 pymysql 自写分隔器执行时，脚本内"注释里的分号"导致每个文件首个语句被静默跳过（守卫变量 @c 为 NULL → IF 走 SELECT 1 空操作）。已直接补执行缺失语句并复核。**生产执行请用标准 mysql 客户端**（脚本本身含说明头+可重入守卫，客户端执行无此问题）。192.168.3.200 库按用户指示未做任何连接/写入。
---
## 端到端冒烟（2026-07-28，8086 端口连 161 测试库）
| 项 | 结果 | 证据 |
|---|---|---|
| uploadBind（aiCodeReview+reviewResult=pass） | ✅ | code=0；zt_file.url 生成；zt_story.code_review_url 写入、**code_review_status=pass**（story 6566） |
| aiBatchAdd（devel+test 两任务） | ✅ | code=0，created=2，taskIds=[5263,5264]；zt_task：status=wait、openedby=ai、estimate=1.0/0.5 |
| aiBatchAdd 幂等（重复提交） | ✅ | created=0，两任务全部 skipped |
**排障记录**：aiBatchAdd 首次冒烟报"失败"，日志（F:/logs/zentao/zentao.log）显示实为 `HttpMessageNotReadableException: Invalid UTF-8`——**是 curl -d 中文未按 UTF-8 编码所致，非接口问题**。改用 `--data-binary @file.json`（UTF-8 文件）后通过。排查过程曾误排：zt_task `left` 保留字（实体已有 `@TableField("`left`")` 反引号处理）、161/200 库表结构差异（161 zt_task 列为 camelCase，与实体一致）。
8086 冒烟实例已关闭（8085 为用户自有实例，未触碰）。冒烟数据（story 6566 的审查附件 id=220、任务 5263/5264）保留在 161 测试库，可随手清理。
---
## 前端联调（2026-07-28，playwright+系统Chrome headless 真机验证）
**最终：全套 10/11 + 聚焦 4/4 通过**（唯一未过项为旧脚本的过时按钮文案定位，已由聚焦脚本验证功能正常）。验证环境：后端 8086（连 161）+ 前端 dev server 8088（代理 8086）。
### 联调发现并已修复的 BUG
| # | BUG | 修复 |
|---|---|---|
| 1 | 审查状态显示"未审"、提交按钮卡死 | 后端：ZtStoryDTO 补 8 个新字段（BeanUtils 才带得出去） |
| 2 | AI 指标区块"暂无数据"（queryByMonth 的 projectId 过滤不匹配） | 后端：新增 `GET /zt-story-expand/queryByStoryId`；前端改调该接口（api/count.js 补路径） |
| 3 | 前端读 `code_review_status`（snake）而后端出 `codeReviewStatus`（camel） | 前端 product.vue 5 处统一 camelCase |
| 4 | .md 判断只认标题后缀（冒烟文件标题无 .md 后缀） | isMd 改认 extension 字段 |
| 5 | uploadBind 的 url 用 baseUrl 绝对地址 → 跨域加载失败 | url 改存相对路径 `/zentao/img/...`（经前端源/代理可达，生产同源同样成立） |
| 6 | markdown-it v14 纯 ESM 与 webpack4 不兼容（8 编译错误） | 降级 markdown-it@12.3.2（package.json 已改） |
### 页面级验证点（截图 tmp/pw_*.png）
登录跳转 ✅；研发详情 6 区块（需求ID/AI指标实数 8.5+0.6+人员/审查报告**通过绿标**/提交测试报告**按钮可用**/工作日志/测试用例）✅；**MD 在线渲染出完整 markdown**（标题/列表/加粗）✅；用户需求「需求讨论会议」tab ✅；会议详情附件区块 ✅；冒烟任务在「关联任务」可见（郭其兵/张富斌）✅
### 给用户/运维的注意事项
- 用户 8085 实例跑的是**修复前旧代码**（重启即得修复）
- `file.baseUrl` 拓扑：uploadBind 现存相对路径，跨域问题已消；`/common/upload` 老接口仍用绝对 baseUrl（历史行为未动）
- 161 冒烟残留：zt_file 220(deleted)/221、zt_task 5263/5264、story 6566 的 expand 改写、url 字段改动
- 运行中：后端 8086（含全部修复）、dev server 8088（供点击验收）
---
## 真实点击测试（2026-07-28，playwright 真实 UI 交互，全部通过）
**研发详情页（8/8）**：登录 ✅；点「复制」出提示 ✅；**UI 上传工作日志** → zt_file(222)+zt_story.work_log_url 刷新（相对路径）✅；**UI 提交测试报告** → zt_file(223)+test_report_submit_url 刷新 ✅；卡点反例（未审需求 6565 显示"不可提交"）✅
**会议链路（4/4+渲染）**：UI 新建会议（产品/类型/时间/地点/参会人/主题/3 个必填富文本）→ zt_meeting 落库 ✅；编辑弹窗上传 MD → zt_file(228) 落库 ✅；**zt_meeting.url 刷新** ✅；会议详情附件区块显示 + MD 在线渲染出内容 ✅
**本轮修复**：老式两段式上传（/common/upload+updateFile）不刷新 zt_meeting.url → ZtMeetingServiceImpl 加 `refreshMeetingUrl`（add/modify 均挂，与 uploadBind 的 refreshOwnerUrl 双通道一致）。
**测试脚本资产**（可复用回归）：tmp/pw_ui_test.py（页面区块）、pw_ui_test2.py（AI指标+MD渲染）、pw_real_click.py（上传+卡点）、pw_real_click2.py（会议链路）；运行器 tmp/pw-venv。
---
## 三期：绩效消费（2026-07-28 用户授权"全跑"，批1+批2+前端完成）
**口径默认锁定**（decision_log 2026-07-28）：总分=0~100×权重；Bug率按‰；severity 1~2 重大/3~4 普通；申诉=系统入口+人工复核；产品助理验收链补写字段。
### 批1：数据与计算基座（agent-5）
- DDL×3：zt_perf_config（uk_role_item）、zt_doc_check（uk_story_month_doc，含申诉状态流字段）、init 62 行规则（9 岗位，权重合计均=1.00）——**已执行 161：61 行生效（1 行 INSERT IGNORE 去重）**
- calculators 18 个（策略模式+linear/threshold/manual 规则）：双完成率（PRD/团队）、版本计划、双 Bug 率、Bug 密度、检出率、双及时率、准时率、饱和度、代码质量（MD 头部正则解析 round/flat 双模式）、运维 4 项、双文档齐备
- 完成率接入：`GET /count/workloadRate`；月末核查 job（每月 28 日 02:00）+ `POST /count/generateDocCheck`/`docCheckAppeal`/`docCheckAppealResolve`
- FR-014 全套：五路判定+zt_doc_check 快照+扣分合并 scopeJson+申诉回滚
- 测试：44 例（PerfTestSupport 手工 TableInfo 初始化）
### 批2：报表引擎+接口（agent-6）
- PerfScoreEngine：linear（封顶/segments）/threshold 分档/manual 透传/bonus 条件/refund 连续 N 月返还
- `ZtPerfController`（/zt-perf）：report（落库读/实时算）、generateMonthScore（保留人工分重算）、manualScore、appeal（scopeJson.appeals）、appealReview（overturned 回滚满分防重复）、config CRUD（admin 限定）
- scopeJson 统一结构（PerfMonthScope POJO）
- 测试：引擎 7+服务 3
### 前端（agent-7）
- src/views/perf/ 4 页面：report.vue（9 岗位 tab+总分卡+申诉/复核）、docCheck.vue（五列 ✓/✗+月度确认锁定）、manualScoreDialog.vue、config.vue（规则行内编辑+JSON 校验）
- src/api/perf.js + router/modules/perf.js 注册；eslint 0 error、模板编译全过
### 全量验证
- `mvn test`：**Tests run: 73, Failures: 0, Errors: 0 / BUILD SUCCESS**（批1 44+批2 10+一二期 19）
- 并行碰撞已对齐（zt_perf_config 实体/服务以批1 版本为准；批2 最小修复批1 文件 2 处编译错误）
### 遗留/待办
- 岗位细分（前后端 userType 同为 KFZ，resolveRole 默认 backendDev，TODO）；FR-014 扣分归属（现取 story.assignedTo，待 IT 经理确认）；docCheckConfirm 接口占位 TODO（前端已留）；申诉 account 为空场景口径；菜单权限码需在 base_role 配置（perf-report/doccheck/config 等）后页面可见
- 待联调：启动 8086 加载三期代码 → perf 页面真实验证 + 对拍（最近月份 vs 线下 Excel）
---
## 三期联调（2026-07-28，161 环境，全部通过）
**接口**：完成率（当月无迭代 rate=0+remark 口径）✅；/zt-perf/report（backendDev 实算 total=10+auto/manual 徽标）✅；FR-014 generateDocCheck（6566 置指数 25 后：五路判定 3✓2✗ 扣 4 分，判定源正确）✅；docCheckMatrix（docs map+deduct+status 契约一致）✅；docCheckConfirm ✅。
**页面（真实浏览器验证）**：/perf/report（9 岗位 tab+总分卡+auto/manual 徽标+申诉/编辑列）✅；/perf/docCheck（6566 行 3✓2✗ 扣4 状态 pending）✅；/perf/config（规则 61 行表格+编辑）✅。
**联调修复（7 处）**：①新增 docCheckMatrix/docCheckConfirm 接口（前端契约缺数据源）；②岗位 tab 中文→编码映射（report/config 页 roleList 改 label+value 双轨）；③总分卡岗位显示加 roleLabel 中文映射；④report 空账号（全部人员）→ 兜底当前登录人（service）；⑤controller account 参数 required=false；⑥菜单注册（base_menu 父级+3页+7按钮，授 3 角色，admin 全量自动可见）；⑦dev server 重启识别新 views/perf 目录。
**注意（对拍时关注）**：空数据月份 auto 项 raw=0→score=0 的语义（如 bugDensity 扣满）需真实数据验证规则合理性；完成率分母"当月无迭代"口径待真实迭代数据验证；FR-014 扣分归集依赖 story.assignedTo（6566 无负责人故 deductByAccount 为空，符合预期但生产需关注）。
**可视化验收后调整（用户反馈）**：研发详情「需求 ID」区块+复制按钮移除（页面顶部已有 ID+标题，冗余；方法 copyStoryId 一并删）。dev_plan §3.5 已同步。
---
## 会议纪要 MD 预览修复链（2026-07-29，161 环境，实测通过）
**问题**：用户需求详情会议纪要 tab 点 MD 在线查看失败/下载 0KB；fileList 一度返回空。
**根因与修复**：
1. `CommonsController.downLoad` 硬编码 linuxFilePath → 改 OS 感知路径（Windows 下 0KB 的根因）。
2. legacy `/common/upload` 不写 url 字段 → 现在写入相对路径 `/zentao/img/...`（与 uploadBind 一致）。
3. zt_file 历史数据：234/235/236 手工补 objecttype='meeting'（老 upload 不传 objectType，靠保存时 updateFile 绑定）；230/232/233 曾被 updateFile 清理逻辑标 deleted='1'（当时 objecttype 未绑定，editDialog fileList 查不到 → 视为已移除）。
4. MdPreview 组件由纯文本 pre 改为 **mavon-editor 预览模式**（只读/代码高亮/表格/引用，PM 与 F:\zd 均已装 mavon-editor@2.10.4）。
**防误删核查**：meeting editDialog 打开时 fileList(objectType='meeting') 装入 form.files（editDialog.vue:345-353），保存时 getParam 拼 id 串 → updateFile 的 notIn 清理不会误删已绑定附件。闭环安全。
**实测（8089 前端 + 8085 后端，真实浏览器）**：用户需求 324 详情 → 会议纪要 tab（会议卡 84：时间/操作人/需求会议 tag/MD 按钮齐全，tab 不再粘连）→ 点 MD → rich_demo.md 富文本渲染通过（表格/SQL 代码块高亮/引用/嵌套列表）。接口层：fileList 返回 3 条 deleted='0' 附件；GET /zentao/img/....md 200/598B（8085/8086 均通）。截图 tmp/pw_324_meeting_tab.png、tmp/pw_324_md_preview.png。
---
## 指标公式验证 + 5‰ 豁免阈值修复（2026-07-29，P0 关闭）
**验证范围**：SRC-002 新版考核 xlsx 全部 9 岗位 sheet × zt_perf_config 61 行规则 × calculators 代码，逐条对照（此前只做过单测与接口级验证，未做全量公式核对）。
**一致项（56/61 行）**：9 岗位权重合计均=1.0；linear/threshold/manual 参数与 xlsx 全部吻合，含易错点——后端代码质量 round 模式（初审严重3/错误超6扣3/复审严重5/错误1）vs 前端 flat（每问题扣3）；前端饱和度 0.3 vs 后端 0.2；王宇航表无 PRD 项且稳定性 0.2；UI 三档 threshold（100/40/0）；tester 线上Bug 普通扣5、重大扣100=该项0分；opsMajorTask 百分制换算=及时率×20 与 xlsx 一致（deductPerStep=1 在百分制下等价，非错误）。
**P0 差异（4 行）**：xlsx/PRD §7.3 规定线上Bug率与产品缺陷率「≤5‰ 得满分」，实现缺豁免阈值——有 1 个普通 Bug 就扣 3 分。影响 id 4（projectManager/onlineBugRate）、11（projectManagerWyh/onlineBugRate）、19（productManager/productDefectRate）、24（productAssistant/productDefectRate）。
**修复**：AbstractWeightedBugCalculator 增加 exemptPerMille 分支——分子=当月上线需求（releaseddate 当月）的 prod Bug 数，分母=当月上线需求 estimate 和，率≤5‰ 满分豁免、超才按个扣分；tester（id45，xlsx 无豁免口径）及无该参数的规则走原逻辑不受影响。4 行 rule_json 已加 `"exemptPerMille":5`（161 库 + sql/20260728_init_zt_perf_config.sql 同步）。
**单测**：BugIndicatorCalculatorsTest 新增 3 用例（1‰ 豁免满分 / 10‰ 超阈值扣 6 分 / 无上线需求边界满分），perf 包 54 个测试全绿。
**遗留（已在 PRD 标注待确认，非本次新增）**：加分项 4 条默认停用（id34/41/48/52，待 IT 经理确认口径）；acceptOnTime 走 manual（zt_story_user 验收时间链断裂）；AC-013-2 与线下真实考核 Excel 对拍未做（需用户提供线下 Excel/真实月份）。
---
## CHG-027 框架验收指标新字段+接口（2026-07-29，161 环境，实测通过）
**背景**：用户拍板——老验收标准（zt_storyspec.verify）不动，AI 框架验收指标走新字段+接口。
**改动**：
1. DDL：`zt_story_expand` 加 `acceptance_criteria` MEDIUMTEXT（Given/When/Then MD），161 已执行 + `sql/20260729_alter_zt_story_expand_acceptance.sql` 迁移文件。
2. 实体 `ZtStoryExpand.acceptanceCriteria` + mapper XML resultMap 补映射；service 零改动（updateById 空值不覆盖，新字段随 saveOrUpdate 自然透传）。
3. 上传通道=现有 `/zt-story-expand/saveOrUpdate`（框架指标同通道），不新增端点（避免与 saveOrUpdate 重复设计）。
**验证**：单测+1（insert 透传 acceptanceCriteria，3/3 绿）；真实接口（8086）——324 上传 Given/When/Then 中文 MD → code:0，queryByStoryId 回读字段完整；6566（finished）→ 正确拒绝"该需求已完成，不可再修改"；zt_storyspec.verify 确认不受影响。
**注意**：用户 8085 需重启加载本次改动（本字段 + 5‰ 豁免修复 + MdPreview/mavon 相关）。
---
## QA 测试文档生成（2026-07-29）
`06_test_docs/` 建成：test_cases.md（36 条用例：33 AC + CHG-027 补充 + TC-002-4 附件防误删回归，14 FR + CHG-027 全覆盖，含环境/账号/前置数据/覆盖矩阵/执行记录表/阻塞依赖）、defects.md、regression.md（模板待执行填充）。已知阻塞：TC-013-2 依赖线下 Excel；上传类用例前置=8085 重启加载 CHG-026/027。
---
## 研发详情上传按钮位置修正（2026-07-29）
用户反馈：4 个文档区块（提交测试报告/其他测试文档/代码审查报告/工作日志）上传按钮浮在文件列表上方 → storyinfo/components/product.vue 调整为文件列表在前、上传按钮在最后（测试用例/模版为只读区无上传钮，不动）。已同步 F:\zd，8089 热更新实测截图 tmp/pw_6566_review_sec.png 确认。另：测试用例文档（zt_file 238）已 uploadBind 挂 6566，test_case_url 刷新，下载 200/12566B（curl 中文 title GBK 乱码已 DB 修正——框架 python 上传无此问题）。
---
## AI 指标区块撤掉三个人员字段（2026-07-29，用户拍板）
productPerson/developPerson/testPerson 三字段无自动数据源（打分弹窗手填，6566 为 SQL 调试数据）→ 研发详情 AI 指标区块撤下这三项展示（storyinfo/components/product.vue，9 项保留）。**不动**：zt_story_expand 三列、打分弹窗、需求报表列（属工时统计功能）；右侧基本信息的产品经理/测试人员为 zt_story 自有字段，保留。已同步 F:\zd，8089 实测截图 tmp/pw_6566_ai_block.png。
---
## 测试报告模版生成+传禅道（2026-07-29）
`06_test_docs/test_report_template.md`（7 节：概述/环境/执行汇总/36 条明细空表/缺陷统计/回归/结论签字）→ uploadBind(objectType=testReport) 挂 6566（zt_file 239，test_report_download_url 刷新，下载 200/2348B）。6566 测试类文档现状：用例✓ 模版✓ 提交件✗（待执行）其他✗。
---
## 200→161 全库复制 + zentao_dev_2026 增量 DDL（2026-07-29）
**复制**：200 zentao_dev（只读，94 表 2.6GB）→ 161 zentao_dev_2026。zt_action/zt_actionrecent 按计划只建空表；其余 92 表行数对拍全部一致；中文抽查正常。过程排障：161 元数据锁（残留事务→DROP TABLE 排队→新连接挂起），KILL 阻塞线程后恢复；max_allowed_packet=64MB 导致大字段表断连 → 脚本按 12MB 分包+断点续跑+重试（tmp/db_copy_200_to_161.py）。
**增量 DDL（用户指定只加字段不含数据）**：zt_file.url、zt_meeting.url、zt_story 7 url 列+code_review_status、zt_story_expand ai_participation_rate+acceptance_criteria 共 12 列 + zt_perf_config/zt_doc_check 两空表，幂等脚本 tmp/apply_ddl_2026.py，验证通过。**未加（属数据）**：zt_perf_config 61 行规则种子、ai 用户、绩效菜单 base_menu——跑绩效功能前需补。
---
## CHG-028 饱和度达标工时口径修正（2026-07-29）
用户发现：郭尚雨 6 月老月报 91% vs 新绩效 104%——排查为分子差异（老=分配工时 estimate、新=实绩 consumed），属口径并存（老报表不动）。另发现实现误用老系统分母（工作日×8−请假）×0.75，与 xlsx/PRD §7.3「团队总工作天数×5」不符 → 用户拍板改为 **（当月工作天数 − 请假小时÷8）×5**（半天=0.5 天），分子维持 zt_effort.consumed。WorkSaturationCalculator 已改；单测 15/15 绿（新增请假半天用例）；规则配置无需改（百分比规则不变）。PRD v1.26、decision_log 已录。**注意**：8085 重启后生效；分母变小（5h/天 vs 6h/天）→ 饱和度百分比整体上升，历史月份重算分数会变高，属预期。
---
## CHG-029 老模块饱和度统一（2026-07-29，8086 实测一致）
用户拍板"再老的改"。排查发现 91/104 均为老模块（IZtCountService）两方法口径分叉：月报分子排除 closed/cancel 任务、地盘不排除。统一为新口径：分子=实绩工时（zt_task.consumed，全状态任务）、分母=（工作天数−请假小时÷8)×5。改动 IZtCountService 5 处（setUserWorkTime、buildKFZScore 分子+workTime 全集、地盘方法分母+分子、项目组汇总分子、buildXMZLScore 显示）。**8086（2026 库）实测郭尚雨 2026-06：月报列表 saturation=1.25、地盘绩效 saturation=1.25，完全一致**（131h÷105h）。注意：①老模块分子用 zt_task.consumed（131h），新绩效模块用 zt_effort（86.5h）——两表数据不一致导致老页面 125% vs 新绩效 82.4% 得分 64，属数据源差异，后续要么对齐数据源要么老页面淘汰；②8085 需用户 IDE 重编译重启生效；③前端 axios 带 Authorization 头，curl 直调需 -H "Authorization: token"（"token" 头过滤器不读）。
---
## CHG-030 aiBatchAdd 工时预算校验（2026-07-29，8086 实测通过）
用户拍板"拆的任务工时不能比研发需求总工时高"。aiBatchAdd 新增预算校验：已有任务 estimate 合计 + 本批新增（dup 跳过项不计）> zt_story_expand.evaluation_time → 整批拒绝（报文明细：已有Xh+新增Yh>预算Zh）；无评估工时不设防。单测+4（预算内放行/超额拒绝/已有任务计入/无预算放行，8/8 绿）。**8086 实测**：22h 已有下 12h 新增被拒（消息正确含"新增0h"重复项剔除）、22+2>10 被拒、调 30h 后 24≤30 放行（created=1+skipped 重复项）。测试数据已清理。注意：2026 库（200 镜像）zt_story_expand.evaluation_time 全列为空 → 预算校验在该库当前不触发（无预算数据），生产/老库有评估工时后才生效；8085 需 IDE 重编译重启。
---
## CHG-032 撤销禅道侧工时校验（2026-07-29）
用户明确"禅道不能做校验" → CHG-030 全部回滚：ZtTaskServiceImpl.aiBatchAdd 恢复原状（预算校验+storyExpandService 注入移除），AiBatchAddServiceTest 4 个预算用例移除（回 4/4 绿）。工时匹配纪律只在框架侧：拆任务时 Σ任务工时=需求评估工时（PRD FR-006 规则5、tgassist PJM 纪律，均已去掉"禅道兜底"表述）。8085 重编译后 aiBatchAdd 回到无校验状态。
---
## CHG-029 全量验证闭环（2026-07-29，8086 实测）
补改最后一处漏网：workDetailsCount（开发者工作统计）saturation 分子 storyTotalTime(estimate)→workTime(consumed)。四处实测（郭尚雨 2026-06，2026 库）：月报(全产品集)=1.25、月报(119 中道救援)=1.09、地盘绩效=1.25、开发者工作统计(119)=1.09——公式全统一（consumed÷(21×5=105h)），109 vs 125 纯产品集筛选范围差异（119 线下 114h vs 全部 131h），与用户页面所见完全吻合。buildXMZLScore 达标工时显示同步新口径。
---
## CHG-034 达标工时团队口径（2026-07-29）
用户指出 CHG-028 实现不符 xlsx 字面（"完全不是一个东西"）→ 改严格团队口径。新模块 WorkSaturationCalculator 与老模块 4 处（setUserWorkTime/地盘方法/XMZL 显示/项目组汇总经 dto 传递）统一 teamExamineTime。单测 15/15 绿（新增团队平摊用例：(w×2−0.5)×5÷2）。8086 实测：2026 库 KFZ=13 人、6 月无请假 → 团队口径=(21×13−0)×5÷13=105h，地盘绩效 examineTime=105.0/saturation=1.25 一致（无请假时与个人口径同值）。**未能实测请假平摊**：os_system.it_approval 是 join 视图不可写，且 2026 全年无请假记录；单测已覆盖。**遗留口径疑点**：getApprovalTime 同日分支直接累加 apply_days（单位疑为小时，与老代码用法一致按小时/8 折算；OA 无数据可校，若实际为天需改折算）；张富斌（测试）user_type=KFZ 被计入团队人数——xlsx 要求"后端+前端"，若其为测试应改 user_type 或另行排除，待用户确认。
---
## 前端老口径描述改新 Excel（2026-07-29）
用户指出月报点击查看仍显示老描述。改 3 文件：performance.vue（KFZ 考核表：月度达标工时公式→团队总工作天数×5÷开发人数/请假全团队摊、数据映射 有效工时allocationTime→实际产出工时workTime；代码质量 5%→10%且规则改 xlsx 初审/复审两段；文档质量 15%→10%；不规范行为描述改 xlsx 六维度）、reportForms.vue（工作饱和度 tooltip+注释块→实绩÷月度达标工时）、monthReport.vue（列头"可用工时(6*工作天数)"→"月度达标工时"，数据列 haveTime 本就是团队口径 105h）。已同步 F:\zd，8089 热更新编译通过。**注意**：地盘绩效页得分计算（saturationScore 等）仍是老规则，与页面上新 Excel 描述并存——完整新算分在 /perf/report，老页淘汰前存在此割裂，已在 PRD 7.5 标注 ❌/🔶 项。
---
## CHG-035 三期绩效页面下线（2026-07-29，用户拍板）
用户："不需要这些页面，月报的绩效按钮就是人工评分"。2026 库删除绩效菜单 13 行+授权 37 行；恢复备份 sql/20260729_insert_perf_menu.sql（列名完整，50 INSERT）。页面代码/zt_perf_config 61 规则/zt_doc_check 保留未删。人工评分=月报「绩效」按钮（老 editDialog 流程）。8085 重新登录后菜单消失。FR-012/013/014 功能本体保留，仅入口下线。
---
## CHG-036 老弹窗得分改新 Excel（2026-07-29，8086 实测通过）
方案经用户确认后实施：utils/PerfScoreRules 纯函数（及时完成25：95段扣1/94段扣2 分段累计；Bug密度30：>15%每增1%扣3分无截断；饱和度20：<100%每减1%扣2分）+ IZtCountService.buildKFZScore 接入（punctuality/bugDensity/saturation 三分项替换，codeQuality 5→10、documentQuality 15→10、workAttitude 5 满分默认）。**弹窗路径核实**：月报 查看/绩效按钮 → performance.vue → myWorkScore → buildKFZScore（KFZ），总分由前端 sum（六得分项+两加分项）自动合成。PerfScoreRulesTest 3/3 绿（分段/截断/科学计数 BigDecimal 归一）。**8086 实测郭尚雨 2026-06**：saturation 1.25→20、及时率 1.0→25、bugDensity 4%→30、三项人工满分，总分=100，与新 Excel 逐项吻合。月报列表 DTO 不带得分字段（只展示比率列）不受影响。buildCsScore（标注"老的"）无调用方，顺带对齐不影响任何页面。8085 需 IDE 重编译重启。
---
## CHG-037 老绩效弹窗全岗位改新 Excel（2026-07-30，8086 实测通过）
**背景**：CHG-036 只改了 KFZ 弹窗得分；本次把月报「绩效」弹窗其余岗位全部切到新 Excel（SRC-002）口径，岗位得分改由新绩效引擎（zt_perf_config 规则）按 score×weight 加权产出。
**后端**：
- PerformanceDTO 新增 7 字段：workloadPrdScore/workloadTeamScore/opsMajorTaskScore/opsMonitorScore/opsInspectScore/opsBackupScore/otherOpsScore。
- IZtCountService 新增 perfItemScore(scope, itemKey, default)：按岗位 itemKey 从 perfReportService.report 取加权得分；指标无数据/人工项（score=null）给满分默认。
- buildXMJLScore（项目经理）重写：PRD完成率20/团队完成率30/版本计划10/线上Bug10/文档齐备10/问题管理5/稳定性10/技能5；王宇航按 account 走 projectManagerWyh 变体（无 PRD 项、团队40、稳定性20）；旧 programCount/任务管理/Bug管理/会议管理 附加计算废弃。
- buildCPJLScore（产品经理）：PRD完成率40/团队完成率20/项目准时率10/产品缺陷率15/问题响应10/主动性5；展示字段（计划/准时上线数、严重/普通 Bug 数）保留原取数。
- buildXMZLScore（产品助理）：PRD完成率50/及时验收20（人工默认满分，zt_story_user 验收链断裂维持人工）/产品缺陷率15/问题响应10/主动性5。
- buildYwScore（运维，新增方法+UserType.YW 调度分支）：大项任务20/监控15/巡检10/备份10 走引擎（opsEngineer 4 项 calculator），其他运维15/稳定性20/不规范行为10 人工满分默认。
- buildCScore（测试）及时完成改 PerfScoreRules.testerPlanScore（=100%得20，每减1%扣2分）；buildUiScore 改 uiPunctualityScore（=100%得50/90%+得40/<90%得0）。
**前端**（performance.vue，已同步 F:\zd\web_zentao）：XMGLY/CPJL/XMZL 三区块按 xlsx 全量重写（行/权重/评分标准/得分说明逐字对齐 SRC-002）；新增 YW 区块（含创新贡献加分项）；新增王宇航变体块（account 判断先于 userType switch）；juedgeRole 加 YW；各区块总计 amountTo 同步新得分字段。
**验证**：
- 单测：PerfScoreRulesTest +2（testerPlan/uiPunctuality 分段边界，5/5 绿）；perf 包+Ops/Bug 计算回归 33 绿。
- 8086（2026 库）myWorkScore 六账号实测：王宇航 workloadTeamScore=35.6、孙世超 26.7、魏冬霞 workloadTeamScore=15.6/productBugRate=15、李语嫣 releaseScore=20/productBugRate=15、岑海峰 opsMonitor=12.75/opsInspect=7.5/opsBackup=9.7/otherOps=15、刘圣清 designScore=40/workAttitude=10——各岗位得分字段均按新口径产出。
- 8089 弹窗截图四岗位通过：王宇航（tmp/pw_chg037_wangyuhang.png，总分 85.6）、蒋恒·项目经理（tmp/pw_chg037_jiangheng.png，总分 66.7）、李语嫣·产品助理（tmp/pw_chg037_liyuyan.png，总分 50）、刘圣清·UI（tmp/pw_chg037_liushengqing.png，总分 50）。
**注意/遗留**：
1. 8085 需用户 IDE 重编译重启生效；本次验证用 8086（已含本改动）+ 8088（8089 dev server 默认端口 8088，临时以 VUE_APP_BACK_REST_URL=8086 启动，未改 .env.local）。
2. CPJL（魏冬霞）/YW（岑海峰）在 2026 库 2026 全年无任务，月报列表不出行，弹窗未截图；两岗位得分字段已经 8086 API 实测，前端结构经语法+字段绑定核对。
3. 版本计划完成率多人为 0：2026 库版本发布数据稀疏，引擎按实数算出 0（非默认值缺失），生产数据下另行观察。
4. 人工评审项（其他运维/稳定性/不规范行为/问题管理/技能等）满分默认，IT 经理弹窗手改后提交，老流程不变。
---
## CHG-038 KFZ 前后端工程师分流（2026-07-30，8086 实测通过）
**背景**：用户拍板——新 Excel 前端/后端工程师是两张表（前端：饱和度30%、无文档质量项、代码质量 flat 每问题扣3；其余逐项相同），系统 user_type 只有 KFZ 无法区分 → 加「开发方向」标识，用户拍板维护入口=用户新增/编辑表单下拉。
**DDL**：`zt_user` 加 `dev_direction` varchar(16)（frontend=前端/backend=后端，NULL 按后端口径，仅 KFZ 有效），161 zentao_dev+zentao_dev_2026 已执行 + `sql/20260730_alter_zt_user_dev_direction.sql` 迁移文件。
**后端**：
- ZtUser/ZtUserDTO 加 devDirection；addUser 非 KFZ 置空、modifyUser 同步 setter（非 KFZ 置空）；pageList/登录返回自然带出。
- PerfScoreRules.saturationScore 参数化满分（rate, full），新增 FULL_SATURATION_FRONT=30；原 20 满分重载委托保持 CHG-036 行为。
- buildKFZScore 分流：frontend → 饱和度满分 30、文档质量项不设（DTO 初始 0，前端表无此项）、devDirection 透出；backend/NULL → 原口径不变。PerformanceDTO 加 devDirection。
**前端**：
- 用户新增/编辑弹窗（user/dialog/addDialog.vue、editDialog.vue）：用户属性=开发者时出现「开发方向」下拉（前端/后端，必填校验仅 KFZ 生效）；编辑经 leftCopy 自动带出已存值。
- performance.vue：KFZ case 按 isFrontDev()（优先 myWorkScore DTO.devDirection，其次行数据/登录用户）分流两个区块——前端块：饱和度30%、无文档质量行、代码质量 flat 描述、amountTo 剔除 documentQualityScore；后端块维持原样；getMyWorkScore 拿到 DTO 后重建表格保证方向准确。已同步 F:\zd\web_zentao。
**验证**：
- 单测 PerfScoreRulesTest +1（前端饱和度 30/20/0 边界+默认 20 兼容，6/6 绿）。
- 8086（2026 库）实测：郭尚雨临时标 frontend → myWorkScore 返回 devDirection=frontend、saturation 1.25→**saturationScore=30**（后端口径应为 20）、documentQualityScore=0（不计）；弹窗截图 tmp/pw_chg038_guoshangyu_front.png——饱和度 30% 得 30、无文档质量行、代码质量 flat 描述、总分 100。金亮（NULL）对照截图 tmp/pw_chg038_jinliang_backend.png——后端块不变（文档质量行在、初审/复审描述）。用户编辑弹窗截图 tmp/pw_chg038_user_form.png——开发者属性下出现「开发方向」下拉且正确带出「前端」。测试后郭尚雨 dev_direction 已复位 NULL。
- myWorkScore 注意：zt_month_score 有已存快照的月份返回快照不重算（既有行为），分流只对未保存月份生效。
**待办**：现有 KFZ 人员 dev_direction 全 NULL（=后端口径），等用户提供前后端名单后一次性 SQL 初始化。
---
## CHG-037 补测：CS 测试工程师（2026-07-30，8086 实测通过）
首轮验证漏掉 CS 分支，补测：API——孙庆方 2026-06 及时率 96%→punctualityScore=12（testerPlanScore 20−4×2，CHG-037 新口径生效）、文洋洋 80%→0、检出率 29%/53%→bugFindScore=30、无线上 Bug→bugScore=20、测试文档 25/不规范行为 5 人工满分默认；弹窗截图 tmp/pw_chg037_cs_sunqingfang.png（五项得分 12/30/20/25/5、总计 92 与 API 一致）。admin（GSGC）API 确认走 buildXMJLScore 项目经理口径。**注意**：CS 分支 myWorkScore 响应约 8~10s（getBugFindScore 重查询，既有行为非本次引入），弹窗需等待数据返回；首轮截图空数据即等待不足所致，非缺陷。至此 9 张岗位表全部实测覆盖。
---
## CHG-038 前后端名单初始化（2026-07-30，用户拍板）
用户提供名单：**前端=周林芳、张富斌、孟冉**，其余 KFZ 一律后端。两库已刷：zentao_dev 前端 3/后端 13、zentao_dev_2026 前端 3/后端 10（含原 NULL 全部补齐 backend，无 NULL 遗留）。张富斌 CHG-034 遗留疑点一并关闭——确认为前端开发（维持 KFZ，不改 CS）。8086 实测周林芳（6 月 139%）弹窗=前端块：饱和度 30% 得 30、无文档质量行，截图 tmp/pw_chg038_zhoulinfang.png。
---
## 月报出行机制澄清 + 运维入口解决（2026-07-30，用户拍板"找个迭代加一下"）
**机制定论**（修正 CHG-037 遗留#2 的表述）：月报列表=产品集→项目→执行（zt_executionproject）→过滤「begin 或 end 落在当月」的执行→取执行团队成员（zt_team）。三点推论：①产品经理挂在执行团队里就会出行，**跟有无任务无关**——魏冬霞 6 月不出行只是因为她在 139 飞侠车服而非当时查看的 119，切到 139 即在列（弹窗实测 45.6 分：团队15.6/缺陷15/响应10/主动5/准时0——计划45上线32）；②长期迭代（如 146 代驾主流程 2025-02~2027-03）begin/end 永不落当月 → 成员任何月份都不出行（既有逻辑，未动）；③生产 161 当前（2026-07）无任何 begin/end 落 7 月的执行，月报 7 月暂空属数据现状。
**运维入口**：岑海峰两库原本 0 任务 0 团队。按用户拍板：zentao_dev_2026 加入 车服-20260730（307，7/6-7/30 窗口内）→ 7 月 139 列表出行，YW 弹窗实测总分 74.8（监控12.3/巡检7.5/备份10/其他15/稳定20/行为10），截图 tmp/pw_yw_cenhaifeng.png；zentao_dev（生产）同步加 146（占位，窗口外不出行，待 8 月新迭代建立后把运维加进当月迭代即可）。**至此 9 张岗位表弹窗全部实测通过**（CPJL=魏冬霞 tmp/pw_cpjl_weidongxia.png、YW=岑海峰）。
---
## CHG-039 workloadRatePrd 人员匹配修复（2026-07-30，8086 实测通过）
**发现**：用户质疑"魏冬霞 6 月工作量指数为 0 对吗"→ 排查：WorkloadRatePrdCalculator 按 `product_person LIKE account` 过滤，但该列实际存**中文姓名**（"魏冬霞"，多人逗号分隔如"蒋恒,李淑敏"）→ 恒不匹配，分子恒 0 → 项目经理/产品经理/产品助理的 PRD 完成率得分恒 0（假"未达标"）。
**修复**：scopeStoryIds 改按昵称匹配（userService.getByAccount→nickname），account 兜底（未来写英文账号也兼容）。单测 +1（昵称路径+验证 getByAccount 调用；account 兜底由原用例覆盖），WorkloadRateCalculatorsTest 5/5 绿。
**8086（2026 库）实测**：魏冬霞 workloadPrdScore 0→**40**（6 月指数 314.03÷105=299% 满分）；孙世超 0→**20**（满分）；李语嫣仍 0——她两库 expand 都是 0 行（无任何需求把 product_person 写成她），属数据缺失非匹配问题，若业务上 PRD 归她需补 product_person 数据。
**注意**：8085 需再次重编译重启加载本修复；生产 zentao_dev 的 zt_story_expand 仅 6 行（含"产品""张三"等脏数据），PRD 完成率指标要等评估流程把 product_person 写起来才真正可用。
---
## 0 分专项排查 + CHG-040 opsMajorTask 匹配修复（2026-07-31）
**背景**：用户要求"所有得分为 0 的认真检查"。对 9 个代表账号（2026 库，2026-06）逐项下钻，分类定论：
| 得分项 | 账号 | 判定 |
|---|---|---|
| UI 任务及时 punctualityScore=0 | 刘圣清 | 真 0（6 月无任务，规则内） |
| 版本计划 versionPlanFinishedRate=0 | 孙世超/王宇航 | **口径问题**：6 月发布需求 123 个但 estimate 全 0/NULL → 分母 0 → percent() 按 0% 扣分；非"没按时发布"。待用户拍板（补 estimate / 分母 0 按个数算 / 给满分豁免 / 维持） |
| 项目准时率 productProjectOnTimeRateScore=0 | 魏冬霞 | 真 0（计划 45 准时 32=71%，<90% 每减 1% 扣 2 → 扣完） |
| PRD 完成率 workloadPrdScore=0 | 李语嫣 | 数据缺失（无需求 product_person 写她名，两库均 0 行） |
| 大项任务 opsMajorTaskScore=0 | 岑海峰 | **bug**：zt_yw_task.belong_to_user 存中文姓名按 account 匹配恒空（CHG-039 同类） |
**CHG-040 修复**：OpsMajorTaskCalculator 按昵称匹配（注入 IZtUserService，and 嵌套 OR+final 变量），account 兜底；单测+1（OpsCalculatorsTest 9/9 绿）。8086 实测：6 月=0（真 0，1 任务未完成）、7 月=**13.2**（3 任务 2 及时→66 分×0.2，与手算一致）。zt_yw_fwqsearch/patrol/backups 三表经核实存 account，监控/巡检/备份三项不受影响。
**8085 需再次重编译重启**（本修复+CHG-039）。
---
## CHG-041 绩效弹窗「绩效数据」列补过程值（2026-07-31，8086 实测通过）
**背景**：用户要求"所有人的绩效数据那一列给值（分子分母等）"——CHG-037 各岗位弹窗的绩效数据列大量留空，得分看不到依据。
**链路**：计算器（ThreadLocal rawDetail，compute 入口清除防串）→ PerfIndicatorCalculator.consumeRawDetail（接口默认 null）→ ZtPerfReportServiceImpl.computeScope 收集并挂到 PerfMonthScope.Item.rawDetail（随 scopeJson 落库快照也带）→ IZtCountService.fillRawDetail 拷入 PerformanceDTO.perfRawDetail（buildXMJL/CPJL/XMZL/YW 四方法）→ 弹窗模板：data 绑定值以 `#itemKey` 开头时渲染 dataObj.perfRawDetail[itemKey]（无数据显示 —，rawDetailOf 方法）。
**各指标明细格式**：工作量指数 "Σ指数 X / 达标 Yh = Z%"；版本计划 "按时 Xh / 总发布 Yh = Z%（发布 n 个）"；线上Bug/缺陷率 "Bug n 个（重大 x/普通 y）/ Σ工时 Yh = Z‰（豁免线 5‰）"（非豁免口径="按个扣分"）；项目准时率 "准时 x / 规划 y = Z%"；运维大项 "及时 x / 到期 y = Z%"；运维周频次 "实做 x / 应做 y（缺 z 次）"；文档齐备 "缺失 n 份 × 扣 x 分 / 缺失 0 份 / 当月无核查记录"。
**弹窗绑定**：XMGLY/wyh/CPJL/XMZL/YW 五区块 19 行挂上明细（线上Bug 行原绑定的 普通/重大BUG数量（后端不赋值恒 0 误导）一并替换为明细；CPJL 准时率/缺陷率保留原展示字段追加明细）。CS/KFZ/UI 区块本就有 DTO 实值，不动。
**验证**：单测 63 全绿（rawDetail 调用不影响既有断言）；8086 实测——孙世超 workloadRatePrd "Σ指数 242.8 / 达标 105h = 231.24%"→20、workloadRateTeam "Σ指数 1076.53 / 达标 1365h = 78.87%"→26.7、versionPlanRate "按时 0h / 总发布 0h = 0%（发布 123 个）"→0（估算口径问题直接可见）；蒋恒弹窗截图 tmp/pw_chg041_jiangheng.png 五行明细全渲染。
**注意**：8085 需重编译重启（含 CHG-039/040/041 三批）；老快照月份（zt_month_score 已存）明细为空显示 —，属正常。
---
## CHG-042 项目经理 PRD 完成率改团队口径（2026-07-31，用户拍板）
**背景**：用户指出"孙世超是项目管理员，他的（PRD 完成率）不是他一个人的，是项目所有人"——xlsx 项目经理表 PRD 完成率与团队完成率同公式（分母"团队可用工作天数×5"、"除测试人员外其他岗位都作为工作量产出方纳入统计"），个人口径理解有误。
**改动**：WorkloadRatePrdCalculator 按岗位分流——projectManager/projectManagerWyh：范围=全部需求（不按 product_person 过滤）、分母=工作天数×5×产出人数（devProducerCount，KFZ 全员）；产品经理/产品助理维持个人口径（product_person 昵称匹配+个人工时）不变。
**验证**：单测+1（团队口径不过滤+分母乘人数+不查 expand，6/6 绿）；8086 实测 6 月——孙世超/蒋恒 workloadPrdScore 20→**15.6**（Σ指数 1076.53/达标 1365h=78.87%，每减 1% 扣 1 → 78×0.2），魏冬霞（产品经理）40 不变（个人口径 299.08%），李语嫣 0 不变（个人口径无数据）。
**注意**：8085 需重编译重启（含 CHG-039~042 四批）。
---
## CHG-043 项目经理两项完成率改项目口径（2026-07-31，用户拍板"按照迭代来"）
**背景**：CHG-042 把项目经理 PRD 完成率改成全部门口径（分母=全部 13 KFZ）后，用户拍板应按"他下面的开发"算——即他当月窗口内参与的迭代（执行）成员。
**口径**：项目经理（含王宇航变体）的 workloadRatePrd 与 workloadRateTeam 两项统一为项目口径——
- 分子 = 他**当月窗口内**（迭代 begin 或 end 落当月，与月报列表过滤同一约定，长期迭代不算）参与的执行 → 关联产品的需求 workload_index 和；
- 分母 = 工作天数×5×**这些执行的 KFZ 成员去重数**（测试不计；他本人 XMGLY 非 KFZ 天然不含）；
- 无在窗执行 → 分子 0/分母 0 → 该项 0 分。产品经理/助理维持个人口径、产品/其他岗位的"团队完成率"维持部门口径不变。
**实现**：AbstractWorkloadRateCalculator 新增 projectExecs/projectScopeStoryIds/projectProducerCount 三方法（team→execution→project→product→story 链），producerCount 钩子加 month 参数；Prd/Team 两计算器按 isProjectManager 分流。单测重写 1 例（项目口径全链路 mock+不查 expand 断言），6/6 绿。
**8086 实测 6 月**：孙世超 Σ556.83/525h（5 人）=106.06% → PRD 20/团队 30 双满分；蒋恒 Σ519.7/945h（9 人）=54.99% → PRD 10.8/团队 23.1；王宇航 Σ0/630h=0% → 按规则 50 分×0.4=20（项目当月无产出记录，非满分豁免）；魏冬霞（产品经理）不变。
**注意**：8085 需重编译重启（CHG-039~043 五批）；蒋恒/孙世超人数差异源于各自在窗执行不同成员集；代码窗口约定（begin/end 落当月）不含跨月长期迭代，与月报列表一致。
---
## CHG-044 达标工时全链路上弹窗（2026-07-31，8086 实测通过）
**背景**：用户要求"分子分母都要列出来"——KFZ 弹窗工作量饱和度行原来只有 实绩/人均达标工时/饱和度，看不到团队口径的中间量。
**改动**：PerformanceDTO +3 字段（teamWorkDays 团队总工作天数·人天、teamLeaveDays 团队请假折算天数、teamTargetTime 团队达标总工时）；IZtCountService 新增 fillTeamExamine（setUserWorkTime 调用，KFZ/CS/UI/XMJL 链路全覆盖），teamExamineTime 与请假折算抽取 teamLeaveDays 共用；performance.vue 两个 KFZ 块饱和度行绑定补齐五行。
**展示效果**（郭尚雨 6 月）：实际产出工时 131 / 团队总工作天数 273 / 团队达标总工时 1365 / 月度达标工时 105 / 工作饱和度 125% → 得分 20。截图 tmp/pw_chg044_guoshangyu.png。8086 API 同值验证；单测无回归（Misc/PerfScoreRules 21 绿）。8085 需重编译重启。
---
## CHG-045 版本计划完成率改工作量指数加权（2026-07-31，用户拍板"workload_index 用这个"）
**背景**：版本计划完成率原按 zt_story.estimate 加权，123 个 6 月发布需求 estimate 全 0 → 分母 0 → 孙世超/王宇航该项恒 0（假"未达标"）；用户拍板改用 zt_story_expand.workload_index。
**改动**：VersionPlanRateCalculator 加权源 estimate → expand.workload_index（String 列，parseIndex 非数字/空按 0；无 expand 行自然不进分子分母）；明细改"按时 X / 总发布 Y（指数加权，发布 n 个）= Z%"。单测改写+新增各 1（指数加权正常值、无指数分母 0 边界），Misc 16/16 绿。
**8086 实测 6 月**：孙世超 versionPlanFinishedRate 0→**5.4**（按时 477.1/总 658.21=72.48% → 100−23×2=54 → ×0.1）。覆盖说明：123 个发布需求仅 34 个有 expand 指数，无指数需求按 0 权重不进分子分母（占比失真风险随评估流程覆盖率提升自然消解）。8085 需重编译重启。
---
## CHG-046 《AI项目文档更新记录》独立承载全链路（2026-07-31，用户拍板"加字段+功能完善+前端展示"）
**背景**：五类文档中仅《AI项目文档更新记录》无独立承载（原设计寄身 aiWorkLog 的 doc_update 类，从未产出，全库零命中）。
**改动**：
1. DDL：zt_story 加 `ai_doc_update_url` varchar(512)，161 两库已执行 + `sql/20260731_alter_zt_story_doc_update.sql`。
2. FileTypes 增 `aiDocUpdate("aiDocUpdate","AI项目文档更新记录")`；uploadBind(refreshOwnerUrl) 增该类型→刷新 zt_story.ai_doc_update_url；ZtStory 实体加字段（MP 自动映射，无需 XML）。
3. FR-014 核查判定改通道：DOC_DOC_UPDATE 由"zt_file(aiWorkLog) doc_update 类"改为 **zt_file(aiDocUpdate)**，detail 同步；DocCheckServiceTest 断言更新（4/4 绿）。
4. 前端 storyinfo/components/product.vue 研发需求详情新增《AI项目文档更新记录》区块（工作日志与交付物之间）：文件列表+上传按钮（aiDocUpdate），aiDocUpdateFiles+fileFieldMap+fetchObjectFiles 三处接线。已同步 F:\zd。
**8086 全链路实测**：multipart 上传测试 MD 到 6566 → code:0（zt_file 8799）→ zt_story.ai_doc_update_url 刷新 → fileList 返回该文件（注意：fileList 无 @RequestBody，必须 form 表单传参，JSON 体不绑定）→ 6566 详情页新区块渲染文件+上传按钮（截图 tmp/pw_chg046_6566.png）。curl 上传中文 title GBK 乱码已 DB 修正（已知 curl 老问题，框架/浏览器上传无此问题）。**8085 需重编译重启**。
**说明**：①快照/实时判定之争本轮不动（用户问的是承载）；②框架侧生产 doc_update 内容仍待 DT9 挂钩点补齐（现以手动上传为主）；③zt_doc_check 六月快照范围不含 6566（其月工作量不在 6 月），核查翻牌效果待真实大型需求上传后自然呈现。
---
## CHG-047 文档齐备改实时字段判定+项目口径（2026-07-31，用户拍板"需求的 url 字段直接判断"）
**背景**：①快照归属错位——项目经理"文档齐备"按 assignedTo 归集，孙世超项目 4 个大型需求五类全缺（20 份），扣分却挂在 luoyong/sunying（其考核表无此项），孙世超反显满分；②用户拍板不要快照表/月末 job，直接读需求 url 字段实时判。
**改动**：DocReadyScoreCalculator 重写（继承 AbstractWorkloadRateCalculator 复用 CHG-043 项目口径取数）——
- 判定：大型需求（当月有指数记录且指数>20）的 **zt_story 五个 url 字段**（testCaseUrl/testReportSubmitUrl/aiDocUpdateUrl/codeReviewUrl/workLogUrl）非空即在，缺失 n 份 × 扣 2 分扣完截止；
- 归属：projectManager/projectManagerWyh ∩ 他当月窗口内执行关联产品的大型需求；其他岗位=全量大型需求；
- 明细："大型需求 m 个，缺失 n 份（8930缺[用例，报告，更新记录，审查，日志] …）"；
- 不再读 zt_doc_check 快照（表与手动触发接口保留，矩阵页已下线）；TestDocReadyCalculator（CS 测试文档项）不动。
**验证**：单测改写 2 例+新增 1 例（项目口径缺 2→96/无指数记录→100/无在窗执行→100），Misc 17/17 绿。8086 实测 6 月：**孙世超 满分 10 → 6**（4 个大型需求×5 类全缺=20 份×2=扣 40，明细逐需求列出缺失类型）；王宇航 10（项目范围当月无大型需求）。8085 需重编译重启。
**后续提醒**：zt_doc_check 快照表与 generateDocCheck 接口已成摆设（仅矩阵页用，已下线），可择机清理；异议流程随快照一并闲置。
---
## CHG-048 PRD 完成率项目口径扩到产品经理/助理（2026-07-31，用户拍板"跟项目管理员一样的方案"）
**背景**：魏冬霞 PRD 完成率原按个人口径（product_person 名下 314.03/105h=299.08%），用户指出 xlsx 该公式与项目管理员同文字（"团队可用工作天数×5"、"除测试外都纳入统计"），应同方案。核实：她与孙世超同属车服团队（在窗执行同为 286/297/300/301 → 产品 150）。
**改动**：WorkloadRatePrdCalculator 项目口径分支由 projectManager/projectManagerWyh 扩到 productManager/productAssistant（isProjectScopedRole 四角色统一：范围=当月窗口内执行关联产品的需求、分母=执行内 KFZ 成员数×天数×5）；product_person 个人口径保留为其余角色兜底（实际已无使用者）。团队完成率（workloadRateTeam）维持 CHG-043 不变（项目经理=项目口径，其余=部门口径）。
**验证**：单测默认角色改 backendDev（个人兜底路径保持覆盖）+新增 CPJL 项目口径用例，WorkloadRate 7/7、Misc 17/17 绿。8086 实测 6 月：魏冬霞 314.03/105(299.08%) → **556.83/525h=106.06% → 40 满分**（与孙世超同数据源，数值收敛合理）；李语嫣 0 不变（她项目产品 145 当月无指数记录，属数据缺失）；孙世超不变。
**注意**：①李语嫣的 0 根因=产品 145 无工作量数据（非口径）；②四角色的 PRD 完成率与团队完成率现在数据源差异=项目 vs 部门，xlsx 两行得以区分；③8085 需重编译重启。
---
## CHG-049 版本计划完成率改项目口径（2026-07-31，用户拍板"孙世超是飞侠的为啥不区分"）
**背景**：versionPlanRate 原全表统计（145/150/161 三产品混算 72.48%），且指数覆盖严重不均（150 占 30/34 权重、145 道路救援 72 个发布仅 1 个有指数）——孙世超是飞侠车服项目经理，应按其项目产品区分。
**改动**：VersionPlanRateCalculator 继承 AbstractWorkloadRateCalculator 复用 CHG-043 项目口径：projectManager/projectManagerWyh 只统计他当月窗口内执行关联产品的发布需求（其余角色=全表兜底，当前无使用者）；指数加权逻辑（CHG-045）不变。单测版本正常用例补项目 mock（Misc 17/17 绿）。
**8086 实测 6 月**：
- 孙世超 5.4→**9.4**：按时 477.1/总发布 516.61（发布 38 个·产品 150）=92.35%，每减 1% 扣 2 → 94×0.1
- 王宇航 0：按时 0/总发布 33（发布 72 个·产品 145 道路救援）=0%——他项目是道路救援，72 个发布仅 1 个有指数（权重 33 且未按时），覆盖率不足致其版本率失真（单需求决定 100%）
**注意**：145 产品线指数覆盖率 1/72，王宇航的版本率在该产品评估流程跑起来前不可用于考核；8085 需重编译重启。
---
## CHG-050 Bug 率 5‰ 豁免复活：分母改任务工时+项目口径（2026-07-31，用户拍板"需求工时是任务sum"）
**背景**：线上Bug率/产品缺陷率的 5‰ 豁免分母原取 zt_story.estimate（全库未填）→ 率恒 0‰ 恒豁免，用户在车服加 6 月线上 Bug（zt_bug 2566，普通，挂 8277）验证发现扣分不触发。
**改动**（AbstractWeightedBugCalculator 继承 AbstractWorkloadRateCalculator 复用项目口径）：
1. 分母 zt_story.estimate → **当月上线需求的 devel 任务 estimate 合计**（用户拍板"需求工时是任务sum"）；
2. 四角色（项目经理/王宇航/产品经理/产品助理）上线需求范围 ∩ 当月窗口内执行关联产品（同 CHG-043 项目口径）；
3. 无上线需求 → 满分并注明（项目范围）。
**验证**：单测 exempt 两例改任务工时 mock+项目 mock（Bug 12、Workload 7、Misc 17 全绿；排障一例：mock 执行时间跨月末边界致项目范围为空）。8086 实测 6 月（测试 Bug 2566 在库）：孙世超 **9.7**（1 普通/165.5h=6.04‰>5‰ → 扣 3 → 97×0.1，明细"Bug 1 个（重大 0/普通 1）/ Σ工时 165.5h = 6.04‰"）；王宇航 10（项目 0 Bug/275.5h 豁免）；魏冬霞产品缺陷率 **14.55**（同 Bug，97×0.15）。
**注意**：①测试 Bug id=2566 标题含"【测试】…可删"，影响孙世超/魏冬霞 6 月该项得分，不要时直接删行即可；②150 单产品 165.5h 的分母较小，1 个普通 Bug 即破 5‰ 线——项目口径下该指标对小团队偏敏感，属口径本身特性；③8085 需重编译重启。
---
## CHG-051 引擎扣分统一为加权尺度（2026-07-31，用户拍板"10分满分 10-2"）
**背景**：用户质疑"缺 20 份为啥还是 6 分"——引擎原按 100 分制扣分再 ×权重（扣分量只有 xlsx 字面 1/10 效果），与 KFZ（CHG-036 起即加权尺度）两套尺度并存。
**改动**：AbstractPerfIndicatorCalculator 新增 scaleDeduct——配置权重注入 rule（`__w`），扣分按 1/权重 放大到 100 分制再扣（最终 ×权重=xlsx 字面加权扣分）；接入 applyLinear（全部 rate 类）、perBugScore（Bug 类）、OpsCount（运维周频次）、DocReady（文档齐备）四处扣分点；threshold 分档与 PerfScoreRules（KFZ/CS/UI）本就加权尺度不变。**结果对齐 xlsx**：10 分项缺 1 份=扣 2（10−2=8），缺 20 份=扣完=0。
**单测**：新增加权用例 3（docReady 缺 2→60、Bug 超线 2 普通→40、监控缺 2→60），全量 93 绿（旧用例配置无 weight 不走缩放，行为不变）。
**预期效果（孙世超 6 月，手算）**：文档齐备 6→**0**（20 份×2/0.1=400 扣完）；线上Bug 9.7→**7**（3/0.1=30→70×0.1）；团队完成率 26.7→**19.0**（11/0.3=36.7→63.3×0.3）；版本计划 9.4→**4**（6/0.1=60→40×0.1）；PRD 完成率 20（满分项不受影响）。
**实测状态**：8086 重启时 161 数据库 Too many connections（共享开发库连接耗尽，HikariCP checkFailFast；pymysql 同样 1040），待连接释放后补实测。**8085 需重编译重启**。
---
## CHG-053 绩效弹窗跟随月报选中产品集（2026-07-31，用户拍板"按照当前选择产品"）
**背景**：用户拍板公式"按理说都是根据某个产品来算的"——弹窗不再只按本人项目，而跟随月报下拉选中的产品集。
**链路**：monthReport.vue 把 `dataForm.project`（下拉选中的 program id）→ editDialog `:program` → performance.vue `program` prop → myWorkScore 请求加 `project` 参数；后端 IZtCountService.myWorkScore：`project` 非空时 pids=该 program 的产品集（替代本人授权产品），并在调度分支外裹 `AbstractPerfIndicatorCalculator.setCurrentProgram/clearCurrentProgram`（try/finally）；AbstractWorkloadRateCalculator 的 projectScopeStoryIds/projectProducerCount 优先走选中产品集（新增 currentProgramProductIds/execsOfProducts，选中时不再要求本人是该迭代成员），null 时回退 CHG-043 本人路径。影响范围：任务/需求取数（pids）+ 引擎全部项目口径指标（工作量/版本/Bug率/齐备）。
**验证**：单测 93 全绿无回归。**8086 API 实测**（孙世超 6 月）：program=139 → prd 20/team 30（556.83/525h=106.06%）、vp 4（92.35%）、bug 7（6.04‰）、doc 0；program=119 → prd/team 0（Σ0/630h）、vp 0（72 发布仅 33 权重按时 0）、bug 10 豁免、doc 10（无大型需求）——同一人两套分随切换。**8089 UI 实测**：下拉 139 弹窗含 556.83/525h/92.35%（截图 tmp/pw_chg053_139_jun.png）；119 无本项目数据。已同步 F:\zd。
**注意**：①快照月（zt_month_score 已存）仍返回旧存值；②8085 需重编译重启+前端发版；③附带修正 playwright 脚本月份控制（直填月份输入框替代「上月」按钮）。
**CHG-053 补充（同日）**：用户实测发现魏冬霞在 139 下团队完成率仍显 1365h——WorkloadRateTeamCalculator 的项目口径分支只开了项目经理 → 同步改 isProjectScopedRole 四角色（CHG-052 的正确归位，随"按当前选择产品"生效）。复测：魏冬霞 program=139 → 团队完成率 1365h/78.87%/0 → **525h/106.06%/满分 20**；program=119 → 0（Σ0/630h）。WorkloadRate 7/7 绿。
---
## CHG-054 CS 测试需求范围修正：assignedTo ∪ expand.test_person（2026-07-31，用户拍板"先修复"）
**背景**：孙颖缺陷检出率恒 0 排查——当前测试需求范围仅 zt_story.assignedTo（她 6 月 3 个），而 zt_story_expand.test_person 指定她测的 6 月有 24 个（其中 21 个 assignedTo 是开发）；全量 134 个指定需求中 assignedTo 是她的仅 12 个，assignedTo 口径严重漏算。
**改动**：IZtCountService 新增 testStoriesOf（注入 IZtStoryExpandService，test_person 中文姓名 like 匹配，assignedTo 池∪expand 指定，均按产品+releaseddate 当月过滤）；三处 buildCScore 调用点（newPerformanceCount/programCount/myWorkScore 的 CS 分支）统一替换原 assignedTo 二次过滤。
**8086 实测（孙颖）**：6 月 检出率 0.0%（24 个需求已纳入计算、devSlightBug=0，真无检出，此前是"取不到数不算"）；**5 月 检出率 48%（12 个普通 Bug）→ bugFindScore 满分 30**（修复前恒 0）。其余 CS 账号同享修正。8085 需重编译重启。
---
## CHG-055 检出率得分不为空（2026-07-31，用户拍板"得分不能为空 要么为0"）
getBugFindScore 三条空值路径统一显式赋 0：无测试需求、无开发工时、检出率 i≤0，均 set bugFindRate=0 + bugFindScore=0（原不赋值弹窗显示空）。8086 实测孙颖 6 月 bugFindScore=0（不再是 null）。
---
## CHG-057 需求详情页撤审查状态显示（2026-08-06，用户拍板"代码审查报告不需要通过或者不通过在需求详情页面"）
**改动**：storyinfo/components/product.vue——「代码审查报告」区块标题旁状态徽标（通过绿/未通过红/未审）移除；`codeReviewStatusText` computed 一并删除（全文件无其他引用）。**保留不动**：①提交测试报告卡点（`codeReviewStatus !== 'pass'` 时提示"代码审查未通过，不可提交"+隐藏上传按钮，FR-008 SOP 卡点）；②后端 `code_review_status` 字段与 uploadBind 解析写入（代码质量考核取数依赖）。
**验证**：vue-template-compiler 模板编译 errors=none；script 块 @babel/core 解析 ok。两副本已同步（codes/web_zentao + F:\zd\web_zentao）。**⚠️ 页面级验证待补**：8085/8086 后端当前未运行（8088/8089 dev server 在线，热更新已生效），8085 启动后刷新需求详情页确认。
**补记（留痕补齐，证据指引）**：
- CHG-056（08-04，Bug 分级 severity 1=重大、2/3/4=普通）：IZtCountService.java:1339 注释处 + AbstractWeightedBugCalculator/DefectFindRateCalculator 两处同步修改；decision_log 已录。
- CHG-058（08-05，AI 代码审查/工作日志/文档更新记录三区块前端上传入口移除，上传只走 AI 框架通道）：product.vue 三处 CHG-058 注释；同会话另完成 mermaid 流程图渲染（public/mermaid.min.js 静态引入 + MdPreview window.mermaid 渲染，8088 实测 9130 流程图通过）。
---
## CHG-059 aiBatchAdd 补历史留痕（2026-08-06，用户报"AI 拆的任务历史记录没有"）
**根因**：aiBatchAdd 只 insert zt_task，不写 zt_action——且全库从未有过 task 级 action（手工建任务也不写），需求详情的「历史记录」区块（actionList 按 objecttype+objectid 查）只见 story 级动态，故 AI 拆任务完全无痕迹。
**改动**：ZtTaskServiceImpl.aiBatchAdd 每个新建任务写一条需求级动态（与 uploadBind 上传留痕同模式：ActionType.XQ + ActionStatus.BJ，actor=ai，product=需求产品，extra=指派账号由前端映射昵称），comment="AI拆分任务：{名称}（开发/测试，工时Xh）"；skipped 防重项不写。actionService 为类内既有注入，无新依赖。
**单测**：AiBatchAddServiceTest +1（留痕用例：新建写动态/comment 含任务名与工时/extra=指派账号/skipped 不写），setUp 补 actionService mock。**Tests run: 5, Failures: 0, Errors: 0**。
**8086 实测**：临时 2 任务上传 → zt_action+zt_actionrecent 各写 2 条（comment/extra 正确）→ 临时任务与 action 行已清理；18563/18564（修复前创建）按原创建时间补录动态 2 条（comment 标注"补录"）。
**注意**：8085 为用户实例，跑的是修复前代码——**需 IDE 重编译重启**后 aiBatchAdd 才有留痕；历史里 18563/18564 的补录记录已可直接看到。
---
## CHG-060 aiBatchAdd 补任务级留痕（2026-08-06，用户指出"任务侧历史也要有，手工拆任务本来有"）
**更正 CHG-059 的误判**：此前"全库零 task 级 action"系 2026 库复制时 zt_action 按计划清空所致——手工建任务本就写 RW+XJ（ZtTaskServiceImpl:681，actor=登录人）。
**改动**：aiBatchAdd 在 CHG-059 需求级动态之外，每个新建任务再写一条任务级动态（ActionType.RW + ActionStatus.XJ，objectId=taskId，actor=ai，comment 空，与手工建任务同一形状），任务详情页历史可见。
**单测**：留痕用例补 RW+XJ 断言（mock insert 不回填 id，objectId 为 null 校验形状），**5/5 全绿**。
**8086 实测**：临时任务 18567 → story 级（edited+comment）与 task 级（opened，product=150）双写成功，actionrecent 同步；临时数据已清理。18563/18564 按原创建时间补录 task 级动态 2 条。
**注意**：8085 需 IDE 重编译重启后生效（含 CHG-059/060 两批）。
---
## CHG-061 AI 通道接口鉴权 + ai 永久 token（2026-08-06，用户拍板"创建人都要 token 的"）
**背景**：AI 上传三接口（saveOrUpdate/aiBatchAdd/uploadBind）此前无鉴权直连（R-003/DT4 二期必决项）。JwtUtil.sign 本无过期设计，token 天然永久。
**改动**：
1. 鉴权门禁——saveOrUpdateExpand、aiBatchAdd：限 ai 账户 token（非 ai 登录用户也拒）；uploadBind：需任意有效登录态（前端上传组件在用，不能限 ai）。
2. 创建人改取 token 身份——aiBatchAdd 的 openedby 与两级 zt_action actor、refreshOwnerUrl 的上传动态 actor（无登录态兜底 ai 兼容直调）、zt_file.addedby 沿用既有 token 取值。
3. ai 永久 token 已生成：HMAC256（account=ai），存 `.claude/ai_token.txt`（已用 8085 验证：真 token 放行 / 伪造 token"请登录"）。
4. 框架脚本：`submit_assessment.py`、`upload_md.py` 自动带 Authorization（读 ZENTAO_AI_TOKEN → .claude/ai_token.txt）；**两脚本默认地址改正线→本地 8085**（用户拍板"别用正线的 url"），打正线需显式设 ZENTAO_BASE_URL。
**单测**：AiBatchAdd +1（非ai整批拒绝且零写入）、ZtStoryExpand +2（非ai/无token拒绝、ai放行）、UploadBind 测试补 actionService mock（修复 08-05 留痕上线时未补 mock 的既有断点）。**三类 6+5+13=24 全绿**。
**8086 实测 3×3 矩阵**：无 token 三接口全拒；admin token 仅 uploadBind 放行（zt_file.addedby=admin）；ai token 全通（任务 openedby=ai、action actor=ai/admin 各归各）。测试数据已清理（zt_file 8815/8816 软删、任务 18569 软删、action 行删除、9130 test_other_url 恢复 08-05 值；上传目录留 2 个探针 MD 孤儿文件，低危）。
**注意**：①8085 需 IDE 重编译重启后门禁生效（重启前旧代码照旧放行，脚本带 token 向下兼容）；②生产 itsm 仍为无鉴权旧代码，发版前该口子都在；③ai 账户密码仍是默认 MD5（123456），建议改密——改密不影响已签 token（checkToken 只验签不查库）。
---
## 9130 任务换新流程重建（2026-08-06，用户指出原任务建于修改前）
18563/18564（无 token 时代创建+手工补录留痕）软删、补录行清除 → 8085 新代码下以 ai token 重传 aiBatchAdd：**18570（devel/6h/罗勇）+ 18571（test/3h/未指派）**，openedby=ai，需求级+任务级动态由系统自动双写（119044-119047），9130 链路数据全部为真实流程产出，无手工补录。
---
## CHG-062 批拆留痕合并为一条（2026-08-06，用户拍板"一次上传多个任务应该就一条记录"）
**改动**：aiBatchAdd 需求级留痕由"每任务一条"改为"每批次一条"——循环内只写任务级（RW+opened）并收集文案，循环结束写一条需求级动态：`AI拆分任务 N 个：①名称（开发，工时6.0h，指派：罗勇）；②名称（测试，工时3.0h，未指派）`；有重复跳过项追加"；重复跳过 M 个"；指派经 userService.getByAccount 转中文名（查不到兜底账号）；extra 不再携带指派（文案内嵌）。
**单测**：留痕用例改写为聚合断言（个数/序号/指派/跳过数），AiBatchAdd 6/6 绿。
**8086 实测**：2 任务批拆 → 需求级 1 条+任务级 2 条；未指派文案"未指派"（无冗余前缀）。9130 既有 2 条单任务记录已合并重写成一条（原创建时间保留）。截图 tmp/pw_9130_history.png。
**注意**：8085 需 IDE 重编译重启生效。
---
## CHG-063 文档区块归集「需求文档」tab（2026-08-06，用户拍板"放在需求的一生后面加一个 tab 需求文档"）
**改动**：storyinfo/components/product.vue——测试用例/测试报告模版、提交测试报告、其他测试文档、代码审查报告、工作日志、AI项目文档更新记录 共 6 个文档区块由左栏（span16）整体迁移至右栏 el-tabs 新增第三个 pane「需求文档」（位于 需求的一生 之后）；左栏保留 需求描述/验收标准/附件/AI指标/交付物/历史记录。数据与方法零改动（fetchBlockFile/uploadForm/卡点逻辑原样）。
**验证**：vue-template-compiler errors=none（移动时丢失 需求的一生 pane 闭合标签一处，已修）；六区块 tab 内齐全、左栏无残留（程序化断言）；8088+8085 实测 9130 页面：tabs=[基本信息/需求的一生/需求文档]，六区块渲染正常、上传按钮/卡点状态正确。截图 tmp/pw_9130_doctab.png。已同步 F:\zd。
**已知**：tab 头在 span8 窄栏下标签偏挤（el-tabs 默认样式，功能性影响无）；提交测试报告上传按钮因 9130 code_review_status=pass 正常可用。
---
## CHG-064 产品助理弹窗前后端对齐（2026-08-06，用户报"产品助理的前端页面显示有问题"）
**根因**：08-05 用户拍板"绩效的除了产品和项目经理其他撤回到 git 提交版本"，08-05 会话完成了后端 IZtCountService 还原（buildXMZLScore 等回老版），但**前端 performance.vue 的 XMZL 区块未同步还原**——新版区块绑定的 workloadPrdScore/productBugRate/productProblemResponse/productResponsibilityScore 老后端不产出 → 弹窗得分全空。全角色对齐核查：CS/UI=老+老✓；CPJL/XMGLY/KFZ/YW=新+新✓（按拍板保留）；**XMZL 是唯一前后端错配**。
**改动**：performance.vue 的 case 'XMZL' 块还原为 git HEAD 版（及时验收20/项目文档50/会议管理30，绑定 releaseCount/releaseOnTimeCount/releaseOnTimeRate/documentQualityProblem/projectDocumentScore/meetWeek/meetStory/meetScore 老字段）。已同步 F:\zd。
**验证**：编译 errors=none；字段交叉核对（HEAD 绑定 10 字段 ↔ 老后端 getReleaseScore/getMeetScore 全部有产出，documentQualityProblem DTO 默认 0）；8088+8085 实测李语嫣（145 道路救援 2026-06）弹窗：及时验收 0/项目文档 50/会议管理 30/总计 80 渲染正常。截图 tmp/pw_xmzl_liyuyan.png。纯前端改动，8085 无需重启（dev server 热更新）。
---
## CHG-065 产品助理+UI 弹窗改新 Excel 口径（2026-08-06，用户拍板"不对 按照新的excel来"、"还有ui人员的也更新掉"）
**背景**：撤销 CHG-064/08-05 对 XMZL 的老版还原，产品助理与 UI 均按新 Excel（SRC-002）执行。
**改动**：
1. `buildXMZLScore` 重建为新口径：scope=perfReportService.report(month, "productAssistant", account) + fillRawDetail；workloadPrdScore=perfItemScore(workloadRatePrd,50)、releaseScore=20（人工默认满分）、productBugRate=perfItemScore(productDefectRate,15)、productProblemResponse=10、productResponsibilityScore=5（后两项人工满分默认）；移除老版 getReleaseScore/getMeetScore/documentQualityScore=50/projectDocumentScore=50 与 0.75 达标工时。
2. `buildUiScore` 及时率得分：老内联公式（90 边界漏判：90%→0）改走 `PerfScoreRules.uiPunctualityScore`（=100%→50/≥90%→40/<90%→0，CHG-037 规则类幸存）；designScore=40/workAttitude=10 本已符合新 Excel 不动。
3. 前端 performance.vue：XMZL 区块恢复新 Excel 版（撤销 CHG-064 老版还原）；UI 区块无需改（git 版行/权重/字段本就与新 Excel 一致）。已同步 F:\zd。
**验证**：前端编译 errors=none；后端 PerfScoreRulesTest 6/6 绿。**8086 API 实测（2026-06）**：李语嫣 workloadPrdScore=0（真0，145 无指数记录）/releaseScore=20/productBugRate=15/productProblemResponse=10/productResponsibilityScore=5，perfRawDetail 两键齐——与 CHG-037 时期实测值一致；刘圣清 punctualityScore=0（真0，无任务）/designScore=40/workAttitude=10。8088 弹窗结构核验：两角色新行齐全、无旧版残留（截图 tmp/pw_chg065_xmzl.png、pw_chg065_ui.png）。
**注意**：8085 当前跑的是老后端，弹窗数值要 **IDE 重编译重启**后才按新口径显示（现在页面显示的是老后端值：PRD完成率空/及时验收0/问题响应15 等 DTO 默认值）。
---
## CHG-066 XMZL 弹窗列错位修复（2026-08-06，用户报"分项跑到绩效数据那一列"）
**根因**：performance.vue 模板 `<td v-if="item.category">` 仅在行配置含 category 时渲染类目格——XMZL 区块「项目绩效」rowspan=2 只覆盖前两行，产品缺陷率/问题响应和解决两行无类目格 → 单元格少一个整行左移，得分值落进「绩效数据」列。全角色扫描：仅 XMZL 有此配置缺陷（KFZ/CS/UI/YW/XMGLY/CPJL 覆盖均正常）。
**改动**：XMZL 区块首行 rowspan 2→4（项目绩效覆盖 完成率/验收/缺陷率/响应 四行，与新 Excel 结构一致）。已同步 F:\zd。
**验证**：编译 errors=none；8088 实拍李语嫣弹窗：项目绩效跨四行分组正确、各列对齐、得分 0/20/15/10/5 落「得分」列、总计 50、首行明细"Σ指数 0 / 达标 630h = 0%"正常（截图 tmp/pw_chg065_xmzl.png）。同期 8085 已带 CHG-065 新后端（弹窗数值与 8086 API 实测一致）。
---
## CHG-067 Bug 需求关联字段 story→toStory（2026-08-06，用户拍板"story 字段应该没用 启用的是toStory"）
**数据证据**：全库 prod Bug 76 个 story>0 的 **0 个**、toStory>0 的 23 个；dev Bug 2433 个 story>0 的 **0 个**、toStory>0 的 2251 个——story 列全库未用，需求关联实际全走 toStory。
**改动（4 处死字段修复）**：
1. `AbstractWeightedBugCalculator.computeWithExempt`：5‰豁免分子取数 `.in(getStory)` → `.in(getTostory)`（线上Bug率/产品缺陷率核心修复，此前结构性漏算恒满分）；
2. `IZtCountService:1350`（buildCPJLScore 展示严重/普通 Bug 数）同改；
3. `ZtBugServiceImpl:527`：入参本就是 toStory 的 ID，查询列同步改（按需求查 Bug 列表此前恒空）；
4. `ZtStoryServiceImpl:1982`：关闭需求联动关闭未关闭 Bug（此前永远找不到 Bug）。
已用 toStory 的（检出率 getBugFindScore/DefectFindRateCalculator/ZtStoryServiceImpl:2363）不动。
**验证**：perf 计算器套件 13+7+10 全绿。**8086 新代码实测**：王宇航 2026-02 onlineBugRate 100→**40**（2 普通 Bug/336.2h=5.95‰ 超豁免线，扣 6→加权尺度 40，与手算一致）；无回归——李语嫣 6月=15（真0）、孙世超 6月=7（同 CHG-051）。排障：首轮实测误打 CHG-065 残留 8086 实例（占端口新实例未起），杀旧重启后复测通过。王宇航 2 月快照已恢复原值（备份 tmp/wyh_202602_snapshot_backup.json），历史月份是否统一重算待用户拍板。
**注意**：8085 需 IDE 重编译重启生效； prod Bug story=0 的录入习惯意味着**仍有 17 个历史 prod Bug 两字段都空**（任何口径都够不着，含 6 月的 2411）——要么补关联，要么接受豁免。
---
## CHG-068 需求文档 tab 视觉重设计 + tab 头间距（2026-08-06，用户拍板"tab 靠太近"、"需求文档页面太丑你优化他"）
**tab 头间距根因**：App.vue 全局 `.el-tabs__item{width:4rem!important}` 定宽，5 字标题（需求的一生）溢出 63px 盒子与下一个 tab 粘连；另有来历不明的 rem padding 覆盖。修复：`.filterInfo` 作用域 `width:auto!important` 解除定宽 + 兄弟选择器 `margin-left:16px`（绕开 padding 覆盖链）。
**需求文档 tab 重设计**（数据绑定零改动，测试断言全部保留）：六类文档由"白卡片堆叠+hr"改为**分节卡片**——节标题（蓝色竖条+16px 标题+份数徽章）、文件行（文档图标+文件名悬停变色+灰色小字 操作人·时间+查看/下载）、子分组（测试用例/模版）、卡点提示改 el-alert 风格黄条、审查轮次改蓝色徽章、空态文案统一"暂无附件（由 AI 框架上传）"。
**验证**：编译 errors=none（生成器脚本四重大括号事故 14 处已修）；13 项关键绑定程序化断言无缺；8088 实拍：tab 头间距正常、六分节渲染正确、计数徽章正确（2/1/2/1/2/2 份）。截图 tmp/pw_9130_doctab.png。已同步 F:\zd。
### CHG-068 补充（同日）：
- **meta 行字段大小写修复**：fileList 接口返回 addedby/addeddate（全小写），新旧模板都绑的 item.addedBy/addedDate（驼峰）恒空——老设计空 span 不可见，新设计 meta 行暴露为吊着的孤「·」。改绑正确字段名 + 空值整行不渲染（7 处）。实拍：文件名+「ai · 2026-08-05 17:14」完整对齐。
- **tab 间距收敛**：margin-left 16px→6px（用户反馈"间隔又太远"），文本对文本约 31px。
---
## CHG-069 saveScopeJson 登录态 NPE 修复 + 打包（2026-08-06）
**根因**：`ZtPerfReportServiceImpl.saveScopeJson:356` 无防御读 `RiskUserThreadLocal.get().getName()`——该写法一直靠 ThreadLocal 静态初始化块预置 admin 的隐性 quirk 撑着；CHG-061 给 AiBatchAddServiceTest 加的 tearDown clean() 把这个默认值清掉，同线程后续跑的 ZtPerfReportServiceTest 即 NPE（测试顺序依赖暴露）。
**修复**：①saveScopeJson 空值兜底 "system"（生产侧同样防未来调度线程无登录态 NPE）；②ZtPerfReportServiceTest 补 BeforeEach 登录态/AfterEach 清理（测试自给自足）。
**验证**：ZtPerfReportServiceTest 3/3、AiBatchAddServiceTest 6/6、ZtStoryExpandServiceTest 5/5 全绿。
**打包**：`mvn package -DskipTests` → `codes/zentao/target/zentao.jar`（154MB，2026-08-06 15:54，含 CHG-039~069 全部改动）。
---
## mermaid 发布包缺失修复（2026-08-06，用户报"打包发布到测试环境流程图没有正常显示"）
**根因**：mermaid 三件套（public/mermaid.min.js、index.html `<%= BASE_URL %>mermaid.min.js` 引用、MdPreview mermaid 渲染逻辑）08-05 会话只加在 codes 副本，F:\zd 副本一直没有——用户从 zd 打发布包，包里无 mermaid。
**处理**：三件套同步 zd；清 webpack 缓存重打 `F:\zd\web_zentao\dist`（mermaid.min.js ✓ / index.html head 引用（先于 app bundle，window.mermaid 可用）✓ / MdPreview 代码入 chunk-37091a66、chunk-56c8e14c ✓ 全量搜索证实）。注意点：publicPath='/'，mermaid 以 /mermaid.min.js 绝对路径引用，前端须部署在域名根路径。
---
## CHG-070 productPageList 性能修复（2026-08-06，用户报"接口要5秒"）
**定位（161 实测）**：产品列表页统计拉的 3 张全量表——zt_story(*) 3447行/923ms、**zt_bug(*) 未关闭 954行/7340ms（steps MEDIUMTEXT 共 44MB，均值 46KB/行）**、zt_story_user(*) 2273行/498ms。zt_bug 全字段拉取是唯一主因。
**改动**：ZtProductServiceImpl.productPageList 三处查询修剪 select 列（story: id/product/status/stage；bug: id/product/status；story_user: id/product/status），统计逻辑零改动。
**验证**：修剪后 SQL 预演 50/27/93ms；8086 端到端实测 **0.49/0.19/0.23s（原约 5s，~20 倍提升）**，结果集正确（total=10）。已重打 target/zentao.jar（17:02），发布 8015 即可生效。
---
## CHG-071 exportScope 快照三格式兼容（2026-08-06，用户问"exportScope 要按新修改调整吗"+NPE 报错）
**根因**：zt_month_score.scope_json 三种格式并存——①老 DTO 平铺（弹窗提交时代）②引擎 PerfMonthScope（generateMonthScore）③docCheck 专项（FR-014 扣分合并）；exportScope 一律按老 DTO 解析 → 后两种全 null → generatorDevlopExcel 取 delayTask.toString() NPE（luoyong 2026-06=docCheck 格式实锤）。
**改动**：exportScope 解析改走新助手 resolveScoreDto——引擎格式=新算 DTO 为底+人工项（source=manual）按 score×weight 覆盖；老 DTO 格式=直接反序列化+统计字段缺失从新算回填（backfillStats 13 字段）；其他格式=新算 DTO。
**验证**：8086 导出 2026-06（原 NPE 场景）HTTP 200/13.6s/有效 xlsx——罗勇开发考核表完整渲染（任务 9/超期 2/及时率 88%→8 分、Bug 密度 0→30 分），统计字段齐。已重打 target/zentao.jar（17:28）。
**同族遗留**：myWorkScore 弹窗对引擎/docCheck 格式快照同样按老 DTO 解析会空值——弹窗出现历史月份空分时同一招修（resolveScoreDto 可直接复用），待用户指示。
---
## CHG-072 myWorkScore 快照分流 + CHG-073 userList 脱敏（2026-08-06，用户拍板"1 2 都做"）
**CHG-072**（exportScope 同族）：myWorkScore 拆为薄壳+myWorkScoreCompute——老 DTO 平铺快照维持快路径；引擎/docCheck 格式快照不再按老格式解析（全空），改走新算+人工项以快照覆盖（overlayManualScores 复用）。实测：luoyong 6月（docCheck 快照）修复前全空→修复后 punctualityScore=8/delayTask=2/totalTask=9 等新算值；sunying 5月（老快照）快路径快照值原样。
**CHG-073**：userList 响应剔除 password 列（MD5 哈希不下发），其余 51 字段全保留兼容。排障：实体 `@TableField("\`password\`")` 列名带反引号，首版按 getColumn() 匹配失效，改按 getProperty() 匹配后实测 password 不再泄露。
**打包**：target/zentao.jar（2026-08-06 17:54，含 CHG-070~073）。
---
## CHG-074 月报列表达标工时与弹窗对齐（2026-08-07，用户指出"月度达标应该跟详情的一致"）
**根因**：08-05 还原波及 pageMonthReport——月度达标工时退回老个人口径（(21×8)×0.75=126），且饱和度分子用 storyTotalTime(estimate)；而弹窗 myWorkScore 走团队口径（21×5=105）+实绩 consumed。两处不一致。
**改动**：pageMonthReport 的 haveTime 改 `teamExamineTime(accountIds,...)`（在窗 KFZ 人均，无 KFZ 退回个人口径兜底）；饱和度分子 storyTotalTime→workTime（实绩）。
**验证**：8086 实测月报 139/2026-06——全员达标=105.0（与弹窗一致）；陈浩 126/105=120%、罗勇 25/105=24%、孙颖 84/105=80%。jar 已重打（17:5x 见时间戳）。
---
## CHG-075 exportScope 静默空响应修复（2026-08-07，用户报"没有文件导出"）
**根因（双重）**：①方法尾部 `catch(Exception){log.error}` 静默吞异常——"未查询到数据"（当月无在窗执行/任务）等异常被吞成**空 200**，前端拿到 0B 响应即无文件也无提示；②无快照人员 `continue` 跳过——当月（如 8 月）没人有快照时一个文件都不产。
**改动**：①BusinessException 重新抛出交全局异常处理器回 JSON（前端弹"未查询到数据"等真实原因），其他异常包装"导出失败"；②无快照人员用新算 DTO 导出（自动分+人工满分默认），有快照走 CHG-071 三格式解析。
**验证**：8086 实测——2026-08+139 返回 JSON 错误（前端可提示）0.4s；2026-06+139 文件 23.5KB→44.4KB（无快照人员补齐，含陈浩表）。jar 已重打。
---
## CHG-076 aiBatchAdd 中文姓名指派映射（2026-08-07，用户拍板"指派中文要查数据库"）
**改动**：aiBatchAdd 建任务前解析 assignedTo——非既有账号时按 `zt_user.nickname` 查库映射为账号（AI 框架传中文名场景）；账号原样、查不到原样保留。需求级留痕文案的指派展示用映射后账号取昵称。
**验证**：单测+1（中文名映射用例，7/7 绿）；8086 实测 assignedTo="罗勇" → 落库 assignedto=luoyong（验证数据已清理）。jar 已重打。
---
## CHG-056 绩效导出换新版式 + 并行改动合并修复（2026-08-10，用户拍板"改"）
**导出换新版式**：9 份新模版（9 岗位 sheet 全量，含王宇航变体/前后端分离/新增运维）由 `tmp/make_perf_templates.py` 从 SRC-002 xlsx 生成（占位符 {name}/{date}/{得分键}/{total}/detail_*）；IZtCountService 7 个 generator 重写（新键名+devDirection 分流前后端模版+perfRawDetail 明细入「绩效数据」列）、新增 generatorYwExcel + exportScope YW 分支、helper（scoreStr/scoreTotal/perfDetail 等）。
**排障两个坑**：①openpyxl 生成的 xlsx 是 **inlineStr 单元格**，POI setCellValue 会残留旧 `<is>` 内联串导致读回旧值（占位符零替换）→ writeXlsx 先 setCellType(BLANK) 再写值修复；②**并行改动撞车**：另一会话在 IZtCountService 上做了"选中产品集 KFZ 成员"口径（buildKFZScore 加 accountIds 参数+fillTeamExamine(accountIds)），但底版偏旧，把 CHG-036/038（PerfScoreRules 算分、前后端分流）与 CHG-054/055（testStoriesOf/检出率赋 0）覆盖丢失 → 已全部合并还原（保留 accountIds 团队口径新逻辑，恢复 PerfScoreRules 算分+devDirection+testStoriesOf+显式 0 分），补回 PerfScoreRules import；pom.xml 的 surefire skipTests 硬编码块（为绕 AOT 报错加的）已移除（lombok 1.18.34 已治本）。
**验证**：单测 92 全绿（surefire 恢复可跑）；8086 实测——郭尚雨 devDir=backend/docQ=10/饱和 20、孟冉 devDir=frontend/无文档质量项、孙颖检出率显式 0；导出全量 28 sheet 无残留占位符，孙世超 sheet 得分+明细全对（20/30/4/10/0/5/10/5，总 84），孟冉前端模版无文档质量行，郭尚雨后端 sheet 总分 100。
**注意**：①王宇航 sheet 走变体模版（无 PRD 行）；②岑海峰 6 月不在窗口执行内不出 sheet（7 月起正常）；③导出列路径（exportScope）不读 zt_month_score 快照、实时算；④8085 需重编译重启+前端发版。
---
## CHG-057 CS 测试文档齐备改实时字段判定（2026-08-10，用户拍板口径）
**口径（用户定）**：范围=zt_story_expand.test_person 指定 ∪ assignedTo 且本月发布的需求（复用 CHG-054 testStoriesOf）；判定=test_case_url（用例）+ test_report_submit_url（**提交件**，AI 模版 testReportDownload 不计）非空；每缺一份扣 3 分（25 分项直接扣完截止）；本月无需求→满分 25。
**改动**：buildCScore 弃写死 25，实时遍历 testedStory 两个 url 字段计数，documentQualityProblem=缺失数透出展示。
**8086 实测**：孙颖 6 月 缺失 46（23 需求×2）→ 0；孙庆方 缺失 34 → 0（2026 库这些需求确实没人传测试文档，非误判）；孙颖 2025-12（无测试需求月）→ 满分 25 ✓。8085 需重编译重启。
**注**：引擎的 TestDocReadyCalculator（快照版，归属按 account 匹配中文名列本就失效）自此彻底废弃，仅 CS 弹窗路径生效；原 CS 弹窗「测试文档」行 data 绑定 documentQualityProblem（问题个数）直接显示缺失份数。
---
## CHG-058 需求文档拆独立区块 + 前端改动恢复（2026-08-11，用户拍板"可以加类型/入口处改/顺带前端"）
**改动**：FileTypes 增 `storyPrd("storyPrd","需求文档")`；uploadBind 刷新 prd_url（storyPrd 与 story 同字段）；upload_md.py VALID_TYPES+用法注释（需求文档一律 storyPrd，story 保留给手动附件，互不影响他人接入）；storyinfo/product.vue「需求文档」归位到右侧「需求文档」tab 顶部 section（复用 dc0b5a5 doc-sec 版式），无上传按钮、纯 AI 框架上传，空态文案"暂无附件（由 AI 框架上传）"。6566 实测：上传→prd_url 刷新→fileList 返回→tab 渲染；9130 需求文档已传（zt_file 8824，内容由 zt_storyspec 真实 spec 生成，curl GBK 乱码 title 已 SQL 修正），截图 tmp/pw_9130_prd_tab。已同步 F:\zd\web_zentao。
**并行会话撞车处置**：郭其兵 08-11 13:10 提交 dc0b5a5「新版绩效」（main_2026 分支），收编了我 13:10 前的前端工作（CHG-036~053/046/会议等）+他自己的三期绩效页面（views/perf/*）；工作区被切到该提交后，我 14 点的 CHG-058 前端编辑（未提交）丢失 → 从 F:\zd\web_zentao（14:16 同步版）拷回 product.vue，diff 验证恰好是 CHG-058 那 49 行、无其他损失。codes/web_zentao 当前状态=dc0b5a5 + product.vue(M, CHG-058)，建议尽快提交避免再次被冲。
**环境备忘**：用户的 8085 IDE 后端与我的 8086 当前都连 zentao_dev_2026（IDE run config 带 2026 覆盖）；8088 前端由用户在 codes/web_zentao 启动。生产 itsm 未动。
---
## CHG-077 uploadBind 入口 story→storyPrd 归一化 + 8 需求错传数据修复（2026-08-17，用户拍板"改"+"一起"）
**起因**：200 库 9209 用户报"上传的 md 落到了附件"。排查实证：AI 通道把 PRD/验收标准用 objectType=story 调 uploadBind（zt_action 留痕"上传需求"），而「需求文档」区块只认 storyPrd（product.vue fileFieldMap）；且 refreshOwnerUrl 中 story 与 storyPrd 同写 prd_url，last-write-wins 致 prd_url 被后传的验收标准覆盖。误用源头：对外接口文档 §5.2 只列 story 未列 storyPrd（CHG-058 只改了 upload_md.py 客户端，管不住外部调用方）。
**改动**：UploadDTO 增 normalizeObjectTypeForBind()（story 归一 storyPrd）；CommonsController.uploadBind 校验后调用，一处生效（refreshOwnerUrl 与 zt_file 落库同读 DTO）。原生两段式上传不受影响（UI 手动附件不走 uploadBind，前端全项目无 story 传参）。
**单测**：新增 UploadBindNormalizeTest 4 条（story→storyPrd / storyPrd 不变 / 其他类型不变 / null 安全）；回归 UploadBindRefreshOwnerUrlTest 13 条。**17/17 绿**。
**200 库数据修复（已提交回读验证）**：18 条 ai 误传 story 文件改 storyPrd（9143×4/9179×3/9180×1/9208×2/9209×2/9213×2/9226×2/9238×2）；8 需求 prd_url 从"验收标准"校正回 PRD/需求说明/需求文档（9143→9395、9179→9343、9180→9335、9208→9435、9209→9428、9213→9416、9226→9404、9238→9397 的 url）。
**待办**：代码改动在本地 codes/zentao，需郭其兵提交+部署后归一化才在线生效；对外接口文档 §5.2 仍只列 story——归一化上线后文档与行为一致，可不急改。
---
## CHG-078 用户需求导出/分页加「迭代版本」列（2026-08-17，用户拍板）
**需求**：/zt-story-user/export 与 pageList 加迭代版本列，参照分页列表 execList 字段，只要迭代名称、多迭代拼接。
**现状**：列表页已有该列（userstory/product.vue 用 execList 渲染）；缺口在导出（execList 标 @ExcelIgnore）。
**改动**：ZtStoryUserDTO 增 execNames（@ExcelProperty "迭代版本" index=5，后续列 index 顺移+1）；ZtStoryUserServiceImpl 增静态 buildExecNames（名称去重排序逗号拼接，空→null），pageList 与 storyListByProductId 两处填充点接入。前端零改动。
**单测**：BuildExecNamesTest 4/4 绿（多迭代拼接/单迭代/空/空白名过滤）。
**待办**：代码在本地 codes/zentao，需郭其兵提交+部署生效。
---
## CHG-079 modifyTask 后端权限校验：创建人/项目管理员/admin（2026-08-28，**已撤销——用户拍板"后端不用改"**）
**背景**：代码勘察发现 /zt-task/modifyTask 后端无任何归属/角色校验（前端仅按钮显隐控制：openedby 本人 或 XMGLY/GSGC），任何登录用户可直调接口改任意任务——而 estimate/left/consumed 是绩效算分输入，存在越权篡改风险。
**改动**：`ZtTaskServiceImpl.modifyTask`（selectById 判空后）加门禁：当前用户为 `admin`、任务 `openedby` 本人、或 `userType==XMGLY`（项目管理员）三者其一放行，否则抛"仅任务创建人或项目管理员可修改任务"。原有的状态卡点（cancel/closed/done 拒改）与 KFZ 评审流转不受影响。
**口径说明**：①GSGC（公司高层）未纳入后端白名单——用户本次只点名项目管理员，前端 GSGC 按钮（doing/wait 可编辑）与后端将不一致，如需放开再说；②ai 创建的任务 openedby=ai，此后仅项目管理员/admin 可改；③startTask 原有的指派人校验、aiBatchAdd/saveOrUpdate 的 ai 门禁均不受影响。
**验证**：JDK17 mvn compile BUILD SUCCESS。未写单测（modifyTask 为重 DB 依赖方法，现测试体系无对应基建）。
**待办**：8085 需重编译重启生效；代码需郭其兵提交部署（同 CHG-077/078 一并）。
**撤销记录（同日）**：用户确认后端不用改（modifyTask 加门禁会挡住前端已放开的 GSGC 编辑 doing/wait 等既有路径，回归风险>收益），代码已还原，编译状态回到改动前。
---
## CHG-080 任务编辑放开 XMJL 项目经理（前端，2026-08-28，用户拍板"项目经理也可以修改、只用改前端"）
**背景**：任务编辑按钮的角色白名单此前只有 XMGLY（项目管理员）/GSGC（公司高层），XMJL（项目经理，如孙世超）在全前端都改不了别人创建的任务。用户确认后端不动（CHG-079 已撤销），仅放前端。
**改动**（三处，编辑按钮 userType 白名单加 `XMJL`）：
1. `implement/task/components/product.vue:312`（研发任务列表）
2. `territory/task/components/product.vue:321`（地盘任务列表）
3. `implement/taskinfo/components/product.vue:608`（任务详情页）——顺带修笔误：`waiting`（不存在的状态）→ `wait`，否则详情页 XMJL/XMGLY 对 wait 状态任务仍无编辑入口（与列表页口径不一致）
**未动**：`implement/look/tab/content.vue` 编辑菜单项本就无角色门槛（仅 task-edit 权限键）；testtask 页无角色限制。前提：XMJL 角色的菜单权限需含 `task-edit` 键（BaseRoleAuthority 数据配置），无键则按钮仍不显示。
**同步**：三文件已同步 F:\zd\web_zentao（diff 核对仅本次改动）。
**待办**：8088 前端热更新/重启生效；代码需随 CHG-077/078 一并提交。
---
## CHG-082 aiBatchAdd 放行 affair 事务任务（后端，2026-09-16，用户拍板"就事务 开始开发"）
**背景**：AI 拆批接口 `/zt-task/aiBatchAdd` 的类型白名单原为 devel/test（后 CHG-081 放行 design，未入本档）。事务型任务（affair）此前传参会整批拒绝 `任务类型仅支持devel/test/design:affair`。
**改动**（两处 + 测试）：
1. `ZtTaskServiceImpl.java:1382-1390`：白名单加 `TaskType.affair`，报错文案同步为 `devel/test/design/affair`
2. `ZtTaskAiBatchDTO.java:26`：type 注释补 affair
3. `AiBatchAddServiceTest`：新增 `aiBatchAdd_affair_createsTask`（仿 design 用例，断言留痕显示「事务」）；`aiBatchAdd_illegalType_rejectsAll` DisplayName 同步
**已核对不受影响**（affair 与 design 同路径，天然隔离）：
- 需求计划时间回写：`batchAddTask:1314-1324` 只对 devel/test 回写，affair 跳过
- 绩效专项公式：取数按类型显式过滤（如 `IZtCountService.java:1256` 只查 `type="devel"`），affair 不进
- 需求级留痕：`ZtTaskServiceImpl.java:1471` 按 TaskType 枚举动态取中文名，affair 自动显示「事务」
- 看板挂载：`ZtKanbanlaneServiceImpl.addTask` 按任务状态分列，与类型无关
**已知行为（与 design 一致，用户已知情）**：
- 需求状态联动 `taskFinishChangeStatus` else 分支（`ZtStoryServiceImpl.java:1623-1645`）：需求下无活跃 devel/test 任务时，affair 任务会把需求看板列置 backlog/ready
- 指派 affair 任务会触发微信指派通知（`taskSendZpMessage`，与类型无关）
**验证**：`mvn test -Dtest=AiBatchAddServiceTest` → 10/10 通过（JDK 17）。
---
## CHG-083 三个统计接口性能优化（后端，2026-09-16，用户要求"不要影响老的代码/其他业务，先留存正线数据再比对"）
**背景**：`/zt-project/projectTeamTimeWork`、`/count/storyBarChart`、`/count/bugBarChart` 正线耗时 7~19s。
**根因**：
1. 两个柱状图在 6 个月循环内每月调用全量绩效 `newPerformanceCount`（全岗位算分、逐人 bug/审批/文档查询），而图表只用 KFZ 成员的 allocationTime/examineTime 两个字段；
2. `storyBarChart` 逐月 `userMapByIds(null)` 全用户表扫描 ×6、`allProductList()` ×6、逐用户 filter 任务全表；
3. `projectTeamTimeWork` 任务查询无日期条件捞全量历史、全用户表扫描、天数×人数×任务数三层 O(n³) 扫描。
**改动**（老共享方法 `newPerformanceCount`/`fillTeamExamine`/`getApprovalTime` 等一行未动，其他业务路径不受影响）：
1. `IZtCountService` 新增私有 `kfzMonthTimesLite()`：复刻图表实际消费口径（成员集合同 newPerformanceCount 798-840 行；allocationTime 同 buildKFZScore 的 Σestimate 剔除 closed/cancel；examineTime 团队人均口径公式同 fillTeamExamine），跳过无关算分；任务按指派人预分组
2. 新增批量请假查询 `ZtTaskMapper.itApprovalsByNames`（XML 条件与 itApprovalByUserName 完全一致，name 改 IN；老 SQL 未动）+ `IZtTaskService/ZtTaskServiceImpl` 透传——原逐人逐月跨库查 os_system.it_approval（date() 函数不走索引，约 人数×6 次），现每月 1 次
3. `storyBarChart`：`allProductList` 提出循环按需取一次；多部门成员实绩工时按指派人预分组（floatBatchAdd 两位精度口径保持一致）
4. `bugBarChart`：仅需 allocationTime，needExamine=false 跳过达标工时/请假计算
5. `ZtProjectServiceImpl.projectTeamTimeWork`：任务 SQL 加 estStarted 当月范围（按天循环本就只匹配当月任务，口径不变）；用户表只查团队成员∪任务相关人（原全表）；任务按 `yyyy-MM-dd#账号` 预分组替代三层扫描
**验证**（证据：F:\zentao\1\PM\perf-snapshots\20260916\）：
- 留存正线基线（8013，老代码）→ 本地起新代码直连正线库（application-local.yml 用户已指向 192.168.3.200/zentao_dev）→ 同一时刻背靠背比对：
- storyBarChart：16.6s → 3.9s，data **IDENTICAL**
- bugBarChart：14.1s → 1.1s，data **IDENTICAL**
- projectTeamTimeWork：6.9s → 0.12s，data **IDENTICAL**
- 对照组 monthScopeByProgram（未改动路径）：IDENTICAL，耗时不变（4.1s vs 4.9s）
- 单测 103/103 通过（JDK 17）
- 中途插曲：增量编译导致 v2 实例 baseMapper 绑定异常（NPE），clean compile 后消失；8085 dev 库与正线库数据不同，8085 基线仅用于过程验证
**注意**：本地验证期间本地实例曾直连正线库运行约 15 分钟（只读接口验证），已关停。
workspace/specs/ai-sop-20260723-1024/06_test_docs/defects.md
+8
View File
@@ -0,0 +1,8 @@
# 缺陷记录
> 执行 test_cases.md 发现的缺陷逐条登记；修复后关闭并转 regression.md 复测。
> 严重级：P0 阻断（功能不可用/数据错误）｜P1 主要（功能缺陷有绕行）｜P2 次要（UI/体验）
| 缺陷单号 | 关联用例 | 严重级 | 现象 | 预期 | 状态(新建/修复中/待复测/已关闭) | 登记人 | 日期 |
|---|---|---|---|---|---|---|---|
| （暂无） | | | | | | | |
workspace/specs/ai-sop-20260723-1024/06_test_docs/regression.md
+7
View File
@@ -0,0 +1,7 @@
# 回归与复测记录
> 缺陷修复后按本表复测；每轮全量回归标注范围（全量/模块）。
| 轮次 | 范围 | 关联缺陷单号 | 复测结果 | 执行人 | 日期 | 备注 |
|---|---|---|---|---|---|---|
| （暂无） | | | | | | |
workspace/specs/ai-sop-20260723-1024/06_test_docs/test_cases.md
+252
View File
@@ -0,0 +1,252 @@
# 测试用例文档 — 禅道 AI SOP + 绩效系统改造
> 依据：`outputs/acceptance.md` 33 条 AC（14 个 FR 全覆盖）+ CHG-027 框架验收指标新字段。
> 用例编号 TC-{FR序号}-{序号}，与 AC 编号一一对应；每条含正常/边界/异常路径。
> 执行方式：手工按步骤执行，结果填入「执行记录」列（通过/失败+缺陷单号）。
---
## 0. 执行须知
### 0.1 环境
| 项 | 值 |
|---|---|
| 后端 | http://127.0.0.1:8085/zentao（测试库 192.168.1.161:3306/zentao_dev） |
| 前端 | dev server（npm run serve，如 http://localhost:8089） |
| 账号 | admin / 123456（系统管理员） |
| 测试数据 | 用户需求 324（产品 145）、研发需求 6566（expand 已 finished）、会议 84 |
### 0.2 通用准备
1. **接口 token**（接口类用例需要）：
```
POST /zentao/zt-user/login {"account":"admin","password":"<md5(123456)>"}
→ 响应 data 即 token，后续请求头带 token
```
2. **SQL 校验**：用例中「DB 预期」指在 161 zentao_dev 库执行对应 SELECT。
3. **文件类用例**：准备任意 `.md` 文件（如记事本写几行 markdown 表格）用于上传。
### 0.3 判定约定
- 页面类：以浏览器实际显示为准（截图留证）
- 接口类：以响应 code=0 + DB 落库为准
- 失败一律登记 `06_test_docs/defects.md`，修复后走 `regression.md` 复测
---
## 1. 用例明细
### TC-001 用户需求管理（FR-001）
**TC-001-1 评审通过激活**（AC-001-1，正常）
- 前置：新建用户需求并提交评审，全员评审人已在 zt_user 存在
- 步骤：①产品→用户需求→新建，填写标题/描述/验收标准，提交评审；②各评审人登录→评审通过
- 预期：status=active；DB zt_story_user.revieweddate 落库；二期后 activateddate 同步有值
**TC-001-2 评审不通过关闭**（AC-001-2，异常）
- 步骤：新建用户需求提交评审→评审人选「不通过」
- 预期：需求关闭；DB closedby/closeddate/closedreason 落库；列表状态显示已关闭
### TC-002 需求讨论会与纪要 MD（FR-002）
**TC-002-1 会议纪要上传 MD 并在线渲染**（AC-002-1，正常）
- 前置：产品 145 下已建会议（关联用户需求 324）
- 步骤：①产品→会议纪要→新建弹窗，选类型/日期/地点/参会人，「关联用户需求」单选下拉选 324；②附件区上传 .md 文件；③保存后进会议详情/用户需求 324 详情「会议纪要」tab；④点卡片上「MD」按钮
- 预期：DB zt_file 新增 objecttype=meeting 附件（含操作人 addedby/时间 addeddate）；zt_meeting.url 刷新为最新一份；MD 弹窗渲染富文本（非纯文本）
**TC-002-2 非 MD 附件不渲染**（AC-002-2，边界）
- 步骤：会议上传 PDF/图片附件
- 预期：附件列表仅提供下载，不出现 MD 在线渲染入口
**TC-002-3 关联需求精确匹配**（AC-002-3，异常/匹配）
- 前置：存在关联需求 112 的会议
- 步骤：打开用户需求 12 的详情「会议纪要」tab
- 预期：只列出 story_ids 精确含 12 的会议，不误中 112
**TC-002-4 编辑会议附件不误删**（补充，回归用例）
- 前置：会议已有 2 份 MD 附件
- 步骤：编辑弹窗打开（附件区应自动带出已有附件）→直接保存
- 预期：DB zt_file 原有附件 deleted 仍为 '0'，不被误标 '1'
### TC-003 PRD 文档管理（FR-003）
**TC-003-1 PRD 上传可见可下载**（AC-003-1，正常）
- 步骤：研发需求详情→PRD 区上传 .md PRD
- 预期：附件列表可见可下载；下载文件非 0KB、内容一致
**TC-003-2 多版 PRD 按时间排列**（AC-003-2，边界）
- 步骤：同一需求先后上传 2 版 PRD
- 预期：多份均保留可下载，按上传时间排列
### TC-004 需求级 AI 工作量指标（FR-004）+ 框架验收指标（CHG-027）
**TC-004-1 指标上传落库**（AC-004-1，正常）
- 步骤：`POST /zentao/zt-story-expand/saveOrUpdate`，报文 `{"storyId":<新需求id>,"workloadIndex":"3.2","aiParticipationRate":"0.6"}`
- 预期：code=0；DB zt_story_expand 新增一行，workload_index/ai_participation_rate 有值
**TC-004-2 幂等更新不新增**（AC-004-2，幂等）
- 步骤：同 storyId 再次提交不同指标值
- 预期：DB 仍一行，值被更新
**TC-004-3 已完成需求拒绝**（AC-004-3，异常）
- 步骤：对 storyId=6566（requirementStatus=finished）再提交
- 预期：code≠0，message=「该需求已完成，不可再修改」；DB 无变化
**TC-004-4 框架验收指标新字段**（CHG-027，补充）
- 步骤：①`saveOrUpdate` 报文 `{"storyId":324,"acceptanceCriteria":"## AC-1\n- Given…Then…"}`；②`GET /zentao/zt-story-expand/queryByStoryId?storyId=324`；③查 zt_storyspec.verify
- 预期：①code=0；②回读 acceptanceCriteria 完整（中文/换行不丢）；③老 verify 字段不受影响
### TC-005 验收标准展示（FR-005）
**TC-005-1 verify 富文本展示+用例评审链**（AC-005-1，验证）
- 步骤：研发需求编辑页录入验收标准（verify）保存→详情页查看；进入用例评审（story-case）流转一步
- 预期：详情页验收标准富文本正常展示；评审链状态可流转
### TC-006 研发任务双通道（FR-006）
**TC-006-1 AI 批量建任务**（AC-006-1，正常）
- 步骤：`POST /zentao/zt-task/aiBatchAdd`，报文含 storyId + tasks（1 条 type=devel 指派开发、1 条 type=test 指派测试，各带 aiEvaluationTime）
- 预期：响应返回 taskIds；DB zt_task 新增：status=wait、openedby=ai、estimate=报文工时；测试任务 assignedTo=指定测试人员
**TC-006-2 非法报文整批拒绝**（AC-006-2，异常）
- 步骤：storyId 不存在 或 type 非法，提交
- 预期：code≠0；DB 零入库（zt_task 无新增）
**TC-006-3 防重跳过**（AC-006-3，防重）
- 步骤：同 storyId+name+type 已存在时再次提交（含 1 条重复 + 1 条新任务）
- 预期：重复项进响应 skipped，新任务正常创建
### TC-007 任务级 AI 工时（FR-007）
**TC-007-1 工时入 estimate**（AC-007-1，正常）
- 步骤：TC-006-1 创建任务后查 DB
- 预期：zt_task.estimate=报文 aiEvaluationTime（标准字段）
**TC-007-2 无扩展表**（AC-007-2，豁免验证）
- 步骤：DB 执行 `SHOW TABLES LIKE 'zt_task_extend'`
- 预期：不存在该表
### TC-008 AI 代码审查报告 MD（FR-008）
**TC-008-1 上传+状态写入+在线查看**（AC-008-1，正常）
- 前置：需求下开发任务已完工
- 步骤：研发需求详情→「代码审查报告」→上传审查 MD（结论含 pass）
- 预期：DB zt_file(aiCodeReview) 落附件；zt_story.code_review_url 刷新；code_review_status=pass；详情页在线渲染
**TC-008-2 SOP 卡点**（AC-008-2，卡点）
- 步骤：code_review_status 为 NULL 或 reject 的需求，查看「提交测试报告」按钮
- 预期：按钮禁用/不可提交
**TC-008-3 多轮回炉**（AC-008-3，边界）
- 步骤：第 1 轮 reject 报告上传后，再传第 2 轮 pass 报告
- 预期：url 刷新为最新；历史多份 zt_file 均保留；extra.round 递增；status 随最新轮更新
**TC-008-4 非法参数拒绝**（AC-008-4，异常）
- 步骤：uploadBind 缺 storyId 或 objectType 非法
- 预期：拒绝并返回错误，不入库
### TC-009 BUG 全流程（FR-009）
**TC-009-1 提交→指派→修复→复测→验收**（AC-009-1，验证）
- 步骤：测试人员提交 BUG→指派开发→开发修复点解决→测试复测关闭→验收（bugYs）
- 预期：各状态流转正常，zt_bug 状态/指派/解决字段落库
### TC-010 测试类文档 4 字段（FR-010）
**TC-010-1 用例/模版只读**（AC-010-1，正常）
- 步骤：研发需求详情查看「测试用例」（testCase）与「测试报告模版」（testReport）
- 预期：可查看可下载；无上传覆盖入口
**TC-010-2 提交测试报告**（AC-010-2，正常+卡点）
- 前置：code_review_status=pass（按钮可用）
- 步骤：上传填完的测试报告（testReportSubmit）
- 预期：zt_story.test_report_submit_url 刷新；FR-014 判定该项齐备
**TC-010-3 其他测试文档**（AC-010-3，边界）
- 步骤：上传其他测试文档（testOther）
- 预期：test_other_url 刷新，可查看下载
### TC-011 AI 工作日志 MD（FR-011）
**TC-011-1 日志上传在线看**（AC-011-1，正常）
- 步骤：研发需求详情→「工作日志」上传 MD（或框架 uploadBind type=aiWorkLog）
- 预期：zt_file(aiWorkLog) 落附件；work_log_url 刷新；在线渲染
**TC-011-2 事件即传**（AC-011-2，时效·人工抽查）
- 步骤：抽 1 个框架节点产出，核对上传时间与事件时间
- 预期：当日即传，非月末批量补传
### TC-012 工作量指标完成率统计（FR-012）
**TC-012-1 完成率口径**（AC-012-1，正常）
- 前置：zt_story_month_workload 当月有数据
- 步骤：`GET /zentao/zt-perf/report?month=yyyy-MM&role=backendDev`（或完成率接口）取 workloadRate 项
- 预期：=Σ(月度工作量指数)÷(团队可用工作天数×5)；测试人员不计入产出方；与手工 SQL 计算一致
### TC-013 九岗位绩效报表（FR-013）
**TC-013-1 规则配置化**（AC-013-1，正常）
- 步骤：①/perf/report 页切换 9 岗位 tab；②/perf/config 改一条权重/阈值保存；③回报表页重算
- 预期：自动项产出分数；配置改动即时生效（无需改代码）；页面 auto/manual 徽标正确
**TC-013-2 对拍验收**（AC-013-2，对拍·需线下 Excel）
- 前置：IT 经理提供最近 1~2 个已线下考核月份的 Excel
- 步骤：系统 generateMonthScore 后与线下 Excel 逐人逐项比对
- 预期：一致或差异可解释（差异记录 defects.md 并评估是否口径问题）
### TC-014 大型需求文档齐备自动核查（FR-014）
**TC-014-1 五类齐全不扣分**（AC-014-1，正常）
- 前置：大型需求（指数>20）五类文档齐全（测试用例/测试报告提交件/AI文档更新记录/AI代码审查报告/AI工作日志）
- 步骤：月度核查 generateDocCheck
- 预期：五类全 ✓；不扣分；zt_doc_check 写快照
**TC-014-2 缺 2 份扣 4 分**（AC-014-2，扣分）
- 前置：同 6566 演示数据（缺 2 份）
- 步骤：generateDocCheck 后查 /perf/docCheck 矩阵
- 预期：3✓2✗；扣 4 分（每份 2 分）；zt_month_score.scopeJson 可见扣分
**TC-014-3 判定源正确性**（AC-014-3，验证）
- 步骤：仅上传 testReport 模版（不传提交件），另传 aiWorkLog 非 doc_update 类
- 预期：测试报告项判 ✗（不认模版）；AI 文档更新记录项判 ✗（只认 doc_update 类）
**TC-014-4 异议回滚**（AC-014-4，异议）
- 步骤：对扣分记录发起 appeal→技术负责人 appealReview 撤销
- 预期：对应扣分回滚；zt_doc_check/月分留痕（状态+操作人+时间）
---
## 2. 覆盖矩阵
| FR | 功能 | AC 数 | 用例 | 类型 |
|---|---|---|---|---|
| FR-001 | 用户需求管理 | 2 | TC-001-1/2 | 页面 |
| FR-002 | 会议纪要 MD | 3+1 | TC-002-1~4 | 页面+DB |
| FR-003 | PRD 文档 | 2 | TC-003-1/2 | 页面+接口 |
| FR-004 | AI 工作量指标 | 3 | TC-004-1/2/3 | 接口+DB |
| CHG-027 | 框架验收指标 | — | TC-004-4 | 接口+DB |
| FR-005 | 验收标准/用例 | 1 | TC-005-1 | 页面 |
| FR-006 | 任务双通道 | 3 | TC-006-1/2/3 | 接口+DB |
| FR-007 | 任务级工时 | 2 | TC-007-1/2 | DB |
| FR-008 | 代码审查报告 | 4 | TC-008-1~4 | 页面+接口 |
| FR-009 | BUG 流程 | 1 | TC-009-1 | 页面 |
| FR-010 | 测试文档 4 字段 | 3 | TC-010-1~3 | 页面+接口 |
| FR-011 | AI 工作日志 | 2 | TC-011-1/2 | 接口+页面 |
| FR-012 | 完成率统计 | 1 | TC-012-1 | 接口+SQL |
| FR-013 | 九岗位绩效 | 2 | TC-013-1/2 | 页面+对拍 |
| FR-014 | 文档齐备核查 | 4 | TC-014-1~4 | 接口+页面 |
合计 36 条用例；14 FR + CHG-027 全覆盖；每 FR ≥1 正常 + ≥1 异常/边界（FR-012/013 以对拍/口径验证承担）。
## 3. 执行记录（执行时填写）
| 用例 | 结果(通过/失败) | 执行人 | 日期 | 缺陷单号 | 备注 |
|---|---|---|---|---|---|
| （逐条填写） | | | | | |
## 4. 已知阻塞/依赖
- TC-013-2 依赖 IT 经理提供线下考核 Excel，未提供前挂起
- TC-001/005/009 为复用功能验证，可排最低优先级
- 上传类用例前置：8085 已重启加载最新代码（含 CHG-026/027）
workspace/specs/ai-sop-20260723-1024/06_test_docs/test_report_template.md
+89
View File
@@ -0,0 +1,89 @@
# 测试报告（模版）
> 说明：本模版由 AI 框架生成，测试人员下载后按实际执行填写，填完经研发需求详情「提交测试报告」上传。
> 依据：`test_cases.md`（36 条用例，14 FR + CHG-027 全覆盖）。
## 1. 测试概述
- 测试对象：禅道 AI SOP + 绩效系统改造
- 测试范围：FR-001 ~ FR-014 + CHG-027（见用例文档覆盖矩阵）
- 测试依据：acceptance.md 33 条验收标准
- 测试类型：功能测试（页面/接口/DB 校验）
## 2. 测试环境
| 项 | 值 | 实际情况（填写） |
|---|---|---|
| 后端 | http://127.0.0.1:8085/zentao（161 测试库） | |
| 前端 | dev server | |
| 测试账号 | admin 等 | |
| 测试日期 | | |
## 3. 用例执行汇总
| 总用例数 | 通过 | 失败 | 阻塞/挂起 | 通过率 |
|---|---|---|---|---|
| 36 | | | | |
## 4. 用例执行明细
| 用例编号 | 结果(通过/失败/阻塞) | 执行人 | 日期 | 缺陷单号 | 备注 |
|---|---|---|---|---|---|
| TC-001-1 | | | | | |
| TC-001-2 | | | | | |
| TC-002-1 | | | | | |
| TC-002-2 | | | | | |
| TC-002-3 | | | | | |
| TC-002-4 | | | | | |
| TC-003-1 | | | | | |
| TC-003-2 | | | | | |
| TC-004-1 | | | | | |
| TC-004-2 | | | | | |
| TC-004-3 | | | | | |
| TC-004-4 | | | | | |
| TC-005-1 | | | | | |
| TC-006-1 | | | | | |
| TC-006-2 | | | | | |
| TC-006-3 | | | | | |
| TC-007-1 | | | | | |
| TC-007-2 | | | | | |
| TC-008-1 | | | | | |
| TC-008-2 | | | | | |
| TC-008-3 | | | | | |
| TC-008-4 | | | | | |
| TC-009-1 | | | | | |
| TC-010-1 | | | | | |
| TC-010-2 | | | | | |
| TC-010-3 | | | | | |
| TC-011-1 | | | | | |
| TC-011-2 | | | | | |
| TC-012-1 | | | | | |
| TC-013-1 | | | | | |
| TC-013-2 | | | | | |
| TC-014-1 | | | | | |
| TC-014-2 | | | | | |
| TC-014-3 | | | | | |
| TC-014-4 | | | | | |
## 5. 缺陷统计
| 严重级 | 发现数 | 已关闭 | 待复测 | 未关闭 |
|---|---|---|---|---|
| P0 阻断 | | | | |
| P1 主要 | | | | |
| P2 次要 | | | | |
缺陷明细见 `defects.md`，逐条登记缺陷单号。
## 6. 回归记录
| 轮次 | 范围 | 结果 | 执行人 | 日期 |
|---|---|---|---|---|
| | | | | |
## 7. 测试结论
- 结论（通过 / 有条件通过 / 不通过）：
- 遗留问题与风险：
- 测试负责人签字：　　　　　　日期：
- 项目经理签字：　　　　　　日期：
workspace/specs/ai-sop-20260723-1024/07_council/decision.md
+34
View File
@@ -0,0 +1,34 @@
# Council 决策记录（关键决策留痕）
> 摘自 PRD 变更记录 + decision_log.md，按决策主题归并。
## D-01 AI 文档承载方式
**决策**：MD 文件流，不建 zt_ai_code_review / zt_ai_work_log 结构化表。
**理由**：不建表、人可直接阅读、上传即看；结构化弱点由 MD 头部约定补偿。
**决策人**：用户（CHG-014 拍板）。
## D-02 任务级 AI 数据承载
**决策**：砍 zt_task_extend；AI 工时入 zt_task.estimate；任务级指数豁免。
**理由**：evaluation_time 与 estimate 冗余；指数无消费方；一期缩至 1 列（W 10.2→3.2）。
**决策人**：用户（CHG-019 拍板）。
## D-03 禅道核心表加列破例
**决策**：zt_story 加 8 列（7 url + code_review_status）；zt_file/zt_meeting 各加 url。
**理由**：各存最新一份的访问需求直取优先；用户明确拍板接受破例。
**决策人**：用户（CHG-018/020/021/022/023/025）。
## D-04 任务提交双通道
**决策**：AI 框架批量（aiBatchAdd）+ 人工创建保留；AI 任务创建人=ai 专用账户；初始状态 wait 走现有任务流程。
**决策人**：用户（CHG-006/007）。
## D-05 上传接口鉴权
**决策**：二期必决项；落地为内部 token（saveOrUpdate/aiBatchAdd 限 ai，uploadBind 需登录），创建人取 token 身份。
**决策人**：用户（v1.10 升级 + CHG-061 落地）。
## D-06 原型暂缓
**决策**：原型与移动端暂缓（skip_flags.prototype=true）。
**决策人**：用户（2026-07-23）。
## D-07 普通/重大 Bug 分级
**决策**：severity 1=重大、2/3/4=普通，以老弹窗 getBugFindScore 为准；撤销 07-28 锁定的 1~2=重大。
**决策人**：用户（2026-08-04）。
workspace/specs/ai-sop-20260723-1024/07_council/review.md
+25
View File
@@ -0,0 +1,25 @@
# Council 评审记录（回溯）
> ⚠️ 本工作区为 **2026-10-08 回溯归档**，以下评审结论由 pmassist 会话记录回溯认定，
> 非 tgassist 实时门禁产物。
## 评审结论
| 项 | 结论 | 依据 |
|---|---|---|
| 需求合理性 | ✅ 通过 | SOP 符合性核查（v1.8）：18 步流程、6 类数据、8 项动作全有落点 |
| 架构取舍 | ✅ 通过 | 扩展表 + MD 文件流方案经 4 方案对比（5.5），用户拍板 |
| 证据充分性 | ✅ 通过（代码级） | PRD 12 章证据映射：全部 [ZT:...] 行号级引用，2026-07-22 两轮摸底 |
| 安全合规 | ⚠️ 有条件通过 | R-003 上传接口鉴权列为二期必决项 → CHG-061 已兑现，转通过 |
| 可验收性 | ✅ 通过 | 33 AC 覆盖 14/14 FR；含幂等/防重/对拍/判定源正确性验证点 |
## 评审过程事实
- 评审形式：用户逐轮质询 AI（summary.md「审查迭代」段），单日 25 版 PRD 迭代
- 拍板事项全部留痕于 PRD 变更记录（CHG-014 MD 流 / CHG-019 砍表 / CHG-021~025 zt_story 8 列）
- 对外交付评审：2026-08-07 用户拍板接口文档对外发布（Word 版）
## 遗留评审意见
1. 页面级验收需补截图证据（G2 门禁不能完全关闭）
2. 三期开工前须完成 R-004 考核公式逐 sheet 核对（与 IT 经理）
workspace/specs/ai-sop-20260723-1024/99_archive/release_notes.md
+40
View File
@@ -0,0 +1,40 @@
# 归档说明（Release Notes）
> 归档日期：2026-10-08 | 归档操作：AI 回溯回填 | 归档人：pmassist
## 归档原因
本需求（ai-sop）原始会话由 pmassist-v3 创建于 `prds/ai-sop-20260723-1024/`，
从未进入 tgassist Spec Workspace 流，导致 `workspace/specs/` 长期空置。
按用户决策（2026-10-08），将会话已定稿产物回填归档至本工作区，补齐门禁追溯档案。
## 文件来源映射
| 本工作区 | 来源（prds/ai-sop-20260723-1024/） | 处理方式 |
|---|---|---|
| 00_meta/session.yaml, summary.md, decision_log.md | 同名文件 | 原样复制 |
| 00_meta/rounds/, questions/ | 同名目录 | 原样复制 |
| 00_meta/project.yaml, status.md, roles.md, gates.md, evidence_index.md | — | **归档时新建（派生）** |
| 01_input/requirements.md | desc.md | 复制 |
| 01_input/prd_final.md | outputs/prd_final.md | 复制（冻结基线） |
| 01_input/references/ | materials/ ×3 + materials_index.md + 禅道AI通道接口文档_v1.0.docx | 复制 |
| 02_acceptance/acceptance.md | outputs/acceptance.md | 复制 |
| 02_acceptance/checklist.md | — | **归档时新建（派生自 acceptance.md）** |
| 03_plan/ | — | **归档时新建（派生自 PRD 4.3/9/10 章）** |
| 04_design/architecture.md, data_model.md | — | **归档时新建（派生自 PRD 5/7 章）** |
| 04_design/interfaces.md | outputs/ai_api_interfaces.md | 复制 |
| 05_delivery/dev_log.md | dev_log.md | 复制 |
| 05_delivery/change_log.md | — | **归档时新建（派生自 PRD 变更记录 + summary）** |
| 06_test_docs/ ×4 | 06_test_docs/ ×4 | 原样复制 |
| 07_council/review.md, decision.md | — | **归档时新建（回溯认定）** |
## 事实源声明
**`prds/ai-sop-20260723-1024/` 仍是事实源**。本工作区为归档快照，
若两处内容冲突，以 prds/ 为准并同步修订本工作区。
## 遗留事项（进入下一门禁前）
1. 页面级验证补截图（RT 证据）→ 关闭 G2
2. 用户建 zentao 需求单给 ID → 闭环 5.6 ID 流转约定
3. 三期立项时新建 tgassist 工作区（从方向 1 初始化起走实时门禁）