IM直播 / 消息列表与聊天室扩展

列表一键已读＋对话气泡Badge 功能 原型＋PRD

本方案覆盖两个主场景：`聊天列表` 新增 `一键已读` 下拉提示条入口，用于处理当前 `訊息` 列表全部未读； `聊天室` 内则新增发送者 `Badge` 展示，用于区分普通用户等级、群主、群管、主播角色。点击列表页 `一键已读` 后，统一将当前 `訊息` 列表未读会话置已读，并同步刷新列表未读数、底部聊天入口角标与下拉提示条状态； 聊天室内每位发送者仅展示一个 Badge，并按既定优先级选择最终样式。

列表动作 `訊息` 列表页仅在下拉列表时露出 `一键已读` 提示条，展示当前列表实际未读数，并提供 `X` 关闭入口与成功 toast 反馈。
对话Badge 聊天室内按发送者角色展示对话气泡 Badge，覆盖 `用户 / 群主 / 群管 / 主播` 四类身份。
显示优先级 同一发送者同一时刻仅展示一个 Badge，优先级为 `群主 > 群管 > 主播 > 用户等级Lv`。
同步重点 需同步刷新列表未读数、底部聊天角标、会话行红点，以及聊天室内角色 Badge 的服务端角色映射。

H5 原型

以下原型直接使用你提供的两张截图：图1为聊天列表页 `一键已读` 的同页组合示意，上方展示下拉触发后的提示条与 `X` 关闭入口，下方展示成功后的 toast 反馈； 图2说明聊天室内对话气泡 Badge 的展示位置、角色类型与现有右侧功能入口的共存关系。

01 聊天列表 / 列表一键已读 在 `訊息` 列表页下拉至触发阈值后，于页签下方露出 `一键已读` 顶部提示条；当前截图同时组合展示顶部提示条、`X` 关闭入口与底部成功 toast 的样式结果。
聊天列表一键已读原型
落点说明： `一键已读` 为聊天列表级入口，位于 `訊息 / 聯絡 / 群組` 页签下方的下拉展开区；当前截图为同页组合示意，上方表现下拉后露出的提示条，下方表现成功反馈 toast。
交互说明： 实际交互仍以 PRD 时序为准：仅当用户下拉列表达到触发阈值时，提示条才展示；点击 `X` 可关闭当前次下拉提示条，点击 `一键已读` 后直接发起请求，成功后隐藏提示条并展示底部成功 toast。当前截图仅将入口态与成功反馈态合并展示。
02 聊天室 / 对话气泡Badge 在聊天室消息流内，发送者昵称右侧按角色展示 Badge；普通用户显示等级头盔，特殊角色显示 `群主`、`群管`、`主播` 标签。
聊天室对话气泡Badge原型
落点说明： Badge 固定挂载在发送者昵称右侧，与消息时间、消息正文分层展示，不进入消息正文区域。
展示说明： 同一发送者只展示一个 Badge；若同时满足多角色，按 `群主 > 群管 > 主播 > 用户等级Lv` 取最高优先级展示。

PRD 章节

1. 需求背景

  • 当前 `訊息` 列表存在大量未读会话时，用户只能逐条进入或依赖零散红点判断，缺少对当前列表的统一已读处理动作。
  • 当前聊天室消息流缺少一致的发送者身份标识，普通用户等级、群主、群管、主播角色分辨成本高。
  • 业务需要同时补足 `列表级已读收敛` 与 `对话气泡角色识别` 两个场景，且不改变现有消息列表与聊天室主体布局。
  • 本期目标是让用户在列表页快速清理未读，在聊天室内快速识别发送者角色。

2. 原型交互

列表一键已读流程

01 触发 用户在 `訊息` 页签下拉列表；仅当位移达到阈值且 list_unread_total > 0 时，才露出提示条。
→
02 展示 提示条位于页签下方、快捷入口上方；默认文案为 `当前有 {list_unread_total} 条未读消息`，右侧展示 `一键已读` 与 `X`。
→
03 关闭 点击 `X` 后立即隐藏当前次下拉提示条；本次下拉停留期间不再重复出现，松手回弹或重新下拉后可再次展示。
→
04 请求 点击 `一键已读` 后进入 loading 与不可重复点击状态，请求服务端将当前 `訊息` 列表全部未读会话更新为已读。
→
05 结果 成功后清空列表未读数并隐藏提示条，再展示 `已将 {read_all_success_count} 条消息标记为已读` toast 2 秒；失败则提示 `一键已读失败，请稍后重试`。

