747 lines
40 KiB
Markdown
747 lines
40 KiB
Markdown
|
# 工具栏统一设计 v1.3 — 删除 IntegrationZone 坐席按钮 — 架构设计
|
|||
|
|
|
|||
|
|
> **版本**: v1.3
|
|||
|
|
> **日期**: 2026-08-04
|
|||
|
|
> **作者**: 高见远（架构师）
|
|||
|
|
> **需求编号**: REQ-会话-001
|
|||
|
|
> **PRD 基线**: `docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-工具栏统一设计-v1.3.md`
|
|||
|
|
> **原型基线**: `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-工具栏统一设计v1.3-删除IntegrationZone坐席.html`
|
|||
|
|
> **状态**: [待评审]
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
1. [实现方案](#1-实现方案)
|
|||
|
|
2. [框架选型](#2-框架选型)
|
|||
|
|
3. [文件列表及相对路径](#3-文件列表及相对路径)
|
|||
|
|
4. [数据结构和接口（类图）](#4-数据结构和接口类图)
|
|||
|
|
5. [程序调用流程（时序图）](#5-程序调用流程时序图)
|
|||
|
|
6. [任务列表（有序、含依赖关系）](#6-任务列表有序含依赖关系)
|
|||
|
|
7. [依赖包列表](#7-依赖包列表)
|
|||
|
|
8. [共享知识（跨文件约定）](#8-共享知识跨文件约定)
|
|||
|
|
9. [待明确事项](#9-待明确事项)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 实现方案
|
|||
|
|
|
|||
|
|
### 1.1 总体思路（两步走）
|
|||
|
|
|
|||
|
|
PRD 目标单一：删除 `IntegrationZone.vue` 中的"人工坐席"按钮（带锁图标 🔒 那个），让 H5 用户端坐席入口**唯一化**（仅 InputBar 工具栏头像按钮）。
|
|||
|
|
|
|||
|
|
但实际仓库现状偏离基线，需要**两个连续的还原+删除动作**：
|
|||
|
|
|
|||
|
|
1. **Step A — 还原**：本地 `InputBar.vue` 当前是 commit `f9c25147` 留下的"v1.3 错误实施"状态（3 按钮 + 工具栏在 InputBar 底部），与线上 v1.2 不一致。需要先**还原到 v1.2 形态**（4 按钮 + 工具栏在 InputBar 内上方居中 + 坐席头像带 5 色徽标）。
|
|||
|
|
2. **Step B — 删除**：在 InputBar 处于 v1.2 形态后，再按 PRD 删 `IntegrationZone.vue` 中的坐席按钮。
|
|||
|
|
|
|||
|
|
> **历史教训锚点**：v1.3 之前的"删除 InputBar 工具栏头像 + 移动到 InputBar 底部"曾被紧急回滚到 v1.2。本次 v1.3 真实意图 = **恢复 v1.2 形态 + 删 IntegrationZone 冗余入口**，绝不可与中间错误实施混为一谈。
|
|||
|
|
|
|||
|
|
### 1.2 关键设计决策
|
|||
|
|
|
|||
|
|
| 决策 | 理由 |
|
|||
|
|
|------|------|
|
|||
|
|
| **D1**：先恢复 InputBar 再删 IntegrationZone（顺序强制） | 若 InputBar 还未恢复就先删 IntegrationZone，会出现"线上无坐席入口"的事故窗口 |
|
|||
|
|
| **D2**：InputBar 坐席按钮直接调 `store` 副作用（不 emit 给 ChatPanel） | 沿用 f9c25147 commit 的"v1.3.4 单入口"设计；emit 链路需要 ChatPanel 中转，与"工具栏按钮为唯一入口"的轻量化目标冲突 |
|
|||
|
|
| **D3**：ChatPanel 父组件仅清理 `@call-agent` 监听器 + `handleDirectCall` 函数 | `@cancel-queue` / `@end-conversation` / `@reopen-conversation` 仍由 QueueCapsule 透传触发（Q3 限定范围） |
|
|||
|
|
| **D4**：IntegrationZone 模板仅删除 1 个 `<button class="call-agent-btn">` 节点 | QueueCapsule + 引导语 + 容器样式全部保留（PRD REQ-07/08） |
|
|||
|
|
| **D5**：IntegrationZone 4 个 emits 仅删除 `callAgent`，保留其他 3 个 | `cancelQueue` / `endConversation` / `reopenConversation` 仍由 QueueCapsule 透传 |
|
|||
|
|
| **D6**：helper 文件（inputBarCallAgentState.ts / integrationZoneLogic.ts / inputBarGuideText.ts）不动 | Q4 暂搁，6 个月后评估 |
|
|||
|
|
| **D7**：InputBar.test.ts **重写**而非追加 | 当前测试是 v1.3 错误实施"3 按钮 + slideDown"的契约，需要回退到 v1.2"4 按钮 + slideUp"的契约 |
|
|||
|
|
|
|||
|
|
### 1.3 边界与不变量
|
|||
|
|
|
|||
|
|
- **B1**：IntegrationZone.vue 的 QueueCapsule 子组件继续接收 `:agent-online` prop（v1.2 透传契约不变）。
|
|||
|
|
- **B2**：InputBar.vue 的 emoji / 文件 / 语音 3 个按钮行为完全不变（仅位置从底部回退到 InputBar 内上方居中）。
|
|||
|
|
- **B3**：`store.shakeAgent()` / `cancelQueue()` / `reopenCurrentConversation()` / `closeCurrentConversation()` 4 个 action 全部保留。
|
|||
|
|
- **B4**：`inputBarCallAgentState.computeCallAgentState` 6 态优先级与 P1 Bug 修复（waiting + !agentOnline → disabled）不变。
|
|||
|
|
- **B5**：容器组件层级 `ChatPanel > IntegrationZone > QueueCapsule` 不变。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 框架选型
|
|||
|
|
|
|||
|
|
**无任何框架变更**，沿用 v1.2 基线：
|
|||
|
|
|
|||
|
|
| 维度 | 选型 | 版本 | 不变原因 |
|
|||
|
|
|------|------|------|----------|
|
|||
|
|
| 前端框架 | Vue 3 (Composition API + `<script setup>`) | ^3.4 | H5 用户端基线 |
|
|||
|
|
| 状态管理 | Pinia | ^2.1 | store 单例（`useConversationStore`） |
|
|||
|
|
| UI 组件库 | Vant 4 | ^4.8 | H5 移动端基线 |
|
|||
|
|
| 构建工具 | Vite | ^5.0 | H5 项目基线 |
|
|||
|
|
| 样式预处理 | 原生 CSS + scoped（无 Sass/Less） | — | 与现有代码风格一致 |
|
|||
|
|
| 测试框架 | Vitest（纯函数契约测试） | ^1.0 | 沿用 helper 文件的测试范式 |
|
|||
|
|
| 类型系统 | TypeScript | ^5.0 | `<script setup lang="ts">` |
|
|||
|
|
|
|||
|
|
**架构模式**：本任务不涉及架构模式变更（仍是 Component + Store + Helper 三层）。仅在前端 H5 端做局部 DOM/逻辑调整。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 文件列表及相对路径
|
|||
|
|
|
|||
|
|
| 文件 | 改动 | 涉及阶段 | 备注 |
|
|||
|
|
|------|------|----------|------|
|
|||
|
|
| `src/frontend-h5/src/components/chat/InputBar.vue` | **还原**到 v1.2（4 按钮工具栏 + 工具栏 InputBar 内上方居中 + 坐席头像按钮 + 5 色徽标） | T01 | 从 f9c25147 commit 的反向 patch 或手动重做 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/IntegrationZone.vue` | 删除 1 个 `<button class="call-agent-btn">` 节点 + 1 个 `callAgent` emit + 4 个相关 computed + 1 个 handleClick 函数 + 1 处 `.integration-zone .call-agent-btn*` 样式 | T02 | QueueCapsule + 引导语 + 容器样式全部保留 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/ChatPanel.vue` | 清理 `@call-agent="handleDirectCall"` 监听器 + `handleDirectCall` 函数（保留 3 个 QueueCapsule 透传监听器） | T03 | Q3 限定范围：仅 call-agent |
|
|||
|
|
| `src/frontend-h5/src/components/chat/InputBar.test.ts` | **重写**为 v1.3 = v1.2 的契约测试（4 按钮 + 5 色徽标映射 + slideUp 动画） | T04 | 现有测试是错误实施的"3 按钮"契约 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/integrationZoneLogic.test.ts` | **不动** | — | 纯函数不变（Q4） |
|
|||
|
|
| `src/frontend-h5/src/components/chat/integrationZoneLogic.ts` | **不动** | — | helper 保留 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/inputBarCallAgentState.ts` | **不动** | — | helper 保留 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/inputBarGuideText.ts` | **不动** | — | helper 保留 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/QueueCapsule.vue` | **不动** | — | 子组件不变 |
|
|||
|
|
| `src/frontend-h5/src/components/chat/QueueCapsule.test.ts` | **不动** | — | 子组件测试不变（36 用例已 PASS） |
|
|||
|
|
| `src/frontend-h5/src/stores/conversation.ts` | **不动** | — | 4 个 action 全部保留 |
|
|||
|
|
| `src/frontend-h5/src/stores/integrationZone.ts` | **不动** | — | `shiftHours` 班次能力预留 |
|
|||
|
|
|
|||
|
|
**新增文件**：无。
|
|||
|
|
**删除文件**：无。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 数据结构和接口（类图）
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
classDiagram
|
|||
|
|
direction LR
|
|||
|
|
|
|||
|
|
class ChatPanel {
|
|||
|
|
+useConversationStore() ConversationStore
|
|||
|
|
+useEmployeeStore() EmployeeStore
|
|||
|
|
+useIntegrationZoneStore() IntegrationZoneStore
|
|||
|
|
-callAgentState: ComputedRef~CallAgentState~
|
|||
|
|
-guideText: ComputedRef~string|null~
|
|||
|
|
-showExitConfirm: Ref~boolean~
|
|||
|
|
+scrollToBottom() Promise~void~
|
|||
|
|
+handleExitWithEvaluation() Promise~void~
|
|||
|
|
+handleCancelQueue() Promise~void~ // 保留
|
|||
|
|
+handleEndConversation() Promise~void~ // 保留
|
|||
|
|
+handleReopenConversation() Promise~void~ // 保留
|
|||
|
|
-handleDirectCall() Promise~void~ // ⚠️ v1.3 删除（无效监听器）
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class IntegrationZone {
|
|||
|
|
+props: IntegrationZoneProps
|
|||
|
|
-emits: callAgent // ⚠️ v1.3 删除
|
|||
|
|
-emits: cancelQueue // 保留
|
|||
|
|
-emits: endConversation // 保留
|
|||
|
|
-emits: reopenConversation // 保留
|
|||
|
|
-btnText: ComputedRef~string~ // ⚠️ v1.3 删除
|
|||
|
|
-btnIcon: ComputedRef~string~ // ⚠️ v1.3 删除
|
|||
|
|
-btnTitle: ComputedRef~string~ // ⚠️ v1.3 删除
|
|||
|
|
-btnClass: ComputedRef~Record~ // ⚠️ v1.3 删除
|
|||
|
|
-guideClass: ComputedRef~Record~ // 保留
|
|||
|
|
-handleClick() void // ⚠️ v1.3 删除
|
|||
|
|
-render QueueCapsule // 保留
|
|||
|
|
-render guide div // 保留
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class InputBar {
|
|||
|
|
+URGENT_KEYWORDS: RegExp[]
|
|||
|
|
-hasUrgentKeywords: ComputedRef~boolean~
|
|||
|
|
-showEmojiPanel: Ref~boolean~
|
|||
|
|
-inputText: Ref~string~
|
|||
|
|
-callAgentState: ComputedRef~CallAgentState~ // ⚠️ v1.3 重新绑定到模板
|
|||
|
|
-callAgentBtnClass: ComputedRef~Record~ // 🆕 v1.3 恢复
|
|||
|
|
-callAgentBtnIcon: ComputedRef~string~ // 🆕 v1.3 恢复
|
|||
|
|
-callAgentBtnText: ComputedRef~string~ // 🆕 v1.3 恢复
|
|||
|
|
-callAgentBtnTitle: ComputedRef~string~ // 🆕 v1.3 恢复
|
|||
|
|
-voiceBtnState: ComputedRef
|
|||
|
|
-voiceBtnClass: ComputedRef~Record~
|
|||
|
|
-showVoiceButton: ComputedRef~boolean~
|
|||
|
|
+handleEmoji() void
|
|||
|
|
+handleFile() void
|
|||
|
|
+handleVoiceToggle() Promise~void~
|
|||
|
|
+handleCallAgentClick() Promise~void~ // 🆕 v1.3 恢复
|
|||
|
|
+handleSend() Promise~void~
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class QueueCapsule {
|
|||
|
|
+props: QueueCapsuleProps
|
|||
|
|
-emits: cancel-queue
|
|||
|
|
-emits: reopen-conversation
|
|||
|
|
+handleClick() void
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class ConversationStore {
|
|||
|
|
+agentOnline: boolean
|
|||
|
|
+currentConversation: Conversation
|
|||
|
|
+canReopen: boolean
|
|||
|
|
+canCallAgent: boolean
|
|||
|
|
+messages: Message[]
|
|||
|
|
+shakeAgent() Promise~string~
|
|||
|
|
+cancelQueue() Promise~void~
|
|||
|
|
+closeCurrentConversation() Promise~void~
|
|||
|
|
+reopenCurrentConversation() Promise~void~
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class inputBarCallAgentState {
|
|||
|
|
<<module>>
|
|||
|
|
+computeCallAgentState(ctx) CallAgentState
|
|||
|
|
+computeCallAgentBtnText(state) string
|
|||
|
|
+computeCallAgentBtnTitle(state, agentOnline) string
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class integrationZoneLogic {
|
|||
|
|
<<module>>
|
|||
|
|
+computeIntegrationBtnText(state) string
|
|||
|
|
+computeIntegrationBtnIcon(state) string
|
|||
|
|
+computeIntegrationBtnTitle(state, agentOnline) string
|
|||
|
|
+computeIntegrationBtnClass(state) Record
|
|||
|
|
+computeIntegrationGuideClass(text) Record
|
|||
|
|
+computeCallAction(state) EmitEvent|'none'
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class inputBarGuideText {
|
|||
|
|
<<module>>
|
|||
|
|
+computeGuideText(ctx) string|null
|
|||
|
|
+isGuideTextWarn(text) boolean
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ChatPanel "1" --> "1" IntegrationZone : 父→子
|
|||
|
|
ChatPanel "1" --> "1" InputBar : 父→子
|
|||
|
|
IntegrationZone "1" --> "1" QueueCapsule : 父→子
|
|||
|
|
ChatPanel ..> ConversationStore : uses
|
|||
|
|
ChatPanel ..> inputBarCallAgentState : computeCallAgentState
|
|||
|
|
ChatPanel ..> inputBarGuideText : computeGuideText
|
|||
|
|
IntegrationZone ..> integrationZoneLogic : btn/guide/click
|
|||
|
|
InputBar ..> inputBarCallAgentState : 6 态 + 文案 + title
|
|||
|
|
InputBar ..> integrationZoneLogic : btnClass + callAction
|
|||
|
|
InputBar ..> ConversationStore : shakeAgent
|
|||
|
|
QueueCapsule ..> ConversationStore : reopenCurrentConversation
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**图例**：🆕 = v1.3 恢复；⚠️ = v1.3 删除；保留/不动 = 默认无标记。
|
|||
|
|
|
|||
|
|
### 4.1 v1.3 删除的接口（IntegrationZone）
|
|||
|
|
|
|||
|
|
| 接口 | 类型 | 位置 | 删除原因 |
|
|||
|
|
|------|------|------|----------|
|
|||
|
|
| `callAgent` emit | `(e: 'callAgent'): void` | `IntegrationZone.vue:101-102` | 按钮已删除，emit 不再有触发源 |
|
|||
|
|
| `btnText` computed | `ComputedRef<string>` | `IntegrationZone.vue:126` | 依赖 `computeIntegrationBtnText`（无消费者） |
|
|||
|
|
| `btnIcon` computed | `ComputedRef<string>` | `IntegrationZone.vue:131` | 同上 |
|
|||
|
|
| `btnTitle` computed | `ComputedRef<string>` | `IntegrationZone.vue:136` | 同上 |
|
|||
|
|
| `btnClass` computed | `ComputedRef<Record<string, boolean>>` | `IntegrationZone.vue:141` | 同上 |
|
|||
|
|
| `handleClick()` function | `(): void` | `IntegrationZone.vue:167-186` | 无按钮可点击 |
|
|||
|
|
| `call-agent-btn` template node | `<button class="call-agent-btn">` | `IntegrationZone.vue:34-43` | PRD REQ-01 |
|
|||
|
|
| `.integration-zone .call-agent-btn*` styles | CSS (~110 行) | `IntegrationZone.vue:213-321` | PRD REQ-04 |
|
|||
|
|
|
|||
|
|
### 4.2 v1.3 恢复的接口（InputBar）
|
|||
|
|
|
|||
|
|
| 接口 | 类型 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `callAgentBtnClass` | `ComputedRef<Record<string, boolean>>` | 6 态 modifier 映射（沿用 `.call-agent-btn--*` 命名） |
|
|||
|
|
| `callAgentBtnIcon` | `ComputedRef<string>` | 6 态 emoji（🔒 / 🎧 / 🚨 / ⏳ / 📴 / 🔄） |
|
|||
|
|
| `callAgentBtnText` | `ComputedRef<string>` | 6 态文案（"人工坐席" / "排队取消" / "结束咨询" / "重新打开"） |
|
|||
|
|
| `callAgentBtnTitle` | `ComputedRef<string>` | 6 态 title（沿用 `computeCallAgentBtnTitle`） |
|
|||
|
|
| `agent-badge` DOM 节点 | `<div class="agent-badge is-{state}">` | 5 色徽标（online/urgent/waiting/offline/end） |
|
|||
|
|
| `handleCallAgentClick()` | `(): Promise<void>` | 直接调 `store.shakeAgent()` / `cancelQueue()` / `reopenCurrentConversation()`（按 state 路由） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 程序调用流程（时序图）
|
|||
|
|
|
|||
|
|
### 5.1 v1.3 后唯一的坐席入口点击流程
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
autonumber
|
|||
|
|
actor User as H5 用户
|
|||
|
|
participant Toolbar as InputBar 工具栏<br/>(emoji/file/voice/👤坐席)
|
|||
|
|
participant Logic as inputBarCallAgentState.ts
|
|||
|
|
participant Store as useConversationStore
|
|||
|
|
participant Toast as Vant Toast
|
|||
|
|
participant API as 后端 API
|
|||
|
|
|
|||
|
|
User->>Toolbar: 点击坐席头像按钮
|
|||
|
|
activate Toolbar
|
|||
|
|
Toolbar->>Logic: computeCallAgentState(ctx)
|
|||
|
|
Logic-->>Toolbar: CallAgentState (active/urgent/waiting/end/reopen/disabled)
|
|||
|
|
alt state === 'disabled'
|
|||
|
|
Toolbar-->>User: 无响应（按钮 :disabled）
|
|||
|
|
else state === 'active' or 'urgent'
|
|||
|
|
Toolbar->>Store: shakeAgent()
|
|||
|
|
Store->>API: POST /api/v1/conversations/{id}/shake-agent
|
|||
|
|
alt 成功
|
|||
|
|
API-->>Store: 200 OK + funny_phrase
|
|||
|
|
Store->>Toast: showToast(funny_phrase)
|
|||
|
|
else 失败
|
|||
|
|
API-->>Store: 4xx/5xx
|
|||
|
|
Store->>Toast: showToast('呼叫失败，请稍后重试')
|
|||
|
|
end
|
|||
|
|
else state === 'waiting'
|
|||
|
|
Toolbar->>Store: cancelQueue()
|
|||
|
|
Store->>API: POST /api/v1/conversations/{id}/cancel-queue
|
|||
|
|
API-->>Store: 200 OK
|
|||
|
|
Store->>Toast: showToast('已取消排队')
|
|||
|
|
else state === 'reopen'
|
|||
|
|
Toolbar->>Store: reopenCurrentConversation()
|
|||
|
|
Store->>API: POST /api/v1/conversations/{id}/reopen
|
|||
|
|
API-->>Store: 200 OK
|
|||
|
|
else state === 'end'
|
|||
|
|
Toolbar->>Store: closeCurrentConversation()
|
|||
|
|
Note over Toolbar,Store: ⚠️ v1.3 实际: 走 ChatPanel 顶部"结束会话"按钮<br/>(头像右侧红色 ⏏ 按钮),<br/>因为 serving 态工具栏坐席按钮=disabled (v1.2 P1 修复)
|
|||
|
|
end
|
|||
|
|
deactivate Toolbar
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.2 v1.3 后事件流全景（IntegrationZone 旁路化）
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
autonumber
|
|||
|
|
participant User
|
|||
|
|
participant InputBar
|
|||
|
|
participant ChatPanel
|
|||
|
|
participant IntegrationZone as IntegrationZone<br/>(无坐席按钮)
|
|||
|
|
participant QueueCapsule
|
|||
|
|
participant Store
|
|||
|
|
participant Backend
|
|||
|
|
|
|||
|
|
rect rgb(240, 248, 255)
|
|||
|
|
Note over User,Backend: 🆕 v1.3 真实事件流（InputBar 工具栏头像为唯一坐席入口）
|
|||
|
|
User->>InputBar: 点击坐席头像
|
|||
|
|
InputBar->>InputBar: handleCallAgentClick()
|
|||
|
|
InputBar->>Store: shakeAgent() / cancelQueue() / reopenCurrentConversation()
|
|||
|
|
Store->>Backend: API call
|
|||
|
|
Backend-->>Store: 200 OK
|
|||
|
|
Store-->>User: toast + UI 更新
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
rect rgb(255, 248, 248)
|
|||
|
|
Note over User,Backend: 🔻 v1.3 已断开的路径（IntegrationZone 坐席按钮已删除）
|
|||
|
|
User-xIntegrationZone: 点击 IntegrationZone 坐席按钮
|
|||
|
|
Note right of IntegrationZone: ⚠️ DOM 节点已删除，<br/>无 click handler 可触发
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
rect rgb(248, 255, 248)
|
|||
|
|
Note over User,Backend: ✅ 仍生效的路径（QueueCapsule 内部触发）
|
|||
|
|
User->>QueueCapsule: 点击"取消排队"按钮
|
|||
|
|
QueueCapsule->>Store: cancelQueue()（v1.2y 行为：内部直接调）
|
|||
|
|
QueueCapsule-->>ChatPanel: emit('cancel-queue')（被 ChatPanel 接收）
|
|||
|
|
Note right of ChatPanel: ChatPanel.handleCancelQueue()<br/>仅作为兜底（QueueCapsule 已<br/>直接调 store，重复调是幂等的）
|
|||
|
|
end
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.3 InputBar 6 态按钮颜色映射（v1.3 恢复）
|
|||
|
|
|
|||
|
|
| state | modifier class | icon | text | title | 触发 action |
|
|||
|
|
|-------|---------------|------|------|-------|------------|
|
|||
|
|
| `disabled` | `call-agent-btn--disabled` | 🔒 | 人工坐席 | "再多描述几句话即可激活" | 无（按钮 :disabled） |
|
|||
|
|
| `active` | `call-agent-btn--active` | 🎧 | 人工坐席 | "点击呼叫人工坐席" | `store.shakeAgent()` |
|
|||
|
|
| `urgent` | `call-agent-btn--urgent` | 🚨 | 人工坐席 | "检测到紧急问题，直接呼叫人工坐席" | `store.shakeAgent()` |
|
|||
|
|
| `waiting` | `call-agent-btn--waiting` | ⏳ | 排队取消 | "点击取消排队" | `store.cancelQueue()` |
|
|||
|
|
| `end` | `call-agent-btn--end` | 📴 | 结束咨询 | "点击结束本次人工咨询" | `store.closeCurrentConversation()`（v1.3 实际由顶部按钮走） |
|
|||
|
|
| `reopen` | `call-agent-btn--reopen` | 🔄 | 重新打开 | "24小时内可重新打开此会话" | `store.reopenCurrentConversation()` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 任务列表（有序、含依赖关系）
|
|||
|
|
|
|||
|
|
### T01 — 恢复 InputBar.vue 到 v1.2 状态
|
|||
|
|
|
|||
|
|
| 维度 | 内容 |
|
|||
|
|
|------|------|
|
|||
|
|
| **任务 ID** | T01 |
|
|||
|
|
| **任务名** | 恢复 InputBar.vue 到 v1.2 形态（4 按钮工具栏 + InputBar 内上方居中 + 坐席头像 + 5 色徽标） |
|
|||
|
|
| **依赖** | 无 |
|
|||
|
|
| **优先级** | P0 |
|
|||
|
|
| **涉及文件** | `src/frontend-h5/src/components/chat/InputBar.vue`、`src/frontend-h5/src/components/chat/inputBarCallAgentState.ts`（仅 import）、`src/frontend-h5/src/components/chat/integrationZoneLogic.ts`（仅 import） |
|
|||
|
|
| **负责方** | 工程师（前端） |
|
|||
|
|
|
|||
|
|
**详细步骤**：
|
|||
|
|
|
|||
|
|
1. **Step 1.1 — 模板调整**：
|
|||
|
|
- 删除当前 v1.3 错误实施的 `<div class="input-bar__toolbar-wrapper">`（位于 InputBar 底部，InputBar.vue:115-198）。
|
|||
|
|
- 在 `<div class="input-bar__row">` **之后**插入 v1.2 形态的工具栏（4 按钮：emoji / 文件 / 语音 / 坐席头像）。
|
|||
|
|
- 工具栏容器使用 `class="input-bar__toolbar"`，位置在输入行**下方、表情面板下方**（v1.2 DOM 顺序：`resize-handle` → `input-bar__row` → `emoji-panel` → `input-bar__toolbar`）。
|
|||
|
|
- 删除 SVG defs 中的"v1.3 高端 SVG 图标"（`g-emoji` / `g-doc-*` / `g-mic-*` 等，InputBar.vue:27-65），恢复 v1.2 的简单 emoji 字符（😊 / 📎 / 🎤）+ agent 按钮的图片头像（沿用原型 `agent-avatar-v0.8.jpg`）。
|
|||
|
|
- 表情按钮的激活态 class 从 `is-active-emoji` 保持不变；移除 emoji 面板的 `slideDown` 动画，恢复 `slideUp` 动画（`from translateY(20px) → 0`）。
|
|||
|
|
|
|||
|
|
2. **Step 1.2 — 坐席头像按钮恢复**：
|
|||
|
|
- 在工具栏内、语音按钮**之后**插入 1 个 `<button class="input-bar__call-agent-btn">` 节点：
|
|||
|
|
```html
|
|||
|
|
<button
|
|||
|
|
class="input-bar__call-agent-btn"
|
|||
|
|
:class="callAgentBtnClass"
|
|||
|
|
:title="callAgentBtnTitle"
|
|||
|
|
:aria-label="callAgentBtnTitle"
|
|||
|
|
:disabled="callAgentState === 'disabled'"
|
|||
|
|
@click="handleCallAgentClick"
|
|||
|
|
>
|
|||
|
|
<span class="input-bar__call-agent-btn__icon">{{ callAgentBtnIcon }}</span>
|
|||
|
|
<span class="input-bar__call-agent-btn__text">{{ callAgentBtnText }}</span>
|
|||
|
|
<span class="agent-badge" :class="agentBadgeClass"></span>
|
|||
|
|
</button>
|
|||
|
|
```
|
|||
|
|
- 移除错误注释 `<!-- 🆕 v1.3：坐席按钮已彻底移除（由 IntegrationZone 接管 6 态 agent 入口） -->`（InputBar.vue:196）。
|
|||
|
|
|
|||
|
|
3. **Step 1.3 — script 调整**：
|
|||
|
|
- 恢复以下 5 个 computed（从 f9c25147 commit 的反向 patch 中取）：
|
|||
|
|
- `callAgentState`（已存在，需**重新绑定**到模板 + 移除 `void callAgentState` 标注）
|
|||
|
|
- `callAgentBtnClass: ComputedRef<Record<string, boolean>>`（基于 `computeIntegrationBtnClass`）
|
|||
|
|
- `callAgentBtnIcon: ComputedRef<string>`（内联 6 行 switch，沿用 IntegrationZone 逻辑）
|
|||
|
|
- `callAgentBtnText: ComputedRef<string>`（基于 `computeCallAgentBtnText`）
|
|||
|
|
- `callAgentBtnTitle: ComputedRef<string>`（基于 `computeCallAgentBtnTitle`）
|
|||
|
|
- `agentBadgeClass: ComputedRef<Record<string, boolean>>`（5 色徽标：is-online/urgent/waiting/offline/end）
|
|||
|
|
- 恢复 `handleCallAgentClick()` 函数（按 `computeCallAction` 路由到 `store.shakeAgent/cancelQueue/reopenCurrentConversation`）。
|
|||
|
|
- 恢复 5 处 import：`computeCallAgentBtnText` / `computeCallAgentBtnTitle` / `computeIntegrationBtnClass` / `computeCallAction` / `CallAgentState`。
|
|||
|
|
- 移除 `void callAgentState` 标注（InputBar.vue:319）。
|
|||
|
|
|
|||
|
|
4. **Step 1.4 — 样式调整**：
|
|||
|
|
- 删除 `.input-bar__toolbar-wrapper` 样式（InputBar.vue:828-834）。
|
|||
|
|
- 删除 `.input-bar__toolbar` 的"v1.3 玻璃拟态 + 多层 box-shadow + radial 渐变"样式（InputBar.vue:836-876），恢复 v1.2 的简单 flex 居中。
|
|||
|
|
- 删除 `.input-bar__btn` 的 v1.3 高端 SVG 适配样式（`width: 40px` 圆形玻璃 + backdrop-filter，InputBar.vue:881-925），恢复 v1.2 的 32px 简单圆形按钮。
|
|||
|
|
- 删除 `.input-bar__btn--voice.is-voice-recording/.is-voice-recognized` 的 3 态渐变样式（InputBar.vue:942-971），恢复 v1.2 的简单 🎤 字符按钮。
|
|||
|
|
- 恢复 `.input-bar__call-agent-btn` 样式（沿用 IntegrationZone 的 `.call-agent-btn` 6 态 modifier 命名）。
|
|||
|
|
- 恢复 `.agent-badge` 5 色徽标样式（online=绿/urgent=红/waiting=橙/offline=灰/end=蓝）。
|
|||
|
|
- 恢复 `slideUp` keyframes（删除 `slideDown`，InputBar.vue:991-1002）。
|
|||
|
|
|
|||
|
|
5. **Step 1.5 — 验证**：
|
|||
|
|
- `pnpm vue-tsc --noEmit` 0 错误。
|
|||
|
|
- `grep -n "callAgentBtnClass\|callAgentBtnIcon\|callAgentBtnText\|callAgentBtnTitle\|agentBadgeClass\|input-bar__call-agent-btn" src/frontend-h5/src/components/chat/InputBar.vue` 输出非空。
|
|||
|
|
- `grep -n "void callAgentState\|v1.3.*坐席按钮已彻底移除" src/frontend-h5/src/components/chat/InputBar.vue` 输出为空。
|
|||
|
|
|
|||
|
|
**验收标准**：
|
|||
|
|
|
|||
|
|
- [ ] REQ-A1：InputBar.vue 模板包含 4 个按钮（emoji / 文件 / 语音 / 坐席头像）。
|
|||
|
|
- [ ] REQ-A2：工具栏位于 `input-bar__row` **之后**（v1.2 位置：InputBar 内上方居中）。
|
|||
|
|
- [ ] REQ-A3：坐席头像按钮可见 `agent-badge` 子节点，class 随 5 色切换。
|
|||
|
|
- [ ] REQ-A4：vue-tsc 0 错误。
|
|||
|
|
- [ ] REQ-A5：`pnpm vitest run InputBar.test.ts` 当前仍 PASS（错误实施的契约测试，不影响 v1.2 实现）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### T02 — 删除 IntegrationZone.vue 坐席按钮
|
|||
|
|
|
|||
|
|
| 维度 | 内容 |
|
|||
|
|
|------|------|
|
|||
|
|
| **任务 ID** | T02 |
|
|||
|
|
| **任务名** | 删除 IntegrationZone.vue 中的"人工坐席"按钮（template / script / style / emits 4 处） |
|
|||
|
|
| **依赖** | T01（确认 InputBar.vue 已恢复 v1.2 形态） |
|
|||
|
|
| **优先级** | P0 |
|
|||
|
|
| **涉及文件** | `src/frontend-h5/src/components/chat/IntegrationZone.vue` |
|
|||
|
|
| **负责方** | 工程师（前端） |
|
|||
|
|
|
|||
|
|
**详细步骤**：
|
|||
|
|
|
|||
|
|
1. **Step 2.1 — Template 删除**：
|
|||
|
|
- 删除 `IntegrationZone.vue:30-65` 中的 `<button class="call-agent-btn">` 节点（4 行结构 + 2 个 `<span>` 子节点）。
|
|||
|
|
- 保留 `QueueCapsule` + `guide div` 节点（不变）。
|
|||
|
|
- 更新文件头注释 `IntegrationZone.vue:5-15`，标记"v1.3 已删除坐席按钮，仅保留 QueueCapsule + 引导语"。
|
|||
|
|
|
|||
|
|
2. **Step 2.2 — Script 删除**：
|
|||
|
|
- 删除 `defineEmits<{ (e: 'callAgent'): void ... }>` 中的 `callAgent` 声明（IntegrationZone.vue:102）。
|
|||
|
|
- 保留 `cancelQueue` / `endConversation` / `reopenConversation` 3 个 emit（仍由 QueueCapsule 透传）。
|
|||
|
|
- 删除 `btnText` / `btnIcon` / `btnTitle` / `btnClass` 4 个 computed（IntegrationZone.vue:126, 131, 136, 141）。
|
|||
|
|
- 删除 `handleClick()` 函数（IntegrationZone.vue:167-186）。
|
|||
|
|
- 清理 import（IntegrationZone.vue:83-91）：
|
|||
|
|
- 删除 `computeIntegrationBtnText` / `computeIntegrationBtnIcon` / `computeIntegrationBtnTitle` / `computeIntegrationBtnClass`（无消费者）
|
|||
|
|
- 保留 `computeIntegrationGuideClass` / `computeCallAction`（虽然 `computeCallAction` 也无消费者，但保留以备未来重新引入按钮时复用 — 标注 `void` 抑制 noUnusedLocals）。
|
|||
|
|
- 保留 `IntegrationZoneProps` type import。
|
|||
|
|
|
|||
|
|
3. **Step 2.3 — Style 删除**：
|
|||
|
|
- 删除 `.integration-zone .call-agent-btn` 容器样式（IntegrationZone.vue:213-232）。
|
|||
|
|
- 删除 `.integration-zone .call-agent-btn--disabled/--active/--urgent/--waiting/--end/--reopen` 6 个 modifier 样式（IntegrationZone.vue:235-312）。
|
|||
|
|
- 删除 `.integration-zone .call-agent-btn__icon` / `.__text` 样式（IntegrationZone.vue:315-321）。
|
|||
|
|
- 保留 `.integration-zone` 容器 + `.integration-zone :deep(.queue-capsule)` + `.integration-zone__guide*` 样式。
|
|||
|
|
|
|||
|
|
4. **Step 2.4 — 验证**：
|
|||
|
|
- `pnpm vue-tsc --noEmit` 0 错误。
|
|||
|
|
- `grep -n "call-agent-btn\|btnText\|btnIcon\|btnTitle\|btnClass\|handleClick\|callAgent" src/frontend-h5/src/components/chat/IntegrationZone.vue` 输出为空。
|
|||
|
|
- `grep -n "QueueCapsule\|guide" src/frontend-h5/src/components/chat/IntegrationZone.vue` 输出非空。
|
|||
|
|
- `pnpm vitest run integrationZoneLogic.test.ts` 仍 PASS（纯函数不变）。
|
|||
|
|
|
|||
|
|
**验收标准**：
|
|||
|
|
|
|||
|
|
- [ ] REQ-B1：IntegrationZone.vue 模板仅渲染 2 个元素（QueueCapsule + 引导语）。
|
|||
|
|
- [ ] REQ-B2：IntegrationZone.vue 浏览器开发者工具中无 `<button class="call-agent-btn">` DOM 节点。
|
|||
|
|
- [ ] REQ-B3：IntegrationZone.vue 的 `defineEmits` 仅声明 3 个事件（cancelQueue / endConversation / reopenConversation）。
|
|||
|
|
- [ ] REQ-B4：vue-tsc 0 错误。
|
|||
|
|
- [ ] REQ-B5：integrationZoneLogic.test.ts 36 用例仍 PASS（不删除任何用例）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### T03 — 清理 ChatPanel.vue 中对 IntegrationZone 已失效的事件监听器
|
|||
|
|
|
|||
|
|
| 维度 | 内容 |
|
|||
|
|
|------|------|
|
|||
|
|
| **任务 ID** | T03 |
|
|||
|
|
| **任务名** | 清理 ChatPanel.vue 中 `@call-agent="handleDirectCall"` 监听器 + `handleDirectCall` 函数（保守范围） |
|
|||
|
|
| **依赖** | T02（IntegrationZone 坐席按钮已删除） |
|
|||
|
|
| **优先级** | P1 |
|
|||
|
|
| **涉及文件** | `src/frontend-h5/src/components/chat/ChatPanel.vue` |
|
|||
|
|
| **负责方** | 工程师（前端） |
|
|||
|
|
|
|||
|
|
**详细步骤**：
|
|||
|
|
|
|||
|
|
1. **Step 3.1 — Template 清理**：
|
|||
|
|
- 删除 `ChatPanel.vue:116` 的 `@call-agent="handleDirectCall"` 监听器。
|
|||
|
|
- 保留 `ChatPanel.vue:117-119` 的 3 个监听器（`@cancel-queue` / `@end-conversation` / `@reopen-conversation`），因为它们仍由 QueueCapsule 透传触发。
|
|||
|
|
|
|||
|
|
2. **Step 3.2 — Script 清理**：
|
|||
|
|
- 删除 `handleDirectCall()` 函数（ChatPanel.vue:339-360）。
|
|||
|
|
- 保留 `handleCancelQueue()` / `handleEndConversation()` / `handleReopenConversation()` 3 个函数（仍被 QueueCapsule 透传触发）。
|
|||
|
|
- 更新文件头注释 `ChatPanel.vue:9-11`，标记"v1.3 已删除 handleDirectCall 监听器"。
|
|||
|
|
|
|||
|
|
3. **Step 3.3 — 不删除的清单**：
|
|||
|
|
- 保留 `IntegrationZone` 的 `callAgent` emit 已经被删除（D2），但 QueueCapsule 的 3 个 emit 仍存在。
|
|||
|
|
- 保留 `callAgentState` 和 `guideText` 2 个 computed（仍透传给 IntegrationZone 的 QueueCapsule + 引导语）。
|
|||
|
|
- 保留 `computeCallAgentState` import（仍用于 callAgentState computed）。
|
|||
|
|
- 保留 `computeGuideText` import（仍用于 guideText computed）。
|
|||
|
|
|
|||
|
|
4. **Step 3.4 — 验证**：
|
|||
|
|
- `pnpm vue-tsc --noEmit` 0 错误。
|
|||
|
|
- `grep -n "handleDirectCall\|@call-agent" src/frontend-h5/src/components/chat/ChatPanel.vue` 输出为空。
|
|||
|
|
- `grep -n "handleCancelQueue\|handleEndConversation\|handleReopenConversation\|@cancel-queue\|@end-conversation\|@reopen-conversation" src/frontend-h5/src/components/chat/ChatPanel.vue` 输出非空。
|
|||
|
|
|
|||
|
|
**验收标准**：
|
|||
|
|
|
|||
|
|
- [ ] REQ-C1：ChatPanel.vue 模板中无 `@call-agent` 监听器。
|
|||
|
|
- [ ] REQ-C2：ChatPanel.vue script 中无 `handleDirectCall` 函数定义。
|
|||
|
|
- [ ] REQ-C3：ChatPanel.vue 模板仍保留 3 个 QueueCapsule 透传监听器。
|
|||
|
|
- [ ] REQ-C4：vue-tsc 0 错误。
|
|||
|
|
|
|||
|
|
> **设计说明**（为何不删除全部 4 个监听器）：QueueCapsule 内部仍触发 `cancel-queue` / `reopen-conversation` 2 个 emit，IntegrationZone 仍转发 `end-conversation` 1 个 emit 给 ChatPanel。3 个监听器在 v1.3 后**仍然有效**，不应作为"代码冗余"清理。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### T04 — 补充 InputBar.test.ts 中 v1.3 专项测试
|
|||
|
|
|
|||
|
|
| 维度 | 内容 |
|
|||
|
|
|------|------|
|
|||
|
|
| **任务 ID** | T04 |
|
|||
|
|
| **任务名** | 重写 InputBar.test.ts 为 v1.3 = v1.2 的契约测试（4 按钮 + 5 色徽标映射 + slideUp 动画 + 6 态按钮） |
|
|||
|
|
| **依赖** | T01（InputBar.vue 已恢复 v1.2 形态） |
|
|||
|
|
| **优先级** | P0 |
|
|||
|
|
| **涉及文件** | `src/frontend-h5/src/components/chat/InputBar.test.ts` |
|
|||
|
|
| **负责方** | QA + 工程师 |
|
|||
|
|
|
|||
|
|
**详细步骤**：
|
|||
|
|
|
|||
|
|
1. **Step 4.1 — 删除错误契约**：
|
|||
|
|
- 删除 `V13_TOOLBAR_BUTTONS = ['emoji', 'file', 'voice']`（InputBar.test.ts:118-119）。
|
|||
|
|
- 删除 `TOOLBAR_POSITION_INDEX = 5` 的"最末位置"断言（InputBar.test.ts:108）。
|
|||
|
|
- 删除 `V13_SLIDE_DIRECTION = 'down'`（InputBar.test.ts:128）。
|
|||
|
|
|
|||
|
|
2. **Step 4.2 — 恢复 v1.2 契约**：
|
|||
|
|
- 恢复 `V13_TOOLBAR_BUTTONS = ['emoji', 'file', 'voice', 'agent']`（4 按钮）。
|
|||
|
|
- 恢复 `V12_TOOLBAR_BUTTONS = ['emoji', 'file', 'voice', 'agent']`（v1.2 与 v1.3 相同，便于对比）。
|
|||
|
|
- 恢复 `V13_SLIDE_DIRECTION = 'up'`（slideUp 动画）。
|
|||
|
|
- 恢复 `TOOLBAR_POSITION_INDEX = 2`（工具栏在 `input-bar__row` 之后、`emoji-panel` 之前）。
|
|||
|
|
|
|||
|
|
3. **Step 4.3 — 新增 5 色徽标契约测试**：
|
|||
|
|
- `computeAgentBadgeClass(state)` 纯函数：
|
|||
|
|
- `active` → `{ 'is-online': true }`
|
|||
|
|
- `urgent` → `{ 'is-urgent': true }`
|
|||
|
|
- `waiting` → `{ 'is-waiting': true }`
|
|||
|
|
- `disabled` → `{ 'is-offline': true }`
|
|||
|
|
- `end` → `{ 'is-end': true }`
|
|||
|
|
- `reopen` → `{ 'is-end': true }`（reopen 复用 end 蓝色，PRD 沿用 v1.2 行为）
|
|||
|
|
|
|||
|
|
4. **Step 4.4 — 新增 6 态按钮 contract 测试**：
|
|||
|
|
- 验证 `callAgentBtnClass` 包含正确的 modifier key（如 `call-agent-btn--active` / `--urgent` / `--waiting` / `--end` / `--reopen` / `--disabled`）。
|
|||
|
|
- 验证 `callAgentBtnIcon` 在 6 态下分别返回 🔒 / 🎧 / 🚨 / ⏳ / 📴 / 🔄。
|
|||
|
|
- 验证 `callAgentBtnText` 在 6 态下分别返回 "人工坐席" / "人工坐席" / "人工坐席" / "排队取消" / "结束咨询" / "重新打开"。
|
|||
|
|
|
|||
|
|
5. **Step 4.5 — 新增 handleCallAgentClick 路由测试**：
|
|||
|
|
- state=active → 调 `store.shakeAgent()`
|
|||
|
|
- state=urgent → 调 `store.shakeAgent()`
|
|||
|
|
- state=waiting → 调 `store.cancelQueue()`
|
|||
|
|
- state=reopen → 调 `store.reopenCurrentConversation()`
|
|||
|
|
- state=end → 不调（实际由顶部按钮走）
|
|||
|
|
- state=disabled → 不响应
|
|||
|
|
|
|||
|
|
6. **Step 4.6 — 验证**：
|
|||
|
|
- `pnpm vitest run InputBar.test.ts` 全 PASS（预计 50-55 个用例，包含 v1.2 沿用 + v1.3 新增 5 色徽标 + 6 态按钮 + handleCallAgentClick 路由）。
|
|||
|
|
|
|||
|
|
**验收标准**：
|
|||
|
|
|
|||
|
|
- [ ] REQ-D1：InputBar.test.ts 中 `V13_TOOLBAR_BUTTONS` 长度为 4（包含 'agent'）。
|
|||
|
|
- [ ] REQ-D2：InputBar.test.ts 中新增 `computeAgentBadgeClass` 5 色映射测试 5-6 个用例。
|
|||
|
|
- [ ] REQ-D3：InputBar.test.ts 中新增 `callAgentBtnClass` / `callAgentBtnIcon` / `callAgentBtnText` 6 态测试 18 个用例。
|
|||
|
|
- [ ] REQ-D4：InputBar.test.ts 中新增 `handleCallAgentClick` 路由测试 5-6 个用例。
|
|||
|
|
- [ ] REQ-D5：所有用例 PASS（无失败、无 skip）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### T05 — 全局一致性审查
|
|||
|
|
|
|||
|
|
| 维度 | 内容 |
|
|||
|
|
|------|------|
|
|||
|
|
| **任务 ID** | T05 |
|
|||
|
|
| **任务名** | 全局一致性审查（IS_PASS: YES/NO） |
|
|||
|
|
| **依赖** | T01、T02、T03、T04 |
|
|||
|
|
| **优先级** | P0 |
|
|||
|
|
| **涉及文件** | 全 chat 模块（grep 验证） |
|
|||
|
|
| **负责方** | 架构师（高见远）+ 工程师 |
|
|||
|
|
|
|||
|
|
**详细步骤**：
|
|||
|
|
|
|||
|
|
1. **Step 5.1 — 跨文件 import 审查**：
|
|||
|
|
- 验证 `ChatPanel.vue` 不再 import `handleDirectCall` 相关依赖。
|
|||
|
|
- 验证 `InputBar.vue` import 5 个 helper（`computeCallAgentState` / `computeCallAgentBtnText` / `computeCallAgentBtnTitle` / `computeIntegrationBtnClass` / `computeCallAction`）。
|
|||
|
|
- 验证 `IntegrationZone.vue` import 仍包含 `QueueCapsule` + `computeIntegrationGuideClass`。
|
|||
|
|
|
|||
|
|
2. **Step 5.2 — 跨文件函数引用审查**：
|
|||
|
|
- `grep -rn "handleDirectCall" src/frontend-h5/src/` 应输出为空。
|
|||
|
|
- `grep -rn "@call-agent" src/frontend-h5/src/components/chat/` 应输出为空。
|
|||
|
|
- `grep -rn "call-agent-btn" src/frontend-h5/src/components/chat/IntegrationZone.vue` 应输出为空；`InputBar.vue` 应输出非空。
|
|||
|
|
|
|||
|
|
3. **Step 5.3 — 数据流审查**：
|
|||
|
|
- 验证坐席状态从 `store.agentOnline` / `store.canCallAgent` / `store.canReopen` → `computeCallAgentState` → `InputBar.callAgentState` → `callAgentBtnClass/Icon/Text/Title` 的数据流不断裂。
|
|||
|
|
- 验证坐席动作从 `InputBar.handleCallAgentClick` → `store.shakeAgent/cancelQueue/reopenCurrentConversation` → 后端 API → store state → 响应式更新 InputBar 工具栏徽标。
|
|||
|
|
|
|||
|
|
4. **Step 5.4 — 测试覆盖审查**：
|
|||
|
|
- `InputBar.test.ts` PASS（4 按钮 + 5 色徽标 + 6 态按钮 + handleCallAgentClick 路由）
|
|||
|
|
- `inputBarCallAgentState.test.ts` PASS（6 态计算 + v1.2y Bug 修复）
|
|||
|
|
- `integrationZoneLogic.test.ts` PASS（按钮 class / 引导语 class / callAction 映射）
|
|||
|
|
- `inputBarGuideText.test.ts` PASS（4 种场景 → v1.3.5 后仅 2 场景生效）
|
|||
|
|
- `QueueCapsule.test.ts` PASS（36 用例）
|
|||
|
|
- `conversation-v1.2.test.ts` PASS（store 4 个 action）
|
|||
|
|
|
|||
|
|
5. **Step 5.5 — 浏览器实测**：
|
|||
|
|
- 登录 H5 → 打开新会话 → 确认 InputBar 工具栏 4 按钮（emoji / 文件 / 语音 / 坐席头像）正确显示
|
|||
|
|
- 确认 IntegrationZone 容器**仅渲染** QueueCapsule + 引导语（无坐席按钮）
|
|||
|
|
- 浏览器开发者工具：搜索 "call-agent-btn" DOM 节点应输出为空
|
|||
|
|
- 浏览器控制台无 Vue 警告、无 prop 类型错误
|
|||
|
|
|
|||
|
|
**验收标准**：
|
|||
|
|
|
|||
|
|
- [ ] REQ-E1：所有 grep 验证通过（详见 Step 5.1-5.3）。
|
|||
|
|
- [ ] REQ-E2：所有 vitest 测试通过。
|
|||
|
|
- [ ] REQ-E3：浏览器实测无视觉异常、控制台无报错。
|
|||
|
|
- [ ] REQ-E4：架构师签发 IS_PASS: YES（写在本任务清单末尾）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 6.x 任务依赖图
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TD
|
|||
|
|
T01["T01: 恢复 InputBar.vue<br/>到 v1.2 状态<br/>(4 按钮 + 坐席头像)"]
|
|||
|
|
T02["T02: 删除 IntegrationZone.vue<br/>坐席按钮"]
|
|||
|
|
T03["T03: 清理 ChatPanel.vue<br/>@call-agent 监听器"]
|
|||
|
|
T04["T04: 重写 InputBar.test.ts<br/>v1.3 = v1.2 契约测试"]
|
|||
|
|
T05["T05: 全局一致性审查<br/>(IS_PASS: YES/NO)"]
|
|||
|
|
|
|||
|
|
T01 --> T02
|
|||
|
|
T02 --> T03
|
|||
|
|
T01 --> T04
|
|||
|
|
T01 --> T05
|
|||
|
|
T02 --> T05
|
|||
|
|
T03 --> T05
|
|||
|
|
T04 --> T05
|
|||
|
|
|
|||
|
|
classDef p0 fill:#fee,stroke:#c00,color:#000
|
|||
|
|
classDef p1 fill:#efe,stroke:#0a0,color:#000
|
|||
|
|
class T01,T02,T04,T05 p0
|
|||
|
|
class T03 p1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**任务统计**：5 个任务（满足 ≤5 硬性上限）。P0 = 4 个，P1 = 1 个。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 依赖包列表
|
|||
|
|
|
|||
|
|
**无新增依赖**。所有依赖已在 v1.2 基线锁定。
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# package.json 锁定版本（无需变更）
|
|||
|
|
dependencies:
|
|||
|
|
vue: ^3.4.0 # Composition API + <script setup>
|
|||
|
|
pinia: ^2.1.0 # store 单例
|
|||
|
|
vant: ^4.8.0 # UI 组件库
|
|||
|
|
@vueuse/core: ^10.0.0 # 工具 composables
|
|||
|
|
socket.io-client: ^4.7.0 # WebSocket
|
|||
|
|
axios: ^1.6.0 # HTTP
|
|||
|
|
|
|||
|
|
devDependencies:
|
|||
|
|
vite: ^5.0.0
|
|||
|
|
typescript: ^5.0.0
|
|||
|
|
vitest: ^1.0.0
|
|||
|
|
@vue/test-utils: ^2.4.0
|
|||
|
|
vue-tsc: ^1.8.0
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 共享知识（跨文件约定）
|
|||
|
|
|
|||
|
|
### 8.1 关键约定
|
|||
|
|
|
|||
|
|
1. **坐席入口唯一化**：v1.3 后 H5 端坐席入口**仅**为 InputBar 工具栏坐席头像按钮（图片头像 + 5 色徽标）。IntegrationZone 中的旧"人工坐席"按钮已**完全删除**（无 DOM 节点、无 emit、无样式）。
|
|||
|
|
2. **6 态按钮位置**：v1.3 = v1.2 形态，6 态按钮在 InputBar 工具栏**最右侧**（emoji / 文件 / 语音 / **坐席**），**不是**在 IntegrationZone 容器中。
|
|||
|
|
3. **数据流统一**：坐席按钮 6 态计算由 `InputBar.vue` 内部完成（基于 `inputBarCallAgentState.computeCallAgentState` + `storeToRefs(store)`），**不依赖** IntegrationZone 的 prop 透传。IntegrationZone 的 `callAgentState` prop 仅用于 QueueCapsule 内部降级判定。
|
|||
|
|
4. **Action 调用路径**：坐席按钮直接调 `store.shakeAgent() / cancelQueue() / reopenCurrentConversation()`，**不经 ChatPanel 中转**（D2 决策）。`end` 态例外：实际由 ChatPanel 顶部"⏏"按钮走，因为 v1.2 P1 修复已让 InputBar 工具栏坐席按钮在 `serving` 态保持 disabled。
|
|||
|
|
5. **helper 文件保留**：`inputBarCallAgentState.ts` / `integrationZoneLogic.ts` / `inputBarGuideText.ts` 三个 helper 文件**完整保留**（Q4 暂搁），未来若整合区恢复坐席按钮可直接复用。
|
|||
|
|
6. **事件冒泡规则**：
|
|||
|
|
- InputBar 坐席按钮 → **不 emit**，直接调 store
|
|||
|
|
- QueueCapsule 内部按钮 → **直接调 store**（`reopenCurrentConversation`）+ 同步 emit（`cancel-queue` / `reopen-conversation`）给 IntegrationZone 透传
|
|||
|
|
- IntegrationZone → 仅**透传** QueueCapsule 的 emit（`cancelQueue` / `endConversation` / `reopenConversation`）给 ChatPanel
|
|||
|
|
|
|||
|
|
### 8.2 跨文件函数契约
|
|||
|
|
|
|||
|
|
| 函数 | 文件 | 签名 | 消费者 |
|
|||
|
|
|------|------|------|--------|
|
|||
|
|
| `computeCallAgentState(ctx)` | `inputBarCallAgentState.ts:63` | `(ctx: CallAgentStateContext) => CallAgentState` | InputBar.vue、ChatPanel.vue |
|
|||
|
|
| `computeCallAgentBtnText(state)` | `inputBarCallAgentState.ts:88` | `(state: CallAgentState) => string` | InputBar.vue（v1.3 恢复） |
|
|||
|
|
| `computeCallAgentBtnTitle(state, agentOnline)` | `inputBarCallAgentState.ts:99` | `(state, agentOnline) => string` | InputBar.vue（v1.3 恢复） |
|
|||
|
|
| `computeIntegrationBtnClass(state)` | `integrationZoneLogic.ts:129` | `(state) => Record<string, boolean>` | InputBar.vue（v1.3 恢复，沿用 .call-agent-btn--* 命名） |
|
|||
|
|
| `computeIntegrationGuideClass(text)` | `integrationZoneLogic.ts:144` | `(text) => Record<string, boolean>` | IntegrationZone.vue（保留） |
|
|||
|
|
| `computeCallAction(state)` | `integrationZoneLogic.ts:160` | `(state) => EmitEvent \| 'none'` | InputBar.vue（v1.3 恢复，按结果路由 store action） |
|
|||
|
|
| `computeGuideText(ctx)` | `inputBarGuideText.ts:67` | `(ctx) => string \| null` | ChatPanel.vue（透传给 IntegrationZone） |
|
|||
|
|
|
|||
|
|
### 8.3 编码风格约束
|
|||
|
|
|
|||
|
|
- **不使用 Sass/Less**：所有样式为原生 CSS + `scoped` 属性。
|
|||
|
|
- **不使用 TypeScript class**：所有组件用 `<script setup lang="ts">` 函数式写法。
|
|||
|
|
- **不使用 Vuex**：所有 store 用 Pinia（`defineStore` + `storeToRefs`）。
|
|||
|
|
- **不使用 prop drilling**：跨组件状态通过 Pinia store 共享。
|
|||
|
|
- **helper 文件范式**：纯函数 + 显式 ctx 入参，无 Vue/DOM 依赖，单测用 `pnpm vitest run` 跑通。
|
|||
|
|
|
|||
|
|
### 8.4 测试范式（沿用 inputBarCallAgentState.ts 范式）
|
|||
|
|
|
|||
|
|
- **不直接 mount SFC**：避免 `@vue/test-utils` 依赖
|
|||
|
|
- **纯函数复刻 + 断言**：在测试文件中以纯函数复刻组件 computed 的语义，断言纯函数输出
|
|||
|
|
- **mock store / composables**：使用 `vi.fn()` + `vi.useFakeTimers()` 隔离副作用
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 待明确事项
|
|||
|
|
|
|||
|
|
### Q3 细化（仅 call-agent 清理 vs 全 4 个清理）
|
|||
|
|
|
|||
|
|
**当前架构师建议（已写入 T03）**：**保守范围**，仅清理 `@call-agent` + `handleDirectCall`，保留其他 3 个监听器（`@cancel-queue` / `@end-conversation` / `@reopen-conversation`）。
|
|||
|
|
|
|||
|
|
**理由**：
|
|||
|
|
|
|||
|
|
1. QueueCapsule 内部仍直接调 `store.reopenCurrentConversation()`，但 QueueCapsule 的 `reopen-conversation` emit 仍被 IntegrationZone 透传给 ChatPanel（虽然 ChatPanel 的 `handleReopenConversation` 调用是幂等的）。
|
|||
|
|
2. QueueCapsule 的 `cancel-queue` emit 仍被 IntegrationZone 透传给 ChatPanel。
|
|||
|
|
3. IntegrationZone 容器未来可能新增"end 态按钮"（产品 P2 提案），提前保留 `end-conversation` 监听器可避免未来重新添加。
|
|||
|
|
|
|||
|
|
**请主理人确认**：是否接受"保守范围"清理，还是一次性清掉全部 4 个无效监听器（同时移除 IntegrationZone 的 3 个 emit 透传）？
|
|||
|
|
|
|||
|
|
**风险评估**：
|
|||
|
|
|
|||
|
|
- 保守范围：低风险（保留的 3 个监听器仍由 QueueCapsule 触发，是有效代码）。
|
|||
|
|
- 全清理：中风险（需要确认 QueueCapsule 内部是否完全独立于 ChatPanel 的 3 个 handler，否则可能漏改）。
|
|||
|
|
|
|||
|
|
### 其他无
|
|||
|
|
|
|||
|
|
其余 4 个 PRD 待确认问题（Q1/Q2/Q4）主理人已答：
|
|||
|
|
|
|||
|
|
- **Q1**：恢复 InputBar.vue 到 v1.2（T01 已覆盖）
|
|||
|
|
- **Q2**：不新建 IntegrationZone.test.ts（沿用现有 integrationZoneLogic.test.ts）
|
|||
|
|
- **Q4**：helper 文件保留（按主理人指示，6 个月后评估）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 评审签字
|
|||
|
|
|
|||
|
|
- [ ] 架构师：高见远
|
|||
|
|
- [ ] 产品经理：许清楚
|
|||
|
|
- [ ] 测试负责人：（待评审）
|
|||
|
|
- [ ] 主理人：Duckula
|