OuYingJun1024
cfeacb4bab
- 新表 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>
3.6 KiB
3.6 KiB
Admin 首页数据配置 — 三统计展示模式
所属:Admin 组（前缀
/admin/api/dashboard-display） | 鉴权:Admin Bearer（改需 operator/super） | ← 返回 API 索引
配置客户端首页三个门面数字（帮助用户 / 完成比价 / 累计节省）的展示模式。每个指标可独立选 real/manual/random。用户侧读取见 platform-stats;表见 platform_stat_display。
单位约定:倍率用千分比整数(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取最新展示值。