wecom_it_smart_desk/docs/00-产品开发流程与文档管理规范.md

IT智能服务台 - 产品开发流程与文档管理规范

版本: v1.13 日期: 2026-08-03 状态: [已评审] 作者: Simon 变更说明:

• v1.11 → v1.12：新增 §14 大需求重构的文档化策略（2026-07-28 管理后台 IA 重构经验）
• v1.12 → v1.13：新增 §16 技术方案偏离时的"增量更新章节"治理（基于 2026-08-03 voice_asr.py P0 安全巡检 + 文档-代码不一致修复经验），涵盖：① §16.1 技术方案与实际部署偏离的场景识别；② §16.2 §10 增量更新章节模板；③ §16.3 多策略功能（如语音输入的"手机 JS-SDK / PC 百度 ASR / Web Speech"三分支）的文档化要求；④ §16.4 API 端点调用方分析强制检查项；⑤ §16.5 运营/配置/运维文档与代码一致性核查清单模板

---

一、流程定义

1.1 阶段划分

┌────────────────────────────────────────────────────────────────────────────┐
│                      产品开发标准流程（需求→设计→技术→测试→运维→运营）       │
├────────────────────────────────────────────────────────────────────────────┤
│  【阶段1】  【阶段2】  【阶段3】  【阶段4】    【阶段5】    【阶段6】        │
│   需求定义   设计验证   技术实现   测试验证     运维运营     运营分析        │
│  ────────   ────────   ────────   ────────    ────────    ────────        │
│  业务问题    低保真原型  技术方案    测试用例     部署方案     运营报告        │
│  竞品分析    高保真原型  接口设计    功能测试     监控告警     采用率分析      │
│  可行性评估   交互验证   数据库设计   回归测试     运维手册     用户反馈        │
│  PRD撰写     用户测试    详细设计    性能/安全测试 数据看板     推广复盘        │
│  需求评审     设计评审   技术评审    测试报告     故障排查     KPI回流需求     │
│                                                                    │
│       │          │          │          │            │            │           │
│       ▼          ▼          ▼          ▼            ▼            ▼           │
│   产出:PRD   产出:原型图  产出:技术   产出:测试    产出:运维    产出:运营报告  │
│                         文档        报告+缺陷单   文档                        │
└────────────────────────────────────────────────────────────────────────────┘

1.2 阶段依赖

阶段	前置条件	可并行	产出
阶段1 需求定义	业务目标	竞品分析	PRD
阶段2 设计验证	需求确认	技术预研	原型图
阶段3 技术实现	设计确认	-	技术方案
阶段4 测试验证	开发完成提测	性能压测预排	测试用例、测试报告、缺陷单
阶段5 运维运营	测试通过、上线审批	监控看板预配置	部署方案、运维手册、故障排查
阶段6 运营分析	上线运行一段时间	-	运营报告、采用率、用户反馈、KPI

1.3 各环节的关键定位

环节	不是什么	是什么
测试验证	开发的附属、上线前的"过场"	质量闸门——未通过验收标准不得上线
运维运营	上线后的"甩锅环节"	稳定保障——部署/监控/手册三件套齐备方可发布
运营分析	可有可无的"报表"	价值闭环——验证需求是否达成业务目标，KPI 回流需求

核心逻辑：需求定义"做什么"→设计验证"长什么样"→技术实现"怎么造"→测试验证"造得对不对"→运维运营"稳不稳"→运营分析"用得好不好"。测试是质量的守门员，运维是稳定的保障者，运营是价值的验收员，三者都向前回溯（缺陷回到开发，指标回到需求）。

---

二、文档目录结构

2.0 项目根目录结构（代码与配置）

基于 2026-07-27 整理实践

wecom_it_smart_desk/                    # 项目根目录
├── src/                                 # 源代码（统一管理）
│   ├── backend/                         # Python FastAPI 后端
│   ├── frontend-agent/                  # 坐席工作台前端 (Vue3 + TS)
│   ├── frontend-h5/                    # H5 员工端前端
│   ├── frontend-admin/                   # 管理后台前端
│   └── frontend-terminal/               # 终端管理前端
│
├── configs/                            # 配置文件
│   ├── .env                           # 主环境配置
│   ├── .env.example                   # 环境配置模板
│   ├── .env.production                # 生产环境配置
│   ├── .env.nas                      # NAS 配置
│   └── .dockerignore
│
├── packages/                           # 当前部署包（最新版本）
│   ├── h5_dist.tar.gz                # H5 部署包
│   ├── frontend-agent-dist.tar.gz       # 坐席端部署包
│   └── frontend-admin-dist.zip        # 管理端部署包
│
├── archives/                          # 历史归档（无活跃引用）
│   ├── h5-dist-v*.tar.gz            # 旧版本前端
│   ├── agent-dist-v*.tar.gz          # 旧版本坐席端
│   └── backend-*.tar.gz              # 旧版本后端
│
├── scripts/                           # 脚本工具
│   ├── deploy/                       # 部署脚本
│   ├── debug/                        # 调试/测试脚本
│   └── fix/                         # 修复脚本
│
├── docs/                              # 项目文档（按本规范管理）
├── tools/                             # 辅助工具
├── nginx/                             # Nginx 配置
├── ops-tools/                         # 运维工具
│
├── docker-compose.yml                 # Docker 配置（生产）
└── docker-compose.dev.yml            # Docker 配置（开发）

2.0.1 目录整理规则

类别	存放位置	说明
源代码	src/	后端+前端统一管理
配置文件	configs/	环境变量、Docker配置
当前部署包	packages/	正在使用的部署包
历史归档	archives/	旧版本、临时文件
部署脚本	scripts/deploy/	部署相关脚本
调试脚本	scripts/debug/	测试、调试脚本
修复脚本	scripts/fix/	问题修复脚本
项目文档	docs/	按本规范管理

2.0.2 部署配置路径更新

重要：目录结构变更后，部署配置需同步更新：

配置文件	需要更新的路径
docker-compose.yml	context: ./src/backend
docker-compose.yml	volumes: ./src/backend/app:/app/app
docker-compose.yml	volumes: ./src/frontend-*/dist:...

2.1 标准结构（9 类 + 根治理文件）

