@ (#111)

docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
2026-07-03 15:00:37 +08:00
parent ee132aa93b
commit a563c1ca4b
102 changed files with 2418 additions and 217 deletions
@@ -0,0 +1,33 @@
+# GET /api/v1/platform/savings-feed — 首页轮播 feed(真实+种子混播)
+
+> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:**无** | [← 返回 API 索引](../README.md)
+
+客户端首页顶部「某用户 比价后节省 xx 元」滚动条数据源。全平台真实比价记录优先;不足时用运营配的种子([ops_marquee_seed](../database/ops_marquee_seed.md))补齐到 `limit` 条「混播」,保证轮播不空。
+
+**用户标识脱敏规则(全 feed 统一)**:① 有昵称 → 昵称脱敏:≥3 字「首+隐藏字数个星+末」(省钱小能手→`省***手`)、2 字「首+星」(阿强→`阿*`)、1 字「用户+该字」(喵→`用户喵`);② 没昵称 → 按 `user_id` **确定性合成一个假昵称再脱敏**(同用户恒定,避免无昵称用户清一色 `用户****`),少数露「用户」+ 8 星 + id 后 3 位(`用户********618`)。
+
+> 合成假名走**本地语料组合生成**(无外部库):中文真名(姓池 ×名字字池 拼「姓+1~2字」) / 中文网络昵称 / 英文昵称 / 英文名(可带数字尾) 混播,中文为主英文为辅,组合空间上万。真实条按 `user_id` 播种 → 同一用户名字恒定、不同用户各异(刷新/翻页不变脸,同屏几乎不撞名);种子/兜底用运行时随机源出多样。当前真实用户大多没设昵称,故走合成。
+
+## 入参
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `limit` | int, query | 返回条数,默认 8,范围 1~30 |
+
+## 出参
+响应 `200`:`SavingsFeedOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `items` | list | 轮播条目数组(最多 `limit` 条) |
+| `items[].masked_user` | string | 脱敏用户名:昵称/合成名脱敏(`省***手` / `王*` / `SaveK**g`)或匿名 `用户********618` |
+| `items[].saved_amount_cents` | int | 节省（分），客户端 ÷100 显示「x.xx 元」 |
+| `items[].time` | string | 北京时间 `HH:MM:SS` |
+
+## 说明
+- 真实条:`comparison_record` 中 `status='success'` 且 `0 < saved_amount_cents ≤ 300 元` 的近期记录(金额超 300 元视为异常 / bug 值剔除,防「节省 999 元」穿帮),**JOIN `user` 表取昵称 → 仅 user 表内用户的记录入选**(孤儿/已删用户记录不计,设计如此;当前用户量少,缺口由种子补足),**按 `user_id` 去重**(同一用户只取最新一条,避免单人刷屏);有昵称按真实昵称脱敏,无昵称按 `user_id` 播种**确定性合成**脱敏名(同用户恒定、刷新不变脸)。
+- 种子条:`ops_marquee_seed`(`enabled=true`),仅在真实去重后不足 `limit` 时补齐;**从启用种子中公平随机抽取**(不再固定取前 N,所有种子都有机会露出)。每条种子:用户名留空或旧 `用户****xxx` 模板名则**随机合成混合风格名并避开同屏撞名**(自愈历史种子),金额在 `[min_cents, max_cents]` 取**长尾随机值**(小额居多、偶尔大额,固定金额则 min==max)。
+- 兜底:真实 + 种子仍凑不满 `limit`(种子被全停用 / 太少)时,用**内置合成条补满**,保证轮播既不空也不稀疏。
+- **`time` 为合成的「最近」时间**(从当前北京时间往前**随机抖动**递减,首条几十秒前,其余多数 1~5 分钟、偶尔扎堆或较长):社会证明轮播保证永远像刚发生且节奏自然不机械,不受旧测试数据 / 低谷期记录影响。真实的用户/金额不变,只换展示时间。
+- 因含随机(种子抽取 / 金额 / 展示时间 / 种子合成名),**每次请求结果都不同**——这是轮播想要的鲜活感;但**真实用户的脱敏名按 `user_id` 恒定**,同一用户跨请求不变脸(避免「同一人换张脸」露馅)。
+- **性能**:首页人人都看、真实数据变化慢,真实记录原始行带 **~30s 进程内缓存**(展示层随机仍每次重算,只省 DB 往返;新记录最多晚 30s 进轮播)。查询走复合索引 `ix_comparison_status_created (status, created_at)`,避免随数据量增大全表扫。
+- 逻辑见 `app/repositories/ops_marquee.py`;运营管理种子见 [admin-marquee-seeds](./admin-marquee-seeds.md)。
@@ -0,0 +1,23 @@
+# GET /api/v1/savings/battle — 省钱战绩
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SavingsBattleOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `week_saved_cents` | int | 本周已省（分） |
+| `beat_percent` | int | 超过百分之多少用户 |
+| `streak_days` | int | 连续省钱天数 |
+| `compare_count` | int | 累计完成比价次数（= 真实 `compare` 上报记录数；无记录为 0） |
+
+## 说明
+下单成交口径（`savings_record` 源）的战绩字段。`compare_count` 与 `/summary` 的 `order_count` 同源（均 = 真实**下单上报**记录数）。
+
+> ⚠️ **2026-06 起停用 demo 兜底**：只计真实比价下单上报（`source='compare'`）。下单上报链路已通（Android `PriceBotService` → `POST /api/v1/order/report`）。
+
+> ⚠️ **「我的」页省钱战绩卡已不读本接口**：#23 起卡改为**比价口径**，「完成比价 / 累计发现可省」走 [`GET /api/v1/compare/stats`](./compare-stats.md)（`comparison_record`，比过价就计、不要求下单），「赚取金币」走 `/wallet/account.total_coin_earned`。本 `/battle`（及 `compare_count`/`week_saved_cents`/`beat_percent`/`streak_days`）现仅供订单口径/历史用途，不上战绩卡。
@@ -0,0 +1,29 @@
+# GET /api/v1/savings/records — 省钱明细(游标分页)
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`:`{ items: SavingsRecordOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**SavingsRecordOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 记录 id（也是游标） |
+| `order_amount_cents` | int | 订单金额（分） |
+| `saved_amount_cents` | int | 本单省下（分） |
+| `platform` | string \| null | 平台（美团/饿了么等） |
+| `title` | string \| null | 标题 |
+| `shop_name` | string \| null | 店铺名 |
+| `dishes` | string[] | 菜品列表 |
+| `created_at` | datetime | 时间 |
+
+## 说明
+订单/省钱明细页（`RECORDS`）数据源。
@@ -0,0 +1,18 @@
+# GET /api/v1/savings/summary — 累计帮你省了
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SavingsSummaryOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `total_saved_cents` | int | 累计省下（分） |
+| `order_count` | int | 累计省钱订单数 |
+| `avg_saved_cents` | int | 平均每单省（分） |
+
+## 说明
+「我的」页「累计帮你省了」卡数据源。当前比价上报未接入,实际多为 0。