wecom_it_smart_desk/docs/02-技术文档/技术架构/技术方案-REQ-通用-005-选项选择持久化-v1.1-正式方案.md

技术方案（正式）— 选项选择持久化 v1.1

REQ 编号: REQ-通用-005 版本: v1.1 — 正式方案（基于设计稿 + 用户 5 决策） 日期: 2026-08-02 作者: 高见远（架构师 · Bob） 状态: ✅ 可执行（无需再评审修复路径） 基线: v1.0 技术方案（已部署生产，35 条用例验收通过；本次只增不删） 输入:

• PRD v1.1 增量草案：docs/01-产品文档/00-产品规划/PRD-REQ-通用-005-选项选择持久化-v1.1-增量草案.md（许清楚，2026-08-02）
• 设计稿：本文档前序章节（v1.1 — 方案设计.md，2026-08-02）
• 用户 5 决策（2026-08-02 18:10 接收）：
  1. 修复顺序：Bug 6 → Bug 4 → Bug 5 → Req 7
  2. Dify v3 导入：2026-08-09 前导入（用户承诺）
  3. Req 7 时延指标：< 100ms 端到端（员工→坐席）
  4. Bug 5 视觉分组：方案 1（程序计算分组，不拉 UX）
  5. BackendObserver 监控埋点：✅ 同意作为 Step 4 强制交付

---

§0 变更记录（v1.1 正式方案相对设计稿的差异）

#	项	设计稿（v1.1 设计）	v1.1 正式方案	原因
1	修复顺序	P0 优先级按"风险/价值"建议：Bug 6 → Bug 4 → Bug 5 → Req 7	采纳设计稿建议 + 用户正式确认	决策 1
2	任务粒度	5 步（Step 1~5），粒度偏粗	4 任务（Task 1~4），按"功能模块 + 依赖"合并，符合 P0 5 任务上限	工程派工更清晰
3	Bug 4 修复点	3 个文件（ws.py:407 / conversation.ts:1395 / h5_ai_task.py:443）	同设计稿	已 read/grep 验证
4	Bug 5 视觉分组	方案 1（程序计算分组）	采纳方案 1，不加 UX 流程	决策 4
5	Req 7 监控	"建议"扩展 BackendObserver	强制交付：BackendObserver 单例 + 2 个指标 + E2E puppeteer 脚本	决策 5
6	Req 7 时延预算	单 worker < 50ms；跨 worker 需 Redis Pub/Sub	端到端 < 100ms（员工点选项→坐席渲染 ✓）	决策 3
7	H5 mask 漏洞	设计稿未提及	顺手修复（h5.py:1025）补 v1.0 §4.8 要求	Bug 6 根因分析 A 场景已暴露
8	Dify 依赖	"若 1 周内不导入则先发 B6+Req7"	Dify 2026-08-09 前导入，4 Task 时间窗内可用	决策 2
9	dist 强校验	4 证据链（dist 关键字 + 产物 hash + HTTP 200 + 浏览器实测）	同设计稿，但强制作为合并门禁	历史踩坑（v0.5/v1.0 P0-B/P0-C）

---

§1 架构概览（v1.0 + v1.1 增量点）

1.1 v1.0 基线（不重复，仅作参照）

v1.0 已部署生产的稳定架构：员工点击 → sendOptionSelect（conversation.ts:1621-1737）生成 UUID + 6 字段 → _handle_option_select（ws.py:254-448）走 pg_advisory_xact_lock + 5s 幂等 → messages 表 INSERT → ws_manager.broadcast 给坐席（ws.py:407） → process_h5_ai_reply（h5_ai_task.py:443）推 ai_reply 给员工。Dify 5 字段 inputs、敏感词 16 位中间 4 位 mask、转人工 selected_options 快照、5 重 UUID 守卫（conversation.ts:1662-1680）皆在 v1.0 验收通过。

1.2 v1.1 增量点（4 处补丁，不改变 v1.0 数据契约）

v1.0 → v1.1 增量架构图（增量点用 ★ 标注）

员工 → H5 ChatPanel   【★ 1】MessageBubble.vue:332 派生计算（不依赖内存 ref）
   ↓                   【★ 5】useH5WebSocket.ts:174 计算 RTT+上报
