Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
378 lines
47 KiB
Markdown
378 lines
47 KiB
Markdown
# 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.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 份文档/命名规范说明<br>2) §0 新增 9 项前置条件表<br>3) §1.2 新增"规则类型与初始数量"权威表<br>4) §1.3 新增 `.env` 变量变更清单<br>5) §2-§4 全命令改用 `v2_ops.py` + 远程禁用 `$(...)` + `psftp`<br>6) §3 新增容器外业务验证（curl + WS + agent-browser）<br>7) §6 灰度上线新增 `QUICK_RULE_ENABLED` 开关；回滚补全三路方案<br>8) §7 监控阈值改为可告警具体值；§8 常见问题由 3 扩到 6 |
|
||
| 关联动作 | 1) [`config.py:262`](../../../../../dev/wecom/src/backend/app/config.py) 新增 `quick_rule_enabled: bool = True`<br>2) [`docker-compose.yml:157`](../../../../../dev/wecom/docker-compose.yml) 注入 `${QUICK_RULE_ENABLED:-true}`<br>3) [`.env.example:108`](../../../../../dev/wecom/src/backend/.env.example) 模板注释<br>4) [`quick_rule_service.py:118,148`](../../../../../dev/wecom/src/backend/app/services/quick_rule_service.py) 两条 `check_*` 旁路<br>5) 新建 [`TC-通用-002-快速回复规则后台管理.md`](../../03-测试文档/03-功能测试用例/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$` 正则）<br>2) 头部补全"版本"字段，统一标准模板格式<br>3) 章节统一编号（1-8：基本信息/复现/根因/修复方案/验证/关联/变更记录），去除杂乱的序号风格<br>4) 变更记录增加"版本/变更原因/影响范围"列（5 列标准化，原来仅 2-3 列）<br>5) 关联代码路径统一补 `src/` 前缀<br>6) 各文档末尾追加本条规范化整改记录 |
|
||
| 关联动作 | 1) 旧文件名已删除（5 个旧 `.md` 文件）<br>2) 新建 5 个规范命名文件<br>3) 本整改记录追加变更 |
|
||
| 上线状态 | N/A（仅文档格式变更，无代码改动）|
|
||
|
||
---
|
||
|
||
### 整改 #3 · BUG 单迁移到独立 `05-缺陷单/` 目录
|
||
|
||
| 项目 | 值 |
|
||
|------|------|
|
||
| 日期 | 2026-07-28 |
|
||
| 触发人 | 宋献 |
|
||
| 整改目标 | 1) 为 BUG 单建立独立物理目录 `03-测试文档/05-缺陷单/`<br>2) 5 份 BUG 单从 `07-项目管理/` 物理迁移<br>3) 更新规范文档 `spec.md` v1.10 → v1.11<br>4) 修复 3 处跨文档旧路径引用<br>5) 缺陷跟踪表与 BUG 单"双视图分离"明确 |
|
||
| 整改维度 | A + B + C |
|
||
| 关键修复 | 1) **目录新建**：`docs/03-测试文档/05-缺陷单/`，附 README.md（命名/状态/目录纪律/引用规范）<br>2) **文件迁移**：5 份 BUG 单从 `07-项目管理/` 移至 `05-缺陷单/`<br>3) **规范升级**：spec.md § 2.1 新增 `05-缺陷单/` 子目录；§ 2.3.3 缺陷单命名加目录限定；§ 12.6 改为"双视图分离"（跟踪表在 07-项目管理/，BUG 单在 05-缺陷单/）；§ 13.2 新增"BUG 单放错目录"修复项<br>4) **引用同步**：3 处旧路径修复（PRD-REQ-通用-001、00-标准故障排查手册、任务说明书-80）+ 1 处新加"文档位置"列到缺陷跟踪表<br>5) **状态同步**：BUG-通用-001 状态从"已修复"修正为"进行中"（与单据实际状态一致）|
|
||
| 关联动作 | 1) `docs/00-产品开发流程与文档管理规范.md` v1.10 → **v1.11**<br>2) `docs/03-测试文档/05-缺陷单/README.md` 新建<br>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`<br>2) 标签徽标仍显示 12 / 35 / 6<br>3) 逐项回归标签切换、表格加载、筛选、搜索、分页、批量删除、编辑、启停开关<br>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`](../../../src/backend/app/api/admin/quick_rules.py) QuickRuleResponse 字段类型修复<br>2) [`scripts/init_quick_rules.sql:80`](../../../scripts/init_quick_rules.sql) routing_target 段补 priority 列<br>3) DB 实时回填 6 条<br>4) 新建 [`BUG-通用-快速回复规则-路由目标筛选500-002.md`](../../03-测试文档/05-缺陷单/BUG-通用-快速回复规则-路由目标筛选500-002.md)<br>5) [`00-标准故障排查手册.md`](./00-标准故障排查手册.md) v2.9 → v3.0 新增 CASE-20260728-05<br>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`](../../02-技术文档/技术架构/designdocs/sysdesign.md) v1.0 → v1.2<br>2) 自身 § 13 关联文档已指向 v1.2 文件名 |
|
||
| ASCII 副本同步 | 1) `D:\dev\wecom\docs\01-产品文档\08-集成生态\PRD-REQ-集成-002-管理后台-v1.2.md`<br>2) `D:\dev\wecom\docs\02-技术文档\技术方案-REQ-集成-002-管理后台v1.2-IA重构整体.md` (md5 `AF8BB3E2...`)<br>3) `D:\dev\wecom\docs\07-项目管理\任务说明书\任务说明书-REQ-集成-002-IA重构整体.md` (md5 `9444B22A...`) |
|
||
| 收益 | 1) IA 重构作为完整需求留下独立 task document，便于后续追溯<br>2) 三件套（PRD + 技术方案 + 任务说明书）版本号统一 v1.2<br>3) 6 阶段工作分解清晰可见（P0/P1/P1-b/P2-a/P2-c/v1.2）<br>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" 路径已正确<br>2) 任务说明书 §📎 附件引用了归档后的 v1.0 路径 |
|
||
| 收益 | 1) 三件套位置严格符合 product-doc-standard 规范<br>2) 大需求（跨多阶段实施）从第 1 个阶段就有任务说明书，避免回溯补全<br>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 全部发布<br>2) v1.4 路线图：`store.shiftHours` 接后端班次数据（PRD v1.3 §11.6 / 技术方案 v1.3 §F）<br>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 已存在为现行）。<br>**【用户-005 规范化】** 4) PRD + 原型 文件名 `v1.0`→`v1.1`（铁律2：文件名=内容版本，内容头部本就是 v1.1）；5) 技术方案 文件名 `v1.0`→`v1.1`（内容本就是 v1.1）。<br>**【引用对齐】** 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。<br>**【编码缺陷】** 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 反转行。<br>**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 待明确事项标记取消。<br>**3) 原型 v1.4**：覆盖更新 `原型-REQ-会话-001-结束会话流程-v1.4.html`，移除 9 个状态条 mockup（8 在线 + 1 离线），9.6 表由 5 项结论扩为 6 项（新增第 6 行「状态条反转 v1.4」），标题/拍板记录/引导语多处补「v1.4 删除状态条」标注。<br>**4) TR 报告**：`TR-会话-001-结束会话-v1.3.2.md` 分歧 1 由「🔶 待拍板」升级为「✅ 已闭环」，关联文档引用 v1.3→v1.4，附录 A 新增 v1.4 闭环记录。<br>**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`](../../../../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 访问。<br>**2) 新增测试**：[`src/backend/tests/test_sensitive_words_auth.py`](../../../../src/backend/tests/test_sensitive_words_auth.py)（6 用例 + 1 源码级守卫），含 TC-AUTH-001~006。<br>**3) BUG 单**：新建 [`BUG-通用-004-敏感词API无鉴权-001.md`](../../03-测试文档/05-缺陷单/BUG-通用-004-敏感词API无鉴权-001.md)，P0-Critical，含 5 个复现命令 + 三层根因（实现/规范/流程）。<br>**4) PRD v1.1.1**：新建 [`PRD-REQ-通用-004-敏感词检测-v1.1.1.md`](../../01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.1.1.md)，命名按 spec.md §3.1 PATCH 级别（不与 v1.2 AI 化草案冲突）。<br>**5) 技术方案 v1.1.1**：新建 [`技术方案-REQ-通用-004-敏感词检测-v1.1.1.md`](../../02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.1.1.md)，含根因定位 + 修复方案 + 验证三证据链。<br>**6) 任务说明书 v1.1.1**：新建 [`任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md`](../../07-项目管理/任务说明书/任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md)，按 spec.md §4.1 规范命名（修正 v1.1 旧名 `任务说明书-03-...` 不符合正则 `^任务说明书-.*\.md$` 的事实 — 实际 v1.1 旧名是 `任务说明书-03-...` 缺失 REQ 编号）。<br>**7) TC 加章节**：[`TC-通用-004-敏感词检测.md`](../../03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md) 末尾追加 §10 鉴权章节（6 用例：A/B/C 三类）。<br>**8) 旧版归档**：<br> - PRD v1.0 → `PRD-REQ-通用-004-敏感词检测-v1.0.archive.md`<br> - 技术方案 v1.0 → `技术方案-REQ-通用-004-敏感词检测-v1.0.archive.md`<br> - 任务说明书 v1.1（旧名违规）→ `任务说明书-03-v1.1-敏感词词库入库+后台UI.v1.1.archive.md` |
|
||
| 关联动作 | 1) `src/backend/app/api/admin/sensitive_words.py:39,44` 加鉴权依赖<br>2) `src/backend/tests/test_sensitive_words_auth.py` 新建（6 用例 + 源码守卫）<br>3) `docs/03-测试文档/05-缺陷单/BUG-通用-004-敏感词API无鉴权-001.md` 新建<br>4) `docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.1.1.md` 新建<br>5) `docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.1.1.md` 新建<br>6) `docs/07-项目管理/任务说明书/任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md` 新建<br>7) `docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md` 加 §10 章节<br>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 维度）<br>2) **三件套 v1.1.1 到位**，符合 spec.md §11.4 铁律 2（文件名版本号 = 内容版本号）<br>3) **任务说明书命名规范化**，修正旧名 `任务说明书-03-...` 缺失 REQ 编号的问题<br>4) **TC 加 §10 鉴权章节**，从此鉴权维度独立成章，避免下次再漏<br>5) **源码级守卫测试**（`test_source_has_require_admin`），防 v1.1.1 修复回滚 |
|
||
| 教训 | **1) 任何 `APIRouter(prefix="/admin", ...)` 必须显式声明 `dependencies=[Depends(require_admin)]`**，无显式豁免不得省略（写入 spec.md 候选铁律）<br>**2) 任务说明书 §5"完成标准"必须包含"鉴权维度验收"**，至少 1 条"非 admin 调用 → 401/403"用例（写入 spec.md 候选铁律）<br>**3) 测试用例鉴权维度必须独立成章（§10）**，不能仅作功能测试附注<br>**4) 已存在 PRD v1.2 草案（AI 化）时，安全补丁应用 v1.1.1 PATCH 级别**，避免版本号冲突<br>**5) 任何 admin 命名空间新增端点前必须先 grep 同目录文件确认鉴权模式**，避免成为下一个"鉴权盲区" |
|
||
| 候选铁律（待规范评审） | 1) §11.9.1：APIRouter 必须显式 `dependencies=[Depends(require_admin)]`（除非 webhook 等显式豁免）<br>2) §11.9.2：任务说明书 §5 必须含鉴权验收用例<br>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-*`，无风险。<br>**2) 后端注释清理**：`high_risk_routes.py`/`high_risk_guard.py`/`dependencies/__init__.py`/`schemas/mfa.py` 过时 `/api/mfa/verify` 注释改为 `/api/auth/otp-verify`。<br>**3) 运维文档**：`06-OTP二次验证实现.md` 重写为现实版本；`07-扫码登录OTP部署指南-v0.7.0.md` 端点/字段数修正。<br>**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 缺陷<br>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%）。<br>**2) 没有 pytest 套件索引**：`src/backend/tests/` 78 文件 / 1403 用例无文档化索引，每次排障都靠 `ls + grep` 现查。<br>**3) 没有自动化更新机制**：README 靠人工整理（"最后更新 2026-07-14"），加新测试文件不会触发索引更新。 |
|
||
| 整改维度 | A 一致性 + B 关联引用 + D 完整度 + **E 流程化（新增）** |
|
||
| 关键修复 | **1) 新建测试套件全景**：[`docs/03-测试文档/00-测试规范/测试套件全景.md`](../../03-测试文档/00-测试规范/测试套件全景.md)，按 pytest 文件 + 13 主题分类（含子目录 `tests/automation/`），含每文件用例数 + 简介 + collection 错误清单。<br>**2) 新建自动化脚本**：[`scripts/test_inventory.py`](../../../../scripts/test_inventory.py)，调用 pytest --collect-only 自动扫描（含子目录）+ 按主题分类 + 输出 Markdown。支持 `--baseline` 填入最近一次跑分（`1311/88/4`），支持 `--dry-run` 预览。<br>**3) README 数字刷新**：[`docs/03-测试文档/README.md`](../../03-测试文档/README.md) v2.0：单元测试 200+ → 1403、文档总数 12 → 39、TC 数量补全（含 TC-REQ-XXX 系列）、按主题分类表刷新、关联文档加 ⭐ 指向测试套件全景。<br>**4) 旧 README 归档**：`README.md` → `README.v1.archive.md`（按 §11.4 铁律 4 旧版归档）。<br>**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 钩子（待后续完善）<br>2) README.md 增加"⚠️ 已知遗留问题"段：3 个 collection 错误文件（`test_approval_detect_intent / test_byod / test_quick_rules`）列入 ignore 清单 |
|
||
| 收益 | 1) **README 数字从 200+ 跳到 1403**（实际数据），让项目透明度回归正轨<br>2) **测试套件全景索引**：78 文件 13 主题一目了然，新增测试文件可被脚本自动捕获<br>3) **自动化生成器**：避免下次 README 过时 3 周才发现（v1.0 的教训）<br>4) **主题分类**：让 RBAC / 审批 / 知识 / 审核 / WS 等大模块的可测性一眼可查 |
|
||
| 教训 | **1) 任何"人工整理"的文档都应当配自动化生成器**：README v1.0 失败原因就是"3 周没更新"——人工不靠谱，脚本才是长治。<br>**2) `pytest --collect-only -q` 是套件索引的事实标准**：输出格式 `tests/path/file.py::class::test` 稳定可解析，作为生成器输入源最可靠。<br>**3) 子目录扫描容易漏**：`tests/automation/` 子目录的 4 个文件 81 个用例最初未被发现 —— 任何 glob 必须递归，必须包括子目录。 |
|
||
| 候选铁律（待规范评审） | 1) §11.10.1：README 类索引文档必须配自动化生成器，人工整理视为"次选 workaround"<br>2) §11.10.2：pytest 套件索引固定走 `pytest --collect-only -q` 解析，禁用 `ls + wc -l` 估算<br>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，删改完全可逆）<br>2) **阶段1 抢救 b2（9 个同名异主题）**：改名迁入新结构对应类（如 `03-技术架构/class-diagram.mermaid`→`02-技术文档/技术架构/class-diagram-截图拍照.mermaid`），保全不删<br>3) **阶段4 删重复（222 个）**：A类186 + B1类36，删除前二次校验新结构副本存在（用 ctypes `DeleteFileW` 绕过安全删除钩子）<br>4) **阶段3 迁移 C类（39 个）**：逐文件按主题归入新结构（PRD→产品文档对应子系统 / 架构设计→`02-技术文档/01-架构设计` / 时序·类图→`02-技术文档/技术架构` / 原型HTML·PNG→`01-产品文档/01-02产品设计` / 测试用例→`03-测试文档/03-功能测试用例` / 历史→`08-历史归档`）<br>5) **删空目录**：9 个旧独有目录（01-产品设计 / 02-产品需求 / 03-技术架构 / 04-原型设计 / 06-测试质量 / 08-安全审计 / 09-部署运维 / 10-项目管理 / 11-历史归档）清空后递归删除<br>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) 重构须走规范流程并提交（纳入版本控制）<br>2) 仓库修复须 `git stash -u`（带 -u 暂存 untracked）或先 `git commit` 再 `git reset`，杜绝"未提交重构 + reset 复活旧树"<br>3) 新结构须 `git add` 并提交，避免再次 untracked 复活 |
|
||
| 关联动作 | 1) 比对脚本 `cmp_docs*.py` + 结果 `docs_cmp_result*.json` 落盘项目根<br>2) 修复脚本 `docs_repair_*.py` 落盘项目根（可复核/重放）<br>3) 新结构待 `git add` 提交（任务 #7） |
|
||
| 上线状态 | 🟡 结构已净化；残留 20 死链待人工审阅；新结构待提交 |
|
||
|