txagent-y/docs/dev/admin-api/ADMIN-API-06-数据注水.md

ADMIN-API-06 数据注水（BOOST）

共 4 个接口：BOOST-01~04

注水规则

• boost 上限 = 真实数据的 3 倍
• 发布 7 天后自动停止（auto_stop_at）
• 真实数据超过 boost 值时自动停止
• C端展示外显数据 = 真实数据 + boost 数据（仅 is_active=1 时叠加）

---

BOOST-01 设置内容注水

项目	说明
接口路径	POST /admin/api/v1/boost/contents
接口用途	对指定内容设置注水数据（浏览量/点赞/收藏）
权限要求	运营专员
涉及表	content_boost, post, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: boost:manage）
2. 查询 post 表，校验内容存在且 status=2（已上架）（读）
3. 校验注水值不超过真实数据的 3 倍
4. 查询 content_boost 是否已有该 post_id 的记录（读）
   • 已有 → 更新注水值和 is_active=1（更新）
   • 没有 → 创建新记录，设置 auto_stop_at = post.published_at + 7天（写）
5. 设置 operated_by = 当前 admin_id（更新）
6. 写入 admin_operation_log（action: set_content_boost）（写）

请求参数（Body）：

字段	类型	必选	说明
postId	string	是	内容ID
boostViewCount	number	否	注水浏览量
boostLikeCount	number	否	注水点赞数
boostFavoriteCount	number	否	注水收藏数

响应数据：

字段	类型	说明
boostId	string	注水配置ID
postId	string	内容ID
boostViewCount	number	注水浏览量
boostLikeCount	number	注水点赞数
boostFavoriteCount	number	注水收藏数
autoStopAt	timestamp	自动停止时间

---

BOOST-02 关闭内容注水

项目	说明
接口路径	POST /admin/api/v1/boost/contents/:postId/close
接口用途	手动关闭某条内容的注水
权限要求	运营专员
涉及表	content_boost, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: boost:manage）
2. 查询 content_boost（post_id 匹配），校验 is_active=1（读）
3. 更新 is_active=0（更新）
4. 写入 admin_operation_log（action: close_content_boost）（写）

说明： 关闭后该内容外显数据 = 仅真实数据。

路径参数：

字段	类型	必选	说明
postId	string	是	内容ID

请求参数： 无

响应数据：

字段	类型	说明
postId	string	内容ID
isActive	boolean	注水状态：false

---

BOOST-03 设置创作者注水

项目	说明
接口路径	POST /admin/api/v1/boost/creators
接口用途	对指定创作者的粉丝数/订阅数进行注水
权限要求	运营专员
涉及表	creator_boost, user, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: boost:manage）
2. 查询 user 表，校验用户存在且 role=2（创作者）（读）
3. 查询 creator_boost 是否已有该 creator_id 的记录（读）
   • 已有 → 更新注水值和 is_active=1（更新）
   • 没有 → 创建新记录（写）
4. 设置 operated_by = 当前 admin_id（更新）
5. 写入 admin_operation_log（action: set_creator_boost）（写）

请求参数（Body）：

字段	类型	必选	说明
creatorId	string	是	创作者ID
boostFollowerCount	number	否	注水粉丝数
boostSubscriberCount	number	否	注水订阅数

响应数据：

字段	类型	说明
boostId	string	注水配置ID
creatorId	string	创作者ID
boostFollowerCount	number	注水粉丝数
boostSubscriberCount	number	注水订阅数

---

BOOST-04 查看注水状态列表

项目	说明
接口路径	GET /admin/api/v1/boost/list
接口用途	查看当前所有注水的内容/创作者列表及其注水值
权限要求	运营专员
涉及表	content_boost, creator_boost, post, user

接口逻辑：

1. 校验管理员权限（permission_key: boost:manage）
2. 根据 type 参数筛选：
   • type=content → 查询 content_boost（is_active=1），关联 post 获取内容信息（读）
   • type=creator → 查询 creator_boost（is_active=1），关联 user 获取创作者信息（读）
   • type 不传 → 合并查询两者
3. 支持分页

请求参数（Query）：

字段	类型	必选	说明
type	string	否	类型筛选：content/creator，不传为全部
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	注水列表
list[].boostId	string	注水配置ID
list[].type	string	类型：content/creator
list[].targetId	string	目标ID
list[].targetName	string	目标名称（内容标题/创作者昵称）
list[].boostValues	object	注水值
list[].boostValues.viewCount	number	注水浏览量（content类型）
list[].boostValues.likeCount	number	注水点赞数（content类型）
list[].boostValues.favoriteCount	number	注水收藏数（content类型）
list[].boostValues.followerCount	number	注水粉丝数（creator类型）
list[].boostValues.subscriberCount	number	注水订阅数（creator类型）
list[].autoStopAt	timestamp	自动停止时间（content类型）
list[].operatedBy	string	操作人
list[].createdAt	timestamp	创建时间
pagination	object	分页信息