常驻三榜 — 前端对接

面向 C 端 和 管理后台。范围：硬币榜、粉丝新增榜、团队活跃值榜。周年庆 / 斋月假数据不在本方案。

业务日、周一切一律按 东七区（UTC+7）。不要用设备本地时区或 UTC 判断「今天」「本周一」。金额字段都是十进制 string，不要先转 number 再算。

1. 产品约定（两边都要懂）

展示分 = 真实分 + 已生效加成（applied）。C 端看到的分数已经含加成，没有单独的「假分」字段。

规则	说明
只设名次	运营填「至少第 N」，加成由系统算，后台只读
只加一次	执行当下把人推到至少第 N，然后冻结。不追分、不钉死第 N。真人继续入账可以超过
加成记在自然日	日榜 = 当天 `applied`；周榜 = 本周一到今天之和；总榜 = 历史已生效之和
控周 / 总会抬今日日榜	加成只有一套账，切 Tab 数字对得上。后台会返回「日榜大约第几」
未来日 10:00 才加	预设只存那天的日榜名次；东七区当天 10:00 执行（10:05 / 10:15 会重试）。0 点不执行
同一日同一榜同一名次	已被别人占用则保存失败
过往日期	锁定，不能改、不能停用
停用	已生效加成保留，人不会瞬间掉榜。本轮没有「缓降撤榜」

没有「慢慢爬 / 立刻到位 / 停止追分」选项，后台不要做这三项控件。

2. C 端（路径和字段不变）

三个 List HTTP path、proto、请求参数都不变。变化是：入账后几秒内上榜（不再等整点 Cron）；今天还没人得分时日榜是 空列表，不是报错。

鉴权与现网相同，需登录。

榜	方法 / 路径	RPC	请求
硬币	`POST /v1/point/rank/list`	`ListPointRank`	`{ "type": 1\\|2\\|3 }`
粉丝新增	`POST /v1/fans/rank/list`	`ListFansRank`	`{ "type": 1\\|2\\|3 }`
团队活跃值	`POST /v1/active_value/rank/list`	`ListActiveValueRank`	`{ "type": 1\\|2\\|3 }`

type：

值	含义	周期
`1` `TYPE_TODAY`	今日	东七区当天 0 点起
`2` `TYPE_WEEK`	本周	东七区本周一 0 点起
`3` `TYPE_TOTAL`	总榜	累计

type = 0 会参数错误。最多 100 条；封号 / 非正常用户不出现在列表里，rank 按返回列表重排（1 起）。

同一人切 Tab 时，展示分满足：周 ≥ 今日，总 ≥ 周（加成汇总一致）。不要自己用三日相加去对总榜。

空榜：items 空、total 为 0。不要当成接口失败，也不要自己补假数据。

下拉刷新即可拿到最新名次；入账后若要立刻看到自己，延迟 1～2 秒再拉一次足够。

2.1 硬币榜 `PointRankItem`

{
  "rank": 1,
  "amount": "123.4500",
  "user": { "...": "UserFans" },
  "playlets": []
}

字段	说明
`amount`	该周期展示分（真实收入 + 加成），string
`user.tips_level`	可能被后台控榜档案覆盖，直接展示即可
`playlets`	该周期内支持过的短剧，最多 5 个；逻辑与现网相同

2.2 粉丝榜 `FansRankItem`

字段	说明
`fans_count`	该周期 1～5 层新增粉丝（铁粉 + 间推合计，不含加成）
`total_fans_count`	总 1～5 层粉丝

名次按展示分排（真实 1～5 层 + 加成）。不要再读 direct_count / total_direct_count，这两个字段已删除。

2.3 活跃值榜 `ActiveValueRankItem`

字段	说明
`active_value`	该周期展示分（自己 + 向上 5 层团队增量 + 加成），string
`total_active_value`	总榜展示分；没有总榜分时回落用户身上的活跃值

2.4 家族页名次（顺带修了现网空名次）

项	值
路径	`POST /v1/family/data/overview/get`
字段	`active_value_rank`

现在读的是 活跃值日榜 的真实名次（ZREVRANK）。未上榜为 0。不改请求。

3. 管理后台（新页，新接口）

常驻三榜控榜走下面 4 个接口。旧的 ListUserFakeRankData / UpdateUserFakeRankData 只留给周年庆，入口请标明「仅周年庆」；不要再拿它们改硬币 / 粉丝 / 活跃值三榜。

