67 lines
4.5 KiB
Markdown
67 lines
4.5 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](../savings/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
|
||
预览客户端实际会看到的轮播(真实记录会插队、种子随机抽取 / 金额随机 / 名字合成),供运营对效果。**含随机,每次结果不同**;#122 起按**当前数据源模式**实时预览(mixed/real/seed 各自的真实产出)。
|
||
- 入参:`limit`(query,1~30,默认 8)
|
||
- 出参 `200`:`{"items": [{masked_user, saved_amount_cents, time}]}`(条目同 [platform-savings-feed](../savings/platform-savings-feed.md))
|
||
|
||
## GET /admin/api/marquee-seeds/real-records — 分页浏览当前模式下可展示的真实记录(#123)
|
||
审核用:看「真实条」到底会拿哪些 `comparison_record` 上轮播(真实条**不按用户去重**,打乱+去连簇后混播;默认昵称归「无昵称」脱敏档,#122)。
|
||
- 入参:`limit` / `cursor`(游标分页)
|
||
- 出参 `200`:`{"items": [...], "next_cursor": int|null}`
|
||
|
||
## GET /admin/api/marquee-seeds/mode — 首页轮播数据源模式
|
||
出参:`{"mode": "mixed" | "real" | "seed"}`(混播 / 只真实 / 只种子)。
|
||
|
||
## PATCH /admin/api/marquee-seeds/mode — 改数据源模式(带审计)
|
||
- 入参:`{"mode": "mixed" | "real" | "seed"}`;operator 起。改动客户端重拉 feed 生效。
|
||
|
||
## 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`=数量 / 金额非法。
|
||
|
||
## POST /admin/api/marquee-seeds/batch-delete — 批量删除(带审计)
|
||
对选中的多条种子一次删除(一个事务 + 一条审计)。
|
||
- 入参 `OpsMarqueeSeedBatchDelete`:`ids`(int 数组;空数组 = no-op;不存在的 id 自动跳过)
|
||
- 出参 `200`:`{"deleted": <实际删除条数>}`
|
||
|
||
## POST /admin/api/marquee-seeds/batch-enable — 批量启用 / 停用(带审计)
|
||
对选中的多条种子一次置启用态。
|
||
- 入参 `OpsMarqueeSeedBatchEnable`:`ids`(int 数组)、`enabled`(bool)
|
||
- 出参 `200`:`{"updated": <实际更新条数>}`
|
||
|
||
## 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` / `batch_delete` / `batch_enable`)。预览为只读,任意已登录 admin 可用。
|
||
- 改动客户端**进首页 / 回前台**重拉 feed 时生效。
|