WS → ws._handle_option_select
   ├─ DB (commit) ─┐
   │                ├─【★ 2a】ws.py:407 同时 broadcast_to_employees([employee_id])
   │                │           (同步把员工的 option_select 推给员工端)
   ├─ ws_manager.broadcast (坐席)  【★ 4a】BackendObserver 落库 commit_ts vs 广播 send_ts
   └─ process_h5_ai_reply
        └─【★ 2b】h5_ai_task.py:443 broadcast_to_employees ai_reply (现状 OK)
              └─【★ 2c】h5_ai_task.py:443 在 Dify still_thinking 15s 兜底再广播 option_select 确认
【★ 3】ChatPanel.vue:96 视觉分组（option_select 按 question_id 折叠）
Dify Workflow  → ai_thinking → ai_reply → 选项气泡 ✓

1.3 v1.1 关键不变量（与 v1.0 兼容）

不变量	v1.1 行为
6 字段 inputs	❌ 不变（PRD v1.0 §4.6）
5 重 UUID 守卫	❌ 不变（conversation.ts:1662-1680）
msg_type 枚举	❌ 不变：option_select / text / ai_structured / ...
extra_data 字段	❌ 不变：question_id / option_id / option_value / client_msg_id / selected_from_message_id / option_label_masked
observer 指标命名规范	🆕 见 §7：option_select_* 前缀
--workers 1	❌ 不变（deploy-server/docker-compose.yml:115）

---

§2 任务分解（按决策 1 顺序：Bug 6 → Bug 4 → Bug 5 → Req 7）

任务粒度原则：每个任务 ≥ 3 个相关文件；按"功能模块 + 依赖"合并；T01 是基础设施。

Task T01：项目基础设施（强制前置）

字段	内容
目标	确认依赖、安装脚本、CI 强校验关卡 ready
文件清单	package.json（H5 + Agent）、pnpm-workspace.yaml、deploy-server/docker-compose.yml、scripts/build-and-verify.sh（新增 4 证据链）
行数估算	< 30
验证标准	pnpm install 通过；docker compose config 校验通过；scripts/build-and-verify.sh 4 证据链脚本可执行
强校验证据	① pnpm-lock.yaml hash；② docker-compose config OK；③ 4 证据链脚本存在；④ CI pipeline green

Task T02：修复 Bug 6 — 刷新后选项 ✓ 视觉丢失（前置 / 解锁 QA）

字段	内容
目标	isOptionSelected 从 store 内存 ref 改为派生自 messages（刷新生效）
文件清单	(a) src/frontend-h5/src/components/chat/MessageBubble.vue:332-343（isOptionSelected 重写，从 messages 过滤 msg_type==='option_select'）；(b) src/frontend-h5/src/stores/conversation.ts:241（MessageBubble 调用点，从 selectedOptionLabels 切到 computed 暴露的 selectedOptionIdsFromHistory）；(c) src/backend/app/api/h5.py:1025（顺手修复 v1.0 §4.8 mask 漏洞，对 option_select 调用 mask_sensitive_text(content)）
行数估算	< 60
验证标准	① H5 选选项 → ✓ 显示；② 浏览器刷新 → ✓ 依然显示；③ 长会话 (≥ 60 条) 滚动到顶部 → 早期选项 ✓ 依然显示；④ REST 返回的 option_select content 已 mask
强校验证据	① dist 含 filteredOptionIdsFromHistory 派生关键字；② dist 含 h5_mask_v1_1 函数调用痕迹；③ pytest src/backend/tests/test_h5_mask_option_select.py -v 通过；④ 浏览器实测截图 + dist hash

Task T03：修复 Bug 4 — 员工端 AI 回答延迟显示（核心痛点）

字段	内容
目标	员工选选项后立即看到 ✓ 气泡；Dify 回 ai_reply 即使 conversation_id 微偏差也能落 UI
文件清单	(a) src/backend/app/api/ws.py:407-421（在 ws_manager.broadcast 给坐席之后追加 ws_manager.broadcast_to_employees([employee_id], {...}) 同步推自己的 option_select，确保员工端先看到 ✓）；(b) src/frontend-h5/src/stores/conversation.ts:1395-1401（handleAiReply 软校验：conversation_id 不匹配时 console.warn + 仍尝试落 UI，仅当 message_id 已处理才 return）；(c) src/backend/app/tasks/h5_ai_task.py:443-458（在 broadcast_to_employees ai_reply 之前，增加 broadcast_to_employees option_select 确认事件，作为 still_thinking 兜底）
行数估算	< 80
验证标准	① 模拟弱网（puppeteer throttle 1Mbps + 100ms RTT）→ 选项后 < 500ms 看到 ✓；② 会话切换竞态 → 切换前选项仍在 UI；③ 强校验 4 证据链
强校验证据	① dist 含 broadcast_to_employees_option_select 关键字；② dist 含 soft_match_fallback 关键字；③ ws.py 走 grep "broadcast_to_employees" 命中 2 处（ws.py + h5_ai_task.py）；④ BackendObserver option_select_broadcast_latency_ms 指标可见