鉴权与其它 /v1/man/* 相同。

3.1 列表 `POST /v1/man/rank_control/list`

RPC：ListRankControls

{ "board": 0 }

字段	说明
`board`	`0` 或不传 = 三榜都返回；`1` 硬币 / `2` 粉丝 / `3` 活跃值

响应只有 已经保存过的控榜行，不是 14 天空日历。前端自己铺格子：

起点：东七区 本周一 0 点
终点：再加 13 天（本周 7 天 + 下周 7 天）
把 items[] 按 date（东七区自然日）+ board + user_id 填进格子

{
  "items": [
    {
      "user_id": 10001,
      "board": 1,
      "date": 1756771200,
      "target_rank": 3,
      "target_boost": "12.0001",
      "applied": "12.0001",
      "applied_at": 1756807200,
      "enabled": true,
      "current_rank": 3,
      "estimated_daily_rank": 1,
      "tips_level": 0,
      "support_playlet_count": 0,
      "period": 1
    }
  ]
}

字段	说明
`date`	unix 秒。按东七区取自然日展示，不要按浏览器时区
`target_rank`	当时目标：至少第 N
`target_boost`	系统算出的目标加成，只读，不要做成输入框
`applied`	已生效加成。未来日未执行时为 `"0"`
`applied_at`	生效时间 unix；`0` = 还没执行（未来日或 10:00 尚未跑完）
`enabled`	`false` = 已停用，加成仍保留
`current_rank`	当前实际名次（按这条当时设的 `period`）。未来日或未上榜为 `0`
`estimated_daily_rank`	控周榜 / 总榜后，今日日榜大约第几。设日榜时与 `current_rank` 接近
`period`	设名次时用的周期；未来日固定为日榜
`tips_level` / `support_playlet_count`	C 端展示覆盖，未设则为 0

列表建议展示两列名次：目标第 N / 当前第 X。当前第 X 比目标差，说明已经被真人超过，这是预期，不是 bug。

3.2 设名次 `POST /v1/man/rank_control/set`

RPC：SetRankTarget

{
  "user_id": 10001,
  "board": 1,
  "period": 1,
  "date": 1756771200,
  "target_rank": 3,
  "tips_level": 0,
  "support_playlet_count": 0
}

字段	必填	说明
`user_id`	是	被控榜用户
`board`	是	`1` / `2` / `3`，不能 `0`
`period`	今天有效	`1` 日 / `2` 周 / `3` 总。不传按日榜。未来日会被忽略，只存日榜名次
`date`	是	unix，后端按东七区取自然日。建议传那天东七区 0 点的 unix
`target_rank`	是	≥ 1，至少第 N
`tips_level`	否	`0` 表示不改覆盖
`support_playlet_count`	否	`0` 表示不改

board / period 枚举：

值	board	period
0	未指定（list 可用，set 不可）	未指定 → 日榜
1	硬币	日榜
2	粉丝新增	周榜
3	团队活跃值	总榜

今天： 当场按 period 对应的榜算缺口，加成记在今天，立刻上榜并冻结。响应里看 current_rank、estimated_daily_rank。

未来日： 只存当天日榜名次，applied_at = 0，到那天 10:00 才加分。UI 上 period 请锁成日榜，不要让人选「下周周榜第 3」。

同一天再设： 按新目标对已有 applied 做差值（可以减），不是再累加一笔。

保存成功返回 { "item": { ... } }，结构同列表单项。控周 / 总时务必展示 estimated_daily_rank（例如：「日榜大约会变成第 X」）。

3.3 停用 `POST /v1/man/rank_control/disable`

{ "user_id": 10001, "board": 1, "date": 1756771200 }

空响应。已生效 applied 不清。过往日期会失败。

3.4 重建榜 `POST /v1/man/rank_control/rebuild`（应急）

{ "board": 1, "period": 0 }

字段	说明
`board`	必填，重建哪一张榜
`period`	`0` 或不传 = 日 + 周 + 总；否则只重建该周期

给运营 / 开发应急用（分数对不齐、Redis 丢了）。会扫库，可能较慢，按钮要二次确认，不要进日常设名次流程。成功空响应。

3.5 错误码

业务码	场景	建议文案
`27001` `CODE_RANK_TARGET_OCCUPIED`	该日该榜该名次已被别人占用	该名次已被占用，请换一个
`27002` `CODE_RANK_DATE_LOCKED`	过往日期不可改 / 不可停用	过往日期已锁定
`CODE_USER_NOT_FOUND`	`user_id` 不存在	用户不存在
`CODE_NOT_FOUND`	停用时没有这条控榜	记录不存在
`CODE_ARGUMENT`	参数非法，或正在加分请重试	参数错误 / 请稍后重试
`CODE_DATABASE`	内部错误	请稍后重试

4. 后台页面怎么铺（建议）

顶部 Tab：硬币 / 粉丝 / 活跃值（对应 board），或一张表三榜都展示。
横向 14 天：本周一～下周日，标出「今天」。今天之前的格子只读。
每个格子：用户、目标第 N、当前第 X、已生效加成、是否已执行（看 applied_at）。
今天可设 period（日 / 周 / 总）；未来日只能设日榜第 N。
保存后如果是周 / 总，提示「日榜大约第 estimated_daily_rank」。
不要提供手填加成、不要每周一键套同一套数、不要「钉死第 N」。

今天 00:00–10:00 未来日的格子还没执行，C 端是真榜，这是预期。10:00 之后刷新列表，applied_at 应非 0。

5. 验收（前端可自测）

C 端

入账 / 绑邀请后下拉，日 / 周 / 总名次几秒内变化；退款后硬币榜下降
今天 0 点刚过、还没人得分：日榜空列表
封号用户从榜上消失
切日 / 周 Tab，同一人分数周 ≥ 日

管理端

今天设第 3，保存后 C 端至少第 3；过一会儿被真人超过，当前名次变差，加成不变
同一天同一榜两个用户设同一名次：第二个失败 27001
改昨天：失败 27002
设未来某日第 1：列表 applied_at = 0；当天 10:00 后刷新应已生效
控周榜后，提示里的预估日榜名次有值，且今日日榜分数升高

常驻三榜 — 前端对接

1. 产品约定（两边都要懂）

2. C 端（路径和字段不变）

2.1 硬币榜 PointRankItem

2.2 粉丝榜 FansRankItem

2.3 活跃值榜 ActiveValueRankItem