Sfoglia il codice sorgente

docs: AGENTS.md 写入「依赖注入纪律」强约束(禁止循环依赖 / @Lazy 纪律 / 静态检查)

根 AGENTS.md 与 cfc-backend/AGENTS.md 同步写入:

- 4.2.1 禁止循环依赖:禁止引入环、禁止 spring.main.allow-circular-references、
  禁止用 @Lazy 掩盖新环(抽窄接口 / 下沉 / 事件解耦三种打破手段)、
  新增 Service 注入前必须确认依赖图无环(tools/check_circular_deps.py + pre-commit 阻断)。
- 4.2.4 @Lazy 使用纪律与静态检查:@Lazy 仅在字段名与 Bean 名严格一致时使用;
  既有 30+ 条 @Lazy 设计环只登记不重构;工具退出码约定与钩子启用方式。

注:任务引用的 docs/循环依赖诊断与修复方案.md(V2) 在仓库及全部历史中不存在
(上一轮中断时未提交),该小节按任务「强约束」原文重建,未改动其它章节。
Sisyphus 3 settimane fa
parent
commit
d36a63880d
2 ha cambiato i file con 62 aggiunte e 0 eliminazioni
  1. 31 0
      AGENTS.md
  2. 31 0
      cfc-backend/AGENTS.md

+ 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`)