wecom_it_smart_desk/docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-工具栏统一设计-v1.3.md

# 工具栏统一设计 v1.3 — 删除 IntegrationZone 旧"人工坐席"按钮 PRD

> **版本**: v1.3
> **日期**: 2026-08-04
> **状态**: [待评审]
> **作者**: 许清楚（产品经理）
> **需求编号**: REQ-会话-001
> **子系统**: 02-会话管理
> **模块**: H5 用户端工具栏统一
> **基线版本**: v1.2（2026-08-04 09:18 已部署上线）
> **关联文档**:
>   - 原型: `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-工具栏统一设计v1.3-删除IntegrationZone坐席.html`

---

## 1. 产品目标

v1.2 已部署上线后，H5 用户端聊天页面存在 **两个坐席入口并存** 的视觉冗余问题：

- **入口 A**：`IntegrationZone.vue` 中的"人工坐席"按钮（带锁图标 🔒），位于 InputBar 上方独立行
- **入口 B**：`InputBar.vue` 工具栏中的坐席头像按钮（图片头像 + 5 色状态徽标），位于 InputBar 内上方居中

用户在反馈中通过截图明确标出"去掉"箭头指向 IntegrationZone 锁图标按钮，要求删除它，统一入口。

**v1.3 目标**：仅做 **2 件事**——
1. **删除** `IntegrationZone.vue` 中的"人工坐席"按钮（带锁图标 🔒 那个）
2. **保持** InputBar 工具栏 4 按钮不变（emoji / 文件 / 语音 / 坐席头像）

最终效果：H5 用户端坐席入口**唯一化**（仅 InputBar 工具栏头像），消除视觉冗余。

---

## 2. 用户故事

1. **As a** H5 用户（员工），
   **I want** 在聊天页面只看到**一个**清晰的坐席入口，
   **so that** 我能毫不犹豫地点选，无须在 IntegrationZone 锁图标按钮和 InputBar 工具栏头像按钮之间做选择。

2. **As a** H5 用户（员工），
   **I want** 聊天界面更整洁，避免重复控件干扰视线，
   **so that** 我能专注于与 AI / 坐席的对话，提升沟通效率。

---

## 3. 需求池

### P0（必须做）

| 编号 | 需求 | 说明 |
|------|------|------|
| REQ-会话-001-v1.3-01 | **删除 IntegrationZone.vue 中的"操作按钮"元素** | 删除 template 中 `<button class="call-agent-btn">` 及其子元素（🔒 图标 + 文案） |
| REQ-会话-001-v1.3-02 | **删除 IntegrationZone.vue 中的相关 script 逻辑** | 删除 `btnText` / `btnIcon` / `btnTitle` / `btnClass` 4 个 computed 与 `handleClick` 函数 |
| REQ-会话-001-v1.3-03 | **删除 IntegrationZone.vue 中的 emits 声明** | 删除 `callAgent` / `cancelQueue` / `endConversation` / `reopenConversation` 4 个 emit 声明 |
| REQ-会话-001-v1.3-04 | **删除 IntegrationZone.vue 中的相关样式** | 删除 `.integration-zone .call-agent-btn*` 系列样式（约 110 行 CSS） |
| REQ-会话-001-v1.3-05 | **保留 InputBar 工具栏 4 按钮不变** | emoji / 文件 / 语音 / 坐席头像 4 个按钮渲染、数量、位置、状态徽标、点击逻辑全部不变 |
| REQ-会话-001-v1.3-06 | **保留 InputBar 工具栏位置不变** | 位置保持 **InputBar 内上方居中**（v1.2 位置不动） |
| REQ-会话-001-v1.3-07 | **保留 IntegrationZone 中的 QueueCapsule** | 进度胶囊子组件继续渲染、工作、`agentOnline` prop 透传不变 |
| REQ-会话-001-v1.3-08 | **保留 IntegrationZone 中的引导语** | 4 种场景引导语文案 + warn 样式继续渲染，仅 `disabled` 态显示的规则不变 |
| REQ-会话-001-v1.3-09 | **保留 helper 文件不动** | `inputBarCallAgentState.ts` / `integrationZoneLogic.ts` 完整保留（helper 仍可能被未来其他场景复用，不做清理） |
| REQ-会话-001-v1.3-10 | **store 副作用调用链不变** | `store.shakeAgent()` / `cancelQueue()` / `closeCurrentConversation()` / `reopenCurrentConversation()` 4 个 action 仍可用，仍由 InputBar 工具栏头像按钮调用 |

### P1（应该做）

无。

### P2（可以做）

无。

---

## 4. UI 设计稿

引用已确认原型：`docs/01-产品文档/02-会话管理/原型-REQ-会话-001-工具栏统一设计v1.3-删除IntegrationZone坐席.html`

### 4.1 关键视觉对比

