intelligrow/star-chart-search-enhancer

Fork 0

wxs 121977fd0d feat: export author spread metrics

2026-06-29 16:06:14 +08:00

8.2 KiB

Raw Blame History

星图达人视频传播数据导出需求文档

目标

在现有星图达人 CSV 导出流程中，额外调用星图接口 get_author_spread_info，获取达人视频传播相关指标，并把这些指标追加到导出表格中。

因为同一个指标在不同参数组合下含义不同，所以导出字段名必须带上参数前缀。例如：

只看指派_排除营销流量_星图视频_近30天_完播率

这个字段表示：它不是普通的“完播率”，而是在“只看指派 + 排除营销流量 + 星图视频 + 近30天”这组参数下获取到的完播率。

字段名前缀只体现会造成数据差异、且在当前导出中可变化的参数。固定不变的参数不用写进字段名前缀。

接口

调用接口：

GET /gw/api/data_sp/get_author_spread_info

请求参数：

参数	含义
`o_author_id`	达人的星图 ID
`platform_source`	固定传 `1`
`platform_channel`	固定传 `1`
`type`	视频类型
`flow_type`	是否排除营销流量
`only_assign`	是否只看指派
`range`	数据时间范围

请求需要带上当前星图网页登录态，所以实现时请求要使用浏览器当前 cookie，也就是 credentials: "include"。

星图 ID 来源

o_author_id 需要从 search_for_author_square 接口返回值中获取：

authors[i].attribute_datas.id

如果同一行数据里同时存在顶层 star_id 和 attribute_datas.id，这个接口优先使用 attribute_datas.id 作为 o_author_id。

参数含义

only_assign

值	含义	字段名前缀
`true`	只看指派	`只看指派`
`false`	取消“只看指派”勾选	`不限指派`

flow_type

值	含义	字段名前缀
`1`	排除营销流量	`排除营销流量`
`0`	不排除营销流量	`不排除营销流量`

range

值	含义	字段名前缀
`2`	近 30 天	`近30天`
`3`	近 90 天	`近90天`

type

值	含义	字段名前缀
`1`	个人视频	`个人视频`
`2`	星图视频	`星图视频`

多组参数导出

第一版需要支持多组参数组合。

参数组合需要区分“个人视频”和“星图视频”两类处理：

type=1 个人视频：only_assign=false、flow_type=0 固定，只允许调整 range。
type=2 星图视频：需要支持多组参数组合，因为 only_assign、flow_type、range 的不同设置会导致接口返回的数据不同。

个人视频固定参数：

type=1
flow_type=0
only_assign=false

个人视频可变参数：

range=2 或 range=3

因为个人视频里 only_assign=false 和 flow_type=0 是固定参数，所以它们不写入字段名前缀。个人视频字段只需要体现视频类型和时间范围，例如：

个人视频_近30天_完播率
个人视频_近90天_完播率

星图视频可以配置多组参数。每一组参数都会调用一次 get_author_spread_info，并为这一组参数生成 7 个导出字段。

例如某一组参数是：

only_assign=true
flow_type=1
type=2
range=2

那么这一组会生成：

只看指派_排除营销流量_星图视频_近30天_完播率
只看指派_排除营销流量_星图视频_近30天_播放量中位数
只看指派_排除营销流量_星图视频_近30天_互动率
只看指派_排除营销流量_星图视频_近30天_作品平均时长
只看指派_排除营销流量_星图视频_近30天_作品平均评论数
只看指派_排除营销流量_星图视频_近30天_作品平均点赞数
只看指派_排除营销流量_星图视频_近30天_作品平均转发数

字段名规则固定为：

<会变化的参数文案>_<视频类型文案>_<时间范围文案>_<指标名>

对星图视频来说，only_assign、flow_type、range 都可能变化，所以字段名要保留这些参数。对个人视频来说，只有 range 变化，所以字段名不需要写 不限指派 和 不排除营销流量。