docs/
├── 00-产品开发流程与文档管理规范.md     ← 本规范（治理文件，置顶）
├── 00-版本迭代总览.md                   ← 全局版本索引（治理文件，置顶）
│
├── 01-产品文档/
│   ├── 01-认证与登录/       (PRD+原型: 企微登录、OTP、SSO)
│   ├── 02-会话管理/         (PRD+原型: 消息、暂停恢复、存档)
│   ├── 03-AI服务/          (PRD+原型: 意图识别、路由、对话)
│   ├── 04-坐席工作台/       (PRD+原型: 消息框、截图、布局)
│   ├── 05-用户端H5/        (PRD+原型: H5界面、群聊、邀请)
│   ├── 06-审批与待办/       (PRD+原型: 审批流、代办)
│   ├── 07-知识库/           (PRD+原型: RAG、知识迭代)
│   └── 08-集成生态/         (PRD+原型: 第三方集成)
│
├── 02-技术文档/
│   ├── 技术架构/            (系统架构设计、类图/时序图、架构图)
│   ├── 实现配置/            (Dify Prompt、实施计划、审批模板等)
│   └── 重构记录/            (按版本拆分的重构方案，原 02-技术文档/重构记录)
│
├── 03-测试文档/
│   ├── 00-测试规范/
│   ├── 01-综合报告/
│   ├── 02-E2E测试/
│   ├── 03-功能测试用例/
│   ├── 04-版本测试报告/
│   └── 05-缺陷单/             (BUG 单独立落点：BUG-{模块}-{描述}-{序号}.md)
│
├── 04-运维文档/
│   ├── 运维指南/            (运维手册、故障排查)
│   └── 部署运维/            (部署指南、nginx配置、运维工具 toolbox、发布说明)
│
├── 05-运营文档/
│   ├── 用户手册/            (坐席/员工操作手册——运营过程中的物料)
│   └── 运营报告/            (运营周/月报、功能采用率、用户反馈、推广效果)
│
├── 06-安全审计/            (安全审计报告、漏洞扫描、CORS/CSP、集成安全分析)
│
├── 07-项目管理/            (任务说明书、SOP、状态看板、日报)
│
└── 08-历史归档/            (仅保留历史留痕、无活跃引用的文档)

2.2 类别边界规则（避免错放）

类别	包含	不包含（应放别处）
01-产品文档	PRD、原型图、设计说明（按子系统合并：PRD+原型放同一目录）	操作手册→05；技术方案→02
02-技术文档	架构设计、接口/DB设计、Prompt配置、实施计划、重构方案	部署手册→04；测试用例→03
03-测试文档	测试规范、用例、报告、缺陷	开发自测记录→02
04-运维文档	部署、监控、故障排查、运维SOP	业务运营报告→05
05-运营文档	用户手册、运营报告	技术运维→04
06-安全审计	安全审计、漏洞、合规	一般运维→04
07-项目管理	任务说明书、迭代、会议、看板	PRD→01
08-历史归档	仅历史留痕	仍被引用的→提升回主文档

2.3 命名规则

2.3.1 产品文档（01-产品文档）

文档类型	命名格式	示例
PRD	PRD-REQ-[需求编号]-[功能名]-v[版本号].md	PRD-REQ-会话-001-暂停恢复-v1.1.md
原型图	原型-REQ-[需求编号]-[功能名]-v[版本号].html	原型-REQ-会话-001-暂停恢复-v1.1.html

2.3.2 技术文档（02-技术文档）

文档类型	命名格式	示例	关联
技术方案	技术方案-REQ-[需求编号]-[功能名]-v[版本号].md	技术方案-REQ-会话-001-暂停恢复-v1.0.md	关联 PRD
架构设计	架构设计-[功能名].md	架构设计-知识库迭代.md	可关联 REQ
接口设计	API-[功能名].md	API-会话管理.md	可关联 REQ
数据模型	数据模型-[功能名].md	数据模型-知识库.md	可关联 REQ
前端设计	前端设计-[功能名].md	前端设计-知识库迭代.md	可关联 REQ
Dify DSL备份	{应用标识}_{版本/日期}_{操作类型}.yml	itdesk_main_2026-7-24_102740.yml	关联 Dify 应用

2.3.2.1 Dify DSL 备份文件命名规范

适用范围：Dify 应用的 DSL（Domain Specific Language）导出文件备份

应用	应用标识	示例
主应用（智能IT支持-员工咨询）	itdesk_main	itdesk_main_2026-7-24_102740.yml
分诊应用	triage	triage_2026-7-20_v1.yml
审批意图应用	approval_intent	approval_intent_2026-7-18.yml

保存位置：02-技术文档/实现配置/dify_dsl/

2.3.3 其他文档

文档类型	命名格式	示例
需求变更	变更-功能名-日期.md	变更-暂停恢复-20260719.md
测试用例	TC-功能名.md	TC-暂停恢复.md
测试报告	TR-功能名-版本.md	TR-暂停恢复-v1.1.md
缺陷单	BUG-{模块}-{描述}-{序号}.md（目录：03-测试文档/05-缺陷单/）	03-测试文档/05-缺陷单/BUG-AI-打印机安装路由错误-001.md
部署方案	DEPLOY-功能名.md	DEPLOY-暂停恢复.md
监控告警	MON-功能名.md	MON-暂停恢复.md
运维手册	OPS-功能名.md	OPS-暂停恢复.md
用户手册	手册-角色.md	手册-坐席端.md
运营报告	运营报告-周期.md	运营报告-2026Q3.md
安全审计	SEC-主题-日期.md	SEC-前端审计-20260615.md
任务说明书	任务说明书-编号-主题.md	任务说明书-78-审批流程.md
版本总览	00-版本迭代总览.md	-

命名规则说明：

• 产品文档必须关联 REQ 编号（PRD、原型）
• 技术文档建议关联 REQ 编号（技术方案必须关联，其他可选）
• 存量文件允许保留原名（避免破坏内部引用），新文档按上表命名
• 重命名需同步修正引用

2.4 重构记录拆分规则

原 02-技术文档/重构记录 不再单列。按版本迭代内容拆分：

• 架构/技术方案部分 → 02-技术文档/技术架构 或 02-技术文档/重构记录
• 需求/PRD 部分 → 并入对应 01-产品文档/子系统 的 PRD 版本历史
• 全局版本索引 → 00-版本迭代总览.md

2.5 历史归档分拣规则

08-历史归档 仅保留无活跃引用的历史留痕。新文档归档前必须分拣：

• 仍被主文档引用（规范/PRD/技术方案引用了该文件）→ 提升回对应主文档（附录或引用）
• 仅历史留痕、无活跃引用 → 留在归档
• 归档文件命名保留 -archived-日期 后缀以便追溯

---

三、版本管理

3.1 版本号规则

 PRD-功能名-MAJOR.MINOR.PATCH
                     │    │    │
                     │    │    └─ Patch: 错别字修正、格式调整
                     │    │
                     │    └──── Minor: 新增非核心功能、UI调整
                     │
                     └────── Major: 核心功能变更、架构调整

3.2 文档状态

状态	标记	说明
草稿	[草稿]	正在编写中
待评审	[待评审]	等待评审
已评审	[已评审]	评审通过
已废弃	[已废弃]	已不推荐使用

---

四、变更管理

4.1 变更流程

需求变更
    │
    ▼
评估影响范围 ━━━━━━━━━━┓
    │                        │
    ▼                        ▼
 小变更              大变更（架构/核心）
    │                        │
    ▼                        ▼
更新PRD版本号           重新评审
+ 变更记录              + 重新设计
+ 通知相关人             + 技术方案更新

4.2 变更记录模板

## 变更记录

| 日期 | 变更人 | 变更内容 | 变更原因 | 影响范围 |
|------|---------|----------|----------|----------|
| 2026-07-19 | Simon | 新增版本回滚功能 | 用户反馈需要 | 需更新技术方案 |

4.3 文档更新时机

