From e37faa68da3fab7df812bbdcfe414b0e643b7437 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 5 May 2026 11:02:05 +0800 Subject: [PATCH] =?UTF-8?q?feat(wx-security):=20Phase=201=20=E5=9F=BA?= =?UTF-8?q?=E7=A1=80=E8=AE=BE=E6=96=BD=20(PR=20#1659=20/=20Issue=20#1652)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-05/05_feat_wx-security_phase1.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 changelogs/2026-05/05_feat_wx-security_phase1.md diff --git a/changelogs/2026-05/05_feat_wx-security_phase1.md b/changelogs/2026-05/05_feat_wx-security_phase1.md new file mode 100644 index 0000000..8103a72 --- /dev/null +++ b/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 各业务服务订阅