ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
33 lines
2.7 KiB
Markdown
33 lines
2.7 KiB
Markdown
# Common Core 模块指引
|
||
|
||
## 数据库访问与中文注释约束
|
||
|
||
- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
|
||
|
||
## 职责边界
|
||
|
||
- 提供不依赖具体业务域的返回模型、异常、基础实体和 MyBatis-Plus 通用配置。
|
||
- 不引入订单、仓库、租户等领域实体，不调用业务服务，也不承载 Controller。
|
||
|
||
## 快速索引
|
||
|
||
| 功能 | 入口 |
|
||
|---|---|
|
||
| 统一响应与分页 | `src/main/java/com/baiyue/common/core/api/ApiResponse.java`、`PageResult.java` |
|
||
| 返回码与下游 code 还原 | `src/main/java/com/baiyue/common/core/api/ResultCode.java`；成功码是字符串 `"200"`，`ResultCode.of` 的未知 code 降级为 `B0001` |
|
||
| 业务异常 | `src/main/java/com/baiyue/common/core/exception/BizException.java` |
|
||
| 通用审计字段 | `src/main/java/com/baiyue/common/core/model/BaseEntity.java` |
|
||
| MyBatis-Plus 与审计人 | `src/main/java/com/baiyue/common/core/mybatis/` |
|
||
| 有限重试与退避 | `src/main/java/com/baiyue/common/core/retry/BoundedRetryPolicy.java`；供多个服务的 Outbox 复用，不拥有持久化或投递逻辑 |
|
||
| 人工重试事务与凭据 | `src/main/java/com/baiyue/common/core/outbox/OutboxOperations.java`、`EventOperationsTokenGuard.java`；三个生产服务显式选择本库表及事件白名单，锁定 DEAD 原记录，状态恢复与审计同事务；不访问其他服务数据库或直接投递事件 |
|
||
| 逐次投递审计事务 | `src/main/java/com/baiyue/common/core/outbox/EventDeliveryJournal.java`；领取与STARTED、持有者CAS完成与审计各自同库REQUIRES_NEW事务；HTTP在两个事务之间执行，迟到结果不得写入；JDBC为optional依赖，Print等无数据库服务不被引入JDBC |
|
||
| 响应契约测试 | `src/test/java/com/baiyue/common/core/ApiResponseTest.java` |
|
||
|
||
## 修改与验证
|
||
|
||
- 公共响应、错误码或基础实体变化会影响所有服务；先检索并同步修改全部消费者、测试和契约。当前正式模型不保留旧序列化或数据库兼容分支；若已有不可变外部契约，先单独定义升级规则。
|
||
- `ApiResponse.successful()` 只认字符串 `"200"`。不得恢复旧成功码 `"0"`，也不得把 `code` 改成数字；前端和 Feign 调用方都按字符串严格判断。
|
||
- `ResultCode.httpStatus` 保留错误分类元数据，但普通业务异常的实际 HTTP 状态由 `common-web/GlobalExceptionHandler` 统一收敛为 200；真实 HTTP 状态例外见 `../docs/统一响应约定改造方案-HTTP200.md`。
|
||
- 新能力只有被多个模块稳定复用时才放入本模块。
|
||
- 从父目录运行 `mvn -pl common-core -am test`。
|