From adf37c7f4b6ad51f13238522be776e1d436d1b0e Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 22 Mar 2026 21:20:30 +0800
Subject: [PATCH] =?UTF-8?q?changelog:=20API=E5=AE=89=E5=85=A8=E6=A0=A1?=
 =?UTF-8?q?=E9=AA=8C=E5=8A=A0=E5=9B=BA=E9=80=9A=E7=9F=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

全部16个微服务输入校验加固，不影响正常业务流程。
详见 changelogs/2026-03/2026-03-22_api_security_hardening.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../2026-03-22_api_security_hardening.md      | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 changelogs/2026-03/2026-03-22_api_security_hardening.md

diff --git a/changelogs/2026-03/2026-03-22_api_security_hardening.md b/changelogs/2026-03/2026-03-22_api_security_hardening.md
new file mode 100644
index 0000000..5b83de7
--- /dev/null
+++ b/changelogs/2026-03/2026-03-22_api_security_hardening.md
@@ -0,0 +1,87 @@
+# API 安全校验加固
+
+**日期**: 2026-03-22
+**影响范围**: 全部 16 个微服务
+**类型**: 安全加固（纯后端，不影响正常业务流程）
+
+---
+
+## 对前端的影响
+
+### 核心结论：正常使用不受影响
+
+本次改动只增加了输入校验，**不改变任何接口路径、参数名、响应格式**。只要前端传入的数据在合理范围内（正常业务操作都是），完全不受影响。
+
+### 可能触发 400 错误的场景（之前不会报错，现在会）
+
+以下情况会返回 `400 Bad Request`，附带具体的校验错误信息：
+
+#### 1. 字符串超长
+所有 DTO 的字符串字段现在有长度限制：
+- 名称类字段：最长 50-100 字符
+- 描述/备注：最长 500-2000 字符
+- 富文本内容：最长 10000-100000 字符
+- URL 字段：最长 500-1000 字符
+
+**前端建议**：如果有 `<textarea>` 或富文本编辑器，建议前端也加上 `maxlength` 限制，避免用户输入超长内容后提交失败。
+
+#### 2. 数值范围
+- 所有金额字段：不允许负数（`@DecimalMin("0")`）
+- 分页 `pageSize`：最大 100（超过自动截断为 100）
+- 评分 `rating`：必须 1-5
+- 人数字段：`adultCount >= 1`，`childCount >= 0`
+
+#### 3. 列表数量限制
+- 出行人 `travelers`：最多 50 人
+- 图片列表 `images`：最多 9-20 张
+- 视频列表 `videos`：最多 3 个
+- 标签列表 `tags`：最多 20-50 个
+
+#### 4. 枚举字段格式
+以下字段现在必须严格匹配指定值：
+- `refundType`：只能是 `FULL` 或 `PARTIAL`
+- `action`（退款审核）：只能是 `APPROVE` 或 `REJECT`
+- `sortDir`：只能是 `asc` 或 `desc`
+
+#### 5. 小程序端 DTO 校验
+所有小程序 API（`/mp/**`）现在启用了 `@Valid` 校验：
+- `phone`：必须匹配 `^1\d{10}$`（11位手机号）
+- `code`（登录码）：不能为空
+- `content`（评价/反馈）：不能为空，最长 2000-5000 字
+
+---
+
+## 不影响前端的后端内部加固
+
+以下改动完全在后端内部，前端无感知：
+
+| 加固项 | 说明 |
+|--------|------|
+| 退款并发锁 | Redis 分布式锁防止重复退款 |
+| 法大大回调签名验证 | HMAC-SHA256 签名校验 |
+| 资源状态修改角色校验 | 仅 SUPER_ADMIN 可直接改状态 |
+| 定时任务 Bean 白名单 | 防止执行非授权代码 |
+| 文件预览 XSS 防护 | OSS 域名白名单 + HTML 转义 |
+| 限流器 IP 防伪造 | 优先使用 X-Real-IP |
+| 2FA 端点限流 | 5次/分钟/IP |
+| 退款/支付角色校验 | 需要 ADMIN/SUPER_ADMIN/FINANCE 角色 |
+| 折扣上限 | 折扣不能等于总价（防 100% 免单） |
+| 支付幂等 | Redis 防重复提交 |
+| 公式引擎沙箱 | 关键词黑名单 + 循环上限 |
+
+---
+
+## 400 错误响应格式
+
+校验失败时返回格式不变：
+```json
+{
+  "code": 400,
+  "message": "参数校验失败",
+  "data": {
+    "fieldName": "具体的错误提示（中文）"
+  }
+}
+```
+
+**前端建议**：如果尚未统一处理 400 错误，建议在请求拦截器中对 400 状态码做 toast 提示，展示 `data` 中的第一条错误信息。