# 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` 文本同步机审

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

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

**响应**:
```json
{
  "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 提交。

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

**响应**:
```json
{
  "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[]` |

**例**：
```js
// 评价提交流程
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 字段（私有列表才返，公开列表后端已自动过滤未审核内容）：

```jsonc
{
  "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`

```js
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 后即可联调。