Răsfoiți Sursa

Merge remote-tracking branch 'origin/fix/circular-deps' into merge/cfclub-all-20261031

Agnes Agent 2 săptămâni în urmă
părinte
comite
e8181694fb

+ 25 - 5
.githooks/pre-commit

@@ -1,13 +1,33 @@
 #!/usr/bin/env bash
-# 知识库提交前校验:暂存区含 docs/参考资料/知识库 变更时自动运行校验脚本。
+# 提交前校验:
+# 1) 知识库校验:暂存区含 docs/参考资料/知识库 变更时运行 docs/scripts/validate_kb.py
+# 2) 循环依赖校验:暂存区含 cfc-backend/ 或 tools/check_circular_deps.py 变更时运行
+#    tools/check_circular_deps.py;eager 循环依赖非空则阻断提交。
 # 阻断不合规提交(返回非 0 时 git commit 会失败),可用 git commit --no-verify 跳过。
+#
+# 启用方式:bash docs/scripts/install_git_hooks.sh(core.hooksPath -> .githooks,幂等)
 set -euo pipefail
 
 ROOT="$(git rev-parse --show-toplevel)"
 KB_DIR="docs/参考资料/知识库"
-VALIDATOR="$ROOT/docs/scripts/validate_kb.py"
+KB_VALIDATOR="$ROOT/docs/scripts/validate_kb.py"
+CIRCULAR_CHECKER="$ROOT/tools/check_circular_deps.py"
 
+PY_BIN="$(command -v python3 || command -v python || true)"
+
+# 1) 知识库校验
 if git diff --cached --name-only -- "$KB_DIR" | grep -q .; then
-  echo "[pre-commit] 检测到知识库变更,运行校验: $VALIDATOR"
-  python3 "$VALIDATOR" "$ROOT/$KB_DIR"
-fi
+  echo "[pre-commit] 检测到知识库变更,运行校验: $KB_VALIDATOR"
+  "$PY_BIN" "$KB_VALIDATOR" "$ROOT/$KB_DIR"
+fi
+
+# 2) 循环依赖强约束(eager 环非空 → 阻断提交)
+STAGED_FILES="$(git diff --cached --name-only)"
+if grep -qE '^(cfc-backend/|tools/check_circular_deps\.py$)' <<< "$STAGED_FILES"; then
+  if [ -z "$PY_BIN" ]; then
+    echo "[pre-commit] 未找到 python3/python,无法执行循环依赖检查(请先安装 Python)" >&2
+    exit 1
+  fi
+  echo "[pre-commit] 检测到后端代码变更,运行循环依赖检查: $CIRCULAR_CHECKER"
+  "$PY_BIN" "$CIRCULAR_CHECKER"
+fi

+ 1 - 0
.gitignore

@@ -67,6 +67,7 @@ worktrees/
 
 # Python
 *.py
+!tools/check_circular_deps.py
 __pycache__/
 
 # OpenCode

+ 31 - 0
AGENTS.md

@@ -371,6 +371,37 @@ cd cfc-langgraph && .venv/Scripts/python.exe -m uvicorn local_report_app:app --h
 - **DI**: `@Resource`,字段名必须与类型默认 Bean Name 一致
 - **角色控制**: 控制器内手动检查 `@RequestAttribute("role")`
 
+## 依赖注入纪律(强约束 · 违反即打回)
+
+### 4.2.1 禁止循环依赖
+
+- **禁止引入循环依赖**:任何新增或修改的 Bean 依赖边都不得形成环(`A → B → … → A`)。
+- **禁止设置 `spring.main.allow-circular-references=true`** 来掩盖环:Spring Boot 2.6+ 默认禁止循环依赖,
+  该开关已从 `cfc-backend/src/main/resources/application.yml` 移除,恢复默认禁令。
+  历史背景:曾因 `ActivationQuotaService → BasicQuotaService → MembershipService → ActivationQuotaService`
+  启动期真环被迫打开该开关;已通过把会员等级查询下沉到 `MemberLevelQueryService`(只依赖 Mapper)从设计上打破。
+- **禁止用 @Lazy 掩盖新环**,必须从设计上打破,三种手段:
+  1. **抽窄接口** —— 把宽泛的 Service 依赖替换为调用方真正需要的窄接口 / 只读查询组件;
+  2. **下沉** —— 把纯查询 / 纯计算逻辑下沉到只依赖 Mapper 的组件(如 `MemberLevelQueryService`,严禁再注入 Service,否则环只会转移);
+  3. **事件解耦** —— 用 Spring 事件 / 发布订阅替代双向直接依赖。
+- **新增 Service 注入前必须确认依赖图无环**:提交前运行 `python3 tools/check_circular_deps.py`
+  (eager 环数量必须为 0);pre-commit 钩子会在暂存区含 `cfc-backend/` 或 `tools/check_circular_deps.py`
+  变更时自动运行,eager 环非空即阻断提交。
+
+### 4.2.4 @Lazy 使用纪律与静态检查
+
+- **@Lazy 仅在字段名与 Bean 名严格一致时使用**:`@Resource` + `@Lazy` 在 Spring 4.2+ 生效;
+  字段名必须等于目标 Bean 名(默认 Bean 名 = 类名首字母小写),如
+  `@Resource private MemberLevelQueryService memberLevelQueryService;`。
+- 既有 30+ 条 @Lazy 设计环**只登记不重构**,不要清理现有 @Lazy:台账由
+  `python3 tools/check_circular_deps.py` 输出第 [2] 节(@Lazy 掩盖的设计环)与第 [3] 节(@Lazy 注入点清单)给出。
+- 新增 @Lazy 属于「掩盖环」而非「打破环」,除既有登记外按违规处理。
+- 静态检查工具:`tools/check_circular_deps.py` 解析 `cfc-backend/src/main/java` 全部 Java 的
+  `@Resource/@Autowired` 字段注入、setter 注入、构造器注入,`@Resource` 按 by-name(失败回退 by-type)、
+  其余按 by-type + 接口实现回退解析 Bean,构建依赖图并区分 eager 边与 @Lazy 边。
+  退出码:`0` = 无 eager 环;`1` = 存在 eager 环(阻断提交);`2` = 环境/路径错误。
+  启用钩子:`bash docs/scripts/install_git_hooks.sh`(幂等,`core.hooksPath -> .githooks`)。
+
 ## 时间显示规范
 
 所有页面展示时间必须统一以下两种格式,禁止使用 `toLocaleString()`、`toLocaleTimeString()` 等浏览器差异化输出:

+ 31 - 0
cfc-backend/AGENTS.md

@@ -51,6 +51,37 @@ Spring Boot 2.7.18 后端服务,MyBatis-Plus ORM,JWT 认证。
 - **Bean名冲突检查:** 新增 Controller/Service 时,确保类名不与其他包中的类重名(Spring 默认 Bean Name 为类名首字母小写)
 - **身份标识:** `userId`=登录账号(`users.id`)、`memberId`/`familyMemberId`/`currentMemberId`=家庭成员(`family_members.id`)、`childId`=遗留表(`children.id`);账号自身/交易/权限判断用 userId,成员/孩子数据(任务/健康/成长/关系/五维能量)用 memberId;`JwtInterceptor` 按 `userId+familyId` 自动反查 `currentMemberId`(始终是登录账号自己),**切换视角不改变 currentMemberId**,靠前端显式传 `memberId` 参数覆盖;新功能禁止新增 `childId` 引用(详见 `docs/architecture/userid-vs-memberid-usage-guide.md`)
 
