完善注释

client-api/src/main/java/org/jiayunet/service/FuncPermissionService.java

@@ -19,7 +19,9 @@ import java.time.LocalDate;
 import java.time.ZoneId;
 
 /**
- * 功能权限服务（校验、扣减、查询、添加库存、回退）
+ * 功能权限服务
+ * <p>依赖：FuncPermissionMapper、UserFuncPermissionStockMapper、UserFuncUsageLogMapper</p>
+ * <p>使用表：bg_func_permission（查询功能定义）、bg_user_func_permission_stock（库存校验与扣减）、bg_user_func_usage_log（使用记录与免费次数统计）</p>
  *
  * @author zk
  */
@@ -38,7 +40,7 @@ public class FuncPermissionService {
 
     /**
      * 校验用户功能权限并扣减库存
-     * <p>优先使用每日免费额度，免费额度用完后走付费库存</p>
+     * <p>1. 查功能权限定义 2. 判断每日免费额度是否充足 3. 免费额度用完则查付费库存 4. 校验时间维度 5. 校验次数维度并原子扣减 6. 插入使用记录</p>
      *
      * @param userId   用户ID
      * @param funcCode 功能权限编码

client-api/src/main/java/org/jiayunet/service/LoginService.java

@@ -34,6 +34,9 @@ import java.util.stream.Collectors;
 
 /**
  * 登录服务
+ * <p>依赖：SmsService（验证码发送与校验）、UserRegisterService（自动注册）</p>
+ * <p>使用表：bg_user（查询/创建用户）</p>
+ * <p>使用Redis：login:token:{userId}（登录令牌与多设备管理）</p>
  *
  * @author zk
  */
@@ -64,6 +67,7 @@ public class LoginService {
 
     /**
      * 发送短信验证码
+     * <p>1. 生成6位随机验证码 2. 委托SmsService发送</p>
      */
     public boolean sendCode(String mobileNumber) {
         Assert.hasText(mobileNumber, "手机号不能为空");
@@ -77,6 +81,7 @@ public class LoginService {
 
     /**
      * 短信验证码登录
+     * <p>1. 校验验证码 2. 查询用户，不存在则自动注册 3. 检查用户状态 4. 生成JWT 5. 构建Redis登录信息并管理多设备在线 6. 设置Cookie返回用户信息</p>
      */
     @Transactional(rollbackFor = Exception.class)
     public LoginVo smsLogin(String mobileNumber, String code, String inviteCode, HttpServletRequest request, HttpServletResponse response) {

client-api/src/main/java/org/jiayunet/service/RouteMenuService.java

@@ -17,7 +17,9 @@ import java.util.*;
 import java.util.stream.Collectors;
 
 /**
- * 路由菜单服务（查询、添加库存、获取用户菜单）
+ * 路由菜单服务
+ * <p>依赖：RouteMenuMapper、UserRouteMenuStockMapper</p>
+ * <p>使用表：bg_route_menu（查询菜单定义）、bg_user_route_menu_stock（用户菜单库存管理）</p>
  *
  * @author zk
  */
@@ -91,6 +93,7 @@ public class RouteMenuService {
 
     /**
      * 获取用户有效路由菜单（树形结构，支持多级菜单）
+     * <p>1. 查询所有启用菜单 2. 收集公开免费菜单ID 3. 查询用户有效库存合并菜单ID 4. 补充父节点 5. 转VO构建树形结构</p>
      *
      * @param userId 用户ID
      * @return 树形路由菜单

client-api/src/main/java/org/jiayunet/service/UserRegisterService.java

@@ -18,6 +18,8 @@ import java.time.Instant;
 
 /**
  * 用户注册服务
+ * <p>依赖：UserMapper（用户持久化）、UserInviteMapper（邀请记录持久化）</p>
+ * <p>使用表：bg_user（创建用户、查询邀请人）、bg_user_invite（写入邀请关系）</p>
  *
  * @author zk
  */
@@ -48,6 +50,7 @@ public class UserRegisterService {
 
     /**
      * 注册新用户
+     * <p>1. 创建用户并生成邀请码 2. 若携带邀请码则绑定邀请关系</p>
      *
      * @param mobileNumber 手机号
      * @param inviteCode   邀请码（可选）
@@ -75,6 +78,7 @@ public class UserRegisterService {
 
     /**
      * 绑定邀请关系
+     * <p>1. 根据邀请码查找邀请人 2. 校验有效性（存在且非自己） 3. 写入邀请记录</p>
      */
     private void bindInvite(User user, String inviteCode) {
         // 查找邀请人
@@ -104,6 +108,7 @@ public class UserRegisterService {
 
     /**
      * 生成10位邀请码（大写字母+数字），确保唯一
+     * <p>最多重试3次，碰撞则重新生成</p>
      */
     private String generateInviteCode() {
         for (int i = 0; i < 3; i++) {

client-api/src/main/java/org/jiayunet/service/WxPayNotifyMessageAbstractImpl.java

@@ -10,6 +10,10 @@ import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
 /**
+ * 微信支付回调实现
+ * <p>依赖：WxPayNotifyMessageAbstract（common模块支付回调抽象）</p>
+ * <p>使用表：待对接商品订单表</p>
+ *
  * @author zk
  */
 @Service