wecom_it_smart_desk/docs/01-产品文档/02-会话管理/交付-REQ-会话-001-工具栏统一设计v1.9-开发交付清单.md

# 交付 - 工具栏统一设计 v1.9 · 开发交付清单

> **版本**: v1.9（员工端落地版 · 2026-08-05 最终微调）
> **REQ 编号**: REQ-会话-001
> **负责人**: Duckula 主理人
> **状态**: ✅ 已拍板，正式交付开发
> **基线原型**: `原型-REQ-会话-001-工具栏统一设计v1.9-员工端落地版.archive.html`
> **历史版本**（已归档，仅供回溯）: v1.3 / v1.4 / v1.5 / v1.6 / v1.7 / v1.8

---

## 一、目标

把员工端会话窗口的输入区工具栏统一为：

> 圆角长方形 + 中央圆润拱形轨道（人工坐席按钮 60px 居中），
> 工具栏作为唯一浮起的玻璃元素，融于「会话消息区 ↔ 消息输入区」之间。
> 三区共享同一块连续浅色表面，无内部区隔线。

**业务目标**：让"转人工坐席"成为输入区里最显眼、可点、不突兀的主 CTA。

---

## 二、需要修改/创建的文件

| # | 文件 | 类型 | 改动 | 影响范围 |
|---|------|------|------|----------|
| 1 | `src/frontend-h5/src/components/chat/InputBar.vue` | **改** | 工具栏容器重构为 `.gem-toolbar`；新增 SVG 轨道；坐席按钮 .agent-btn.gem（60px、居中、不探出、无光晕）；工具按钮 .glass-btn 保持 40px 在轨道内不溢出；aria-label/title/focus-visible；装饰 SVG 加 aria-hidden | 仅本组件 |
| 2 | `src/frontend-h5/src/components/chat/InputBar.test.ts` | **改** | 补充两端收口 + 坐席 60px 居中结构测试 | 测试同步 |
| 3 | `src/frontend-h5/src/assets/images/agent-avatar.jpg` | **新建/替换** | 接入实际员工头像资源（占位图 `agent-avatar-v0.8.jpg` 替换） | 资源替换 |
| 4 | `src/frontend-h5/src/styles/theme.scss`（或对应 token 文件） | **改** | 新增 gem 工具栏相关设计 token：`--gem-toolbar-height: 84px` / `--gem-btn-size: 40px` / `--gem-agent-size: 60px` / `--gem-radius: 18px` | 全局可复用 |

**不动**：
- `IntegrationZone.vue`（v1.3 已删除坐席按钮）
- `inputBarCallAgentState.ts` / `integrationZoneLogic.ts`（helper 保留）
- `IntegrationZone.test.ts`（无坐席按钮相关测试）
- 其余无关组件

---

## 三、SVG 轨道（必须严格按此 path 实现）

**viewBox**: `0 0 312 84`
**中心线 y**: `42`
**关键几何**（不要改）：
- 坐席按钮 60px，y 区间 `12..72`
- 工具按钮 40px，y 区间 `22..62`
- 轨道左右端点 `x=0` / `x=312`，圆角端帽半径 `18`
- 顶/底两端直线段：`y=18` / `y=66`，x 区间 `[18..84]` 与 `[216..294]`
- 穹顶区间：`x 84..216`
- 顶点：`y=4`（顶）/ `y=80`（底），位于 `x=156`

```html
<svg class="gem-toolbar-bg" viewBox="0 0 312 84"
     preserveAspectRatio="xMidYMid meet"
     aria-hidden="true" role="presentation">
  <path d="M 18 18
           L 84 18
           C 116 18, 126 6, 156 4
           C 186 6, 196 18, 216 18
           L 294 18
           C 302 18, 312 26, 312 34
           L 312 50
           C 312 58, 302 66, 294 66
           L 216 66
           C 196 66, 186 78, 156 80
           C 126 78, 116 66, 84 66
           L 18 66
           C 0 66, 0 58, 0 50
           L 0 34
           C 0 26, 10 18, 18 18 Z"
        fill="url(#g-rail)" stroke="rgba(255,255,255,0.85)" stroke-width="1.2"/>
</svg>
```

**SVG defs（轨道渐变 + 已有图标渐变）** 全部沿用 v1.9 落地版文件中的 `<defs>` 块，复制即可。

---

## 四、核心 CSS（按此实现）

```scss
.gem-toolbar {
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 0 16px;
  width: fit-content;
  height: 84px;
}
.gem-toolbar-bg {
  position: absolute; inset: 0;
  width: 100%; height: 100%;
  z-index: 0; pointer-events: none; overflow: visible;
}
.gem-row {
  position: relative; z-index: 2;
  display: flex; align-items: center; justify-content: center;
  gap: 12px;
}
.gem-toolbar .agent-btn.gem {
  width: 60px; height: 60px;
  margin: 0 6px; z-index: 3;
  box-shadow: none;          /* 不探出 · 无光晕 */
}
.gem-toolbar .glass-btn { z-index: 2; }

/* 可见的键盘 focus 态（可达性） */
.glass-btn:focus-visible,
.agent-btn:focus-visible {
  outline: 2px solid #6366f1;
  outline-offset: 2px;
}
```

**三区融合关键**：消息区 / `.gem-band` / `.inputbar-mock` 都不要 `border-top`/`border-bottom`，且 `background: transparent`，让 `chatpanel` 自身的渐变背景透出来，仅窗口标题栏保留 chrome 分隔。

