# 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 变更记录模板 ```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-[模块]-[序号] > **需求名称**: > **需求类型**: [ ] 新增 [ ] 变更 [ ] 废弃 > **关联模块**: > **需求来源**: > **业务背景**: ## 需求描述 ## 预期收益 ## 关联文档（若有） ``` ### 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 归档文件处理 - 归档文件命名：`原文件名-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 变更日志格式 ```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）加 `` 套层，原内容迁入 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 ``` #### 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 "" src/frontend-*/src/` | | 2 | **前端 `apiClient` 全局拦截器**（决定加 auth 后的兼容性）| `Grep -l "interceptors\|Bearer" src/frontend-*/src/api/` | | 3 | **后端其他模块的反向调用** | `Grep -l "" src/backend/app/` | | 4 | **测试用例**（即使 AsyncMock 不走 HTTP 也算潜在生产调用意图）| `Grep -l "" src/backend/tests/` | | 5 | **运维配置 + 文档注释**（环境变量清单、技术方案增量更新）| `Grep -l "" 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 巡检必做 | --- *文档结束*