分类功能添加注释

alien-entity/src/main/java/shop/alien/mapper/second/SecondGoodsCategoryMapper.java

@@ -7,13 +7,24 @@ import shop.alien.entity.second.SecondGoodsCategory;
 import java.util.List;
 
 /**
- * 二手商品映射器
+ * 二手商品分类Mapper接口
+ * 提供商品分类的数据库操作方法
  */
 public interface SecondGoodsCategoryMapper extends BaseMapper<SecondGoodsCategory> {
+    
     /**
-     * 自定义分页查询
+     * 根据父级ID和状态查询商品分类列表
+     *
+     * @param parentId 父级分类ID，可为空，为空时查询顶级分类
+     * @param categoryState 分类状态，可为空，1表示启用，0表示禁用
+     * @return 商品分类列表
      */
     List<SecondGoodsCategory> querySecondGoodsByParentId(@Param("parentId") Integer parentId, @Param("categoryState") Integer categoryState);
 
+    /**
+     * 查询所有商品分类信息
+     *
+     * @return 所有商品分类列表
+     */
     List<SecondGoodsCategory> querySecondGoodsInfo();
 }

alien-entity/src/main/java/shop/alien/mapper/second/SecondRecommendMapper.java

@@ -11,19 +11,60 @@ import java.util.List;
 
 
 /**
- * 二手商品映射器
+ * 二手商品推荐Mapper接口
+ * 提供商品推荐、关注商品、新品商品等列表查询和商品详情查询的数据库操作方法
  */
 public interface SecondRecommendMapper extends BaseMapper<SecondGoodsRecommendVo> {
+    
     /**
-     * 自定义分页查询
+     * 分页查询推荐商品列表
+     *
+     * @param page 分页参数
+     * @param userId 用户ID
+     * @param position 经纬度信息，格式为"经度,纬度"
+     * @param typeId 商品类型ID
+     * @param phoneId 手机ID
+     * @return 分页的推荐商品列表
      */
     IPage<SecondGoodsRecommendVo> getSecondRecommendByPage(IPage<SecondGoodsRecommendVo> page, @Param("userId") Integer userId, @Param("position") String position, @Param("typeId") Integer typeId, @Param("phoneId") String phoneId);
 
+    /**
+     * 分页查询关注商品列表
+     *
+     * @param page 分页参数
+     * @param userId 用户ID
+     * @param phoneId 手机ID
+     * @param position 经纬度信息，格式为"经度,纬度"
+     * @return 分页的关注商品列表
+     */
     IPage<SecondGoodsRecommendVo> querySecondConcernByPage(IPage<SecondGoodsRecommendVo> page, @Param("userId") Integer userId, @Param("phoneId") String phoneId, @Param("position") String position);
 
+    /**
+     * 分页查询新品商品列表
+     *
+     * @param page 分页参数
+     * @param userId 用户ID
+     * @param phoneId 手机ID
+     * @param position 经纬度信息，格式为"经度,纬度"
+     * @return 分页的新品商品列表
+     */
     IPage<SecondGoodsRecommendVo> querySecondNewGoodsByPage(IPage<SecondGoodsRecommendVo> page,@Param("userId") String userId, @Param("phoneId") String phoneId, @Param("position") String position);
 
+    /**
+     * 查询商品的评论信息
+     *
+     * @param ids 商品ID列表
+     * @return 商品评论信息列表
+     */
     List<SecondCommentVo> querySecondCommentInfo(@Param("ids") List<Integer> ids);
 
+    /**
+     * 查询商品详情信息
+     *
+     * @param goodsId 商品ID
+     * @param phoneId 手机ID
+     * @param position 经纬度信息，格式为"经度,纬度"
+     * @return 商品详情信息
+     */
     SecondGoodsRecommendVo querySecondGoodsDetail(@Param("goodsId") Integer goodsId, @Param("phoneId") String phoneId, @Param("position") String position);
 }

alien-second/src/main/java/shop/alien/second/controller/SecondGoodsCategoryController.java

@@ -12,6 +12,10 @@ import shop.alien.second.service.SecondGoodsCategoryService;
 
 import java.util.List;
 
+/**
+ * 二手平台商品类型控制器
+ * 提供商品类型查询功能
+ */
 @Slf4j
 @Api(tags = {"二手平台-商品类型"})
 @ApiSort(9)
@@ -23,6 +27,14 @@ public class SecondGoodsCategoryController {
 
     private final SecondGoodsCategoryService service;
 
+    /**
+     * 根据父级ID和状态查询商品类型列表
+     *
+     * @param parentId 父级类型ID，可为空，为空时查询顶级分类
+     * @param categoryState 分类状态，可为空，1表示启用，0表示禁用
+     * @return 商品类型列表
+     * @throws Exception 查询过程中可能发生的异常
+     */
     @ApiOperation("搜索商品类型")
     @PostMapping("/querySecondGoodsByParentId")
     public R<List<SecondGoodsCategory>> querySecondGoodsByParentId(
@@ -30,4 +42,4 @@ public class SecondGoodsCategoryController {
             @RequestParam(value = "categoryState", required = false) Integer categoryState) throws Exception {
         return R.data(service.querySecondGoodsByParentId(parentId, categoryState), "查询成功");
     }
-}
+}

alien-second/src/main/java/shop/alien/second/service/SecondGoodsCategoryService.java

