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

14 KiB
Raw Blame History

工具栏统一设计 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