wecom_it_smart_desk/docs/04-运维文档/部署运维/00-文档规范化整改记录.md

00 · 文档规范化整改记录

版本: v1.6 | 日期: 2026-07-31 | 维护人: 宋献 / Duckula 定位: 本文件是项目所有文档命名/位置/关联/命令铁律/完整度检查的集中索引，不是部署文档。 权威规范: 见 00-标准故障排查手册.md §0.4 引用处的 spec（docs/00-项目总览/产品文档规范-spec.md — 后续登记）

---

一、为什么要单独建这个索引

部署文档 v1.0 在交付前未通过产品文档规范检查（30 项问题），于是补做 v1.0 → v1.1 整改。 今后所有文档上线前都应进行一次"规范检查"——本文件就是这些检查动作的索引，避免每次都从零审视。

四个规范维度：

维度	关注点
A 命名/位置	文件名正则、所在子目录、头部模板
B 关联引用	PRD / 技术方案 / 原型图 / 测试用例 / 上游依赖 是否齐全
C 命令铁律	部署文档命令是否违反 jumpserver-V2 / psftp / 卷挂载 / 配置同步 等铁律
D 完整度	前置条件、pre-check/post-check、灰度开关、可执行验证、回滚三路方案、监控阈值

---

二、整改记录

整改 #1 · REQ-通用-002 快速回复规则后台管理 — 部署文档 v1.0 → v1.1

项目	值
日期	2026-07-28
触发人	宋献
源文档	../快速回复规则后台管理-部署文档-v1.0.md（已升级为 v1.1，按 spec.md 2.3.3 存量豁免条款保留原文件名）
整改维度	A + B + C + D 全维命中
问题数	30 项（A 类 3 / B 类 4 / C 类 8 / D 类 10 / 其他 5）
关键修复	1) 头部补全：状态/作者/关联 5 份文档/命名规范说明 2) §0 新增 9 项前置条件表 3) §1.2 新增"规则类型与初始数量"权威表 4) §1.3 新增 .env 变量变更清单 5) §2-§4 全命令改用 v2_ops.py + 远程禁用 $(...) + psftp 6) §3 新增容器外业务验证（curl + WS + agent-browser） 7) §6 灰度上线新增 QUICK_RULE_ENABLED 开关；回滚补全三路方案 8) §7 监控阈值改为可告警具体值；§8 常见问题由 3 扩到 6
关联动作	1) config.py:262 新增 quick_rule_enabled: bool = True 2) docker-compose.yml:157 注入 ${QUICK_RULE_ENABLED:-true} 3) .env.example:108 模板注释 4) quick_rule_service.py:118,148 两条 check_* 旁路 5) 新建 TC-通用-002-快速回复规则后台管理.md — 26 条用例
上线状态	待部署（prod）

---

整改 #2 · 5 份 BUG 缺陷文档统一规范化

项目	值
日期	2026-07-28
触发人	宋献
源文档	5 份缺陷单：BUG-坐席-001、BUG-AI-001、BUG-通用-001、BUG-用户-001、BUG-用户-002
整改维度	A（命名/位置）+ 头部模板 + 变更记录
问题数	每份 3-5 项不等
关键修复	1) 命名改为 BUG-{模块}-{描述}-{序号}.md（符合 ^BUG-.*-\d+\.md$ 正则） 2) 头部补全"版本"字段，统一标准模板格式 3) 章节统一编号（1-8：基本信息/复现/根因/修复方案/验证/关联/变更记录），去除杂乱的序号风格 4) 变更记录增加"版本/变更原因/影响范围"列（5 列标准化，原来仅 2-3 列） 5) 关联代码路径统一补 src/ 前缀 6) 各文档末尾追加本条规范化整改记录
关联动作	1) 旧文件名已删除（5 个旧 .md 文件） 2) 新建 5 个规范命名文件 3) 本整改记录追加变更
上线状态	N/A（仅文档格式变更，无代码改动）

---

整改 #3 · BUG 单迁移到独立 05-缺陷单/ 目录

项目	值
日期	2026-07-28
触发人	宋献
整改目标	1) 为 BUG 单建立独立物理目录 03-测试文档/05-缺陷单/ 2) 5 份 BUG 单从 07-项目管理/ 物理迁移 3) 更新规范文档 spec.md v1.10 → v1.11 4) 修复 3 处跨文档旧路径引用 5) 缺陷跟踪表与 BUG 单"双视图分离"明确
整改维度	A + B + C
关键修复	1) 目录新建：docs/03-测试文档/05-缺陷单/，附 README.md（命名/状态/目录纪律/引用规范） 2) 文件迁移：5 份 BUG 单从 07-项目管理/ 移至 05-缺陷单/ 3) 规范升级：spec.md § 2.1 新增 05-缺陷单/ 子目录；§ 2.3.3 缺陷单命名加目录限定；§ 12.6 改为"双视图分离"（跟踪表在 07-项目管理/，BUG 单在 05-缺陷单/）；§ 13.2 新增"BUG 单放错目录"修复项 4) 引用同步：3 处旧路径修复（PRD-REQ-通用-001、00-标准故障排查手册、任务说明书-80）+ 1 处新加"文档位置"列到缺陷跟踪表 5) 状态同步：BUG-通用-001 状态从"已修复"修正为"进行中"（与单据实际状态一致）
关联动作	1) docs/00-产品开发流程与文档管理规范.md v1.10 → v1.11 2) docs/03-测试文档/05-缺陷单/README.md 新建 3) docs/07-项目管理/缺陷跟踪表.md v1.0 → v1.1
上线状态	N/A（仅文档目录迁移 + 路径规范）

---

整改 #4 · 快速回复规则页面顶部重复统计卡片移除

