Simon
44e77dcb0e
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
250 lines
24 KiB
Markdown
250 lines
24 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 待开发启动）|
|
||
|
||
---
|
||
|
||
## 三、规范检查清单（模板）
|
||
|
||
> 下次新增/修改任何文档前，对照检查 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 §⑨） |
|