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

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

> **版本**: v1.14
> **日期**: 2026-08-09
> **状态**: [已评审]
> **作者**: 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 运营/配置/运维文档与代码一致性核查清单模板
> - **v1.13 → v1.14**：新增 §13.5.1~13.5.4 归档命名约定全员一致性（基于 2026-08-09 工具栏统一设计 v0.3~v1.9 批量归档经验），涵盖：① §13.5.1 归档命名格式表 + 全员一致性铁律；② §13.5.2 引用指向规则（活文档指向当前生产版本）；③ §13.5.3 归档目录位置规则；④ §13.5.4 归档操作 7 步 SOP；同步清理 §13.5 旧表述 `-archived-日期`（统一为 `.archive`）

---

## 一、流程定义

### 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 变更记录模板

```markdown
## 变更记录

| 日期 | 变更人 | 变更内容 | 变更原因 | 影响范围 |
|------|---------|----------|----------|----------|
| 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 文档头部模板

```markdown
# 功能名称

> **版本**: 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 变更记录模板

```markdown
## 变更记录

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

### 8.4 废弃文档处理

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

---

## 九、输入环节模板体系

### 9.1 各环节标准模板

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

### 9.2 需求收集表模板

```markdown
# 需求收集表

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

## 需求描述

## 预期收益

## 关联文档（若有）
```

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

```markdown
# 任务说明书

> **关联需求编号**: 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 缺陷单模板

```markdown
# 缺陷单：缺陷简要描述

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

## 基本信息

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

## 复现步骤

1. 
2. 
3. 

## 根因分析

## 修复方案

## 验证结果

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

## 变更记录

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

## 关联信息

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

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

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

```markdown
# 缺陷跟踪表

| 缺陷编号 | 标题 | 状态 | 优先级 | 发现日期 | 修复人 | 预计完成 | 实际关闭 |
|----------|------|------|--------|----------|--------|----------|----------|
| 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 归档文件处理

- **归档命名约定**：`.archive` 后缀（详见 §13.5.1）
- **归档目录**：默认留在原目录（命名加 `.archive` 即可）；仅当完全无活跃引用 + 跨多个子系统时，移至 `08-历史归档/{原类别}/`
- **归档条件**：无活跃引用（不被其他文档引用）
- **归档前确认**：仍有引用 → 提升回主文档（不归档）；无引用 → 归档

#### 13.5.1 归档命名约定（全员一致性铁律）

> **核心原则**：**同一条演进线上所有旧版本必须全员打 `.archive` 后缀，不留半归档半未归档。**

**命名格式表**：

| 文档类型 | 归档命名格式 | 示例 |
|---------|-------------|------|
| PRD / 技术方案 | `原文件名.archive.md` | `PRD-REQ-会话-001-工具栏统一设计-v1.3.archive.md` |
| 原型 HTML | `原文件名.archive.html` | `原型-REQ-会话-001-工具栏统一设计v1.4-xxx.archive.html` |
| 任务说明书 | `原文件名.v{X}.archive.md`（保留版本号） | `任务说明书-REQ-集成-002-xxx.v1.0.archive.md` |
| Vue 组件 | `原文件名.archive.vue` | `AssignmentMode.archive.vue` |

**触发场景（任一命中即应归档）**：

| 场景 | 说明 |
|------|------|
| **被新版本接替** | 同一需求编号的 vN → vN+1，前序版本归档 |
| **被合并/收编** | 多源 → 单一源，被合并方归档 |
| **文档状态变更** | 文档状态变为 `[已废弃]`（§8.4） |

**全员一致性原则**：

- 同一条演进线：**第一个版本加 `.archive` 之后，所有同级版本必须全员加 `.archive`**
- 自查：`ls *.html` 第一眼必须能区分"当前生产"和"历史归档"
- 反例：v1.9 加了 `.archive` 但 v1.4~v1.8 仍无 `.archive` → 目录里"半归档半未归档"，结构混乱（2026-08-09 工具栏原型原状）

**`.archive` vs `.archive-日期` 取舍**：

- **推荐**：`.archive`（无日期）—— 文件位置 + REQ 编号本身就是时间戳
- 仅当需要明确"精确归档日期"时附加 `-YYYYMMDD`（如 `xxx.archive-20260809.md`）
- §2.5 / §13.5 旧版提到的 `-archived-日期` 格式已**不再推荐**，统一为 `.archive`（v1.14 清理）

**禁止**：

- ❌ 把归档文件直接删除（保留作为历史快照）
- ❌ 在活文档里混用半归档（部分打 `.archive` 部分不打）
- ❌ 用 `-old` / `-deprecated` / `_bak` 等其他后缀命名归档（统一用 `.archive`）

#### 13.5.2 引用指向规则

> **核心原则**：活文档的引用应指向当前生产版本；归档文件仅作历史参考。

| 引用场景 | 指向规则 |
|---------|---------|
| 任务说明书 / 交付清单的"基线" | 指向当前生产版本（不带 `.archive`）|
| PRD / 技术方案引用 | 指向当前生产版本 |
| 运维 SOP / 故障排查 | 指向当前生产版本 |
| 历史对照 / 复盘 | 可引用 `.archive` 文件（说明对比意向）|

**反例**（2026-08-09 群聊入口接线任务说明书教训）：

- 任务说明书"5 按钮基线"指向 `v1.9-员工端落地版.archive.html` → 误导实施者锁错版本
- 修正：扫描 grep，识别所有指向 `.archive` 的活文档引用，**必须更新到当前生产版本**

#### 13.5.3 归档文件目录位置

- **首选**：留在原目录（不移动），命名加 `.archive` 后缀即可
- 仅当满足以下全部条件时才能移到 `08-历史归档/`：
  - 完全没有活跃引用
  - 跨多个子系统的历史归档
  - 明确标 `08-历史归档/{原类别}/原文件名`

**禁止**：

- ❌ 把被引用的归档文件移动到 `08-历史归档/`（违反"归档 = 历史留痕"的可达性）
- ❌ 修改归档文件内容（保持历史不变性）

#### 13.5.4 归档操作 SOP（基于 2026-08-09 工具栏原型归档经验）

| # | 步骤 | 操作 |
|---|------|------|
| 1 | 识别归档范围 | 列出该 REQ 编号下所有版本文件，按时间/版本号排序 |
| 2 | 区分当前生产 vs 旧版本 | 当前生产保留原名，其余加 `.archive` |
| 3 | 批量重命名 | `Bash` 的 `mv` 或 PowerShell 的 `Rename-Item` |
| 4 | 跨文档树扫描引用 | `grep -rn 原文件名 docs/ src/` |
| 5 | 同步更新活文档引用 | 将指向 `.archive` 的引用更新到当前生产 |
| 6 | 跳过归档区 | `archives/` / `08-历史归档/` 目录内的引用**不动**（历史不变性） |
| 7 | 验证 | `ls` 目录确认当前生产 vs 归档分离清晰 |

### 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 变更日志格式

```markdown
## 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`），记录每次整改。**

**格式**：

```markdown
### 整改 #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）**不删除**，顶部加：

```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）` 章节，使用以下模板：

```markdown
## 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 巡检必做 |

---

*文档结束*