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（换行分隔）<br>2. 精准匹配 star_id 字段<br>3. 返回完整视频数据列表 |
| US-002 | 作为运营人员，我想要通过达人unique_id查询数据，以便根据达人ID快速定位数据 | 1. 支持批量输入达人unique_id<br>2. 精准匹配 star_unique_id 字段<br>3. 返回对应视频数据 |
| US-003 | 作为运营人员，我想要通过达人昵称模糊搜索，以便在不知道精确ID时也能找到数据 | 1. 支持输入达人昵称<br>2. 模糊匹配 star_nickname 字段<br>3. 返回所有匹配结果 |
<!-- MODIFIED: 统一术语为"预估自然看后搜人数" -->
| US-004 | 作为运营人员，我想要看到预估自然CPM和看后搜人数成本，以便评估投放效果 | 1. 自动计算预估自然CPM<br>2. 自动计算预估自然看后搜人数<br>3. 自动计算预估自然看后搜人数成本<br>4. 数据展示在结果列表中 |

#### P1 - 重要故事

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

#### P2 - 次要故事

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

<!-- ITER: 2026-01-28 - 新增视频分析用户故事 -->
<!-- NEW START -->
#### P0 - 视频分析增强

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

### 2.3 用户旅程

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

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

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

## 3. 功能需求

### 3.1 功能架构

<!-- MODIFIED: 统一术语为"预估自然看后搜人数" -->
<!-- ITER: 2026-01-28 - 新增巨量云图视频分析模块 -->
```
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 数据计算模块

<!-- MODIFIED: 补充完整计算公式，统一术语为"预估自然看后搜人数" -->
| 功能点 | 描述 | 关联用户故事 | 优先级 | 验收标准 |
|--------|------|--------------|--------|----------|
| 预估自然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 | 文件可下载，数据完整，中文列名 |

<!-- ITER: 2026-01-28 - 新增巨量云图视频分析模块 -->
<!-- NEW START -->
#### 3.2.5 视频分析模块

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

## 4. 非功能需求

### 4.1 性能需求

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

### 4.2 安全需求

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

### 4.3 兼容性需求

<!-- MODIFIED: 后端改用 Python FastAPI，前端使用 Next.js -->
| 平台/环境 | 支持版本 |
|-----------|----------|
| 浏览器 | Chrome/Edge/Firefox 最新版 |
| Python | 3.9+ 及以上 |
| PostgreSQL | 14.x 及以上 |
| Node.js（前端构建） | 18.x 及以上 |

### 4.4 可用性需求

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

## 5. 数据需求

### 5.1 数据模型

<!-- MODIFIED: 补充完整字段名，明确计算公式所需字段 -->
```
┌─────────────────────────────────────────────────────────────────┐
│                    视频数据表 (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 外部接口

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

<!-- NEW START -->
**品牌API详情**：
- 接口地址：`/v1/yuntu/brands/{brand_id}`
- 请求方式：GET
- 用途：根据合作品牌ID（brand_id）查询品牌名称
- 文档：https://api.internal.intelligrow.cn/docs#/云图
<!-- NEW END -->

<!-- ITER: 2026-01-28 - 修复品牌API响应解析+添加认证 -->
<!-- NEW START -->
**品牌API认证与响应格式**：
- 认证方式：Bearer Token（`Authorization: Bearer {token}`）
- Token配置：通过环境变量 `BRAND_API_TOKEN` 配置
- 响应格式：
```json
{
  "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` 获取品牌名称
<!-- NEW END -->

<!-- ITER: 2026-01-28 - 新增巨量云图API和Cookie池API -->
<!-- ITER: 2026-01-28 - 修复API参数格式问题 -->
<!-- NEW START -->
**Cookie池API详情**：
- 接口地址：`/v1/yuntu/get_cookie`
- 请求方式：GET
- 认证方式：Bearer Token（`Authorization: Bearer {YUNTU_API_TOKEN}`）
- 用途：获取巨量云图认证信息列表（aadvid + auth_token）
- **使用方式**：随机选取任意一组 aadvid/auth_token，避免限流
- 示例：
```bash
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、搜索、费用等分析数据
- 请求参数：
```json
{
  "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` - 总花费（单位可能是分）
<!-- NEW END -->

### 6.2 内部接口

<!-- MODIFIED: 补充核心API端点，改用 FastAPI RESTful 风格 -->
| 接口 | 方法 | 用途 | 说明 |
|------|------|------|------|
| /api/v1/query | POST | 批量查询KOL视频数据 | FastAPI 后端服务提供 |
| /api/v1/export | GET | 导出查询结果为Excel/CSV | FastAPI 后端服务提供 |
| /api/v1/videos/{item_id}/analysis | GET | 获取单个视频分析数据 | FastAPI 后端服务提供 (NEW) |

<!-- NEW START -->
**API 架构说明**：
- 后端采用 FastAPI 框架，提供 RESTful API
- 前端（Next.js）通过 HTTP 请求调用后端 API
- API 版本管理：使用 `/api/v1/` 前缀
- 跨域支持：FastAPI 配置 CORS 中间件
<!-- NEW END -->

## 7. 约束与依赖

### 7.1 技术约束

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

### 7.2 业务约束

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

### 7.3 外部依赖

<!-- MODIFIED: 补充品牌API依赖 -->
| 依赖 | 说明 |
|------|------|
| 云图数据源 | 视频数据需从云图平台同步 |
| PostgreSQL 数据库 | 依赖数据库服务可用性 |
| 品牌API | 依赖内部API服务获取品牌名称 |

## 8. 里程碑规划

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

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

## 9. 风险评估

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

## 附录

### A. 术语表

<!-- MODIFIED: 补充计算公式相关术语 -->
| 术语 | 定义 |
|------|------|
| 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. 输出字段完整列表

<!-- MODIFIED: 补全所有输出字段的数据库字段名 -->
| 中文名 | 字段名 | 说明 |
|--------|--------|------|
| 视频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