Simon
225 lines
8.6 KiB
Markdown
225 lines
8.6 KiB
Markdown
# 交付 - 工具栏统一设计 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 · 团队助手） |