|
|
# 数字货币发行请求模块设计
|
|
|
|
|
|
## 目标
|
|
|
|
|
|
实现“①发送数字货币发行请求”教学页面的后端。学生携带有效的本系统 JWT 后，可以查询商业银行库存、创建并逐步处理发行申请、查看央行端接收结果。接口不区分教师与学生角色。
|
|
|
|
|
|
## 范围
|
|
|
|
|
|
本期仅覆盖页面的第 1 步：商业银行生成并发送发行请求，以及中央银行显示已接收的请求。第 2 至第 7 步（验签、业务核查、准备金扣减、数字货币生成、确权）不在本期实现范围内。
|
|
|
|
|
|
## 限界上下文与分层
|
|
|
|
|
|
扩展既有 `issuance` 限界上下文，不新增顶层模块。`IssuanceRequest` 是聚合根；库存查询是该上下文的只读查询模型。
|
|
|
|
|
|
```text
|
|
|
issuance/
|
|
|
domain/
|
|
|
model/ IssuanceRequest、IssuanceApplicationId、DenominationItem、IssuanceRequestStatus
|
|
|
repository/ IssuanceRequestRepository
|
|
|
service/ IssuanceMessageComposer、IssuanceSignatureService
|
|
|
application/
|
|
|
command/ CreateIssuanceRequestCommand、UpdateDenominationsCommand
|
|
|
query/ IssuanceInventoryQueryService、IssuanceRequestQueryService
|
|
|
service/ IssuanceRequestApplicationService
|
|
|
infrastructure/
|
|
|
persistence/ MyBatis-Plus Entity、Mapper、Repository 实现
|
|
|
crypto/ Bouncy Castle 的 SM3/SM2 实验实现
|
|
|
interfaces/
|
|
|
rest/ IssuanceRequestController、CentralBankIssuanceController
|
|
|
dto/ 请求与响应 DTO
|
|
|
```
|
|
|
|
|
|
依赖方向保持 `interfaces → application → domain`，`infrastructure` 只实现领域端口。Controller 不直接调用 Mapper。
|
|
|
|
|
|
## 聚合与状态机
|
|
|
|
|
|
`IssuanceRequest` 保存机构代码、机构标识、发行金额、面额明细、币种、时间戳、待签名原文、摘要、签名、签名密钥标识、请求报文和当前状态。
|
|
|
|
|
|
状态只能按下列顺序变化：
|
|
|
|
|
|
```text
|
|
|
DRAFT → MESSAGE_PREPARED → DIGESTED → SIGNED → PACKAGED → SENT → RECEIVED
|
|
|
```
|
|
|
|
|
|
- 只有 `DRAFT` 可修改总金额、面额明细和币种。
|
|
|
- 面额数量必须为正整数，`Σ(面额 × 数量)` 必须等于发行总金额。
|
|
|
- `prepare-message` 只允许从 `DRAFT` 执行，并冻结时间戳和待签名原文。
|
|
|
- `digest`、`sign`、`package` 只允许在前一状态执行。
|
|
|
- `send` 从 `PACKAGED` 进入 `SENT` 后，在同一事务中立即进入 `RECEIVED`，模拟中央银行已接收；重复发送返回同一请求，不生成第二笔记录。
|
|
|
- 已到达目标状态的重复按钮请求返回当前数据，不重新计算摘要或签名。
|
|
|
|
|
|
待签名原文采用固定字段顺序：
|
|
|
|
|
|
```text
|
|
|
ISSUE|{bankCode}|{organizationId}|{totalAmount}|{denominations}|{currency}|{timestamp}
|
|
|
```
|
|
|
|
|
|
`denominations` 按面额从大到小序列化为 `面额:数量`，例如 `100:400,50:100,20:200,10:50,5:80,1:100`。
|
|
|
|
|
|
## 密码学教学实现
|
|
|
|
|
|
服务端使用 Bouncy Castle 提供的 SM3 和 SM2 算法：摘要为 SM3 十六进制文本，签名算法为 `SM3withSM2`。私钥不通过接口输入或返回。
|
|
|
|
|
|
本期通过 `SigningKeyProvider` 端口提供 `sm2-key-02` 实验密钥；基础设施实现仅在服务端生成并缓存密钥对。响应只暴露 `signingKeyRef`、摘要和签名。后续第 2 步验签可替换为配置化或密钥库实现，不改变聚合和接口契约。
|
|
|
|
|
|
## 数据模型
|
|
|
|
|
|
基础初始化脚本 `src/main/resources/schema.sql` 增加以下幂等表和演示数据：
|
|
|
|
|
|
| 表 | 关键字段 | 用途 |
|
|
|
| --- | --- | --- |
|
|
|
| `issuance_bank_inventory` | `bank_code`、`current_balance`、`warning_threshold` | 查询库存、预警阈值和建议补充金额。预置 `BKCHCNBJ00001`。 |
|
|
|
| `issuance_request` | `id`、`request_no`、`bank_code`、`organization_id`、`total_amount`、`currency`、`request_timestamp`、`message_text`、`digest`、`signature`、`signing_key_ref`、`payload_json`、`status`、审计字段 | 发行申请聚合持久化。 |
|
|
|
| `issuance_request_denomination` | `request_id`、`denomination`、`quantity` | 发行请求的面额明细，`request_id + denomination` 唯一。 |
|
|
|
|
|
|
建议补充金额始终计算为 `max(warning_threshold - current_balance, 0)`，不单独持久化。
|
|
|
|
|
|
## REST 接口
|
|
|
|
|
|
所有接口均以 `/api/v1/issuance` 开头，要求有效 JWT，不添加角色限定。
|
|
|
|
|
|
| 方法与路径 | 作用 |
|
|
|
| --- | --- |
|
|
|
| `GET /inventory?bankCode=BKCHCNBJ00001` | 返回库存余额、预警阈值、建议补充金额。 |
|
|
|
| `POST /requests` | 创建 `DRAFT` 发行申请，返回申请 ID 与基础数据。 |
|
|
|
| `PUT /requests/{id}` | 仅在 `DRAFT` 更新金额、面额明细和币种。 |
|
|
|
| `GET /requests/{id}` | 返回商业银行端完整申请与处理产物。 |
|
|
|
| `POST /requests/{id}/prepare-message` | 冻结时间戳并生成待签名原文。 |
|
|
|
| `POST /requests/{id}/digest` | 对待签名原文生成 SM3 摘要。 |
|
|
|
| `POST /requests/{id}/sign` | 使用 `sm2-key-02` 生成 SM2 签名。 |
|
|
|
| `POST /requests/{id}/package` | 生成包含请求号、机构、金额、面额、币种、时间戳、摘要和签名的 JSON 报文。 |
|
|
|
| `POST /requests/{id}/send` | 模拟发送至中央银行并返回 `RECEIVED`。 |
|
|
|
| `GET /central-bank/requests/{id}` | 返回中央银行端接收状态和 JSON 报文。 |
|
|
|
|
|
|
不存在的申请返回 `RESOURCE_NOT_FOUND`；状态不合法或金额校验不通过返回 `VALIDATION_ERROR`；未认证请求沿用既有 Spring Security 的 `UNAUTHORIZED` 响应。
|
|
|
|
|
|
## 测试标准
|
|
|
|
|
|
- 领域单元测试覆盖金额守恒、非法状态流转和重复发送幂等性。
|
|
|
- 应用/持久化测试覆盖库存建议金额、请求与面额明细的保存和读取。
|
|
|
- `MockMvc` 测试覆盖学生有效 JWT 下的所有首期接口，以及未认证被拒绝。
|
|
|
- 密码学测试校验 SM3 输出长度和 SM2 签名可由同一实验公钥验证。
|
|
|
- 全量 Maven 测试在 JDK 8 下通过；以 `dev` profile 启动后，Swagger 页面可访问。
|
|
|
|
|
|
## 明确约束
|
|
|
|
|
|
- 使用 JDK 8、Spring Boot 2.7.18、MyBatis-Plus 3.5.17、Spring Security 5.7。
|
|
|
- 不恢复 Flyway；所有基础表变化同步更新幂等 `schema.sql` 并在 118 测试库验证。
|
|
|
- 不在日志、接口响应或数据库中保存私钥明文。
|
|
|
- 不实现真实央行网络调用、准备金扣减或数字货币生成。
|