+## 依赖注入纪律(强约束 · 违反即打回)
+
+### 4.2.1 禁止循环依赖
+
+- **禁止引入循环依赖**:任何新增或修改的 Bean 依赖边都不得形成环(`A → B → … → A`)。
+- **禁止设置 `spring.main.allow-circular-references=true`** 来掩盖环:Spring Boot 2.6+ 默认禁止循环依赖,
+  该开关已从 `src/main/resources/application.yml` 移除,恢复默认禁令。
+  历史背景:曾因 `ActivationQuotaService → BasicQuotaService → MembershipService → ActivationQuotaService`
+  启动期真环被迫打开该开关;已通过把会员等级查询下沉到 `MemberLevelQueryService`(只依赖 Mapper)从设计上打破。
+- **禁止用 @Lazy 掩盖新环**,必须从设计上打破,三种手段:
+  1. **抽窄接口** —— 把宽泛的 Service 依赖替换为调用方真正需要的窄接口 / 只读查询组件;
+  2. **下沉** —— 把纯查询 / 纯计算逻辑下沉到只依赖 Mapper 的组件(如 `MemberLevelQueryService`,严禁再注入 Service,否则环只会转移);
+  3. **事件解耦** —— 用 Spring 事件 / 发布订阅替代双向直接依赖。
+- **新增 Service 注入前必须确认依赖图无环**:提交前运行 `python3 tools/check_circular_deps.py`
+  (eager 环数量必须为 0);pre-commit 钩子会在暂存区含 `cfc-backend/` 或 `tools/check_circular_deps.py`
+  变更时自动运行,eager 环非空即阻断提交。
+
+### 4.2.4 @Lazy 使用纪律与静态检查
+
+- **@Lazy 仅在字段名与 Bean 名严格一致时使用**:`@Resource` + `@Lazy` 在 Spring 4.2+ 生效;
+  字段名必须等于目标 Bean 名(默认 Bean 名 = 类名首字母小写),如
+  `@Resource private MemberLevelQueryService memberLevelQueryService;`。
+- 既有 30+ 条 @Lazy 设计环**只登记不重构**,不要清理现有 @Lazy:台账由
+  `python3 tools/check_circular_deps.py` 输出第 [2] 节(@Lazy 掩盖的设计环)与第 [3] 节(@Lazy 注入点清单)给出。
+- 新增 @Lazy 属于「掩盖环」而非「打破环」,除既有登记外按违规处理。
+- 静态检查工具:`tools/check_circular_deps.py` 解析 `src/main/java` 全部 Java 的
+  `@Resource/@Autowired` 字段注入、setter 注入、构造器注入,`@Resource` 按 by-name(失败回退 by-type)、
+  其余按 by-type + 接口实现回退解析 Bean,构建依赖图并区分 eager 边与 @Lazy 边。
+  退出码:`0` = 无 eager 环;`1` = 存在 eager 环(阻断提交);`2` = 环境/路径错误。
+  启用钩子:`bash docs/scripts/install_git_hooks.sh`(幂等,`core.hooksPath -> .githooks`)。
+
 ## 用户模型统一口径
 
 - **能登录用户**:`family_members.userId` 非空且关联 User 有 openid(VO 层 `memberType=login`)

+ 11 - 6
cfc-backend/src/main/java/com/etotem/cfc/service/BasicQuotaService.java