| 维度 | v1.2（当前线上） | v1.3（目标） |
|------|------------------|--------------|
| IntegrationZone 坐席按钮 | 🔒 显示在 InputBar 上方（带锁图标 + "人工坐席"文案） | ❌ **完全删除** |
| InputBar 工具栏按钮数 | 4（emoji / 文件 / 语音 / 坐席头像） | **4 不变**（emoji / 文件 / 语音 / 坐席头像） |
| 工具栏位置 | InputBar 内上方居中 | **InputBar 内上方居中（不变）** |
| 坐席入口数量 | 2 个（IntegrationZone + InputBar 工具栏） | **1 个（仅 InputBar 工具栏头像）** |
| QueueCapsule 进度胶囊 | 显示 | **显示（不变）** |
| 引导语 | 显示（disabled 态） | **显示（disabled 态，不变）** |

### 4.2 v1.3 目标布局示意（文字版）

```
┌─────────────────────────────────────┐
│  ChatPanel 头部（标题栏）            │
├─────────────────────────────────────┤
│                                     │
│  消息流区域                          │
│                                     │
├─────────────────────────────────────┤
│  IntegrationZone（v1.3 后仅 2 元素） │
│   [QueueCapsule 进度胶囊]           │
│   （disabled 态时）引导语 ⚠️ ...     │
├─────────────────────────────────────┤
│  InputBar（v1.3 不动）              │
│   ┌─────────────────────────────┐   │
│   │   [🙂] [📄] [🎤] [👤坐席]   │   │ ← 4 按钮工具栏（居中）
│   └─────────────────────────────┘   │
│   ┌─────────────────────────────┐   │
│   │  文本输入框  ...     [发送] │   │
│   └─────────────────────────────┘   │
└─────────────────────────────────────┘
```

---

## 5. 验收标准

### 5.1 必过项（P0 验证）

- [ ] **REQ-01**：`IntegrationZone.vue` 模板中不再渲染 `<button class="call-agent-btn">` 元素
- [ ] **REQ-02**：`IntegrationZone.vue` 浏览器开发者工具检查元素：坐席按钮 DOM 已彻底消失（无残留 `<button>` 节点）
- [ ] **REQ-03**：`IntegrationZone.vue` 模板中 `QueueCapsule` 仍正常渲染
- [ ] **REQ-04**：`IntegrationZone.vue` 模板中引导语仍正常渲染（disabled 态下显示）
- [ ] **REQ-05**：`InputBar.vue` 工具栏仍显示 **4 个按钮**（emoji / 文件 / 语音 / 坐席头像）
- [ ] **REQ-06**：`InputBar.vue` 工具栏位置保持 **InputBar 内上方居中**（v1.2 位置不动）
- [ ] **REQ-07**：坐席功能仍可通过 **InputBar 工具栏头像按钮** 触发（点击坐席头像弹出坐席面板 / 进入排队 / 显示状态）
- [ ] **REQ-08**：状态徽标（5 色）仍正常显示（online / urgent / waiting / offline / end）
- [ ] **REQ-09**：表情按钮 / 文件按钮 / 语音按钮点击逻辑不受影响
- [ ] **REQ-10**：`store.shakeAgent()` 等副作用调用链保持不变

### 5.2 代码清洁度

- [ ] **REQ-11**：`IntegrationZone.vue` 的 `script setup` 中无未使用的 import / computed / 函数
- [ ] **REQ-12**：`IntegrationZone.vue` 的 `script setup` 中 `emits` 声明已清理（不再声明 callAgent / cancelQueue / endConversation / reopenConversation）
- [ ] **REQ-13**：`IntegrationZone.vue` 的 `style scoped` 中无未使用的 `.call-agent-btn*` 样式

### 5.3 测试

- [ ] **REQ-14**：`integrationZoneLogic.test.ts` 单元测试仍全部 PASS（纯函数无变化）
- [ ] **REQ-15**：`InputBar.test.ts` 单元测试仍全部 PASS（InputBar 不动）
- [ ] **REQ-16**：若存在 IntegrationZone 组件级测试，则同步删除坐席按钮相关测试用例（详见第 7 节待确认问题 #2）

### 5.4 用户体验

- [ ] **REQ-17**：H5 用户端聊天页面坐席入口**唯一化**（仅 InputBar 工具栏头像）
- [ ] **REQ-18**：浏览器实测无视觉异常（错位、留白过多、组件塌陷等）
- [ ] **REQ-19**：浏览器控制台无报错（无未定义引用、无 prop 类型警告）

### 5.5 回滚准备

- [ ] **REQ-20**：保留 v1.2 部署包，5 分钟内可回滚

---

## 6. 范围边界

### 6.1 改动范围（仅 1 个文件）

| 文件 | 改动内容 |
|------|----------|
| `src/frontend-h5/src/components/chat/IntegrationZone.vue` | 删除 [1] 操作按钮（template 段、script 段、style 段）；保留 [2] QueueCapsule + [3] 引导语 + .integration-zone 容器样式 |

### 6.2 不动范围（明确列出）

