完善注释

2026-03-12 18:18:24 +08:00
parent 2c2d31ad92
commit 9355201dda
5 changed files with 22 additions and 3 deletions
@@ -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 功能权限编码
@@ -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) {
@@ -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 树形路由菜单
@@ -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++) {
@@ -10,6 +10,10 @@ import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;

 /**
+ * 微信支付回调实现
+ * <p>依赖：WxPayNotifyMessageAbstract（common模块支付回调抽象）</p>
+ * <p>使用表：待对接商品订单表</p>
+ *
 * @author zk
 */
@Service