Task T04：修复 Bug 5 + Req 7 — 视觉分组 + 时延监控埋点（合并任务）

注：决策 1 顺序为 Bug 5 → Req 7；本任务按"功能聚合"合并，因 Req 7 监控依赖 dist 与 BackendObserver 基础设施，与 Bug 5 视觉分组在同一前端 release 周期内。决策 5 强制 Req 7 监控，故两者绑定。

字段	内容
目标	(a) Bug 5：按 question_id 折叠视觉分组（方案 1，不拉 UX）；(b) Req 7：BackendObserver 埋点 + 端到端测量脚本
文件清单	(a) src/frontend-h5/src/components/chat/MessageBubble.vue:174-179（option_select 模板加 data-question-id 属性 + collapsed class）；(b) src/frontend-h5/src/components/chat/ChatPanel.vue:96-112（store.messages 改 computed groupedMessagesByQuestion，连续同 question_id 折叠为 1 组）；(c) src/backend/app/services/backend_observer.py（新增单例，含 record_event(metric_name, value, tags) + 4 个指标：option_select_persist_latency_ms / option_select_broadcast_latency_ms / option_select_e2e_latency_ms / option_select_dify_timeout_count）；(d) src/backend/app/api/ws.py:407 + src/backend/app/tasks/h5_ai_task.py:443（嵌入 BackendObserver 计时点）；(e) src/frontend-h5/scripts/measure-option-latency.mjs（新增 puppeteer 脚本：员工点击 → WS 收到 → 坐席渲染 ✓，输出 p50/p95 + BackendObserver 查询 URL）
行数估算	< 200
验证标准	① Bug 5：选同一 question 不同 option → 上次选项灰底折叠，新选项高亮，新 AI 答案紧随；② Req 7：测量脚本 p95 < 100ms；BackendObserver GET /api/backend-observer/metrics 返回 4 指标
强校验证据	① dist 含 collapsed-question-group class 关键字；② dist 含 BackendObserver.record_event 调用痕迹；③ puppeteer 脚本测量日志 p95 < 100ms；④ BackendObserver /metrics HTTP 200 + 含 4 指标

2.5 任务依赖图

graph TD
    T01[T01: 项目基础设施] --> T02[T02: Bug 6 — 刷新 ✓ 派生]
    T01 --> T03[T03: Bug 4 — 员工端 AI 延迟]
    T01 --> T04[T04: Bug 5 视觉分组 + Req 7 监控]
    T02 --> T04
    T03 --> T04

顺序备注：T02（Bug 6）可在 T01 后立即并行开发，因只影响 H5 端。T03（Bug 4）跨前后端，但与 T02 无文件冲突，可并行。T04（Bug 5 + Req 7）依赖 T02/T03 落地后集成测试。决策 1 是上线顺序，不是开发顺序。

---

§3 数据结构和接口（类图）

