wecom_it_smart_desk/docs/01-产品文档/05-用户端H5/PRD-REQ-用户-001-群聊双模式-v1.0.md

群聊参与者展开/缩略双模式 PRD

版本: v1.0 日期: 2026-07-14 作者: 许清楚（产品经理） 状态: 待评审 子系统: 05-用户端H5 模块: 群聊

---

1. 项目信息

字段	值
项目名称	participant_dual_mode
技术栈	H5端: Vue3 + Vant4 + TypeScript / 坐席端: Vue3 + Element Plus + TypeScript / 后端: 无需改动
语言	中文
UI风格	企微浅色扁平风格，accent = #07C160

原始需求复述

IT智能服务台群聊功能中，同一会话最多有4种角色：原始员工（发起人）、主责坐席、协作坐席、被邀请人。当前参与者展示存在两个问题：H5端 ParticipantList.vue 平铺完整列表始终占用较大空间，挤压聊天区域；坐席端 ParticipantBar.vue 一行横条信息密度低，只能看到名字缩略。本次需求为群聊参与者展示实现展开/缩略双模式，让用户在"快速概览谁在群里"和"查看参与者详情"之间切换。

已确认设计决策（用户已拍板）

1. H5端展开模式：方案B 底部弹出 — Vant4 van-popup position="bottom"
2. 坐席端展开模式：就地向下展开 — 点击 ParticipantBar 横条向下撑开详情面板（~150px）
3. 头像排列顺序：主责坐席第一位，其余按加入时间排列，不分组
4. 退出确认：H5端点击"退出会话"弹 van-dialog 二次确认（保留已有实现）
5. 缩略模式角色区分：头像边框色 — 坐席蓝框、发起人橙框、被邀请人无框
6. 缩略模式信息量：头像条显示数字徽标，如"5人在群"
7. 自己的标识：自己头像加高亮环 + 略放大
8. 默认模式：缩略模式为默认，点击展开
9. 超员处理：缩略头像条超过N个显示前几个 + "+剩余人数"文本；展开模式支持滚动

---

2. 产品定义

2.1 产品目标

提升信息密度与空间利用率：将H5端原本平铺占用大量纵向空间的参与者列表改为缩略头像条（一行），释放出的空间归还给聊天区域；将坐席端一行横条改为可展开的详情面板，在需要时才展示完整信息。两端默认均为缩略模式，用户按需展开，兼顾"快速概览"与"查看详情"两种场景。

统一双端交互心智模型：H5端和坐席端虽然技术栈不同（Vant4 vs Element Plus），但交互逻辑保持一致——缩略模式看"谁在群里"，展开模式看"每个人是谁"，降低用户跨端使用的学习成本。

保持角色辨识度：通过头像边框色（坐席蓝框、发起人橙框、被邀请人无框）和自己的高亮环，在缩略模式下也能快速辨识参与者的角色身份和自己的位置。

2.2 用户故事

#	角色	用户故事
US-1	员工	As a 报修员工, I want 在聊天页面看到一行紧凑的参与者头像条而不是占满半屏的列表, so that 聊天区域有更多空间显示消息记录，我能看清上下文
US-2	员工	As a 被邀请参与会话的员工, I want 点击头像条从底部弹出参与者详情面板，看到每个人的姓名、部门和角色, so that 我能确认群里都有谁再决定是否发言
US-3	员工	As a 被邀请员工, I want 在展开的详情面板中点击"退出会话"并经过二次确认后退出, so that 我可以安全退出不再相关的会话，且不会误触退出
US-4	坐席	As a 主责坐席, I want 点击参与者横条就地展开详情面板，看到每个参与者的完整信息（姓名、角色、加入状态）, so that 我在需要时快速了解协作人员情况，不展开时不占空间
US-5	坐席	As a 主责坐席, I want 在展开的详情面板中直接操作"邀请"和"移除参与者", so that 管理参与者不需要额外跳转到其他页面
US-6	坐席/员工	As a 任何参与者, I want 缩略模式中通过头像边框颜色快速区分坐席/发起人/被邀请人，并看到自己的头像有高亮标记, so that 我一眼就能知道群里的角色构成和自己的位置

---

3. 需求池（P0/P1/P2）

P0 — 必须完成（核心体验）

FE-H5-01 H5端缩略模式头像条

