@

docs: reorganize api docs into categorized subdirectories and fill missing docs

- Categorize 77 existing api docs into 16 business-domain subdirectories
  (auth/ad/wallet/coupon/compare/savings/signin/tasks/invite/user/
   device/platform/intent/meituan/other) plus admin/ and internal/
- Split admin/ into 7 sub-resource subdirectories (auth/users/wallet/
  withdraws/feedbacks/admins/ad) with 4 single-file docs at root
- Create 21 new docs covering 28 previously undocumented endpoints:
  ad/watch-report, wallet/transfer-auth (3 endpoints), coupon/session+
  stats+completed-today+prompt (7), invite/me+invitees+bind+landing-track,
  user/onboarding (2), platform/flags+ad-config+app-version,
  intent/step+precoupon/step, analytics/events, order/report,
  report/submit+records, feedback/config+records, trace/finalize
- Add mock request/response JSON examples to all new docs
- Create docs/README.md with full category index for LLM navigation
- Update docs/api/README.md: fix all links, add new endpoint rows,
  replace "no doc" markers with actual links
- Fix back-navigation links (./README.md -> ../README.md or
  ../../README.md) in all moved files
@

docs/api/other/report-submit.md

@@ -0,0 +1,57 @@
+# 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 后台操作），不在此端点