OuYingJun1024
c9578f5ba2
轮播 feed(marquee_seed,全新): - 新增 marquee_seed 表 + admin CRUD/批量生成/预览;真实比价记录(success 且 0<省额≤300元、按 user 去重)优先,种子兜底混播 - 种子为「生成规则」:用户名可空(空则按脱敏格式随机合成、避开同屏撞名),金额改 [min,max] 区间随机,feed 公平随机抽取(不看 sort_order) - 新增 GET /api/v1/platform/savings-feed(无鉴权);展示时间统一刷新为相对当前的最近时刻 三统计配置(platform_stat_display)增强: - 自增长新增「绝对增量」方式(random_kind=add,每周期 +[step_min,step_max]) - 真实值模式加基数偏移(real_offset,展示=真实+偏移) - 只增不减护栏(allow_decrease 默认关,real/manual 不回退防门面缩水) - 累计节省 real 口径只计 0<单条≤300元防虚高;倍率上限 5.0→1.5;PATCH 支持 apply_now 立即更新 迁移:marquee_seed_table / marquee_seed_range / platform_stat_growth_offset(均可逆,已验证) 文档:API/DB 对应文档同步更新 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
46 lines
3.0 KiB
Markdown
46 lines
3.0 KiB
Markdown
# Admin 首页轮播种子管理
|
||
|
||
> 所属:Admin 组（前缀 `/admin/api/marquee-seeds`） | 鉴权:Admin Bearer（改需 operator/super) | [← 返回 API 索引](./README.md)
|
||
|
||
管理首页轮播「真实+种子混播」的兜底种子。种子是「生成规则」:`masked_user` 可空(空→feed 随机合成名)、金额是 `[min_cents, max_cents]` 区间(feed 每次随机取值)。用户侧 feed 见 [platform-savings-feed](./platform-savings-feed.md);表见 [marquee_seed](../database/marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
|
||
|
||
## 复用结构 MarqueeSeedOut
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | int | |
|
||
| `masked_user` | string \| null | 脱敏用户名;`null` = feed 随机合成 |
|
||
| `min_cents` | int | 金额区间下限(分) |
|
||
| `max_cents` | int | 金额区间上限(分);固定金额则与下限相等 |
|
||
| `enabled` | bool | 停用不参与混播 |
|
||
| `sort_order` | int | 仅后台列表排序(小在前) |
|
||
| `created_at` | string \| null | 创建时间(ISO) |
|
||
|
||
## GET /admin/api/marquee-seeds — 种子列表
|
||
出参 `200`:`list[MarqueeSeedOut]`(按 `sort_order,id`)。
|
||
|
||
## GET /admin/api/marquee-seeds/preview — 预览实际混播 feed
|
||
预览客户端实际会看到的轮播(真实记录会插队、种子随机抽取 / 金额随机 / 名字合成),供运营对效果。**含随机,每次结果不同**。
|
||
- 入参:`limit`(query,1~30,默认 8)
|
||
- 出参 `200`:`{"items": [{masked_user, saved_amount_cents, time}]}`(条目同 [platform-savings-feed](./platform-savings-feed.md))
|
||
|
||
## POST /admin/api/marquee-seeds — 新增(带审计)
|
||
入参 `MarqueeSeedCreate`:`masked_user`(可选,空 / 不传 → 随机合成)、`min_cents`(必填,≥0)、`max_cents`(必填,≥min,≤1000 元)、`enabled`(默认 true)、`sort_order`(默认 0)。出参:新建的 `MarqueeSeedOut`。`400`=金额非法。
|
||
|
||
## POST /admin/api/marquee-seeds/bulk — 批量生成(带审计)
|
||
冷启动铺量:一次生成 `count` 条「自动合成名」(masked_user=null)种子,金额均为给定区间,`sort_order` 续在当前最大值之后。
|
||
- 入参 `MarqueeSeedBulkCreate`:`count`(1~200)、`min_cents`、`max_cents`、`enabled`(默认 true)
|
||
- 出参 `200`:`list[MarqueeSeedOut]`(新建的 count 条)。`400`=数量 / 金额非法。
|
||
|
||
## PATCH /admin/api/marquee-seeds/{seed_id} — 改(带审计)
|
||
入参 `MarqueeSeedUpdate`(均可选):`masked_user` / `min_cents` / `max_cents` / `enabled` / `sort_order`。
|
||
- `masked_user` 约定:**不传**=不改;**传空串**=清空(改回随机合成);**传值**=固定该名。
|
||
- 只改单边 `min_cents` / `max_cents` 时,与现有的另一边一起做「上限≥下限」校验。
|
||
出参:更新后的 `MarqueeSeedOut`。`404`=种子不存在;`400`=金额非法。
|
||
|
||
## DELETE /admin/api/marquee-seeds/{seed_id} — 删(带审计)
|
||
出参 `200`:`{"deleted": true}`。`404`=种子不存在。
|
||
|
||
## 说明
|
||
- 写操作需 operator(super 恒可),均写 `admin_audit_log`(action=`marquee_seed.create` / `update` / `delete` / `bulk_generate`)。预览为只读,任意已登录 admin 可用。
|
||
- 改动客户端**进首页 / 回前台**重拉 feed 时生效。
|