好友是 IM 私聊的前提：只有互为好友（且未被对方拉黑），才能给对方发私聊消息。好友模块由 yudao-module-im 后端模块的 friend 包实现，用户侧前端在 @/views/im/home 的「通讯录」页。

本文涉及好友关系表 im_friend、好友申请表 im_friend_request 两张表，二者都通过 user_id 关联到系统用户（AdminUser），并由「申请记录 → 同意后写入好友关系」串起：

• 好友关系：双向的好友绑定。互为好友会存 两条对称记录（A→B、B→A），备注、置顶、免打扰、拉黑等都做成单边设置。
• 好友申请：好友的「申请 — 验证」流程，一次申请一条记录，记录申请理由、处理结果与处理时间；接收方同意后，才把关系双向写入 im_friend。

1. 好友关系

好友，由 ImFriendController 提供接口。

好友关系是「单边两条」的

A 和 B 互为好友时，im_friend 存 两条 记录（user_id=A, friend_user_id=B 和 user_id=B, friend_user_id=A）。这样备注、免打扰、置顶、拉黑都做成 单边属性——我给你设的备注只有我看得到，我删了你、你那条不受影响。

1.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `im_friend` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `user_id` bigint NOT NULL COMMENT '用户编号',
  `friend_user_id` bigint NOT NULL COMMENT '好友用户编号',

  `display_name` varchar(64) DEFAULT '' COMMENT '好友备注（仅自己可见）',
  `add_source` tinyint DEFAULT NULL COMMENT '添加来源',
  `add_time` datetime DEFAULT NULL COMMENT '添加好友时间',

  `silent` bit(1) DEFAULT b'0' COMMENT '是否免打扰',
  `pinned` bit(1) DEFAULT b'0' COMMENT '是否置顶联系人',
  `blocked` bit(1) DEFAULT b'0' COMMENT '是否拉黑',

  `status` tinyint NOT NULL DEFAULT '0' COMMENT '好友状态（0=正常，1=已删除）',
  `delete_time` datetime DEFAULT NULL COMMENT '删除好友时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_im_friend_user_friend` (`user_id`, `friend_user_id`)
) ENGINE=InnoDB COMMENT='IM 好友关系表';

① user_id、friend_user_id 关联好友双方的用户编号（即 AdminUser）。一条记录表示 user_id 单边视角下的好友 friend_user_id，唯一键 (user_id, friend_user_id) 保证不重复。

② display_name、add_source、add_time 是 单边属性：display_name 好友备注，仅自己可见；add_source 添加来源，枚举 ImFriendAddSourceEnum（1=搜索，2=群聊，3=扫码，4=名片，当前主要用搜索 / 群聊两种入口）；同意好友申请时，备注只写入发起方那条、来源双向写入。

③ silent、pinned、blocked 是三个单边开关：silent 免打扰，pinned 置顶联系人（影响通讯录与会话排序），blocked 拉黑——拉黑必须先是好友，单边屏蔽对方发来的私聊消息，对方无感知。

④ status 好友状态（CommonStatusEnum，0=正常，1=已删除），delete_time 删除时间。删除好友是单边软删：把自己这条置为「已删除」并记录 delete_time，对方那条不动，所以对方通讯录里依然有你。

发消息前如何判定好友关系

发私聊消息前，会用 ImFriendService 的 getFriendState 方法一次性判定双方关系，结果是枚举 ImFriendStateEnum（0=非好友 / 已删除，1=好友，2=好友但已被对方拉黑）。该结果带 Redis 缓存，是私聊发送链路上的热点判断，详见 《消息》。

1.2 通讯录与好友资料

对应 [IM 即时通讯 -> 聊天] 全屏聊天工作台的「通讯录」页，对应 yudao-ui-admin-vue3 项目的 @/views/im/home/pages/contact 目录。左侧分「新的朋友」「群聊」「好友」三个区块，右侧展示选中项的详情。

好友列表（FriendList.vue）按拼音首字母分桶（A~Z、#）展示，搜索框支持按昵称、备注、全拼、首字母过滤（如「老张」可用 lz、zhang、老 命中）。

点选某个好友后，右侧是好友资料卡（UserInfo.vue），展示头像、昵称、备注、来源、添加时间，底部提供「发消息 / 语音通话 / 视频通话」入口（语音 / 视频详见 《通话》）。资料卡上可完成大部分单边操作：

• 备注：资料卡「备注」一行点击即可行内编辑，对应 ImFriendController 的 updateFriend 方法。
• 免打扰 / 置顶：在会话列表的会话菜单中切换，同样调用 ImFriendController 的 updateFriend 方法，对应 im_friend 的 silent / pinned。
• 拉黑 / 移出黑名单：资料卡右上「…」菜单中的「加入黑名单 / 移出黑名单」，对应 ImFriendController 的 blockFriend / unblockFriend 方法；拉黑必须先是好友。
• 删除联系人：「…」菜单中的「删除联系人」，弹窗可勾选「同时清空聊天记录」，对应 ImFriendController 的 deleteFriend 方法（单边软删，对方无感知）。

