kol-insight/doc/PRD.md

KOL Insight - 产品需求文档 (PRD)

文档信息

项目	内容
版本	v1.0
创建日期	2025-01-28
状态	草稿

1. 产品概述

1.1 产品背景

在 KOL 营销领域，运营人员需要频繁查询达人视频数据以评估投放效果、计算投放成本。现有的云图平台虽然提供了数据，但缺乏批量查询和成本预估能力，导致运营人员需要手动逐条查询和计算，效率低下。

KOL Insight 旨在解决这一痛点，提供批量数据查询和智能成本预估功能，帮助运营人员快速获取决策所需的数据。

1.2 产品定位

• 目标用户：KOL 营销运营人员、投放优化师、品牌方
• 核心价值：批量查询 KOL 视频数据，自动计算预估 CPM 和看后搜成本
• 差异化优势：支持多种查询方式（星图ID/达人ID/昵称），自动计算关键成本指标

1.3 产品目标

目标	指标	衡量方式
提升查询效率	单次可批量查询多个 KOL	对比手动查询耗时
降低计算错误	自动计算预估指标准确率 100%	人工抽检验证
提高数据可用性	支持数据导出	导出功能完整性

2. 用户故事

2.1 用户角色定义

角色	描述	核心目标	痛点
运营人员	负责 KOL 投放执行与数据分析的一线人员	快速获取 KOL 视频表现数据	逐条查询效率低，成本计算繁琐
投放优化师	负责投放策略优化的专业人员	评估投放 ROI，优化投放策略	数据分散，难以横向对比

2.2 用户故事列表

P0 - 核心故事

ID	用户故事	验收标准
US-001	作为运营人员，我想要批量输入星图ID查询KOL数据，以便快速获取多个达人的视频表现	1. 支持批量输入星图ID（换行分隔） 2. 精准匹配 star_id 字段 3. 返回完整视频数据列表
US-002	作为运营人员，我想要通过达人unique_id查询数据，以便根据达人ID快速定位数据	1. 支持批量输入达人unique_id 2. 精准匹配 star_unique_id 字段 3. 返回对应视频数据
US-003	作为运营人员，我想要通过达人昵称模糊搜索，以便在不知道精确ID时也能找到数据	1. 支持输入达人昵称 2. 模糊匹配 star_nickname 字段 3. 返回所有匹配结果

| US-004 | 作为运营人员，我想要看到预估自然CPM和看后搜人数成本，以便评估投放效果 | 1. 自动计算预估自然CPM
2. 自动计算预估自然看后搜人数
3. 自动计算预估自然看后搜人数成本
4. 数据展示在结果列表中 |

P1 - 重要故事

ID	用户故事	验收标准
US-005	作为运营人员，我想要导出查询结果，以便在 Excel 中进一步分析或汇报	1. 支持导出为 Excel/CSV 格式 2. 导出数据包含所有查询字段 3. 中文列名清晰可读
US-006	作为运营人员，我想要看到视频的完整数据指标，以便全面了解视频表现	1. 展示所有核心指标（曝光、互动、A3率等） 2. 数据格式清晰易读

P2 - 次要故事

ID	用户故事	验收标准
US-007	作为运营人员，我想要点击视频链接直接跳转，以便快速查看原视频	1. 视频链接可点击 2. 新窗口打开视频页面

P0 - 视频分析增强

ID	用户故事	验收标准
US-008	作为运营人员，我想要查看视频的详细分析数据（触达、A3、搜索、费用、成本指标），以便全面评估视频投放效果	1. 调用巨量云图API获取实时数据 2. 展示6大类25+指标 3. 成本指标自动计算 4. A3指标更新到数据库

2.3 用户旅程

核心用户旅程：批量查询 KOL 数据

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    触发点       │     │   输入查询条件   │     │   查看结果      │     │   导出数据      │
│  需要KOL数据    │ ──▶ │  批量输入ID/昵称 │ ──▶ │  浏览数据列表   │ ──▶ │  下载Excel/CSV  │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │                       │
        ▼                       ▼                       ▼                       ▼
   "需要快速获取        "选择查询方式，      "系统自动计算       "数据可用于
    多个达人数据"        粘贴ID列表"          CPM等指标"          汇报和分析"

用户从需要 KOL 数据开始，选择合适的查询方式（星图ID/达人ID/昵称），批量输入查询条件后提交查询。系统返回结果列表，自动计算预估 CPM 和看后搜成本等指标。用户可浏览数据，需要时导出为 Excel 或 CSV 文件。

3. 功能需求

3.1 功能架构