场景	需要更新的文档
新增功能（涉及UI）	PRD + 原型图 + 技术方案 + 测试用例
新增功能（纯接口）	PRD + 技术方案 + 测试用例
功能调整	PRD(版本号) + 变更记录 + 原型图（视情况）+ 测试用例
UI优化	原型图
技术优化	技术方案
需求变更	PRD(版本号) + 变更记录 + 回归测试用例
提测	测试用例定稿 + 测试报告初版
发现缺陷	缺陷单 + 回归用例（修复后）
上线	部署方案 + 监控告警 + 运维手册
线上故障	缺陷单 + 运维手册（排查SOP补充）
运营复盘	运营报告 + 监控结论回流至 PRD 指标章节
归档	按 2.5 分拣：提升回主文档 或 留 08-历史归档

4.4 原型图必要性判断

需求类型	是否需要原型图	判断依据
涉及新页面/新组件/UI交互变化	✅ 需要	有用户可见的界面改动
纯后端 API / 数据逻辑	❌ 不需要	无 UI 变化
仅修改现有组件的显示逻辑	⚠️ 视情况	参考现有原型是否有该元素

---

五、文档关联

5.1 引用关系

00-版本迭代总览.md（全局索引）
    │
    ├─ 引用 → 各版本 PRD / 技术方案 / 测试报告 / 发布说明
    │
PRD (01-产品文档)
    │
    ├─ 引用 → 原型图（01-02产品设计）
    │
    ├─ 引用 → 技术方案（02-技术文档）
    │           └─ 引用 → 接口设计 / 数据库设计
    │
    ├─ 引用 → 测试用例（03-测试文档）
    │           └─ 回流 → 缺陷单 → 回归用例
    │
    ├─ 引用 → 部署/监控/运维手册（04-运维文档）
    │
    ├─ 引用 → 安全审计（06-安全审计，涉及合规的需求）
    │
    └─ 运营指标回流 → PRD 指标章节（05-运营文档 闭环）

5.2 文档头部模板

# 功能名称

> **版本**: v1.0
> **日期**: 2026-07-19
> **状态**: [待评审]
> **作者**: Simon
> **关联文档**: 
>   - PRD: `01-产品文档/子系统/PRD-REQ-模块-序号-功能名-v版本号.md`
>   - 原型: `01-产品文档/子系统/原型-功能名.html`
>   - 技术: `02-技术文档/实现配置/xxx.md`
>   - 测试: `03-测试文档/04-版本测试报告/TR-xxx.md`
>   - 运维: `04-运维文档/部署运维/DEPLOY-xxx.md`

---

六、总结

流程原则

1. 阶段清晰：需求 → 设计 → 技术 → 测试 → 运维 → 运营，顺序执行、向后回溯
2. 依赖明确：前序产出作为后续输入
3. 质量闸门：测试未通过验收标准不得上线；运维三件套齐备方可发布
4. 价值闭环：运营指标未达预期回流需求
5. 版本管理：每次变更更新版本号
6. 变更记录：所有变更必须记录

核心规则

• 需求确认后才开始设计
• 设计确认后才开始技术方案
• 技术方案评审后才开始开发
• 开发提测后测试是质量守门员，不得"带病上线"
• 测试通过后运维接手，部署/监控/手册三件套齐备方可发布
• 上线后运营分析回流 PRD，形成需求→价值闭环
• 重构记录按版本拆分，不单列目录
• 历史归档先分拣，仍被引用的提升回主文档
• 所有文档变更必须记录版本和变更内容

---

七、需求编号体系

7.1 需求编号与文档的关系

需求编号（主键）
    │
    ├── 关联 PRD 文档
    ├── 关联 技术方案 文档
    ├── 关联 测试用例 文档
    └── 关联 任务说明书

REQ-会话-001 ──┬──→ PRD-会话模块-暂停恢复.md
               ├──→ 技术方案-会话模块-暂停恢复.md
               ├──→ TC-会话模块-暂停恢复.md
               └──→ 任务说明书-会话-001.md

关系：

• 一对一：1个需求编号 → 1个核心PRD文档
• 一对多：1个需求编号 → 多个关联文档（技术方案、测试用例等）

7.2 需求编号命名规则

[类型]-[模块]-[序号]

类型：
- REQ（需求/Requirement）——产品需求
- TASK（任务/Task）——开发任务
- BUG（缺陷/Bug）——缺陷修复

模块：
- 认证（认证与登录）
- 会话（会话管理）
- AI（AI服务）
- 坐席（坐席工作台）
- 用户（用户端H5）
- 审批（审批与待办）
- 知识（知识库）
- 集成（集成生态）

序号：3位数字，自动递增

7.3 需求编号全局唯一性（强约束）

⚠️ 强制要求：需求编号在项目范围内全局唯一

规则	说明
唯一性	同一REQ编号只能分配给一个需求，禁止重复使用
跨模块	序号在模块内递增，不同模块可使用相同序号（如REQ-会话-001和REQ-坐席-001）
禁用历史编号	已使用过的REQ编号即使需求废弃也不能重新分配
技术文档关联	所有技术方案、测试用例、任务说明书必须关联REQ编号

违规处理：

• 新增需求时AI需校验REQ编号是否已存在
• 代码commit message必须包含REQ编号
• 上线审批需检查REQ编号关联的文档是否完整

7.3 编号示例

需求编号	含义
REQ-会话-001	会话模块第1个需求
REQ-审批-012	审批模块第12个需求
TASK-会话-001	会话模块第1个开发任务
BUG-消息-003	消息模块第3个缺陷

7.4 文档命名规范（增加需求编号）

# PRD 文档
PRD-[模块名]-[功能名].md
PRD-REQ-[需求编号]-[功能名].md  # 推荐

# 技术方案
技术方案-[模块名]-[功能名].md

# 测试用例
TC-[模块名]-[功能名].md

# 任务说明书
任务说明书-[需求编号]-[功能名].md

---

八、文档生命周期管理

8.1 新增 / 变更 / 删除判断

类型	判断依据	举例
新增	之前不存在、从未实现过的功能	"新增暂停恢复功能"
变更	已有功能的需求/技术调整	"修改暂停超时从24h改为8h"
删除	已有功能不再需要	"移除短信通知功能"

8.2 生命周期流程

需求进入 → 判断[新增/变更/废弃]
    │
    ├─ 新增 → 新建完整文档
    │
    ├─ 变更 → 在原文档中更新 + 追加变更记录
    │
    └─ 删除 → 标记"已废弃" + 扫描引用

8.3 变更记录模板

## 变更记录

| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|------|------|----------|--------|----------|
| 2026-07-19 | v1.1 | 新增暂停超时配置 | Simon | 用户反馈24h太长 |

8.4 废弃文档处理

• 在文档头部标记状态：> **状态**: [已废弃]
• 说明废弃原因和替代方案
• 保留在原位置（不移动到归档，除非完全无引用）

---

九、输入环节模板体系

9.1 各环节标准模板