classDiagram
    direction LR

    %% ====== 数据模型（已存在） ======
    class Message {
        +UUID id
        +UUID conversation_id
        +string sender_type
        +string sender_id
        +string content
        +string msg_type
        +dict extra_data
        +datetime created_at
        +string status
    }

    class OptionSelectExtraData {
        +string question_id
        +string option_id
        +string option_value
        +string client_msg_id
        +string selected_from_message_id
        +string option_label_masked
        +string option_label_original (DB only)
    }
    OptionSelectExtraData --o Message : embedded in extra_data JSONB

    %% ====== 服务类（已存在 + v1.1 新增） ======
    class OptionSelectHandler {
        +__init__(session_factory)
        +handle(payload, employee_id) Message
        -acquire_advisory_lock(db, key)
        -find_duplicate(db, payload)
        -persist(db, payload, employee_id)
    }

    class ConnectionManager {
        +dict active_connections
        +dict employee_connections
        +__init__()
        +broadcast(data)
        +broadcast_to_employees(ids, data)
    }
    OptionSelectHandler --> ConnectionManager : broadcast + broadcast_to_employees (v1.1)

    %% ★ 新增 v1.1
    class BackendObserver {
        <<singleton>>
        +list events
        +record_event(metric_name, value, tags) void
        +get_metrics(name_filter) list
        +metric_names$ list~string~
    }
    ConnectionManager ..> BackendObserver : 触发时延记录
    OptionSelectHandler ..> BackendObserver : commit_ts 记录

    class SensitiveMask {
        <<utility>>
        +mask_sensitive_text(text) string
        +mask_sensitive_value(value) string
    }
    %% ★ H5 REST 端点 v1.1 修复：调用 mask
    class H5MessageEndpoint {
        +h5_get_messages(limit, before)
        -_mask_outbound(messages) list
    }
    H5MessageEndpoint --> SensitiveMask : masks option_select content

    %% ====== 前端 store / component ======
    class ConversationStore {
        +Message[] messages
        +bool wsConnected
        +Ref~string[]~ selectedOptionLabels (deprecated v1.1)
        +Ref~string[]~ selectedOptionIdsFromHistory (v1.1 ★)
        +sendOptionSelect(value,label,sourceId,qId,oId) void
        +handleNewMessage(data) void
        +handleAiReply(data) void [v1.1 软校验]
        +groupedMessagesByQuestion() Message[] (v1.1 ★)
        +latestSelectionForQuestion(qId) string|null
    }
    ConversationStore o-- Message : owns

    class MessageBubble {
        +Message msg
        +bool isLatestInGroup
        +bool isOptionSelectedComputed (v1.1 ★)
        +computed data-question-id (v1.1 ★)
    }
    MessageBubble --> ConversationStore : reads messages + isOptionSelectedComputed
    MessageBubble --> Message : renders

    class ChatPanel {
        +computed groupedMessages (v1.1 ★)
        +render bubbles
    }
    ChatPanel --> ConversationStore : groupedMessagesByQuestion
    ChatPanel --> MessageBubble : iter

    class UseH5WebSocket {
        +Ref wsConnected
        +computed rttMs (v1.1 ★)
        +onmessage handler
    }
    UseH5WebSocket --> BackendObserver : 上报 e2e latency (HTTP)
    UseH5WebSocket --> ConversationStore : dispatches handleNewMessage / handleAiReply

    class MeasureOptionLatencyScript {
        <<puppeteer script, v1.1 ★>>
        +run() Report
        -employeeClick() timestamp
        -agentRender() timestamp
        -diff() ms
    }
    MeasureOptionLatencyScript ..> BackendObserver : queries /metrics

3.1 v1.1 新增 / 修改的对外契约

接口	位置	变更
BackendObserver.record_event(name, value, tags)	src/backend/app/services/backend_observer.py	新增
BackendObserver.get_metrics(name_filter)	同上	新增，供运维/前端查询
GET /api/backend-observer/metrics?name=option_select_*	新增路由	新增（只读，最近 N 条，JSON）
ConversationStore.selectedOptionIdsFromHistory	conversation.ts 新增 computed	新增，替换 selectedOptionLabels 的视觉判定
ConversationStore.groupedMessagesByQuestion	同上	新增（Bug 5）
WSManager.broadcast_to_employees([employee_id], data)	已有，新增调用点	ws.py:407 之后
h5_get_messages 返回值对 option_select.content 做 mask	h5.py:1025	修复（v1.0 §4.8）

---

§4 程序调用流程（4 个时序）

时序 ① — 点选-广播-落库（Bug 6 主链路，含 T02 + T03）

sequenceDiagram
    autonumber
    actor Emp as 员工
    participant MB as MessageBubble
    participant Store as ConversationStore
    participant WS as ws._handle_option_select
    participant DB as PostgreSQL
    participant WSM as ws_manager
    participant Obs as BackendObserver
    participant Task as process_h5_ai_reply

    Emp->>MB: 点击 option
    MB->>Store: sendOptionSelect(value,label,...)
    Note over Store: lastSentOptionContent=label<br/>optionSubmitting=true<br/>5 重 UUID 守卫判定
    Store->>WS: option_select(6 字段 + client_msg_id)

    WS->>WS: UUID 校验
    WS->>DB: BEGIN + pg_advisory_xact_lock
    WS->>DB: SELECT 5s 内同 UUID
    alt 5s 内重复
        DB-->>WS: 命中 dup
        WS-->>Store: 无副作用，结束
    else 首次
        WS->>DB: INSERT Message(msg_type=option_select)
        DB-->>WS: commit_ts = T1
        %% ★ v1.1 T03: 同步推员工端
        WS->>WSM: broadcast_to_employees([employee_id], new_message)
        WSM-->>Store: new_message (employee 端)
        Store->>Store: trackProcessedMessageId + push message
        Note over Store: 员工立即看到 ✓ 气泡<br/>(不再依赖 Dify 兜底)
        %% 既有的坐席广播
        WS->>WSM: broadcast(new_message) (坐席)
        WSM-->>Obs: 记录 broadcast_ts = T2
        Obs-->>Obs: option_select_broadcast_latency_ms = T2 - T1
        WS->>Task: create_task(process_h5_ai_reply)
    end

    Note over Obs,T1: ★ v1.1 Req 7：T2-T1 应 < 50ms（单 worker）

