guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
58 lines
2.0 KiB
Markdown
58 lines
2.0 KiB
Markdown
# POST /api/v1/report — 提交上报更低价
|
||
|
||
> 所属:Report 组（前缀 `/api/v1/report`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
|
||
|
||
众包纠偏：用户发现比价记录中某平台有更低价格时提交上报。需附截图证明，原最低价由 `comparison_record_id` 反查（不信任客户端传的快照），提交价必须 < 原最低价。提交后 `status=pending`，人工审核通过后发奖。
|
||
|
||
## 入参
|
||
|
||
**multipart/form-data**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `comparison_record_id` | int | ✅ | 比价记录 ID |
|
||
| `reported_platform_id` | string | ✅ | 上报平台标识：`meituan-waimai` / `jd-waimai` / `taobao-shanguang` |
|
||
| `reported_price` | string | ✅ | 用户填的更低价（元，如 `23.5`） |
|
||
| `images` | file[] | ✅（1–4 张） | 截图证明 |
|
||
|
||
Mock 入参（curl 示例）:
|
||
```bash
|
||
curl -X POST https://app-api.shaguabijia.com/api/v1/report \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-F "comparison_record_id=5678" \
|
||
-F "reported_platform_id=jd-waimai" \
|
||
-F "reported_price=18.8" \
|
||
-F "images=@screenshot1.png" \
|
||
-F "images=@screenshot2.png"
|
||
```
|
||
|
||
## 出参
|
||
|
||
响应 `200`:`ReportSubmitOut`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | int | 上报记录 ID |
|
||
| `status` | string | 固定 `pending`（待审核） |
|
||
| `created_at` | datetime | 提交时间（ISO 8601 UTC） |
|
||
|
||
Mock 出参:
|
||
```json
|
||
{
|
||
"id": 89,
|
||
"status": "pending",
|
||
"created_at": "2026-07-03T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
## 错误码
|
||
- `400` 价格不合法（≤0 / 格式错）/ 上报价 ≥ 原最低价 / 图片问题（空/超 4 张/格式不对）/ 不支持的上报平台
|
||
- `401` 未鉴权
|
||
- `404` 比价记录不存在或不属于当前用户
|
||
|
||
## 说明
|
||
- 原最低价由 `comparison_record_id` → `ComparisonRecord.best_price_cents` 反查
|
||
- 校验（D）：`reported_price_cents < original_price_cents`，否则 400
|
||
- 截图落盘 `MEDIA_ROOT/price_report/`，文件名随机防覆盖
|
||
- 发奖走人工审核（admin 后台操作），不在此端点
|