@@ -57,8 +57,13 @@ public class BasicQuotaService {
     @Resource
     private UserMapper userMapper;
 
+    // 会员等级查询下沉到 MemberLevelQueryService(只依赖 Mapper):
+    // 若此处直接注入 MembershipService,会形成
+    // ActivationQuotaService → BasicQuotaService → MembershipService → ActivationQuotaService
+    // 的启动期 eager 循环依赖(曾迫使开启 spring.main.allow-circular-references)。
+    // 字段名须与 Bean 名(memberLevelQueryService)严格一致。
     @Resource
-    private MembershipService membershipService;
+    private MemberLevelQueryService memberLevelQueryService;
 
     /**
      * 按配额类型返回周期内上限(0 表示无配额限制/未知类型)
@@ -105,8 +110,8 @@ public class BasicQuotaService {
         dto.setPeriodStart(periodStart);
         dto.setPeriodEnd(periodEnd);
         // FAMILY 及以上不限次:下发 unlimited 标记,前端不展示进度条、不做剩余次数拦截
-        int userOrder = membershipService.getLevelOrder(membershipService.getMemberLevel(userId));
-        if (userOrder > membershipService.getLevelOrder("BASIC")) {
+        int userOrder = memberLevelQueryService.getLevelOrder(memberLevelQueryService.getMemberLevel(userId));
+        if (userOrder > memberLevelQueryService.getLevelOrder("BASIC")) {
             dto.setUnlimited(true);
         }
         return dto;
@@ -181,8 +186,8 @@ public class BasicQuotaService {
             result.setSuccess(true);
             return result;
         }
-        int userOrder = membershipService.getLevelOrder(membershipService.getMemberLevel(userId));
-        int basicOrder = membershipService.getLevelOrder("BASIC");
+        int userOrder = memberLevelQueryService.getLevelOrder(memberLevelQueryService.getMemberLevel(userId));
+        int basicOrder = memberLevelQueryService.getLevelOrder("BASIC");
         if (userOrder > basicOrder) {
             // FAMILY/PREMIUM/LIFETIME:不限次
             result.setSuccess(true);
@@ -275,7 +280,7 @@ public class BasicQuotaService {
         if (userId == null) {
             return false;
         }
-        String level = membershipService.getMemberLevel(userId);
+        String level = memberLevelQueryService.getMemberLevel(userId);
         if (!"BASIC".equals(level)) {
             return false;
         }

+ 143 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/MemberLevelQueryService.java

@@ -0,0 +1,143 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.entity.FamilyMembership;
+import com.etotem.cfc.entity.MembershipLevel;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.FamilyMembershipMapper;
+import com.etotem.cfc.mapper.MembershipLevelMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.Date;
+
+/**
+ * 会员等级查询服务(只读下沉层)。
+ *
+ * <p>背景:原 {@code getMemberLevel / getLevelOrder} 挂在 MembershipService 上,导致
+ * {@code ActivationQuotaService → BasicQuotaService → MembershipService → ActivationQuotaService}
+ * 三条边全为 eager 的启动期循环依赖(迫使 application.yml 打开
+ * {@code spring.main.allow-circular-references: true})。</p>
+ *
+ * <p>做法:把等级判定逻辑逐行等价下沉到本类,使 {@code BasicQuotaService} 只依赖
+ * 「只读、无状态、不依赖任何 Service」的查询组件,从设计上断开启动期真环。</p>
+ *
+ * <p><b>强约束</b>:本类只允许依赖 Mapper(UserMapper / MembershipLevelMapper /
+ * FamilyMembershipMapper),<b>严禁注入任何 Service</b>,否则循环依赖只会被转移而非消除。
+ * 新增注入前必须先跑 {@code python3 tools/check_circular_deps.py} 确认依赖图无 eager 环。</p>
+ *
+ * @see MemberLevelQueryService#getMemberLevel(Long)
+ * @see MemberLevelQueryService#getLevelOrder(String)
+ */
+@Slf4j
+@Service
+public class MemberLevelQueryService {
+
+    @Resource
+    private UserMapper userMapper;
+
+    @Resource
+    private MembershipLevelMapper levelMapper;
+
+    @Resource
+    private FamilyMembershipMapper membershipMapper;
+
+    /**
+     * 获取用户当前有效会员等级(检查有效期)。
+     * 会员身份包含两个维度:个人会员身份(users.member_level + member_expire_time)
+     * 与家庭会员身份(family_memberships 有效付费记录)。两者不一致时,取级别更高者
+     * 作为实际有效身份(级别对照 membership_levels.level_order)。
+     */
+    public String getMemberLevel(Long userId) {
+        User user = userMapper.selectById(userId);
+        if (user == null) {
+            return "FREE";
+        }
+
+        // 个人会员身份(含有效期校验)
+        String personal = user.getMemberLevel() != null ? user.getMemberLevel() : "FREE";
+        // 服务商(PROVIDER)为独立角色,不构成会员等级身份,不参与会员权益判定
+        if ("PROVIDER".equals(personal)) {
+            personal = "FREE";
+        }
+        if ("FAMILY".equals(personal) && user.getMemberExpireTime() != null) {
+            if (user.getMemberExpireTime().before(new Date())) {
+                personal = "FREE";
+            }
+        }
+
+        // 家庭会员身份(family_memberships 有效付费记录,含有效期校验)
+        String family = user.getFamilyId() != null ? getFamilyEffectiveLevel(user.getFamilyId()) : "FREE";
+
+        // 个人与家庭身份不一致时,取级别更高者
+        return resolveEffectiveLevel(personal, family);
+    }
+
+    /**
+     * 获取等级编码对应的级别数字(数字越大级别越高;PROVIDER=1 与 FREE 同级,视为非会员),未知等级回退 1(最低)
+     */
+    public int getLevelOrder(String levelCode) {
+        if (levelCode == null || levelCode.isEmpty()) {
+            return 1;
+        }
+        try {
+            MembershipLevel level = levelMapper.selectOne(
+                    new LambdaQueryWrapper<MembershipLevel>()
+                            .eq(MembershipLevel::getLevelCode, levelCode)
+                            .last("LIMIT 1"));
+            return (level != null && level.getLevelOrder() != null) ? level.getLevelOrder() : 1;
+        } catch (Exception e) {
+            return 1;
+        }
+    }
+
+    /**
+     * 获取家庭有效会员等级(按家庭维度判定,不依赖任何特定用户)
+     * @return 等级代码(FAMILY/PREMIUM/LIFETIME/FREE),无有效会员返回 FREE
+     */
+    private String getFamilyEffectiveLevel(Long familyId) {
+        if (familyId == null) return "FREE";
+        FamilyMembership active = getActiveFamilyMembership(familyId);
+        if (active != null) return active.getLevelCode();
+        return "FREE";
+    }
+
+    /**
+     * 会员判定:取个人会员身份与家庭会员身份中级别更高者作为实际有效身份。
+     * 级别对照 membership_levels.level_order(数字越大级别越高)。
+     * 级别数字相同时(如 FREE 与 BASIC 同为 1),优先非 FREE 的一侧,避免同级覆盖。
+     */
+    private String resolveEffectiveLevel(String personalLevel, String familyLevel) {
+        String personal = (personalLevel == null || personalLevel.isEmpty()) ? "FREE" : personalLevel;
+        String family = (familyLevel == null || familyLevel.isEmpty()) ? "FREE" : familyLevel;
+        int personalOrder = getLevelOrder(personal);
+        int familyOrder = getLevelOrder(family);
+        if (familyOrder > personalOrder) {
+            return family;
+        }
+        if (personalOrder > familyOrder) {
+            return personal;
+        }
+        if ("FREE".equals(personal) && !"FREE".equals(family)) {
+            return family;
+        }
+        return personal;
+    }
+
+    /**
+     * 方案B:获取家庭当前有效的付费会员记录(未过期、paymentStatus=paid)
+     * @return 有效会员记录,无则返回 null
+     */
+    private FamilyMembership getActiveFamilyMembership(Long familyId) {
+        if (familyId == null) return null;
+        return membershipMapper.selectOne(
+                new LambdaQueryWrapper<FamilyMembership>()
+                        .eq(FamilyMembership::getFamilyId, familyId)
+                        .eq(FamilyMembership::getPaymentStatus, "paid")
+                        .gt(FamilyMembership::getEndDate, new Date())
+                        .orderByDesc(FamilyMembership::getEndDate)
+                        .last("LIMIT 1"));
+    }
+}

+ 11 - 34
cfc-backend/src/main/java/com/etotem/cfc/service/MembershipService.java

@@ -83,6 +83,12 @@ public class MembershipService implements MembershipServiceInterface {
     @Resource
     private ActivationQuotaService activationQuotaService;
 
+    // 会员等级判定的唯一事实源在 MemberLevelQueryService(只依赖 Mapper);
+    // 本类仅做委托,避免 getMemberLevel/getLevelOrder 存在两套实现。
+    // 字段名须与 Bean 名(memberLevelQueryService)严格一致。
+    @Resource
+    private MemberLevelQueryService memberLevelQueryService;
+
     // ==================== 基础查询 ====================
 
     /**
@@ -1293,48 +1299,19 @@ public class MembershipService implements MembershipServiceInterface {
      * 会员身份包含两个维度:个人会员身份(users.member_level + member_expire_time)
      * 与家庭会员身份(family_memberships 有效付费记录)。两者不一致时,取级别更高者
      * 作为实际有效身份(级别对照 membership_levels.level_order)。
+     *
+     * <p>实现已下沉至 {@link MemberLevelQueryService}(唯一事实源,只依赖 Mapper,
+     * 不依赖任何 Service),本方法仅为保持调用方不变的委托入口。</p>
      */
     public String getMemberLevel(Long userId) {
-        User user = userMapper.selectById(userId);
-        if (user == null) {
-            return "FREE";
-        }
-
-        // 个人会员身份(含有效期校验)
-        String personal = user.getMemberLevel() != null ? user.getMemberLevel() : "FREE";
-        // 服务商(PROVIDER)为独立角色,不构成会员等级身份,不参与会员权益判定
-        if ("PROVIDER".equals(personal)) {
-            personal = "FREE";
-        }
-        if ("FAMILY".equals(personal) && user.getMemberExpireTime() != null) {
-            if (user.getMemberExpireTime().before(new Date())) {
-                personal = "FREE";
-            }
-        }
-
-        // 家庭会员身份(family_memberships 有效付费记录,含有效期校验)
-        String family = user.getFamilyId() != null ? getFamilyEffectiveLevel(user.getFamilyId()) : "FREE";
-
-        // 个人与家庭身份不一致时,取级别更高者
-        return resolveEffectiveLevel(personal, family);
+        return memberLevelQueryService.getMemberLevel(userId);
     }
 
     /**
      * 获取等级编码对应的级别数字(数字越大级别越高;PROVIDER=1 与 FREE 同级,视为非会员),未知等级回退 1(最低)
      */
     public int getLevelOrder(String levelCode) {
-        if (levelCode == null || levelCode.isEmpty()) {
-            return 1;
-        }
-        try {
-            MembershipLevel level = levelMapper.selectOne(
-                    new LambdaQueryWrapper<MembershipLevel>()
-                            .eq(MembershipLevel::getLevelCode, levelCode)
-                            .last("LIMIT 1"));
-            return (level != null && level.getLevelOrder() != null) ? level.getLevelOrder() : 1;
-        } catch (Exception e) {
-            return 1;
-        }
+        return memberLevelQueryService.getLevelOrder(levelCode);
     }
 
     /**

+ 0 - 3
cfc-backend/src/main/resources/application.yml

@@ -8,9 +8,6 @@ server:
       Strict-Transport-Security: max-age=31536000; includeSubDomains
 
 spring:
-  main:
-    # 最新主线多处服务字段注入存在循环依赖,启动期允许 Spring 解析(运行时仍按需调用)
-    allow-circular-references: true
   servlet:
     multipart:
       max-file-size: 50MB

+ 168 - 0
cfc-backend/src/test/java/com/etotem/cfc/service/MemberLevelQueryServiceTest.java

@@ -0,0 +1,168 @@
+package com.etotem.cfc.service;
+
+import com.etotem.cfc.entity.FamilyMembership;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.FamilyMembershipMapper;
+import com.etotem.cfc.mapper.MembershipLevelMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mock;
+import org.mockito.Mockito;
+import org.mockito.MockitoAnnotations;
+
+import java.lang.reflect.Field;
+import java.util.Date;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.when;
+
+/**
+ * MemberLevelQueryService 单元测试(纯单元测试,无 SpringBootTest,避免 MySQL 连接)。
+ *
+ * 说明:本服务由 MembershipService 下沉而来(getMemberLevel / getLevelOrder 逐行等价搬迁,
+ * 唯一事实源,只依赖 Mapper、不依赖任何 Service)。本测试覆盖搬迁前后必须逐分支等价的核心语义:
+ * <ol>
+ *   <li>PROVIDER → FREE(服务商为独立角色,不构成会员等级)</li>
+ *   <li>FAMILY 过期 → FREE(含 member_expire_time 校验)</li>
+ *   <li>个人/家庭取高(含 FREE/BASIC 同级 tie-break 优先非 FREE)</li>
+ *   <li>未知等级回退 1(level_order 缺失或空/未知 code)</li>
+ * </ol>
+ *
+ * level_code → level_order 属于配置数据而非被测逻辑,通过 spy stub getLevelOrder 提供
+ * (与生产 membership_levels 数据一致:FREE=1 BASIC=1 FAMILY=2 PROVIDER=3 PREMIUM=4 LIFETIME=5)。
+ */
+public class MemberLevelQueryServiceTest {
+
+    @Mock
+    private UserMapper userMapper;
+
+    @Mock
+    private FamilyMembershipMapper membershipMapper;
+
+    @Mock
+    private MembershipLevelMapper levelMapper;
+
+    private MemberLevelQueryService service;
+
+    @BeforeEach
+    public void setUp() {
+        MockitoAnnotations.openMocks(this);
+        MemberLevelQueryService raw = new MemberLevelQueryService();
+        setField(raw, "userMapper", userMapper);
+        setField(raw, "membershipMapper", membershipMapper);
+        setField(raw, "levelMapper", levelMapper);
+        service = Mockito.spy(raw);
+        doReturn(1).when(service).getLevelOrder("FREE");
+        doReturn(1).when(service).getLevelOrder("BASIC");
+        doReturn(2).when(service).getLevelOrder("FAMILY");
+        doReturn(3).when(service).getLevelOrder("PROVIDER");
+        doReturn(4).when(service).getLevelOrder("PREMIUM");
+        doReturn(5).when(service).getLevelOrder("LIFETIME");
+    }
+
+    private void setField(Object target, String fieldName, Object value) {
+        try {
+            Field f = target.getClass().getDeclaredField(fieldName);
+            f.setAccessible(true);
+            f.set(target, value);
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    private User user(Long id, String level, Date expire, Long familyId) {
+        User u = new User();
+        u.setId(id);
+        u.setMemberLevel(level);
+        u.setMemberExpireTime(expire);
+        u.setFamilyId(familyId);
+        return u;
+    }
+
+    private FamilyMembership activeMembership(String code) {
+        FamilyMembership fm = new FamilyMembership();
+        fm.setLevelCode(code);
+        fm.setPaymentStatus("paid");
+        fm.setEndDate(future());
+        return fm;
+    }
+
+    private Date future() {
+        return new Date(System.currentTimeMillis() + 86_400_000L);
+    }
+
+    private Date past() {
+        return new Date(System.currentTimeMillis() - 86_400_000L);
+    }
+
+    // ── 分支1:PROVIDER → FREE ──────────────────────────────────────────
+
+    @Test
+    void getMemberLevel_provider_returnsFree() {
+        // 服务商为独立角色,不构成会员等级身份;即便家庭侧有更高会员也按 FREE 参与比较
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "PROVIDER", future(), null));
+        assertEquals("FREE", service.getMemberLevel(1L));
+    }
+
+    @Test
+    void getMemberLevel_nullUser_returnsFree() {
+        when(userMapper.selectById(999L)).thenReturn(null);
+        assertEquals("FREE", service.getMemberLevel(999L));
+    }
+
+    // ── 分支2:FAMILY 过期 → FREE ────────────────────────────────────────
+
+    @Test
+    void getMemberLevel_familyExpired_returnsFree() {
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "FAMILY", past(), null));
+        assertEquals("FREE", service.getMemberLevel(1L));
+    }
+
+    // ── 分支3:个人/家庭取高 ─────────────────────────────────────────────
+
+    @Test
+    void getMemberLevel_personalHigher_thanFamily_returnsPersonal() {
+        // 个人 PREMIUM(4) > 家庭 FAMILY(2)
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "PREMIUM", future(), 10L));
+        when(membershipMapper.selectOne(any())).thenReturn(activeMembership("FAMILY"));
+        assertEquals("PREMIUM", service.getMemberLevel(1L));
+    }
+
+    @Test
+    void getMemberLevel_familyHigher_thanPersonal_returnsFamily() {
+        // 家庭 PREMIUM(4) > 个人 FREE(1)
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "FREE", null, 10L));
+        when(membershipMapper.selectOne(any())).thenReturn(activeMembership("PREMIUM"));
+        assertEquals("PREMIUM", service.getMemberLevel(1L));
+    }
+
+    @Test
+    void getMemberLevel_tieBetweenFreeAndBasic_prefersNonFree() {
+        // FREE 与 BASIC 同为 level_order=1,平级时优先非 FREE 一侧
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "FREE", null, 10L));
+        when(membershipMapper.selectOne(any())).thenReturn(activeMembership("BASIC"));
+        assertEquals("BASIC", service.getMemberLevel(1L));
+    }
+
+    @Test
+    void getMemberLevel_noFamilyRecord_usesPersonalLevel() {
+        when(userMapper.selectById(1L)).thenReturn(user(1L, "FAMILY", future(), null));
+        assertEquals("FAMILY", service.getMemberLevel(1L));
+    }
+
+    // ── 分支4:未知等级回退 1 ────────────────────────────────────────────
+
+    @Test
+    void getLevelOrder_unknownCode_fallsBackToOne() {
+        assertEquals(1, service.getLevelOrder("UNKNOWN"));
+    }
+
+    @Test
+    void getLevelOrder_nullOrEmpty_fallsBackToOne() {
+        assertEquals(1, service.getLevelOrder(null));
+        assertEquals(1, service.getLevelOrder(""));
+    }
+}

