Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
424 lines
28 KiB
Markdown
424 lines
28 KiB
Markdown
# PRD - 分诊排查系统（排查流程图管理）
|
||
|
||
> **REQ编号**: REQ-坐席-007
|
||
> **版本**: v1.3（存量文件名暂保留 v1.0，避免破坏既有引用）
|
||
> **日期**: 2026-07-28
|
||
> **状态**: [待评审]
|
||
> **作者**: 宋献
|
||
> **优先级**: P0
|
||
> **需求类型**: 存量功能补充与生产化改造
|
||
> **关联文档**:
|
||
> - 原型: `原型-REQ-坐席-007-分诊排查系统-v1.0.html`
|
||
> - 技术方案: `../../../02-技术文档/技术架构/技术方案-REQ-坐席-007-分诊排查系统-v1.0.md`
|
||
> - 功能测试: `../../../03-测试文档/03-功能测试用例/TC-坐席-007-分诊排查系统.md`（v1.0，54 条用例，评审通过后补齐）
|
||
|
||
---
|
||
|
||
## 一、需求背景
|
||
|
||
### 1.1 业务问题
|
||
|
||
常见 IT 故障依赖坐席个人经验排查，容易出现步骤遗漏、处理口径不一致、新坐席上手慢，以及员工转人工后重复描述和重复排查等问题。当前仓库已经存在“排查流程图管理”页面、坐席排查步骤组件和员工 H5 自助排查页面，但数据契约、持久化、发布机制和跨端执行闭环尚未完成。
|
||
|
||
### 1.2 产品定位
|
||
|
||
“排查流程图管理”是**分诊排查系统的管理入口**，负责将高频故障的标准排查方法沉淀为可发布、可执行、可追踪的模板。产品统一名称建议为“分诊排查管理”，流程图是模板内容的一种表达方式，不是独立绘图工具。
|
||
|
||
完整链路：
|
||
|
||
`管理员编制模板 → 校验与发布 → 坐席/员工选择或被推荐模板 → 按节点执行 → 记录路径与结果 → 未解决时携带上下文转人工 → 运营数据回流优化模板`
|
||
|
||
### 1.3 目标用户
|
||
|
||
| 角色 | 主要诉求 |
|
||
|---|---|
|
||
| IT 支持组长/管理员 | 统一维护排查标准，控制版本和发布范围，查看使用效果 |
|
||
| 呼叫坐席 | 快速选择模板、按步骤推进，避免遗漏，完整记录排查过程 |
|
||
| 员工 | 对常见问题进行低门槛自助排查，未解决时无损转人工 |
|
||
| 运营/质量管理员 | 分析模板采用率、解决率、断点和过期内容 |
|
||
|
||
---
|
||
|
||
## 二、目标与成功标准
|
||
|
||
### 2.1 用户目标
|
||
|
||
1. 管理员能在一个入口完成模板创建、校验、预览、发布、停用和版本回滚。
|
||
2. 坐席能在会话中 10 秒内定位并启动合适模板，执行状态与会话绑定。
|
||
3. 员工能按清晰步骤自助排查，转人工时自动携带已完成路径。
|
||
4. 管理者可追踪模板是否有效，而不是只统计“建了多少模板”。
|
||
|
||
### 2.2 业务目标
|
||
|
||
| 指标 | 口径 | 上线后 30 天成功阈值 | 远期目标 |
|
||
|---|---|---:|---:|
|
||
| 模板采用率 | 启动模板的适用会话数 / 适用会话总数 | ≥40% | ≥65% |
|
||
| 模板完成率 | 到达结束节点的执行实例 / 启动实例 | ≥70% | ≥85% |
|
||
| 模板辅助解决率 | 标记“已解决”的完成实例 / 完成实例 | ≥45% | ≥60% |
|
||
| 员工自助解决率 | 无需转人工的自助实例 / 自助启动实例 | ≥20% | ≥35% |
|
||
| 重复排查率 | 转人工后重复执行已完成节点的实例 / 转人工实例 | ≤10% | ≤5% |
|
||
| 模板执行异常率 | 死路、无后继、同步失败实例 / 启动实例 | ≤2% | ≤1% |
|
||
|
||
> 当前无可信基线，目标值为首版假设；上线前需通过埋点获取 2 周基线并评审调整。
|
||
|
||
---
|
||
|
||
## 三、范围
|
||
|
||
### 3.1 P0：生产可用最小闭环
|
||
|
||
1. **模板列表**：按名称、分类、状态搜索；显示版本、节点数、预估时间、最后发布人和更新时间。
|
||
2. **模板编辑**：维护基本信息和节点树；支持步骤节点、判断节点、结束节点及是/否分支。
|
||
3. **结构校验**：保存前检查根节点、节点 ID 唯一性、分支完整性、不可达节点、循环和结束节点。
|
||
4. **草稿与发布**：编辑只产生草稿；发布后生成不可变版本；已发布版本供执行端使用。
|
||
5. **版本管理**：查看历史版本、版本差异、回滚为新草稿；禁止直接覆盖历史版本。
|
||
6. **启用与停用**：停用后不可新启动，但已有执行实例可继续完成。
|
||
7. **权限与审计**：管理员可维护；坐席和员工只读已发布模板；记录创建、修改、发布、停用、回滚和删除操作。
|
||
8. **坐席执行**：模板启动、节点推进、分支选择、暂停/恢复、结束；执行状态绑定会话并持久化。
|
||
9. **员工自助**：查看可用模板、按节点执行、反馈是否解决；转人工时传递模板版本、已完成节点、选择路径和备注。
|
||
10. **导入导出**：使用统一 JSON Schema；单条导入、单条导出、全部导出；导入先校验再进入草稿。
|
||
11. **问诊模板**：通过 `purpose` 字段统一管理，单实例（`code=triage_intake`），由路由层兜底自动启动；实例来源 `triage_fallback`，不计入模板完成率和模板辅助解决率；问诊结束自动回到标准模板选择界面（路由 + 手动双轨），详见 §5.4.4 和 §5.4.8。
|
||
12. **purpose 字段管理**：所有模板主记录新增 `purpose` 字段，值域 `troubleshooting` / `triage`，新建时强制选择且事后不允许切换；编辑器、列表、API 全部按 `purpose` 区分校验规则集、列表 Tab 和筛选条件，详见 §5.4.8。
|
||
|
||
### 3.2 P1：体验与运营增强
|
||
|
||
- AI 根据会话意图推荐模板，默认模板直接启动，详见 §5.4。
|
||
- 节点绑定知识库文章、下载文件、检测接口或审批入口。
|
||
- 模板灰度发布、适用部门/角色范围和定时生效。
|
||
- 使用漏斗、节点退出率、版本效果对比和过期提醒。
|
||
- 可视化拖拽编辑器；首版仍可保留 JSON 高级编辑能力。
|
||
|
||
### 3.3 P2：远期能力
|
||
|
||
- 节点触发自动化修复动作并支持回滚。
|
||
- 基于历史成功路径自动推荐模板优化方案。
|
||
- 模板跨租户/跨组织共享与模板市场。
|
||
|
||
### 3.4 非目标（Non-goals）
|
||
|
||
1. **不建设通用 BPM 工作流引擎**：首版只服务 IT 故障排查，不承载审批和复杂业务编排。
|
||
2. **不直接自动执行高风险命令**：涉及终端变更、账号权限和安全策略的动作另行走自动化审批与审计。
|
||
3. **不替代知识库**：模板负责顺序和决策，详细知识内容通过引用关联。
|
||
4. **不让 AI 自动发布模板**：AI 可建议，发布责任仍由具备权限的管理员承担。
|
||
5. **不追求自由画布制图**：首版优先保证结构化、可校验、可执行，而不是视觉排版自由度。
|
||
|
||
---
|
||
|
||
## 四、用户故事
|
||
|
||
### 4.1 管理员
|
||
|
||
- 作为 IT 支持组长，我希望把 VPN、邮箱、账号等故障沉淀为标准模板，以便不同坐席按同一口径处理。
|
||
- 作为模板管理员，我希望发布前获得结构校验结果，以便避免断路、死循环和缺失分支进入生产。
|
||
- 作为模板管理员，我希望修改已发布模板时产生新版本，以便进行追溯、回滚和效果比较。
|
||
- 作为质量管理员，我希望查看模板采用率、完成率和节点退出率，以便持续优化无效步骤。
|
||
|
||
### 4.2 呼叫坐席
|
||
|
||
- 作为呼叫坐席，我希望根据员工问题快速搜索并启动模板，以便减少判断成本。
|
||
- 作为呼叫坐席，我希望看到当前步骤、已完成步骤和后续分支，以便清楚掌握排查进度。
|
||
- 作为呼叫坐席，我希望暂停后恢复同一执行实例，以便处理长耗时或跨班次问题。
|
||
|
||
### 4.3 员工
|
||
|
||
- 作为员工，我希望按照易懂的步骤完成自助排查，以便常见问题无需等待坐席。
|
||
- 作为员工，我希望在未解决时一键转人工，并自动携带已做过的操作，以便不重复描述和排查。
|
||
- 作为员工，我希望明确知道某一步是否会修改设备或账号，以便在执行前作出知情选择。
|
||
|
||
---
|
||
|
||
## 五、核心业务流程
|
||
|
||
### 5.1 模板生命周期
|
||
|
||
1. 管理员新建或导入模板，系统创建草稿。
|
||
2. 编辑基本信息、节点、分支、说明和风险提示。
|
||
3. 系统执行语法校验和结构校验；失败时禁止发布。
|
||
4. 管理员预览坐席端和员工端呈现效果。
|
||
5. 管理员填写版本说明并发布，生成版本快照。
|
||
6. 执行端只读取已发布且启用的版本。
|
||
7. 后续修改从已发布版本复制为新草稿；重新发布产生新版本。
|
||
8. 停用模板后禁止新启动；历史实例仍关联原版本快照。
|
||
|
||
### 5.2 坐席协同执行
|
||
|
||
模板选择采用 **“统一路由推荐 + 坐席手动覆盖”** 的双轨策略，详细策略见 §5.4。
|
||
|
||
1. 路由层根据员工描述、会话上下文、历史成功率推荐默认模板和候选模板。
|
||
2. 路由推荐结果**直接启动**默认模板的执行实例；坐席无需点击二次确认弹窗，会话区立即出现排查步骤栏。
|
||
3. 启动实例同时记录 `conversation_id`、`employee_id`、`agent_id`、`template_version_id`、`source`（`ai_recommend` / `agent`）和起始时间。
|
||
4. 坐席可以随时通过排查栏顶部的 “换其他模板” 入口手动覆盖；手动切换会触发确认提示，详见 §5.4。
|
||
5. 坐席完成步骤或选择判断分支，后端计算下一个合法节点并实时同步给会话双方。
|
||
6. 任一方断线重连时，从服务端恢复执行状态。
|
||
7. 结束时记录“已解决/未解决/转其他流程”、耗时、备注和终止原因。
|
||
|
||
### 5.3 员工自助转人工
|
||
|
||
1. 员工从 H5 选择已发布模板并开始自助排查。
|
||
2. 系统逐步展示节点，不暴露不相关分支和内部运维信息。
|
||
3. 员工选择“未解决/需要人工”时，创建或关联会话。
|
||
4. 坐席接入后可查看执行摘要，并从当前节点继续或重新选择模板。
|
||
|
||
---
|
||
|
||
### 5.4 模板选择策略 · 路由推荐与手动覆盖
|
||
|
||
#### 5.4.1 策略总览
|
||
|
||
坐席端采用 **“统一路由推荐 + 手动覆盖”** 的双轨结构：
|
||
|
||
- 路由层负责默认选择，坐席负责最终决定。
|
||
- 路由层不直接修改会话状态，只产生推荐结果；模板启动命令由坐席端发起或由路由层在坐席无操作时自动触发。
|
||
- 手动覆盖始终是合法路径，不被路由层阻断。
|
||
- **问诊模板结束时自动回到标准模板选择界面（路由 + 手动双轨）**，由服务端在执行 `triage_fallback` 实例的结束命令时复位路由状态，确保问诊不会把会话卡在兜底分支。
|
||
|
||
#### 5.4.2 路由层职责
|
||
|
||
| 输入 | 输出 |
|
||
|---|---|
|
||
| 员工首句描述、会话上下文、历史类似会话、AI 意图识别结果 | 默认模板 + 2~3 个候选模板 + 每个候选的推荐理由与置信度 |
|
||
| 员工补充信息或会话状态变化 | 重新计算候选并刷新推荐 |
|
||
| 路由无任何匹配 | 触发兜底 B：自动推荐“问诊对话模板” |
|
||
|
||
#### 5.4.3 启动方式：直接启动
|
||
|
||
1. 路由层给出推荐后，**默认模板直接启动**，不弹出“是否确认启动”的二次确认弹窗。
|
||
2. 排查栏立即出现，展示模板名称、版本、当前节点和“换其他模板”入口。
|
||
3. 若坐席在 3 秒内点击 “换其他模板”，系统视为“立即覆盖”，仍视为手动选择。
|
||
4. 自动启动的实例来源记为 `ai_recommend`，用于统计路由采纳率。
|
||
|
||
#### 5.4.4 路由失败的兜底 B：问诊对话模板
|
||
|
||
1. 当路由无匹配时，由后端创建一个特殊模板 `code=triage_intake`，版本独立维护。
|
||
2. 模板内容是一组短问题与是/否分支，例如：“故障现象是什么 / 是否仅发生在公司网络 / 是否影响其他同事 / 是否重启过终端 / 是否变更过密码”，目的不是排查根因，而是帮助坐席快速收敛问题方向。
|
||
3. 问诊对话模板走与正式模板一致的会话级实例、版本快照、同步和结束流程，不在 UI 上做特殊样式，仅在排查栏顶部显示 “问诊中” 标识。
|
||
4. 问诊模板结束或任一节点触发跳转时，自动回到标准模板选择界面（路由推荐 + 手动覆盖双轨）。
|
||
5. 问诊模板本身不计入“模板完成率”和“模板辅助解决率”，仅作为路由层的服务能力。
|
||
6. 问诊模板在数据库层面通过 `purpose=triage` 标识，与排查共享同一套 Schema、版本、执行实例、状态机和权限机制；不允许独立建表或独立 API。
|
||
7. 同一会话中 `source=triage_fallback` 的活跃实例与普通实例遵循同样的“同会话单活跃实例”约束，问诊实例被取消后下一次路由仍可能再次触发问诊，直到员工描述落入某个排查的覆盖范围。
|
||
|
||
#### 5.4.5 手动切换模板：必须提示并结束当前实例
|
||
|
||
1. 坐席点击 “换其他模板” 时，前端必须弹出确认提示：“切换模板将结束当前排查实例并开始新的实例，是否继续？”。
|
||
2. 确认后：
|
||
- 当前实例状态置为 `cancelled`，写入 `reason="agent_switched_template"`。
|
||
- 新模板创建新执行实例；旧实例的路径摘要保留在会话归档中，但不计入当前活跃会话的执行进度。
|
||
3. 取消则保留当前实例继续推进。
|
||
4. **同一会话同一时刻只允许一个活跃实例**，避免多实例污染指标；该约束由后端在创建实例时校验，同一会话存在 `running` 实例时拒绝新的 `ai_recommend` 自动启动和 `agent` 手动启动。
|
||
|
||
#### 5.4.6 关键交互规则
|
||
|
||
| 场景 | 行为 |
|
||
|---|---|
|
||
| 路由高置信度推荐 | 直接启动默认模板 |
|
||
| 路由低置信度推荐 | 直接启动默认模板 + 在排查栏顶部显示“推荐置信度低，是否换其他模板？”提示 |
|
||
| 路由无匹配 | 自动启动问诊对话模板 |
|
||
| 坐席无操作 | 保持自动启动的实例继续推进 |
|
||
| 坐席主动换模板 | 弹出确认 → 旧实例 cancelled → 启动新实例 |
|
||
| 跨模板跳转（如 VPN → 网络） | 仅由坐席主动发起，不允许路由自动跨模板跳转 |
|
||
|
||
#### 5.4.7 与现有文档的差异说明
|
||
|
||
- 原 §3.2 P1 中描述 “AI 根据会话意图推荐模板，坐席确认后启动” 的措辞在本版被替换为 **“直接启动 + 手动覆盖”**；产品决策点已与本节对齐。
|
||
- 原 §5.2 第 1 步 “坐席在会话中搜索模板或接受 AI 推荐” 调整为 “路由直接启动 + 手动覆盖”，更准确反映实际操作。
|
||
- 原 §3.1 P0 #8 “坐席执行” 仍保留作为后端能力，但 UI 入口与交互由本节定义。
|
||
|
||
---
|
||
|
||
#### 5.4.8 与排查流程图的一体两面关系
|
||
|
||
排查流程（`purpose=troubleshooting`）和问诊对话（`purpose=triage`）**不是两个独立系统**，而是同一个模板体系的两个面向：
|
||
|
||
| 维度 | 排查流程 | 问诊对话 |
|
||
|---|---|---|
|
||
| 主导角色 | 坐席 | 员工 |
|
||
| 目标 | 标准化排查根因 | 收敛故障方向为下一轮排查铺路 |
|
||
| 节点粒度 | 中长流程，可能含终端检测、权限变更 | 短问题与是/否分支，≤10 节点 |
|
||
| 实例来源 | `ai_recommend` / `agent` | `triage_fallback` |
|
||
| 指标归属 | 计入完成率、辅助解决率 | 仅计转化率 |
|
||
| 结束行为 | 已解决/未解决/转其他流程 | 自动回到标准模板选择（路由 + 手动双轨） |
|
||
|
||
**统一规则**：
|
||
|
||
1. 数据模型同一份：模板主表、`nodes[]`、版本、执行实例、状态机、WebSocket 同步、权限矩阵全部复用。
|
||
2. 唯一区分字段是 `purpose`，值域 `troubleshooting`（默认）/ `triage`。
|
||
3. 新建模板时强制选择 `purpose`；模板创建后 `purpose` 字段不可修改，只能通过“基于此模板复制为另一种用途”的方式新建。
|
||
4. **UI 必须分而不拆**：管理后台列表按 `purpose` 分 Tab（Troubleshooting / Triage），编辑器顶部加“模板用途”选项，详见 §7.1。
|
||
5. **校验规则必须按 purpose 区分**：结构校验入口加载对应 `purpose` 的规则集，`triage` 模板限制节点数 ≤10、深度 ≤4、强制包含结束节点且 `result=redirect`、标签必须包含 `triage` 或 `intake`，详见 §6.1 FR-04。
|
||
6. **指标必须显式隔离**：指标服务层硬编码 `source=triage_fallback` 的实例不计入 `troubleshooting_*` 指标，仅计入 `troubleshooting_template_start_total{source=triage_conversion}` 转化率指标，详见 §11。
|
||
7. **权限必须显式隔离**：`triage` 模板对员工**始终可见**，对坐席**始终只读**，不参与排查的部门/角色过滤矩阵，详见 §8.2。
|
||
8. **禁止新增独立页面或独立 API**：`triage` 模板的入口、编辑、列表、导入导出全部复用现有分诊排查管理页面，不引入“问诊模板管理”新页面。
|
||
|
||
**一体两面的承诺**：用户在任一端（员工或坐席）看到的模板都来自同一份后端真相，只是 `purpose` 不同；运营和开发只需要维护一套系统。
|
||
|
||
---
|
||
|
||
## 六、功能需求与验收标准
|
||
|
||
### 6.1 模板管理
|
||
|
||
| 编号 | 需求 | 优先级 | 验收标准摘要 |
|
||
|---|---|---|---|
|
||
| FR-01 | 列表搜索、分类和状态过滤 | P0 | 组合筛选结果准确，空状态有引导 |
|
||
| FR-02 | 新建、复制、编辑、预览、归档 | P0 | 操作有权限校验和审计记录 |
|
||
| FR-03 | 节点树编辑和 JSON 高级编辑 | P0 | 两种模式使用同一 Schema，切换不丢数据 |
|
||
| FR-04 | 结构校验 | P0 | 无根、重复 ID、缺失分支、循环、无结束节点禁止发布；按 `purpose` 加载校验规则集：`troubleshooting` 节点数 ≤100、深度 ≤20；`triage` 节点数 ≤10、深度 ≤4、必须包含结束节点且 `result=redirect`、标签必须含 `triage` 或 `intake` |
|
||
| FR-05 | 草稿、发布、停用、回滚 | P0 | 历史版本不可变，回滚产生新草稿 |
|
||
| FR-06 | 导入导出 | P0 | 导入错误定位到字段/节点；不得静默丢字段；导入时若未声明 `purpose` 默认 `troubleshooting` |
|
||
| FR-07 | 操作审计 | P0 | 可按模板、操作者、动作和日期查询；`purpose` 变更（仅允许在复制新建场景发生）需写入审计 |
|
||
| FR-13 | purpose 字段 | P0 | 模板主记录必含 `purpose` 字段；新建强制选择，事后不可修改；列表筛选和列表 Tab 按 `purpose` 区分 |
|
||
| FR-14 | 问诊模板统一管理 | P0 | 问诊模板与排查共用同一管理入口、编辑器、版本、审计和 API；不在前端新增独立页面，在后端不新增独立表 |
|
||
|
||
### 6.2 执行端
|
||
|
||
| 编号 | 需求 | 优先级 | 验收标准摘要 |
|
||
|---|---|---|---|
|
||
| FR-08 | 创建会话级执行实例 | P0 | 同一会话可暂停恢复；状态持久化 |
|
||
| FR-09 | 服务端推进节点 | P0 | 客户端不能跳至非法节点；分支结果可追溯 |
|
||
| FR-10 | 坐席/员工实时同步 | P0 | 正常网络下状态同步 P95 ≤2 秒；重连后恢复一致 |
|
||
| FR-11 | 自助转人工上下文 | P0 | 坐席能看到模板版本、路径、已完成步骤和员工备注 |
|
||
| FR-12 | 结束结果采集 | P0 | 必填解决结果；异常退出可标记原因 |
|
||
|
||
### 6.3 Given / When / Then
|
||
|
||
1. **发布校验**
|
||
Given 草稿存在缺失的“否”分支，When 管理员点击发布，Then 系统拒绝发布并定位问题节点。
|
||
2. **版本隔离**
|
||
Given 会话正在执行 v1.0，When 管理员发布 v1.1，Then该会话继续执行 v1.0，新会话使用 v1.1。
|
||
3. **停用行为**
|
||
Given 模板已停用，When 新用户搜索模板，Then 不返回该模板；已有执行实例仍可完成。
|
||
4. **跨端同步**
|
||
Given 坐席和员工处于同一执行实例，When 坐席完成节点，Then员工端在 2 秒内显示相同进度。
|
||
5. **断线恢复**
|
||
Given 客户端在第 4 个节点断线，When 重新连接，Then从服务端恢复至第 4 个节点且历史路径完整。
|
||
6. **转人工**
|
||
Given 员工已完成 3 个节点仍未解决，When 点击转人工，Then坐席收到执行摘要且不要求员工重复已完成步骤。
|
||
7. **越权保护**
|
||
Given 普通坐席登录，When 调用创建或发布接口，Then返回 403 并写入安全日志。
|
||
8. **并发保护**
|
||
Given 两名管理员同时编辑同一草稿，When后保存者提交旧版本号，Then返回 409 并提示刷新或比较差异。
|
||
9. **purpose 不可修改**
|
||
Given 已存在模板 `purpose=troubleshooting`，When 尝试修改 `purpose` 字段为 `triage`，Then 返回 400 并提示“请基于此模板复制为另一种用途”。
|
||
10. **问诊模板独立指标**
|
||
Given 路由层无匹配自动启动 `triage_intake` 实例，When 实例结束，Then 该实例不计入 `troubleshooting_template_complete_total` 与 `troubleshooting_template_resolved_total`，仅计入 `troubleshooting_template_start_total{source=triage_conversion}`。
|
||
11. **问诊结束回到标准模板选择**
|
||
Given 问诊实例正常结束，When 坐席回到会话区，Then 排查栏消失并恢复路由 + 手动双轨状态，可由路由层再次推荐新模板。
|
||
12. **Triage 模板可见性**
|
||
Given 员工登录 H5，When 查询可用模板列表，Then `purpose=triage` 的模板始终可见，不受部门或角色可见范围限制。
|
||
|
||
---
|
||
|
||
## 七、信息架构与页面
|
||
|
||
### 7.1 管理后台
|
||
|
||
- 导航：运营配置 / 分诊排查管理
|
||
- 页面：模板列表（**按 `purpose` 分 Tab：Troubleshooting / Triage**）、模板编辑/预览、版本历史、发布确认、操作审计、使用分析（P1）
|
||
- 模板编辑区顶部增加 **“模板用途” 选项**，新建时强制选择 `purpose`，事后不可修改
|
||
- 模板编辑区：基本信息（含 `purpose`）、结构化节点树、JSON 高级模式、实时校验（按 `purpose` 加载校验规则集）、双端预览
|
||
- 排查 Tab 的表头显示当前选中模板的 `purpose` 标识，避免运营误编辑问诊模板为排查
|
||
|
||
### 7.2 坐席工作台
|
||
|
||
- 会话区底部“排查步骤”栏
|
||
- 模板选择器、最优路径、完整决策树、当前节点操作、暂停/结束
|
||
- 展示与会话关联的执行摘要
|
||
- **当执行实例 `source=triage_fallback` 时，排查栏顶部显示 “问诊中” 标识**
|
||
- 问诊实例结束时排查栏收起并恢复路由 + 手动双轨状态
|
||
|
||
### 7.3 员工 H5
|
||
|
||
- 自助排查入口、分类/搜索、模板详情、逐步执行页、解决结果页、转人工确认页
|
||
- 内部敏感说明不向员工显示
|
||
- **员工看到的 Triage 模板永远在分类首位（不参与部门/角色可见范围过滤），且作为路由无匹配时的兜底入口**
|
||
|
||
---
|
||
|
||
## 八、数据、权限与合规要求
|
||
|
||
### 8.1 关键数据
|
||
|
||
- 模板主记录、不可变版本快照、节点定义、执行实例、节点执行日志、发布审计日志。
|
||
- 执行日志仅保存排查必要信息，不在模板节点中采集账号密码、验证码、密钥等敏感数据。
|
||
- 会话归档时应保留模板版本号和路径摘要，避免模板更新后历史记录失真。
|
||
|
||
### 8.2 权限矩阵
|
||
|
||
| 能力 | 管理员/组长 | 呼叫坐席 | 员工 | 审计员 |
|
||
|---|:---:|:---:|:---:|:---:|
|
||
| 查看已发布排查 | ✓ | ✓ | ✓（员工可见范围） | ✓ |
|
||
| 查看已发布问诊模板（`purpose=triage`） | ✓ | ✓（只读） | ✓（**始终可见，不受部门/角色过滤**） | ✓ |
|
||
| 创建/编辑草稿 | ✓ | - | - | - |
|
||
| 发布/停用/回滚 | ✓ | - | - | - |
|
||
| 修改 `purpose` 字段 | -（创建后不可修改） | - | - | - |
|
||
| 启动与执行 | 可测试 | ✓ | ✓（triage 永远允许） | - |
|
||
| 查看执行明细 | ✓ | 当前会话 | 本人实例 | ✓ |
|
||
| 查看审计日志 | ✓ | - | - | ✓ |
|
||
|
||
### 8.3 合规
|
||
|
||
- 操作日志和执行日志按照最小必要原则采集，并遵循《个人信息保护法》相关要求。
|
||
- 节点若涉及终端检测、截屏、日志采集或权限变更，必须明确告知用途并按既有授权流程执行。
|
||
- 导出的模板文件不得包含员工个人数据、真实凭据和生产密钥。
|
||
- `purpose=triage` 的模板对员工始终可见，**不得在该模板的可见范围字段中写入敏感过滤条件**（如部门、角色、外部标签），避免出现“兜底模板被过滤掉”的场景。
|
||
|
||
---
|
||
|
||
## 九、依赖与约束
|
||
|
||
1. 依赖管理后台 RBAC、会话服务、WebSocket 单进程消息管理、员工 H5 认证和数据库迁移能力。
|
||
2. 当前实现中后端 CRUD 使用进程内 Mock 数据，正式开发必须切换到数据库。
|
||
3. 当前管理端列表期望数组，而后端返回 `{items,total}`，需统一接口契约。
|
||
4. 当前存在 `flowchart`、`root_node`、`path_steps` 多套结构，必须建立唯一 Schema 和迁移规则。
|
||
5. 当前 H5 自助页面未正式注册路由，坐席与员工执行状态未形成后端闭环。
|
||
|
||
---
|
||
|
||
## 十、风险与对策
|
||
|
||
| 风险 | 影响 | 对策 |
|
||
|---|---|---|
|
||
| 模板内容过时 | 引导错误，扩大故障 | 设置负责人、复审周期、过期提醒和一键停用 |
|
||
| 流程结构复杂 | 管理成本和执行放弃率上升 | 限制深度，提供结构校验和双端预览 |
|
||
| 发布修改影响执行中会话 | 历史路径失真 | 执行实例固定绑定版本快照 |
|
||
| 双端状态不一致 | 重复或跳步 | 服务端作为唯一状态源，事件幂等和重连恢复 |
|
||
| 模板包含敏感信息 | 合规与安全风险 | 字段审查、导出脱敏、发布权限和审计 |
|
||
| 指标驱动坐席机械执行 | 忽略个案 | 允许合规跳出并记录原因，不以完成率单一考核 |
|
||
| 路由推荐结果不可信时坐席仍机械跟随 | 排查方向偏差 | 路由低置信度时显示提示；问诊模板兜底；手动覆盖始终开放 |
|
||
| 同一会话存在多个并发实例 | 指标污染、转人工摘要混乱 | 服务端约束“同一会话同一时刻仅一个活跃实例”；手动切换前必须确认 |
|
||
|
||
---
|
||
|
||
## 十一、开放问题
|
||
|
||
| 问题 | 责任方 | 是否阻塞 |
|
||
|---|---|:---:|
|
||
| 模板发布权限是否仅限管理员，还是组长也可发布？ | 产品/安全 | 是 |
|
||
| 员工可见模板是否按部门、设备或角色过滤？ | 产品/运营 | 是 |
|
||
| 已发布模板删除采用归档还是硬删除？建议仅归档 | 产品/技术 | 是 |
|
||
| 模板节点最大深度和节点数量限制 | 产品/技术 | 否 |
|
||
| 执行日志保留期限及会话归档策略 | 安全/合规 | 是 |
|
||
| 首批生产模板的负责人和复审周期 | 运营 | 否 |
|
||
|
||
---
|
||
|
||
## 十二、上线阶段建议
|
||
|
||
1. **阶段 A：管理闭环**——数据库持久化、统一 Schema、草稿/发布/版本、RBAC、审计。
|
||
2. **阶段 B：坐席闭环**——会话级实例、步骤推进、暂停恢复、结果采集。
|
||
3. **阶段 C：员工自助**——H5 路由、双端同步、转人工上下文。
|
||
4. **阶段 D：智能与运营**——AI 推荐、效果看板、灰度和内容治理。
|
||
|
||
上线闸门：P0 验收通过、独立测试用例完备、端到端验证通过、部署与回滚方案齐备后，方可标记为生产可用。
|
||
|
||
---
|
||
|
||
## 十三、变更记录
|
||
|
||
| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|
||
|---|---|---|---|---|
|
||
| 2026-06-06 | v1.0 | 创建简版 PRD，定义排查步骤栏、数据模型和基础 API | 宋献 | 初始需求 |
|
||
| 2026-07-28 | v1.1 | 补充产品定位、角色与场景、完整范围、非目标、指标、权限、验收标准、风险和生产化路线 | Duckula | 文档规范化补充，解决存量文档不完整问题 |
|
||
| 2026-07-28 | v1.2 | 新增 §5.4 模板选择策略：明确“统一路由推荐 + 手动覆盖”双轨；路由推荐默认模板直接启动；路由无匹配时兜底使用问诊对话模板；手动切换模板必须确认并结束当前实例；同会话单实例约束由后端校验 | 宋献 + Duckula | 完成坐席端选择策略的产品决策 |
|
||
| 2026-07-28 | v1.3 | 升级到“一体两面”模型：所有模板通过 `purpose` 字段（`troubleshooting`/`triage`）统一管理；§3.1 P0 新增 #11 问诊模板与 #12 purpose 字段；新增 §5.4.8 “与排查流程图的一体两面关系”；§6.1 新增 FR-13/FR-14；§6.3 新增验收用例 #9~#12；§7 页面分 Tab + 模板用途选项 + 问诊中标识；§8.2 权限矩阵拆分排查/问诊；§11 指标增加 `triage_conversion`；§13 变更记录追加 | 宋献 + Duckula | 落实用户决策：排查流程与问诊对话是同一系统的两个面向，通过 `purpose` 区分而非分系统 |
|