From 5845fb1dc4610ad0556e08721895dab115b9e048 Mon Sep 17 00:00:00 2001
From: chenyuan <chenyuan@example.com>
Date: Tue, 4 Aug 2026 14:19:13 +0800
Subject: [PATCH] docs: define Chinese API message rules

---
 ...2026-08-04-api-messages-encoding-design.md | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-04-api-messages-encoding-design.md

diff --git a/docs/superpowers/specs/2026-08-04-api-messages-encoding-design.md b/docs/superpowers/specs/2026-08-04-api-messages-encoding-design.md
new file mode 100644
index 0000000..e182ba1
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-04-api-messages-encoding-design.md
@@ -0,0 +1,30 @@
+# 后端中文提示与 UTF-8 响应设计
+
+## 目标
+
+所有面向前端的 API 提示使用中文，并确保 JSON 响应始终采用 UTF-8 编码，避免 Swagger 和前端出现乱码。
+
+## 范围
+
+- 成功响应提示。
+- 未登录、无权限和平台凭据异常提示。
+- 发行申请、面额结构等业务校验提示。
+- 参数校验和未处理异常的对外提示。
+- Swagger 中由后端发布的中文标题与说明。
+
+错误码保持现有枚举值不变；前端根据 `code` 的既有逻辑无需调整。
+
+## 设计
+
+1. `ApiResponse` 的成功消息改为“操作成功”。
+2. 安全异常响应明确设置 `application/json;charset=UTF-8`，并使用“未登录或登录已失效”“无访问权限”等中文消息。
+3. 业务服务中会回传给前端的英文校验信息改为中文，例如“各面额小计之和必须等于申请总金额”。
+4. 全局参数校验不直接返回框架产生的英文异常文本，改为统一的中文提示；保留业务校验的具体中文原因。
+5. 应用配置强制 Web 响应编码为 UTF-8。
+
+## 验证
+
+- 单元测试校验 OpenAPI 和 API 响应使用 UTF-8。
+- 接口测试校验典型面额校验失败返回中文提示。
+- 接口测试校验无 Token、无权限时返回中文提示。
+- 执行完整 Maven 测试，并在本地 Swagger 中验证响应头和响应体。