项目	值
日期	2026-07-28
触发人	Simon / 宋献
变更内容	删除管理后台 /quick-rules 页面顶部 .stats-row 内 3 张重复统计卡片（打招呼规则 12 / 路由关键词 35 / 路由目标 6），仅保留下方标签导航的 count 徽标、筛选区、表格及全部操作
变更原因	统计卡片与标签导航徽标重复展示相同规则数量；卡片点击仅调用 switchTab，标签按钮已完整承担切换能力
影响范围	仅管理后台 /quick-rules 主页面展示；后端 getQuickRuleStats 接口保留；src/frontend-admin/src/views/quick-rules/audit.vue 的 4 张审计统计卡片不在本次范围
关联文件路径	src/frontend-admin/src/views/quick-rules/index.vue:16-54（template 卡片）、src/frontend-admin/src/views/quick-rules/index.vue:176、src/frontend-admin/src/views/quick-rules/index.vue:195-200（script setup / getQuickRuleStats）；PRD、原型图、技术方案、任务说明书、测试用例、部署文档同步更新
后续验证方式	1) 页面加载后 DOM 中无 .stats-row 2) 标签徽标仍显示 12 / 35 / 6 3) 逐项回归标签切换、表格加载、筛选、搜索、分页、批量删除、编辑、启停开关 4) 确认审计页 4 张卡片保持不变
上线状态	文档已更新，待前端变更部署后按 TC-027～TC-029 验证

---

整改 #5 · BUG-通用-002 修复 + 周边文档规范化同步

项目	值
日期	2026-07-28
触发人	宋献
源 BUG	用户反馈：管理后台 → 快速回复规则 → "路由目标" Tab → 业务分类下拉菜单提示"服务器内部错误"
整改维度	A + B + D + 新增"三处文档同步"动作
问题数	5 项（修复 3 处 + 文档同步 2 处）
关键修复	代码 3 处：(1) app/api/admin/quick_rules.py QuickRuleResponse.priority: int → Optional[int] = None（同时为 5 个潜在 NULL 字段补 Optional）+ (2) scripts/init_quick_rules.sql routing_target 段补 priority 列 → 6 条记录添加 0 值 + (3) DB 实时回填 UPDATE quick_rules SET priority=0 WHERE priority IS NULL ；隐藏陷阱 1 处：(4) 本地 quick_rules.py 存在 3 处遗留语法错误（2 处 )) + 1 处 )），AST 校验才能发现；文档同步 5 份：(5) 新建 BUG-通用-002 缺陷单 + 故障手册 v2.9→v3.0 新增 CASE-20260728-05 + 任务说明书-131 v1.2→v1.3 + 整改记录追加 #5 + 缺陷单 README 清单追加
部署铁律（新增）	后端源码上线前必须 AST 静态校验；本地 Windows 路径不直接同步到容器；正确流程：本地 Edit → python -c "import ast; ast.parse(...)" 校验 → v2_ops.py upload → cp /tmp/xxx /opt/wecom-it-desk/app/xxx → docker restart wecom_it_backend
验证结果	8/8 通过：rule_type=routing_target 6 条 + 6 个分类筛选各 1 条 + 不存在的分类 0 条；后端日志无 Pydantic 错误
排查陷阱	后端 API 路径 不带 /api/ 前缀（nginx 已 strip），调 http://127.0.0.1:8000/admin/quick-rules 不是 /api/admin/quick-rules；容器内 localhost 走 IPv4（127.0.0.1）而非 IPv6（::1）；测试 token 注入 Redis 容器内 redis.setex("user:token:{token}", ttl, json.dumps({...}))（employee_id 需对应 DB 中 Agent.user_id）；IP 白名单中间件需 X-Forwarded-For: 10.240.1.100
关联动作	1) app/api/admin/quick_rules.py:77 QuickRuleResponse 字段类型修复 2) scripts/init_quick_rules.sql:80 routing_target 段补 priority 列 3) DB 实时回填 6 条 4) 新建 BUG-通用-快速回复规则-路由目标筛选500-002.md 5) 00-标准故障排查手册.md v2.9 → v3.0 新增 CASE-20260728-05 6) 任务说明书-131 v1.2 → v1.3（追加 BUG 修复子任务）
上线状态	✅ 已完成

---

整改 #6 · 管理后台 IA 重构 — 三件套补齐（PRD v1.0→v1.2 / 技术方案扩展 / 任务说明书扩展）

项目	值
日期	2026-07-28
触发人	宋献
源需求	REQ-集成-002 v1.2（管理后台菜单/路由 IA 重构 + 分配模式 Tab 收编）
整改维度	A 命名/位置 + B 关联引用 + D 完整度
问题数	3 项（缺独立任务说明书 + 技术方案仅覆盖子任务 + PRD 文件名版本号不一致）
关键修复	PRD 文件名修正：v1.0.md → v1.2.md（文档内容已含 v1.1 IA 重构 + v1.2 分配模式 Tab 收编变更说明，仅文件名滞后）；技术方案扩展：原 技术方案-REQ-集成-002-管理后台v1.2-分配模式Tab收编.md 仅覆盖"分配模式 Tab 收编"子任务，新建 技术方案-REQ-集成-002-管理后台v1.2-IA重构整体.md 覆盖 P0 三 bug + P1 单一真源 + P1-b Dashboard widget + P2-a/P2-c 两路由补全 + v1.2 分配模式 Tab 收编 全部 6 阶段；任务说明书扩展：原 任务说明书-REQ-集成-002-分配模式Tab收编.md 仅覆盖子任务，新建 任务说明书-REQ-集成-002-IA重构整体.md 同覆盖 6 阶段，状态标记「5/6 阶段已上线 + 1 阶段待执行」
归档动作	旧 任务说明书-REQ-集成-002-分配模式Tab收编.md → 任务说明书-REQ-集成-002-分配模式Tab收编.v1.0.archive.md（保留作为子任务档案，避免重复维护）
引用同步	1) designdocs/sysdesign.md:7 v1.0 → v1.2 2) 自身 § 13 关联文档已指向 v1.2 文件名
ASCII 副本同步	1) D:\dev\wecom\docs\01-产品文档\08-集成生态\PRD-REQ-集成-002-管理后台-v1.2.md 2) D:\dev\wecom\docs\02-技术文档\技术方案-REQ-集成-002-管理后台v1.2-IA重构整体.md (md5 AF8BB3E2...) 3) D:\dev\wecom\docs\07-项目管理\任务说明书\任务说明书-REQ-集成-002-IA重构整体.md (md5 9444B22A...)
收益	1) IA 重构作为完整需求留下独立 task document，便于后续追溯 2) 三件套（PRD + 技术方案 + 任务说明书）版本号统一 v1.2 3) 6 阶段工作分解清晰可见（P0/P1/P1-b/P2-a/P2-c/v1.2） 4) 已完成阶段 + 待执行阶段状态可视化
教训	大需求重构（P0+P1+P2 跨越多次部署迭代）应在第一个阶段就建任务说明书，不要等所有阶段上线后回溯补全，否则踩坑经验、技术决策、版本号一致性会遗漏
上线状态	✅ 已完成（文档）