时序 ② — AI 回复回流（T03 Bug 4 软校验 + T02 派生）

sequenceDiagram
    autonumber
    participant Dify as Dify Workflow
    participant Task as process_h5_ai_reply
    participant DB as PostgreSQL
    participant WSM as ws_manager
    participant WS as H5 useH5WebSocket
    participant Store as ConversationStore
    participant MB as MessageBubble (员工)

    Dify-->>Task: 返回结构化 reply
    Task->>DB: INSERT Message(ai_text)
    DB-->>Task: commit
    %% ★ v1.1 T03: still_thinking 兜底 option_select 确认（若 Dify 超时）
    Task->>WSM: broadcast_to_employees(option_select confirm) [if still_thinking]
    WSM->>WS: ai_reply { type: "ai_reply", data: {...} }
    WS->>Store: handleAiReply(data)
    Note over Store: ★ v1.1 Bug 4 软校验:<br/>conversation_id 不匹配 → console.warn<br/>但不再 return，继续 push<br/>（仅 message_id 已去重才 return）
    Store->>Store: trackProcessedMessageId
    Store->>Store: messages.value.push(finalMessage)
    Store-->>MB: reactive 触发重渲
    MB->>MB: 显示 AI 答案气泡（打字机逐字）
    Note over MB: ★ v1.1 T02 派生：<br/>isOptionSelected 改为从 messages 过滤<br/>msg_type==='option_select' by question_id<br/>不再依赖内存 ref

    MB->>MB: 渲染 ✓ (历史选项) + AI 答案（新）

时序 ③ — 视觉分组（T04 Bug 5）

sequenceDiagram
    autonumber
    actor Emp as 员工
    participant Store as ConversationStore
    participant Panel as ChatPanel
    participant MB as MessageBubble

    Note over Store: messages 序列:<br/>[ai_structured Q1]<br/>[option_select Q1.optA] <-- 第 1 次<br/>[ai_text 回复1]<br/>[option_select Q1.optB] <-- 第 2 次（重选）<br/>[ai_text 回复2]

    Emp->>Store: 选 Q1.optB
    Store->>Store: sendOptionSelect → WS
    Note over Store: groupedMessagesByQuestion (v1.1 ★)<br/>按 question_id 相邻聚合<br/>折叠：Q1.optA 标 collapsed class<br/>高亮：Q1.optB 当前选项

    Panel->>MB: v-for msg in groupedMessages
    MB->>MB: option_select 分支加 data-question-id="Q1"
    alt collapsed (历史同题选项)
        MB->>MB: class="message-bubble--option-select collapsed"<br/>背景灰底 + 折叠图标 ▾
    else current (本次选项)
        MB->>MB: class="message-bubble--option-select active"<br/>蓝底 + ✓
    end
    MB->>MB: ai_text 紧随其后，按时间顺序独立出现
    Note over MB: ★ 顺序：① ✓当前 ② AI 思考占位 ③ AI 答案

时序 ④ — 时延监控埋点与端到端测量（T04 Req 7）

sequenceDiagram
    autonumber
    actor Emp as 员工 (Chromium A)
    actor Agent as 坐席 (Chromium B)
    participant H5Emp as H5 useH5WebSocket (Emp)
    participant H5Agt as H5 useH5WebSocket (Agt)
    participant WS as ws._handle_option_select
    participant WSM as ws_manager
    participant Obs as BackendObserver
    participant Script as measure-option-latency.mjs

    Script->>Script: 启动双 context + login
    Script->>Script: t0 = performance.now()

    Emp->>H5Emp: click option
    H5Emp->>WS: option_select payload
    H5Emp->>H5Emp: 记录 client_send_ts = T0

    WS->>WSM: broadcast_to_employees + broadcast
    WSM->>H5Agt: new_message(option_select)
    H5Agt->>H5Agt: 渲染 ✓
    H5Agt->>Script: postMessage { event: 'rendered', ts: T_agent }

    H5Emp->>H5Emp: 收到自己的 new_message (员工端)
    H5Emp->>Obs: POST /api/backend-observer/record<br/>{metric: 'option_select_e2e_latency_ms',<br/>value: T_agent - T0}
    WSM->>Obs: 记录 option_select_persist_latency_ms<br/>option_select_broadcast_latency_ms

    Script->>Script: t1 = performance.now() (员工点击到坐席渲染)
    Script->>Obs: GET /api/backend-observer/metrics?name=option_select_*
    Obs-->>Script: 4 个指标
    Script->>Script: p50/p95 计算 + 告警 (>100ms warning)
    Script->>Script: 输出 report.json

