simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f2fd4fa0127bb0620886f4c9d2304f46501eedab
wecom_it_smart_desk/docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-工具栏统一设计-v1.3.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

258 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 工具栏统一设计 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
Reference in New Issue View Git Blame Copy Permalink