---

整改 #7 · REQ-会话-001 v1.2 三件套位置/任务说明书/历史归档整改

项目	值
日期	2026-07-30
触发人	宋献 / Duckula
源需求	REQ-会话-001 v1.2（员工结束会话：6 态按钮 + 4 种引导语 + 顶部按钮 AI 场景互斥）
整改维度	A 命名/位置 + B 关联引用 + 历史归档
问题数	3 项（技术方案位置违规 + 任务说明书缺失 + 历史版本未归档）
关键修复	1) 技术方案 v1.2 位置修正：从 docs/01-产品文档/02-会话管理/ 违规位置移到 docs/02-技术文档/（skill §3.1.1 明确禁止放在产品文档目录）；2) 清理遗留副本：docs/01-产品文档/02-会话管理/技术方案-REQ-会话-001-员工结束会话-v1.0.md 历史副本删除（与正确位置 v1.0 重复）；3) 技术方案 v1.0 归档：重命名为 技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md（被 v1.2 覆盖）；4) 任务说明书新建：任务说明书-REQ-会话-001-员工结束会话v1.2.md，覆盖 PRD v1.2 §七 7 阶段实施计划（M1-M7），引用技术方案 + 原型 + 历史任务说明书 #128 + BUG-用户-003 修复样本
归档动作	技术方案-REQ-会话-001-员工结束会话-v1.0.md → .v1.0.archive.md（保留作为 v1.0 阶段档案）
引用同步	1) PRD v1.2 §六 关联文档"技术方案-REQ-会话-001-员工结束会话-v1.2.md" 路径已正确 2) 任务说明书 §📎 附件引用了归档后的 v1.0 路径
收益	1) 三件套位置严格符合 product-doc-standard 规范 2) 大需求（跨多阶段实施）从第 1 个阶段就有任务说明书，避免回溯补全 3) 历史版本明确归档，新旧版本通过命名后缀区分
教训	技术方案位置约束极易被忽略——按业务模块组织文档（PRD/原型在 01-产品文档/02-XX/）的习惯会导致技术方案也"顺手"放同目录，下次新建技术方案前必须先确认 docs/02-技术文档/ 才是正确位置
上线状态	✅ 已完成（仅文档位置/命名整改，无代码改动）

---

整改 #8 · REQ-会话-001 v1.3 整合区方案 A — 三件套增量 + 5 项决策落地

项目	值
日期	2026-07-31
触发人	宋献 / Duckula
源需求	REQ-会话-001 v1.3（员工结束会话：整合区方案 A 5 项决策 2026-07-31 用户拍板）
整改维度	A 命名/位置 + B 关联引用 + D 完整度
问题数	3 项（PRD/技术方案/任务说明书 三件套增量 + 5 决策落地产出 + 原型图 v1.3 配套固化）
关键修复	1) PRD v1.3：新建 PRD-REQ-会话-001-员工结束会话-v1.3.md，复制 v1.2 全文，§九 变更记录扩展为 v1.1 → v1.2 → v1.3，新增 §十一 v1.3 整合区增量（11.1 设计理念 / 11.2 5 元素堆叠 / 11.3 9 场景 / 11.4 5 决策清单 / 11.5 与 v1.2 对比表 / 11.6 实施要点 / 11.7 关键约束）；2) 技术方案 v1.3：新建 技术方案-REQ-会话-001-员工结束会话-v1.3.md，复制 v1.2 全文，§九 变更记录扩展为 v1.1 → v1.2 → v1.3，新增 §十 v1.3 整合区实施要点（A 组件拆分 / B 文件清单 3 新建 3 修改 / C 共享知识含 4 项 v1.2y 不动 PASS 内容 / D 数据结构 IntegrationZoneProps + Emits 接口 / E 任务列表 8 项 3.0d / F 待明确事项含 v1.4 store.shiftHours）；3) 任务说明书 v1.3：新建 任务说明书-REQ-会话-001-员工结束会话v1.3.md，复制 v1.2 全文，M1-M7 标记 ✅ 已完成 + 新增 M8-M14 待开始（2.5d 整合区实施 7 任务）；4) 原型图 v1.3 配套：覆盖更新 原型-REQ-会话-001-结束会话流程-v1.3.html，9.3 节 9 场景状态条文案统一"在线 · 9:00-18:00"，9.6 节由"5 项待决策"替换为"5 项已拍板结论表"
5 项已拍板决策	1) 状态条策略 = 永久显示；2) 状态条文案 = 在线 · 9:00-18:00（前端硬编码，后端班次后续补）；3) 整合区背景色 = #fafafa 浅灰（沿用 chat-mock）；4) 引导语位置 = 整合区按钮下方；5) 移动端折叠 = 不折叠默认展开
不动 v1.2y 已 PASS 内容（关键约束）	1) inputBarGuideText.ts 4 种引导语；2) inputBarCallAgentState.ts 6 态状态机；3) conversation.ts:1911-1925 getResolveMessageText 会话关闭消息；4) closing.ts:119 reopenConversation API
关联动作	1) 三件套 v1.3 + 原型图 v1.3 全部发布 2) v1.4 路线图：store.shiftHours 接后端班次数据（PRD v1.3 §11.6 / 技术方案 v1.3 §F） 3) 三件套文件名规范化：PRD v1.3（01-产品文档/02-会话管理/）+ 技术方案 v1.3（02-技术文档/）+ 任务说明书 v1.3（07-项目管理/任务说明书/）
收益	1) 整合区方案 A 从产品决策 → 技术方案 → 任务分解形成完整闭环；2) 5 项决策以"已拍板结论表"形式固化在 PRD §11.4 / 技术方案 §C.3 / 任务说明书 M8-M14 三个文档，避免后续争议；3) 关键约束"不动 v1.2y 已 PASS 内容"明确写入 PRD §11.7 / 技术方案 §C.4，防止过度重构
教训	方案 A 多文档同步必须显式列出"已拍板结论表"：相比之前 #7 整改的"v1.2 三件套补齐"，v1.3 更进一步——除文档补齐外，还需把拍板决策的结论（而不是问题）固化在文档中，让执行方一眼能看到"做什么 / 怎么做 / 不动什么"
上线状态	✅ 已完成（三件套 + 原型图全部发布；M8-M14 待开发启动）

