ouzhou
766666601e
Co-authored-by: OuYingJun1024 <1034284404@qq.com> Reviewed-on: #22 Reviewed-by: marco <marco@wonderable.ai> Co-authored-by: ouzhou <ouzhou@wonderable.ai> Co-committed-by: ouzhou <ouzhou@wonderable.ai>
46 lines
3.1 KiB
Markdown
46 lines
3.1 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);表见 [ops_marquee_seed](../database/ops_marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
|
||
|
||
## 复用结构 OpsMarqueeSeedOut
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `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[OpsMarqueeSeedOut]`(按 `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 — 新增(带审计)
|
||
入参 `OpsMarqueeSeedCreate`:`masked_user`(可选,空 / 不传 → 随机合成)、`min_cents`(必填,≥0)、`max_cents`(必填,≥min,≤1000 元)、`enabled`(默认 true)、`sort_order`(默认 0)。出参:新建的 `OpsMarqueeSeedOut`。`400`=金额非法。
|
||
|
||
## POST /admin/api/marquee-seeds/bulk — 批量生成(带审计)
|
||
冷启动铺量:一次生成 `count` 条「自动合成名」(masked_user=null)种子,金额均为给定区间,`sort_order` 续在当前最大值之后。
|
||
- 入参 `OpsMarqueeSeedBulkCreate`:`count`(1~200)、`min_cents`、`max_cents`、`enabled`(默认 true)
|
||
- 出参 `200`:`list[OpsMarqueeSeedOut]`(新建的 count 条)。`400`=数量 / 金额非法。
|
||
|
||
## PATCH /admin/api/marquee-seeds/{seed_id} — 改(带审计)
|
||
入参 `OpsMarqueeSeedUpdate`(均可选):`masked_user` / `min_cents` / `max_cents` / `enabled` / `sort_order`。
|
||
- `masked_user` 约定:**不传**=不改;**传空串**=清空(改回随机合成);**传值**=固定该名。
|
||
- 只改单边 `min_cents` / `max_cents` 时,与现有的另一边一起做「上限≥下限」校验。
|
||
出参:更新后的 `OpsMarqueeSeedOut`。`404`=种子不存在;`400`=金额非法。
|
||
|
||
## DELETE /admin/api/marquee-seeds/{seed_id} — 删(带审计)
|
||
出参 `200`:`{"deleted": true}`。`404`=种子不存在。
|
||
|
||
## 说明
|
||
- 写操作需 operator(super 恒可),均写 `admin_audit_log`(action=`ops_marquee_seed.create` / `update` / `delete` / `bulk_generate`)。预览为只读,任意已登录 admin 可用。
|
||
- 改动客户端**进首页 / 回前台**重拉 feed 时生效。
|