环节	模板	关键字段
业务需求入口	需求收集表	需求编号、类型标记、新增/变更/废弃
产品评审	PRD 评审表	关联需求编号、类型标记
设计评审	原型评审表	关联PRD、变更标记
技术评审	技术方案评审表	关联需求编号、关联PRD
测试评审	测试用例评审表	关联技术方案、变更标记
上线审批	上线checklist	文档完备性检查、需求编号关联

9.2 需求收集表模板

# 需求收集表

> **需求编号**: REQ-[模块]-[序号]  <!-- AI 自动生成 -->
> **需求名称**: 
> **需求类型**: [ ] 新增  [ ] 变更  [ ] 废弃
> **关联模块**: 
> **需求来源**: 
> **业务背景**: 

## 需求描述

## 预期收益

## 关联文档（若有）

9.3 任务说明书模板（增加关联字段）

# 任务说明书

> **关联需求编号**: REQ-[模块]-[序号]  <!-- 必填 -->
> **关联PRD**: 
> **需求类型**: [ ] 新增  [ ] 变更  [ ] 废弃

---

十、约束管理措施

10.1 用户直接修改的约束

问题场景：

用户 → 直接找技术 → 修改参数 → 代码变更
                ↑
                没有产品评审，没有文档记录

约束流程：

用户直接反馈
    │
    ▼
技术接收 → 立即转产品确认（强制）
    │
    ▼
产品评估 → 判断[新增/变更/废弃]
    │
    ▼
    ├─ 变更 → 更新PRD + 变更记录
    ├─ 废弃 → 标记已废弃
    └─ 拒绝 → 告知用户原因
    │
    ▼
技术执行 → 代码commit必须关联需求编号
    │
    ▼
上线审批 → 检查需求编号是否存在、文档是否更新

10.2 代码提交约束

# Commit message 格式
[REQ-会话-001] 添加暂停恢复功能

# 强制关联需求编号（必填）

10.3 上线审批检查项

检查项	说明
需求编号关联	commit message 必须包含 REQ-xxx
PRD 更新	对应的 PRD 文档是否已更新
变更记录	变更是否有变更记录
测试用例	是否有对应的测试用例

---

十一、AI/Skill 自动引导功能

11.1 Skill 可实现的功能

功能	实现方式
自动生成需求编号	根据模块+序号自动生成下一个编号
编号校验	检查编号格式是否正确、是否已存在
关联检查	检查需求编号是否关联了必要文档（PRD+技术方案+测试用例）
命名规范检查	正则匹配 PRD-[模块]-[功能].md，不符则警告
变更记录提醒	识别"变更"类型时，自动在文档末尾追加变更记录表格
引用检查	扫描被引用的文档是否标记为"已废弃"

11.2 Skill 无法完全自动化的环节

环节	需要人工
判断是新增还是变更	需理解业务上下文
确认废弃是否有风险	需人工评估
最终审批	需人工确认

11.3 自动引导流程

输入（需求/任务）
    │
    ▼
AI 检索历史文档库 ──→ 找到相关文档？
    │               │
    │              否 ──→ 建议新增文档
    │               │
    ▼               ▼
有相关文档 ──→ 一致性检查
    │              │
    │             是 ──→ 建议变更文档（追加变更记录）
    │              │
    │             否 ──→ 冲突警告（需人工确认）
    │
    ▼
生成/更新文档（强制填写需求编号）
    │
    ▼
技术执行 → commit message 关联需求编号
    │
    ▼
上线审批 → 自动检查文档完备性

---

十二、缺陷管理（BUG Tracking）

12.1 缺陷管理流程

缺陷发现 → 评估优先级 → 创建缺陷单 → 修复 → 验证 → 关闭
                              ↓
                        回归测试用例

12.2 缺陷状态流转

状态	英文	说明	流转方向
待处理	Open	缺陷已确认，待指派	新建 → 指派
进行中	In Progress	正在修复中	指派 → 修复中
已修复	Fixed	代码已修复，待验证	修复中 → 验证
已验证	Verified	验证通过，缺陷关闭	验证 → 关闭
已关闭	Closed	缺陷修复并验证完成	-
延期	Deferred	暂不处理，推迟	指派 → 延期
无法复现	Can't Reproduce	无法复现，关闭	指派 → 无法复现

12.3 缺陷优先级定义

优先级	级别	说明	SLA（响应时限）
P0-Critical	致命	系统崩溃、数据丢失、业务中断	4小时内响应
P1-High	高	核心功能不可用、严重影响业务	24小时内响应
P2-Medium	中	功能异常但有绕过方案	3天内响应
P3-Low	低	轻微问题、UI样式、体验优化	下一迭代安排

12.4 缺陷编号规则

BUG-[模块]-[序号]

模块：
- AI（AI服务/意图识别/路由）
- 会话（会话管理）
- 坐席（坐席工作台）
- 用户（用户端H5）
- 审批（审批与待办）
- 知识（知识库）
- 集成（第三方集成）
- 运维（部署/运维问题）

序号：3位数字，自动递增

示例：

• BUG-AI-001 - AI模块第1个缺陷
• BUG-会话-003 - 会话模块第3个缺陷

12.5 缺陷单模板

# 缺陷单：缺陷简要描述

> **缺陷编号**: BUG-[模块]-[序号]
> **状态**: [待处理/进行中/已修复/已验证/已关闭/延期/无法复现]
> **优先级**: [P0-Critical/P1-High/P2-Medium/P3-Low]
> **发现日期**: YYYY-MM-DD
> **发现人**: 
> **指派人**: 
> **修复人**: 
> **关闭日期**: 

## 基本信息

| 字段 | 内容 |
|------|------|
| 缺陷标题 | |
| 影响范围 | |
| 触发条件 | |
| 预期行为 | |
| 实际行为 | |

## 复现步骤

1. 
2. 
3. 

## 根因分析

## 修复方案

## 验证结果

| 验证项 | 结果 | 验证人 | 验证日期 |
|--------|------|--------|----------|
| 功能验证 | 通过/失败 | | |
| 回归测试 | 通过/失败 | | |

## 变更记录

| 日期 | 变更内容 | 变更人 |
|------|----------|--------|
| | | |

## 关联信息

- **关联需求**: REQ-[模块]-[序号]（若有）
- **关联代码文件**: 
- **关联测试用例**: TC-[模块]-[缺陷编号]

12.6 缺陷跟踪表（轻量级管理）

缺陷管理采用双视图分离架构：跟踪表（横向汇总）在 07-项目管理/，BUG 单（纵向闭环）在 03-测试文档/05-缺陷单/。

# 缺陷跟踪表

| 缺陷编号 | 标题 | 状态 | 优先级 | 发现日期 | 修复人 | 预计完成 | 实际关闭 |
|----------|------|------|--------|----------|--------|----------|----------|
| BUG-AI-001 | 打印机安装路由错误 | 已验证 | P2 | 2026-07-20 | Simon | 2026-07-20 | 2026-07-20 | [03-测试文档/05-缺陷单/BUG-AI-001.md](../03-测试文档/05-缺陷单/BUG-AI-打印机安装路由错误-001.md) |

双视图协作：

