@ (#111)

docs/api目录文档分类和补全

---------

Co-authored-by: guke <guke@autohome.com.cn>
Reviewed-on: #111

docs/api/compare/compare-milestone-claim.md

@@ -0,0 +1,34 @@
+# POST /api/v1/compare/milestones/{milestone}/claim — 领取比价战绩里程碑奖励
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+领取某一档(第 `milestone` 次)。⚠️ **当前不真发金币**(产品定,后续整体删除该功能):仍写
+`comparison_milestone_claim`((user_id, milestone) 唯一)标记该档已领、**每档只能领一次**,但不调
+`grant_coins`、不写 `coin_transaction`,余额不变,`coin_awarded` 恒为 0。进度口径见
+[milestones 进度接口](./compare-milestones.md)。
+
+## 入参
+- 路径参数 `milestone`(int):档位序号,1..6(= `RECORD_MILESTONES` 长度)。
+
+## 出参
+响应 `200`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `milestone` | int | 本次领取的档位序号 |
+| `coin_awarded` | int | 本次发放金币(当前恒为 `0`,暂不真发) |
+| `coin_balance` | int | 领奖后金币余额(当前不变) |
+
+```json
+{ "milestone": 1, "coin_awarded": 0, "coin_balance": 29087 }
+```
+
+## 错误
+- `401` 未鉴权
+- `404` 档位越界(`unknown milestone`,milestone < 1 或 > 档位总数)
+- `409` 该档还没解锁(`milestone locked`,成功比价次数 < milestone)
+- `409` 该档已领过(`milestone already claimed`)
+
+## 说明
+- 当前不发金币,客户端领取后只需把本档状态刷成 claimed 即可;若后续恢复发奖,再按 `coin_awarded` 刷新钱包余额([`GET /api/v1/wallet/account`](./wallet-account.md))。
+- 幂等:重复领同一档返回 409(唯一约束 + 领取前查重)。