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 待开发启动）

---

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

下次新增/修改任何文档前，对照检查 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 构建通过）