ac0f086821
- 完成 T-001A: 前端项目初始化 (Next.js 14 + TypeScript + Tailwind CSS) - 完成 T-001B: 后端项目初始化 (FastAPI + SQLAlchemy + asyncpg) - 完成 T-002: 数据库配置 (KolVideo 模型 + 索引 + 测试) - 完成 T-003: 基础 UI 框架 (Header/Footer 组件 + 品牌色系) - 完成 T-004: 环境变量配置 (前后端环境变量) Co-Authored-By: Claude <noreply@anthropic.com>
366 lines
18 KiB
Markdown
366 lines
18 KiB
Markdown
# 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. 新窗口打开视频页面 |
|
||
|
||
### 2.3 用户旅程
|
||
|
||
**核心用户旅程：批量查询 KOL 数据**
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ 触发点 │ │ 输入查询条件 │ │ 查看结果 │ │ 导出数据 │
|
||
│ 需要KOL数据 │ ──▶ │ 批量输入ID/昵称 │ ──▶ │ 浏览数据列表 │ ──▶ │ 下载Excel/CSV │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
│ │ │ │
|
||
▼ ▼ ▼ ▼
|
||
"需要快速获取 "选择查询方式， "系统自动计算 "数据可用于
|
||
多个达人数据" 粘贴ID列表" CPM等指标" 汇报和分析"
|
||
```
|
||
|
||
用户从需要 KOL 数据开始，选择合适的查询方式（星图ID/达人ID/昵称），批量输入查询条件后提交查询。系统返回结果列表，自动计算预估 CPM 和看后搜成本等指标。用户可浏览数据，需要时导出为 Excel 或 CSV 文件。
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 功能架构
|
||
|
||
<!-- MODIFIED: 统一术语为"预估自然看后搜人数" -->
|
||
```
|
||
KOL Insight
|
||
├── 数据查询模块
|
||
│ ├── 星图ID精准查询
|
||
│ ├── 达人unique_id精准查询
|
||
│ └── 达人昵称模糊查询
|
||
├── 数据计算模块
|
||
│ ├── 预估自然CPM计算
|
||
│ ├── 预估自然看后搜人数计算
|
||
│ └── 预估自然看后搜人数成本计算
|
||
├── 数据展示模块
|
||
│ ├── 结果列表展示
|
||
│ └── 视频链接跳转
|
||
└── 数据导出模块
|
||
└── Excel/CSV导出
|
||
```
|
||
|
||
### 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 | 文件可下载，数据完整，中文列名 |
|
||
|
||
## 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) |
|
||
|
||
<!-- NEW START -->
|
||
**品牌API详情**：
|
||
- 接口地址：`/v1/yuntu/brands/{brand_id}`
|
||
- 请求方式：GET
|
||
- 用途：根据合作品牌ID（brand_id）查询品牌名称
|
||
- 文档：https://api.internal.intelligrow.cn/docs#/云图
|
||
<!-- NEW END -->
|
||
|
||
### 6.2 内部接口
|
||
|
||
<!-- MODIFIED: 补充核心API端点，改用 FastAPI RESTful 风格 -->
|
||
| 接口 | 方法 | 用途 | 说明 |
|
||
|------|------|------|------|
|
||
| /api/v1/query | POST | 批量查询KOL视频数据 | FastAPI 后端服务提供 |
|
||
| /api/v1/export | GET | 导出查询结果为Excel/CSV | FastAPI 后端服务提供 |
|
||
|
||
<!-- 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
|