+ 17 - 0
cfc-backend/src/test/java/com/etotem/cfc/service/MembershipServiceTest.java

@@ -57,11 +57,28 @@ public class MembershipServiceTest {
     @BeforeEach
     public void setUp() {
         MockitoAnnotations.openMocks(this);
+        // 会员等级判定的唯一事实源已下沉至 MemberLevelQueryService:
+        // 用同一组 mock Mapper 装配真实的查询服务,再注入 MembershipService 的委托字段,
+        // 保持既有用例断言语义不变(getMemberLevel 走「MembershipService → MemberLevelQueryService」
+        // 委托链,spy stub 提供 level_order 配置映射,与生产 membership_levels 一致)。
+        MemberLevelQueryService query = new MemberLevelQueryService();
+        setField(query, "userMapper", userMapper);
+        setField(query, "membershipMapper", membershipMapper);
+        setField(query, "levelMapper", levelMapper);
+        query = Mockito.spy(query);
+        doReturn(1).when(query).getLevelOrder("FREE");
+        doReturn(1).when(query).getLevelOrder("BASIC");
+        doReturn(2).when(query).getLevelOrder("FAMILY");
+        doReturn(3).when(query).getLevelOrder("PROVIDER");
+        doReturn(4).when(query).getLevelOrder("PREMIUM");
+        doReturn(5).when(query).getLevelOrder("LIFETIME");
+
         MembershipService raw = new MembershipService();
         setField(raw, "userMapper", userMapper);
         setField(raw, "membershipMapper", membershipMapper);
         setField(raw, "levelMapper", levelMapper);
         setField(raw, "memberUpgradeRecordMapper", memberUpgradeRecordMapper);
+        setField(raw, "memberLevelQueryService", query);
         service = Mockito.spy(raw);
         doReturn(1).when(service).getLevelOrder("FREE");
         doReturn(1).when(service).getLevelOrder("BASIC");

+ 4 - 2
docs/scripts/install_git_hooks.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# 安装仓库级 git hooks:将 core.hooksPath 指向 .githooks/,启用提交前知识库校验。
+# 安装仓库级 git hooks:将 core.hooksPath 指向 .githooks/,启用提交前校验:
+# 1) 知识库校验(docs/参考资料/知识库 变更)
+# 2) 后端循环依赖强约束(cfc-backend/ 或 tools/check_circular_deps.py 变更,eager 环阻断)
 # 幂等,可重复执行。
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 git -C "$ROOT" config core.hooksPath .githooks
 echo "hooksPath -> $(git -C "$ROOT" config core.hooksPath)"
-echo "已启用: $ROOT/.githooks/pre-commit (知识库提交前校验)"
+echo "已启用: $ROOT/.githooks/pre-commit (知识库 + 循环依赖 提交前校验)"

+ 843 - 0
tools/check_circular_deps.py

@@ -0,0 +1,843 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+tools/check_circular_deps.py — CFC 后端 Spring 循环依赖静态检查
+
+用途
+----
+在提交前静态解析 cfc-backend/src/main/java 的全部 Java 源码,构建「Bean 依赖图」,
+区分 **eager 边**(启动期立即实例化)与 **@Lazy 边**(延迟代理,启动期不实例化),
+输出:
+
+  1. eager 循环依赖清单 —— 启动期致命,必须为空;非空时退出码 1(阻断提交)
+  2. @Lazy 掩盖的设计环台账 —— 允许存在(既有 30+ 条),仅登记不阻断
+  3. @Lazy 注入点清单 —— 供人工复核「@Lazy 仅在字段名与 Bean 名严格一致时使用」
+
+解析能力
+--------
+  * 字段注入:@Resource / @Autowired(含 @Lazy、@Qualifier、@Resource(name="..."))
+  * setter 注入:方法上的 @Autowired / @Resource
+  * 构造器注入:构造器上的 @Autowired / @Resource
+  * @Resource 按 by-name 解析(by-name 失败回退 by-type)
+  * @Autowired 按 by-type 解析;接口类型回退到「唯一实现类」
+  * Bean 识别:@Service / @Component / @Repository / @Controller / @RestController /
+    @Configuration / com.etotem.cfc.mapper 下的 Mapper 接口
+
+退出码
+------
+  0 —— 未发现 eager 循环依赖
+  1 —— 发现 eager 循环依赖(必须从设计上打破,禁止用 @Lazy 掩盖新环)
+  2 —— 脚本自身错误(源码目录不存在等)
+
+用法
+----
+  python3 tools/check_circular_deps.py
+"""
+
+import os
+import re
+import sys
+from collections import defaultdict
+
+# --------------------------------------------------------------------------- #
+# 路径与常量
+# --------------------------------------------------------------------------- #
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir))
+SRC_DIR = os.path.join(ROOT, "cfc-backend", "src", "main", "java")
+
+STEREOTYPE_SIMPLE = {"Service", "Component", "Repository", "Controller",
+                     "RestController", "Configuration"}
+MAPPER_PACKAGE_PREFIX = "com.etotem.cfc.mapper"
+
+INJECT_ANNOTATIONS = ("@Resource", "@Autowired")
+LAZY_ANNOTATION = "@Lazy"
+
+# 集合/容器注入:Spring 注入的是「多个候选」,无法归到单一 Bean 节点,解析时跳过
+COLLECTION_TYPES = {
+    "List", "Set", "Map", "Collection", "Iterable", "ArrayList", "LinkedList",
+    "HashSet", "TreeSet", "HashMap", "LinkedHashMap", "TreeMap", "Optional",
+    "ObjectProvider", "Multimap",
+}
+
+
+# --------------------------------------------------------------------------- #
+# 源码预处理
+# --------------------------------------------------------------------------- #
+
+def strip_comments(src):
+    """把注释替换为等长空格(保留换行与偏移),避免注释中的注解造成误判。"""
+    out = list(src)
+    i, n = 0, len(src)
+    state = None  # None / 'line' / 'block' / 'str' / 'char'
+    while i < n:
+        c = src[i]
+        nxt = src[i + 1] if i + 1 < n else ""
+        if state is None:
+            if c == "/" and nxt == "/":
+                state = "line"
+                out[i] = out[i + 1] = " "
+                i += 2
+                continue
+            if c == "/" and nxt == "*":
+                state = "block"
+                out[i] = out[i + 1] = " "
+                i += 2
+                continue
+            if c == '"':
+                state = "str"
+                i += 1
+                continue
+            if c == "'":
+                state = "char"
+                i += 1
+                continue
+            i += 1
+            continue
+        if state == "line":
+            if c == "\n":
+                state = None
+            else:
+                out[i] = " "
+            i += 1
+            continue
+        if state == "block":
+            if c == "*" and nxt == "/":
+                out[i] = out[i + 1] = " "
+                state = None
+                i += 2
+                continue
+            if c != "\n":
+                out[i] = " "
+            i += 1
+            continue
+        if state in ("str", "char"):
+            quote = '"' if state == "str" else "'"
+            if c == "\\":
+                i += 2
+                continue
+            if c == quote:
+                state = None
+            i += 1
+            continue
+    return "".join(out)
+
+
+def decapitalize(name):
+    """Spring 默认 Bean 名:首字母小写(前两字母均大写则保持原样)。"""
+    if not name:
+        return name
+    if len(name) > 1 and name[0].isupper() and name[1].isupper():
+        return name
+    return name[0].lower() + name[1:]
+
+
+def strip_generics(type_text):
+    """List<Foo> -> List;Map<String, Foo> -> Map"""
+    depth = 0
+    out = []
+    for ch in type_text:
+        if ch == "<":
+            depth += 1
+            continue
+        if ch == ">":
+            depth = max(0, depth - 1)
+            continue
+        if depth == 0:
+            out.append(ch)
+    return "".join(out).strip()
+
+
+def simple_type(type_text):
+    """取类型简单名(去包名、泛型、数组)"""
+    t = strip_generics(type_text).strip()
+    t = t.split(".")[-1].strip()
+    while t.endswith("[]"):
+        t = t[:-2].strip()
+    t = t.replace("...", "").strip()
+    return t
+
+
+# --------------------------------------------------------------------------- #
+# 类型声明解析
+# --------------------------------------------------------------------------- #
+
+TYPE_DECL_RE = re.compile(
+    r"(?P<prefix>[^{};]*?)\b(?P<kind>class|interface|enum)\s+(?P<name>\w+)"
+    r"(?P<rest>[^{};]*?)\{"
+)
+
+
+class TypeDecl(object):
+    __slots__ = ("name", "kind", "package", "file", "prefix", "rest", "body_start", "body_end")
+
+    def __init__(self, name, kind, package, file, prefix, rest, body_start, body_end):
+        self.name = name
+        self.kind = kind
+        self.package = package
+        self.file = file
+        self.prefix = prefix
+        self.rest = rest
+        self.body_start = body_start
+        self.body_end = body_end
+
+
+def parse_package(src):
+    m = re.search(r"^\s*package\s+([\w.]+)\s*;", src, re.M)
+    return m.group(1) if m else ""
+
+
+def parse_type_decls(src, file_path):
+    decls = []
+    package = parse_package(src)
+    for m in TYPE_DECL_RE.finditer(src):
+        prefix = m.group("prefix")
+        # 仅认列 0 开始的顶层声明(缩进声明视为方法体内的局部类/匿名类,跳过)
+        last_line = prefix.split("\n")[-1] if prefix else ""
+        if last_line[:1] in (" ", "\t"):
+            continue
+        body_start = m.end()
+        depth = 1
+        i = body_start
+        while i < len(src) and depth > 0:
+            if src[i] == "{":
+                depth += 1
+            elif src[i] == "}":
+                depth -= 1
+            i += 1
+        decls.append(TypeDecl(
+            name=m.group("name"),
+            kind=m.group("kind"),
+            package=package,
+            file=file_path,
+            prefix=prefix,
+            rest=m.group("rest"),
+            body_start=body_start,
+            body_end=i - 1,
+        ))
+    return decls
+
+
+def prefix_annotation_names(prefix):
+    """提取声明前注解块中的注解简单名(兼容全限定写法)"""
+    return [m.split(".")[-1] for m in re.findall(r"@\s*([\w.]+)", prefix)]
+
+
+def is_stereotype(prefix):
+    """类声明前的注解块里是否含 Spring stereotype 注解"""
+    return bool(STEREOTYPE_SIMPLE & set(prefix_annotation_names(prefix)))
+
+
+def stereotype_name(prefix):
+    """解析 @Service("xxx") / @Component("xxx") 显式 Bean 名"""
+    for m in re.finditer(r"@\s*([\w.]+)(?:\s*\(\s*\"([^\"]+)\"\s*\))", prefix):
+        if m.group(1).split(".")[-1] in STEREOTYPE_SIMPLE:
+            return m.group(2)
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# 注入点解析
+# --------------------------------------------------------------------------- #
+
+class InjectionPoint(object):
+    __slots__ = ("owner", "kind", "field", "type", "annotation", "lazy", "file", "line", "explicit_name")
+
+    def __init__(self, owner, kind, field, type_, annotation, lazy, file, line, explicit_name=None):
+        self.owner = owner
+        self.kind = kind            # field / setter / constructor
+        self.field = field
+        self.type = type_
+        self.annotation = annotation  # @Resource / @Autowired
+        self.lazy = lazy
+        self.file = file
+        self.line = line
+        self.explicit_name = explicit_name
+
+    def describe(self):
+        loc = "%s:%d" % (os.path.relpath(self.file, ROOT), self.line)
+        return "%s.%s  (%s %s%s) -> %s  [%s]" % (
+            self.owner, self.field, self.annotation,
+            "@Lazy " if self.lazy else "",
+            self.type, loc, self.kind)
+
+
+ANNOTATION_RE = re.compile(
+    r"\s*@\s*(?P<name>[\w.]+)(?:\s*\((?P<args>(?:[^()]|\([^()]*\))*)\))?")
+
+
+def skip_annotations(src, pos):
+    """跳过紧邻的注解块,返回 (新位置, 注解列表)"""
+    anns = []
+    while True:
+        m = ANNOTATION_RE.match(src, pos)
+        if not m:
+            break
+        anns.append((m.group("name"), m.group("args") or ""))
+        pos = m.end()
+    return pos, anns
+
+
+def find_next_token(src, pos, tokens=(";", "{", "=")):
+    """找到下一个顶层分隔符(跳过字符串/字符字面量与括号)"""
+    depth = 0
+    i = pos
+    n = len(src)
+    while i < n:
+        c = src[i]
+        if c in "\"'":
+            quote = c
+            i += 1
+            while i < n:
+                if src[i] == "\\":
+                    i += 2
+                    continue
+                if src[i] == quote:
+                    break
+                i += 1
+            i += 1
+            continue
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+        elif depth == 0 and c in tokens:
+            return c, i
+        i += 1
+    return None, n
+
+
+def parse_field_decl(text):
+    """'private Foo bar' -> ('Foo', 'bar');'private List<Foo> bars' -> ('List', 'bars')"""
+    text = text.strip()
+    if not text:
+        return None, None
+    text = re.sub(r"^(?:public|protected|private|static|final|transient|volatile)\s+", "", text)
+    text = text.strip()
+    if not text:
+        return None, None
+    # 泛型整体作为一个 token
+    m = re.match(r"^(?P<type>[\w.]+(?:\s*<.*?>)?(?:\s*\[\s*\])*)\s+(?P<name>\w+)\s*$", text, re.S)
+    if not m:
+        return None, None
+    return m.group("type"), m.group("name")
+
+
+def split_params(param_text):
+    """按顶层逗号切分参数列表"""
+    parts, buf, depth = [], [], 0
+    for ch in param_text:
+        if ch in "<([":
+            depth += 1
+        elif ch in ">)]":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append("".join(buf))
+            buf = []
+        else:
+            buf.append(ch)
+    if "".join(buf).strip():
+        parts.append("".join(buf))
+    return parts
+
+
+def parse_method_params(text):
+    """解析方法/构造器参数 -> [(type, name), ...]"""
+    idx = text.find("(")
+    if idx < 0:
+        return []
+    start = idx + 1
+    depth = 1
+    i = start
+    while i < len(text) and depth > 0:
+        if text[i] in "([{":
+            depth += 1
+        elif text[i] in ")]}":
+            depth -= 1
+        i += 1
+    inner = text[start:i - 1]
+    result = []
+    for raw in split_params(inner):
+        p = raw.strip()
+        if not p:
+            continue
+        p = re.sub(r"^(?:final|@\w+(\([^)]*\))?)\s+", "", p)
+        p = re.sub(r"^(?:public|protected|private)\s+", "", p).strip()
+        tokens = re.findall(r"[\w.]+(?:\s*<.*?>)?(?:\s*\[\s*\])?|\w+", p)
+        if not tokens:
+            continue
+        if len(tokens) == 1:
+            result.append((tokens[0], tokens[0]))
+        else:
+            result.append((" ".join(tokens[:-1]), tokens[-1]))
+    return result
+
+
+def scan_class_body(src, decl):
+    """扫描类体(顶层成员)中的注入点"""
+    points = []
+    body = src[decl.body_start:decl.body_end]
+    offset = decl.body_start
+    i = 0
+    depth = 0
+    n = len(body)
+    while i < n:
+        c = body[i]
+        if c in "\"'":
+            quote = c
+            i += 1
+            while i < n:
+                if body[i] == "\\":
+                    i += 2
+                    continue
+                if body[i] == quote:
+                    break
+                i += 1
+            i += 1
+            continue
+        if c == "{":
+            depth += 1
+            i += 1
+            continue
+        if c == "}":
+            depth -= 1
+            i += 1
+            continue
+        if depth == 0 and c == "@":
+            # 收集连续的注解块(顺序不限:@Lazy @Autowired / @Autowired @Lazy / @Resource @Lazy)
+            block_start = i
+            pos = i
+            block = []
+            while True:
+                m = ANNOTATION_RE.match(body, pos)
+                if not m:
+                    break
+                block.append((m.group("name"), m.group("args") or ""))
+                pos = m.end()
+            if not block:
+                i += 1
+                continue
+            # 注解名归一为简单名(兼容 @org.springframework.context.annotation.Lazy 等全限定写法)
+            simple_names = [a[0].split(".")[-1] for a in block]
+            inject_ann = None
+            if "Resource" in simple_names:
+                inject_ann = "Resource"
+            elif "Autowired" in simple_names:
+                inject_ann = "Autowired"
+            if inject_ann is None:
+                i = max(pos, block_start + 1)
+                continue
+            lazy = "Lazy" in simple_names
+            explicit_name = None
+            for aname, aargs in block:
+                if aname.split(".")[-1] in ("Resource", "Autowired"):
+                    mn = re.search(r"name\s*=\s*\"([^\"]+)\"", aargs or "")
+                    if mn:
+                        explicit_name = mn.group(1)
+            after = pos
+            # 找到声明
+            tok, tok_pos = find_next_token(body, after)
+            if tok is None:
+                i = after
+                continue
+            seg = body[after:tok_pos]
+            if tok in (";", "="):
+                type_text, field = parse_field_decl(seg)
+                if type_text and field:
+                    points.append(InjectionPoint(
+                        owner=decl.name, kind="field", field=field,
+                        type_=simple_type(type_text), annotation="@" + inject_ann,
+                        lazy=lazy, file=decl.file,
+                        line=src.count("\n", 0, offset + after) + 1,
+                        explicit_name=explicit_name))
+            elif tok == "{":
+                params = parse_method_params(seg)
+                is_ctor = re.search(r"\b%s\s*\(" % re.escape(decl.name), seg) is not None
+                for ptype, pname in params:
+                    if ptype.startswith("this"):
+                        continue
+                    points.append(InjectionPoint(
+                        owner=decl.name, kind="constructor" if is_ctor else "setter",
+                        field=pname, type_=simple_type(ptype), annotation="@" + inject_ann,
+                        lazy=lazy, file=decl.file,
+                        line=src.count("\n", 0, offset + after) + 1,
+                        explicit_name=explicit_name))
+            i = max(after, block_start + 1)
+            continue
+        i += 1
+    return points
+
+
+# --------------------------------------------------------------------------- #
+# Bean 注册表与依赖解析
+# --------------------------------------------------------------------------- #
+
+class Registry(object):
+    def __init__(self):
+        self.bean_by_name = {}          # bean name -> TypeDecl
+        self.classes_by_simple = defaultdict(list)   # simple name -> [TypeDecl]
+        self.interfaces = {}            # simple name -> TypeDecl(kind=interface)
+        self.implementations = defaultdict(list)     # interface simple name -> [TypeDecl]
+
+    def add(self, decl, bean_name):
+        self.bean_by_name[bean_name] = decl
+        self.classes_by_simple[decl.name].append(decl)
+        if decl.kind == "interface":
+            self.interfaces[decl.name] = decl
+
+    def link(self):
+        for decl in list(self.classes_by_simple.values()):
+            pass
+        for names in self.classes_by_simple.values():
+            for decl in names:
+                rest = decl.rest or ""
+                m = re.search(r"\bimplements\s+([^{]+)", rest)
+                if m:
+                    for iface in split_params(m.group(1)):
+                        iface = re.sub(r"<.*?>", "", iface).strip().split(".")[-1]
+                        if iface:
+                            self.implementations[iface].append(decl)
+                m2 = re.search(r"\bextends\s+([^{]+)", rest)
+                if m2 and decl.kind == "interface":
+                    for parent in split_params(m2.group(1)):
+                        parent = re.sub(r"<.*?>", "", parent).strip().split(".")[-1]
+                        if parent:
+                            self.implementations[parent].append(decl)
+
+    def resolve(self, point):
+        """返回 (目标 TypeDecl 列表, 解析方式);多实现时保守全连边(宁可多报不漏报)"""
+        if point.type in COLLECTION_TYPES:
+            return [], "collection"
+        # 1) 显式 name:@Resource(name="x") / @Autowired(name="x")
+        if point.explicit_name and point.explicit_name in self.bean_by_name:
+            return [self.bean_by_name[point.explicit_name]], "by-name(explicit)"
+        # 2) @Resource by-name:字段名 = Bean 名(本项目强约束)
+        if point.annotation == "@Resource" and point.field in self.bean_by_name:
+            return [self.bean_by_name[point.field]], "by-name"
+        # 3) by-type:类型简单名直接命中 Bean 类
+        cands = self.classes_by_simple.get(point.type, [])
+        if len(cands) == 1:
+            return cands, "by-type"
+        if len(cands) > 1:
+            return [], "ambiguous-type"
+        # 4) 接口 → 实现类
+        impls = self.implementations.get(point.type, [])
+        if len(impls) == 1:
+            return impls, "by-type(iface->impl)"
+        if len(impls) > 1:
+            primary = [d for d in impls if "@Primary" in (d.prefix or "")]
+            if len(primary) == 1:
+                return primary, "by-primary"
+            return impls, "ambiguous-iface"
+        return [], "unresolved"
+
+
+# --------------------------------------------------------------------------- #
+# 图算法
+# --------------------------------------------------------------------------- #
+
+def tarjan_scc(nodes, adj):
+    """返回 SCC 列表(迭代版 Tarjan)"""
+    index = {}
+    low = {}
+    on_stack = {}
+    stack = []
+    result = []
+    counter = [0]
+
+    for root in nodes:
+        if root in index:
+            continue
+        work = [(root, iter(adj.get(root, ())))]
+        index[root] = low[root] = counter[0]
+        counter[0] += 1
+        stack.append(root)
+        on_stack[root] = True
+        while work:
+            v, it = work[-1]
+            advanced = False
+            for w in it:
+                if w not in index:
+                    index[w] = low[w] = counter[0]
+                    counter[0] += 1
+                    stack.append(w)
+                    on_stack[w] = True
+                    work.append((w, iter(adj.get(w, ()))))
+                    advanced = True
+                    break
+                if on_stack.get(w):
+                    low[v] = min(low[v], index[w])
+            if advanced:
+                continue
+            work.pop()
+            if work:
+                u = work[-1][0]
+                low[u] = min(low[u], low[v])
+            if low[v] == index[v]:
+                comp = []
+                while True:
+                    w = stack.pop()
+                    on_stack[w] = False
+                    comp.append(w)
+                    if w == v:
+                        break
+                result.append(comp)
+    return result
+
+
+def find_cycle_within(nodes, adj):
+    """在给定节点集合内寻找一条简单环(DFS),返回路径列表"""
+    node_set = set(nodes)
+    for start in sorted(nodes):
+        stack = [(start, [start])]
+        visited = set()
+        while stack:
+            node, path = stack.pop()
+            for nxt in adj.get(node, ()):
+                if nxt == start:
+                    return path + [start]
+                if nxt in node_set and nxt not in visited:
+                    visited.add(nxt)
+                    stack.append((nxt, path + [nxt]))
+    return None
+
+
+def enumerate_cycles(nodes, adj, limit=100):
+    """枚举节点集合内的全部简单环(从环上最小节点起步,保证每环只枚举一次)"""
+    node_set = set(nodes)
+    cycles = []
+    for start in sorted(nodes):
+        if len(cycles) >= limit:
+            break
+        stack = [(start, [start])]
+        while stack:
+            if len(cycles) >= limit:
+                break
+            node, path = stack.pop()
+            for nxt in sorted(adj.get(node, ())):
+                if nxt == start:
+                    cycles.append(path + [start])
+                    if len(cycles) >= limit:
+                        break
+                elif nxt in node_set and nxt not in path and nxt >= start:
+                    stack.append((nxt, path + [nxt]))
+    return cycles
+
+
+def find_path(src, dst, adj):
+    """BFS 最短路径 src → dst(含端点),不可达返回 None"""
+    if src == dst:
+        return [src]
+    prev = {src: None}
+    queue = [src]
+    head = 0
+    while head < len(queue):
+        node = queue[head]
+        head += 1
+        for nxt in sorted(adj.get(node, ())):
+            if nxt in prev:
+                continue
+            prev[nxt] = node
+            if nxt == dst:
+                path = [dst]
+                cur = node
+                while cur is not None:
+                    path.append(cur)
+                    cur = prev[cur]
+                path.reverse()
+                return path
+            queue.append(nxt)
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# 主流程
+# --------------------------------------------------------------------------- #
+
+def collect_types():
+    registry = Registry()
+    decls = []
+    for dirpath, _dirnames, filenames in os.walk(SRC_DIR):
+        for fn in filenames:
+            if not fn.endswith(".java"):
+                continue
+            path = os.path.join(dirpath, fn)
+            with open(path, "r", encoding="utf-8", errors="replace") as fh:
+                raw = fh.read()
+            src = strip_comments(raw)
+            file_decls = parse_type_decls(src, path)
+            for d in file_decls:
+                decls.append((src, d))
+                # Mapper 接口(MyBatis-Plus 扫描 com.etotem.cfc.mapper)
+                if d.kind == "interface" and d.package.startswith(MAPPER_PACKAGE_PREFIX):
+                    registry.add(d, decapitalize(d.name))
+                elif is_stereotype(d.prefix):
+                    explicit = stereotype_name(d.prefix)
+                    registry.add(d, explicit or decapitalize(d.name))
+    registry.link()
+    return registry, decls
+
+
+def build_graph(registry, decls):
+    edges = []        # (owner, target, point)
+    skipped = 0       # 实体/POJO/无法解析(非 Bean,忽略)
+    ambiguous = []    # 接口多实现,按保守全连边(可能多报)
+    for src, decl in decls:
+        if decl.name not in registry.classes_by_simple:
+            continue
+        if len(registry.classes_by_simple[decl.name]) != 1:
+            continue
+        if not (is_stereotype(decl.prefix) or
+                (decl.kind == "interface" and decl.package.startswith(MAPPER_PACKAGE_PREFIX))):
+            continue
+        points = scan_class_body(src, decl)
+        for p in points:
+            targets, how = registry.resolve(p)
+            if not targets:
+                if how in ("ambiguous-type",):
+                    ambiguous.append((p, how))
+                else:
+                    skipped += 1
+                continue
+            if how == "ambiguous-iface":
+                ambiguous.append((p, how))
+            for t in targets:
+                edges.append((decl, t, p))
+    return edges, skipped, ambiguous
+
+
+def main():
+    if not os.path.isdir(SRC_DIR):
+        sys.stderr.write("[check_circular_deps] 源码目录不存在: %s\n" % SRC_DIR)
+        return 2
+
+    registry, decls = collect_types()
+    edges, skipped, ambiguous = build_graph(registry, decls)
+
+    # 邻接表
+    eager_adj = defaultdict(set)
+    full_adj = defaultdict(set)
+    edge_info = {}
+    for owner, target, p in edges:
+        if owner.name == target.name:
+            continue
+        kind = "lazy" if p.lazy else "eager"
+        eager_adj[owner.name].add(target.name) if kind == "eager" else None
+        full_adj[owner.name].add(target.name)
+        edge_info[(owner.name, target.name)] = (kind, p)
+
+    class_nodes = set()
+    for decls_of_same_simple_name in registry.classes_by_simple.values():
+        for decl in decls_of_same_simple_name:
+            class_nodes.add(decl.name)
+
+    # ---- 1. eager 环(全部简单环) ----
+    eager_sccs = tarjan_scc(class_nodes, eager_adj)
+    eager_cycles = []
+    for comp in eager_sccs:
+        if len(comp) > 1:
+            sub = {n: [t for t in eager_adj.get(n, ()) if t in comp] for n in comp}
+            eager_cycles.extend(enumerate_cycles(comp, sub))
+        elif comp:
+            node = comp[0]
+            if node in eager_adj.get(node, ()):
+                eager_cycles.append([node, node])
+
+    # ---- 2. @Lazy 掩盖的设计环:逐条 @Lazy 边判断是否位于某个环上 ----
+    design_cycles = []
+    seen_design = set()
+    for (u, v), (kind, _p) in sorted(edge_info.items()):
+        if kind != "lazy":
+            continue
+        path = find_path(v, u, full_adj)
+        if not path:
+            continue  # 该 @Lazy 边不在任何环上
+        cycle = [u] + path
+        key = frozenset(cycle[:-1])
+        if key in seen_design:
+            continue
+        seen_design.add(key)
+        design_cycles.append(cycle)
+
+    # ---- 3. @Lazy 注入点清单 ----
+    lazy_points = [p for (_o, _t, p) in edges if p.lazy]
+    lazy_points.sort(key=lambda p: (p.owner, p.field))
+
+    # ---- 输出 ----
+    out = []
+    out.append("=" * 72)
+    out.append("CFC 后端循环依赖静态检查 (tools/check_circular_deps.py)")
+    out.append("=" * 72)
+    out.append("源码目录      : %s" % os.path.relpath(SRC_DIR, ROOT))
+    out.append("Java 文件数   : %d" % sum(1 for _d, _f, files in os.walk(SRC_DIR) for f in files if f.endswith(".java")))
+    out.append("识别 Bean 数  : %d" % len(registry.bean_by_name))
+    out.append("注入点总数    : %d (eager %d / lazy %d)"
+               % (len(edges), len(edges) - len(lazy_points), len(lazy_points)))
+
+    out.append("[1] Eager 循环依赖(启动期致命,必须为空)")
+    if eager_cycles:
+        for i, cyc in enumerate(eager_cycles, 1):
+            out.append("  ✗ 环 %d: %s" % (i, " → ".join(cyc)))
+            for a, b in zip(cyc, cyc[1:]):
+                info = edge_info.get((a, b))
+                if info:
+                    out.append("      %s --%s--> %s" % (a, info[0], b))
+    else:
+        out.append("  ✅ 未发现 eager 循环依赖")
+    out.append("")
+
+    out.append("[2] @Lazy 掩盖的设计环台账(既有设计债,仅登记不阻断)")
+    if design_cycles:
+        for i, cyc in enumerate(design_cycles, 1):
+            lazy_edges = []
+            for a, b in zip(cyc, cyc[1:]):
+                info = edge_info.get((a, b))
+                if info and info[0] == "lazy":
+                    lazy_edges.append("%s → %s" % (a, b))
+            out.append("  • 环 %d: %s" % (i, " → ".join(cyc)))
+            if lazy_edges:
+                out.append("      @Lazy 断点: %s" % ", ".join(lazy_edges))
+    else:
+        out.append("  (无)")
+    out.append("")
+
+    out.append("[3] @Lazy 注入点清单(字段名须与 Bean 名严格一致)")
+    if lazy_points:
+        for p in lazy_points:
+            out.append("  - %s.%s  (%s %s) -> %s  [%s:%d]"
+                       % (p.owner, p.field, p.annotation,
+                          "@Lazy" if p.lazy else "", p.type,
+                          os.path.relpath(p.file, ROOT), p.line))
+    else:
+        out.append("  (无)")
+    out.append("")
+
+    if ambiguous:
+        out.append("[4] 接口多实现(按保守全连边,可能产生额外环提示):%d 条" % len(ambiguous))
+        seen = {}
+        for p, how in ambiguous:
+            key = (p.owner, p.field, p.type)
+            seen.setdefault(key, p)
+        for p in list(seen.values())[:15]:
+            out.append("  - %s.%s -> %s  (ambiguous-iface)" % (p.owner, p.field, p.type))
+    else:
+        out.append("[4] 所有注入点均唯一解析到 Bean")
+    if skipped:
+        out.append("    另有 %d 个注入点未解析(实体/POJO/容器类型,正常忽略)" % skipped)
+    out.append("")
+
+    if eager_cycles:
+        out.append("结论: ❌ 发现 %d 条 eager 循环依赖 —— 必须从设计上打破"
+                   "(抽窄接口 / 下沉 / 事件解耦),禁止用 @Lazy 掩盖新环。" % len(eager_cycles))
+        out.append("=" * 72)
+        print("\n".join(out))
+        return 1
+
+    out.append("结论: ✅ eager 环 = 0(通过)")
+    out.append("=" * 72)
+    print("\n".join(out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())