✨ feat(im): 初始化表情包 v0.1：第二把 review

YunaiV
1 parent 8a4ad959
Showing 22 changed files with 106 additions and 112 deletions
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/face/ImFacePackController.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/face/ImFaceUserItemController.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/manager/face/ImFacePackItemManagerController.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/manager/face/ImFacePackManagerController.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/face/ImFacePackItemMapper.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/face/ImFacePackMapper.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFacePackItemService.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFacePackItemServiceImpl.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFacePackService.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFacePackServiceImpl.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFaceUserItemService.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/face/ImFaceUserItemServiceImpl.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/websocket/dto/message/FaceMessage.java
@@ -2,7 +2,7 @@ package cn.iocoder.yudao.module.im.controller.admin.face;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.face.vo.ImFacePackUserRespVO;
+import cn.iocoder.yudao.module.im.controller.admin.face.vo.pack.ImFacePackUserRespVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackDO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackItemDO;
 import cn.iocoder.yudao.module.im.service.face.ImFacePackItemService;
@@ -2,8 +2,8 @@ package cn.iocoder.yudao.module.im.controller.admin.face;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.face.vo.ImFaceUserItemRespVO;
-import cn.iocoder.yudao.module.im.controller.admin.face.vo.ImFaceUserItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem.ImFaceUserItemRespVO;
+import cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem.ImFaceUserItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFaceUserItemDO;
 import cn.iocoder.yudao.module.im.service.face.ImFaceUserItemService;
 import io.swagger.v3.oas.annotations.Operation;
