docs: add ticket support lifecycle manual

docs/operations/ticket-support-lifecycle-manual.md

@@ -0,0 +1,440 @@
+# 技术支持工单全流程操作手册
+
+## 1. 文档目的
+
+本文面向一线技术支持人员，说明如何在 AI 工单平台中完成以下闭环：
+
+1. 提交客户问题材料并创建工单。
+2. 补全信息、接管和进入处理。
+3. 运行支持分析并核对引用依据。
+4. 记录内部排查和客户沟通。
+5. 提交客户确认、填写解决结论并关闭工单。
+6. 评估知识沉淀价值并复核运行审计。
+
+本文同时记录 2026-07-28 使用真实浏览器完成的一次端到端体验。实测产生的工单是
+`TK202607280003`，工单 ID 为 `18`。文中的客户、组织和故障场景均为本地演练数据。
+
+## 2. 流程总览
+
+```mermaid
+flowchart LR
+    A["提交材料"] --> B["AI 智能受理"]
+    B --> C["待补充 pending_info"]
+    C --> D["待处理 pending"]
+    D --> E["处理中 in_progress"]
+    E --> F["待确认 pending_confirm"]
+    F --> G["已解决 resolved"]
+    G --> H["知识价值评估"]
+    H --> I["已关闭 closed"]
+    B -. "模型或受理失败" .-> J["人工表单/人工接管"]
+    E -. "分析无可信引用" .-> K["人工排查"]
+    J --> D
+    K --> F
+```
+
+标准原则：
+
+- AI 输出是排查辅助，不替代技术支持对事实、风险和解决结论的确认。
+- 支持分析没有正式引用时，只能用于人工排查，不允许自动复用或自动解决。
+- 内部备注和客户可见记录用途不同；客户可见记录也不等同于渠道已经发送。
+- 工单关闭前必须有明确的解决方案、客户确认和处理说明。
+- 知识沉淀只能进入受治理流程，不能绕过审核直接发布。
+
+## 3. 操作前准备
+
+| 检查项 | 要求 |
+|---|---|
+| 登录身份 | 具备工单创建、编辑、状态流转、支持分析和关闭权限 |
+| 后端服务 | Django API 可用 |
+| 异步服务 | Redis 和 Celery Worker 可用，否则智能受理与 Agent 运行会停在排队状态 |
+| 模型配置 | 智能受理 Agent 和支持分析 Agent 已发布，模型渠道连通 |
+| 知识配置 | 如需知识沉淀，知识蒸馏 Agent 必须已发布 |
+| 材料安全 | 不上传令牌、Cookie、密码、完整会话标识或未脱敏日志 |
+
+本次实测环境：
+
+| 项目 | 实际值 |
+|---|---|
+| 日期 | 2026-07-28，Asia/Shanghai |
+| 前端 | `http://localhost:5173` |
+| 浏览器 | Codex 内置真实浏览器，桌面视口 1440 × 1000 |
+| 登录身份 | 本地管理员演示账号 |
+| 创建方式 | 智能受理，仅提交文本材料 |
+| 演练工单 | `TK202607280003` / ID `18` |
+| 受理运行 | Agent 运行 `#56` |
+| 支持分析运行 | `1e2f4b06-b786-4916-97f0-69e4b9ceed96` |
+
+## 4. 标准操作步骤
+
+### 4.1 登录并进入创建页
+
+1. 打开平台登录页并登录。
+2. 在工作台点击“新建工单”。
+3. 默认选择“智能受理”；需要完全人工录入时切换到“普通表单”。
+
+检查点：
+
+- 页面应显示“提交材料、智能解析、补全事实、正式建单”四个阶段。
+- 桌面端应允许输入和上传材料；移动端当前仅支持查看。
+
+![智能受理创建页](images/ticket-lifecycle/01-create-intake.jpg)
+
+### 4.2 提交问题材料
+
+在“聊天记录或补充说明”中尽量提供：
+
+- 发生时间。
+- 业务系统、模块和环境。
+- 问题表现与错误信息。
+- 影响范围。
+- 已尝试动作。
+- 期望结果和客户诉求。
+
+本次演练材料：
+
+> 生产环境单点登录回调后持续白屏，影响上海财务团队约 25 人；控制台报
+> `OIDC_STATE_MISMATCH`，清理缓存并重新登录仍复现。
+
+点击“开始智能受理”后，不要重复提交。运行页应依次展示材料解析、事实提取、结构化字段、
+创建工单和完成事件。
+
+![智能受理运行中](images/ticket-lifecycle/02-intake-running.jpg)
+
+异常处理：
+
+- 长时间没有事件：检查 Celery Worker、Redis 和 Agent 运行记录。
+- 模型或解析失败：保留原材料，使用“转人工”或普通表单继续。
+- 信息不足：按页面追问补充，不要重复创建另一张工单。
+
+### 4.3 核对自动建单结果
+
+智能受理成功后会自动进入正式工单详情。技术支持必须核对：
+
+- 标题是否准确、简洁。
+- 问题描述是否忠实于材料。
+- 环境、对象、系统和影响范围是否正确。
+- 优先级是否与业务影响匹配。
+- 是否存在缺失字段和字段证据冲突。
+
+本次实测自动提取结果：
+
+| 字段 | 结果 |
+|---|---|
+| 标题 | 财务系统单点登录回调白屏 |
+| 状态 | 待补充 |
+| 优先级 | 高 |
+| 环境 | 生产环境 |
+| 对象 | 财务系统 Web 端 |
+| 影响范围 | 上海财务团队约 25 人 |
+| 错误信息 | `OIDC_STATE_MISMATCH` |
+| 缺失信息 | 客户最后消息时间、问题开始时间、关联系统、支持首次响应时间、支持最后回复时间 |
+
+![自动创建的待补充工单](images/ticket-lifecycle/03-ticket-pending-info.jpg)
+
+### 4.4 补全信息并人工接管
+
+1. 点击页头主操作“立即补全”。
+2. 只填写能够从材料或沟通中确认的事实；不确定的时间保持为空。
+3. 保存后确认缺失数量下降，活动流出现字段修改记录。
+4. 信息足够时进入“更多工单操作”，选择“转为待处理”。
+5. 流转说明应解释已确认的事实、仍需排查的内容和接管原因。
+
+推荐流转说明：
+
+> 已核对问题描述、环境、影响范围与错误码，现由人工接管进入待处理，后续核对认证回调、
+> 会话 Cookie 和服务端日志。
+
+### 4.5 分派并开始处理
+
+标准流程应先完成处理人分派，再开始排查：
+
+1. 在待处理状态点击“分派处理人”。
+2. 选择责任人并保存。
+3. 确认页头显示处理人。
+4. 点击主操作“开始处理”，或在“更多工单操作”中选择“开始处理”。
+5. 填写处理计划后提交，状态变为“处理中”。
+
+建议处理计划至少包含：
+
+- 首轮排查范围。
+- 需要核对的日志、配置或依赖。
+- 是否需要客户补充材料。
+- 生产变更风险和回滚要求。
+
+### 4.6 运行支持分析
+
+在“处理中”状态点击“开始支持分析”。运行中需要关注：
+
+- Agent 发布版本。
+- 冻结依据数量。
+- 开始时间。
+- 是否禁止重复启动。
+- “运行轨迹”是否可打开。
+
+![支持分析运行中](images/ticket-lifecycle/04-support-analysis-running.jpg)
+
+分析完成后按以下顺序阅读：
+
+1. 分析结论。
+2. 建议排查顺序。
+3. Agent 推荐方案和自动化策略。
+4. 客户回复任务。
+5. 正式引用依据和全部冻结候选。
+
+可信边界：
+
+- 只有 `citations` 指定的冻结依据才是本次输出的正式引用。
+- 没有正式引用时，页面应明确提示“仅供人工排查，不允许自动复用”。
+- 推荐方案必须来自本次冻结依据中的 `candidate_solution_ids`。
+- 涉及生产变更、匹配度不足或策略未通过时，必须人工处理。
+
+本次分析未引用任何冻结依据，最终被标记为失败并要求人工接管。系统仍保留了分析摘要、
+5 个排查步骤和回复草稿，未推荐解决方案，也没有执行自动解决。
+
+![支持分析安全降级](images/ticket-lifecycle/05-support-analysis-degraded.jpg)
+
+### 4.7 记录人工排查结果
+
+点击“继续人工排查”，在活动流顶部添加“内部备注”。内容建议使用以下结构：
+
+```text
+复现结果：
+检查范围：
+根因判断：
+已执行动作：
+验证结果：
+风险与回滚：
+下一步：
+```
+
+本次演练记录的根因是回调域名变更后，Cookie Domain 与 SameSite 配置未覆盖新域；
+测试环境修正后复测通过，生产变更等待确认。
+
+保存后检查：
+
+- 活动流按时间倒序显示。
+- 记录标记为“仅内部”。
+- 系统事件和人工备注能够区分。
+
+### 4.8 记录客户沟通
+
+1. 将“记录可见范围”切换为“客户可见记录”。
+2. 记录已经向客户说明的进展、验证请求和下一次反馈时间。
+3. 保存后检查活动流标记为“客户可见”。
+
+注意：
+
+- 客户可见记录只表示业务记录的可见范围。
+- 实际编辑、发送和送达确认应由正式 `CustomerReplyTask` 完成。
+- 不应以客户可见记录代替渠道发送。
+
+### 4.9 提交客户确认
+
+完成技术验证和客户沟通后：
+
+1. 打开“更多工单操作”。
+2. 选择“提交确认”。
+3. 填写已执行修复、技术复测结果以及需要客户确认的事项。
+4. 提交后状态变为“待确认”。
+
+![等待客户确认](images/ticket-lifecycle/06-pending-customer-confirmation.jpg)
+
+标准情况下，此阶段应出现正式客户回复任务，可编辑回复、发送到渠道并确认送达。
+
+### 4.10 标记解决
+
+客户确认恢复后点击“标记解决”，填写：
+
+- 解决方案：具体配置、代码、数据或操作变更。
+- 处理说明：客户确认、验证范围、监控和回滚信息。
+- 已回复客户：确认实际已完成客户回复后再开启。
+
+本次解决方案：
+
+> 将认证回调新域名加入 Cookie Domain 范围，并将回调 Cookie 调整为
+> `SameSite=None; Secure`；清理旧会话后重新登录，生产复测正常。
+
+提交后状态变为“已解决”，支持分析结果转为只读。
+
+### 4.11 知识沉淀
+
+在已解决状态展开“知识沉淀”：
+
+1. 查看是否已经自动生成知识价值评估。
+2. 如尚未生成，点击“评估知识价值”。
+3. 评估通过后只生成受治理草稿。
+4. 草稿必须经过审核和发布，才能重新进入检索。
+
+本次环境未发布知识蒸馏 Agent，因此评估没有启动。页面给出了明确失败原因，没有伪造
+知识草稿。
+
+![知识价值评估降级](images/ticket-lifecycle/07-knowledge-governance.jpg)
+
+### 4.12 关闭工单
+
+只有满足以下条件后才关闭：
+
+- 客户已经确认恢复。
+- 解决方案完整。
+- 客户回复状态明确。
+- 监控、风险和回滚信息已记录。
+- 知识沉淀已完成，或已明确登记后续人工任务。
+
+点击“关闭工单”，补充必填的处理说明并提交。关闭后：
+
+- 状态为“已关闭”。
+- 页头不再显示重新分析等处理动作。
+- 支持分析、活动流和运行轨迹保持只读可查。
+- 页面当前任务变为复核关闭记录与知识资产。
+
+![已关闭工单](images/ticket-lifecycle/08-ticket-closed.jpg)
+
+### 4.13 复核运行审计
+
+从支持分析区域点击“运行轨迹”，检查：
+
+- 运行 ID、Agent 版本和终态。
+- 每个步骤的模型、能力和执行结果。
+- 输入、结构化输出和调用尝试。
+- Token、耗时和重试。
+- 配置快照、检索策略和冻结依据。
+- 失败代码与安全降级原因。
+
+本次支持分析审计结果：
+
+| 项目 | 实际值 |
+|---|---|
+| 运行 ID | `1e2f4b06-b786-4916-97f0-69e4b9ceed96` |
+| Agent | 支持分析 Agent，发布 v6 |
+| 模型 | `gpt-5.6-terra`，`vision_chat` |
+| 冻结依据 | 3 条 |
+| 输入 / 输出 Token | 1847 / 502 |
+| 总 Token | 2349 |
+| 总耗时 | 13109 ms |
+| 步骤状态 | `analyze` 成功 |
+| 运行终态 | 失败 |
+| 失败代码 | `untrusted_support_output` |
+| 失败原因 | 支持分析结果必须引用至少一条检索依据 |
+
+步骤成功但运行失败并不矛盾：模型成功返回了结构化结果，但业务信任校验发现
+`citations` 为空，因此拒绝将结果视为可信支持结论。
+
+![Agent 运行审计](images/ticket-lifecycle/09-agent-run-audit.jpg)
+
+## 5. 本次真实浏览器实测记录
+
+| 时间 | 操作 | 状态或结果 |
+|---|---|---|
+| 19:00 | 提交文本材料并启动智能受理 | 运行事件持续更新 |
+| 19:00 | 自动创建正式工单 | `TK202607280003`，状态“待补充” |
+| 19:01 | 补充关联系统并尝试保存业务时间 | 关联系统保存成功，4 个时间字段未保存 |
+| 19:03 | 从更多菜单人工转为待处理 | 成功 |
+| 19:05 | 从更多菜单开始处理 | 成功，但处理人仍未设置 |
+| 19:05 | 启动支持分析 | 冻结 3 条依据，禁止重复启动 |
+| 19:05 | 支持分析结束 | 可信校验失败，安全降级为人工排查 |
+| 19:06 | 保存内部排查结论 | 成功，活动流标记“仅内部” |
+| 19:08 | 保存客户可见进展 | 成功，活动流标记“客户可见” |
+| 19:08 | 提交客户确认 | 状态变为“待确认” |
+| 19:09 | 填写解决方案并标记解决 | 状态变为“已解决” |
+| 19:10 | 启动知识价值评估 | 因未发布知识蒸馏 Agent 而未启动 |
+| 19:12 | 填写关闭说明并关闭工单 | 状态变为“已关闭” |
+| 19:12 | 查看支持分析运行轨迹 | 输入、输出、Token、耗时、快照和失败原因可追溯 |
+
+## 6. 实测发现的问题
+
+### LIFE-01：业务时间填写后未保存
+
+- 严重度：高。
+- 复现：在“补全工单信息”中填写 4 个 `datetime-local` 字段并保存。
+- 实际：表单关闭后 4 个时间字段仍为待补全，没有错误提示。
+- 影响：缺失任务无法自动完成，技术支持容易误以为信息已保存。
+- 建议：修复前端时间序列化或后端字段映射；保存失败时保持表单打开并显示字段级错误。
+
+### LIFE-02：“分派处理人”打开了错误表单
+
+- 严重度：阻断。
+- 复现：待处理状态点击页头主操作“分派处理人”。
+- 实际：打开的是“补全工单信息”，且没有处理人字段。
+- 影响：技术支持无法通过主操作完成责任人分派。
+- 建议：提供独立分派弹窗或在表单中加入处理人字段，并在保存后更新页头。
+
+### LIFE-03：未分派也能进入处理中
+
+- 严重度：高。
+- 复现：处理人未设置时，从“更多工单操作”选择“开始处理”。
+- 实际：状态成功变为“处理中”，页头继续显示“处理人：未设置”。
+- 影响：责任归属与业务状态不一致，工作台和 SLA 统计可能失真。
+- 建议：状态机在进入 `in_progress` 前强制校验处理人，或将当前操作者自动设为处理人并记录事件。
+
+### LIFE-04：正式客户回复任务未生成
+
+- 严重度：高。
+- 复现：支持分析结束后进入待确认状态。
+- 实际：页面长期显示“正在生成正式回复任务”，没有可编辑、发送或确认送达的任务区域。
+- 影响：页面要求使用正式回复任务，但用户只能记录客户可见活动，回复闭环不完整。
+- 建议：失败分析也应创建人工回复任务；任务生成失败要显示重试或人工创建入口，并阻止在未确认回复状态时直接解决。
+
+### LIFE-05：智能受理等待时间显示不准确
+
+- 严重度：中。
+- 实际：受理已经运行数十秒，页面仍显示“已等待 0 秒”；最初长时间停在“准备受理…”。
+- 影响：用户无法判断是否卡住或需要转人工。
+- 建议：以服务端运行时间或稳定的客户端计时器显示耗时，并设置超时、重试和转人工提示。
+
+### LIFE-06：支持检索候选与问题无关
+
+- 严重度：中，属于知识和检索质量问题。
+- 实际：OIDC 回调白屏问题冻结的 3 条依据均为采集账号密码或采集进度内容。
+- 正面表现：可信校验拒绝了无引用输出，没有自动推荐或自动解决。
+- 建议：加强关联系统、模块和错误码的过滤权重；低相关候选不足时明确返回“无可靠依据”。
+
+### LIFE-07：知识沉淀环境未就绪
+
+- 类型：环境配置阻塞。
+- 实际：点击“评估知识价值”提示“尚未发布知识蒸馏 Agent”。
+- 影响：已解决工单不能进入知识草稿流程。
+- 建议：部署验收清单增加知识蒸馏 Agent 发布检查，并在工作台提供配置就绪状态。
+
+### LIFE-08：结束状态仍显示“继续人工排查”
+
+- 严重度：中。
+- 实际：工单已解决或已关闭后，失败的支持分析仍显示“继续人工排查”按钮。
+- 影响：与“结果只读保留”的文案冲突，容易让用户误以为还能修改已结束工单。
+- 建议：结束状态仅保留分析结论、引用和运行轨迹，隐藏所有处理型按钮。
+
+## 7. 当前版本的人工降级路径
+
+当自动能力不可用时，按以下顺序确保工单仍可完成：
+
+1. 智能受理失败：保留材料，切换普通表单或人工接管。
+2. 时间字段无法保存：在内部备注记录已确认时间，并登记缺陷，避免重复建单。
+3. 无法分派：由有权限的支持人员从更多菜单接管；修复前需在线下明确责任人。
+4. 支持分析失败：保留冻结依据和运行 ID，点击“继续人工排查”并记录实际结果。
+5. 正式回复任务缺失：记录客户可见进展，并通过既有受控渠道发送；在活动流记录送达和确认。
+6. 知识评估未启动：在关闭说明中登记原因，后续由知识管理员人工创建草稿。
+
+人工降级不得绕过权限、生产变更审批、客户确认或审计要求。
+
+## 8. 关闭前检查清单
+
+- [ ] 工单标题、描述、环境、系统和影响范围准确。
+- [ ] 处理人明确，责任归属可追溯。
+- [ ] 支持分析结论已核对，引用可信边界清楚。
+- [ ] 实际排查结果已经写入内部备注。
+- [ ] 客户沟通内容和实际送达状态已经记录。
+- [ ] 客户已经确认恢复。
+- [ ] 解决方案、验证范围、风险和回滚信息完整。
+- [ ] “已回复客户”与真实情况一致。
+- [ ] 知识沉淀已完成，或已登记未完成原因与后续责任人。
+- [ ] Agent 运行 ID、配置快照和失败原因可查询。
+
+## 9. 本次实测结论
+
+当前版本能够通过真实浏览器完成：
+
+`智能受理 → 自动建单 → 人工接管 → 处理中 → 支持分析安全降级 → 内部排查 →
+客户可见记录 → 待确认 → 已解决 → 已关闭 → 运行审计`。
+
+状态主线和统一活动流已经具备连续处理能力，支持分析在没有可信引用时也能安全降级。
+但“处理人分派、业务时间保存、正式客户回复任务、知识蒸馏 Agent”仍存在阻断或环境缺口。
+在这些问题关闭前，不建议把本次结果解释为生产业务闭环已经完全通过。