243 lines
8.2 KiB
Markdown
243 lines
8.2 KiB
Markdown
# 星图达人视频传播数据导出需求文档
|
||
|
||
## 目标
|
||
|
||
在现有星图达人 CSV 导出流程中，额外调用星图接口 `get_author_spread_info`，获取达人视频传播相关指标，并把这些指标追加到导出表格中。
|
||
|
||
因为同一个指标在不同参数组合下含义不同，所以导出字段名必须带上参数前缀。例如：
|
||
|
||
```text
|
||
只看指派_排除营销流量_星图视频_近30天_完播率
|
||
```
|
||
|
||
这个字段表示：它不是普通的“完播率”，而是在“只看指派 + 排除营销流量 + 星图视频 + 近30天”这组参数下获取到的完播率。
|
||
|
||
字段名前缀只体现会造成数据差异、且在当前导出中可变化的参数。固定不变的参数不用写进字段名前缀。
|
||
|
||
## 接口
|
||
|
||
调用接口：
|
||
|
||
```text
|
||
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` 接口返回值中获取：
|
||
|
||
```text
|
||
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` 的不同设置会导致接口返回的数据不同。
|
||
|
||
个人视频固定参数：
|
||
|
||
```text
|
||
type=1
|
||
flow_type=0
|
||
only_assign=false
|
||
```
|
||
|
||
个人视频可变参数：
|
||
|
||
```text
|
||
range=2 或 range=3
|
||
```
|
||
|
||
因为个人视频里 `only_assign=false` 和 `flow_type=0` 是固定参数，所以它们不写入字段名前缀。个人视频字段只需要体现视频类型和时间范围，例如：
|
||
|
||
```text
|
||
个人视频_近30天_完播率
|
||
个人视频_近90天_完播率
|
||
```
|
||
|
||
星图视频可以配置多组参数。每一组参数都会调用一次 `get_author_spread_info`，并为这一组参数生成 7 个导出字段。
|
||
|
||
例如某一组参数是：
|
||
|
||
```text
|
||
only_assign=true
|
||
flow_type=1
|
||
type=2
|
||
range=2
|
||
```
|
||
|
||
那么这一组会生成：
|
||
|
||
- `只看指派_排除营销流量_星图视频_近30天_完播率`
|
||
- `只看指派_排除营销流量_星图视频_近30天_播放量中位数`
|
||
- `只看指派_排除营销流量_星图视频_近30天_互动率`
|
||
- `只看指派_排除营销流量_星图视频_近30天_作品平均时长`
|
||
- `只看指派_排除营销流量_星图视频_近30天_作品平均评论数`
|
||
- `只看指派_排除营销流量_星图视频_近30天_作品平均点赞数`
|
||
- `只看指派_排除营销流量_星图视频_近30天_作品平均转发数`
|
||
|
||
字段名规则固定为：
|
||
|
||
```text
|
||
<会变化的参数文案>_<视频类型文案>_<时间范围文案>_<指标名>
|
||
```
|
||
|
||
对星图视频来说，`only_assign`、`flow_type`、`range` 都可能变化，所以字段名要保留这些参数。对个人视频来说，只有 `range` 变化，所以字段名不需要写 `不限指派` 和 `不排除营销流量`。
|
||
|
||
这里必须保留会变化参数的前缀，不能把不同参数组合下的同名指标合并。例如下面两个字段都叫“完播率”，但数据含义不同，必须作为两个独立字段导出：
|
||
|
||
```text
|
||
只看指派_排除营销流量_星图视频_近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` | 平均转发数 |
|
||
|
||
示例响应：
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
```
|
||
|
||
## 导出流程
|
||
|
||
1. 当前插件仍然先从星图达人搜索页收集达人列表。
|
||
2. 从 `search_for_author_square` 的 `authors[i].attribute_datas.id` 取出每个达人的星图 ID。
|
||
3. 用户导出 CSV 时，先按现有逻辑确定导出范围，例如当前页、前 5 页、前 10 页、全部或自定义页数。
|
||
4. 对导出范围内的每个达人，先按个人视频参数调用 `get_author_spread_info`：`type=1`、`flow_type=0`、`only_assign=false` 固定，`range` 按配置取值。
|
||
5. 如果配置了星图视频参数组合，再按每一组星图视频参数分别调用 `get_author_spread_info`。
|
||
6. 把每次接口返回值解析成 7 个指标。
|
||
7. CSV 保留原有字段顺序，在现有字段后追加这些带参数前缀的新字段。
|
||
|
||
## 失败处理
|
||
|
||
- 如果某个达人没有 `attribute_datas.id`，这一行的视频传播指标留空。
|
||
- 如果某个参数组合请求失败，这一组参数对应的 7 个字段留空。
|
||
- 如果接口响应结构异常，这一组参数对应的 7 个字段留空。
|
||
- 某个达人失败不能影响其他达人导出。
|
||
- 某组参数失败不能影响同一个达人的其他参数组导出。
|
||
|
||
## 性能要求
|
||
|
||
这个功能会产生比较多接口请求：
|
||
|
||
```text
|
||
请求数 = 导出的达人数量 * 参数组合数量
|
||
```
|
||
|
||
所以实现时需要：
|
||
|
||
- 做并发限制，避免一次性打太多请求。
|
||
- 保持最终 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。
|