项目	说明
需求	将 ParticipantList.vue 改造为默认显示一行紧凑头像条
布局	横向排列：[5人在群] [头像1][头像2][头像3]+2 ，高度约 40px
头像排列	主责坐席第一位，其余按加入时间顺序排列，不分组
角色边框	坐席蓝框 #3b82f6、发起人橙框 #FF9800、被邀请人无边框
自己标识	自己头像加高亮环 #07C160（2px ring）+ scale(1.1) 放大
超员处理	缩略头像条最多显示 N 个头像（N=4），超出显示 +剩余人数 文本
数字徽标	头像条左侧显示"X人在群"文字徽标
交互	点击头像条任意位置触发展开
约束	缩略模式高度 ≤ 44px，不遮挡聊天消息区

FE-H5-02 H5端展开模式（底部弹出）

项目	说明
需求	点击缩略头像条，从底部弹出参与者详情面板
组件	Vant4 van-popup position="bottom" round
内容	完整参与者列表：头像(32px) + 姓名 + 部门 + 角色徽标(发起人/坐席/已加入/待加入)
排列	与缩略模式一致：主责坐席第一位，其余按加入时间排列
当前用户	高亮背景色 + "（我）"文字标签（保留现有实现）
头像降级	有avatar URL用img，加载失败显示姓名首字（保留现有逻辑）
退出按钮	仅被邀请人可见，点击弹 showConfirmDialog 二次确认（保留现有实现）
关闭方式	下滑关闭 / 点击遮罩关闭 / 点击右上角关闭按钮
约束	弹出面板高度不超过屏幕 60%，内容区支持纵向滚动；上方聊天记录仍可见

FE-Agent-01 坐席端缩略模式横条改造

项目	说明
需求	改造 ParticipantBar.vue 缩略模式，增加数字徽标和角色边框
布局	保持现有一行横条结构：[N人参与:] [头像1][头像2]... + 邀请
角色边框	主责坐席蓝框 #3b82f6、协作坐席绿框 #07C160、发起人橙框 #FF9800、被邀请人无框
自己标识	自己头像加高亮环 + scale(1.1) 放大
超员处理	超过 N 个头像（N=6）只显示前几个 + +剩余人数 文本，溢出部分不横向滚动
数字徽标	保留现有"N人参与:"文字，增加总人数计算（主责+协作+被邀请）
交互	点击横条主体区域触发展开；"+ 邀请"按钮独立点击不触发展开
约束	缩略模式高度 ≤ 36px

FE-Agent-02 坐席端展开模式（就地展开）

项目	说明
需求	点击 ParticipantBar 横条，在其原位置向下撑开详情面板
布局	flex 垂直布局，展开面板高度 ~150px，消息区被 flex 自动压缩但依然可见可滚动
内容	参与者详情：头像(28px) + 姓名 + 角色标签(主责/协作/发起人) + 加入状态(已加入/待加入)
排列	主责坐席第一位，其余按加入时间排列，不分组
操作按钮	主责坐席可见"+ 邀请"按钮和每项的"移除"图标（保留现有功能）
收起	面板右上角"收起"按钮 / 再次点击横条折叠回去
动画	展开/收起使用 CSS transition（max-height / opacity），时长 ≤ 200ms
约束	展开面板内容超出时支持纵向滚动；展开时消息区最小高度不低于 200px

P1 — 应该完成（体验增强）

FE-Common-01 展开状态记忆

项目	说明
需求	用户在当前会话中展开参与者面板后，切换会话再切回时保持展开/收起状态
实现	状态存储在组件本地 ref，按会话 ID 记忆（不持久化到 localStorage）
约束	页面刷新后恢复默认缩略模式

FE-H5-03 缩略头像条角标提示

项目	说明
需求	当有新的待加入参与者时，缩略头像条显示小红点角标
触发	participants 列表中存在 joined === false 的项时显示
样式	头像条右上角 8px 红点

FE-Agent-03 展开面板头像悬停 tooltip

项目	说明
需求	坐席端展开面板中，鼠标悬停头像显示完整姓名和部门 tooltip
组件	Element Plus el-tooltip
约束	仅在姓名被截断时显示（内容溢出时）

P2 — 可以后续实现（锦上添花）

FE-Common-02 参与者加入/退出动画

