wx/hl-api-changelog

派生 0

API Changelog Bot 60399e96db frontend(mmg): wx 内容安全方案前端集成指南 (Phase 1-2E 全链路 5 PR + Hotfix #1670 )

2026-05-05 18:01:05 +08:00

9.0 KiB

原始文件 Blame 文件历史

frontend(mmg): 微信内容安全方案 — 前端集成指南

关联 PR: #1659 #1661 #1667 #1666 #1668 #1669（全 5 Phase 已合 dev）日期: 2026-05-05 对接人: mmg

后端方案已全链路闭环，前端需要按本指南接入新接口 + 调整 body/响应字段。本指南是 5 个 Phase 的整合视图，不需要去翻散落的 changelog。

一、新增接口（前端直接调）

1. `POST /mp/security/text-check` 文本同步机审

提交评价/投诉/反馈/姓名修改等含用户输入文本的业务前，先调本接口拿审核结果决定是否拦截。

请求:

http.post('/mp/security/text-check', {
  content: "用户提交的文本内容",   // 必填,≤2500 字
  scene: 2                          // 必填:1=资料/2=评论/3=论坛/4=社交日志
})

响应:

{
  "code": 200,
  "data": {
    "pass": true,
    "suggest": "pass",     // pass / review / risky / pass-degraded
    "label": 100,          // Integer 类型，100=正常
    "traceId": "xxx",
    "degraded": false,
    "detail": null         // 命中时是关键词摘要字符串
  }
}

前端拦截规则:

pass=true 或 suggest=pass → 放行
suggest=review → toast「内容疑似违规,请修改后重试」+ 阻断
suggest=risky → toast「内容包含违规信息,请修改」+ 阻断
suggest=pass-degraded 或网络异常 → 降级放行（不阻断业务，后端事后人工兜底）

2. `POST /mp/security/media-check` 媒体异步机审

图片/音频上传到 OSS 后，调本接口拿 traceId，把 traceId 数组随业务 API 提交。

请求:

http.post('/mp/security/media-check', {
  mediaUrl: "https://oss.example.com/xxx.jpg",  // 必填,已上传 OSS 的 https URL
  mediaType: "image"                            // 必填:image / audio
})

响应:

{
  "code": 200,
  "data": {
    "traceId": "967e945cd8a3e458effc23eb0e7c84e1"  // 失败时为 null
  }
}

前端使用:

同步只返 traceId，不阻断业务提交（异步审核）
traceId 收集到数组里，业务 API 提交时随 mediaTraceIds 字段传给后端
traceId=null（降级）时仍然继续业务，后端按未审核处置

二、业务 API body 新增 `mediaTraceIds` 字段（5 个接口）

业务接口	body 新增字段
`POST /mp/review/create` 评价	`mediaTraceIds: string[]`
`POST /mp/complaint/create` 投诉	`mediaTraceIds: string[]`
`POST /mp/order/{orderId}/refund` 退款	`mediaTraceIds: string[]`
`POST /mp/order/refund/{appId}/appeal` 申诉	`mediaTraceIds: string[]`
`POST /mp/order/refund/{orderId}/direct-appeal` 直接申诉	`mediaTraceIds: string[]`
`POST /mp/common/feedback` 客服反馈	`mediaTraceIds: string[]`

例：

// 评价提交流程
const traceIds = []
for (const url of uploadedImageUrls) {
  const r = await http.post('/mp/security/media-check', { mediaUrl: url, mediaType: 'image' })
  if (r.data.traceId) traceIds.push(r.data.traceId)  // null 时跳过即可
}
await http.post('/mp/review/create', {
  orderId: '...',
  content: '评价文本',
  images: uploadedImageUrls,
  mediaTraceIds: traceIds   // 新加字段
})

未传 mediaTraceIds 的接口（发票/退款理由/昵称/姓名）按无图处理，不影响。

三、查询响应新增字段

`/mp/review/my` 我的评价列表 + 详情

VO 新增 2 字段（私有列表才返，公开列表后端已自动过滤未审核内容）：

{
  "id": "...",
  "content": "...",
  "rating": 5,
  "auditStatus": "MANUAL_REVIEW",   // 新增 (Phase 2A): wx 内容安全机审状态
  "reportStatus": "NORMAL",         // 新增 (Phase 2B): 举报状态
  "hiddenReason": null,             // 新增 (Phase 2B): HIDDEN 时返回隐藏原因
  "createdAt": "..."
}

前端展示状态条文案：

auditStatus	状态条
`PENDING`	「审核中,通过后展示」灰色
`APPROVED`	(无提示，正常展示)
`MANUAL_REVIEW`	「审核中,预计 24h 内」黄色
`REJECTED`	「内容未通过审核」红色 + 重新编辑按钮

reportStatus	状态条
`NORMAL`	(无提示)
`PENDING_REVIEW`	(无提示，仍展示)
`HIDDEN`	「该评价已下架」+ `hiddenReason`

公开列表（产品评价/首页精选/旅行相册）后端已强制过滤 audit_status='APPROVED' AND report_status!='HIDDEN'，前端无需特殊处理。

四、新接口：评价举报 `POST /mp/review/report`

http.post('/mp/review/report', {
  reviewId: '101010101010',         // String 雪花 ID(必填,严禁 Number)
  reason: 'SPAM',                   // 必填,字典 review_report_reason
  detail: '广告链接,引导外部'        // 可选(≤500 字)
})

reason 字典（建议从 dict.getList('review_report_reason') 取，避免硬编码）:

reason	文案
`SPAM`	广告/营销
`INSULT`	辱骂/人身攻击
`PORN`	色情低俗
`POLITICS`	政治敏感
`FAKE`	虚假评价
`LEAK_PRIVACY`	泄露他人隐私
`OTHER`	其他

响应: 成功 200 / 失败业务码：

code	文案	处理
551001	举报原因无效	toast
551002	今日举报次数已达上限	toast，引导明日再来
551003	评价不存在	toast
551004	不能举报自己的评价	toast
551005	您已举报过该评价	toast
551006	无法识别用户身份,请重新登录	引导重新登录

举报后业务流程：

同 review 累计举报 ≥3 次 → report_status=PENDING_REVIEW（用户侧仍可见，运营人工审核中）
≥10 次且 24h 内 → 自动 HIDDEN（用户侧立即下架）
命中举报触发再机审：risky → 强制 HIDDEN

五、出行人姓名（前端不做硬拦截）

按官方契约 §8，姓名是实名信息，前端不应做内容机审（怕误伤真实姓「操/苟」、少数民族罕字、港澳台/外籍拼音）。

前端不需要改：

❌ 不要在创建出行人前调 text-check
❌ 不要本地正则/黑名单拦截

后端三层兜底已自动处理：

第 1 层：异步机审（不阻塞业务，命中标 MANUAL_REVIEW 不删数据）
第 2 层：下单选出行人时仅挡 REJECTED（人工裁决），其他状态全放行
第 3 层：本地正则（长度/字符集/重复字符防垃圾）

新增错误码（出行人下单时）:

code	文案
100701	姓名长度异常(2-30 字符)
100702	姓名含非法字符
100703	姓名含敏感词
100704	姓名格式不正确
100705	此出行人信息异常,请联系客服核实

同款适用：紧急联系人 / 用户实名。

六、头像 / 昵称（前端流程同现状）

昵称：前端调 text-check 文本同步机审（按"一"节流程），命中拦截
头像：前端 fileApi.upload 上传 OSS → securityApi.checkMedia 拿 traceId → userApi.updateUserInfo({avatar}) 不传 traceId（后端会在 /mp/file/upload 内部异步审，traceId 关联到 fileId 后通过 webhook 自动反查 user 表）

REJECTED 时后端自动重置默认头像，前端展示用户资料时拿到的就是已重置后的 URL。

七、调用顺序总结

评价/投诉/退款申诉 (含图)

1. 用户填表(选图)
2. 图上传 OSS → 拿 url[]
3. 文本调 /mp/security/text-check → 拿 suggest 决定是否阻断
4. 每张图调 /mp/security/media-check → 收集 traceId[]
5. 业务接口提交 (body 含 mediaTraceIds)

客服反馈 / 心愿单 / 备注 (仅文本)

1. 用户填表
2. 调 /mp/security/text-check → 决定阻断
3. 业务接口提交 (body 不含 mediaTraceIds)

用户昵称

1. 用户填昵称
2. 调 /mp/security/text-check → 决定阻断
3. /mp/user/profile 提交

用户头像

1. 上传 OSS
2. 调 /mp/security/media-check → 拿 traceId (失败也继续)
3. /mp/user/profile 提交 avatar (不传 traceId)

出行人

1. 用户填姓名
2. /mp/user/traveler 直接提交 (前端不调 security)
3. 后端三层兜底自动处理

八、降级容错

任何 /mp/security/* 接口 5xx 或网络异常：

前端按 降级放行 处理（不阻断业务）
用户体验优先于绝对合规
后端会通过 pass-degraded 标记记录，事后人工兜底审核

九、前端工作量预估

按本指南改前端约：

通用工具：utils/contentSecurity.js + utils/ugc.js 包装 text-check / media-check（已有则更新）
6 个业务页面调用点：评价提交 / 投诉提交 / 退款申请 / 申诉提交 / 客服反馈 / 心愿提交
评价列表：私有列表加状态条文案（auditStatus / reportStatus）
评价举报新页面：调 /mp/review/report
字典：拉 review_report_reason 字典做举报原因下拉
头像/昵称：检查现有流程是否已按上述顺序

@mmg 有任何疑问随时找我。后端已部署到 dev 分支，等运维 nacos 配 wechat.miniapp.webhook.token 后即可联调。

9.0 KiB 原始文件 Blame 文件历史 Unescape Escape