• 缺陷跟踪表.md：横向视角（多缺陷状态汇总）
• BUG-{模块}-{描述}-{序号}.md：纵向视角（单缺陷全生命周期）

禁止：

• ❌ 把 BUG 单放进 07-项目管理/（违反 § 2.2 类别边界规则）
• ❌ 把缺陷跟踪表放进 05-缺陷单/（跟踪表属于项目管理工具）

12.7 缺陷管理与代码提交

# Commit message 格式
[BUG-AI-001] 修复打印机安装路由到前台的问题

# 强制关联缺陷编号（必填）

12.8 缺陷管理检查清单

步骤	操作	说明
1	创建缺陷单	填写基本信息、复现步骤
2	评估优先级	根据影响范围确定 P0-P3
3	指派修复人	明确责任人
4	代码修复	commit message 关联 BUG 编号
5	创建回归用例	确保修复不引入新问题
6	验证修复	功能验证 + 回归测试
7	更新缺陷单	填写验证结果，关闭缺陷

---

十三、文档整理实践指南（基于2026-07-19经验）

13.1 整理检查清单

步骤	操作	说明
1	扫描目录结构	使用 Get-ChildItem -Recurse 列出所有文件
2	检查命名规范性	PRD/技术方案是否包含 REQ 编号
3	检查头部模板	是否包含必填字段（版本、日期、状态、作者）
4	检查关联	技术方案是否关联 PRD，PRD 是否关联原型
5	更新引用路径	文档移动后必须更新所有引用
6	检查归档标记	历史文档使用 -archived-日期 后缀

13.2 常见问题与修复

问题	修复方法
REQ 编号格式错误（如 REQ-02-001）	修正为 REQ-[模块]-[序号]（如 REQ-会话-001）
引用路径过时（如 docs/02-产品需求/）	更新为 01-产品文档/子系统/
技术方案缺少 REQ 编号	在头部添加 > **REQ编号**: REQ-[模块]-[序号]
文档放错目录	按 2.2 类别边界规则移动到正确目录
子目录编号不统一	统一使用 01-、02-、... 前缀
BUG 单放错目录（如 07-项目管理/BUG-*.md）	按 § 12.6.3 迁移至 03-测试文档/05-缺陷单/
BUG 单命名格式错误（如缺序号）	重命名为 BUG-{模块}-{描述}-{序号}.md（符合 ^BUG-.*-\d+\.md$）

13.2.1 构建产物验证三证据链（基于 2026-07-28 经验）

适用场景：管理后台等需要企业微信扫码登录的端，agent-browser 无法自动 E2E 时，如何证明前端改造正确？

证据	验证方式	命令
编译层	npm run build 通过，无 TS 报错	npm run build 2>&1 | tail -10
产物层	chunk 含新功能字符串字面量（保留特征）	grep -E "新功能|字符串" dist/assets/{Chunk-*.js}
部署层	服务器 HTTP 200 + 关键 API 200	curl -I http://{server}/itadmin/ && curl http://{server}:8000/admin/{endpoint}

禁止：用源码变量名验证产物（minify 后变量名消失）。改用：

• 属性名（.in_progress / .session_id）
• CSS class（.mode-card / .monitor-widget）
• Route name（字符串保留）
• 字符串字面量（手动接单 / agents-assignment）

13.3 引用路径更新原则

1. 同步更新：文档移动或重命名后，必须更新所有引用该文档的地方
2. 使用相对路径：01-产品文档/02-会话管理/PRD-REQ-会话-001-暂停恢复-v1.1.md
3. 避免死链接：更新后验证目标文档是否存在

13.4 部署配置同步铁律（基于2026-07-23经验）

修改 config.py 默认值 ≠ 配置生效，必须同步更新服务器 .env 文件。

场景	操作
修改 config.py 默认值	同步更新服务器 .env 文件（或确保 docker-compose.yml 有正确的默认值兜底 ${VAR:-默认值}）
新增环境变量	同时更新 .env 文件、docker-compose.yml、config.py 三处
部署/重启前	核对 .env 与 config.py 的差异

违反后果：配置不生效，导致运行时使用旧值/默认值，引发难以排查的运行时异常（如本次 Dify 超时导致 [object Object] bug）。

13.5 归档文件处理

• 归档文件命名：原文件名-archived-日期.后缀
• 归档目录：08-历史归档/
• 归档条件：无活跃引用（不被其他文档引用）
• 归档前确认：仍有引用 → 提升回主文档；无引用 → 归档

13.6 Dify DSL 备份与变更管理规范

基于 2026-07-24 实践总结

13.6.1 Dify 应用维护流程

备份当前DSL → 本地修改 → 导入Dify控制台 → 点击发布 → 重启后端 → 验证

13.6.2 备份规范

项目	规则
备份位置	docs/02-技术文档/实现配置/dify_dsl/
命名格式	{应用标识}_{YYYY-M-D_HHMMSS}.yml
操作类型后缀	_BACKUP（常规备份）、_v版本号（特定版本）
变更日志	docs/02-技术文档/实现配置/dify变更日志.md

13.6.3 变更日志格式

## 2026-07-24
- 应用：智能IT支持-员工咨询
- 操作：导出DSL备份 / 修改Prompt / 导入发布
- 文件：itdesk_main_2026-7-24_102740.yml
- 备注：变更内容简要说明

13.6.4 关联技能

• dify-deploy：Dify 应用维护工具集 skill，支持备份、导入、发布、重启、验证全流程

13.6.5 关键注意事项

场景	注意事项
修改前	必须先从 Dify 控制台导出当前 DSL 备份
导入后	必须点击「发布」按钮，否则更改不生效
发布后	必须重启后端容器（docker compose restart backend）
验证	手动发送测试消息，确认 AI 回复符合预期

13.7 多路径代码同步铁律（基于 2026-07-27 经验）

场景：项目同时存在于中文路径与 ASCII 路径两处

路径	用途
D:\资料\03-项目开发\wecom_it_smart_desk\src\	工作目录（中文）
D:\dev\wecom\src\	ASCII 构建路径（pnpm install 不卡死）

铁律：

