diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendController.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendController.java
index 7f885df..5c1b6b3 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendController.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendController.java
@@ -57,17 +57,8 @@ public class ImFriendController {
         return success(buildFriendRespVO(friend));
     }
 
-    @PostMapping("/add")
-    @Operation(summary = "添加好友（双向建立关系）")
-    @Parameter(name = "friendUserId", description = "好友的用户编号", required = true, example = "2048")
-    public CommonResult<Boolean> addFriend(
-            @RequestParam("friendUserId") @NotNull(message = "好友用户编号不能为空") Long friendUserId) {
-        friendService.addFriend(getLoginUserId(), friendUserId);
-        return success(true);
-    }
-
     @DeleteMapping("/delete")
-    @Operation(summary = "删除好友（双向软删除）")
+    @Operation(summary = "删除好友（单向软删除）")
     @Parameter(name = "friendUserId", description = "好友的用户编号", required = true, example = "2048")
     public CommonResult<Boolean> deleteFriend(
             @RequestParam("friendUserId") @NotNull(message = "好友用户编号不能为空") Long friendUserId) {
@@ -76,12 +67,30 @@ public class ImFriendController {
     }
 
     @PutMapping("/update")
-    @Operation(summary = "更新好友信息")
+    @Operation(summary = "更新好友单边属性（备注 / 免打扰 / 联系人置顶）")
     public CommonResult<Boolean> updateFriend(@Valid @RequestBody ImFriendUpdateReqVO reqVO) {
         friendService.updateFriend(getLoginUserId(), reqVO);
         return success(true);
     }
 
+    @PutMapping("/block")
+    @Operation(summary = "拉黑好友（必须先是好友；单边屏蔽对方私聊消息）")
+    @Parameter(name = "friendUserId", description = "好友的用户编号", required = true, example = "2048")
+    public CommonResult<Boolean> blockFriend(
+            @RequestParam("friendUserId") @NotNull(message = "好友用户编号不能为空") Long friendUserId) {
+        friendService.blockFriend(getLoginUserId(), friendUserId);
+        return success(true);
+    }
+
+    @PutMapping("/unblock")
+    @Operation(summary = "移出黑名单")
+    @Parameter(name = "friendUserId", description = "好友的用户编号", required = true, example = "2048")
+    public CommonResult<Boolean> unblockFriend(
+            @RequestParam("friendUserId") @NotNull(message = "好友用户编号不能为空") Long friendUserId) {
+        friendService.unblockFriend(getLoginUserId(), friendUserId);
+        return success(true);
+    }
+
     // ========== 私有方法：VO 组装 ==========
 
     private List<ImFriendRespVO> buildFriendRespVOList(Collection<ImFriendDO> friends) {
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendRequestController.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendRequestController.java
new file mode 100644
index 0000000..9c74946
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendRequestController.java
@@ -0,0 +1,102 @@
+package cn.iocoder.yudao.module.im.controller.admin.friend;
+
+import cn.hutool.core.collection.CollUtil;
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.framework.common.util.collection.MapUtils;
+import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
+import cn.iocoder.yudao.module.im.controller.admin.friend.vo.request.ImFriendRequestApplyReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.friend.vo.request.ImFriendRequestRespVO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
+import cn.iocoder.yudao.module.im.service.friend.ImFriendRequestService;
+import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
+import cn.iocoder.yudao.module.system.api.user.dto.AdminUserRespDTO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Stream;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.convertList;
+import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.convertSetByFlatMap;
+import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.getLoginUserId;
+
+/**
+ * IM 好友申请记录 Controller
+ *
+ * @author 芋道源码
+ */
+@Tag(name = "管理后台 - IM 好友申请")
+@RestController
+@RequestMapping("/im/friend-request")
+@Validated
+public class ImFriendRequestController {
+
+    @Resource
+    private ImFriendRequestService friendRequestService;
+
+    @Resource
+    private AdminUserApi adminUserApi;
+
+    @PostMapping("/apply")
+    @Operation(summary = "发起好友申请")
+    public CommonResult<Long> applyFriend(@Valid @RequestBody ImFriendRequestApplyReqVO reqVO) {
+        ImFriendRequestDO request = friendRequestService.applyFriend(getLoginUserId(), reqVO);
+        return success(request != null ? request.getId() : null);
+    }
+
+    @PutMapping("/agree")
+    @Operation(summary = "同意好友申请")
+    @Parameter(name = "id", description = "申请编号", required = true, example = "1024")
+    public CommonResult<Boolean> agreeFriendRequest(
+            @RequestParam("id") @NotNull(message = "申请编号不能为空") Long id) {
+        friendRequestService.agreeFriendRequest(getLoginUserId(), id);
+        return success(true);
+    }
+
+    @PutMapping("/refuse")
+    @Operation(summary = "拒绝好友申请")
+    public CommonResult<Boolean> refuseFriendRequest(
+            @RequestParam("id") @NotNull(message = "申请编号不能为空") Long id,
+            @RequestParam(value = "handleContent", required = false)
+            @Size(max = 255, message = "处理理由最多 255 个字符") String handleContent) {
+        friendRequestService.refuseFriendRequest(getLoginUserId(), id, handleContent);
+        return success(true);
+    }
+
+    @GetMapping("/list")
+    @Operation(summary = "查询「我相关」的好友申请列表（含我发起的、别人加我的）")
+    public CommonResult<List<ImFriendRequestRespVO>> getMyFriendRequestList() {
+        List<ImFriendRequestDO> list = friendRequestService.getMyFriendRequestList(getLoginUserId());
+        return success(buildList(list));
+    }
+
+    // ========== 私有方法：VO 组装 ==========
+
+    private List<ImFriendRequestRespVO> buildList(List<ImFriendRequestDO> list) {
+        if (CollUtil.isEmpty(list)) {
+            return Collections.emptyList();
+        }
+        Set<Long> userIds = convertSetByFlatMap(list, r -> Stream.of(r.getFromUserId(), r.getToUserId()));
+        Map<Long, AdminUserRespDTO> userMap = adminUserApi.getUserMap(userIds);
+        return convertList(list, r -> {
+            ImFriendRequestRespVO vo = BeanUtils.toBean(r, ImFriendRequestRespVO.class);
+            MapUtils.findAndThen(userMap, r.getFromUserId(), user ->
+                    vo.setFromNickname(user.getNickname()).setFromAvatar(user.getAvatar()));
+            MapUtils.findAndThen(userMap, r.getToUserId(), user ->
+                    vo.setToNickname(user.getNickname()).setToAvatar(user.getAvatar()));
+            return vo;
+        });
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendRespVO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendRespVO.java
index b3ff24c..af509b8 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendRespVO.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendRespVO.java
@@ -29,6 +29,15 @@ public class ImFriendRespVO {
     @Schema(description = "好友展示备注的拼音（小写无空格）", example = "laozhang")
     private String displayNamePinyin;
 
+    @Schema(description = "添加来源", example = "1")
+    private Integer addSource; // 参见 ImFriendAddSourceEnum 枚举
+
+    @Schema(description = "是否置顶联系人", example = "false")
+    private Boolean pinned;
+
+    @Schema(description = "是否拉黑（仅自己可见）", example = "false")
+    private Boolean blocked;
+
     @Schema(description = "好友状态", example = "0")
     private Integer status;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendUpdateReqVO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendUpdateReqVO.java
index 3aecfa1..f48266b 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendUpdateReqVO.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendUpdateReqVO.java
@@ -20,4 +20,7 @@ public class ImFriendUpdateReqVO {
     @Size(max = 16, message = "好友备注最多 16 个字符")
     private String displayName;
 
+    @Schema(description = "是否置顶联系人；不传表示不修改", example = "true")
+    private Boolean pinned;
+
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestApplyReqVO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestApplyReqVO.java
new file mode 100644
index 0000000..fea58c1
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestApplyReqVO.java
@@ -0,0 +1,35 @@
+package cn.iocoder.yudao.module.im.controller.admin.friend.vo.request;
+
+import cn.iocoder.yudao.framework.common.validation.InEnum;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendAddSourceEnum;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * IM 好友申请 - 发起 Request VO
+ *
+ * @author 芋道源码
+ */
+@Schema(description = "管理后台 - IM 好友申请发起 Request VO")
+@Data
+public class ImFriendRequestApplyReqVO {
+
+    @Schema(description = "接收方用户编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "2048")
+    @NotNull(message = "接收方用户编号不能为空")
+    private Long toUserId;
+
+    @Schema(description = "申请理由", example = "我是芋艿（一种食材）")
+    @Size(max = 255, message = "申请理由最多 255 个字符")
+    private String applyContent;
+
+    @Schema(description = "对接收方的备注（仅自己可见）", example = "老张")
+    @Size(max = 16, message = "好友备注最多 16 个字符")
+    private String displayName;
+
+    @Schema(description = "添加来源", example = "1")
+    @InEnum(ImFriendAddSourceEnum.class)
+    private Integer addSource;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestRespVO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestRespVO.java
new file mode 100644
index 0000000..6f8f93d
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/request/ImFriendRequestRespVO.java
@@ -0,0 +1,58 @@
+package cn.iocoder.yudao.module.im.controller.admin.friend.vo.request;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * IM 好友申请 Response VO
+ *
+ * @author 芋道源码
+ */
+@Schema(description = "管理后台 - IM 好友申请 Response VO")
+@Data
+public class ImFriendRequestRespVO {
+
+    @Schema(description = "申请编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "1024")
+    private Long id;
+
+    @Schema(description = "发起方用户编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "100")
+    private Long fromUserId;
+
+    @Schema(description = "接收方用户编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "200")
+    private Long toUserId;
+
+    @Schema(description = "处理结果", requiredMode = Schema.RequiredMode.REQUIRED, example = "0")
+    private Integer handleResult; // 参见 ImFriendRequestHandleResultEnum 枚举
+
+    @Schema(description = "申请理由", example = "我是芋艿（一种食材）")
+    private String applyContent;
+
+    @Schema(description = "处理理由（接收方拒绝时可选填）", example = "暂不通过")
+    private String handleContent;
+
+    @Schema(description = "添加来源", example = "1")
+    private Integer addSource; // 参见 ImFriendAddSourceEnum 枚举
+
+    @Schema(description = "处理时间")
+    private LocalDateTime handleTime;
+
+    @Schema(description = "申请创建时间")
+    private LocalDateTime createTime;
+
+    // ========== 下面是聚合字段，方便前端显示 ==========
+
+    @Schema(description = "发起方昵称（实时聚合自 AdminUser）", example = "芋道")
+    private String fromNickname;
+
+    @Schema(description = "发起方头像（实时聚合自 AdminUser）")
+    private String fromAvatar;
+
+    @Schema(description = "接收方昵称（实时聚合自 AdminUser）", example = "老张")
+    private String toNickname;
+
+    @Schema(description = "接收方头像（实时聚合自 AdminUser）")
+    private String toAvatar;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendDO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendDO.java
index 55dcc15..8832ebe 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendDO.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendDO.java
@@ -16,6 +16,8 @@ import java.time.LocalDateTime;
  * - 双向关系：A-B 互为好友会存 2 条记录（userId=A, friendUserId=B 和 userId=B, friendUserId=A）
  * - 状态管理：{@link #status} 使用 {@link CommonStatusEnum}，ENABLE=正常，DISABLE=已删除
  * - 免打扰：{@link #muted} 控制是否屏蔽来自该好友的通知
+ * - 联系人置顶：{@link #pinned} 单边，影响联系人 / 会话排序
+ * - 黑名单：{@link #blocked} 弱关联 friend，单边屏蔽对方消息（必须先是好友）
  *
  * @author 芋道源码
  */
@@ -55,6 +57,20 @@ public class ImFriendDO extends BaseDO {
      */
     private String displayName;
     /**
+     * 添加来源
+     * <p>
+     * 枚举 {@link cn.iocoder.yudao.module.im.enums.friend.ImFriendAddSourceEnum}
+     */
+    private Integer addSource;
+    /**
+     * 是否置顶联系人
+     */
+    private Boolean pinned;
+    /**
+     * 是否拉黑（弱关联 friend，单边屏蔽对方私聊消息）
+     */
+    private Boolean blocked;
+    /**
      * 好友状态
      * <p>
      * 枚举 {@link CommonStatusEnum}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendRequestDO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendRequestDO.java
new file mode 100644
index 0000000..ec30987
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/friend/ImFriendRequestDO.java
@@ -0,0 +1,85 @@
+package cn.iocoder.yudao.module.im.dal.dataobject.friend;
+
+import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendAddSourceEnum;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendRequestHandleResultEnum;
+import com.baomidou.mybatisplus.annotation.KeySequence;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.*;
+
+import java.time.LocalDateTime;
+
+/**
+ * IM 好友申请记录 DO
+ * <p>
+ * 配合「申请 - 审批」流程：
+ * - 发起方调 apply 接口落库（handleResult=UNHANDLED）
+ * - 接收方调 agree / refuse 处理（更新 handleResult / handleTime / handleContent）
+ * - 申请通过后，displayName / addSource 同步写入 {@link ImFriendDO}
+ *
+ * @author 芋道源码
+ */
+@TableName("im_friend_request")
+@KeySequence("im_friend_request_seq")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ImFriendRequestDO extends BaseDO {
+
+    /**
+     * 编号
+     */
+    @TableId
+    private Long id;
+    /**
+     * 发起方用户编号
+     * <p>
+     * 关联 AdminUserDO 的 id 字段
+     */
+    private Long fromUserId;
+    /**
+     * 接收方用户编号
+     * <p>
+     * 关联 AdminUserDO 的 id 字段
+     */
+    private Long toUserId;
+
+    // ========== 申请发起阶段（发起方填写） ==========
+    /**
+     * 申请理由
+     */
+    private String applyContent;
+    /**
+     * 发起方对接收方的备注
+     * <p>
+     * 同意后写入 A 侧 {@link ImFriendDO#getDisplayName()}；B 侧不动
+     */
+    private String displayName;
+    /**
+     * 添加来源
+     * <p>
+     * 枚举 {@link ImFriendAddSourceEnum}
+     */
+    private Integer addSource;
+
+    // ========== 申请处理阶段（接收方填写） ==========
+    /**
+     * 处理结果
+     * <p>
+     * 枚举 {@link ImFriendRequestHandleResultEnum}
+     */
+    private Integer handleResult;
+    /**
+     * 处理理由（接收方拒绝时可选填）
+     */
+    private String handleContent;
+    /**
+     * 处理时间
+     */
+    private LocalDateTime handleTime;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/friend/ImFriendRequestMapper.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/friend/ImFriendRequestMapper.java
new file mode 100644
index 0000000..7e15549
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/friend/ImFriendRequestMapper.java
@@ -0,0 +1,36 @@
+package cn.iocoder.yudao.module.im.dal.mysql.friend;
+
+import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
+import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
+import org.apache.ibatis.annotations.Mapper;
+
+import java.util.List;
+
+/**
+ * IM 好友申请记录 Mapper
+ *
+ * @author 芋道源码
+ */
+@Mapper
+public interface ImFriendRequestMapper extends BaseMapperX<ImFriendRequestDO> {
+
+    default ImFriendRequestDO selectLatestByFromUserIdAndToUserId(Long fromUserId, Long toUserId) {
+        return selectOne(new LambdaQueryWrapperX<ImFriendRequestDO>()
+                .eq(ImFriendRequestDO::getFromUserId, fromUserId)
+                .eq(ImFriendRequestDO::getToUserId, toUserId)
+                .orderByDesc(ImFriendRequestDO::getId)
+                .last("LIMIT 1"));
+    }
+
+    default List<ImFriendRequestDO> selectMyList(Long userId, int limit) {
+        // 先放扩展过滤再放双向 OR；否则 .and() 返回 LambdaQueryWrapper 基类，丢失 eqIfPresent 等扩展方法
+        LambdaQueryWrapperX<ImFriendRequestDO> wrapper = new LambdaQueryWrapperX<>();
+        wrapper.and(w -> w.eq(ImFriendRequestDO::getFromUserId, userId)
+                        .or().eq(ImFriendRequestDO::getToUserId, userId))
+                .orderByDesc(ImFriendRequestDO::getId)
+                .last("LIMIT " + limit);
+        return selectList(wrapper);
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/redis/RedisKeyConstants.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/redis/RedisKeyConstants.java
index d2d7149..a11a182 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/redis/RedisKeyConstants.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/redis/RedisKeyConstants.java
@@ -16,12 +16,12 @@ public interface RedisKeyConstants {
     String GROUP_MESSAGE_READ = "im:group:message:read:%s";
 
     /**
-     * 好友关系是否存在的缓存
+     * 好友关系状态缓存（合并「是否好友」+「是否拉黑」两态）
      * <p>
-     * KEY 格式：friend:{userId}_{friendUserId}
-     * VALUE 数据类型：Boolean
+     * KEY 格式：friend_state:{userId}_{friendUserId}
+     * VALUE 数据类型：{@link cn.iocoder.yudao.module.im.enums.friend.ImFriendStateEnum}
      */
-    String FRIEND = "friend";
+    String FRIEND_STATE = "friend_state";
 
     /**
      * 群信息缓存
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/ErrorCodeConstants.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/ErrorCodeConstants.java
index 3b3ef1e..1ccb953 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/ErrorCodeConstants.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/ErrorCodeConstants.java
@@ -45,6 +45,14 @@ public interface ErrorCodeConstants {
     // ========== 好友 (1-040-600-000) ==========
     ErrorCode FRIEND_NOT_FRIEND = new ErrorCode(1_040_600_001, "对方不是您的好友");
     ErrorCode FRIEND_ADD_SELF = new ErrorCode(1_040_600_002, "不允许添加自己为好友");
+    ErrorCode FRIEND_NOT_BLOCKED = new ErrorCode(1_040_600_003, "对方未在黑名单中");
+    ErrorCode FRIEND_BLOCKED_BY_PEER = new ErrorCode(1_040_600_004, "您已被对方拉入黑名单，无法发送消息");
+
+    // ========== 好友申请 (1-040-610-000) ==========
+    ErrorCode FRIEND_REQUEST_NOT_EXISTS = new ErrorCode(1_040_610_001, "好友申请不存在");
+    ErrorCode FRIEND_REQUEST_HANDLED = new ErrorCode(1_040_610_002, "好友申请已处理");
+    ErrorCode FRIEND_REQUEST_NOT_TO_ME = new ErrorCode(1_040_610_003, "不能处理别人的好友申请");
+    ErrorCode FRIEND_REQUEST_TARGET_INVALID = new ErrorCode(1_040_610_004, "好友申请的对方不存在或已禁用");
 
     // ========== 敏感词 (1-040-700-000) ==========
     ErrorCode SENSITIVE_WORD_NOT_EXISTS = new ErrorCode(1_040_700_000, "敏感词不存在");
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendAddSourceEnum.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendAddSourceEnum.java
new file mode 100644
index 0000000..9295b6d
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendAddSourceEnum.java
@@ -0,0 +1,42 @@
+package cn.iocoder.yudao.module.im.enums.friend;
+
+import cn.iocoder.yudao.framework.common.core.ArrayValuable;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+import java.util.Arrays;
+
+/**
+ * IM 好友添加来源枚举
+ * <p>
+ * 由发起方调用 apply 接口时传入；同意后同步写入 im_friend.add_source（双向）
+ *
+ * @author 芋道源码
+ */
+@RequiredArgsConstructor
+@Getter
+public enum ImFriendAddSourceEnum implements ArrayValuable<Integer> {
+
+    // TODO DONE @AI：GROUP 提前到 source=2（先实现）；BUSINESS_CARD 简化为 CARD
+    SEARCH(1, "搜索"), // FriendAddDialog 搜索流程
+    GROUP(2, "群聊"), // TODO @AI：群成员主页加好友，待落 UI 入口
+    QR_CODE(3, "扫码"), // TODO @芋艿：后续实现扫码加好友
+    CARD(4, "名片"); // TODO @芋艿：后续实现通过名片加好友，类似微信的「扫一扫 - 名片」功能，或者「通讯录 - 推荐好友」功能
+
+    public static final Integer[] ARRAYS = Arrays.stream(values()).map(ImFriendAddSourceEnum::getSource).toArray(Integer[]::new);
+
+    /**
+     * 来源
+     */
+    private final Integer source;
+    /**
+     * 名字
+     */
+    private final String name;
+
+    @Override
+    public Integer[] array() {
+        return ARRAYS;
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendRequestHandleResultEnum.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendRequestHandleResultEnum.java
new file mode 100644
index 0000000..d5d2bf8
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendRequestHandleResultEnum.java
@@ -0,0 +1,46 @@
+package cn.iocoder.yudao.module.im.enums.friend;
+
+import cn.iocoder.yudao.framework.common.core.ArrayValuable;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * IM 好友申请处理结果枚举
+ *
+ * @author 芋道源码
+ */
+@RequiredArgsConstructor
+@Getter
+public enum ImFriendRequestHandleResultEnum implements ArrayValuable<Integer> {
+
+    UNHANDLED(0, "未处理"),
+    AGREED(1, "同意"),
+    REFUSED(2, "拒绝");
+
+    public static final Integer[] ARRAYS = Arrays.stream(values()).map(ImFriendRequestHandleResultEnum::getResult).toArray(Integer[]::new);
+
+    /**
+     * 结果
+     */
+    private final Integer result;
+    /**
+     * 名字
+     */
+    private final String name;
+
+    @Override
+    public Integer[] array() {
+        return ARRAYS;
+    }
+
+    /**
+     * 判断申请是否还未处理
+     */
+    public static boolean isUnhandled(Integer result) {
+        return Objects.equals(UNHANDLED.result, result);
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendStateEnum.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendStateEnum.java
new file mode 100644
index 0000000..7b274f9
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/friend/ImFriendStateEnum.java
@@ -0,0 +1,42 @@
+package cn.iocoder.yudao.module.im.enums.friend;
+
+import cn.iocoder.yudao.framework.common.core.ArrayValuable;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+import java.util.Arrays;
+
+/**
+ * IM 好友关系状态（合并「是否好友」+「是否拉黑」两态）
+ * <p>
+ * 用 state 而非 status：避免和 ImFriendDO 的 statue 物理字段（CommonStatusEnum：ENABLE / DISABLE）混淆。
+ * <p>
+ * 用于 ImFriendService.getFriendState 返回值与 FRIEND_STATE 缓存值：私聊发送热点路径下，sender 调缓存即可同时判定「能否发」和「是否屏蔽接收方」
+ *
+ * @author 芋道源码
+ */
+@RequiredArgsConstructor
+@Getter
+public enum ImFriendStateEnum implements ArrayValuable<Integer> {
+
+    NONE(0, "非好友 / 已删除"),
+    FRIEND(1, "好友"),
+    BLOCKED(2, "好友且已被对方拉黑");
+
+    public static final Integer[] ARRAYS = Arrays.stream(values()).map(ImFriendStateEnum::getState).toArray(Integer[]::new);
+
+    /**
+     * 状态值
+     */
+    private final Integer state;
+    /**
+     * 名字
+     */
+    private final String name;
+
+    @Override
+    public Integer[] array() {
+        return ARRAYS;
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/message/ImMessageTypeEnum.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/message/ImMessageTypeEnum.java
index cf2d52e..a863a27 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/message/ImMessageTypeEnum.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/message/ImMessageTypeEnum.java
@@ -33,10 +33,63 @@ public enum ImMessageTypeEnum implements ArrayValuable<Integer> {
     TIP_TIME(20, "时间分隔", false, false), // 暂无（前端本地生成）
     TIP_TEXT(21, "系统提示", true, false), // 对应 TextMessage 类
 
-    // ========== 好友变更 ==========
-    FRIEND_ADD(100, "好友添加", false, false), // 暂无对应类
-    FRIEND_DELETE(101, "好友删除", false, false), // 暂无对应类
-    FRIEND_UPDATE(102, "好友更新", false, false), // 暂无对应类（客户端收到后自行拉取）
+    // ========== 好友通知（1201-1210 直接复用 OpenIM 段位编号） ==========
+    /**
+     * 对应 OpenIM：FriendApplicationApprovedNotification 1201
+     * 对应自己的类：FriendRequestApprovedNotification
+     * 场景：B 同意 A 的好友申请，推给 A 多端
+     */
+    FRIEND_REQUEST_APPROVED(1201, "好友申请被同意", false, false),
+    /**
+     * 对应 OpenIM：FriendApplicationRejectedNotification 1202
+     * 对应自己的类：FriendRequestRejectedNotification
+     * 场景：B 拒绝 A 的好友申请，推给 A 多端
+     */
+    FRIEND_REQUEST_REJECTED(1202, "好友申请被拒绝", false, false),
+    /**
+     * 对应 OpenIM：FriendApplicationNotification 1203
+     * 对应自己的类：FriendRequestNotification
+     * 场景：A 申请加 B，推给 B 多端，前端落到「新的朋友」列表
+     */
+    FRIEND_APPLICATION(1203, "收到新的好友申请", false, false),
+    /**
+     * 对应 OpenIM：FriendAddedNotification 1204
+     * 对应自己的类：FriendAddNotification
+     * 场景：双方建立好友关系（同意申请 / 管理员导入），推给 A、B 双方多端
+     */
+    FRIEND_ADD(1204, "新增好友", false, false),
+    /**
+     * 对应 OpenIM：FriendDeletedNotification 1205
+     * 对应自己的类：FriendDeleteNotification
+     * 场景：A 删除 B，推给 A、B 双方多端
+     */
+    FRIEND_DELETE(1205, "好友被删除", false, false),
+    // 1206 对应 OpenIM FriendRemarkSetNotification；本系统并入 FRIEND_UPDATE(1210) 统一推送，单一字段变更不再独立通道
+    /**
+     * 对应 OpenIM：BlackAddedNotification 1207
+     * 对应自己的类：FriendBlockNotification
+     * 场景：A 拉黑 B，仅推 A 多端
+     */
+    FRIEND_BLOCK(1207, "加入黑名单", false, false),
+    /**
+     * 对应 OpenIM：BlackDeletedNotification 1208
+     * 对应自己的类：FriendUnblockNotification
+     * 场景：A 移出 B 的黑名单，仅推 A 多端
+     */
+    FRIEND_UNBLOCK(1208, "移出黑名单", false, false),
+    /**
+     * 对应 OpenIM：FriendInfoUpdatedNotification 1209
+     * 对应自己的类：FriendInfoUpdatedNotification
+     * 场景：B 改了昵称 / 头像后，推给 B 的所有好友
+     * TODO @AI：未实现；待 system 模块改昵称 / 头像时回调 IM 模块批量推此事件，前端 dispatcher 已就绪
+     */
+    FRIEND_INFO_UPDATED(1209, "好友资料变更", false, false),
+    /**
+     * 对应 OpenIM：FriendsInfoUpdateNotification 1210（窄化到 muted / pinned 单边属性）
+     * 对应自己的类：FriendUpdateNotification
+     * 场景：A 改了 muted / pinned 等单边属性，推 A 多端
+     */
+    FRIEND_UPDATE(1210, "好友信息批量更新", false, false),
 
     // ========== 群事件（1501-1520 直接复用 OpenIM 段位编号；1530+ 我们独有扩展） ==========
     // 1500 对应 OpenIM GroupNotificationBegin 起始位，仅作占位，不使用
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestService.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestService.java
new file mode 100644
index 0000000..cb08e45
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestService.java
@@ -0,0 +1,49 @@
+package cn.iocoder.yudao.module.im.service.friend;
+
+import cn.iocoder.yudao.module.im.controller.admin.friend.vo.request.ImFriendRequestApplyReqVO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
+
+import java.util.List;
+
+/**
+ * IM 好友申请 Service 接口
+ *
+ * @author 芋道源码
+ */
+public interface ImFriendRequestService {
+
+    /**
+     * 发起好友申请
+     *
+     * @param fromUserId 发起方用户编号
+     * @param reqVO      申请请求
+     * @return 申请记录
+     */
+    ImFriendRequestDO applyFriend(Long fromUserId, ImFriendRequestApplyReqVO reqVO);
+
+    /**
+     * 同意好友申请
+     *
+     * @param userId    操作人用户编号
+     * @param requestId 申请记录编号
+     */
+    void agreeFriendRequest(Long userId, Long requestId);
+
+    /**
+     * 拒绝好友申请
+     *
+     * @param userId        操作人用户编号
+     * @param requestId     申请记录编号
+     * @param handleContent 拒绝理由
+     */
+    void refuseFriendRequest(Long userId, Long requestId, String handleContent);
+
+    /**
+     * 查询「我相关」的申请列表（含我发起的、别人加我的）
+     *
+     * @param userId 用户编号
+     * @return 申请记录列表
+     */
+    List<ImFriendRequestDO> getMyFriendRequestList(Long userId);
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestServiceImpl.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestServiceImpl.java
new file mode 100644
index 0000000..05d084e
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendRequestServiceImpl.java
@@ -0,0 +1,189 @@
+package cn.iocoder.yudao.module.im.service.friend;
+
+import cn.hutool.core.util.BooleanUtil;
+import cn.hutool.core.util.ObjUtil;
+import cn.hutool.extra.spring.SpringUtil;
+import cn.iocoder.yudao.framework.common.enums.CommonStatusEnum;
+import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
+import cn.iocoder.yudao.module.im.controller.admin.friend.vo.request.ImFriendRequestApplyReqVO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendDO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
+import cn.iocoder.yudao.module.im.dal.mysql.friend.ImFriendRequestMapper;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendRequestHandleResultEnum;
+import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
+import cn.iocoder.yudao.module.im.framework.config.ImProperties;
+import cn.iocoder.yudao.module.im.service.websocket.ImWebSocketService;
+import cn.iocoder.yudao.module.im.service.websocket.dto.ImPrivateMessageDTO;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend.FriendRequestApprovedNotification;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend.FriendRequestNotification;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend.FriendRequestRejectedNotification;
+import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
+import jakarta.annotation.Resource;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.transaction.support.TransactionSynchronization;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
+import org.springframework.validation.annotation.Validated;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Objects;
+
+import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.*;
+
+/**
+ * IM 好友申请 Service 实现类
+ *
+ * @author 芋道源码
+ */
+@Slf4j
+@Service
+@Validated
+public class ImFriendRequestServiceImpl implements ImFriendRequestService {
+
+    @Resource
+    private ImFriendRequestMapper friendRequestMapper;
+
+    @Resource
+    private ImFriendService friendService;
+    @Resource
+    private ImWebSocketService websocketService;
+
+    @Resource
+    private ImProperties imProperties;
+
+    @Resource
+    private AdminUserApi adminUserApi;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public ImFriendRequestDO applyFriend(Long fromUserId, ImFriendRequestApplyReqVO reqVO) {
+        Long toUserId = reqVO.getToUserId();
+        // 1.1 校验：不能加自己
+        if (Objects.equals(fromUserId, toUserId)) {
+            throw exception(FRIEND_ADD_SELF);
+        }
+        // 1.2 校验对方存在且启用
+        adminUserApi.validateUser(toUserId);
+        // 1.3 已是好友：直接幂等返回
+        ImFriendDO friend = friendService.getFriend(fromUserId, toUserId);
+        if (friend != null && CommonStatusEnum.isEnable(friend.getStatus())) {
+            return null;
+        }
+        // 1.4 被对方拉黑：静默成功，不暴露
+        // TODO @AI：是不是 peerFriend？这样更好理解。
+        // TODO @AI：是不是应该提示被拉黑了？返回 null 给前端很奇怪。
+        ImFriendDO reverse = friendService.getFriend(toUserId, fromUserId);
+        if (reverse != null && BooleanUtil.isTrue(reverse.getBlocked())) {
+            log.info("[applyFriend][fromUserId({}) 被 toUserId({}) 拉黑，静默忽略]", fromUserId, toUserId);
+            return null;
+        }
+
+        // 2. 落库：复用最新一条未处理记录；否则新建
+        ImFriendRequestDO request = friendRequestMapper.selectLatestByFromUserIdAndToUserId(fromUserId, toUserId);
+        if (request != null && ImFriendRequestHandleResultEnum.isUnhandled(request.getHandleResult())) {
+            // 复用未处理记录：刷新申请理由 / 备注 / 来源；createTime 维持首次申请时间不变（与列表 id DESC 排序一致）
+            BeanUtils.copyProperties(reqVO, request);
+            friendRequestMapper.updateById(request);
+        } else {
+            request = BeanUtils.toBean(reqVO, ImFriendRequestDO.class)
+                    .setFromUserId(fromUserId).setToUserId(toUserId)
+                    .setHandleResult(ImFriendRequestHandleResultEnum.UNHANDLED.getResult());
+            friendRequestMapper.insert(request);
+        }
+
+        // 3. 推送 FRIEND_APPLICATION 给 toUser 多端
+        FriendRequestNotification payload = (FriendRequestNotification) new FriendRequestNotification()
+                .setRequestId(request.getId()).setApplyContent(request.getApplyContent()).setAddSource(request.getAddSource())
+                .setOperatorUserId(fromUserId).setFriendUserId(fromUserId);
+        websocketService.sendPrivateMessageAsync(toUserId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_APPLICATION.getType(), fromUserId, toUserId, payload));
+
+        // 4. 全局自动通过开关：注册 afterCommit 回调，事务提交后再走同意流程
+        if (imProperties.getFriend().isAutoAccept()) {
+            Long requestId = request.getId();
+            TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
+
+                @Override
+                public void afterCommit() {
+                    getSelf().agreeFriendRequest(toUserId, requestId);
+                }
+
+            });
+        }
+        return request;
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void agreeFriendRequest(Long userId, Long requestId) {
+        // 1. 校验申请存在 + 未处理 + 操作人是接收方
+        ImFriendRequestDO request = validateRequestForHandle(userId, requestId);
+
+        // 2. 更新申请：handleResult=AGREED + handleTime
+        LocalDateTime now = LocalDateTime.now();
+        friendRequestMapper.updateById(new ImFriendRequestDO().setId(request.getId())
+                .setHandleResult(ImFriendRequestHandleResultEnum.AGREED.getResult()).setHandleTime(now));
+        request.setHandleResult(ImFriendRequestHandleResultEnum.AGREED.getResult()).setHandleTime(now);
+
+        // 3. 双向建立好友关系
+        friendService.becomeFriends(request);
+
+        // 4. 推 FRIEND_REQUEST_APPROVED 给 fromUser 多端
+        FriendRequestApprovedNotification payload = (FriendRequestApprovedNotification)
+                new FriendRequestApprovedNotification().setRequestId(request.getId())
+                        .setOperatorUserId(userId).setFriendUserId(userId);
+        websocketService.sendPrivateMessageAsync(request.getFromUserId(), ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_REQUEST_APPROVED.getType(), userId, request.getFromUserId(), payload));
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void refuseFriendRequest(Long userId, Long requestId, String handleContent) {
+        // 1. 校验申请存在 + 未处理 + 操作人是接收方
+        ImFriendRequestDO request = validateRequestForHandle(userId, requestId);
+
+        // 2. 更新申请：handleResult=REFUSED + handleContent + handleTime
+        LocalDateTime now = LocalDateTime.now();
+        friendRequestMapper.updateById(new ImFriendRequestDO().setId(request.getId())
+                .setHandleResult(ImFriendRequestHandleResultEnum.REFUSED.getResult())
+                .setHandleContent(handleContent).setHandleTime(now));
+
+        // 3. 推 FRIEND_REQUEST_REJECTED 给 fromUser 多端
+        FriendRequestRejectedNotification payload = (FriendRequestRejectedNotification)
+                new FriendRequestRejectedNotification().setRequestId(request.getId())
+                        .setHandleContent(handleContent)
+                        .setOperatorUserId(userId).setFriendUserId(userId);
+        websocketService.sendPrivateMessageAsync(request.getFromUserId(), ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_REQUEST_REJECTED.getType(), userId, request.getFromUserId(), payload));
+    }
+
+    @Override
+    public List<ImFriendRequestDO> getMyFriendRequestList(Long userId) {
+        return friendRequestMapper.selectMyList(userId, imProperties.getFriend().getRequestListMaxSize());
+    }
+
+    /**
+     * 校验申请可被「当前用户」处理：申请存在 + 未处理 + 操作人 = 接收方
+     */
+    private ImFriendRequestDO validateRequestForHandle(Long userId, Long requestId) {
+        ImFriendRequestDO request = friendRequestMapper.selectById(requestId);
+        if (request == null) {
+            throw exception(FRIEND_REQUEST_NOT_EXISTS);
+        }
+        if (ObjUtil.notEqual(request.getToUserId(), userId)) {
+            throw exception(FRIEND_REQUEST_NOT_TO_ME);
+        }
+        if (!ImFriendRequestHandleResultEnum.isUnhandled(request.getHandleResult())) {
+            throw exception(FRIEND_REQUEST_HANDLED);
+        }
+        return request;
+    }
+
+    private ImFriendRequestServiceImpl getSelf() {
+        return SpringUtil.getBean(getClass());
+    }
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendService.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendService.java
index bdedc73..b39e24a 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendService.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendService.java
@@ -4,88 +4,81 @@ import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.im.controller.admin.friend.vo.ImFriendUpdateReqVO;
 import cn.iocoder.yudao.module.im.controller.admin.manager.friend.vo.ImFriendManagerPageReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendDO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendStateEnum;
 
 import java.util.Collection;
 import java.util.List;
 
 /**
  * IM 好友关系 Service 接口
+ * <p>
+ * 注意：用户端「加好友」走 {@link ImFriendRequestService#applyFriend} 申请-审批流程，
+ * 不再开放直接 add 接口；只有 {@link #becomeFriends} 是内部入口（被 agree 同意 / 管理员 import 触发）。
  *
  * @author 芋道源码
  */
 public interface ImFriendService {
 
     /**
-     * 判断两个用户是否是好友关系（未删除状态）
-     *
-     * @param userId       用户编号
-     * @param friendUserId 好友用户编号
-     * @return 是否好友
+     * 获取 userId 视角下与 friendUserId 的好友关系状态（私聊发送热点路径）
+     * <p>
+     * 合并「是否好友」+「是否被自己拉黑」两态，供调用方一次缓存查询完成判定，详见 {@link ImFriendStateEnum}
      */
-    boolean isFriend(Long userId, Long friendUserId);
+    ImFriendStateEnum getFriendState(Long userId, Long friendUserId);
 
     /**
      * 获得当前用户的好友列表（含已删除状态）
-     * <p>
-     * 返回的列表里**包含已删除状态**，前端按 status 区分展示（已删除的置灰）；
-     * 原因是本地已经建立会话的好友被单向删除后，前端仍需要展示头像/昵称。
-     *
-     * @param userId 用户编号
-     * @return 好友关系列表（含已删除的记录）
      */
     List<ImFriendDO> getFriendList(Long userId);
 
     /**
      * 获得当前用户与指定用户之间的有效好友列表（仅 ENABLE 状态）
-     *
-     * @param userId        用户编号
-     * @param friendUserIds 需要校验的好友用户编号集合
-     * @return 有效好友关系列表
      */
     List<ImFriendDO> getActiveFriendList(Long userId, Collection<Long> friendUserIds);
 
     /**
-     * 查询一个好友关系记录（仅限本人视角）
-     *
-     * @param userId       当前登录用户编号
-     * @param friendUserId 目标用户编号
-     * @return 好友关系记录，不存在返回 null
+     * 查询一个好友关系记录
      */
     ImFriendDO getFriend(Long userId, Long friendUserId);
 
+    // ==================== 内部入口 ====================
+
     /**
-     * 添加好友（双向绑定）
+     * 双向建立好友关系（内部入口）
      * <p>
-     * 核心流程：
-     * 1. 校验：不允许添加自己；对方必须存在
-     * 2. 双向插入/更新关系（若已存在则刷新为未删除）
-     * 3. 推送"你们已成为好友"系统提示（TODO）
+     * 由 {@link ImFriendRequestService#agreeFriendRequest} 同意申请 / 管理后台导入触发；
+     * A 侧 displayName / addSource 取自申请记录；B 侧 displayName 为空、addSource 同来源。
+     * 写库后推送 FRIEND_ADD 通知给 A、B 双方多端，并下发 TIP 系统消息。
      *
-     * @param userId       当前登录用户编号
-     * @param friendUserId 好友的用户编号
+     * @param request 已同意的申请记录（决定 fromUserId / toUserId / addSource / displayName）
      */
-    void addFriend(Long userId, Long friendUserId);
+    void becomeFriends(ImFriendRequestDO request);
+
+    // ==================== 用户端 ====================
 
     /**
-     * 删除好友（双向软删除）
+     * 删除好友（单向软删除）
      * <p>
-     * 两边关系都标记为已删除状态。
-     *
-     * @param userId       当前登录用户编号
-     * @param friendUserId 好友的用户编号
+     * 仅删除 userId 视角下的好友关系；对端 friendUserId 的视角不受影响（与 OpenIM 单边删除语义对齐）
      */
     void deleteFriend(Long userId, Long friendUserId);
 
     /**
-     * 更新好友信息（仅更新本人→对方的单边关系属性）
-     * <p>
-     * 目前支持：免打扰（muted）；后续可扩展备注等字段。
-     *
-     * @param userId  当前登录用户编号
-     * @param reqVO   更新请求
+     * 更新好友单边属性（备注 / 免打扰 / 联系人置顶）
      */
     void updateFriend(Long userId, ImFriendUpdateReqVO reqVO);
 
+    /**
+     * 拉黑好友（必须先是好友）
+     */
+    void blockFriend(Long userId, Long friendUserId);
+
+    /**
+     * 移出黑名单
+     */
+    void unblockFriend(Long userId, Long friendUserId);
+
     // ==================== 管理后台 ====================
 
     /**
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendServiceImpl.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendServiceImpl.java
index 1e503cd..fd550a9 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendServiceImpl.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/friend/ImFriendServiceImpl.java
@@ -1,22 +1,26 @@
 package cn.iocoder.yudao.module.im.service.friend;
 
+import cn.hutool.core.util.BooleanUtil;
 import cn.hutool.extra.spring.SpringUtil;
 import cn.iocoder.yudao.framework.common.enums.CommonStatusEnum;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.im.controller.admin.friend.vo.ImFriendUpdateReqVO;
 import cn.iocoder.yudao.module.im.controller.admin.manager.friend.vo.ImFriendManagerPageReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendDO;
+import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendRequestDO;
 import cn.iocoder.yudao.module.im.dal.mysql.friend.ImFriendMapper;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendStateEnum;
+import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
 import cn.iocoder.yudao.module.im.service.message.ImPrivateMessageService;
 import cn.iocoder.yudao.module.im.service.websocket.ImWebSocketService;
 import cn.iocoder.yudao.module.im.service.websocket.dto.ImPrivateMessageDTO;
-import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend.*;
 import jakarta.annotation.Resource;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.cache.annotation.CacheEvict;
 import org.springframework.cache.annotation.Cacheable;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.context.annotation.Lazy;
-import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.validation.annotation.Validated;
@@ -24,11 +28,10 @@ import org.springframework.validation.annotation.Validated;
 import java.time.LocalDateTime;
 import java.util.Collection;
 import java.util.List;
-import java.util.Objects;
 
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
-import static cn.iocoder.yudao.module.im.dal.redis.RedisKeyConstants.FRIEND;
-import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FRIEND_ADD_SELF;
+import static cn.iocoder.yudao.module.im.dal.redis.RedisKeyConstants.FRIEND_STATE;
+import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FRIEND_NOT_BLOCKED;
 import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FRIEND_NOT_FRIEND;
 import static cn.iocoder.yudao.module.im.enums.ImCommonConstants.FRIEND_ADD_TIP_MESSAGE;
 import static cn.iocoder.yudao.module.im.enums.ImCommonConstants.FRIEND_DELETE_TIP_MESSAGE;
@@ -44,138 +47,218 @@ import static cn.iocoder.yudao.module.im.enums.ImCommonConstants.FRIEND_DELETE_T
 public class ImFriendServiceImpl implements ImFriendService {
 
     @Resource
-    private ImFriendMapper imFriendMapper;
+    private ImFriendMapper friendMapper;
 
     @Resource
-    private AdminUserApi adminUserApi;
-
-    @Resource
-    private ImWebSocketService imWebSocketService;
+    private ImWebSocketService websocketService;
     @Resource
     @Lazy
     private ImPrivateMessageService privateMessageService;
 
     @Override
-    @Cacheable(cacheNames = FRIEND, key = "#userId + '_' + #friendUserId", unless = "#result == null")
-    public boolean isFriend(Long userId, Long friendUserId) {
-        ImFriendDO friend = imFriendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
-        return friend != null && CommonStatusEnum.isEnable(friend.getStatus());
+    @Cacheable(cacheNames = FRIEND_STATE, key = "#userId + '_' + #friendUserId", unless = "#result == null")
+    public ImFriendStateEnum getFriendState(Long userId, Long friendUserId) {
+        // 1.1 我侧记录：我方删了，都算非好友
+        ImFriendDO mine = friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        if (mine == null || !CommonStatusEnum.isEnable(mine.getStatus())) {
+            return ImFriendStateEnum.NONE;
+        }
+        // 1.2 对方侧记录：对方删了 = 不是好友
+        ImFriendDO peer = friendMapper.selectByUserIdAndFriendUserId(friendUserId, userId);
+        if (peer == null || !CommonStatusEnum.isEnable(peer.getStatus())) {
+            return ImFriendStateEnum.NONE;
+        }
+        // 2. 仅当双方都是 ENABLE 状态，才算好友关系；此时对方拉黑我，则是 BLOCKED
+        return BooleanUtil.isTrue(peer.getBlocked()) ? ImFriendStateEnum.BLOCKED : ImFriendStateEnum.FRIEND;
     }
 
     @Override
     public List<ImFriendDO> getFriendList(Long userId) {
-        return imFriendMapper.selectListByUserId(userId);
+        return friendMapper.selectListByUserId(userId);
     }
 
     @Override
     public List<ImFriendDO> getActiveFriendList(Long userId, Collection<Long> friendUserIds) {
-        return imFriendMapper.selectListByUserIdAndFriendUserIdsAndStatus(userId, friendUserIds,
+        return friendMapper.selectListByUserIdAndFriendUserIdsAndStatus(userId, friendUserIds,
                 CommonStatusEnum.ENABLE.getStatus());
     }
 
     @Override
     public ImFriendDO getFriend(Long userId, Long friendUserId) {
-        return imFriendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        return friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
     }
 
     @Override
     public void updateFriend(Long userId, ImFriendUpdateReqVO reqVO) {
-        // 1. 校验好友关系存在
-        ImFriendDO friend = imFriendMapper.selectByUserIdAndFriendUserId(userId, reqVO.getFriendUserId());
+        // 1.1 校验：至少改一个字段（无字段变更，直接结束）
+        if (reqVO.getDisplayName() == null && reqVO.getMuted() == null && reqVO.getPinned() == null) {
+            return;
+        }
+        // 1.2 校验好友关系存在
+        ImFriendDO friend = friendMapper.selectByUserIdAndFriendUserId(userId, reqVO.getFriendUserId());
         if (friend == null) {
             throw exception(FRIEND_NOT_FRIEND);
         }
 
-        // 2. 更新好友属性
-        imFriendMapper.updateById(new ImFriendDO().setId(friend.getId())
-                .setMuted(reqVO.getMuted()).setDisplayName(reqVO.getDisplayName()));
+        // 2. 更新好友属性（备注 / 免打扰 / 联系人置顶）
+        friendMapper.updateById(new ImFriendDO().setId(friend.getId())
+                .setMuted(reqVO.getMuted())
+                .setDisplayName(reqVO.getDisplayName())
+                .setPinned(reqVO.getPinned()));
 
-        // 3. 推送好友更新通知（多端同步）
-        imWebSocketService.sendPrivateMessageAsync(userId,
-                ImPrivateMessageDTO.ofFriendUpdate(userId, reqVO.getFriendUserId()));
+        // 3. 推 FRIEND_UPDATE 给 A 多端：所有单边属性变更合并为单条通知，避免多通知顺序竞争
+        FriendUpdateNotification payload = (FriendUpdateNotification) new FriendUpdateNotification()
+                .setDisplayName(reqVO.getDisplayName()).setMuted(reqVO.getMuted()).setPinned(reqVO.getPinned())
+                .setOperatorUserId(userId).setFriendUserId(reqVO.getFriendUserId());
+        websocketService.sendPrivateMessageAsync(userId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_UPDATE.getType(), userId, userId, payload));
     }
 
     @Override
     @Transactional(rollbackFor = Exception.class)
-    public void addFriend(Long userId, Long friendUserId) {
-        // 1.1 校验：不允许添加自己为好友
-        if (Objects.equals(userId, friendUserId)) {
-            throw exception(FRIEND_ADD_SELF);
-        }
-        // 1.2 校验对方存在（禁用/不存在的账号不允许添加）
-        adminUserApi.validateUser(friendUserId);
-
-        // 2. 双向绑定
-        getSelf().addFriend0(userId, friendUserId);
-        getSelf().addFriend0(friendUserId, userId);
-
-        // 3.1 插入 TIP_TEXT 系统提示消息并推送双方
-        privateMessageService.sendTipPrivateMessage(userId, friendUserId, FRIEND_ADD_TIP_MESSAGE);
-        // 3.2 推送好友添加通知给双方
-        imWebSocketService.sendPrivateMessageAsync(userId,
-                ImPrivateMessageDTO.ofFriendAdd(friendUserId, userId));
-        imWebSocketService.sendPrivateMessageAsync(friendUserId,
-                ImPrivateMessageDTO.ofFriendAdd(userId, friendUserId));
+    public void becomeFriends(ImFriendRequestDO request) {
+        Long fromUserId = request.getFromUserId();
+        Long toUserId = request.getToUserId();
+        // 1. 双向建立关系：A 侧带申请的 displayName / addSource；B 侧 displayName 为空、addSource 同来源
+        getSelf().addFriend0(fromUserId, toUserId, request.getDisplayName(), request.getAddSource());
+        getSelf().addFriend0(toUserId, fromUserId, null, request.getAddSource());
+
+        // TODO DONE @AI：删除「在 openim 里」措辞；TIP 与 FRIEND_ADD 目的不同保持双发
+        // TODO @AI：在确认一次；是否需要发送 tip？而是通过 FRIEND_ADD 可以满足了。。。（讨论一下）
+        // 2.1 推 TIP 系统消息（双方私聊会话里看到「你们已成为好友」）；TIP 走会话入库，FRIEND_ADD 走事件通知
+        privateMessageService.sendTipPrivateMessage(fromUserId, toUserId, FRIEND_ADD_TIP_MESSAGE);
+
+        // 2.2.1 推 FRIEND_ADD 给 fromUser 多端
+        FriendAddNotification toFrom = (FriendAddNotification) new FriendAddNotification()
+                .setOperatorUserId(toUserId).setFriendUserId(toUserId);
+        websocketService.sendPrivateMessageAsync(fromUserId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_ADD.getType(), toUserId, fromUserId, toFrom));
+        // 2.2.2 推 FRIEND_ADD 给 toUser 多端
+        FriendAddNotification toTo = (FriendAddNotification) new FriendAddNotification()
+                .setOperatorUserId(fromUserId).setFriendUserId(fromUserId);
+        websocketService.sendPrivateMessageAsync(toUserId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_ADD.getType(), fromUserId, toUserId, toTo));
     }
 
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void deleteFriend(Long userId, Long friendUserId) {
-        // 1. 双向标记为 DISABLE + 记录 deleteTime
+        // 1. 单边软删：仅 userId 视角的关系置 DISABLE；friendUserId 视角不动
         getSelf().deleteFriend0(userId, friendUserId);
-        getSelf().deleteFriend0(friendUserId, userId);
 
-        // 2.1 插入 TIP_TEXT 系统提示消息并推送双方
+        // 2.1 推 TIP 系统消息
         privateMessageService.sendTipPrivateMessage(userId, friendUserId, FRIEND_DELETE_TIP_MESSAGE);
-        // 2.2 推送好友删除通知给双方
-        imWebSocketService.sendPrivateMessageAsync(userId,
-                ImPrivateMessageDTO.ofFriendDelete(userId, friendUserId));
-        imWebSocketService.sendPrivateMessageAsync(friendUserId,
-                ImPrivateMessageDTO.ofFriendDelete(friendUserId, userId));
+
+        // 2.2 推 FRIEND_DELETE 给 userId 多端做同步（friendUserId 不感知）
+        FriendDeleteNotification payload = (FriendDeleteNotification) new FriendDeleteNotification()
+                .setOperatorUserId(userId).setFriendUserId(friendUserId);
+        websocketService.sendPrivateMessageAsync(userId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_DELETE.getType(), userId, userId, payload));
+    }
+
+    @Override
+    @Caching(evict = {
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#userId + '_' + #friendUserId"),
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#friendUserId + '_' + #userId")
+    })
+    public void blockFriend(Long userId, Long friendUserId) {
+        // 1.1 校验是好友
+        ImFriendDO friend = friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        if (friend == null || !CommonStatusEnum.isEnable(friend.getStatus())) {
+            throw exception(FRIEND_NOT_FRIEND);
+        }
+        // 1.2 已拉黑直接返回，幂等
+        if (BooleanUtil.isTrue(friend.getBlocked())) {
+            return;
+        }
+
+        // 2. 单边更新
+        friendMapper.updateById(new ImFriendDO().setId(friend.getId()).setBlocked(true));
+
+        // 3. 推 FRIEND_BLOCK 给 A 多端
+        FriendBlockNotification payload = (FriendBlockNotification) new FriendBlockNotification()
+                .setOperatorUserId(userId).setFriendUserId(friendUserId);
+        websocketService.sendPrivateMessageAsync(userId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_BLOCK.getType(), userId, userId, payload));
+    }
+
+    @Override
+    @Caching(evict = {
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#userId + '_' + #friendUserId"),
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#friendUserId + '_' + #userId")
+    })
+    public void unblockFriend(Long userId, Long friendUserId) {
+        // 1.1 校验是好友
+        ImFriendDO friend = friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        if (friend == null || !CommonStatusEnum.isEnable(friend.getStatus())) {
+            throw exception(FRIEND_NOT_FRIEND);
+        }
+        // 1.2 未拉黑则报错
+        if (!BooleanUtil.isTrue(friend.getBlocked())) {
+            throw exception(FRIEND_NOT_BLOCKED);
+        }
+
+        // 2. 单边更新
+        friendMapper.updateById(new ImFriendDO().setId(friend.getId()).setBlocked(false));
+
+        // 3. 推 FRIEND_UNBLOCK 给 A 多端
+        FriendUnblockNotification payload = (FriendUnblockNotification) new FriendUnblockNotification()
+                .setOperatorUserId(userId).setFriendUserId(friendUserId);
+        websocketService.sendPrivateMessageAsync(userId, ImPrivateMessageDTO.ofFriendNotification(
+                ImMessageTypeEnum.FRIEND_UNBLOCK.getType(), userId, userId, payload));
     }
 
     /**
-     * 单向绑定好友关系：
-     * - 首次：新增记录（status=ENABLE，addTime=now）
-     * - 已存在且 ENABLE：无需重复操作
-     * - 已存在但 DISABLE：恢复关系（status=ENABLE，刷新 addTime，清空 deleteTime）
+     * 单向绑定好友关系（内部方法，被 {@link #becomeFriends} 调用）：
+     * - 情况一：已存在记录（含 ENABLE / DISABLE）→ 复用并恢复 ENABLE，重置 muted / pinned / blocked 为 false（删好友再加回来不沿袭旧设置）
+     * - 情况二：不存在记录 → 直接插入新记录
      * <p>
-     * 并发安全：依靠 im_friend 表的唯一索引 uk_im_friend_user_friend(user_id, friend_user_id) 保证幂等，
-     * 当并发 insert 触发 {@link DuplicateKeyException} 时降级为 select + update。
+     * 并发安全：业务侧通过 friend_request.handle_result 已保证 agree 不会并发触发；
+     * 极端并发下若插入唯一键冲突，让 DuplicateKeyException 向外抛出，外层事务回滚。
      */
-    @CacheEvict(cacheNames = FRIEND, key = "#userId + '_' + #friendUserId")
-    public void addFriend0(Long userId, Long friendUserId) {
-        ImFriendDO exists = imFriendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
-        // 情况一：已存在记录 → 恢复或跳过
+    @Caching(evict = {
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#userId + '_' + #friendUserId"),
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#friendUserId + '_' + #userId")
+    })
+    public void addFriend0(Long userId, Long friendUserId, String displayName, Integer addSource) {
+        ImFriendDO exists = friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        // 情况一：复用旧记录 → 恢复 ENABLE + 重置 muted / pinned / blocked 与首次新增对齐
         if (exists != null) {
-            if (CommonStatusEnum.isEnable(exists.getStatus())) {
-                return;
+            ImFriendDO update = new ImFriendDO().setId(exists.getId())
+                    .setStatus(CommonStatusEnum.ENABLE.getStatus()).setAddTime(LocalDateTime.now())
+                    .setMuted(false).setPinned(false).setBlocked(false);
+            if (displayName != null) {
+                update.setDisplayName(displayName);
             }
-            imFriendMapper.updateById(new ImFriendDO().setId(exists.getId())
-                    .setStatus(CommonStatusEnum.ENABLE.getStatus()).setAddTime(LocalDateTime.now()));
+            if (addSource != null) {
+                update.setAddSource(addSource);
+            }
+            friendMapper.updateById(update);
             return;
         }
-        // 情况二：新增好友关系
+        // 情况二：不存在记录 → 直接插入新记录
         ImFriendDO friend = ImFriendDO.builder().userId(userId).friendUserId(friendUserId)
-                .muted(false).status(CommonStatusEnum.ENABLE.getStatus()).addTime(LocalDateTime.now()).build();
-        try {
-            imFriendMapper.insert(friend);
-        } catch (DuplicateKeyException e) {
-            // 并发场景：另一个请求已先一步插入，且其插入的必然是 ENABLE 状态（DISABLE 场景在上方分支已处理），直接忽略
-            log.warn("[addFriend0][userId({}) friendUserId({}) 并发插入冲突，忽略]", userId, friendUserId);
-        }
+                .muted(false).pinned(false).blocked(false)
+                .displayName(displayName).addSource(addSource)
+                .status(CommonStatusEnum.ENABLE.getStatus()).addTime(LocalDateTime.now()).build();
+        friendMapper.insert(friend);
     }
 
     /**
      * 单向解除好友关系（status 设为 DISABLE，记录 deleteTime）
+     * <p>
+     * blocked 不主动重置：删好友期间保留拉黑状态；如果未来再 addFriend0，由 addFriend0 统一重置
      */
-    @CacheEvict(cacheNames = FRIEND, key = "#userId + '_' + #friendUserId")
+    @Caching(evict = {
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#userId + '_' + #friendUserId"),
+            @CacheEvict(cacheNames = FRIEND_STATE, key = "#friendUserId + '_' + #userId")
+    })
     public void deleteFriend0(Long userId, Long friendUserId) {
-        ImFriendDO exists = imFriendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
+        ImFriendDO exists = friendMapper.selectByUserIdAndFriendUserId(userId, friendUserId);
         if (exists == null || CommonStatusEnum.isDisable(exists.getStatus())) {
             return;
         }
-        imFriendMapper.updateById(new ImFriendDO().setId(exists.getId())
+        friendMapper.updateById(new ImFriendDO().setId(exists.getId())
                 .setStatus(CommonStatusEnum.DISABLE.getStatus()).setDeleteTime(LocalDateTime.now()));
     }
 
@@ -187,7 +270,7 @@ public class ImFriendServiceImpl implements ImFriendService {
 
     @Override
     public PageResult<ImFriendDO> getFriendPage(ImFriendManagerPageReqVO reqVO) {
-        return imFriendMapper.selectPage(reqVO);
+        return friendMapper.selectPage(reqVO);
     }
 
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImpl.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImpl.java
index 453e484..eed78d7 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImpl.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImpl.java
@@ -13,6 +13,7 @@ import cn.iocoder.yudao.module.im.dal.dataobject.message.ImPrivateMessageDO;
 import cn.iocoder.yudao.module.im.dal.mysql.message.ImPrivateMessageMapper;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageStatusEnum;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
+import cn.iocoder.yudao.module.im.enums.friend.ImFriendStateEnum;
 import cn.iocoder.yudao.module.im.service.friend.ImFriendService;
 import cn.iocoder.yudao.module.im.service.message.dto.ImPrivateMessageSendDTO;
 import cn.iocoder.yudao.module.im.service.sensitiveword.ImSensitiveWordService;
@@ -66,9 +67,13 @@ public class ImPrivateMessageServiceImpl implements ImPrivateMessageService {
             return existing;
         }
         // 1.2 好友校验
-        if (!friendService.isFriend(senderId, reqVO.getReceiverId())) {
+        ImFriendStateEnum state = friendService.getFriendState(senderId, reqVO.getReceiverId());
+        if (state == ImFriendStateEnum.NONE) {
             throw exception(FRIEND_NOT_FRIEND);
         }
+        if (state == ImFriendStateEnum.BLOCKED) {
+            throw exception(FRIEND_BLOCKED_BY_PEER);
+        }
         // 1.3 文本消息敏感词过滤
         if (ImMessageTypeEnum.TEXT.getType().equals(reqVO.getType())) {
             sensitiveWordService.validateText(reqVO.getContent());
@@ -81,7 +86,7 @@ public class ImPrivateMessageServiceImpl implements ImPrivateMessageService {
                 .setSenderId(senderId).setStatus(ImMessageStatusEnum.UNREAD.getStatus()).setSendTime(LocalDateTime.now()));
         privateMessageMapper.insert(message);
 
-        // 3. WebSocket 异步推送（接收方 + 发送方多端同步）
+        // 3. WebSocket 异步推送：接收方 + 发送方多端同步
         ImPrivateMessageDTO websocketMessage = ImPrivateMessageDTO.ofSend(message);
         imWebSocketService.sendPrivateMessageAsync(message.getReceiverId(), websocketMessage);
         imWebSocketService.sendPrivateMessageAsync(senderId, websocketMessage);
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/dto/ImGroupMessageSendDTO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/dto/ImGroupMessageSendDTO.java
index 33eeb83..1403d51 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/dto/ImGroupMessageSendDTO.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/dto/ImGroupMessageSendDTO.java
@@ -1,7 +1,7 @@
 package cn.iocoder.yudao.module.im.service.message.dto;
 
 import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
-import cn.iocoder.yudao.module.im.service.websocket.dto.notification.*;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.group.*;
 import jakarta.validation.constraints.NotNull;
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/ImPrivateMessageDTO.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/ImPrivateMessageDTO.java
index a609561..df3a19f 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/ImPrivateMessageDTO.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/ImPrivateMessageDTO.java
@@ -1,8 +1,10 @@
 package cn.iocoder.yudao.module.im.service.websocket.dto;
 
+import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
 import cn.iocoder.yudao.module.im.dal.dataobject.message.ImPrivateMessageDO;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
+import cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend.BaseFriendNotification;
 import lombok.Data;
 import lombok.experimental.Accessors;
 
@@ -103,45 +105,19 @@ public class ImPrivateMessageDTO {
     // ==================== 好友变更相关 ====================
 
     /**
-     * 构建好友添加推送 DTO（通知对方"你有一位新好友"）
+     * 构建好友通知推送 DTO（统一入口）
      *
-     * @param userId       当前用户编号（即发起添加的用户）
-     * @param friendUserId 好友的用户编号（即接收通知的用户）
+     * @param type            消息类型；取自 {@link ImMessageTypeEnum} 中的 FRIEND_* 段
+     * @param operatorUserId  操作人用户编号；同时作为帧的 senderId 用于定位接收端 friendUserId
+     * @param receiverUserId  推送目标用户编号
+     * @param payload         好友通知 payload（继承 {@link BaseFriendNotification}）
      * @return 私聊 DTO
      */
-    public static ImPrivateMessageDTO ofFriendAdd(Long userId, Long friendUserId) {
-        return new ImPrivateMessageDTO()
-                .setType(ImMessageTypeEnum.FRIEND_ADD.getType())
-                .setSenderId(userId).setReceiverId(friendUserId)
-                .setSendTime(LocalDateTime.now());
-    }
-
-    /**
-     * 构建好友删除推送 DTO（通知对方"好友关系已解除"）
-     *
-     * @param userId       当前用户编号（即发起删除的用户）
-     * @param friendUserId 好友的用户编号（即接收通知的用户）
-     * @return 私聊 DTO
-     */
-    public static ImPrivateMessageDTO ofFriendDelete(Long userId, Long friendUserId) {
-        return new ImPrivateMessageDTO()
-                .setType(ImMessageTypeEnum.FRIEND_DELETE.getType())
-                .setSenderId(userId).setReceiverId(friendUserId)
-                .setSendTime(LocalDateTime.now());
-    }
-
-    /**
-     * 构建好友更新推送 DTO（通知自己多端同步好友属性变更）
-     *
-     * @param userId       当前用户编号
-     * @param friendUserId 好友的用户编号
-     * @return 私聊 DTO
-     */
-    public static ImPrivateMessageDTO ofFriendUpdate(Long userId, Long friendUserId) {
-        return new ImPrivateMessageDTO()
-                .setType(ImMessageTypeEnum.FRIEND_UPDATE.getType())
-                .setSenderId(userId).setReceiverId(friendUserId)
-                .setSendTime(LocalDateTime.now());
+    public static ImPrivateMessageDTO ofFriendNotification(Integer type, Long operatorUserId,
+                                                           Long receiverUserId, BaseFriendNotification payload) {
+        return new ImPrivateMessageDTO().setType(type)
+                .setSenderId(operatorUserId).setReceiverId(receiverUserId)
+                .setContent(JsonUtils.toJsonString(payload)).setSendTime(LocalDateTime.now());
     }
 
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/BaseFriendNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/BaseFriendNotification.java
new file mode 100644
index 0000000..4ee8f87
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/BaseFriendNotification.java
@@ -0,0 +1,24 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 好友事件通知基类
+ * <p>
+ * 所有好友事件 payload 共享：
+ * - operatorUserId 标识"谁触发的"，用于多端同步时本端识别"是我自己触发的"还是"对方触发的"
+ * - friendUserId 标识"好友是谁"，前端按它定位 / 更新本地 friend 缓存
+ */
+@Data
+public abstract class BaseFriendNotification {
+
+    /**
+     * 操作人用户编号
+     */
+    private Long operatorUserId;
+    /**
+     * 好友用户编号
+     */
+    private Long friendUserId;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendAddNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendAddNotification.java
new file mode 100644
index 0000000..5892174
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendAddNotification.java
@@ -0,0 +1,13 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 新增好友通知
+ * <p>
+ * 双向建立好友关系后，推送给 A、B 双方多端；前端拉取好友信息入库
+ */
+@Data
+public class FriendAddNotification extends BaseFriendNotification {
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendBlockNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendBlockNotification.java
new file mode 100644
index 0000000..f8cb69e
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendBlockNotification.java
@@ -0,0 +1,13 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 加入黑名单通知
+ * <p>
+ * A 拉黑 B 后仅推 A 多端；B 端不感知（B 那边 blocked=0 不变）
+ */
+@Data
+public class FriendBlockNotification extends BaseFriendNotification {
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendDeleteNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendDeleteNotification.java
new file mode 100644
index 0000000..cd887e0
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendDeleteNotification.java
@@ -0,0 +1,13 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 好友删除通知
+ * <p>
+ * 仅推送给操作人多端做同步（对端不感知，与单边删除语义对齐）；前端清除本地好友 + 级联清理私聊会话
+ */
+@Data
+public class FriendDeleteNotification extends BaseFriendNotification {
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendInfoUpdatedNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendInfoUpdatedNotification.java
new file mode 100644
index 0000000..a7be29d
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendInfoUpdatedNotification.java
@@ -0,0 +1,16 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+// TODO @AI：1209 暂未实现；好友信息在 system 模块，需要 system 改昵称 / 头像后发 ApplicationEvent，IM 模块监听后回调发送此通知
+/**
+ * 好友资料变更通知（对端改了昵称 / 头像）
+ * <p>
+ * 推送给资料被改的人的所有好友；前端清缓存 + 重拉资料
+ * <p>
+ * 此处 friendUserId 表示「资料被更新的那个人」（即对端），与 operatorUserId 一致
+ */
+@Data
+public class FriendInfoUpdatedNotification extends BaseFriendNotification {
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestApprovedNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestApprovedNotification.java
new file mode 100644
index 0000000..bc68f4f
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestApprovedNotification.java
@@ -0,0 +1,18 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 好友申请被同意通知
+ * <p>
+ * 推送给原申请发起方多端；前端按 requestId 把对应申请记录 handleResult 更新为「已同意」
+ */
+@Data
+public class FriendRequestApprovedNotification extends BaseFriendNotification {
+
+    /**
+     * 已处理的申请记录编号
+     */
+    private Long requestId;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestNotification.java
new file mode 100644
index 0000000..965e904
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestNotification.java
@@ -0,0 +1,26 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 收到新的好友申请通知
+ * <p>
+ * 推送给申请的接收方多端；前端拿到 requestId 后按需 fetch 完整申请记录，避免 payload 体积过大
+ */
+@Data
+public class FriendRequestNotification extends BaseFriendNotification {
+
+    /**
+     * 申请记录编号
+     */
+    private Long requestId;
+    /**
+     * 申请理由
+     */
+    private String applyContent;
+    /**
+     * 添加来源
+     */
+    private Integer addSource;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestRejectedNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestRejectedNotification.java
new file mode 100644
index 0000000..afe0a18
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendRequestRejectedNotification.java
@@ -0,0 +1,22 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 好友申请被拒绝通知
+ * <p>
+ * 推送给原申请发起方多端；前端按 requestId 把对应申请记录 handleResult 更新为「已拒绝」
+ */
+@Data
+public class FriendRequestRejectedNotification extends BaseFriendNotification {
+
+    /**
+     * 已处理的申请记录编号
+     */
+    private Long requestId;
+    /**
+     * 拒绝理由（可选）
+     */
+    private String handleContent;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUnblockNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUnblockNotification.java
new file mode 100644
index 0000000..a57f00d
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUnblockNotification.java
@@ -0,0 +1,13 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 移出黑名单通知
+ * <p>
+ * A 把 B 移出黑名单后仅推 A 多端
+ */
+@Data
+public class FriendUnblockNotification extends BaseFriendNotification {
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUpdateNotification.java
new file mode 100644
index 0000000..24cf533
--- /dev/null
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/friend/FriendUpdateNotification.java
@@ -0,0 +1,27 @@
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.friend;
+
+import lombok.Data;
+
+/**
+ * 好友信息批量更新通知（备注 / 免打扰 / 联系人置顶等单边属性）
+ * <p>
+ * A 改了对 B 的备注 / 免打扰 / 置顶等单边属性后仅推 A 多端做同步；
+ * 一次 update 涉及多个字段时合并为单条通知，避免多通知顺序竞争。
+ */
+@Data
+public class FriendUpdateNotification extends BaseFriendNotification {
+
+    /**
+     * 备注；不为空则更新（空串表示清空）
+     */
+    private String displayName;
+    /**
+     * 免打扰；不为空则更新
+     */
+    private Boolean muted;
+    /**
+     * 联系人置顶；不为空则更新
+     */
+    private Boolean pinned;
+
+}
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/BaseGroupNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/BaseGroupNotification.java
index 781851d..3e916b1 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/BaseGroupNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/BaseGroupNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupAdminAddNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupAdminAddNotification.java
index be15f9a..186835d 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupAdminAddNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupAdminAddNotification.java
@@ -1,7 +1,7 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 添加管理员事件通知（memberUserIds 为被设管理员的成员）
  */
-public class GroupAdminAddNotification extends MembersAffectedNotification {
+public class GroupAdminAddNotification extends GroupMembersAffectedNotification {
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupAdminRemoveNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupAdminRemoveNotification.java
index 6620d5d..f6bc3ea 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupAdminRemoveNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupAdminRemoveNotification.java
@@ -1,7 +1,7 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 撤销管理员事件通知（memberUserIds 为被撤销管理员的成员）
  */
-public class GroupAdminRemoveNotification extends MembersAffectedNotification {
+public class GroupAdminRemoveNotification extends GroupMembersAffectedNotification {
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupCreateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupCreateNotification.java
index 862afe7..4c3b6fc 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupCreateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupCreateNotification.java
@@ -1,7 +1,7 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 群创建事件通知（memberUserIds 含创建者 + 初始邀请成员）
  */
-public class GroupCreateNotification extends MembersAffectedNotification {
+public class GroupCreateNotification extends GroupMembersAffectedNotification {
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupDissolveNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupDissolveNotification.java
index 5392bf4..bec91fa 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupDissolveNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupDissolveNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 群解散事件通知
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupInfoUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupInfoUpdateNotification.java
index 3f629e5..70a073d 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupInfoUpdateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupInfoUpdateNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberInviteNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberInviteNotification.java
index 64a3bfd..0092bfe 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberInviteNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberInviteNotification.java
@@ -1,7 +1,7 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 成员加入事件通知（memberUserIds 为被邀请人）
  */
-public class GroupMemberInviteNotification extends MembersAffectedNotification {
+public class GroupMemberInviteNotification extends GroupMembersAffectedNotification {
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberKickNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberKickNotification.java
index 4f4a0e3..3ac811d 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberKickNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberKickNotification.java
@@ -1,7 +1,7 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 成员被移出事件通知（memberUserIds 为被移出成员）
  */
-public class GroupMemberKickNotification extends MembersAffectedNotification {
+public class GroupMemberKickNotification extends GroupMembersAffectedNotification {
 }
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberNicknameUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberNicknameUpdateNotification.java
index 2d8020f..0fbe63f 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberNicknameUpdateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberNicknameUpdateNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberQuitNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberQuitNotification.java
index 406aed1..cab23a5 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberQuitNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberQuitNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 /**
  * 成员退群事件通知
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberSettingUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberSettingUpdateNotification.java
index 7183393..949be97 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMemberSettingUpdateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMemberSettingUpdateNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/MembersAffectedNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMembersAffectedNotification.java
index 5c82a13..add8349 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/MembersAffectedNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMembersAffectedNotification.java
@@ -1,14 +1,16 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
 import java.util.List;
 
+// TODO DONE @AI：本身已是 BaseGroupNotification 的子类，名字不带 Group 前缀是因为是抽象基类、被多种 Group* 通知共用
+// TODO @AI：它目前只被 group 使用。别过度设计，名字按照我说的调整下；
 /**
  * 涉及成员列表的群事件通知基类：用于 Create / Invite / Kick / AdminAdd / AdminRemove
  */
 @Data
-public abstract class MembersAffectedNotification extends BaseGroupNotification {
+public abstract class GroupMembersAffectedNotification extends BaseGroupNotification {
 
     /**
      * 受影响的成员用户编号列表
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMessagePinNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMessagePinNotification.java
index 12d509e..fe7e9ef 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMessagePinNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMessagePinNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import cn.iocoder.yudao.module.im.dal.dataobject.message.ImGroupMessageDO;
 import lombok.Data;
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMessageUnpinNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMessageUnpinNotification.java
index 204fa2a..1185b5c 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupMessageUnpinNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupMessageUnpinNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupNameUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupNameUpdateNotification.java
index 0d95571..689ef24 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupNameUpdateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupNameUpdateNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupNoticeUpdateNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupNoticeUpdateNotification.java
index c52fb1d..c2afa6c 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupNoticeUpdateNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupNoticeUpdateNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupOwnerTransferNotification.java b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupOwnerTransferNotification.java
index e099ab0..612a764 100644
--- a/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/GroupOwnerTransferNotification.java
+++ b/yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/notification/group/GroupOwnerTransferNotification.java
@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.module.im.service.websocket.dto.notification;
+package cn.iocoder.yudao.module.im.service.websocket.dto.notification.group;
 
 import lombok.Data;
 
diff --git a/yudao-module-im/src/test/resources/sql/clean.sql b/yudao-module-im/src/test/resources/sql/clean.sql
index 9101fff..39f3097 100644
--- a/yudao-module-im/src/test/resources/sql/clean.sql
+++ b/yudao-module-im/src/test/resources/sql/clean.sql
@@ -3,3 +3,4 @@ DELETE FROM "im_group_message";
 DELETE FROM "im_group";
 DELETE FROM "im_group_member";
 DELETE FROM "im_friend";
+DELETE FROM "im_friend_request";
diff --git a/yudao-module-im/src/test/resources/sql/create_tables.sql b/yudao-module-im/src/test/resources/sql/create_tables.sql
index 6689d38..5ad1dd2 100644
--- a/yudao-module-im/src/test/resources/sql/create_tables.sql
+++ b/yudao-module-im/src/test/resources/sql/create_tables.sql
@@ -84,6 +84,9 @@ CREATE TABLE IF NOT EXISTS "im_friend" (
     "friend_user_id" bigint NOT NULL COMMENT '好友用户编号',
     "muted" bit DEFAULT FALSE COMMENT '是否免打扰',
     "display_name" varchar(64) NOT NULL DEFAULT '' COMMENT '好友展示备注（仅自己可见）',
+    "add_source" tinyint DEFAULT NULL COMMENT '添加来源',
+    "pinned" bit DEFAULT FALSE COMMENT '是否置顶联系人',
+    "blocked" bit DEFAULT FALSE COMMENT '是否拉黑',
     "status" tinyint NOT NULL COMMENT '好友状态',
     "add_time" timestamp DEFAULT NULL COMMENT '添加好友时间',
     "delete_time" timestamp DEFAULT NULL COMMENT '删除好友时间',
@@ -95,3 +98,22 @@ CREATE TABLE IF NOT EXISTS "im_friend" (
     "tenant_id" bigint NOT NULL DEFAULT 0,
     PRIMARY KEY ("id")
 ) COMMENT 'IM 好友关系表';
+
+CREATE TABLE IF NOT EXISTS "im_friend_request" (
+    "id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY COMMENT '编号',
+    "from_user_id" bigint NOT NULL COMMENT '发起方用户编号',
+    "to_user_id" bigint NOT NULL COMMENT '接收方用户编号',
+    "handle_result" tinyint NOT NULL DEFAULT 0 COMMENT '处理结果；0未处理；1同意；2拒绝',
+    "apply_content" varchar(255) DEFAULT NULL COMMENT '申请理由',
+    "handle_content" varchar(255) DEFAULT NULL COMMENT '处理理由',
+    "display_name" varchar(64) DEFAULT NULL COMMENT '发起方对接收方的备注',
+    "add_source" tinyint DEFAULT NULL COMMENT '添加来源',
+    "handle_time" timestamp DEFAULT NULL COMMENT '处理时间',
+    "creator" varchar(64) DEFAULT '',
+    "create_time" timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updater" varchar(64) DEFAULT '',
+    "update_time" timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deleted" bit NOT NULL DEFAULT FALSE,
+    "tenant_id" bigint NOT NULL DEFAULT 0,
+    PRIMARY KEY ("id")
+) COMMENT 'IM 好友申请记录表';