| 文件 | 不动原因 |
|------|----------|
| `src/frontend-h5/src/components/chat/InputBar.vue` | v1.2 已正确（4 按钮工具栏 + InputBar 内上方居中位置） |
| `src/frontend-h5/src/components/chat/inputBarCallAgentState.ts` | helper 函数保留，可能未来被其他场景复用 |
| `src/frontend-h5/src/components/chat/integrationZoneLogic.ts` | helper 函数保留，可能未来被其他场景复用 |
| `src/frontend-h5/src/components/chat/QueueCapsule.vue` | 子组件不动 |
| `src/frontend-h5/src/components/chat/inputBarGuideText.ts` | 引导语文案 helper 不动 |
| `src/frontend-h5/src/stores/conversation.ts` | store action（shakeAgent / cancelQueue / closeCurrentConversation / reopenCurrentConversation）调用链不变 |
| `src/frontend-h5/src/components/chat/InputBar.test.ts` | 单元测试不动 |
| `src/frontend-h5/src/components/chat/integrationZoneLogic.test.ts` | 纯函数无变化，测试不动 |

### 6.3 依赖与阻塞

- **外部依赖**：无
- **阻塞项**：无
- **建议协同**：
  - 父组件 `ChatPanel.vue` 中对 IntegrationZone 的 `@callAgent` / `@cancelQueue` / `@endConversation` / `@reopenConversation` 事件监听可能需要清理（IntegrationZone 不再 emit 这些事件后，监听器变为无效）。建议由架构师在实现时一并处理。

---

## 7. 待确认问题

### Q1. 本地代码与"v1.2 线上状态"描述不一致 ⚠️

**现象**：
- 任务描述：v1.2 线上 InputBar 工具栏为 **4 按钮**（emoji / 文件 / 语音 / **坐席头像**）
- 本地 `InputBar.vue` 现状：模板中仅 **3 按钮**（emoji / 文件 / 语音），注释明确写着"v1.3：坐席按钮已彻底移除（由 IntegrationZone 接管 6 态 agent 入口）"

**可能原因**：
- 本地代码尚未同步到 v1.2 线上版本
- 或 InputBar.vue 的代码注释指的是过去的 v1.3，与当前任务中的 v1.3 是同名但不同含义

**建议**：
- **以原型 HTML 为准**（明确 v1.3 目标为 4 按钮工具栏）
- 主理人需确认本地代码是否已回滚到 v1.2 基线，是否需要在 InputBar.vue 中同步加入坐席头像按钮（按 v1.2 形态）

**风险**：若本地代码不同步，架构师实现时可能基于错误的基线。

---

### Q2. 测试文件 `IntegrationZone.test.ts` 不存在 ⚠️

**现象**：
- 任务描述提及 `IntegrationZone.test.ts`（删除坐席按钮相关测试用例）
- 实际目录中只有 `integrationZoneLogic.test.ts`（纯函数测试），**无 IntegrationZone 组件级测试**

**建议**：
- 主理人确认：是仅依赖现有 `integrationZoneLogic.test.ts` 即可？还是需要新建 IntegrationZone 组件级测试？
- 默认方案（推荐）：**不新建组件级测试**，依赖纯函数测试 + 浏览器实测验证

**风险**：低（纯函数测试已覆盖核心逻辑）。

---

### Q3. ChatPanel 父组件的事件监听清理

**现象**：
- 父组件 `ChatPanel.vue` 当前监听 IntegrationZone 的 `@callAgent` / `@cancelQueue` / `@endConversation` / `@reopenConversation` 事件
- v1.3 后 IntegrationZone 不再 emit 这些事件，父组件监听器变为无效

**建议**：
- 由架构师在实现时同步清理 ChatPanel.vue 中的 IntegrationZone 事件监听
- 本 PRD 不强制要求（属架构师职责范围）

**风险**：低（无效监听器不影响功能，仅为代码冗余）。

---

### Q4. helper 文件 `integrationZoneLogic.ts` 最终去留

**现象**：
- 任务明确说 helper 文件"保留给未来用"
- 但 `integrationZoneLogic.ts`（专门服务 IntegrationZone）的 `computeIntegrationBtnText` / `computeIntegrationBtnIcon` / `computeIntegrationBtnTitle` / `computeIntegrationBtnClass` / `computeIntegrationGuideClass` / `computeCallAction` 等函数在 v1.3 后**无任何消费者**（IntegrationZone 已不渲染按钮）
- `inputBarCallAgentState.ts` 仍在被 InputBar.vue 使用（虽然 InputBar 也已不渲染坐席按钮，但 computed 仍存在），不算死代码

**建议**：
- 本次 v1.3 保留 `integrationZoneLogic.ts` 不动（遵循任务指示）
- 未来由架构师评估：若 6 个月内无新消费者，可清理以减少维护成本

**风险**：低（仅代码冗余，无功能影响）。

---

## 变更记录

| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|------|------|----------|--------|----------|
| 2026-08-04 | v1.3 | 初始版本：删除 IntegrationZone 旧"人工坐席"按钮，统一 InputBar 工具栏为唯一坐席入口 | 许清楚（产品经理） | 用户反馈 v1.2 双坐席入口视觉冗余，截图标注删除 IntegrationZone 锁图标按钮 |

---

## 评审签字

- [ ] 产品经理：许清楚
- [ ] 架构师：（待评审）
- [ ] 测试负责人：（待评审）
- [ ] 主理人：Duckula