guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
74 lines
5.0 KiB
Markdown
74 lines
5.0 KiB
Markdown
# Admin 首页数据配置 — 三统计展示模式
|
||
|
||
> 所属:Admin 组（前缀 `/admin/api/dashboard-display`） | 鉴权:Admin Bearer（改需 operator/super） | [← 返回 API 索引](../README.md)
|
||
|
||
配置客户端首页三个门面数字（帮助用户 / 完成比价 / 累计节省）的展示模式。每个指标可独立选 real/manual/random。用户侧读取见 [platform-stats](./platform-stats.md);表见 [ops_stat_config](../database/ops_stat_config.md)。
|
||
|
||
> **单位约定**:倍率用**千分比整数**(1.000→`1000`、1.100→`1100`)。`total_saved` 的 `manual_value` / `random_current` / `random_initial` / `random_step_min` / `random_step_max` / `real_offset` 单位都是**分**(前端展示时 ÷100 取元);两个计数指标是个数。
|
||
|
||
---
|
||
|
||
## GET /admin/api/dashboard-display — 三指标配置 + 真实值预览
|
||
|
||
### 出参
|
||
响应 `200`:`list[OpsStatItemOut]`(按 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_kind` | string | 自增长方式：`mult` ×倍率 / `add` +绝对增量 |
|
||
| `random_step_min` | int | add 模式增量下限（基础单位） |
|
||
| `random_step_max` | int | add 模式增量上限（基础单位） |
|
||
| `real_offset` | int | real 模式保底值（基础单位）：展示 = max(真实值, 保底值)。字段名沿用 real_offset（语义已改为"保底"） |
|
||
| `allow_decrease` | bool | 是否允许展示值下降（默认 false = 只增不减） |
|
||
| `random_current` | int \| null | 当前展示值（所有模式，基础单位） |
|
||
| `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`。
|
||
|
||
### 入参 `OpsStatUpdateRequest`(字段均可选,只改传了的)
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `mode` | string | `real` / `manual` / `random` |
|
||
| `manual_value` | int | manual 固定值（基础单位，≥0） |
|
||
| `random_mult_min` | int | 倍率下限（千分比，1000~1500） |
|
||
| `random_mult_max` | int | 倍率上限（千分比，≥下限，≤1500） |
|
||
| `random_tick_seconds` | int | 更新间隔（秒，≥60） |
|
||
| `random_anchor_minutes` | int | 触发时刻对齐偏移（分钟，0~1439） |
|
||
| `random_kind` | string | 自增长方式：`mult` / `add` |
|
||
| `random_step_min` | int | add 增量下限（基础单位，≥0） |
|
||
| `random_step_max` | int | add 增量上限（基础单位，≥下限） |
|
||
| `real_offset` | int | real 保底值（基础单位，≥0）：展示 = max(真实值, 保底值) |
|
||
| `allow_decrease` | bool | 允许展示值下降（默认 false=只增不减） |
|
||
| `random_initial` | int | 切 random 的初始基数（基础单位）；**留空则用当前真实值播种** |
|
||
| `apply_now` | bool | 立即更新:不等更新钟点,保存后马上刷新一次(random 走一档,real/manual 取应有值,均经护栏) |
|
||
|
||
### 出参
|
||
响应 `200`:更新后的 `OpsStatItemOut`(同上)。
|
||
|
||
### 错误
|
||
- `400`:mode/kind 非法 / 倍率越界（<1000 或 >1500）/ 上限<下限 / 增量负值或上限<下限 / 偏移负值 / tick<60 / 更新时间越界 / manual 负值。
|
||
- `403`:角色不足（需 operator 或 super_admin）。
|
||
- `404`:无效 metric（不在三指标内,作为 400 文案返回）。
|
||
|
||
### 说明
|
||
- **统一定时刷新**:三模式的展示值(`random_current`)只在「更新时间(按更新间隔)」对齐的北京钟点刷新一次——real 快照查库(+偏移)/ manual 取固定值 / random 按 `random_kind` 走一档(`mult` ×倍率 / `add` +增量)。`random_tick_seconds`+`random_anchor_minutes` 三模式通用。
|
||
- **只增不减护栏**(`allow_decrease=false`,默认):real/manual 刷新时新目标值低于当前展示值则保持不降;要下调须显式传 `allow_decrease=true`。
|
||
- 改 mode/manual/倍率/增量/偏移等到**下个更新钟点**才在客户端生效(展示值不立即变);`random_initial` 立即设起点并重置;`apply_now=true` 立即刷新一次。首次无展示值时按当前模式播种。
|
||
- 每次改动写 `admin_audit_log`(action=`ops_stat_config.set`,detail 含改前/改后快照)。
|
||
- 客户端在**进首页 / 回前台时**重拉 `/stats` 取最新展示值。
|