---

§5 依赖包列表

包	版本约束	用途	是否新增
puppeteer	^23.0.0（devDependencies）	Req 7 端到端时延测量脚本	🆕 新增
Promise.withResolvers	浏览器原生（Chrome 119+）	useH5WebSocket RTT 计算（无新依赖）	❌ 沿用
Vue 3 + Pinia + Vite	已存在	全部前端	❌ 不变
FastAPI + SQLAlchemy Async	已存在	后端	❌ 不变
BackendObserver	自研单例模块（无外部依赖）	监控埋点	🆕 新模块，无第三方包

结论：v1.1 仅新增 puppeteer（devDependency，仅供 scripts/measure-option-latency.mjs 使用）。生产构建产物体积不受影响。BackendObserver 为自研文件，不引入 Prometheus 等重型依赖，符合"轻量观测"原则。

---

§6 共享知识（跨文件约定）

6.1 msg_type 枚举（不变）

值	出处	v1.1 行为
option_select	选项确认（员工点选）	❌ 不变
text	普通文本	❌ 不变
ai_structured	AI 结构化（含 options）	❌ 不变
ai_text	AI 纯文本	❌ 不变
file / image / voice	媒体	❌ 不变

6.2 extra_data 字段规范（option_select 类）

{
  "question_id": "stable-question-uuid-or-slug",  // 必填
  "option_id":   "stable-option-id",               // 必填
  "option_value": "backend-value",                 // 必填
  "client_msg_id": "uuid-v4",                      // 必填（幂等键）
  "selected_from_message_id": "msg-uuid",          // 必填（归属题目的消息）
  "option_label_masked": "*** **** 5678",          // 仅外发
  "option_label_original": "..."                   // 仅 DB 存，外部不外发
}

v1.1 不引入新字段；仅在 h5_get_messages 输出时确保 content（即 option_label）被 masked。

6.3 BackendObserver 指标命名规范（🆕 v1.1）

指标名	类型	单位	标签	触发点
option_select_persist_latency_ms	histogram	ms	conv_id	DB commit 后
option_select_broadcast_latency_ms	histogram	ms	conv_id	ws_manager.broadcast 前
option_select_e2e_latency_ms	histogram	ms	conv_id	员工端 useH5WebSocket 计算
option_select_dify_timeout_count	counter	integer	conv_id	h5_ai_task.py:443 still_thinking 触发时

命名约定：{feature}_{aspect}_{metric}_{unit}，全小写 + 下划线。禁止用驼峰或简写。

6.4 强校验 4 证据链（dist 发布门禁）

每次 Bugfix 合并前必须出具：

1. dist 关键字：grep 产物包含功能特征字符串（见各 Task 强校验列）
2. 产物 hash：sha256sum dist/**/*.{js,css} 输出 ≥ 1 行变化
3. HTTP 200：curl -I https://h5.example.com/ 返回 200/304
4. 浏览器实测：puppeteer 截图 + 控制台无 ERROR

6.5 WS 事件类型（不变，但 v1.1 增加 1 个新）

type	方向	说明
new_message	双通道（坐席 + 员工 v1.1）	通用消息，含 option_select
ai_thinking	双通道	AI 思考占位
ai_reply	仅员工	AI 终态
🆕 option_select_confirm	仅员工（still_thinking 兜底）	Dify 超时 15s 后由后端主动补发

---

§7 测试用例增量（基于决策 5 BackendObserver 指标 + 4 步 E2E）

7.1 BackendObserver 指标验收（新增 P0 用例）

