feat(platform): 首页门面三统计 + 运营后台展示模式配置

- 新表 platform_stat_display:每个指标可选 real/manual/random 三种
  展示模式,含建表 + anchor_minutes 两个 alembic migration
- 公开接口 GET /api/v1/platform/stats(无鉴权门面数字,登录前可读)
- 运营后台 GET/PATCH /admin/api/dashboard-display 配置展示模式
- 配套 model/repository/schema,注册 router(app/main+admin/main),
  导出 model,补 docs(api/database 索引及 3 篇详情)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
OuYingJun1024
2026-06-06 22:45:07 +08:00
parent f5d1a1a20d
commit cfeacb4bab
16 changed files with 726 additions and 1 deletions
+27
View File
@@ -0,0 +1,27 @@
# GET /api/v1/platform/stats — 首页三统计(全平台门面数字)
> 所属:Platform 组(前缀 `/api/v1/platform` | 鉴权:**无**(登录前首页也要展示) | [← 返回 API 索引](./README.md)
客户端首页顶部「帮助用户 / 完成比价 / 累计节省」三个平台级数字。每个指标的展示模式由运营后台配(见 [admin-dashboard-display](./admin-dashboard-display.md)),本接口只返回算好的结果值。
## 入参
无。
## 出参
响应 `200`:`PlatformStatsOut`
| 字段 | 类型 | 说明 |
|---|---|---|
| `help_users` | int | 帮助用户(人) |
| `total_compares` | int | 完成比价(次) |
| `total_saved_cents` | int | 累计节省(**分**),客户端 ÷100 显示「元」 |
## 说明
三指标各自独立选模式,且**统一「定时刷新」**:客户端看到的展示值只在「更新时间(按更新间隔)」对齐的北京钟点(`anchor + k*间隔`)刷新一次,平时不变。每次刷新按模式算新值:
- **real**:重新快照查库。`help_users`=有过 `status='success'` 比价记录的去重用户数;`total_compares`=成功比价记录数;`total_saved_cents`=成功记录 `saved_amount_cents` 求和。
- **manual**:取运营当前手填的固定值(改值到下个更新钟点生效)。
- **random**:在上次展示值上 ×一个 [min,max](≥1.0)的随机倍率,只增不减(跨几个钟点乘几次)。
计算逻辑见 `app/repositories/platform_stat.py`,模型见 `app/models/platform_stat.py`(表 [platform_stat_display](../database/platform_stat_display.md))。
上线初始播种为 manual + 客户端原写死门面值(12847 / 86532 / 37621.40 元),保证前后展示一致。