@@ -30,8 +30,8 @@ public class ImFaceUserItemController {
     @GetMapping("/list")
     @Operation(summary = "获得我的个人表情列表")
-    public CommonResult<List<ImFaceUserItemRespVO>> getMyFaceUserItemList() {
-        List<ImFaceUserItemDO> items = faceUserItemService.getMyFaceUserItemList(getLoginUserId());
+    public CommonResult<List<ImFaceUserItemRespVO>> getFaceUserItemList() {
+        List<ImFaceUserItemDO> items = faceUserItemService.getFaceUserItemList(getLoginUserId());
         return success(BeanUtils.toBean(items, ImFaceUserItemRespVO.class));
     }
@@ -49,13 +49,4 @@ public class ImFaceUserItemController {
         return success(true);
     }
-    // TODO @AI：个人应该没批量删除把？应该就一个一个删除呢。
-    @DeleteMapping("/delete-list")
-    @Operation(summary = "批量删除个人表情")
-    @Parameter(name = "ids", description = "编号列表", required = true)
-    public CommonResult<Boolean> deleteFaceUserItemList(@RequestParam("ids") List<Long> ids) {
-        faceUserItemService.deleteFaceUserItemList(getLoginUserId(), ids);
-        return success(true);
-    }
-
 }
-package cn.iocoder.yudao.module.im.controller.admin.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.face.vo.pack;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
-package cn.iocoder.yudao.module.im.controller.admin.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
-package cn.iocoder.yudao.module.im.controller.admin.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
@@ -3,9 +3,9 @@ package cn.iocoder.yudao.module.im.controller.admin.manager.face;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemRespVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemRespVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackItemDO;
 import cn.iocoder.yudao.module.im.service.face.ImFacePackItemService;
 import io.swagger.v3.oas.annotations.Operation;
@@ -3,9 +3,9 @@ package cn.iocoder.yudao.module.im.controller.admin.manager.face;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackRespVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackRespVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackDO;
 import cn.iocoder.yudao.module.im.service.face.ImFacePackService;
 import io.swagger.v3.oas.annotations.Operation;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item;
 import cn.iocoder.yudao.framework.common.pojo.PageParam;
 import io.swagger.v3.oas.annotations.media.Schema;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack;
 import cn.iocoder.yudao.framework.common.pojo.PageParam;
 import io.swagger.v3.oas.annotations.media.Schema;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
-package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo;
+package cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
@@ -3,7 +3,7 @@ package cn.iocoder.yudao.module.im.dal.mysql.face;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
 import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemPageReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackItemDO;
 import org.apache.ibatis.annotations.Mapper;
@@ -3,7 +3,7 @@ package cn.iocoder.yudao.module.im.dal.mysql.face;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
 import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackPageReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackDO;
 import org.apache.ibatis.annotations.Mapper;
 package cn.iocoder.yudao.module.im.service.face;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackItemDO;
 import jakarta.validation.Valid;
 import java.util.Collection;
 import java.util.List;
+// TODO @AI：已经分了用户端、和管理后台，注释上就不用写【用户端】【【管理后台】】了。。。
+// TODO @AI：注释的风格，参考下别的模块，一些 params、return 都要写呀；
 /**
  * IM 表情包项 Service 接口
  *
@@ -23,6 +25,16 @@ public interface ImFacePackItemService {
      */
     List<ImFacePackItemDO> getEnabledItemListByPackIds(Collection<Long> packIds);
+    /**
+     * 取某个表情包下的表情数量；ImFacePackService 删除前校验「包下无项」用
+     */
+    Long getFacePackItemCount(Long packId);
+
+    /**
+     * 取多个表情包下的表情数量合计；ImFacePackService 批量删除前校验用
+     */
+    Long getFacePackItemCount(Collection<Long> packIds);
+
     // ==================== 管理后台 ====================
     /**
@@ -4,8 +4,8 @@ import cn.hutool.core.collection.CollUtil;
 import cn.iocoder.yudao.framework.common.enums.CommonStatusEnum;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.item.ImFacePackItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackItemDO;
 import cn.iocoder.yudao.module.im.dal.mysql.face.ImFacePackItemMapper;
 import jakarta.annotation.Resource;
@@ -43,6 +43,19 @@ public class ImFacePackItemServiceImpl implements ImFacePackItemService {
         return facePackItemMapper.selectListByPackIdsAndStatus(packIds, CommonStatusEnum.ENABLE.getStatus());
     }
+    @Override
+    public Long getFacePackItemCount(Long packId) {
+        return facePackItemMapper.selectCountByPackId(packId);
+    }
+
+    @Override
+    public Long getFacePackItemCount(Collection<Long> packIds) {
+        if (CollUtil.isEmpty(packIds)) {
+            return 0L;
+        }
+        return facePackItemMapper.selectCountByPackIds(packIds);
+    }
+
     // ==================== 管理后台 ====================
     @Override
@@ -57,32 +70,33 @@ public class ImFacePackItemServiceImpl implements ImFacePackItemService {
     @Override
     public Long createFacePackItem(ImFacePackItemSaveReqVO reqVO) {
-        // 校验所属表情包存在
+        // 1. 校验所属表情包存在
         facePackService.validateFacePackExists(reqVO.getPackId());
-        ImFacePackItemDO item = BeanUtils.toBean(reqVO, ImFacePackItemDO.class);
-        // TODO @AI：注释风格，和别的模块一致
+        // 2. 入库
+        ImFacePackItemDO item = BeanUtils.toBean(reqVO, ImFacePackItemDO.class);
         facePackItemMapper.insert(item);
         return item.getId();
     }
     @Override
     public void updateFacePackItem(ImFacePackItemSaveReqVO reqVO) {
-        // TODO @AI：注释风格，和别的模块一致
+        // 1.1 校验存在
         validateFacePackItemExists(reqVO.getId());
-        // TODO @AI：注释风格，和别的模块一致
+        // 1.2 校验所属表情包存在
         facePackService.validateFacePackExists(reqVO.getPackId());
-        // TODO @AI：注释风格，和别的模块一致
+        // 2. 更新
         ImFacePackItemDO updateObj = BeanUtils.toBean(reqVO, ImFacePackItemDO.class);
         facePackItemMapper.updateById(updateObj);
     }
     @Override
     public void deleteFacePackItem(Long id) {
-        // TODO @AI：注释风格，和别的模块一致
+        // 1. 校验存在
         validateFacePackItemExists(id);
-        // TODO @AI：注释风格，和别的模块一致
+
+        // 2. 删除
         facePackItemMapper.deleteById(id);
     }
 package cn.iocoder.yudao.module.im.service.face;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackDO;
 import jakarta.validation.Valid;
@@ -4,12 +4,12 @@ import cn.hutool.core.collection.CollUtil;
 import cn.iocoder.yudao.framework.common.enums.CommonStatusEnum;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackPageReqVO;
-import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.ImFacePackSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackPageReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.manager.face.vo.pack.ImFacePackSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFacePackDO;
-import cn.iocoder.yudao.module.im.dal.mysql.face.ImFacePackItemMapper;
 import cn.iocoder.yudao.module.im.dal.mysql.face.ImFacePackMapper;
 import jakarta.annotation.Resource;
+import org.springframework.context.annotation.Lazy;
 import org.springframework.stereotype.Service;
 import org.springframework.validation.annotation.Validated;
@@ -31,9 +31,12 @@ public class ImFacePackServiceImpl implements ImFacePackService {
     @Resource
     private ImFacePackMapper facePackMapper;
-    // TODO @AI：跨模块操作，需要调用对方 service；
+    /**
+     * @Lazy 解决与 ImFacePackItemServiceImpl 的循环依赖（item.create / update 校验所属包存在 → 反向调用本类）
+     */
     @Resource
-    private ImFacePackItemMapper facePackItemMapper;
+    @Lazy
+    private ImFacePackItemService facePackItemService;
     // ==================== 用户端 ====================
@@ -72,10 +75,10 @@ public class ImFacePackServiceImpl implements ImFacePackService {
     @Override
     public void updateFacePack(ImFacePackSaveReqVO reqVO) {
-        // TODO @AI：注释，参考别的模块
+        // 1. 校验存在
         validateFacePackExists(reqVO.getId());
-        // TODO @AI：注释，参考别的模块
+        // 2. 更新
         ImFacePackDO updateObj = BeanUtils.toBean(reqVO, ImFacePackDO.class);
         facePackMapper.updateById(updateObj);
     }
@@ -85,7 +88,7 @@ public class ImFacePackServiceImpl implements ImFacePackService {
         // 1.1 校验存在
         validateFacePackExists(id);
         // 1.2 校验表情包下没有表情；防止误删表情包导致历史 face 消息无法回查归属
-        if (facePackItemMapper.selectCountByPackId(id) > 0) {
+        if (facePackItemService.getFacePackItemCount(id) > 0) {
             throw exception(FACE_PACK_HAS_ITEMS);
         }
@@ -95,15 +98,15 @@ public class ImFacePackServiceImpl implements ImFacePackService {
     @Override
     public void deleteFacePackList(List<Long> ids) {
+        // 1. 任一存在表情则拒绝整批删除，避免「只删一半」的中间态
         if (CollUtil.isEmpty(ids)) {
             return;
         }
-        // 任一存在表情则拒绝整批删除，避免「只删一半」的中间态
-        if (facePackItemMapper.selectCountByPackIds(ids) > 0) {
+        if (facePackItemService.getFacePackItemCount(ids) > 0) {
             throw exception(FACE_PACK_HAS_ITEMS);
         }
-        // 执行删除
+        // 2. 删除
         facePackMapper.deleteByIds(ids);
     }
 package cn.iocoder.yudao.module.im.service.face;
-import cn.iocoder.yudao.module.im.controller.admin.face.vo.ImFaceUserItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem.ImFaceUserItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFaceUserItemDO;
 import jakarta.validation.Valid;
@@ -14,25 +14,20 @@ import java.util.List;
 public interface ImFaceUserItemService {
     /**
-     * 获取我的个人表情列表
+     * 获取指定用户的个人表情列表
      */
-    List<ImFaceUserItemDO> getMyFaceUserItemList(Long userId);
+    List<ImFaceUserItemDO> getFaceUserItemList(Long userId);
     /**
-     * 添加个人表情；返回新增 id（已存在则直接返回旧 id）
+     * 添加个人表情；返回新增记录 id
      * <p>
-     * 同 URL 重复添加时返回旧记录 id，不报错
+     * 同 URL 重复添加抛 FACE_USER_ITEM_DUPLICATED；表上 (user_id, url) 唯一约束兜底并发 race
      */
     Long createFaceUserItem(Long userId, @Valid ImFaceUserItemSaveReqVO reqVO);
     /**
-     * 删除我的某条个人表情
+     * 删除指定用户的某条个人表情
      */
     void deleteFaceUserItem(Long userId, Long id);
-    /**
-     * 批量删除我的个人表情
-     */
-    void deleteFaceUserItemList(Long userId, List<Long> ids);
-
 }
 package cn.iocoder.yudao.module.im.service.face;
-import cn.hutool.core.collection.CollUtil;
+import cn.hutool.core.util.ObjectUtil;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
-import cn.iocoder.yudao.module.im.controller.admin.face.vo.ImFaceUserItemSaveReqVO;
+import cn.iocoder.yudao.module.im.controller.admin.face.vo.userItem.ImFaceUserItemSaveReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.face.ImFaceUserItemDO;
 import cn.iocoder.yudao.module.im.dal.mysql.face.ImFaceUserItemMapper;
 import jakarta.annotation.Resource;
+import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.validation.annotation.Validated;
 import java.util.List;
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FACE_USER_ITEM_DUPLICATED;
 import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FACE_USER_ITEM_NOT_EXISTS;
 import static cn.iocoder.yudao.module.im.enums.ErrorCodeConstants.FACE_USER_ITEM_NOT_OWN;
@@ -27,66 +29,44 @@ public class ImFaceUserItemServiceImpl implements ImFaceUserItemService {
     @Resource
     private ImFaceUserItemMapper faceUserItemMapper;
-    // TODO @AI：传递了 userid，就不用写 myXXX 了；
     @Override
-    public List<ImFaceUserItemDO> getMyFaceUserItemList(Long userId) {
+    public List<ImFaceUserItemDO> getFaceUserItemList(Long userId) {
         return faceUserItemMapper.selectListByUserId(userId);
     }
     @Override
     public Long createFaceUserItem(Long userId, ImFaceUserItemSaveReqVO reqVO) {
-        // 1. 同 URL 已添加：直接返回旧 id；避免一张图反复添加占额度，并保证「添加到表情」幂等
-        // TODO @AI：是不是提示下，已经有这个标签库了。。。
-        ImFaceUserItemDO exist = faceUserItemMapper.selectByUserIdAndUrl(userId, reqVO.getUrl());
-        if (exist != null) {
-            return exist.getId();
+        // 1. 同 URL 已存在则报错；前端 catch 后 toast「已添加过」
+        if (faceUserItemMapper.selectByUserIdAndUrl(userId, reqVO.getUrl()) != null) {
+            throw exception(FACE_USER_ITEM_DUPLICATED);
         }
-        // 2. 入库
-        // TODO @AI：链式调用
-        ImFaceUserItemDO item = BeanUtils.toBean(reqVO, ImFaceUserItemDO.class);
-        item.setUserId(userId);
-        item.setSort(0);
-        faceUserItemMapper.insert(item);
+        // 2. 入库；表 (user_id, url, tenant_id) 唯一约束兜底并发 race —— 两个请求同时过 step 1 时 DB 拦截
+        // TODO @AI：不加唯一索引。不然删除后恢复麻烦。按照我说的来。
+        ImFaceUserItemDO item = BeanUtils.toBean(reqVO, ImFaceUserItemDO.class)
+                .setUserId(userId);
+        try {
+            faceUserItemMapper.insert(item);
+        } catch (DuplicateKeyException ignored) {
+            throw exception(FACE_USER_ITEM_DUPLICATED);
+        }
         return item.getId();
     }
     @Override
     public void deleteFaceUserItem(Long userId, Long id) {
+        // 1.1 校验存在
         ImFaceUserItemDO item = faceUserItemMapper.selectById(id);
         if (item == null) {
             throw exception(FACE_USER_ITEM_NOT_EXISTS);
         }
-        // 防止 A 用户传 B 用户的表情 id 删除别人的表情
-        // TODO @AI：notEquals；
-        if (!item.getUserId().equals(userId)) {
+        // 1.2 校验归属：防止 A 用户传 B 用户的表情 id 删别人的
+        if (ObjectUtil.notEqual(item.getUserId(), userId)) {
             throw exception(FACE_USER_ITEM_NOT_OWN);
         }
-        // TODO @AI：注释
+        // 2. 删除
         faceUserItemMapper.deleteById(id);
     }
-    @Override
-    public void deleteFaceUserItemList(Long userId, List<Long> ids) {
-        if (CollUtil.isEmpty(ids)) {
-            return;
-        }
-        // 一次性查全部待删项；任一不属于当前用户则整批拒绝
-        // TODO @AI：过滤掉，不属于自己的；
-        List<ImFaceUserItemDO> items = faceUserItemMapper.selectByIds(ids);
-        // TODO @AI：不存在的，直接跳过；
-        if (CollUtil.size(items) != CollUtil.size(ids)) {
-            throw exception(FACE_USER_ITEM_NOT_EXISTS);
-        }
-        for (ImFaceUserItemDO item : items) {
-            if (!item.getUserId().equals(userId)) {
-                throw exception(FACE_USER_ITEM_NOT_OWN);
-            }
-        }
-
-        // TODO @AI：注释
-        faceUserItemMapper.deleteByIds(ids);
-    }
-
 }
@@ -14,15 +14,14 @@ public class FaceMessage {
      * 表情图 URL
      */
     private String url;
-    // TODO @AI：openim 有这个字段么？不是一般 url 就足够了呀。
     /**
-     * 渲染宽度（像素）
+     * 渲染宽度（像素，可选）
      * <p>
-     * 客户端渲染时按此尺寸占位，避免图片加载完成后的布局抖动
+     * 客户端渲染时按此尺寸占位，避免图片加载完成后的布局抖动；缺失时由客户端 CSS max-width 兜底
      */
     private Integer width;
     /**
-     * 渲染高度（像素）
+     * 渲染高度（像素，可选）
      */
     private Integer height;
     /**