KOL Insight
├── 数据查询模块
│   ├── 星图ID精准查询
│   ├── 达人unique_id精准查询
│   └── 达人昵称模糊查询
├── 数据计算模块
│   ├── 预估自然CPM计算
│   ├── 预估自然看后搜人数计算
│   └── 预估自然看后搜人数成本计算
├── 数据展示模块
│   ├── 结果列表展示
│   └── 视频链接跳转
├── 数据导出模块
│   └── Excel/CSV导出
└── 视频分析模块 (NEW)
    ├── SessionID池管理
    ├── 巨量云图API集成
    ├── 实时数据获取与更新
    └── 视频分析报表展示

3.2 功能详情

3.2.1 数据查询模块

功能点	描述	关联用户故事	优先级	验收标准
星图ID查询	批量输入星图ID，精准匹配 star_id 字段	US-001	P0	支持批量输入，精准匹配，返回完整数据
达人ID查询	批量输入达人unique_id，精准匹配 star_unique_id 字段	US-002	P0	支持批量输入，精准匹配，返回完整数据
昵称模糊查询	输入达人昵称，模糊匹配 star_nickname 字段	US-003	P0	支持包含匹配，返回所有匹配结果

3.2.2 数据计算模块

功能点	描述	关联用户故事	优先级	验收标准
预估自然CPM	公式：estimated_video_cost / natural_play_cnt * 1000	US-004	P0	计算结果准确，单位为元/千次曝光
预估自然看后搜人数	公式：natural_play_cnt / total_play_cnt * after_view_search_uv	US-004	P0	计算结果准确，单位为人数
预估自然看后搜人数成本	公式：estimated_video_cost / 预估自然看后搜人数	US-004	P0	计算结果准确，单位为元/人

3.2.3 数据展示模块

功能点	描述	关联用户故事	优先级	验收标准
结果列表展示	展示查询结果的完整数据表格	US-006	P1	包含所有指标字段，格式清晰
视频链接跳转	点击视频链接跳转到原视频页面	US-007	P2	链接可点击，新窗口打开

3.2.4 数据导出模块

功能点	描述	关联用户故事	优先级	验收标准
数据导出	将查询结果导出为 Excel/CSV 格式	US-005	P1	文件可下载，数据完整，中文列名

3.2.5 视频分析模块

功能点	描述	关联用户故事	优先级	验收标准
SessionID池管理	从内部API获取Cookie列表，随机选取sessionid用于请求	US-008	P0	1. 调用内部API获取100个sessionid 2. 随机选取机制实现 3. 失败自动切换重试（最多3次）
巨量云图API封装	调用GetContentMaterialAnalysisInfo获取视频分析数据	US-008	P0	1. 正确构造请求参数 2. 超时设置10秒 3. 错误处理和日志记录
视频分析接口	GET /api/v1/videos/{item_id}/analysis	US-008	P0	1. 返回6大类指标 2. 计算指标准确 3. 除零返回null
数据库A3指标更新	从API获取数据后更新数据库对应字段	US-008	P1	1. 更新total_new_a3_cnt 2. 更新heated_new_a3_cnt 3. 更新natural_new_a3_cnt 4. 更新total_cost
视频分析报表	前端展示6大类25+指标	US-008	P1	1. 基础信息展示 2. 触达/A3/搜索/费用/成本指标展示 3. 数值格式化

4. 非功能需求

4.1 性能需求

指标	要求	说明
查询响应时间	≤ 3秒	100条以内的批量查询
页面加载时间	≤ 2秒	首页加载
导出响应时间	≤ 5秒	1000条以内的数据导出

4.2 安全需求

• 数据库连接使用安全凭证，不在代码中硬编码
• 查询输入需进行 SQL 注入防护
• 敏感配置通过环境变量管理

4.3 兼容性需求

平台/环境	支持版本
浏览器	Chrome/Edge/Firefox 最新版
Python	3.9+ 及以上
PostgreSQL	14.x 及以上
Node.js（前端构建）	18.x 及以上

4.4 可用性需求

• 系统可用性目标：99%（工作时间）
• 提供基本的错误提示，便于用户理解问题原因

5. 数据需求

5.1 数据模型

