notice: wx 内容安全方案正式部署窗口期 BadSqlGrammar 已自愈说明

changelogs/2026-05/05_notice_wx-security-prod-deploy-window-glitch.md

@@ -0,0 +1,34 @@
+# notice: wx 内容安全方案正式部署窗口期短暂错误（已自愈）
+
+**日期**: 2026-05-05
+**影响时段**: 17:23 - 17:54（约 31 分钟，部署滚动窗口）
+**症状**: `/mp/review/featured?limit=5` 等评价相关接口偶发返 `BadSqlGrammarException`
+
+## 根因
+
+正式服部署 wx 内容安全方案 Phase 1-2E 时：
+- **17:23** 用户合并 main HEAD `e8ef4824`
+- **17:35** RDS 部分 ALTER 已落（V005 给 order_review 加 4 列：report_count / report_status / hidden_at / hidden_reason）
+- **17:43** 前端拿到 BadSqlGrammar — 老镜像 `e89f0fc1` 还活着，但其代码不知道新列的 entity 映射
+- **17:46-17:54** K8s 滚动完成，4 服务全到 `e8ef4824` → 自愈
+
+属于"schema 增量先行 + 镜像滚动后行"的行业通病窗口（5-30 min 不等）。
+
+## 现状（QA 18:06 确认）
+
+49 次双环境 API 测试全过：
+- 0 BLOCKING / 0 5xx 非业务 / 0 BadSqlGrammar
+- 11 个 wx 内容安全新路径全 OK
+- 评价/投诉/退款/反馈/举报 5 个写接口 401 鉴权链路正确
+- 边界值（limit 0/100/-1/abc / 无效 type）全过
+
+## 预防
+
+后续大版本部署建议：
+1. ALTER 增量 SQL 必保持向后兼容（新增列必须 NULL 或带 DEFAULT，禁止 NOT NULL 无默认）— 项目已是规则
+2. 删列/改类型场景必须分两次部署（先两边读写、再删列）— 本次未踩到
+3. 部署时间挑低峰期（凌晨）减少瞬时窗口暴露给真实用户
+
+## 不需修复
+
+代码层面无 BUG。本次是滚动部署的固有特征，不是回归性问题。