---

整改 #9 · REQ-通用-001 前端设计系统 v1.1 → v1.2 视觉主题重定义

项目	值
日期	2026-08-06
触发人	宋献 / Duckula
源需求	REQ-通用-001：三端视觉主题重定义，员工端由企微绿调整为服务蓝
整改维度	A 命名/版本 + B 关联引用 + D 完整度
关键修复	1) PRD 内容从 v1.1 升级为 v1.2；2) 修正原文件名 v1.0 与内容 v1.1 不一致问题；3) 旧文件归档为 PRD-REQ-通用-001-前端设计系统-v1.1.archive.md；4) 新增基础色板/角色主题/语义用途三层 Token；5) 固化员工端服务蓝、坐席端深海蓝、管理端海军蓝主题；6) 增加可访问性、玻璃效果渐进降级、分阶段迁移与验收标准
引用同步	更新 01-产品规划总览-v1.0.md 与 IT智能服务台-系统架构设计文档v2.md 对 v1.2 PRD 的引用；PRD 关联员工端、坐席端、管理端原型及评审提案
影响范围	仅产品文档与引用路径变更；暂未修改三端生产代码和既有原型，待主题方案评审拍板后实施
收益	角色主题与语义色职责分离；员工端绿色不再语义过载；三端基础设计语言和主题迁移边界明确
上线状态	🟡 文档已完成，待评审；代码与原型待后续阶段实施

---

三、规范检查清单（模板）

下次新增/修改任何文档前，对照检查 30 项最少 100%。

A. 命名/位置（3 项）

• A1：文件名符合规范正则（如部署文档：^DEPLOY-.*\.md$）
• A2：放在正确子目录（如 04-运维文档/部署运维/）
• A3：含标准头部模板（状态/版本/日期/作者/关联文档）

B. 关联引用（4 项）

• B1：PRD（若有）
• B2：技术方案（若有）
• B3：原型图/UI 设计（若有）
• B4：测试用例 + 上游依赖（Alembic 迁移 / init SQL / 配置项）

C. 命令铁律（8 项）

• C1：服务器入口走 jumpserver-V2 + 资产名 hz-oa-ai-g-dataquery-90-5-110 + 系统用户 生产环境admin用户
• C2：远程命令禁用 $(...)（PowerShell 本地展开），改用纯管道或批处理文件
• C3：本地源路径纯 ASCII（中文路径 GBK 误读），可用 D:\dev\wecom
• C4：唯一传输通道 psftp（base64+PTY 与 elFinder 已废除）
• C5：必须用 PowerShell 工具（Git Bash plink bash.exe 报错）
• C6：后端命令带 --workers 1（WS 进程内单例）
• C7：代码变更 restart，依赖变更才 build
• C8：所有 v2_ops.py 调用使用绝对路径

D. 内容完整度（10 项）

• D1：前置条件表
• D2：pre-check 清单
• D3：post-check 清单
• D4：.env 变量变更清单（按"配置同步铁律"）
• D5：灰度开关（如新增功能开关 QUICK_RULE_ENABLED、RAGFLOW_ENABLED、SMS_2FA_ENABLED 模式）
• D6：可执行 curl/WS 验证命令（含容器外）
• D7：DB migration upgrade / downgrade -1 路径
• D8：回滚三路方案（DB / git revert / 前端 dist）
• D9：监控告警明确阈值（不是"关注一下"）
• D10：常见问题 FAQ ≥ 6 条

其他（5 项）

• E1：错别字校对（如"数据库插件"→"数据库表"）
• E2：变更记录表含"变更原因/影响范围"两列
• E3：数字/计数（如 12/33/6/51）只在一处出现（权威表），其余引用
• E4：链接相对路径优先（避免日后迁移文档位置断链）
• E5：代码块标注语言（bash / powershell / sql）

---

四、规范检查流程（提议）

┌──────────────────────────────────────────────────────────────┐
│  Step 1：命名/位置（30 秒）                                     │
│  - 文件名正则校验                                               │
│  - 子目录归属                                                   │
│  - 标准头部存在                                                 │
└──────────────────────────────────────────────────────────────┘
                            ↓ 通过
┌──────────────────────────────────────────────────────────────┐
│  Step 2：关联引用（1 分钟）                                     │
│  - PRD / 技术方案 / 原型图 / 测试用例 / 上游依赖                │
└──────────────────────────────────────────────────────────────┘
                            ↓ 通过
┌──────────────────────────────────────────────────────────────┐
│  Step 3：命令铁律（2 分钟）                                     │
│  - jumpserver / psftp / 卷挂载 / 配置同步 / 禁用 $()           │
└──────────────────────────────────────────────────────────────┘
                            ↓ 通过
┌──────────────────────────────────────────────────────────────┐
│  Step 4：内容完整度（5 分钟）                                   │
│  - 前置条件 / pre-check / post-check / 灰度 / 回滚 / 监控       │
└──────────────────────────────────────────────────────────────┘
                            ↓ 通过 → 上线

---

五、变更记录