项目	说明
需求	参与者加入或退出时，头像条有平滑的增减动画
实现	Vue <TransitionGroup> + CSS transition
约束	不影响功能，动画时长 ≤ 300ms

FE-Common-03 缩略头像条长按预览（H5端）

项目	说明
需求	H5端长按缩略头像条中某个头像，弹出该参与者的简要信息卡片
组件	Vant4 van-popup 小型弹窗
约束	不与点击展开冲突，长按 ≥ 500ms 触发

FE-Agent-04 展开面板键盘快捷键

项目	说明
需求	坐席端支持快捷键切换展开/收起
快捷键	Ctrl+Shift+P（Participant）
约束	仅在聊天区域聚焦时生效

---

4. UI 设计稿描述

4.1 H5端 — 缩略模式（默认）

┌─────────────────────────────────┐
│  [< 返回]   IT智能服务台         │  ← 顶部导航栏
├─────────────────────────────────┤
│                                 │
│    [聊天消息区域 — 释放空间]      │
│                                 │
│    消息1...                      │
│    消息2...                      │
│                                 │
├─────────────────────────────────┤
│ 5人在群  (🟦)(🟧)( )( )+1  ▼    │  ← 缩略头像条 (h≈40px)
├─────────────────────────────────┤
│  [输入框]              [发送]    │  ← 输入区
└─────────────────────────────────┘

