zhangshun/docs/chat-display-name-frontend-handover-20261028.md

沟通姓名与头像同步：前端增量对接

日期：2026-10-28。对象：求职者端/企业端前端联调人员。本次为本地后端改动，尚未提交、推送或发布；线上 Jenkins #107 不包含本次修复。 本文沿用已确认的头像/Logo 对接结构，作为原文档的增量，不改写历史验收状态。

1. 展示规则

• 对方为求职者：contactName 优先使用当前个人资料 realName；缺失、空串或纯空白时回退账号 nickname，再回退“求职者”。姓名/昵称首尾空白去除。
• 对方为企业：contactName 继续使用公司名称，avatarUrl 继续使用公司 Logo，不替换为 HR 的个人头像或姓名。
• DIRECT 和 TALENT_INVITATION 的会话摘要均按上述非匿名规则展示姓名和头像。
• 修改资料姓名不强行改写账号 nickname；修改头像不影响公司 Logo。
• 没有新增手机号、邮箱、简历正文、用户 ID 等展示字段。原消息 senderScope、已有内部 ID 隐藏和简历权限规则保持不变。

2. 接口与权限

API 路径、认证和响应字段不变，无新增迁移或依赖：

接口	用途
PUT /api/v1/profile/me	保存资料姓名 realName；已有在线简历的账号继续遵循 revision 规则，不能为了改名绕过并发保护
现有在线简历保存接口	保存 basicInfo.realName，并同步到资料；沿用既有完整保存及 revision 契约
GET /api/v1/conversations	返回最新会话摘要，前端使用 contactName、avatarUrl
GET /api/v1/conversations/{id}	返回最新会话详情摘要，字段来源与列表一致
POST /api/v1/auth/me/avatar	上传本人头像，沿用原上传协议，返回新的头像版本 URL
GET /api/v1/profile-images/{imageId}	读取头像，仍携带正常 access token；公司 Logo 的原公开规则不变

不新增让前端传 userId 查他人姓名的能力。非成员不能读取会话；邀约头像读取仍检查成员、拉黑、撤回、企业认证及已有企业接受/匹配沟通授权。移除展示匿名不等于关闭这些门禁。

图片/文件附件继续只允许 DIRECT 会话。不能通过本次头像调整扩大 TALENT_INVITATION 的附件权限。

3. 缓存更新与前端修改点

1. 修改姓名后，等待保存接口真正成功；409 冲突、网络错误或服务端失败不能假装已保存。保存成功后刷新个人资料、在线简历的相应缓存。
2. 会话列表和详情统一使用后端 contactName，不再用历史路由参数、第一次登录的 nickname、硬编码名字或旧消息快照长期覆盖。
3. 企业端进入/回到沟通页、打开会话详情时重新读取摘要，更新标题与头像。若已有统一轮询/刷新机制，应让它同步合并这两个字段。
4. 本次未新增“对方改名”WebSocket 事件。用户 A 改名后，不能只刷新 A 本机就声称企业 B 已刷新；B 应在上述刷新点重新拉取。要实现当前打开页面的即时更新，需前端接入既有刷新机制或另行设计事件。
5. 头像更换后使用后端最新版本 URL，并携带认证头；旧 URL 失效不能一直沿用。姓名变化不需要拼接虚假的头像缓存版本。
6. 切账号清理会话缓存；异步请求按账号/会话 ID 或请求代次保护，旧响应不能覆盖新账号、新会话的标题与头像。
7. 名称/头像加载失败保留明确错误或合理占位，不显示假名字，不从手机号推断姓名。

4. 联调验收

• 求职者修改 realName 后，企业重新 GET 列表、详情，contactName 均返回新值；再次修改也更新，原 nickname 不被强行覆盖。
• 无资料记录、null/空白 realName 时回退 nickname；两者均空白时为“求职者”。
• DIRECT/TALENT_INVITATION 摘要遵循同一显示规则；企业一侧仍显示公司名称和 Logo。
• 邀约会话的已授权成员可加载个人头像；匿名、非成员、拉黑后读取仍拒绝；企业未获沟通授权或投递撤回不因展示规则变化而获权。
• 点击同一个会话、返回列表、重新进入、切账号等场景，标题/列表名字/头像不互相覆盖。
• 邀约附件仍不能通过 DIRECT 附件接口读取或发送；不新增个人敏感字段。

请前端回传实际请求/响应（去除 Token 和个人信息）、姓名保存后的两端录屏/截图、缓存刷新方式、类型检查和测试结果。后端定向测试、真实 MySQL、同次 JAR 黑盒、前端实机与线上发布应分别登记，不能把之前 #107 的通知发布验收当作本次姓名修复也已上线。