# 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 各业务服务订阅