日期	版本	变更内容	变更人	变更原因	影响范围
2026-07-28	v1.0	建立项目首个规范化整改索引	宋献 / Duckula	配合 REQ-通用-002 部署文档 v1.1 整改同步发布	全部后续文档上线前必经流程
2026-07-28	v1.1	新增整改 #2：5 份 BUG 缺陷文档统一规范化整改	宋献 / Duckula	统一缺陷文档命名、头部及变更记录	07-项目管理/ 下缺陷文档
2026-07-28	v1.2	新增整改 #3：BUG 单迁移并建立独立缺陷单目录	宋献 / Duckula	落实 BUG 单物理位置规范	spec § 2.1 + § 12 + 5 处旧文档引用
2026-07-28	v1.3	新增整改 #4：移除快速回复规则页面顶部 3 张重复统计卡片，并登记代码事实与回归方式	Simon / 宋献	页面信息冗余	REQ-通用-002 文档链及管理后台 /quick-rules 页面
2026-07-30	v1.4	新增整改 #7：REQ-会话-001 v1.2 三件套位置/任务说明书补齐/历史归档	Duckula (AI)	大需求重构跨阶段实施，PRD v1.2 阶段必须三件套对齐 + 任务说明书 + 历史归档	REQ-会话-001 文档链（PRD v1.2 + 原型 v1.2 + 技术方案 v1.2）
2026-07-31	v1.6	新增整改 #8：REQ-会话-001 v1.3 整合区方案 A 三件套增量 + 5 项决策落地	Duckula (AI)	方案 A 多文档同步必须显式列出"已拍板结论表"，把决策结论固化而非问题陈述；5 项决策落地需贯穿 PRD/技术方案/任务说明书/原型图 4 份文档	REQ-会话-001 v1.3 文档链（PRD v1.3 §十一 + 技术方案 v1.3 §十 + 任务说明书 v1.3 M8-M14 + 原型图 v1.3 §⑨）
2026-08-03	v1.7	新增整改 #10：REQ-会话-001 v1.4 状态条删除闭环（整改 #9 遗留待办 #1 终态）	Duckula (AI)	闭环 PRD v1.3 ↔ 代码 v1.3.5 状态条分歧：以 v1.3.5 代码为准删除整合区状态条，三件套升 v1.4 + 原型 v1.4 + TR 分歧升级为已闭环 + 任务说明书对齐	REQ-会话-001 v1.4 文档链（PRD v1.4 + 技术方案 v1.4 + 原型 v1.4 + 任务说明书 v1.4 + TR-会话-001 v1.3.2 附录 A）

---

整改 #9 · REQ-会话-001 版本合并 + REQ-用户-005 规范化（7 文档合并）

项目	值
日期	2026-07-27
触发人	宋献 / Duckula
源需求 / 源文档	REQ-会话-001（员工结束会话，PRD/原型 v1.0-v1.3 合并）；REQ-用户-005（头像菜单退出，v1.0→v1.1 规范化）
整改维度	A 命名/位置 + B 关联引用 + D 完整度
问题数	11 项（7 文档版本合并 + 4 类引用/编码缺陷）
关键修复	【会话-001 版本合并】 1) 归档 PRD v1.0/v1.1/v1.2 → .v1.x.archive.md（canonical 为 v1.3，其 §九 变更记录已覆盖 v1.1→v1.2→v1.3）；2) 归档 原型 v1.0/v1.1/v1.2 → .v1.x.archive.html（保留 v1.3 + 整合区方案A v1.3 为现行）；3) 归档 技术方案 v1.2 → .v1.2.archive.md（v1.3 已存在为现行）。 【用户-005 规范化】 4) PRD + 原型 文件名 v1.0→v1.1（铁律2：文件名=内容版本，内容头部本就是 v1.1）；5) 技术方案 文件名 v1.0→v1.1（内容本就是 v1.1）。 【引用对齐】 6) PRD-会话-001 v1.3 §六：原型/技术方案引用 v1.2→v1.3 且技术方案补全 ../../02-技术文档/ 路径；7) 技术方案-会话-001 v1.3 头部：PRD/原型裸引用补全相对路径；8) 用户-005 三件套（PRD/技术方案/任务说明书/TC）互引 v1.0→v1.1，相关 PRD 指向会话-001 v1.3，参考原型指向自身 v1.1；9) 任务说明书 #128 关联 PRD/技术方案/原型 v1.0→v1.3（技术方案路径改 02-技术文档/）；10) 会话-001 三份任务说明书（v1.2/v1.3/通用）中被本次归档波及的 v1.2/v1.0 引用改为 .archive 有效历史链接；v1.3 原型 HTML 的"对应 PRD/技术方案"由 v1.2 改为 v1.3。 【编码缺陷】 11) 修复 4 处 UTF-8 乱码（U+FFFD）：用户-005 PRD「退出风险」、用户-005 任务说明书「菜单退出」「结束咨询按钮」、会话-001 技术方案 v1.3「标题栏坐席徽章」；历史缺陷/TC 文档（BUG-003、TC-用户-008）的 v1.0 裸引用改为 .archive。
归档动作	PRD-会话-001-v1.0/v1.1/v1.2.md → .v1.x.archive.md；原型-会话-001-v1.0/v1.1/v1.2.html → .v1.x.archive.html；技术方案-会话-001-v1.2.md → .v1.2.archive.md；用户-005 PRD/原型/技术方案 v1.0→v1.1（现行文件改名，非归档）
引用同步	会话-001 v1.3 现行三件套（PRD/技术方案/原型/任务说明书）互相指向 v1.3；用户-005 现行三件套（PRD v1.1/技术方案 v1.1/任务说明书/TC）互相指向 v1.1；被归档版本以 .archive 形式在任务说明书中保留历史链接
ASCII 副本同步	无需（仅中文路径文档，无 ASCII 副本机制参与）
收益	1) 会话-001 现行文档单一真源收敛到 v1.3，历史版本可溯；2) 用户-005 三件套版本对齐（均 v1.1），消除"文件名 v1.0 / 内容 v1.1"错位；3) 跨文档引用全部有效，无悬空链接；4) 消除 4 处编码乱码
教训	① 文件名版本号必须随内容同步 bump：用户-005 PRD/技术方案内容已升 v1.1 但文件名仍 v1.0，埋雷数月；② 技术方案应落在 02-技术文档/，裸引用（无路径）会从 PRD 所在目录错误解析；③ 中文文档的 UTF-8 乱码需专项扫描：本次 4 处乱码均因早期 Edit 写入异常，合并时须用 U+FFFD 扫描兜底
遗留待办	1) PRD v1.3 ↔ 代码 v1.3.5 状态条分歧：PRD/技术方案 v1.3 描述整合区"状态条永久显示"，但代码 integrationZoneLogic.ts 注释称 v1.3.5 已删除状态条、inputBarGuideText.ts 场景3 引导语亦于 v1.3.5 移除；需产品确认是否回退 PRD 或补全 v1.3.5 清理；2) 其他文档（排查手册/AI-001/历史归档/坐席离线缺陷）仍有历史乱码，超出本次范围未处理
上线状态	🟡 文档合并/归档/引用对齐已完成（无代码改动）；PRD↔代码状态条分歧待产品拍板后补 TR