┌─────────────────────────────────────────────────────────────────┐
│                    视频数据表 (kol_videos)                       │
├─────────────────────────────────────────────────────────────────┤
│ 基础信息                                                        │
│   item_id (视频ID) [主键]                                       │
│   title (视频标题)                                              │
│   star_id (星图ID) [索引]                                       │
│   star_unique_id (达人unique_id) [索引]                         │
│   star_nickname (达人昵称) [索引]                                │
│   video_url (视频链接)                                          │
│   publish_time (发布时间)                                       │
├─────────────────────────────────────────────────────────────────┤
│ 曝光指标                                                        │
│   natural_play_cnt (自然曝光数) ★ 计算用                         │
│   heated_play_cnt (加热曝光数)                                   │
│   total_play_cnt (总曝光数) ★ 计算用                             │
├─────────────────────────────────────────────────────────────────┤
│ 互动指标                                                        │
│   total_interact (总互动)                                       │
│   like_cnt (点赞)                                               │
│   share_cnt (转发)                                              │
│   comment_cnt (评论)                                            │
├─────────────────────────────────────────────────────────────────┤
│ 效果指标                                                        │
│   new_a3_rate (新增A3率)                                        │
│   after_view_search_uv (看后搜人数) ★ 计算用                     │
│   return_search_cnt (回搜次数)                                   │
├─────────────────────────────────────────────────────────────────┤
│ 商业信息                                                        │
│   industry_id (合作行业ID)                                      │
│   industry_name (合作行业)                                      │
│   brand_id (合作品牌ID) → 需调用品牌API获取名称                   │
│   estimated_video_cost (预估视频价格) ★ 计算用                   │
└─────────────────────────────────────────────────────────────────┘

★ 标记字段为计算预估指标所需的关键字段

5.2 数据规范

字段	类型	说明	校验规则
star_id	string	星图ID	非空
star_unique_id	string	达人唯一标识	非空
star_nickname	string	达人昵称	非空
item_id	string	视频ID	非空，唯一
曝光数	integer	各类曝光数据	≥ 0
互动数	integer	各类互动数据	≥ 0
预估视频价格	decimal	预估价格	≥ 0

6. 接口需求

6.1 外部接口

接口	用途	提供方
PostgreSQL	数据存储与查询	自建数据库
品牌API	根据品牌ID获取品牌名称	内部API (api.internal.intelligrow.cn)
Cookie池API	获取巨量云图SessionID列表	内部API (api.internal.intelligrow.cn)
巨量云图API	获取视频分析数据	巨量云图 (yuntu.oceanengine.com)

品牌API详情：

• 接口地址：/v1/yuntu/brands/{brand_id}
• 请求方式：GET
• 用途：根据合作品牌ID（brand_id）查询品牌名称
• 文档：https://api.internal.intelligrow.cn/docs#/云图

品牌API认证与响应格式：

• 认证方式：Bearer Token（Authorization: Bearer {token}）
• Token配置：通过环境变量 BRAND_API_TOKEN 配置
• 响应格式：

{
  "total": 1,
  "last_updated": "2025-12-30T11:28:40.738185",
  "has_more": 0,
  "data": [
    {"industry_id": 20, "industry_name": "母婴", "brand_id": 533661, "brand_name": "Giving/启初"}
  ]
}

• 解析方式：从 data[0].brand_name 获取品牌名称

Cookie池API详情：

• 接口地址：/v1/yuntu/get_cookie
• 请求方式：GET
• 认证方式：Bearer Token（Authorization: Bearer {YUNTU_API_TOKEN}）
• 用途：获取巨量云图认证信息列表（aadvid + auth_token）
• 使用方式：随机选取任意一组 aadvid/auth_token，避免限流
• 示例：

curl -X 'GET' \
  'https://api.internal.intelligrow.cn/v1/yuntu/get_cookie?page=1&page_size=100' \
  -H 'Authorization: Bearer {YUNTU_API_TOKEN}'

• 响应关键字段：
  • data[].aadvid - 云图API的URL参数
  • data[].auth_token - Cookie头完整值（格式：sessionid=xxx）

巨量云图API详情：

• 接口地址：POST /yuntu_common/api/content/trigger_analysis/GetContentMaterialAnalysisInfo?aadvid={AADVID}
• 基础URL：https://yuntu.oceanengine.com
• 认证方式：Cookie头直接使用 auth_token 完整值
• 用途：获取视频触达、A3、搜索、费用等分析数据
• 请求参数：

{
  "is_my_video": "0",
  "object_id": "{item_id}",
  "object_type": 2,
  "start_date": "{YYYYMMDD格式}",
  "end_date": "{start_date+30天,YYYYMMDD格式}",
  "assist_type": 3,
  "assist_video_type": 3,
  "industry_id_list": ["{数据库中视频的industry_id,字符串格式}"],
  "trigger_point_id_list": ["610000", "610300", "610301"]
}

• ⚠️ 参数格式要求：
  • 日期格式必须为 YYYYMMDD（如 20251014），不是 YYYY-MM-DD
  • industry_id_list 使用数据库中视频的 industry_id，传字符串数组
  • Cookie 头直接使用 auth_token 值（已包含 sessionid=xxx）