@@ -6,21 +6,45 @@ import shop.alien.entity.second.SecondGoodsCategory;
 import java.util.List;
 
 /**
- * 二手商品服务接口
+ * 二手商品分类服务接口
+ * 提供商品分类的查询、新增、更新等操作功能
  */
 public interface SecondGoodsCategoryService extends IService<SecondGoodsCategory> {
 
     /**
-     * 获取分类列表
-     * @param parentId 父ID
-     * @return 分页后的屏蔽商品列
+     * 根据父级ID和状态查询商品分类列表
+     *
+     * @param parentId 父级分类ID，可为空，为空时查询顶级分类
+     * @param categoryState 分类状态，可为空，1表示启用，0表示禁用
+     * @return 商品分类列表
+     * @throws Exception 查询过程中可能发生的异常
      */
     List<SecondGoodsCategory> querySecondGoodsByParentId(Integer parentId, Integer categoryState) throws Exception;
 
+    /**
+     * 新增商品分类
+     *
+     * @param category 商品分类对象
+     * @return 受影响的行数，大于0表示插入成功
+     * @throws Exception 插入过程中可能发生的异常
+     */
     Integer insertSecondGoodsCategory(SecondGoodsCategory category) throws Exception;
 
+    /**
+     * 更新商品分类
+     *
+     * @param category 商品分类对象
+     * @return 受影响的行数，大于0表示更新成功
+     * @throws Exception 更新过程中可能发生的异常
+     */
     Integer updateSecondGoodsCategory(SecondGoodsCategory category) throws Exception;
 
+    /**
+     * 查询商品分类树结构
+     *
+     * @return 商品分类树结构列表
+     * @throws Exception 查询过程中可能发生的异常
+     */
     List<SecondGoodsCategory> querySecondGoodsTree() throws Exception;
 
 }

alien-second/src/main/java/shop/alien/second/service/impl/SecondGoodsCategoryServiceImpl.java

@@ -21,7 +21,8 @@ import java.util.Map;
 import java.util.stream.Collectors;
 
 /**
- * 二手商品服务实现类
+ * 二手商品分类服务实现类
+ * 实现商品分类的查询、新增、更新和构建树形结构等核心业务逻辑
  */
 @Slf4j
 @Service
@@ -30,10 +31,14 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
 
     @Autowired
     private SecondGoodsCategoryMapper mapper;
+    
     /**
-     * 保存商品为草稿状态
-     * @param parentId 商品实体
-     * @return 是否成功保存
+     * 根据父级ID和状态查询商品分类列表
+     *
+     * @param parentId 父级分类ID，可为空，为空时查询顶级分类
+     * @param categoryState 分类状态，可为空，1表示启用，0表示禁用
+     * @return 商品分类列表
+     * @throws Exception 查询过程中可能发生的异常
      */
     @Override
     public List<SecondGoodsCategory> querySecondGoodsByParentId(Integer parentId, Integer categoryState) throws Exception {
@@ -45,6 +50,14 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
         }
     }
 
+    /**
+     * 新增商品分类
+     * 会自动计算分类排序值，确保在同一父级下排序值递增
+     *
+     * @param category 商品分类对象
+     * @return 受影响的行数，大于0表示插入成功
+     * @throws Exception 插入过程中可能发生的异常
+     */
     @Override
     public Integer insertSecondGoodsCategory(SecondGoodsCategory category) throws Exception {
         try {
@@ -65,6 +78,14 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
         }
     }
 
+    /**
+     * 更新商品分类
+     * 可以更新分类名称、URL、父级ID、排序、状态等字段，并记录更新人信息
+     *
+     * @param category 商品分类对象
+     * @return 受影响的行数，大于0表示更新成功
+     * @throws Exception 更新过程中可能发生的异常
+     */
     public Integer updateSecondGoodsCategory(SecondGoodsCategory category) throws Exception {
         try {
             JSONObject data = JwtUtil.getCurrentUserInfo();
@@ -106,6 +127,13 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
     }
 
 
+    /**
+     * 查询商品分类树结构
+     * 将所有商品分类构建成树形结构，便于前端展示
+     *
+     * @return 商品分类树结构列表
+     * @throws Exception 查询过程中可能发生的异常
+     */
     @Override
     public List<SecondGoodsCategory> querySecondGoodsTree() throws Exception {
         try {
@@ -116,6 +144,12 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
         }
     }
 
+    /**
+     * 构建商品分类树形结构
+     *
+     * @param nodes 所有商品分类节点列表
+     * @return 根节点列表，每个根节点包含其子节点
+     */
     // 2. 构建树的核心逻辑
     public List<SecondGoodsCategory> buildTree(List<SecondGoodsCategory> nodes) {
         Map<Integer, SecondGoodsCategory> nodeMap = nodes.stream()
@@ -136,6 +170,12 @@ public class SecondGoodsCategoryServiceImpl extends ServiceImpl<SecondGoodsCateg
         return roots;
     }
 
+    /**
+     * 递归添加子节点
+     *
+     * @param parent 父节点
+     * @param nodeMap 节点映射表
+     */
     private void addChildrenRecursive(SecondGoodsCategory parent, Map<Integer, SecondGoodsCategory> nodeMap) {
         List<SecondGoodsCategory> children = nodeMap.values().stream()
                 .filter(child -> child.getParentId().equals(parent.getId()))