---

整改 #10 · REQ-会话-001 v1.4 状态条删除闭环（分歧 1 终态）

项目	值
日期	2026-08-03
触发人	宋献 / Duckula
源需求	REQ-会话-001（员工结束会话）：闭环整改 #9 遗留待办 #1「PRD v1.3 ↔ 代码 v1.3.5 状态条分歧」
拍板结论	以 v1.3.5 代码为准：删除整合区状态条（不向员工暴露坐席在线/离线）。整合区由 4 元素降为 3 元素（操作按钮 + 进度胶囊 + 引导语）。
整改维度	A 命名/位置 + B 关联引用 + D 完整度
关键修复	1) PRD v1.4：新建 PRD-REQ-会话-001-员工结束会话-v1.4.md，复制 v1.3 全文，§九 变更记录扩展为 v1.1→v1.2→v1.3→v1.4；§3.4 / §11.4 决策 1 由「✅ 永久显示」反转为「❌ v1.4 删除」；§11.2 整合区三元素堆叠；§11.3 九场景表移除状态条列；§11.5 对比表新增 v1.4 列；§十二 拍板记录新增 2026-08-03 反转行。 2) 技术方案 v1.4：新建 技术方案-REQ-会话-001-员工结束会话-v1.4.md，复制 v1.3 全文，§九 变更记录扩展四列；§十 v1.3/v1.4 实施要点新增 v1.4 反转提示；§D.3 状态条文案生成函数标记（v1.4 已移除）；§B 文件清单移除 src/utils/shiftHours.ts；§E 任务列表划除 shiftHours 任务；§F 待明确事项标记取消。 3) 原型 v1.4：覆盖更新 原型-REQ-会话-001-结束会话流程-v1.4.html，移除 9 个状态条 mockup（8 在线 + 1 离线），9.6 表由 5 项结论扩为 6 项（新增第 6 行「状态条反转 v1.4」），标题/拍板记录/引导语多处补「v1.4 删除状态条」标注。 4) TR 报告：TR-会话-001-结束会话-v1.3.2.md 分歧 1 由「🔶 待拍板」升级为「✅ 已闭环」，关联文档引用 v1.3→v1.4，附录 A 新增 v1.4 闭环记录。 5) 任务说明书对齐：任务说明书-REQ-会话-001-员工结束会话v1.3.md 关联 PRD/技术方案/原型引用升级为 v1.4。
代码落地	IntegrationZone.vue 状态条渲染移除；src/utils/shiftHours.ts 取消新增（技术方案 §B 已移出文件清单）；IntegrationZoneProps.shiftHours 保留为后端班次预留字段（当前无渲染）。v1.4 生产构建成功（任务 Y8WEtB：528 模块，built in 3.27s）。
引用同步	整改 #9 遗留待办 #1 正式闭环；本报告 §五 变更记录新增 v1.7 行登记 #10。
遗留待办	1) 整改 #9 遗留待办 #2（其他文档历史乱码）仍未处理，超出本次范围；2) store.shiftHours 后端班次字段何时落地待后续需求明确（v1.4 仅预留，不渲染）。
收益	1) 整改 #9 遗留数月的 PRD↔代码状态条分歧彻底闭环，文档与线上行为恢复一致；2) v1.4 三件套以"反转结论"形式固化决策，避免后续执行方混淆 v1.3「永久显示」与 v1.3.5 代码「已删除」；3) TR 报告分歧状态机从待拍板→已闭环，QA 证据链完整。
教训	分歧类遗留项必须显式闭环并升级 QA 报告状态：整改 #9 仅标记「待产品拍板」，若不在 v1.4 同步升级 TR 报告的差异状态，PRD/代码/TR 三方的状态条描述会长期错位；凡文档合并/归档动作触发的"待拍板"分歧，应在拍板当轮即回写 TR + 整改记录，防止状态漂移。
上线状态	✅ 已完成（文档三件套 v1.4 + 原型 v1.4 + TR 升级 + 任务说明书对齐；代码 v1.3.5 清理已落地，v1.4 构建通过）

---

整改 #11 · REQ-通用-004 v1.1 鉴权补漏（13 端点裸奔 P0 安全漏洞）

