# P30 风控与反作弊接口清单

接口前缀 `/api/risk`。当前站点未接入后端，以下为设计稿，用于前后端字段与错误码对齐。

## 1. 提交前校验

`POST /api/risk/check`

请求体：

```json
{
  "scene": "rfq_submit",
  "subjectId": "P-LOCAL-BUYER",
  "payload": { "bidCount24h": 3, "contactValid": true }
}
```

响应：

```json
{ "code": 0, "score": 85, "action": "pass", "reasons": [], "challenge": null }
```

`action` 取值：`pass` 放行、`challenge` 触发验证、`review` 转人工复核、`block` 阻断。

## 2. 验证挑战

- `POST /api/risk/challenge/create` 请求 `{ "scene": "", "subjectId": "" }`
- `POST /api/risk/challenge/verify` 请求 `{ "challengeId": "", "answer": "" }`

校验通过后返回一次性通行凭证，10 分钟内有效。

## 3. 风险事件

- `GET /api/risk/event/list?from=&to=&scene=&action=&page=1&size=20`
- `GET /api/risk/event/detail?id=`
- `POST /api/risk/event/handle` 请求 `{ "id": 0, "decision": "pass|reject", "note": "" }`

## 4. 规则配置

- `GET /api/risk/rule/list`
- `POST /api/risk/rule/save` 请求 `{ "id": 0, "threshold": 5, "weight": 15, "enabled": true, "gray": 0.2 }`
- `POST /api/risk/rule/toggle` 请求 `{ "id": 0, "enabled": true }`

规则变更需要二次确认，并写入审计日志。

## 5. 名单管理

- `GET /api/risk/list/ip`
- `POST /api/risk/list/ip/save` 请求 `{ "ip": "", "reason": "", "expireAt": "" }`
- `GET /api/risk/list/subject`
- `POST /api/risk/list/subject/save` 请求 `{ "subjectId": "", "level": "watch|limit|ban", "note": "" }`

## 6. 申诉

- `POST /api/risk/appeal/submit` 请求 `{ "eventId": 0, "content": "", "contact": "" }`
- `GET /api/risk/appeal/list?status=`
- `POST /api/risk/appeal/handle` 请求 `{ "id": 0, "result": "accept|reject", "note": "" }`

## 7. 错误码

| 码 | 含义 |
| --- | --- |
| 0 | 成功 |
| 400 | 参数缺失或非法 |
| 401 | 未登录 |
| 403 | 无风控后台权限 |
| 409 | 幂等冲突，已存在同键提交 |
| 429 | 频次超限 |
| 451 | 本次提交被阻断，可发起申诉 |
| 500 | 服务端异常 |

## 8. 权限矩阵

| 接口 | 超级管理员 | 运营 | 供应商 | 采购 |
| --- | --- | --- | --- | --- |
| check | 是 | 是 | 是 | 是 |
| challenge/* | 是 | 是 | 是 | 是 |
| event/list | 是 | 是 | 否 | 否 |
| event/handle | 是 | 是 | 否 | 否 |
| rule/* | 是 | 否 | 否 | 否 |
| list/* | 是 | 只读 | 否 | 否 |
| appeal/submit | 是 | 是 | 是 | 是 |
| appeal/handle | 是 | 是 | 否 | 否 |