---

## 五、可访问性（必做）

- 每个 `<button>` 同时具备 `title` 与 `aria-label`
- 装饰性 gem 轨道 SVG：`aria-hidden="true"` + `role="presentation"`
- 坐席徽标：`aria-label="在线"`（按实际状态文案切换）
- 全部按钮可见 `:focus-visible` 蓝环（参考 #6366f1 2px outline + 2px offset）
- 触控目标 ≥ 44px：工具按钮 40px 仅差 4px，靠 `padding` 或 `outline` 不缩小可视区；坐席按钮 60px 满足

---

## 六、响应式预案（≤480px 窄屏 fallback）

```scss
@media (max-width: 480px) {
  /* 拱形轨道在窄屏易走样，降级为方案 A 扁平胶囊 */
  .gem-toolbar { height: 56px; padding: 0 12px; }
  .gem-toolbar-bg { display: none; }  /* 隐藏拱形 SVG */
  .gem-row {
    background: rgba(255, 255, 255, 0.55);
    backdrop-filter: blur(28px) saturate(180%);
    border: 1px solid rgba(255, 255, 255, 0.7);
    border-radius: 20px;
    padding: 8px 16px;
  }
  .gem-toolbar .agent-btn.gem { width: 52px; height: 52px; }
  .gem-toolbar .glass-btn { width: 36px; height: 36px; }
}
```

---

## 七、深色模式预案（预留实现）

```scss
@media (prefers-color-scheme: dark) {
  .chatpanel-mock {
    background: linear-gradient(180deg, rgba(30,30,40,0.95), rgba(20,20,28,0.95));
  }
  .mock-msg.ai {
    background: rgba(99, 102, 241, 0.18);
    border-color: rgba(99, 102, 241, 0.3);
    color: #e5e7eb;
  }
  /* 轨道渐变 g-rail 在 dark 下需重新定义两端 stop-color */
  /* 输入框背景：rgba(255,255,255,0.08) */
}
```

---

## 八、落地检查清单（☑ 12 项 · 交付时逐项打勾）

- [x] 圆角长方形 + 中央圆润拱形轨道（SVG path 已固化）
- [x] 人工坐席按钮 60px 居中、不探出、无光晕
- [x] 两端 4 个工具按钮（emoji/文件/语音/群聊）保持 40px 圆形玻璃，在轨道内不溢出
- [x] 消息区 / gem 工具栏 / InputBar 三区融为连续浅色表面，无内部区隔线
- [x] 仅窗口标题栏保留 chrome 分隔（border-bottom）
- [x] 键盘可达：所有按钮 `title` + `aria-label`，可见 `:focus-visible` 蓝环
- [x] 装饰性 SVG 轨道 `aria-hidden="true" role="presentation"`
- [ ] 头像占位图 `agent-avatar-v0.8.jpg` 接入实际员工头像资源
- [ ] 开发实现：`InputBar.vue` 按此版结构重构
- [ ] 响应式：≤480px 宽度下退化方案 A 扁平胶囊（拱形在窄屏易走样，预留 fallback）
- [ ] 深色模式：背景渐变 / 轨道渐变 / 气泡背景三处需额外定义 `prefers-color-scheme: dark` 变量
- [ ] 回归测试：补充两端收口 + 坐席 60px 居中结构测试用例（`InputBar.test.ts`）

---

## 九、回归测试要点

- 5 个按钮均渲染，顺序：emoji / 文件 / 坐席 / 语音 / 群聊
- 坐席按钮 DOM 含 `.gem` 类，宽高严格 60×60
- SVG `<path>` 的 `d` 属性与本清单 §三 一致（防止误改坐标）
- 装饰 SVG `aria-hidden="true"`
- `@media (max-width: 480px)` 下 `.gem-toolbar-bg` 不可见、`.gem-row` 有胶囊样式
- 键盘 Tab 顺序：emoji → 文件 → 坐席 → 语音 → 群聊 → 输入框 → 发送
- 焦点态可见 2px outline

---

## 十、开放项（交付后不影响主流程，按需迭代）

| 项 | 默认值 | 说明 |
|----|--------|------|
| 坐席 60px 口径 | 较 40px 工具图标大 50% | 若后续产品澄清指 v1.6 的 54px 再 +50%（=81px），需重算 SVG path |
| 头像资源 | 占位图 | 接入实际员工头像后视觉验收 |
| 顶端圆润度 | 当前 SVG path 已推到接近几何极限 | 继续推会出现"拱成平顶"或圆角端帽被挤压；若有更强需求须重新设计几何 |
| 深色模式 | §七 提供实现骨架 | 需设计 token 全局对齐 |

---

## 十一、上线流程建议

1. **开发还原**：按 §三 §四 实现 `InputBar.vue`，逐项打勾 §八 清单
2. **设计验收**：与 Duckula 主理人对齐像素、SVG 几何、可访问性
3. **窄屏验收**：≤480px fallback 单独跑一遍
4. **回归测试**：跑 §九 测试要点
5. **预发布**：灰度 1% → 10% → 100% 观察工具栏点击率 / 误触率
6. **全量上线**：归档 v1.9 原型至历史目录，更新 PRD 引用

---

**拍板人**: Simon
**拍板时间**: 2026-08-05
**文档版本**: 交付版 v1
**联系人**: Duckula 主理人（WorkBuddy · 团队助手）