# platform_stat_display — 首页三统计展示配置

> 模型 `app/models/platform_stat.py` | 关联接口 [platform-stats](../api/platform-stats.md) / [admin-dashboard-display](../api/admin-dashboard-display.md) | [← 表索引](./README.md)

客户端首页三个门面数字（帮助用户 / 完成比价 / 累计节省）的展示配置。一行一指标(主键=`metric`),每指标可独立选 real/manual/random 三种模式。计算逻辑见 `app/repositories/platform_stat.py`。

> **单位**:倍率用**千分比整数**(1.000→`1000`);`total_saved` 指标的 `manual_value` / `random_current` 单位是**分**,两个计数指标是**个数**。

## 字段
| 列 | 类型 | 约束 / 默认 | 说明 |
|---|---|---|---|
| `metric` | String(32) | PK | `help_users` / `total_compares` / `total_saved` |
| `mode` | String(16) | NOT NULL, default `real` | `real` 查库 / `manual` 手填 / `random` 随机增长 |
| `manual_value` | Integer | nullable | manual 模式固定值(基础单位) |
| `random_mult_min` | Integer | NOT NULL, default 1000 | 倍率下限(千分比,≥1000 保证只增不减) |
| `random_mult_max` | Integer | NOT NULL, default 1100 | 倍率上限(千分比) |
| `random_tick_seconds` | Integer | NOT NULL, default 86400 | 更新间隔(秒) |
| `random_anchor_minutes` | Integer | NOT NULL, default 0 | 触发时刻对齐偏移(距北京 0 点分钟数):天=每日时刻 h*60+m、小时=每小时第几分、分钟=0 |
| `random_current` | Integer | nullable | 当前展示值(所有模式,基础单位);惰性 tick 改写 |
| `random_last_tick_at` | DateTime(tz) | nullable | 上次 tick 时刻 |
| `random_kind` | String(8) | NOT NULL, default `mult` | 自增长方式:`mult` ×倍率 / `add` +绝对增量 |
| `random_step_min` | Integer | NOT NULL, default 0 | add 模式增量下限(基础单位) |
| `random_step_max` | Integer | NOT NULL, default 0 | add 模式增量上限(基础单位) |
| `real_offset` | Integer | NOT NULL, default 0 | real 模式基数偏移(基础单位):展示 = 真实值 + 偏移 |
| `allow_decrease` | Boolean | NOT NULL, default false | 是否允许展示值下降(默认 false = 只增不减) |
| `updated_by_admin_id` | Integer | nullable | 最后修改的管理员 |
| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 更新时间 |

## 初始数据(migration 播种)
三行,默认 `mode='manual'` + 客户端原写死门面值,保证上线前后展示一致:

| metric | manual_value | 含义 |
|---|---|---|
| `help_users` | 12847 | 12847 人 |
| `total_compares` | 86532 | 86532 次 |
| `total_saved` | 3762140 | 37621.40 元 |

## 统一「定时刷新」(北京钟点对齐)
`random_current` 现是**所有模式**的「当前展示值」(不止 random),用户侧 `/stats` 直接返回它。
- 触发边界 = 北京时间 `anchor + k*interval`(interval=`random_tick_seconds`,anchor=`random_anchor_minutes*60`,sub-day 间隔取 `anchor % interval` 作相位)。例:每天 09:00 / 每小时 :30 / 每 5 分刻度。
- 读取(`get_display_values`/`get_config`)时跑 `_refresh`:统计 `random_last_tick_at`→`now` 跨过几个边界 N,N≥1 才刷新:
  - **real** → `random_current` = 重新查库的真实值 + `real_offset`(跨多少边界都只取最新),**经只增不减护栏**。
  - **manual** → `random_current` = 当前 `manual_value`,**经只增不减护栏**。
  - **random** → 按 `random_kind` 走 N 个周期:`mult` 连乘随机倍率(`randint(min,max)/1000`,恒 ≥1.0)/ `add` 连加随机增量(`randint(step_min,step_max)`,≥0)。天然只增。
- **只增不减护栏**(`allow_decrease=false`,默认):real/manual 刷新时若新目标值 < 当前 `random_current`,保持当前值不回退(门面忌缩水)。开 `allow_decrease` 才允许下降。
- 用边界索引比较,`random_last_tick_at` 直接记 `now`,不重复计。
- ⚠️ **接受刷新时刻的微小并发竞态**(不加行锁):纯门面数字,无业务后果。
- `random_current` 首次为空时按当前模式播种(`update_config` 或 `_refresh` 兜底);`random_initial` 可立即设起点(不受护栏约束)。

## 说明
- real 口径仅统计 `comparison_record` 中 `status='success'` 的记录(去重用户数 / 记录数)。`total_saved` 的求和**只计入 `0 < saved_amount_cents ≤ 300 元` 的条目**(剔除 bug 异常大值,与轮播口径一致,防一条异常配合「只增不减」永久撑高门面)。
- `倍率上限收紧为 1.500`(单次 ×1.5,原 5.0 太大一跳就假)。
- 改配置走 admin `PATCH /admin/api/dashboard-display/{metric}`,带审计。