# Admin 首页数据配置 — 三统计展示模式

> 所属:Admin 组（前缀 `/admin/api/dashboard-display`） | 鉴权:Admin Bearer（改需 operator/super） | [← 返回 API 索引](./README.md)

配置客户端首页三个门面数字（帮助用户 / 完成比价 / 累计节省）的展示模式。每个指标可独立选 real/manual/random。用户侧读取见 [platform-stats](./platform-stats.md);表见 [platform_stat_display](../database/platform_stat_display.md)。

> **单位约定**:倍率用**千分比整数**(1.000→`1000`、1.100→`1100`)。`total_saved` 的 `manual_value` / `random_current` / `random_initial` 单位是**分**(前端展示时 ÷100 取元)。

---

## GET /admin/api/dashboard-display — 三指标配置 + 真实值预览

### 出参
响应 `200`:`list[PlatformStatItemOut]`(按 help_users / total_compares / total_saved 顺序)

| 字段 | 类型 | 说明 |
|---|---|---|
| `metric` | string | `help_users` / `total_compares` / `total_saved` |
| `label` | string | 帮助用户 / 完成比价 / 累计节省 |
| `unit` | string | 人 / 次 / 分 |
| `mode` | string | `real` / `manual` / `random` |
| `manual_value` | int \| null | manual 固定值（基础单位） |
| `random_mult_min` | int | 倍率下限（千分比，≥1000） |
| `random_mult_max` | int | 倍率上限（千分比） |
| `random_tick_seconds` | int | 更新间隔（秒，默认 86400=1 天） |
| `random_anchor_minutes` | int | 触发时刻对齐偏移（距北京 0 点分钟数：天=每日时刻、小时=每小时第几分、分钟=0） |
| `random_current` | int \| null | random 当前累积值（基础单位） |
| `random_last_tick_at` | string \| null | 上次 tick 时刻（ISO） |
| `real_value` | int | 当前真实值（给运营对比参考，基础单位） |
| `updated_at` | string \| null | 上次修改时间 |

---

## PATCH /admin/api/dashboard-display/{metric} — 改某指标(带审计)

`metric` 路径参数取 `help_users` / `total_compares` / `total_saved`。

### 入参 `PlatformStatUpdateRequest`(字段均可选,只改传了的)
| 字段 | 类型 | 说明 |
|---|---|---|
| `mode` | string | `real` / `manual` / `random` |
| `manual_value` | int | manual 固定值（基础单位，≥0） |
| `random_mult_min` | int | 倍率下限（千分比，1000~5000） |
| `random_mult_max` | int | 倍率上限（千分比，≥下限） |
| `random_tick_seconds` | int | 更新间隔（秒，≥60） |
| `random_anchor_minutes` | int | 触发时刻对齐偏移（分钟，需 `*60 < 更新间隔`） |
| `random_initial` | int | 切 random 的初始基数（基础单位）；**留空则用当前真实值播种** |

### 出参
响应 `200`:更新后的 `PlatformStatItemOut`(同上)。

### 错误
- `400`:mode 非法 / 倍率越界（<1000 或 >5000）/ 上限<下限 / tick<60 / 负值。
- `403`:角色不足（需 operator 或 super_admin）。
- `404`:无效 metric（不在三指标内,作为 400 文案返回）。

### 说明
- **统一定时刷新**:三模式的展示值(`random_current`)只在「更新时间(按更新间隔)」对齐的北京钟点刷新一次——real 快照查库 / manual 取固定值 / random ×倍率。`random_tick_seconds`+`random_anchor_minutes` 三模式通用。
- 改 mode/manual/倍率等到**下个更新钟点**才在客户端生效(展示值不立即变);`random_initial` 例外:立即设为该值并重置(自增长设起点)。首次无展示值时按当前模式播种。
- 每次改动写 `admin_audit_log`(action=`dashboard_display.set`,detail 含改前/改后快照)。
- 客户端在**进首页 / 回前台时**重拉 `/stats` 取最新展示值。