wecom_it_smart_desk/docs/02-技术文档/AI回复三态开关-工程师续载清单.md

AI 回复三态开关（REQ-坐席-010）— 工程师续载清单

创建于 2026-08-04 18:5x 用途：寇豆码在 429 重启后无需重读架构文档，直接据此清单补完剩余 3 件。

权威需求/设计（先读）

• PRD：docs/01-产品文档/04-坐席工作台/PRD-REQ-坐席-010-AI回复三态开关.md
• 技术方案（含 5 任务、行号、Mermaid）：docs/02-技术文档/技术方案-REQ-坐席-010-AI回复三态开关.md
• Mermaid 图：docs/02-技术文档/architecture/REQ-坐席-010-{class-diagram,sequence-diagram}.mermaid

已落盘（不要重写）

T01 数据层

• ✓ src/backend/app/constants/ai_reply_mode.py（62 行）
• ✓ src/backend/app/models/conversation.py line 231 新增 ai_reply_mode: Mapped[str]
• ✓ src/backend/app/schemas/conversation.py line 359 ConversationResponse 加 ai_reply_mode

T02 门控内核

• ✓ src/backend/app/services/ai_reply_gate.py（163 行，6 函数：resolve_mode / conversation_mode / _normalize_status / can_ai_auto_reply_path_a / can_ai_auto_reply_path_b / agent_mirror_enabled / agent_dedicated_message）
• ✓ src/backend/tests/test_ai_reply_gate.py（51 项参数化断言全过 2026-08-04 18:59）

T03 路径 A

• ✓ src/backend/app/services/message_router.py line 187 接入 can_ai_auto_reply_path_a
• ✓ L399 _push_agent_dedicated_message + L567 调用（b 态专属推送）
• ✓ imports constants/ai_reply_gate

T02.5 设置 API

• ✓ src/backend/app/api/conversations.py line 400 PUT /api/conversations/{conversation_id}/ai-reply-mode
• ✓ 含广播 ai_reply_mode_changed WS 事件
• ✓ src/backend/app/services/session_service.py 已加 set_ai_reply_mode

T04 路径 B（含接单后停 AI 缺口修复）

• ✓ src/backend/app/api/h5.py line 946 接 can_ai_auto_reply_path_b（门控在 create_task 之前 ✅）
• ✓ src/backend/app/api/ws.py line 478 同上
• ✓ src/backend/app/tasks/h5_ai_task.py 4 处坐席广播点（L540/817/970/1684）已接 agent_mirror_enabled
• ✓ 2 处 _push_agent_dedicated_message 调用（L567/855）

仍需补完（3 件）

1. Alembic 058 迁移（最简单，可立刻做）

• 文件：src/backend/alembic/versions/058_add_ai_reply_mode.py（仿 057 幂等写法：sa.inspect(bind) 守卫）
• down_revision = '057_troubleshooting_templates'
• 字段：ai_reply_mode = sa.Column("ai_reply_mode", sa.String(20), nullable=False, server_default="employee_only")
• 存量自动套用 server_default，无需数据回填

2. 前端 T05（5 子项）

2a. src/frontend-agent/src/components/chat/ai-assist/AiReplyModeSwitch.vue

• 🤖 图标按钮（复用 .tb-btn 样式）+ el-popover 内 el-radio-group 三态单选
• 三个值：employee_only / employee_and_agent / off，显示中文文案
• 选中即调 setAiReplyMode API
• 当前态高亮（a 正常色 / b 高亮 / off 置灰）

2b. src/frontend-agent/src/components/chat/ReplyBox.vue

• 在 .toolbar-left 之后、.tb-sep 之后、<AiAssistToolbar /> 之前插入 <AiReplyModeSwitch />
• 与 4 个主动 AI 按钮（💡🎚️🖌️🔄）以 .tb-sep 分隔，视觉独立

2c. src/frontend-agent/src/api/（或现有 api 模块）

• setAiReplyMode(conversationId, mode) → PUT /api/conversations/{conversation_id}/ai-reply-mode

2d. conversation store（找已有 conversation store，按 conversationId 存当前 mode）

• action 存 + getter 取；切会话读各自值

2e. WS 监听 ai_reply_mode_changed（不复用 conversation_updated，新增独立 handler）

• payload: {conversation_id, ai_reply_mode}
• 多端同步：收到事件 → 更新 store

3. 修正技术方案文档（按 B 口径）

用户最终澄清（2026-08-04 15:47）：

a 态（employee_only）= AI 只对员工消息/选择作进一步回复；坐席端仍按现状能看到 AI 回复员工的消息。 即：a 维持现状镜像；b 在 a 基础上额外推专属；off 全关。

修正 docs/02-技术文档/技术方案-REQ-坐席-010-AI回复三态开关.md：

• "推坐席"小节：明确 agent_mirror_enabled = (mode != "off")（a/b 都镜像）
• "专属坐席消息"小节：agent_dedicated_message = (mode == "employee_and_agent")（仅 b 推）
• 说明当前实现（h5_ai_task.py + message_router.py 的 _push_agent_dedicated_message）已与本修正口径一致

完成后自测

1. 跑后端：pytest tests/test_ai_reply_gate.py → 期望 51/51
2. 跑前端：pnpm vue-tsc --noEmit（仅 AiReplyModeSwitch.vue 范围无新增错）
3. 全局一致性审查 IS_PASS: YES/NO 重点核对：
   • 字段 ai_reply_mode（不要写成 aiReplyMode / reply_scope）
   • WS 事件 ai_reply_mode_changed（不要复用 conversation_updated）
   • 端点路径 /api/conversations/{conversation_id}/ai-reply-mode
   • 4 个广播点全部已接 agent_mirror_enabled（grep 确认）
   • 不动的 4 个 broadcast_to_employees 未被误改

提交

git add ... && git commit -m "feat(ai-reply-mode): REQ-坐席-010 三态开关完工
- T01 数据层 + alembic 058
- T02 门控内核 + 单测
- T03 路径 A + 坐席专属推送
- T04 路径 B + h5_ai_task 4 广播点收紧 + 接单后停 AI 缺口修复
- T05 前端 AiReplyModeSwitch + 集成 + WS 监听
- 修正技术方案文档'推坐席'小节按 B 口径"

把 commit hash + 改动文件清单 + IS_PASS 结果回传主理人。