From 7f8e56bd1e42049591a2966e31e60bae7aa3f894 Mon Sep 17 00:00:00 2001 From: chenyuan Date: Mon, 3 Aug 2026 20:41:06 +0800 Subject: [PATCH] docs: define Chinese Swagger requirements for issuance --- .../specs/2026-08-03-issuance-request-design.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/superpowers/specs/2026-08-03-issuance-request-design.md b/docs/superpowers/specs/2026-08-03-issuance-request-design.md index d930788..0fa509e 100644 --- a/docs/superpowers/specs/2026-08-03-issuance-request-design.md +++ b/docs/superpowers/specs/2026-08-03-issuance-request-design.md @@ -100,6 +100,15 @@ ISSUE|{bankCode}|{organizationId}|{totalAmount}|{denominations}|{currency}|{time 不存在的申请返回 `RESOURCE_NOT_FOUND`；状态不合法或金额校验不通过返回 `VALIDATION_ERROR`；未认证请求沿用既有 Spring Security 的 `UNAUTHORIZED` 响应。 +## Swagger 文档 + +Swagger 页面使用中文，所有新增 Java 源文件和 OpenAPI 元数据以 UTF-8 保存，页面不允许出现乱码。发行域接口按以下中文标签分组： + +- `数字货币发行模块 - 商业银行端`：库存查询、创建申请、更新申请、生成原文、摘要、签名、封装和发送。 +- `数字货币发行模块 - 中央银行端`：查询发行请求接收状态、接收时间和请求报文。 + +每个接口通过中文 `summary` 和 `description` 明确说明所属模块、所属端、调用条件、状态变化及返回内容；请求字段和响应字段使用中文 `@Schema` 描述。OpenAPI 根标题固定为“数字人民币教学仿真后端”，接口分组和接口说明不得使用英文替代中文。 + ## 测试标准 - 领域单元测试覆盖金额守恒、非法状态流转和重复发送幂等性。 @@ -107,6 +116,7 @@ ISSUE|{bankCode}|{organizationId}|{totalAmount}|{denominations}|{currency}|{time - `MockMvc` 测试覆盖学生有效 JWT 下的所有首期接口，以及未认证被拒绝。 - 密码学测试校验 SM3 输出长度和 SM2 签名可由同一实验公钥验证。 - 全量 Maven 测试在 JDK 8 下通过；以 `dev` profile 启动后，Swagger 页面可访问。 +- 访问 `/v3/api-docs` 和 Swagger UI，确认“数字货币发行模块 - 商业银行端”“数字货币发行模块 - 中央银行端”标签及中文说明可正常显示，不含乱码字符。 ## 明确约束