shaguabijia-app-server/docs/api/admin-dashboard-display.md

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

所属:Admin 组（前缀 /admin/api/dashboard-display） | 鉴权:Admin Bearer（改需 operator/super） | ← 返回 API 索引

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

单位约定:倍率用千分比整数(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 取最新展示值。