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>
177 lines
7.6 KiB
Markdown
177 lines
7.6 KiB
Markdown
# PRD 评审报告
|
||
|
||
## 概要
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 评审时间 | 2026-01-28 21:30 |
|
||
| 目标文档 | doc/PRD.md |
|
||
| 参照文档 | doc/RequirementsDoc.md |
|
||
| 问题统计 | 3 个严重 / 2 个一般 / 3 个建议 |
|
||
|
||
## 一致性检查
|
||
|
||
### 需求覆盖分析
|
||
|
||
| RequirementsDoc 需求项 | PRD 对应位置 | 状态 |
|
||
|------------------------|--------------|------|
|
||
| 批量查询 KOL 视频数据 | US-001, US-002, US-003 | ✅ 已覆盖 |
|
||
| 支持星图ID精准查询 | US-001 / 3.2.1节 | ✅ 已覆盖 |
|
||
| 支持达人unique_id精准查询 | US-002 / 3.2.1节 | ✅ 已覆盖 |
|
||
| 支持达人昵称模糊查询 | US-003 / 3.2.1节 | ✅ 已覆盖 |
|
||
| 计算预估自然CPM | US-004 / 3.2.2节 | ⚠️ 部分覆盖（缺少公式） |
|
||
| 计算预估自然看后搜 | US-004 / 3.2.2节 | ⚠️ 部分覆盖（缺少公式） |
|
||
| 计算预估自然看后搜成本 | US-004 / 3.2.2节 | ⚠️ 部分覆盖（缺少公式） |
|
||
| 数据导出 | US-005 / 3.2.4节 | ✅ 已覆盖 |
|
||
| 调用品牌API获取品牌名称 | - | ❌ 未覆盖 |
|
||
| 技术栈：Next.js + PostgreSQL | 7.1节 | ✅ 已覆盖 |
|
||
| 部署方式：Docker / PM2 | 7.1节 | ✅ 已覆盖 |
|
||
|
||
### 差异说明
|
||
|
||
PRD 新增但 RequirementsDoc 未明确提及的内容：
|
||
1. **用户角色定义**（2.1节）：细化了"运营人员"和"投放优化师"两个角色，这是对原始需求的合理扩展
|
||
2. **用户旅程设计**（2.3节）：可视化了用户操作流程，增强了需求理解
|
||
3. **里程碑规划**（第8章）：增加了MVP和v1.1两个阶段规划
|
||
4. **风险评估**（第9章）：识别了数据同步延迟、性能问题等风险
|
||
|
||
**评估**: 以上新增内容均为合理的 PRD 扩展，有助于后续开发和实施。
|
||
|
||
## 问题清单
|
||
|
||
### 严重问题 (Critical)
|
||
|
||
> 必须修复，否则影响后续文档生成
|
||
|
||
1. **[位置: [doc/PRD.md:199](doc/PRD.md#L199)]** 缺少外部品牌API依赖说明
|
||
- 现状：PRD 第6章"接口需求"中仅提及 PostgreSQL，未说明需要调用外部品牌API
|
||
- 与 RequirementsDoc 的差异：RequirementsDoc 明确说明"合作品牌要使用合作品牌id 调用另一个API查找 https://api.internal.intelligrow.cn/docs#/%E4%BA%91%E5%9B%BE/get_yuntu_cookies_v1_yuntu_get_cookie_get /v1/yuntu/brands/{brand_id}"
|
||
- 建议：在 6.1 外部接口表格中增加品牌API行：
|
||
```
|
||
| 品牌API | 根据品牌ID获取品牌名称 | https://api.internal.intelligrow.cn/v1/yuntu/brands/{brand_id} |
|
||
```
|
||
|
||
2. **[位置: [doc/PRD.md:273](doc/PRD.md#L273)]** 输出字段映射不完整
|
||
- 现状：附录B中大部分输出字段的"字段名"列标记为"-"，缺少数据库字段映射
|
||
- 影响：开发人员无法知道如何从数据库获取这些数据
|
||
- 建议：补全所有输出字段对应的数据库字段名，参考 RequirementsDoc 中的字段定义
|
||
|
||
3. **[位置: [doc/PRD.md:114](doc/PRD.md#L114)]** 计算公式缺失
|
||
- 现状：3.2.2节"数据计算模块"仅描述了功能，未给出具体计算公式
|
||
- 与 RequirementsDoc 的差异：RequirementsDoc 明确了三个公式：
|
||
- 预估自然CPM = estimated_video_cost / natural_play_cnt * 1000
|
||
- 预估自然看后搜人数 = natural_play_cnt / total_play_cnt * after_view_search_uv
|
||
- 预估自然看后搜人数成本 = estimated_video_cost / 预估自然看后搜人数
|
||
- 建议：在 3.2.2 节的"描述"列或"验收标准"列中添加完整的计算公式
|
||
|
||
### 一般问题 (Major)
|
||
|
||
> 建议修复，可提升文档质量
|
||
|
||
1. **[位置: [doc/PRD.md:119](doc/PRD.md#L119)]** 术语不一致
|
||
- 问题：PRD 使用"预估自然看后搜"，RequirementsDoc 使用"预估自然看后搜人数"
|
||
- 影响：可能导致理解偏差（是次数还是人数）
|
||
- 建议：统一术语为"预估自然看后搜人数"，与计算公式中使用的 after_view_search_uv（用户数）概念一致
|
||
|
||
2. **[位置: [doc/PRD.md:168](doc/PRD.md#L168)]** 数据模型与计算公式不匹配
|
||
- 问题：5.1节数据模型中未列出计算公式所需的关键字段：
|
||
- estimated_video_cost（预估视频价格）- 已在5.2中提及
|
||
- natural_play_cnt（自然曝光数）- 已在5.1中提及
|
||
- total_play_cnt（总曝光数）- 已在5.1中提及
|
||
- after_view_search_uv（看后搜人数）- 未明确提及字段名
|
||
- 建议：在 5.1 数据模型图中补充这些关键字段的明确字段名
|
||
|
||
### 改进建议 (Minor)
|
||
|
||
> 可选优化项
|
||
|
||
1. **[位置: [doc/PRD.md:262](doc/PRD.md#L262)]** 术语表可补充
|
||
- 建议：在术语表中补充以下术语：
|
||
- natural_play_cnt：自然曝光次数
|
||
- estimated_video_cost：预估视频价格
|
||
- after_view_search_uv：看后搜用户数
|
||
|
||
2. **[位置: [doc/PRD.md:164](doc/PRD.md#L164)]** 数据需求可细化
|
||
- 建议：补充数据库表名（如 videos 或 kol_videos）
|
||
- 建议：补充关键字段的索引建议（star_id, star_unique_id, star_nickname）
|
||
|
||
3. **[位置: [doc/PRD.md:208](doc/PRD.md#L208)]** 内部接口设计
|
||
- 建议：虽然标注"待补充"，但可以在此阶段先列出核心API端点：
|
||
- POST /api/query - 批量查询接口
|
||
- GET /api/export - 数据导出接口
|
||
|
||
## 用户故事评估
|
||
|
||
| 评估项 | 结果 |
|
||
|--------|------|
|
||
| 用户故事总数 | 7 个 |
|
||
| 符合格式规范 | 7 / 7 ✅ |
|
||
| 有验收标准 | 7 / 7 ✅ |
|
||
| 关联功能点 | 7 / 7 ✅ |
|
||
| 优先级划分 | 明确（P0/P1/P2）✅ |
|
||
|
||
### 用户故事质量评价
|
||
|
||
**优点**:
|
||
- ✅ 所有用户故事都有唯一ID（US-001 ~ US-007）
|
||
- ✅ 格式规范，符合"作为{角色}，我想要{功能}，以便{价值}"结构
|
||
- ✅ 验收标准清晰、可测试
|
||
- ✅ 优先级划分合理，核心查询和计算功能为P0
|
||
|
||
**无明显问题**
|
||
|
||
## 评审结论
|
||
|
||
**需修改后通过**
|
||
|
||
### 结论说明
|
||
|
||
PRD 整体质量较好，功能需求覆盖完整，用户故事设计规范，文档结构清晰。但存在以下关键问题需要修复：
|
||
|
||
1. **外部API依赖缺失**：未说明需要调用品牌API获取品牌名称，这是实现完整功能的必要依赖
|
||
2. **计算公式缺失**：开发人员需要明确的计算公式来实现预估指标
|
||
3. **字段映射不完整**：输出字段与数据库字段的映射关系不明确
|
||
|
||
修复上述3个严重问题后，PRD 可以作为下一阶段（FeatureSummary、UIDesign、DevelopmentPlan）的基础文档。
|
||
|
||
### 下一步行动
|
||
|
||
- [ ] **必须**：在 6.1 节补充品牌API外部接口说明
|
||
- [ ] **必须**：在 3.2.2 节补充完整的计算公式
|
||
- [ ] **必须**：在附录B中补全所有输出字段的数据库字段名
|
||
- [ ] **建议**：统一"预估自然看后搜"术语为"预估自然看后搜人数"
|
||
- [ ] **建议**：在 5.1 数据模型中明确标注计算公式所需字段的字段名
|
||
|
||
---
|
||
|
||
## 附录：RequirementsDoc 原始需求对照
|
||
|
||
为便于对比，以下是 RequirementsDoc 中的核心需求要点：
|
||
|
||
### 功能需求
|
||
- 批量查询 KOL 视频数据
|
||
- 支持星图ID、达人unique_id、达人昵称搜索
|
||
- 计算预估自然CPM、看后搜成本等指标
|
||
- 数据导出
|
||
|
||
### 查询规则
|
||
- 星图ID → 匹配 star_id 字段（精准匹配）
|
||
- 达人unique_id → 匹配 star_unique_id 字段（精准匹配）
|
||
- 达人昵称 → 模糊匹配 star_nickname 字段（包含匹配）
|
||
|
||
### 计算公式
|
||
```
|
||
预估自然CPM = estimated_video_cost / natural_play_cnt * 1000
|
||
预估自然看后搜人数 = natural_play_cnt / total_play_cnt * after_view_search_uv
|
||
预估自然看后搜人数成本 = estimated_video_cost / 预估自然看后搜人数
|
||
```
|
||
|
||
### 外部依赖
|
||
- 品牌API: `/v1/yuntu/brands/{brand_id}`
|
||
- 用途：根据合作品牌ID查询品牌名称
|
||
|
||
### 技术栈
|
||
- Next.js (App Router)
|
||
- PostgreSQL
|
||
- Docker / PM2
|