• 关键响应字段：
  • data.a3_increase_cnt - 新增A3（字符串类型）
  • data.ad_a3_increase_cnt - 加热新增A3（字符串类型）
  • data.natural_a3_increase_cnt - 自然新增A3（字符串类型）
  • data.cost - 总花费（单位可能是分）

6.2 内部接口

接口	方法	用途	说明
/api/v1/query	POST	批量查询KOL视频数据	FastAPI 后端服务提供
/api/v1/export	GET	导出查询结果为Excel/CSV	FastAPI 后端服务提供
/api/v1/videos/{item_id}/analysis	GET	获取单个视频分析数据	FastAPI 后端服务提供 (NEW)

API 架构说明：

• 后端采用 FastAPI 框架，提供 RESTful API
• 前端（Next.js）通过 HTTP 请求调用后端 API
• API 版本管理：使用 /api/v1/ 前缀
• 跨域支持：FastAPI 配置 CORS 中间件

7. 约束与依赖

7.1 技术约束

约束	说明	影响
前端技术栈	React + Next.js (App Router)	前端技术选型固定
后端技术栈	Python FastAPI + PostgreSQL	后端技术选型固定，前后端分离部署
部署方式	Docker（推荐） / PM2（前端） + Gunicorn/Uvicorn（后端）	运维方式固定，需分别部署前后端服务

7.2 业务约束

• 数据来源于云图平台，需确保数据同步的及时性和准确性
• 查询功能仅用于内部运营分析，不对外开放

7.3 外部依赖

依赖	说明
云图数据源	视频数据需从云图平台同步
PostgreSQL 数据库	依赖数据库服务可用性
品牌API	依赖内部API服务获取品牌名称

8. 里程碑规划

Phase 1 - MVP            Phase 2 - 优化
     │                        │
     ▼                        ▼
┌──────────┐            ┌──────────┐
│   MVP    │  ────────▶ │   v1.1   │
│ 核心查询  │            │ 性能优化  │
└──────────┘            └──────────┘
  待定日期                待定日期

阶段	目标	交付物
MVP	完成核心查询和计算功能	可用的批量查询系统，支持数据导出
v1.1	性能优化和体验提升	更快的查询速度，更好的用户体验

9. 风险评估

风险	可能性	影响	应对措施
数据同步延迟	中	中	建立数据同步监控机制
大批量查询性能问题	中	中	设置批量查询上限，优化数据库索引
数据库连接不稳定	低	高	实现连接池和重试机制
品牌API不可用	低	中	缓存品牌数据，降级显示品牌ID

附录

A. 术语表

术语	定义
KOL	Key Opinion Leader，关键意见领袖，即达人/网红
星图ID	巨量星图平台的达人唯一标识
unique_id	达人在平台的唯一标识符
CPM	Cost Per Mille，每千次曝光成本
看后搜	用户观看视频后进行搜索的行为
A3率	用户深度互动率指标
自然曝光	非付费推广获得的曝光量
加热曝光	通过付费推广获得的曝光量
natural_play_cnt	自然曝光次数，用于计算预估自然CPM
total_play_cnt	总曝光次数，包含自然+加热曝光
estimated_video_cost	预估视频价格，用于计算成本指标
after_view_search_uv	看后搜用户数，观看视频后进行搜索的独立用户数

B. 输出字段完整列表

中文名	字段名	说明
视频ID	item_id	主键
视频标题	title	-
爆文类型	viral_type	-
视频链接	video_url	-
新增A3率	new_a3_rate	-
看后搜人数	after_view_search_uv	-
回搜次数	return_search_cnt	-
自然曝光数	natural_play_cnt	计算用
加热曝光数	heated_play_cnt	-
总曝光数	total_play_cnt	计算用
总互动	total_interact	-
点赞	like_cnt	-
转发	share_cnt	-
评论	comment_cnt	-
合作行业ID	industry_id	-
合作行业	industry_name	-
合作品牌ID	brand_id	需调用品牌API
合作品牌	brand_name	从品牌API获取
发布时间	publish_time	-
达人昵称	star_nickname	索引字段
达人unique_id	star_unique_id	索引字段
预估视频价格	estimated_video_cost	计算用
预估自然CPM	(计算字段)	= estimated_video_cost / natural_play_cnt * 1000
预估自然看后搜人数	(计算字段)	= natural_play_cnt / total_play_cnt * after_view_search_uv
预估自然看后搜人数成本	(计算字段)	= estimated_video_cost / 预估自然看后搜人数

C. 参考文档

• RequirementsDoc.md