缩略头像条细节：
┌──────────────────────────────────┐
│ 5人在群  [A][B][C][D]+1        ▼ │
│          ↑  ↑  ↑  ↑             │
│         蓝框 橙框 无框 高亮环     │
│        (坐席)(发起人)(被邀请)(自己)│
└──────────────────────────────────┘
- 头像尺寸: 28px 圆形
- 角色边框: 2px solid (蓝#3b82f6/橙#FF9800/无)
- 自己: 额外高亮环 #07C160 + scale(1.1)
- 超员: 最多4个头像 + "+N" 文本
- 箭头: ▼ 表示可展开

4.2 H5端 — 展开模式（底部弹出）

┌─────────────────────────────────┐
│  [< 返回]   IT智能服务台         │
├─────────────────────────────────┤
│                                 │
│    [聊天消息区域 — 仍可见]       │  ← 上方聊天记录可见
│    消息1...                      │
│                                 │
├─────────────────────────────────┤
│ 5人在群  [A][B][C][D]+1      ▼  │  ← 缩略条仍显示
╞═════════════════════════════════╡  ← van-popup 分隔
│  参与者                  [×]    │  ← 弹出面板头部
│─────────────────────────────────│
│ (🟦) 张三         IT坐席  坐席   │  ← 主责坐席(蓝框)
│ (🟧) 李四         财务部  发起人 │  ← 发起人(橙框)
│ ( )  王五         市场部  已加入 │  ← 被邀请人
│ ( )  赵六         人事部  待加入 │  ← 待加入(灰色)
│─────────────────────────────────│
│        [  退出会话  ]            │  ← 仅被邀请人可见
└─────────────────────────────────┘
  ↑ 下滑关闭 / 点击遮罩关闭

弹出面板细节：
- van-popup position="bottom" round
- 最大高度: 60vh，内容超出纵向滚动
- 头像: 32px 圆形
- 每行: 头像 + 姓名 + 部门 + 角色徽标
- 当前用户: 背景色高亮 + "（我）"标签
- 退出按钮: 红色描边按钮，点击弹 van-dialog 二次确认

4.3 坐席端 — 缩略模式（默认）

┌──────────────────────────────────────────────────────┐
│  UserInfoBar (用户信息栏)                             │
├──────────────────────────────────────────────────────┤
│  TroubleshootBar (排查步骤栏)                         │
├──────────────────────────────────────────────────────┤
│ 5人参与: [A][B][C][D][E][F]+1            + 邀请  ▼  │  ← ParticipantBar 缩略 (h≈36px)
├──────────────────────────────────────────────────────┤
│                                                      │
│              [聊天消息区域]                           │
│                                                      │
│              消息1...                                │
│              消息2...                                │
│                                                      │
├──────────────────────────────────────────────────────┤
│  [回复输入框]                              [发送]    │
└──────────────────────────────────────────────────────┘

缩略横条细节：
┌──────────────────────────────────────────────────────┐
│ 5人参与: (🟦)(🟧)( )( )(🟩)( )+1    + 邀请       ▼ │
│          ↑  ↑  ↑  ↑  ↑  ↑                          │
│        主责 发起 被邀 被邀 协作 被邀                  │
│        蓝框 橙框 无框 无框 绿框 无框                  │
└──────────────────────────────────────────────────────┘
- 头像尺寸: 20px 圆形
- 角色边框: 2px solid (蓝#3b82f6/绿#07C160/橙#FF9800/无)
- 自己: 高亮环 #07C160 + scale(1.1)
- 超员: 最多6个头像 + "+N" 文本
- "+ 邀请"按钮独立点击，不触发展开
- ▼ 箭头表示可展开

4.4 坐席端 — 展开模式（就地展开）

┌──────────────────────────────────────────────────────┐
│  UserInfoBar (用户信息栏)                             │
├──────────────────────────────────────────────────────┤
│  TroubleshootBar (排查步骤栏)                         │
├──────────────────────────────────────────────────────┤
│ 5人参与: [A][B][C][D][E][F]+1            + 邀请  ▲  │  ← 横条(点击收起)
│┌────────────────────────────────────────────────────┐│
││  参与者详情                            [收起]      ││  ← 展开面板 (~150px)
││────────────────────────────────────────────────────││
││ (🟦) 张三(主责)        IT坐席                     ││  ← 主责坐席
││ (🟧) 李四              财务部  发起人              ││  ← 发起人
││ ( )  王五              市场部  已加入     [×]     ││  ← 被邀请人(可移除)
││ ( )  赵六              人事部  待加入     [×]     ││  ← 待加入(可移除)
││ (🟩) 钱七(协作)        IT坐席                     ││  ← 协作坐席
│└────────────────────────────────────────────────────┘│
├──────────────────────────────────────────────────────┤
│                                                      │
│              [聊天消息区域 — 被压缩但可见]            │  ← flex 自动压缩
│              消息1...                                │
│                                                      │
├──────────────────────────────────────────────────────┤
│  [回复输入框]                              [发送]    │
└──────────────────────────────────────────────────────┘

展开面板细节：
- 面板高度: ~150px，内容超出纵向滚动
- 头像: 28px 圆形
- 每行: 头像 + 姓名 + 角色标签 + 部门 + 加入状态 + [移除图标]
- 移除图标: 仅主责坐席可见，点击移除参与者
- "+ 邀请"按钮: 仅主责坐席可见
- 收起: 点击"收起"按钮或再次点击横条
- 动画: max-height + opacity transition ≤ 200ms
- 消息区最小高度: 200px（保证可用性）

4.5 角色边框色规范

角色	边框色	色值	说明
主责坐席	蓝色	#3b82f6	2px solid border
协作坐席	绿色	#07C160	2px solid border
发起人（员工）	橙色	#FF9800	2px solid border
被邀请人	无边框	—	默认样式
自己（任意角色）	高亮环	#07C160	额外 2px ring + scale(1.1)

---

5. 待确认问题

#	问题	影响范围	建议
Q1	缩略头像条超员阈值 N 的取值：H5端取4、坐席端取6是否合理？	两端缩略模式	建议根据实际手机屏幕宽度（375px基准）和桌面端横条宽度做原型验证后确定
Q2	H5端坐席目前无头像接口，缩略模式中坐席头像使用首字母降级，蓝色边框 + 首字母的视觉效果是否需要设计稿确认？	H5端缩略+展开	建议出一张视觉稿确认首字母头像 + 边框的呈现效果
Q3	坐席端展开面板高度固定 ~150px，当参与者超过5人时需要滚动。是否考虑改为自适应高度（如 min(150px, 内容高度)）？	坐席端展开	建议固定150px + 滚动，避免面板过高挤压消息区
Q4	发起人（原始员工）在坐席端的角色边框目前使用橙色，但现有代码中坐席端未区分发起人边框（只有主责蓝边、协作绿边）。是否需要后端在 participants 数据中标记发起人角色？	坐席端	当前 participants 不含发起人（发起人在 currentConversation.employee_id），需确认坐席端是否需要单独展示发起人头像条目
Q5	H5端展开模式弹出面板与输入框的层级关系：弹出面板是否遮罩输入框？还是输入框下移？	H5端展开	建议遮罩输入框，弹出面板为独立浮层，关闭后恢复输入框