以上单边操作完成后，都会通过 WebSocket 推送同步到本人的其它登录端，保证多端一致；推送链路详见 《WebSocket 实时推送与离线消息》。

2. 好友申请

好友申请，由 ImFriendRequestController 提供接口。它记录一次「申请 — 验证」的完整过程：发起方提交申请，接收方同意或拒绝。

2.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `im_friend_request` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `from_user_id` bigint NOT NULL COMMENT '发起方用户编号',
  `to_user_id` bigint NOT NULL COMMENT '接收方用户编号',

  `apply_content` varchar(255) DEFAULT NULL COMMENT '申请理由',
  `display_name` varchar(64) DEFAULT NULL COMMENT '发起方对接收方的备注',
  `add_source` tinyint DEFAULT NULL COMMENT '添加来源',

  `handle_result` tinyint NOT NULL DEFAULT '0' COMMENT '处理结果（0=未处理，1=同意，2=拒绝）',
  `handle_content` varchar(255) DEFAULT NULL COMMENT '处理理由（拒绝时可选填）',
  `handle_time` datetime DEFAULT NULL COMMENT '处理时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_im_friend_request` (`from_user_id`, `to_user_id`, `tenant_id`)
) ENGINE=InnoDB COMMENT='IM 好友申请记录表';

① from_user_id、to_user_id 为发起方 / 接收方。唯一键 (from_user_id, to_user_id)：同一对「申请人 → 接收人」只保留一条记录，重复申请会覆盖原记录的申请内容并重置为未处理，而不是新增一行。

② 申请发起阶段由发起方填写：apply_content 申请理由；display_name 发起方给接收方设的备注，同意后写入发起方那条 im_friend.display_name，接收方那条不写；add_source 添加来源（同 ImFriendAddSourceEnum）。

③ 申请处理阶段由接收方填写：handle_result 处理结果，接收方同意 / 拒绝时回写；handle_content 拒绝理由，可选；handle_time 处理时间。

handle_result 的状态流转：

处理结果	含义	可执行操作
0 未处理	等待接收方验证	同意（agreeFriendRequest）、拒绝（refuseFriendRequest）
1 同意	已成为好友	—
2 拒绝	已拒绝	—

完整流程（方法均在 ImFriendRequestServiceImpl）：

1. 申请（applyFriend）：发起方提交申请，落库 im_friend_request（handle_result=未处理），并 WebSocket 推送给接收方多端。其中有三种特殊情况：
   • 已是好友 / 已被对方拉黑：直接报错，不落申请。
   • 单向好友（自己曾删除对方、但对方仍把自己当好友）：静默恢复自己这条好友关系（silentReAddFriend），不再走审批、不打扰对方。
   • 自动通过：配置项 yudao.im.friend.auto-accept（默认 false 关闭）开启后，申请落库（事务提交）后由系统自动调用一次 agreeFriendRequest 同意，便于演示与压测环境快速建立好友关系。
2. 同意（agreeFriendRequest）：接收方同意，乐观锁将 handle_result 置为同意，双向建立好友关系（becomeFriends：发起方那条带备注 + 来源，接收方那条仅来源），并发送一条「你们已经是好友了」的系统消息气泡，同时推送给发起方多端。
3. 拒绝（refuseFriendRequest）：接收方拒绝，handle_result 置为拒绝，可附拒绝理由，推送给发起方多端。

2.2 添加与处理申请

添加好友：在通讯录点击「添加好友」打开 FriendAddDialog.vue，输入昵称回车搜索用户，选中后填写申请理由（默认带「我是 XXX」）和备注并提交，来源记为「搜索」；若从群成员资料卡进入，则来源为「群聊」。

处理申请：左侧「新的朋友」区块（FriendRequestList.vue）展示与自己相关的申请，未处理数量以红点提示；点选进入申请详情（FriendRequestDetail.vue）：

• 收到的未处理申请：可「同意」或「拒绝」，拒绝时可在弹窗填写理由（不填则不告知对方原因）。
• 自己发出的未处理申请：显示「等待对方验证」，不可操作。
• 已同意的申请：详情直接展示为好友资料卡。

3. 运营侧

运营侧在 [IM 即时通讯 -> 私聊管理] 下提供「好友列表」「好友申请」两个只读查询入口，对应 @/views/im/manager/friend 目录，由 ImFriendManagerController、ImFriendRequestManagerController 提供接口：

• 好友列表：分页查看全量好友关系，可按用户、好友筛选，列表展示双方昵称、来源、状态、添加时间等。
• 好友申请：分页查看全部好友申请记录，含发起方 / 接收方、申请理由、处理结果与处理时间。

运营侧仅用于查询排查，不提供新增 / 修改 / 删除；好友关系的建立与解除都由用户侧完成。