feat(wx-security): Phase 1 基础设施 (PR #1659 / Issue #1652)

changelogs/2026-05/05_feat_wx-security_phase1.md

@@ -0,0 +1,67 @@
+# feat(wx-security): 微信小程序内容安全 API Phase 1 基础设施
+
+**PR**: [#1659](https://git.1814.love:8443/wx/HL/pulls/1659) **Issue**: [#1652](https://git.1814.love:8443/wx/HL/issues/1652) **合并**: 2026-05-05
+
+## 接入背景
+
+按官方契约 `content-security-contract` SYNC 2026-05-05，小程序上线前必须接入微信内容安全 API（`msgSecCheck` / `mediaCheckAsync`），否则审核驳回。
+
+## 新增接口（mp 端，前端直接调）
+
+### `POST /mp/security/text-check` 文本同步机审
+- 入参：`{content: string≤2500字, scene: 1=资料/2=评论/3=论坛/4=社交日志}`
+- 出参：`{pass, suggest: pass/review/risky/pass-degraded, label: Integer, traceId, degraded, detail}`
+- 前端按 `suggest` 决定拦截：`pass`→放行，`review/risky`→toast+阻断，`pass-degraded`→降级放行（微信侧 5xx）
+- openid 后端从登录态 `request.attribute("openid")` 拿，**不接受前端传**
+
+### `POST /mp/security/media-check` 媒体异步机审
+- 入参：`{mediaUrl: https URL, mediaType: "image"|"audio"}`
+- 出参：`{traceId}`（降级时 null）
+- 业务表 `media_trace_ids` JSON 列保存 traceId 数组，webhook 回调反查更新 audit_status
+
+### `POST/GET /mp/security/webhook` 微信平台异步回调
+- GET：URL 配置时 echostr 验证（SHA1 签名）
+- POST：异步审核结果回调，三态映射 `pass→APPROVED`/`review→MANUAL_REVIEW`/`risky→REJECTED`，发 MQ `wx-content-audit-result` 广播
+- 微信约定返回 `"success"` 字符串（验签失败抛 BusinessException → HTTP 200 + Result(code=230705)，微信重试 ≤3 次后放弃）
+- **Phase 1 仅支持明文模式**（公众平台后台需选「明文」），AES Phase 2 扩展
+
+## 业务表 schema 增量
+
+| 表 | 新增字段 |
+|---|---|
+| `wx_media_check_record` (新建) | trace_id PK + openid + media_url + media_type + suggest + label INT + status + callback_at |
+| `traveler` | audit_status + audit_label + audit_at |
+| `user` | nickname_audit_status + avatar_audit_status + avatar_trace_id |
+| `order_review` / `order_complaint` / `refund_application` | audit_status + media_trace_ids |
+| `order_invoice` | audit_status |
+
+迁移 SQL：`hl-user-service/src/main/resources/db/migration/V20260505_001__create_wx_media_check_record.sql` + `V20260505_002__add_audit_status_to_ugc_tables.sql`
+
+## MQ topic
+
+`wx-content-audit-result` + `WxContentAuditResultEvent` DTO（traceId/suggest/label/status/calledBackAt）— Phase 2 各业务服务订阅自身关心的 trace_id 反查更新业务表 audit_status。
+
+## 网关路由
+
+`/mp/security/**` → `lb://hl-user-service`，`webhook` 在 `WebMvcConfig` 排除 TokenInterceptor（无鉴权）。
+
+## 待用户配置（小程序上线前）
+
+1. 微信公众平台 → 小程序后台 → 开通「内容安全」接口权限
+2. 开发设置 → 服务器配置：URL=`https://api.test.1814.love:9443/mp/security/webhook` + Token + 选「明文模式」
+3. nacos `hl-user-{dev,prod}.yml` 填 `wechat.miniapp.webhook.token`
+
+## 前端契约要点（影响 mmg）
+
+- `WxSecCheckResult.label` 是 **Integer**（不是 String，前端可严格相等比较 `=== 100`）
+- `suggest` 五态：`pass` / `review` / `risky` / `pass-degraded`，前端按值拦截
+- `mediaTraceIds` 字段在评价/投诉/申诉等 UGC 业务 API body 中传 String 数组（Phase 2 业务接入后生效）
+- 公开列表会过滤 `audit_status='APPROVED'`（Phase 2 接入），用户自己的列表返全状态供前端展示状态条文案
+
+## Phase 2 范围（独立 PR）
+
+- 19 个 UGC 业务 API 接 mediaTraceIds 入库 + 公开列表 audit_status 过滤
+- 评价举报子系统（`POST /mp/review/report` + 阈值 3/10 触发）
+- 出行人三层兜底（异步审 + 选用挡 REJECTED + 本地正则）
+- hl-admin 后台：人工复审队列 + 命中日志 + 白名单/黑名单 + 举报队列
+- WxContentAuditResultEvent MQ Consumer 各业务服务订阅