这里必须保留会变化参数的前缀，不能把不同参数组合下的同名指标合并。例如下面两个字段都叫“完播率”，但数据含义不同，必须作为两个独立字段导出：

只看指派_排除营销流量_星图视频_近30天_完播率
不限指派_不排除营销流量_星图视频_近30天_完播率

需要导出的指标

每一组参数都要导出下面 7 个指标：

导出字段指标名	接口响应字段	示例值	说明
完播率	`play_over_rate.value`	`2824`	按万分比理解，导出时建议显示为 `28.24%`
播放量中位数	`play_mid`，兜底 `item_rate.play_mid.value`	`10913233`	播放量中位数
互动率	`interact_rate.value`	`402`	按万分比理解，导出时建议显示为 `4.02%`
作品平均时长	`avg_duration`	`5600`	按百分之一秒理解，导出时显示为秒，例如 `56`
作品平均评论数	`comment_avg`	`7502`	平均评论数
作品平均点赞数	`like_avg`	`494458`	平均点赞数
作品平均转发数	`share_avg`	`188267`	平均转发数

示例响应：

{
  "avg_duration": "5600",
  "comment_avg": "7502",
  "interact_rate": {
    "overtake": 5312,
    "value": 402
  },
  "item_rate": {
    "play_mid": {
      "label": "",
      "overtake": 10000,
      "value": 10913233
    }
  },
  "like_avg": "494458",
  "play_mid": "10913233",
  "play_over_rate": {
    "overtake": 9584,
    "value": 2824
  },
  "share_avg": "188267"
}

导出流程

当前插件仍然先从星图达人搜索页收集达人列表。
从 search_for_author_square 的 authors[i].attribute_datas.id 取出每个达人的星图 ID。
用户导出 CSV 时，先按现有逻辑确定导出范围，例如当前页、前 5 页、前 10 页、全部或自定义页数。
对导出范围内的每个达人，先按个人视频参数调用 get_author_spread_info：type=1、flow_type=0、only_assign=false 固定，range 按配置取值。
如果配置了星图视频参数组合，再按每一组星图视频参数分别调用 get_author_spread_info。
把每次接口返回值解析成 7 个指标。
CSV 保留原有字段顺序，在现有字段后追加这些带参数前缀的新字段。

失败处理

如果某个达人没有 attribute_datas.id，这一行的视频传播指标留空。
如果某个参数组合请求失败，这一组参数对应的 7 个字段留空。
如果接口响应结构异常，这一组参数对应的 7 个字段留空。
某个达人失败不能影响其他达人导出。
某组参数失败不能影响同一个达人的其他参数组导出。

性能要求

这个功能会产生比较多接口请求：

请求数 = 导出的达人数量 * 参数组合数量

所以实现时需要：

做并发限制，避免一次性打太多请求。
保持最终 CSV 行顺序和原导出顺序一致。
给每个请求设置超时时间。
第一版不做激进重试，避免接口压力过大。

测试要求

需要补充测试覆盖：

get_author_spread_info URL 参数构造是否正确。
type=1 生成 个人视频 前缀。
type=2 生成 星图视频 前缀。
个人视频是否固定使用：type=1、flow_type=0、only_assign=false。
个人视频是否支持切换 range=2 和 range=3。
个人视频字段名前缀是否不包含固定参数 不限指派 和 不排除营销流量。
星图视频是否支持多组参数组合。
only_assign、flow_type、range 前缀是否正确。
是否从 attribute_datas.id 读取 o_author_id。
多组参数是否分别生成 7 个字段。
响应字段是否正确映射到 7 个导出指标。
接口失败时是否导出空字段。
多个达人并发请求完成顺序不一致时，最终 CSV 行顺序是否保持不变。

暂不做的事情

暂不新增页面上的参数配置 UI。
暂不改变星图搜索页原本的筛选条件。
暂不改变现有后端指标字段。
暂不改变批次提交 payload。

8.2 KiB Raw Blame History Unescape Escape