TC ID	名称	步骤	预期	强校验
TC-v1.1-001	BackendObserver option_select_persist_latency_ms 存在	启动后端 + 触发 option_select → GET /api/backend-observer/metrics?name=option_select_persist_latency_ms	返回 ≥ 1 条样本，p50 < 30ms	curl 返回 JSON 含 metric + samples
TC-v1.1-002	option_select_broadcast_latency_ms p95 < 50ms	同上，连续触发 100 次	p95 < 50ms（单 worker）	report.json p95 字段
TC-v1.1-003	option_select_e2e_latency_ms p95 < 100ms	puppeteer 脚本 100 次	p95 < 100ms（端到端）	measure-option-latency.mjs 输出
TC-v1.1-004	option_select_dify_timeout_count 累加	模拟 Dify 30s 超时	counter +1	Obs metrics
TC-v1.1-005	metrics 端点鉴权	直接 GET（无 token）	401 Unauthorized	curl 状态码

7.2 4 步 E2E（覆盖决策 1 全链路）

TC ID	步骤	期望	关联 Task
TC-v1.1-101	Bug 6 验收：选选项 → 浏览器刷新 → ✓ 仍在	H5 ✓ 显示，且选项按 server_timestamp 升序	T02
TC-v1.1-102	Bug 6 验收：长会话 (>50 条) → 滚动顶 → 早期选项可见	REST limit=50 触发翻页 before，✓ 可见	T02
TC-v1.1-103	Bug 6 验收：H5 REST 返回 option_select content 已 mask	16 位数字中间 4 位 ****	T02
TC-v1.1-201	Bug 4 验收：员工端弱网（throttle 1Mbps + 100ms RTT）下选选项	< 500ms 看到 ✓	T03
TC-v1.1-202	Bug 4 验收：会话切换竞态 → 切换前选项仍在 UI	可见（软校验 fallback）	T03
TC-v1.1-203	Bug 4 验收：Dify 30s 超时 → still_thinking 触发 option_select_confirm	员工端收到 confirm 事件	T03
TC-v1.1-301	Bug 5 验收：选同一 question 不同 option → 上次折叠 + 新选项高亮 + AI 答案紧随	3 个 UI 元素独立出现	T04
TC-v1.1-302	Bug 5 验收：不同 question 的 option 不互相折叠	视觉分组按 question_id 边界	T04
TC-v1.1-401	Req 7 验收：在线坐席端 p95 < 100ms	measure-option-latency.mjs 通过	T04
TC-v1.1-402	Req 7 验收：坐席离线 → 重连 REST → option_select 在历史中	curl GET 含 option_select 行	T04
TC-v1.1-403	Req 7 验收：弱网 (502) → 3s 轮询 fallback 可见	轮询触发，含 option_select	T04

7.3 回归用例（v1.0 TC-REQ-通用-005 必须全过）

• AC-01 / AC-03 / AC-04 / AC-10（35 条用例）全部通过
• 6 项 v1.0 决策不变性测试（撤回/重选、5s UUID、跨卡归属、敏感词、Dify inputs、转人工快照）

---

§8 风险与部署 checklist

8.1 风险矩阵

风险	等级	触发条件	缓解
Dify v3 仍未导入（决策 2）	中	用户 2026-08-09 前未导入 → Bug 4/5 修复用户感知不到	v1.1 Task T04 时已 deadline；超出则跳过 Bug 4/5，先发 T02（Bug 6 不依赖 Dify）
dist 缓存复用（v0.5/v1.0 P0-B 踩坑）	中	浏览器命中旧 dist	4 证据链 + 强制加 ?v= + nginx Cache-Control: no-cache
H5 processedMessageIds 误伤（v1.0 P0-C 修复后）	中	conversation 切换时未清空	T03 修复时核对该集合 clear() 时机（store setActiveConversation 处）
BackendObserver 单进程内存累积	低	长时间运行 events 列表增长	v1.1 用 collections.deque(maxlen=10000)；v1.2+ 落 Prometheus
--workers 1 单例	低	v1.0 已固定，本次不变	deploy-server/docker-compose.yml:115 强校验
isOptionSelected 派生性能	低	长会话消息过滤 O(n)	O(n) 在 store 的 computed 内 Vue 自动缓存；单 component 重渲才重算
mask 函数调用埋点失败导致 500	低	h5.py:1025 引入 mask 后若函数抛错	mask_sensitive_text 已 try/except；fail-open 返回原 content

8.2 部署 checklist（含 dist 强校验 4 证据链）