• 修改源代码时必须两边都改（中文路径 + ASCII 路径）
• build 用 ASCII 路径（中文路径下 pnpm install 卡死，建 junction 也无效）
• 验证方法：build 后查 dist/assets/*.css 或 *.js 的 hash 变化（hash 变 = 源码改了）
• 优化方向：未来考虑用 mklink /J 建符号链接（待评估）

违反后果：build 用的是 ASCII 路径下的旧代码，部署后无效果。

13.8 前端小 UI 改造的 7 件套文档清单（基于 2026-07-28 经验）

适用：Tab 收编 / Tab 拆分 / 页面合并 / 单组件重构等小 UI 改造。

按规范 §4.3"功能调整" + §5.1 引用关系，小 UI 改造也必须配套 7 件套：

#	文档	路径	必要度
1	PRD（版本号升级 + 变更记录）	01-产品文档/{子系统}/	必须
2	原型图（同步改造）	01-产品文档/{子系统}/	必须
3	技术方案	02-技术文档/	必须
4	测试用例（覆盖 + 回归）	03-测试文档/03-功能测试用例/	必须
5	任务说明书	07-项目管理/任务说明书/	必须
6	版本迭代总览	00-版本迭代总览.md	必须
7	部署运维补充（含回滚预案）	04-运维文档/部署运维/	必须

详细流程见 § 十五"前端模块收编/拆分流程"。

---

十四、大需求重构的文档化策略

基于 2026-07-28 管理后台 IA 重构三件套补齐经验总结 （P0 三 bug + P1 单一真源 + P1-b Dashboard widget + P2-a/P2-c 两路由补全 + v1.2 分配模式 Tab 收编，跨越 5 次部署迭代，6 阶段全部闭环）

14.1 大需求识别标准

满足以下任一条件，应视为大需求，需要专门的文档化策略：

判定条件	说明
跨越多个阶段（P0+P1+P2 等）	每个阶段独立部署
跨越多次部署迭代	每次迭代可能持续数小时到数天
影响多个端（前端+后端+运维）	跨端改动需协调
涉及单一真源改造（IA 重构、配置化重构）	触动现有架构约定
涉及多个子系统（菜单+路由+组件+API）	跨子系统改动

14.2 铁律 1：第 1 个阶段就建任务说明书

不要等所有阶段上线后回溯补全任务说明书。

原因：

• 跨多阶段的需求，踩坑经验/技术决策/版本号一致性容易遗漏
• 后续阶段实施时缺乏统一输入文档
• 验收追溯不完整

正确做法：

• 在第 1 个阶段（哪怕只是 P0 bug 修复）就建任务说明书
• 任务说明书覆盖全部 WBS 阶段（已知 + 计划）
• 每个阶段上线后，任务说明书追加状态更新
• 任务说明书 v1.0 → v1.1（最终闭环）→ v1.2（追加最后阶段）

14.3 铁律 2：文件名版本号 = 文档内容版本号

PRD 文件名必须跟实际版本号一致，否则引用混乱。

问题示例：

• 文档内容已是 v1.2，但文件名仍是 PRD-xxx-v1.0.md
• 引用方写 PRD-xxx-v1.0.md，实际内容已是 v1.2，造成误导
• 重命名时若不改引用，会出现"指向 v1.0 但内容是 v1.2"的诡异情况

正确做法：

• 文件名版本号必须 = 文档头部的 > **版本**: vX.Y 字段
• 重命名文件时同步更新所有引用（grep 全文搜索）
• 例：PRD-REQ-集成-002-管理后台-v1.0.md → PRD-REQ-集成-002-管理后台-v1.2.md

14.4 铁律 3：三件套版本对齐

PRD + 技术方案 + 任务说明书的版本号必须保持一致。

理由：

• PRD v1.2 描述 v1.2 变更，技术方案应该是 v1.2，任务说明书也应该是 v1.2
• 不一致会导致引用方无法判断"哪个版本是当前权威"

操作：

• 三个文档使用同一版本号（按需求覆盖范围最高版本）
• 整改时同步更新三个文件的版本号 + 引用链

14.5 铁律 4：子任务合并/扩展的归档规范

被合并/扩展的旧任务说明书应改名为 .v{X}.archive.md 保留作为历史参考。

理由：

• 保留完整的旧任务历史，便于后续追溯
• 文件名后缀明确区分"在维护"和"已归档"
• 避免误以为还在维护导致重复编辑

操作示例：

原文件名：任务说明书-REQ-集成-002-分配模式Tab收编.md
归档后：  任务说明书-REQ-集成-002-分配模式Tab收编.v1.0.archive.md
新建：    任务说明书-REQ-集成-002-IA重构整体.md（覆盖整体 6 阶段）

14.6 铁律 5：整改记录建立独立索引文件

文档规范化整改应该建立独立的索引文件（04-运维文档/部署运维/00-文档规范化整改记录.md），记录每次整改。

格式：

### 整改 #N · 触发需求 / 整改对象

| 项目 | 值 |
|------|------|
| 日期 | YYYY-MM-DD |
| 触发人 |  |
| 源需求 / 源文档 |  |
| 整改维度 | A 命名/位置 + B 关联引用 + C 命令铁律 + D 完整度 |
| 问题数 |  |
| 关键修复 | （逐项描述） |
| 归档动作 | （被替换的旧文档处理方式） |
| 引用同步 | （哪些文件的引用路径需更新） |
| ASCII 副本同步 | （中文路径 ↔ ASCII 副本） |
| 收益 |  |
| 教训 |  |
| 上线状态 | ✅ 已完成 / 🟡 待部署 / ... |

已知整改索引（00-文档规范化整改记录.md）：

• 整改 #1-#6：覆盖部署文档 / BUG 单规范化 / BUG 单目录迁移 / 页面去重 / BUG-通用-002 / IA 重构三件套补齐
• 详见 04-运维文档/部署运维/00-文档规范化整改记录.md

14.7 单一真源 menu.config.ts 模式（IA 重构关键技术决策）

适用于"菜单/路由/权限分散在多个文件"的情况：

menu.config.ts（单一真源）
  ├─ groups[]       // 5 个分组（顺序、图标、颜色）
  ├─ items[]        // 业务菜单
  ├─ subTabs[]      // 父子页签
  ├─ lockedItems[]  // 折叠区占位
  └─ rolesFilter    // 角色过滤字段

        ↓ 派生

Sidebar.vue       // v-for 渲染，零硬编码
router/index.ts   // meta.menuKey 反查

收益：新增菜单仅改 1 文件，自动出现在 Sidebar + router + 角色过滤三处。

14.8 6 阶段标准工作分解（WBS 模板）

阶段	内容	优先级	估时参考
P0	止血 bug 修复（路由/菜单/组件可点性等）	P0	20 min
P1-a	单一真源配置（menu.config.ts / table.config.ts 等）	P1	1.5 h
P1-b	业务功能补全（Dashboard widget / 详情页双视图）	P1	2 h
P2-a	路由补全（顶级路由缺失）	P2	30 min
P2-b	子路由补全（嵌套路由缺失）	P2	30 min
v1.2	UI 收编/合并（独立页 → Tab 收编）	P2	30 min

每个阶段独立部署、独立验证，避免一次大爆炸式变更。

14.9 跨项目铁律沉淀（候选）

铁律	说明
大需求第 1 阶段就建任务说明书	不要等所有阶段上线后回溯补全
文件名版本号 = 内容版本号	PRD 文件名必须跟实际版本号一致
三件套版本对齐	PRD + 技术方案 + 任务说明书使用同一版本号
子任务合并归档	旧任务说明书改名为 .v{X}.archive.md
整改记录建索引文件	00-文档规范化整改记录.md 记录每次整改
单一真源派生模式	menu.config.ts 派生 Sidebar + router，避免多源维护脱节
6 阶段分批部署	P0 → P1 → P1-b → P2-a → P2-b → v1.2，每次独立部署独立验证

---

十五、前端模块收编/拆分流程（基于 2026-07-28 分配模式 Tab 收编经验）

适用范围：前端模块的"独立页 → Tab 内嵌"或反之"Tab 内嵌 → 独立页"调整。这是一类小 UI 改造（不影响后端 API / 数据库），但涉及多文件联动 + 文档联动。

15.1 场景识别

场景	触发条件	典型例子
页面收编	一个独立页（如 /admin/assignment-mode）内容极薄（>50% 灰化占位），且与另一个页面（/admin/agents）有强上下文关联	分配模式 → 坐席管理 Tab
页面拆分	Tab 内嵌内容膨胀（>3 个 Tab 或 Tab 内有复杂配置），需要拆回独立页	阶段二/三分配策略可能膨胀
页面合并	两个独立页面功能高度重叠，可合并为一个带 Tab 的页面	快速回复模板 → 快速回复规则 Tab

15.2 决策矩阵：独立页 vs Tab 内嵌 vs 合并

评估维度	独立页	Tab 内嵌	合并
页面复杂度	内容丰富、独立性强	内容薄、强依赖其他页面数据	两页内容都属于同一业务域
未来扩展性	长期独立演进	短期共存，未来可拆可合	长期共存
上下文关联	与其他页面弱关联	强关联（如解锁条件依赖数据）	强关联
菜单负担	占独立菜单项（可接受）	节省菜单项	节省菜单项
回滚难度	拆 → Tab：需重做 UI；合 → Tab：低	独立 → Tab：低；Tab → 独立：中	独立 → 合：中；合 → 独立：高

推荐原则：

• 内容薄 + 强依赖 → Tab 内嵌（本次方案）
• 内容薄 + 弱依赖 → 保持独立页
• 内容丰富 + 强依赖 → 保持独立页（Tab 切换不会降低复杂度）
• 两个页面均属同一业务域 → 合并（但需谨慎评估回滚难度）

15.3 实施步骤（11 步标准流程）

基于 2026-07-28 分配模式 Tab 收编 80 min 实战提炼。

#	步骤	预计耗时	输出物
1	读源文件 + 画迁移映射（哪些行迁移、哪些保留）	5 min	迁移映射清单
2	目标页（Agents.vue）加 <el-tabs> 套层，原内容迁入 Tab 1	15 min	目标页模板改造
3	Tab 2 复制源页（AssignmentMode.vue）的模板 + 脚本（含 reactive、computed、API 调用）	15 min	第二个 Tab 内容
4	路由表删除源页路由项（/admin/assignment-mode）	2 min	router/index.ts
5	源页文件保留 + 顶部加停用注释（含 30 min 回滚步骤）	2 min	AssignmentMode.vue 顶部注释
6	多路径同步铁律（中文路径 + ASCII 路径双改）	—	见 § 13.7
7	npm run build 验证（无 TS 报错、无 lint 警告）	5 min	dist 目录
8	构建产物验证三证据链（见 § 13.2 补充）	5 min	见 § 13.2
9	部署到生产（v2_ops.py upload + 服务器解压 + docker restart wecom_it_nginx）	15 min	生产 dist
10	（可选）agent-browser 端到端验证	10 min	E2E 报告
11	API 兼容性 curl 验证（关键 API 200 OK）	2 min	API 验证报告

15.4 完整文档清单（按规范 §4.3 "功能调整" + §5.1 引用关系）

#	文档	路径	规范要求
1	PRD	docs/01-产品文档/{子系统}/PRD-REQ-集成-002-xxx-v1.X.md	§4.3"功能调整"+版本号+变更记录
2	原型图	docs/01-产品文档/{子系统}/原型-REQ-xxx-v1.X.html	§4.3"原型图（视情况）"
3	技术方案	docs/02-技术文档/技术方案-REQ-xxx-xxx.md	§4.3
4	测试用例	docs/03-测试文档/03-功能测试用例/TC-xxx-xxx.md	§4.3"功能调整"+回归
5	任务说明书	docs/07-项目管理/任务说明书/任务说明书-REQ-xxx-xxx.md	§3.1.3
6	版本迭代总览	docs/00-版本迭代总览.md（追加一行 + 经验总结）	§5.1 引用关系
7	部署运维补充	docs/04-运维文档/部署运维/DEPLOY-xxx-xxx.md	§4.3"上线" + 含回滚预案
8	commit message	[REQ-集成-002] 分配模式 Tab 收编	§10.2 强制

重要：规范 § 4.3 "功能调整" 场景下，PRD、原型图、测试用例 必须 更新，技术方案与任务说明书 建议 配套（复杂改动必备）。

15.5 强约束（基于本次踩坑）

15.5.1 多路径代码同步铁律

场景：项目同时存在中文路径（D:\资料\03-项目开发\wecom_it_smart_desk\）与 ASCII 路径（D:\dev\wecom\），build 用 ASCII 路径。

操作	强制要求
修改源代码	两边都改（中文路径 + ASCII 路径）
验证方法	build 后查 dist/assets/*.css / *.js 的 hash 变化
优化方向	未来用 mklink 建符号链接（见 § 13.7）

15.5.2 构建产物验证三证据链

场景：admin 后端需企业微信扫码登录，无法用 agent-browser 自动 E2E；如何证明改造正确？

证据	方式	命令示例
编译层	npm run build 通过	npm run build 2>&1 | tail -10
产物层	chunk 含新功能字符串字面量	grep -E "agents-assignment|手动接单" dist/assets/Agents-*.js
部署层	服务器 HTTP 200 + 关键 API 200	curl -I http://10.90.5.110/itadmin/ && curl -I http://10.90.5.110:8000/admin/assignment-mode

禁止：用源码变量名验证产物（minify 后变量名消失）。

15.5.3 源页文件保留 + 停用注释

目的：未来回滚有迹可循（30 分钟可逆）。

源页（AssignmentMode.vue）不删除，顶部加：

<!--
=============================================================================
[模块名] - v1.2 起停用（仅供回滚）
=============================================================================
说明：本文件于 v1.2 起不再使用，内容已迁移至 [目标页] → [Tab 名]。
回滚步骤：见 docs/04-运维文档/部署运维/DEPLOY-xxx-xxx.md § 四、回滚预案
=============================================================================
-->

15.5.4 路由删除 vs 保留

选项	适用场景
删除路由项	收编后源页已无意义（本次方案）
保留路由 + 重定向到目标页	旧链接仍可能访问（外部文档/聊天残留）

推荐：删除路由项（强制走新结构），但在变更日志中明确告知"旧路径已废"。

15.6 回滚预案必备要素

任何收编/拆分/合并 PR 必须包含 § DEPLOY 文档的"回滚预案"章节：

1. 恢复路由（精确到行号或代码片段）
2. 恢复菜单项（如涉及）
3. 把内容搬回源页（列出搬移清单）
4. 恢复目标页单一结构（列出删除的包装层）
5. build + 部署命令（与正向流程相同）
6. 归档文档（旧 PRD / 任务说明书状态改 [已废弃]）

总耗时估算 ≤ 30 min（本次验证）。

15.7 跨项目铁律沉淀

铁律	说明
Tab 收编 vs 轻合并 vs 保持现状	内容薄 + 强依赖 → Tab 收编；内容薄 + 弱依赖 → 保持独立；内容丰富 → 独立页
多路径同步	中文路径 + ASCII 路径必须双改
构建产物验证三证据链	编译 + 产物 grep + 部署 HTTP
源页不删，加停用注释	30 min 可逆回滚
回滚预案必备	DEPLOY 文档 § 四
完整文档清单	PRD + 原型 + 技术方案 + TC + 任务说明书 + 版本总览 + DEPLOY（7 件套）

---

十六、技术方案偏离时的"增量更新章节"治理

基于 2026-08-03 voice_asr.py P0 安全巡检 + 文档-代码不一致修复经验总结 （场景：技术方案 v1.0 设计 H5 = 企微 JS-SDK / 坐席端 = Web Speech API 双路径，实际部署中 H5 PC/Mac 端企微用户改用"前端录音 + 后端 POST /api/voice/asr（百度 ASR）"作为第三条兜底分支，v1.0 漏写）

16.1 场景识别：什么时候触发"增量更新章节"

技术方案（v1.0）发布后，实际部署出现以下任一偏离时，必须走"增量更新章节"流程（禁止直接覆盖原版本内容）：

场景	说明	典型例子
第三方 SDK/WebView 行为限制	企微 PC/Mac 客户端内置浏览器对 Web Speech API 不支持、JS-SDK 在桌面端挂起	语音输入 PC/Mac 兜底
性能/配额约束	实际跑出性能瓶颈导致必须改用其他方案	切换 ASR 供应商、换文件上传通道
跨端一致性需求	原本独立的方案在跨端测试中发现必须统一	路由前缀 /api/v1/ 统一化
安全合规补丁	加 auth、加审计、加加密	voice_asr.py 加 Depends(get_current_user)
环境适配分支	不同浏览器/客户端需要不同策略（"多策略自动切换"）	语音输入双策略

16.2 增量更新章节模板（§10 节）

技术方案文档应在末尾预留 ## 10. 增量更新记录（vX.Y） 章节，使用以下模板：

## 10. 增量更新记录（vX.Y）

> **更新日期**: YYYY-MM-DD
> **触发事件**: （安全巡检 / 性能告警 / 用户反馈 / 跨端测试发现 ...）

### 10.1 背景：vX.0 与实际部署的偏离
（用对比表说明设计 vs 实际的差异，列出哪些分支遗漏）

### 10.2 为什么必须有"X 兜底"
（解释第三方 SDK/WebView/性能约束的客观限制，说明为什么必须走其他路径）

### 10.3 实际技术方案
（流程图 + 关键文件清单）

### 10.4 关联的代码/配置变更
（列出本次同步修改的源文件路径）

### 10.5 编号冲突说明（⚠️ 待治理）
（如果涉及 REQ 编号与 PRD 冲突，记录并提出治理建议，**禁止**当下擅自重命名编号避免范围蔓延）

### 10.6 文档-代码一致性核查清单
（用表格列出所有相关文档的核查状态，强制一次扫一遍）

### 10.7 测试矩阵
（覆盖新分支的所有场景，含安全/性能/兼容性）

16.3 多策略功能的文档化要求

核心原则：技术方案文档必须列出所有生产环境会用到的技术路径，不止是"理想路径"。

对于"自动检测环境 + 多策略切换"的功能（如语音输入），技术方案必须：

必填项	说明
策略枚举表	列出所有可能环境（如：手机企微 / PC 企微 / Mac 企微 / 普通浏览器），每个环境的策略选型
策略优先级	明确优先级（如：企微 JS-SDK > 百度 ASR > 不显示按钮）
降级条件	每个策略的禁用/降级触发条件
不显示按钮 vs 显示禁用态	必须二选一并说明理由（项目惯例：降级策略须"不支持隐藏按钮"，见 §60）
第三方 SDK/WebView 限制证据	注释中明确写明"哪些客户端不支持"，避免后续重复排查

16.4 API 端点调用方分析强制检查项（基于 2026-08-03 voice_asr.py 教训）

⚠️ 强约束：判定某个 API 端点为"孤儿接口"或评估"加 auth 影响范围"前，必须完成以下 5 个来源的 grep 验证，任意一处命中即不能算孤儿。

#	grep 来源	命令模式
1	所有前端项目源码（含 composable/store/api/utils）	Grep -l "<endpoint 字符串>" src/frontend-*/src/
2	前端 apiClient 全局拦截器（决定加 auth 后的兼容性）	Grep -l "interceptors|Bearer" src/frontend-*/src/api/
3	后端其他模块的反向调用	Grep -l "<endpoint 字符串>" src/backend/app/
4	测试用例（即使 AsyncMock 不走 HTTP 也算潜在生产调用意图）	Grep -l "<endpoint 字符串>" src/backend/tests/
5	运维配置 + 文档注释（环境变量清单、技术方案增量更新）	Grep -l "<endpoint 字符串>" docs/04-运维文档/