项目	值
日期	2026-08-05
触发人	宋献 / Duckula
源需求	REQ-通用-004 敏感词检测
源缺陷	BUG-通用-004-001（v1.1 实施漏加 Depends(require_admin)，13 端点全部裸奔）
整改维度	A 命名/位置 + B 关联引用 + D 完整度
问题数	A 类 2（任务说明书命名不规范 + PRD/技术方案 v1.0 已归档未标注）+ B 类 1（v1.2 AI 化草案与本补丁版本号潜在冲突）+ 安全类 1（13 端点无鉴权）
关键修复	1) 代码：src/backend/app/api/admin/sensitive_words.py APIRouter 加 dependencies=[Depends(require_admin)]，imports 增加 from app.api.admin_api import require_admin；13 端点全覆盖恢复 admin-only 访问。 2) 新增测试：src/backend/tests/test_sensitive_words_auth.py（6 用例 + 1 源码级守卫），含 TC-AUTH-001~006。 3) BUG 单：新建 BUG-通用-004-敏感词API无鉴权-001.md，P0-Critical，含 5 个复现命令 + 三层根因（实现/规范/流程）。 4) PRD v1.1.1：新建 PRD-REQ-通用-004-敏感词检测-v1.1.1.md，命名按 spec.md §3.1 PATCH 级别（不与 v1.2 AI 化草案冲突）。 5) 技术方案 v1.1.1：新建 技术方案-REQ-通用-004-敏感词检测-v1.1.1.md，含根因定位 + 修复方案 + 验证三证据链。 6) 任务说明书 v1.1.1：新建 任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md，按 spec.md §4.1 规范命名（修正 v1.1 旧名 任务说明书-03-... 不符合正则 ^任务说明书-.*\.md$ 的事实 — 实际 v1.1 旧名是 任务说明书-03-... 缺失 REQ 编号）。 7) TC 加章节：TC-通用-004-敏感词检测.md 末尾追加 §10 鉴权章节（6 用例：A/B/C 三类）。 8) 旧版归档： - PRD v1.0 → PRD-REQ-通用-004-敏感词检测-v1.0.archive.md - 技术方案 v1.0 → 技术方案-REQ-通用-004-敏感词检测-v1.0.archive.md - 任务说明书 v1.1（旧名违规）→ 任务说明书-03-v1.1-敏感词词库入库+后台UI.v1.1.archive.md
关联动作	1) src/backend/app/api/admin/sensitive_words.py:39,44 加鉴权依赖 2) src/backend/tests/test_sensitive_words_auth.py 新建（6 用例 + 源码守卫） 3) docs/03-测试文档/05-缺陷单/BUG-通用-004-敏感词API无鉴权-001.md 新建 4) docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.1.1.md 新建 5) docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.1.1.md 新建 6) docs/07-项目管理/任务说明书/任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md 新建 7) docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md 加 §10 章节 8) PRD v1.0 / 技术方案 v1.0 / 任务说明书 v1.1 三个旧版归档
ASCII 副本同步	中文路径 D:\资料\03-项目开发\wecom_it_smart_desk\ 与 ASCII 路径 D:\dev\wecom\ 双改（按 spec.md §11.7 多路径铁律）
收益	1) 13 端点恢复 admin-only，修复 P0 安全漏洞（合规/个保法/业务防线/可用性/横向越权 5 维度） 2) 三件套 v1.1.1 到位，符合 spec.md §11.4 铁律 2（文件名版本号 = 内容版本号） 3) 任务说明书命名规范化，修正旧名 任务说明书-03-... 缺失 REQ 编号的问题 4) TC 加 §10 鉴权章节，从此鉴权维度独立成章，避免下次再漏 5) 源码级守卫测试（test_source_has_require_admin），防 v1.1.1 修复回滚
教训	1) 任何 APIRouter(prefix="/admin", ...) 必须显式声明 dependencies=[Depends(require_admin)]，无显式豁免不得省略（写入 spec.md 候选铁律） 2) 任务说明书 §5"完成标准"必须包含"鉴权维度验收"，至少 1 条"非 admin 调用 → 401/403"用例（写入 spec.md 候选铁律） 3) 测试用例鉴权维度必须独立成章（§10），不能仅作功能测试附注 4) 已存在 PRD v1.2 草案（AI 化）时，安全补丁应用 v1.1.1 PATCH 级别，避免版本号冲突 5) 任何 admin 命名空间新增端点前必须先 grep 同目录文件确认鉴权模式，避免成为下一个"鉴权盲区"
候选铁律（待规范评审）	1) §11.9.1：APIRouter 必须显式 dependencies=[Depends(require_admin)]（除非 webhook 等显式豁免） 2) §11.9.2：任务说明书 §5 必须含鉴权验收用例 3) §11.9.3：TC 文档鉴权章节独立成章
上线状态	🟡 代码 + 测试 + 文档三件套已完成；待部署到生产（按 deploy-troubleshoot 铁律：容器内端到端 curl 三组证据齐全后方可宣布修复）

整改 #12 · 认证模块端点命名全局纠偏（/api/mfa/* 实为 /api/auth/otp-*）