□ Step 0  前置：Dify v3 已导入（决策 2 deadline 2026-08-09）
□ Step 1  T01 基础设施：pnpm install / docker compose config OK / 4 证据链脚本就绪
□ Step 2  T02 Bug 6：
    □ 2.1 后端 rebuild image → push private registry
    □ 2.2 H5 dist build → 上传 CDN
      强校验证据链 ①：grep "filteredOptionIdsFromHistory" dist/**/*.js ✓
      强校验证据链 ②：sha256sum dist/**/*.{js,css} 与上一版有差异 ✓
      强校验证据链 ③：curl -I https://h5.example.com/ → 200 ✓
      强校验证据链 ④：puppeteer 刷新 → ✓ 仍显示 + 截图 ✓
    □ 2.3 后端 container restart（仍 --workers 1）
    □ 2.4 验收：TC-v1.1-101 / 102 / 103 通过
□ Step 3  T03 Bug 4：
    □ 3.1 后端 patch：ws.py:407 + h5_ai_task.py:443 → rebuild
    □ 3.2 H5 patch：conversation.ts:1395 软校验 → dist rebuild
      强校验证据链 ①：grep "broadcast_to_employees.*option_select" dist/**/*.js ✓
      强校验证据链 ②：sha256sum 输出有新行 ✓
      强校验证据链 ③：curl 主入口 200 ✓
      强校验证据链 ④：puppeteer 弱网 throttle 测试 → < 500ms 看到 ✓
    □ 3.3 验收：TC-v1.1-201 / 202 / 203 通过
□ Step 4  T04 Bug 5 + Req 7（合并发布）：
    □ 4.1 BackendObserver 单例部署 + /metrics 路由上线
    □ 4.2 dist rebuild（视觉分组 + RTT 上报）
    □ 4.3 measure-option-latency.mjs 跑 100 次 → p95 < 100ms
      强校验证据链 ①：grep "collapsed-question-group" dist/**/*.js ✓
      强校验证据链 ②：BackendObserver metrics 4 个指标均存在 ✓
      强校验证据链 ③：curl /metrics → 200 + JSON ✓
      强校验证据链 ④：puppeteer + report.json p95 < 100ms ✓
    □ 4.4 验收：TC-v1.1-301 / 302 / 401 / 402 / 403 通过
□ Step 5  全量回归：v1.0 35 条 TC-REQ-通用-005 用例全过
□ Step 6  灰度：H5 灰度 10% → 50% → 100%（坐席端无灰度，因 WS 改动向后兼容）
□ Step 7  监控观察 24h：BackendObserver p95 + 上报成功率 ≥ 99%
□ Step 8  收尾：废弃 selectedOptionLabels 引用（v1.1 标记 deprecated，v1.2 删除）

8.3 回滚策略

场景	回滚动作
T02 发布后 Bug 6 未解或引入新 bug	回滚 H5 dist 到上一版（CDN 一键）+ 后端 image tag 回滚
T03 发布后员工端选项不显示	后端 ws.py:407 broadcast_to_employees 一行注释即可关闭
T04 发布后 p95 > 100ms	BackendObserver 持续告警；保留埋点但回滚 dist 视觉分组
任一步骤导致坐席端 regress	坐席端 v1.0 代码未被本次任何 Task 修改，回滚不影响坐席

---

§9 附录：v1.1 与 v1.0 决策一致性自检

v1.0 决策	v1.1 是否触动	证据
撤回/重选（追加新行）	❌	T02/T03/T04 均不动 INSERT 逻辑
5s UUID 幂等	❌	ws.py:316-323 幂等 SQL 未改
跨卡归属（question_id + option_id）	❌	T04 Bug 5 视觉分组按 question_id 折叠，正是该决策的强化
敏感词 16 位中间 4 位 mask	✅（修复漏洞）	h5.py:1025 补 mask → 由 mask 漏洞转一致
Dify 5 字段 inputs	❌	ws.py:433-439 feedback_context 未改
转人工 selected_options 快照	❌	不在本次范围
5 重 UUID 守卫	❌	conversation.ts:1662-1680 视为 T02/T03 修复前提

---

§10 变更记录

版本	日期	变更内容	变更人
v1.0	2026-07-29	初版技术方案（523 行，11 章节）	高见远、宋献
v1.1 设计稿	2026-08-02	4 问题根因 + 修复路径（不进开发）	高见远、宋献
v1.1 正式方案	2026-08-02	基于设计稿 + 用户 5 决策正式化；4 任务（含合并 T04）；类图 + 4 时序；BackendObserver 强制交付；dist 4 证据链；2026-08-09 Dify 导入门槛	高见远

---

下一步：方案冻结 → 工程师寇豆码按 T01→T02→T03→T04 顺序派工 → QA 在 v1.0 TC-REQ-通用-005 基础上扩 TC-v1.1-001~403（13 条新用例） → Dify v3 2026-08-09 前必须导入 → 灰度上线。