聊天室 Badge 流程

01 定位 聊天室内发送者昵称右侧展示对话气泡 Badge，与消息时间、消息正文分层展示。
→
02 角色映射 普通用户展示 `Lv. 1-51` 等级头盔；群主展示 `群主`，群管展示 `群管`，主播展示 `主播`。
→
03 互斥输出 同一发送者只展示一个 Badge；若角色冲突，按 `群主 > 群管 > 主播 > 用户等级Lv` 选择最终样式。
3. 字段定义

列表一键已读字段

字段名称 交互 说明
入口位置 列表下拉展开区内嵌提示条 位于 `訊息 / 聯絡 / 群組` 页签下方、功能快捷入口上方，不进入 `聯絡`、`群組` 页签。
展示条件 下拉达到阈值后展示 仅当当前 `訊息` 列表总未读数 list_unread_total > 0，且用户对列表执行下拉手势并达到触发阈值时展示提示条。
提示文案 顶部提示条默认文案 左侧固定展示 `当前有 {list_unread_total} 条未读消息`，其中 {list_unread_total} 展示实际未读总数。
默认动作 右侧展示 `一键已读` 提示条右侧为主动作入口，用于处理当前 `訊息` 列表全部未读会话。
触发阈值 下拉位移达到阈值露出 建议下拉位移达到 48 px 后露出提示条；位移小于阈值时不展示。
隐藏条件 离开下拉展开区即隐藏 列表静止、上滑、松手回弹结束、切换页签时隐藏提示条。
关闭入口 `X` 关闭当前次下拉提示条 提示条最右侧展示 `X` 关闭图标；点击后仅关闭当前次下拉提示条，本次下拉停留期间不再重复展示。
点击动作 点击 `一键已读` 发起请求 请求参数至少带 tab_type = message、request_id、last_sync_version。
成功结果 成功后刷新列表与提示条状态 当前 `訊息` 列表全部未读置已读，列表红点、底部聊天角标、提示条显隐同步刷新。
底部聊天角标 沿用现有角标封顶规则 当底部聊天总未读数大于 `999` 时展示 `999+`，小于等于 `999` 时展示实际数值。
成功 toast 成功后底部展示结果反馈 成功后在底部聊天入口上方展示 `已将 {read_all_success_count} 条消息标记为已读`，展示时长 2 秒，自动消失，不遮挡顶部提示条区域；其中 read_all_success_count 取点击时未读快照或服务端成功回包，不取刷新后的 list_unread_total。
失败结果 失败后恢复提示条可点击状态 提示条恢复到可点击状态；若当前列表已回弹至静止态，则直接隐藏提示条，并 toast 提示 `一键已读失败，请稍后重试`。

对话气泡 Badge 字段