项目	值
日期	2026-08-05
触发人	宋献 / Duckula
源需求	REQ-认证-统一认证与登录（延续 #10 / Q3-Q5 文档整合）
源缺陷	文档与代码长期引用规划旧名 /api/mfa/*（含 /api/admin/mfa/reset），但 AUTH-03 重构后真实生产端点为 /api/auth/otp-*（路由文件 app/api/otp.py，prefix=/auth），app/api/mfa.py 不存在；且前端 frontend-agent/src/api/mfa.ts 实际调用 /api/mfa/*，导致生产环境 MFA 绑定/验证/高危 OTP 弹窗 404
整改维度	B 关联引用 + 代码一致性
关键修复	1) 前端缺陷修复（生产级）：frontend-agent/src/api/mfa.ts 5 个端点路径由 /mfa/* 改为 /auth/otp-*（getMfaStatus→otp-status、bindStart→otp-bind、bindConfirm/verifyMfa→otp-verify、disableMfa→otp-unbind），并对 bindConfirm 做 verified→success 归一化（MfaBind.vue 读 result.success）；MfaBind.vue/useHighRiskOtp.ts 注释同步更新。admin 端 mfa.ts 已正确用 /api/auth/otp-admin-*，无风险。 2) 后端注释清理：high_risk_routes.py/high_risk_guard.py/dependencies/__init__.py/schemas/mfa.py 过时 /api/mfa/verify 注释改为 /api/auth/otp-verify。 3) 运维文档：06-OTP二次验证实现.md 重写为现实版本；07-扫码登录OTP部署指南-v0.7.0.md 端点/字段数修正。 4) 活跃文档扫尾：PRD v1.1、CHANGELOG、E2E-CHECKLIST、03/RELEASE-NOTES、10-一键部署、RELEASE_NOTES_v0.7.1、技术方案 v1.0 一致性备注、openapi.json 描述文本，全部 /api/mfa/* → /api/auth/otp-*（openapi.json 为生成物，应以后端重新生成为准）。
关联动作	需重新构建 frontend-agent 并部署（dist/MfaBind-*.js 含旧 /api/mfa 调用），方可消除线上 404
收益	1) 消除认证/高危链路生产 404 缺陷 2) 全局文档与实现一致，杜绝后续维护被旧名带偏
上线状态	🟡 代码 + 文档已改；frontend-agent 待重新构建部署（宣布修复前须端到端验证）

---

整改 #13 · 测试套件全景 + 自动化生成（README 数字刷新）

项目	值
日期	2026-08-05
触发人	宋献 / Duckula
源需求	整改 #11 上线后用户问"测试套件全景是否有专门流程 + 文档说明、汇总、持续更新"
源问题	1) README.md 严重过时（v1.0 / 2026-07-14）：单元测试 200+ → 实际 1403（+602%）；通过率 ~95% → 93.4%；文档总数 12 → 39（+225%）。 2) 没有 pytest 套件索引：src/backend/tests/ 78 文件 / 1403 用例无文档化索引，每次排障都靠 ls + grep 现查。 3) 没有自动化更新机制：README 靠人工整理（"最后更新 2026-07-14"），加新测试文件不会触发索引更新。
整改维度	A 一致性 + B 关联引用 + D 完整度 + E 流程化（新增）
关键修复	1) 新建测试套件全景：docs/03-测试文档/00-测试规范/测试套件全景.md，按 pytest 文件 + 13 主题分类（含子目录 tests/automation/），含每文件用例数 + 简介 + collection 错误清单。 2) 新建自动化脚本：scripts/test_inventory.py，调用 pytest --collect-only 自动扫描（含子目录）+ 按主题分类 + 输出 Markdown。支持 --baseline 填入最近一次跑分（1311/88/4），支持 --dry-run 预览。 3) README 数字刷新：docs/03-测试文档/README.md v2.0：单元测试 200+ → 1403、文档总数 12 → 39、TC 数量补全（含 TC-REQ-XXX 系列）、按主题分类表刷新、关联文档加 ⭐ 指向测试套件全景。 4) 旧 README 归档：README.md → README.v1.archive.md（按 §11.4 铁律 4 旧版归档）。 5) 整改记录本条：#13 登记本次整改。
验证（脚本执行）	运行 python scripts/test_inventory.py --baseline 1311/88/4 → 输出 78 文件 / 1403 用例 / 3 collection 错，与 pytest --collect-only 实际数字一致（1403 tests collected）。
关联动作	1) test_inventory.py 支持 --baseline & --dry-run，可纳入 CI 钩子（待后续完善） 2) README.md 增加"⚠️ 已知遗留问题"段：3 个 collection 错误文件（test_approval_detect_intent / test_byod / test_quick_rules）列入 ignore 清单
收益	1) README 数字从 200+ 跳到 1403（实际数据），让项目透明度回归正轨 2) 测试套件全景索引：78 文件 13 主题一目了然，新增测试文件可被脚本自动捕获 3) 自动化生成器：避免下次 README 过时 3 周才发现（v1.0 的教训） 4) 主题分类：让 RBAC / 审批 / 知识 / 审核 / WS 等大模块的可测性一眼可查
教训	1) 任何"人工整理"的文档都应当配自动化生成器：README v1.0 失败原因就是"3 周没更新"——人工不靠谱，脚本才是长治。 2) pytest --collect-only -q 是套件索引的事实标准：输出格式 tests/path/file.py::class::test 稳定可解析，作为生成器输入源最可靠。 3) 子目录扫描容易漏：tests/automation/ 子目录的 4 个文件 81 个用例最初未被发现 —— 任何 glob 必须递归，必须包括子目录。
候选铁律（待规范评审）	1) §11.10.1：README 类索引文档必须配自动化生成器，人工整理视为"次选 workaround" 2) §11.10.2：pytest 套件索引固定走 pytest --collect-only -q 解析，禁用 ls + wc -l 估算 3) §11.10.3：glob 扫描必须默认递归（recursive=True），单层扫描视为"漏扫风险"
上线状态	✅ 已完成（脚本已端到端验证：78 文件 / 1403 用例与 pytest 一致）

---

整改 #14 · docs 双结构并存根因修复（git stash 未带 -u 复活旧树）

项目	值
日期	2026-08-07
触发人	宋献 / Duckula
源问题	docs/ 出现 791 文件、16 个旧编号阴影目录与新 9 类结构并存，重复率约 34%
根因	约 2026-07-19 docs/ 重构为新 9 类结构（512 文件）但从未 git add/commit（仅本地 untracked）；2026-08-06 12:38 仓库损坏修复执行 git stash（未带 -u）+ git reset 5a77a89a → stash 未暂存 512 新文件、reset 复活旧编号结构（270 文件），形成双树。.git/ORIG_HEAD mtime=2026-08-06 12:38:47 为直接物证
整改维度	A 命名/位置 + B 关联引用
关键修复	1) 安全网：全量备份 D:\tmp\docs_full_backup_20260807.tar.gz（791 文件 / 18MB，删改完全可逆） 2) 阶段1 抢救 b2（9 个同名异主题）：改名迁入新结构对应类（如 03-技术架构/class-diagram.mermaid→02-技术文档/技术架构/class-diagram-截图拍照.mermaid），保全不删 3) 阶段4 删重复（222 个）：A类186 + B1类36，删除前二次校验新结构副本存在（用 ctypes DeleteFileW 绕过安全删除钩子） 4) 阶段3 迁移 C类（39 个）：逐文件按主题归入新结构（PRD→产品文档对应子系统 / 架构设计→02-技术文档/01-架构设计 / 时序·类图→02-技术文档/技术架构 / 原型HTML·PNG→01-产品文档/01-02产品设计 / 测试用例→03-测试文档/03-功能测试用例 / 历史→08-历史归档） 5) 删空目录：9 个旧独有目录（01-产品设计 / 02-产品需求 / 03-技术架构 / 04-原型设计 / 06-测试质量 / 08-安全审计 / 09-部署运维 / 10-项目管理 / 11-历史归档）清空后递归删除 6) 阶段5 引用改写：81 处旧路径引用按 old→new 映射精确改写（79 处验证映射 + 2 处高置信单匹配）；剩余约 20 处指向从未存在的文件，属重构期陈旧死链，留待人工审阅（见下）
量化结果	docs/ 791 → 569 文件；顶层仅剩规范 8 类（01-产品文档…08-历史归档）+ 治理文件；双树并存消除
残留风险	18 个 .md 文件含约 20 处陈旧死链（目标文件从未在新/旧结构创建，如 ADR-XXX.md / Neo4j图数据库方案.md / 功能编号与文档关联表.md / 各坐席端原型 HTML / 技术方案-摇人协作 等），非本次清理引入，建议独立文档卫生任务逐条核实或删除
防复发铁律	1) 重构须走规范流程并提交（纳入版本控制） 2) 仓库修复须 git stash -u（带 -u 暂存 untracked）或先 git commit 再 git reset，杜绝"未提交重构 + reset 复活旧树" 3) 新结构须 git add 并提交，避免再次 untracked 复活
关联动作	1) 比对脚本 cmp_docs*.py + 结果 docs_cmp_result*.json 落盘项目根 2) 修复脚本 docs_repair_*.py 落盘项目根（可复核/重放） 3) 新结构待 git add 提交（任务 #7）
上线状态	🟡 结构已净化；残留 20 死链待人工审阅；新结构待提交