关键判断问句（每次必答）：

"如果对这个端点加 auth，会破坏什么用户路径？"

答不出 = 没查够，禁止下结论。

反例（2026-08-03 教训）：

• 仅 grep /voice/asr 字符串找不到全部调用方
• 必须顺藤摸瓜查到 useWecomVoice / useAudioRecorder / useSpeechRecognition 三个 composable
• 必须看 InputBar.vue 的 voiceStrategy computed（多策略自动切换）
• 必须看 api/index.ts 的 interceptors.request（自动注入 Bearer Token 决定加 auth 兼容性）

16.5 文档-代码一致性核查清单模板

触发场景：任何技术方案发布 +90 天、出现 P0/P1 巡检发现、文档与代码不一致修复时，必须做一次一致性核查。

文档类型	核查内容	命中关键词举例
运营手册（如 手册-坐席端.md）	端 × 技术方案矩阵是否真实	语音 / Web Speech / 百度 ASR / 企微 JS-SDK
配置清单（如 配置清单与环境变量.md）	每个环境变量是否有"调用方"说明	BAIDU_* / WECOM_* / DIFY_*
架构设计（如 系统架构设计文档v2.md）	模块描述是否包含多策略分支	"H5 端采用双策略 ..."
业务影响评估（如 PRD）	是否包含"第三方 SDK/WebView 限制"章节	企微 / Chrome / Edge / Firefox
测试用例（如 TC-xxx.md）	覆盖矩阵是否包含所有策略分支	移动端 / PC 端 / 普通浏览器

输出物：在技术方案的 §10.6 文档-代码一致性核查清单 中以表格形式列出，每行带 ✅/⚠️/❌ 状态。

16.6 跨项目铁律沉淀（候选 → ~/.workbuddy/MEMORY.md）

铁律	说明
增量更新章节模板	技术方案偏离时用 ## 10. 增量更新记录（vX.Y） 治理，禁止覆盖原版本
多策略功能必须列全	策略枚举表 + 优先级 + 降级条件 + SDK 限制证据
API 调用方 5 来源 grep	端点安全审计/影响评估前必须多源验证
"加 auth 会破坏什么"必答题	答不出 = 没查够
文档-代码一致性核查清单	技术方案 §10.6 + 每次 P0/P1 巡检必做

---

文档结束