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