|
|
# 数字人民币教学仿真后端开发规范
|
|
|
|
|
|
本文档是本项目新增模块、接口和数据表时的统一约定。目标是在业务持续扩展时保持领域边界清晰、认证安全、数据可演进。
|
|
|
|
|
|
## 运行时版本
|
|
|
|
|
|
项目运行与构建统一使用 JDK 8，框架基线为 Spring Boot 2.7.18、Spring Security 5.7、MyBatis-Plus 3.5.17 和 Springdoc 1.8.0。新增代码不得使用 Java 9 及以上的语言特性或标准库 API；Servlet 与 Bean Validation 使用 `javax.*` 包。
|
|
|
|
|
|
## 1. 架构总览
|
|
|
|
|
|
项目采用 DDD 的“按限界上下文分包”方式。一个顶层模块代表一个业务能力，而不是一个技术层。
|
|
|
|
|
|
```mermaid
|
|
|
flowchart LR
|
|
|
Client[前端 / 调用方] --> API[interfaces 接口层]
|
|
|
API --> App[application 应用层]
|
|
|
App --> Domain[domain 领域层]
|
|
|
App --> Infra[infrastructure 基础设施层]
|
|
|
Infra --> DB[(本系统 MySQL)]
|
|
|
PI[platformintegration 防腐层] --> Platform[(主平台 / CAS)]
|
|
|
API --> Security[security 认证上下文]
|
|
|
Security --> DB
|
|
|
```
|
|
|
|
|
|
当前限界上下文如下：
|
|
|
|
|
|
| 模块 | 职责 | 禁止承担的职责 |
|
|
|
| --- | --- | --- |
|
|
|
| `issuance` | 数字人民币发行相关业务域；当前仅有领域 ID 示例 | 用户认证、主平台 Token 解析 |
|
|
|
| `identity` | 教师/学生身份快照、角色投影与同步 | 提供用户、角色 CRUD |
|
|
|
| `security` | 本系统 JWT、登录、会话兑换、刷新令牌与退出 | 业务领域规则、主平台协议解析 |
|
|
|
| `platformintegration` | 主平台 Token、CAS 和主平台只读查询的防腐适配 | 业务数据落库、业务接口 |
|
|
|
| `shared` | 仅放跨模块通用能力：响应体、异常、审计、基础配置 | 具体业务实体、业务 Service |
|
|
|
|
|
|
## 2. 新模块必须新建顶层文件夹
|
|
|
|
|
|
新增一个独立业务能力时，必须在 `src/main/java/com/yau/digitalrmb/` 下创建新的顶层模块目录。例如钱包、账单或课程场景应分别创建：
|
|
|
|
|
|
```text
|
|
|
wallet/
|
|
|
ledger/
|
|
|
course/
|
|
|
```
|
|
|
|
|
|
不要把新业务类直接放入 `shared`、`security`、`identity` 或根包。只有确实属于这些既有上下文的功能，才允许扩展其目录。
|
|
|
|
|
|
每个新模块默认使用以下目录结构；没有内容的目录不要提前创建：
|
|
|
|
|
|
```text
|
|
|
<module>/
|
|
|
├── domain/
|
|
|
│ ├── model/ # 聚合、实体、值对象、枚举、领域事件
|
|
|
│ ├── service/ # 无法归属单个聚合的纯领域服务
|
|
|
│ └── repository/ # 仓储接口（端口），不含 MyBatis 实现
|
|
|
├── application/
|
|
|
│ ├── command/ # 写操作命令及处理器
|
|
|
│ ├── query/ # 查询模型与查询服务
|
|
|
│ └── service/ # 用例编排、事务边界
|
|
|
├── infrastructure/
|
|
|
│ ├── persistence/
|
|
|
│ │ ├── entity/ # MyBatis-Plus 持久化实体
|
|
|
│ │ ├── mapper/ # Mapper 接口与 XML（如需要）
|
|
|
│ │ └── repository/ # 仓储接口的实现
|
|
|
│ └── client/ # 外部 HTTP、消息或文件系统适配器
|
|
|
└── interfaces/
|
|
|
├── rest/ # Controller
|
|
|
└── dto/ # 请求/响应 DTO
|
|
|
```
|
|
|
|
|
|
简单只读查询可以不创建完整聚合，但 Controller 仍不得直接调用 Mapper；应由 `application.query` 中的查询服务负责。
|
|
|
|
|
|
## 3. 分层与依赖方向
|
|
|
|
|
|
依赖只允许由外向内：
|
|
|
|
|
|
```text
|
|
|
interfaces → application → domain
|
|
|
infrastructure → domain / application 定义的端口
|
|
|
```
|
|
|
|
|
|
具体规则：
|
|
|
|
|
|
- `domain` 不依赖 Spring、MyBatis-Plus、Controller、数据库实体或 HTTP DTO。
|
|
|
- `application` 负责一个用例的编排、权限检查和事务边界；不编写 SQL，不返回 MyBatis 实体。
|
|
|
- `infrastructure` 实现数据库和外部系统适配；Mapper 只能被本模块的仓储实现或查询服务使用。
|
|
|
- `interfaces` 只负责参数校验、调用应用服务、转换 DTO；不得包含业务规则。
|
|
|
- 跨模块访问优先通过对方暴露的应用服务、领域事件或端口；禁止直接引用对方的 Mapper/Entity。
|
|
|
- `shared` 仅接收至少两个模块真实复用且不携带业务语义的代码。不要把“暂时不知道放哪里”的类放入 `shared`。
|
|
|
|
|
|
## 4. 领域建模规则
|
|
|
|
|
|
- 每个写模型先确定聚合根和不变量；一次事务只修改一个聚合。
|
|
|
- 用值对象表达金额、账户号、申请编号、状态等有业务含义的概念，避免在 Service 中散落 `String`、`BigDecimal` 和状态码。
|
|
|
- 聚合 ID 使用独立类型，例如现有的 `IssuanceApplicationId`；接口层和持久化层再做转换。
|
|
|
- 状态流转由聚合方法表达，例如 `approve()`、`reject()`；不要在 Controller 或 Mapper 中直接改状态字段。
|
|
|
- 需要跨聚合通知时发布 `shared.domain.DomainEvent`，由应用层或基础设施层处理副作用。
|
|
|
|
|
|
## 5. 数据库与初始化脚本规范
|
|
|
|
|
|
- 基础表结构和内置数据维护在 `src/main/resources/schema.sql`，脚本必须可重复执行，建表使用 `IF NOT EXISTS`，内置数据使用幂等写法。
|
|
|
- 新增或修改表结构时，先在测试库执行并验证，再同步更新 `schema.sql`；不得依赖 Flyway 或保留 `flyway_schema_history`。
|
|
|
- 表名、字段名使用 `snake_case`；Java 字段使用 `camelCase`，通过 MyBatis-Plus 显式映射差异字段。
|
|
|
- 新业务表必须有主键、必要索引，以及 `created_at`、`updated_at`、`created_by`、`updated_by`、`deleted` 审计字段；可继承 `AuditableEntity`。
|
|
|
- 金额使用 `DECIMAL`，禁止使用 `float`/`double`；时间使用 `TIMESTAMP`，统一以 UTC 语义处理。
|
|
|
- 身份、角色和用户角色仅能由内部投影或初始化脚本写入；不得新增对外 CRUD 接口。
|
|
|
- 禁止将密码、Token、验证码或敏感凭据写入业务表、日志、初始化脚本或测试快照。
|
|
|
|
|
|
## 6. API 与异常规范
|
|
|
|
|
|
- REST Controller 放在 `<module>.interfaces.rest`，路径统一以 `/api/v1/` 开头。
|
|
|
- 请求 DTO 使用 `javax.validation` 注解；Controller 参数标注 `@Valid`。
|
|
|
- 对外成功响应统一使用 `ApiResponse<T>`，不要自行定义不一致的响应包装格式。
|
|
|
- 可预期业务错误抛出 `BusinessException` 并使用 `ErrorCode`；不要在 Controller 中 `try/catch` 后吞掉异常。
|
|
|
- 接口响应只返回 DTO，不返回 MyBatis Entity、密码哈希、刷新令牌摘要或主平台 Token。
|
|
|
- 新接口需补充 Springdoc 注解与说明，确保 Swagger 可读；不在 Swagger 暴露用户、角色或用户角色管理接口。
|
|
|
|
|
|
## 7. 认证与权限规范
|
|
|
|
|
|
- 所有新业务接口默认需要本系统 JWT；只有登录、CAS 回调和必要健康检查可以匿名。
|
|
|
- 当前用户从 Spring Security 的 `Jwt`/`Authentication` 获取，业务模块不得解析主平台 Token。
|
|
|
- 角色只允许 `TEACHER`、`STUDENT`；权限判断放在应用层或 Spring Security 配置中，不能由前端传入角色决定。
|
|
|
- `platformintegration` 是唯一可以处理主平台 Token、CAS Ticket 和主平台只读数据源的模块。
|
|
|
- 主平台连接只授予 `SELECT`；本系统 MySQL 使用主数据源，主平台只读数据源不得被初始化脚本或业务写操作复用。
|
|
|
|
|
|
## 8. 测试与提交规范
|
|
|
|
|
|
- 新领域规则写单元测试；新增接口至少写 `MockMvc` 集成测试；新增表结构需覆盖启动初始化和关键读写。
|
|
|
- 修复缺陷先增加可复现的失败测试，再实现修复。
|
|
|
- 提交前至少运行：
|
|
|
|
|
|
```powershell
|
|
|
mvn test -DforkCount=0 -B
|
|
|
mvn package -DskipTests -B
|
|
|
```
|
|
|
|
|
|
- 提交信息采用 `<type>: <英文简述>`，例如 `feat: add wallet transfer aggregate`、`fix: prevent duplicate issuance`、`docs: add module development guide`。
|
|
|
- 一个提交只做一类明确变更；不要混入格式化、无关重构或本地配置文件。
|
|
|
|
|
|
## 9. 新模块自检清单
|
|
|
|
|
|
- [ ] 已创建新的顶层模块目录，而非把业务代码放入 `shared`。
|
|
|
- [ ] 已区分 `domain`、`application`、`infrastructure`、`interfaces` 职责。
|
|
|
- [ ] Controller 未直接调用 Mapper，且未返回持久化实体。
|
|
|
- [ ] 新增数据库变化已同步到测试库和 `schema.sql`。
|
|
|
- [ ] 接口已校验参数、统一响应，并补充 Swagger 说明。
|
|
|
- [ ] 未记录或返回密码、Token、验证码等敏感信息。
|
|
|
- [ ] 已补齐单元/集成测试并通过 Maven 验证。
|