字段名称 交互 说明
展示位置 昵称右侧展示 Badge 位于发送者昵称右侧，与消息时间、消息正文分层展示。
普通用户等级 展示 `Lv. 1-51` 等级头盔 实际样式按等级资源映射。
群主标签 群主角色显示 `群主` 角色为群主时展示 `群主` 标签。
群管标签 后台指定群管显示 `群管` 角色为后台指定群管时展示 `群管` 标签。
主播标签 后台指定主播显示 `主播` 角色为后台指定主播账号时展示 `主播` 标签。
互斥规则 多角色时只输出一个 Badge 同一发送者同时存在多角色时，仅展示优先级最高的一个 Badge，顺序为：群主、群管、主播、用户等级降序。
昵称截断 仅截断昵称，不截断 Badge 当 `昵称 + Badge` 超出单行宽度时，仅截断昵称并补 `...`，Badge 不截断。
4. 聊天室角色Badge栏位
角色名称 Badge示意 说明
用户
用户等级截图示意
改用截图示意展示用户等级 Badge。实际规则为展示 `Lv. 1-51` 等级头盔；前端按 user_level 映射对应等级资源。
群主
群主标签示意
角色为群主时展示 `群主` 标签；展示后不再叠加普通用户等级头盔。
群管
群管标签示意
角色为后台指定群管时展示 `群管` 标签；展示后不再叠加普通用户等级头盔。
主播
主播标签示意
角色为后台指定主播账号时展示 `主播` 标签；若同时存在其他角色，则按既定优先级判断是否展示。
5. 权限规则 1. `一键已读` 仅对当前登录用户本人可用，不影响其他成员的未读状态。
2. `一键已读` 仅作用当前 `訊息` 列表，不作用 `聯絡`、`群組` 页签的独立未读。
3. 当前用户无 `訊息` 列表访问权限、账号离线或消息能力关闭时，不展示 `一键已读` 提示条。
4. 聊天室内所有仍在群成员均可查看发送者 Badge。
5. 群主、群管、主播 Badge 由服务端角色映射返回，前端不自行推断。
6. 同一时刻仅允许一个 `一键已读` 请求进行中；进行中状态下重复点击 `一键已读` 不再次发起请求。
7. 仅允许在下拉展开区停留期间触发 `一键已读`；列表已回弹至静止态时不可点击该能力。
8. `X` 关闭仅影响当前设备当前次下拉提示条展示，不改变未读数据，也不影响其他终端或下一次重新下拉时的展示资格。
6. 同步 / 异步更新规则 1. 同步更新范围：`一键已读` 成功后，同步刷新 `訊息` 列表各会话未读红点、提示条文案/显隐、底部聊天角标。
2. 异步更新范围：其他终端或 websocket 新未读回写进入时，重新计算 list_unread_total；若仍大于 `0`，仅在用户下一次下拉达到阈值时展示最新总数。
3. 版本比较：前端以 list_read_sync_version 做幂等判断，仅接收大于等于当前本地版本的已读回包。
4. Badge 更新：群主、群管、主播角色变化后，仅影响新拉取消息与当前已渲染消息刷新结果，不回改静态截图资源。
5. 列表手势冲突：下拉位移未达到阈值时，仅保留原有下拉回弹表现，不展示半露出的提示条。
6. 关闭同步：点击 `X` 后，仅本次下拉会话内隐藏提示条；若用户未松手继续停留在下拉态，也不重新露出。
7. 成功反馈：成功 toast 与顶部提示条状态同步更新；提示条先收起，再展示底部成功 toast。
8. 角色优先级：同一消息同时带多个角色时，按 `群主 > 群管 > 主播 > 用户等级Lv` 选择单一 Badge 输出。
7. 异常场景 1. 当前列表总未读数为 `0`：不展示 `一键已读` 提示条。
2. 当前列表总未读数大于 `999`：提示条仍展示实际未读总数，例如 `2797`，不使用 `999+` 截断。
3. 点击 `一键已读` 时网络超时：toast 提示 `一键已读失败，请稍后重试`，提示条恢复可点击。
4. 点击过程中有新未读进入：旧请求成功后重新拉取 list_unread_total；若仍大于 `0`，提示条不立即常驻展示，仅在下一次下拉达到阈值时露出最新总数。
5. 下拉位移不足阈值：不展示 `一键已读` 提示条，仅保留原有列表回弹效果。
6. 用户松手后列表立即回弹至静止态：若当前未发起 `一键已读` 请求，则提示条直接隐藏。
7. 提示条展示期间用户反向上滑：提示条随列表退出下拉展开区并隐藏，不发起已读请求。
8. 点击 `X` 后当前次下拉仍持续停留：提示条保持关闭，不重新自动露出；需松手回弹后重新下拉才可再次展示。
9. 成功 toast 期间用户继续滚动列表：toast 保持 2 秒后自动消失，不阻断列表滚动操作。
10. 成功 toast 展示期间又有新未读进入：toast 不回滚为失败态；2 秒结束后按最新未读状态等待用户下一次下拉再露出提示条。
11. 读取不到用户等级Badge：仅展示用户昵称。
12. 群主、群管、主播角色数据缺失：不展示对应角色标签，仅展示用户昵称。
13. 同一发送者同时命中多角色：仅展示优先级最高的一个 Badge，不叠加多枚标签，顺序为：群主、群管、主播、用户等级降序。

8. 建议新增字段

模块 建议新增字段 说明
列表一键已读 list_unread_total / list_read_sync_version / has_list_unread / read_all_request_id / read_all_loading / read_all_success_count / pull_down_offset / read_all_exposed / read_all_dismissed / read_all_success_toast_text / read_all_success_toast_visible 用于控制列表页 `一键已读` 提示条显隐、下拉阈值触发、`X` 关闭状态、请求进行中态、实际未读总数展示、成功 toast 计数文案与已读回包幂等刷新。
聊天室角色Badge sender_role_type / sender_role_priority / user_level / user_level_badge / role_badge_text / role_badge_style 用于根据用户等级与后台角色映射输出最终单一 Badge，并控制对应样式资源。
会话行状态 conversation_unread_count / conversation_read_at / conversation_role_snapshot 用于一键已读后的列表逐行刷新，以及消息列表中昵称旁 Badge 的快照展示。