2f2f7e0f61
- 新增 AI 厂商动态配置架构文档 (AIProviderConfig V2.0) - 新增 TDD 实施计划 (featuredoc/tdd_plan.md) - 新增文档矛盾追踪记录 (DocumentContradictions.md) - 统一所有文档的技术指标与优先级定义 - 完善功能清单 (F-47~F-50 AI 配置功能) - 更新任务清单支持 AI 服务配置任务 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
524 lines
25 KiB
Markdown
524 lines
25 KiB
Markdown
这是一个基于 `RequirementsDoc.md`、`FeatureSummary.md` (V1.3) 和 `User_Role_Interfaces.md` 编写的开发计划文档。
|
||
|
||
这份文档旨在指导技术团队进行架构设计、选型和排期，重点在于解决**视频处理的高并发/高延迟**、**多模态 AI 的集成**以及**移动端适配**等工程难点。
|
||
|
||
文件名：`DevelopmentPlan.md`
|
||
|
||
---
|
||
|
||
# DevelopmentPlan.md - 智能视频审核系统开发计划
|
||
|
||
| 文档类型 | **Development Plan (技术架构与实施计划)** |
|
||
| --- | --- |
|
||
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
|
||
| **版本号** | V1.5 |
|
||
| **日期** | 2026-02-03 |
|
||
| **依据** | FeatureSummary V1.3, PRD V1.0, RequirementsDoc V1.0 |
|
||
| **侧重** | 技术选型、架构设计、MVP 范围、开发排期、验收标准 |
|
||
|
||
---
|
||
|
||
## 版本历史 (Version History)
|
||
|
||
| 版本 | 日期 | 作者 | 变更说明 |
|
||
| --- | --- | --- | --- |
|
||
| V1.0 | 2026-02-03 | Gemini | 初稿：技术架构、选型、排期 |
|
||
| V1.1 | 2026-02-03 | Claude | 审阅修订：补充 F-05-A/F-45 技术方案、验收标准、数据模型、测试策略 |
|
||
| V1.2 | 2026-02-03 | Claude | Reviewer 修正：Logo检测改向量检索、Brief解析增VLM、弹性GPU、H5防锁屏、排期调整 |
|
||
| V1.2.1 | 2026-02-03 | Claude | 补充多模态时间戳对齐流程图 (Gemini 建议) |
|
||
| V1.3 | 2026-02-03 | Claude | **确立 TDD 为项目核心开发规范**，关联 tdd_plan.md |
|
||
| V1.4 | 2026-02-03 | Claude | **新增 AI 厂商动态配置架构**，支持数据库配置、运行时热更新、多租户隔离 |
|
||
| V1.5 | 2026-02-03 | Claude | 文档一致性修复：统一加密方案、采样精度、处理时间、选型决策、P0 范围、排期等 |
|
||
|
||
---
|
||
|
||
## 1. 技术架构设计 (Architecture Design)
|
||
|
||
### 1.1 系统架构图 (逻辑视图)
|
||
|
||
采用 **前后端分离** + **AI 微服务化** 的架构，以应对视频处理的高算力需求和长尾延迟。
|
||
|
||
```mermaid
|
||
graph TD
|
||
User[用户 (PC/Mobile)] -->|HTTPS| Gateway[API Gateway / Nginx]
|
||
|
||
subgraph Frontend
|
||
Web_PC[PC 审核台 (React/Next.js)]
|
||
Web_H5[达人端 H5 (React/Next.js)]
|
||
end
|
||
|
||
subgraph Backend_Core [核心业务服务]
|
||
API_Main[主业务 API (FastAPI)]
|
||
Auth[认证服务]
|
||
Workflow[工作流引擎]
|
||
Upload_Svc[文件上传服务 (Tus协议)]
|
||
end
|
||
|
||
subgraph Async_Layer [异步处理层]
|
||
Queue[消息队列 (Redis)]
|
||
Worker_Manager[任务调度器 (Celery)]
|
||
Socket_Svc[WebSocket 推送服务]
|
||
end
|
||
|
||
subgraph AI_Engine [AI 引擎集群]
|
||
Svc_Parser[Brief 解析服务 (Layout+VLM+LLM)]
|
||
Svc_NLP[脚本/语义分析 (LLM)]
|
||
Svc_Video[视频多模态流水线]
|
||
Svc_Logo[Logo 向量检索服务]
|
||
end
|
||
|
||
subgraph Storage
|
||
DB[(PostgreSQL - 业务数据)]
|
||
VectorDB[(pgvector - 知识库)]
|
||
Cache[(Redis - 缓存/进度)]
|
||
OSS[对象存储 (视频/图片)]
|
||
end
|
||
|
||
Gateway --> Web_PC
|
||
Gateway --> Web_H5
|
||
Web_PC --> API_Main
|
||
Web_H5 --> API_Main
|
||
API_Main --> DB
|
||
API_Main --> Queue
|
||
Worker_Manager --> Queue
|
||
Worker_Manager --> Svc_Parser
|
||
Worker_Manager --> Svc_NLP
|
||
Worker_Manager --> Svc_Video
|
||
Svc_Video --> OSS
|
||
Socket_Svc <--> User
|
||
|
||
```
|
||
|
||
### 1.2 技术选型 (Tech Stack)
|
||
|
||
| 模块 | 选型建议 | 理由 (Why) |
|
||
| --- | --- | --- |
|
||
| **前端框架** | **Next.js (React)** + Tailwind CSS | 统一 PC 和 H5 代码库；Next.js 的 SSR 对 SEO 和首屏渲染友好；适合构建复杂的审核 Dashboard。 |
|
||
| **移动端** | **Responsive H5 + Wake Lock API** | 全角色（达人/代理商/品牌方）均通过 Next.js 响应式布局覆盖 iOS/Android 浏览器及微信内嵌浏览器，无需开发原生 App。⭐ V1.2 增加防锁屏策略。 |
|
||
| **后端 API** | **Python (FastAPI)** | Python 是 AI 原生语言，FastAPI 具有极高的并发性能（AsyncIO），方便集成 AI 模型 SDK。 |
|
||
| **异步队列** | **Celery + Redis** | 视频审核是典型长耗时任务（3-5分钟），必须异步处理。Celery 成熟稳定。 |
|
||
| **实时通讯** | **WebSocket (Socket.io)** | 必须实现（F-17），用于向前端实时推送“正在检测 Logo...”等细粒度进度。 |
|
||
| **数据库** | **PostgreSQL** + **pgvector** | PG 处理关系型数据，pgvector 插件直接在 PG 中处理向量搜索（竞品库/相似案例），减少架构复杂度。 |
|
||
| **文件存储** | **阿里云 OSS / AWS S3** | 视频文件大，必须上云。需配合 CDN 加速预览。 |
|
||
| **上传协议** | **Tus Protocol** (Uppy.js) | 解决大文件（≤ 100MB）上传不稳定问题，支持**断点续传**，替代 ZIP 上传。 |
|
||
|
||
### 1.3 AI 模型选型 (Model Selection)
|
||
|
||
| 任务 | 模型/服务选型 | 备注 |
|
||
| --- | --- | --- |
|
||
| **通用语义 (NLP)** | **豆包 Pro / Qwen-Max / DeepSeek** | 处理 Brief 解析、反讽识别、情感分析 |
|
||
| **视觉理解 (VLM)** | **Qwen-VL / 豆包视觉** | 处理复杂场景理解（如：环境脏乱差、具体动作判定）；**Brief 图片解析** |
|
||
| **语音识别 (ASR)** | **Paraformer (阿里) / SenseVoice** | 高精度中文语音转写，支持时间戳对齐 |
|
||
| **文字识别 (OCR)** | **PaddleOCR v4** | 针对中文视频字幕优化，开源免费，轻量级 |
|
||
| **版面分析 (Layout)** | **PaddleOCR Layout / LayoutLMv3** | Brief PDF 版面分析，提取图文混排结构 |
|
||
| **竞品 Logo 检测** | **Grounding DINO + Vector DB** | ⭐ V1.2 修正：改为向量检索方案，见下方说明 |
|
||
|
||
> ⭐ **V1.3 重要更新 - AI 厂商动态配置：**
|
||
>
|
||
> 本系统采用**商业 SaaS 级别的 AI 厂商动态配置架构**，详见 [AIProviderConfig.md](./AIProviderConfig.md)。
|
||
>
|
||
> **核心特性：**
|
||
> - **数据库存储配置：** AI 厂商的 API Key、Base URL 等配置存储在数据库中，而非环境变量
|
||
> - **运行时动态加载：** 管理员可在后台配置 AI 厂商，系统运行时动态读取配置初始化客户端
|
||
> - **多租户隔离：** 不同品牌方可配置独立的 AI 厂商和配额
|
||
> - **热更新：** 配置变更即时生效，无需重启服务
|
||
> - **故障转移：** 主厂商不可用时自动切换到备用厂商
|
||
> - **API Key 加密：** 使用 AES-256-GCM 加密存储敏感信息
|
||
>
|
||
> **支持的厂商类型：**
|
||
> - 国内厂商：DeepSeek、通义千问、豆包、智谱、Moonshot
|
||
> - 海外厂商：OpenAI、Anthropic（需注意合规）
|
||
> - 中转服务：OneAPI、OpenRouter
|
||
> - 本地部署：Ollama、vLLM
|
||
|
||
> ⚠️ **V1.2 重要修正 - Logo 检测架构变更：**
|
||
>
|
||
> **废弃方案：** ~~YOLOv8 Fine-tuning~~
|
||
>
|
||
> **新方案：Embedding-based Retrieval (向量检索)**
|
||
> ```
|
||
> 1. 品牌方上传竞品 Logo 图片
|
||
> 2. Grounding DINO 提取 Logo 区域 → CLIP/DINOv2 生成 Embedding
|
||
> 3. 存入 Vector DB (pgvector)
|
||
> 4. 视频帧检测时：提取候选区域 → 生成 Embedding → 向量相似度匹配
|
||
> ```
|
||
>
|
||
> **优势：** 支持 SaaS 模式下品牌**动态添加竞品 Logo**，无需重新训练模型，**即刻生效**。
|
||
|
||
> ⚠️ **数据合规说明：** 根据 PRD 第 10 章"数据本地化"要求，国内客户数据原则上存储于中国大陆境内；若涉及跨境处理，需用户明示同意并符合监管要求。因此：
|
||
> - 生产环境允许国内/海外厂商（可通过 OneAPI/OpenRouter 等中转统一接入），但涉及境外处理需完成合规评估与客户授权
|
||
> - 若无法满足出境合规要求，则仅允许使用国内模型
|
||
> - ASR/OCR/CV 同样需满足对应合规与数据本地化要求
|
||
|
||
---
|
||
|
||
## 2. 关键技术难点与解决方案
|
||
|
||
### 2.1 难点：视频上传与解压风险 (F-30)
|
||
|
||
* **风险：** 传统表单上传大视频会导致超时；ZIP 解压消耗大量 CPU。
|
||
* **方案：**
|
||
1. **废弃 ZIP：** 前端采用 Uppy.js 实现**多文件并发上传**。
|
||
2. **分片上传：** 使用 Tus 协议，将 ≤ 100MB 视频切分为 5MB 的 chunk 上传，服务端合并。
|
||
3. **直传 OSS：** 前端获取签名直传云存储，不经过应用服务器，节省带宽。
|
||
|
||
### 2.1.1 难点：H5 移动端上传中断 ⭐ V1.2 新增
|
||
|
||
* **风险：** iOS Safari 在屏幕锁定或切换后台时会杀死网络请求进程，导致大文件上传中断。
|
||
* **方案：**
|
||
1. **Wake Lock API：** 在上传期间请求屏幕常亮锁，防止系统休眠。
|
||
```javascript
|
||
const wakeLock = await navigator.wakeLock.request('screen');
|
||
```
|
||
2. **UI 防锁屏提示：** 上传开始时显示醒目提示："⚠️ 上传中请保持屏幕常亮，切勿锁屏或切换应用"
|
||
3. **断点续传兜底：** Tus 协议支持断点续传，即使中断也可从断点恢复。
|
||
4. **兼容性处理：** Wake Lock API 在部分旧浏览器不支持，需做 Feature Detection 并提供降级提示。
|
||
|
||
|
||
|
||
### 2.2 难点：长时任务的用户焦虑 (F-17)
|
||
|
||
* **风险：** 视频分析需 3-5 分钟，用户易关闭页面。
|
||
* **方案：** **精细化 WebSocket 推送**。
|
||
* 后端 Worker 每完成一个子步骤（如 OCR 完成、ASR 完成），即向 Redis 写入状态。
|
||
* Socket 服务订阅 Redis，推送到前端：“✅ 字幕提取完成 (30%)” -> “👁️ Logo 检测中...”。
|
||
|
||
|
||
|
||
### 2.3 难点：语境理解与误报控制 (F-09)
|
||
|
||
* **风险：** 将"最开心"误判为广告法违规。
|
||
* **方案：** **两段式 AI 分析**。
|
||
1. **Segment（切片）：** 先让 AI 判断当前时间段是"剧情"还是"植入"。
|
||
2. **Evaluate（执法）：** 如果是"剧情"，应用宽松 Prompt；如果是"植入"，应用严格 Prompt。
|
||
|
||
### 2.4 难点：时长与频次校验 (F-45) ⭐ 新增
|
||
|
||
* **场景：** Brief 要求"产品同框 > 5秒"、"口播提及品牌名 ≥ 3次"。
|
||
* **技术挑战：** 需要将 ASR/CV 的时间戳信息转化为可统计的结构化数据。
|
||
* **方案：**
|
||
|
||
**频次统计（口播提及）：**
|
||
1. ASR 输出带时间戳的逐字稀疏文本：`[00:05.2] 这款 [00:05.8] 产品 [00:06.1] 真的很好用`
|
||
2. NLP 识别"品牌词/产品词"并统计出现次数
|
||
3. 输出：`品牌名提及 4 次 @ [00:05, 00:32, 01:15, 02:08]`
|
||
|
||
**时长统计（产品同框）：**
|
||
1. CV 模型逐帧检测"产品出现"（采样率：2fps 即可）
|
||
2. 合并连续出现的帧为"片段"：`产品出现 @ [00:10-00:18], [01:05-01:12]`
|
||
3. 累加总时长：`产品同框总时长 = 8s + 7s = 15s`
|
||
|
||
**验收标准：**
|
||
- 时长统计误差 ≤ 1秒
|
||
- 频次统计准确率 ≥ 95%
|
||
|
||
### 2.5 多模态时间戳对齐流程 ⭐ V1.2 补充
|
||
|
||
> 这是 Phase 2 延长 1 周的核心原因：ASR/OCR/CV 的时间轴需要精确同步。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Video as 原始视频
|
||
participant ASR as ASR引擎
|
||
participant OCR as OCR引擎
|
||
participant CV as CV检测
|
||
participant Alignment as 对齐算法
|
||
participant Rule as 规则引擎
|
||
|
||
par 并行处理
|
||
Video->>ASR: 提取音频
|
||
ASR-->>Alignment: 输出: [{text: "品牌", start: 5.2s, end: 5.8s}, ...]
|
||
|
||
Video->>OCR: 提取关键帧
|
||
OCR-->>Alignment: 输出: [{text: "品牌", timestamp: 5.5s}, ...]
|
||
|
||
Video->>CV: 逐帧扫描
|
||
CV-->>Alignment: 输出: [{object: "Product", timestamp: 5.0s}, ...]
|
||
end
|
||
|
||
Alignment->>Alignment: 时间轴归一化 & 模糊匹配
|
||
Alignment-->>Rule: 输出结构化时间轴数据
|
||
|
||
Rule->>Rule: 执行逻辑: if (Logo_Duration > 5s) && (Mention_Count >= 3)
|
||
Rule-->>Video: 输出最终审核结论
|
||
```
|
||
|
||
**对齐算法要点：**
|
||
1. **时间轴归一化：** 将 ASR (毫秒级) / OCR (帧级) / CV (帧级) 统一为秒级时间戳
|
||
2. **模糊匹配窗口：** 允许 ±0.5s 的时间容差，解决各模态时间戳微小偏差
|
||
3. **事件合并：** 将同一时间窗口内的多模态事件合并为"复合事件"
|
||
|
||
---
|
||
|
||
## 3. MVP (P0) 开发范围定义
|
||
|
||
基于 `FeatureSummary.md V1.3`，MVP 阶段必须包含的功能：
|
||
|
||
### ✅ MVP 包含 (Must Have) - 共 21 个 P0 功能
|
||
|
||
基于 `FeatureSummary.md V1.3` 第 4.1 章定义：
|
||
|
||
| 模块 | 功能编号 | 功能名称 | 备注 |
|
||
| --- | --- | --- | --- |
|
||
| **Brief 管理** | F-01 | Brief 文档上传与解析 | |
|
||
| | F-02 | 在线文档链接导入 | |
|
||
| | F-03 | 平台规则库自动加载 | 平台规则变更 ≤ 1 工作日同步 |
|
||
| | F-04 | 区域合规规则切换 | |
|
||
| | **F-05-A** | **基础黑白名单与竞品库** | ⭐ MVP 必须能防竞品 |
|
||
| **脚本预审** | F-07 | 文本脚本提交与预审 | |
|
||
| | F-08 | 违规检测与修改建议 | |
|
||
| | **F-09** | **语境理解降低误报** | ⭐ P1→P0，避免"人工智障" |
|
||
| **视频审核** | F-10 | 视频上传 | |
|
||
| | F-11 | 多模态联合检测 | ASR/OCR/CV |
|
||
| | F-12 | 竞品 Logo 检测 | |
|
||
| | F-13 | 违禁词口播检测 | |
|
||
| | F-14 | 时间戳风险标注 | |
|
||
| | **F-45** | **时长与频次校验** | ⭐ 新增，Brief 硬指标 |
|
||
| | **F-17** | **审核进度实时展示** | ⭐ P1→P0，缓解等待焦虑 |
|
||
| **审核台** | F-19 | 风险列表展示 | |
|
||
| | F-20 | 确认/驳回操作 | |
|
||
| **数据看板** | F-33 | 核心指标卡片 | |
|
||
| **AI 配置** | **F-47** | **AI 服务商动态配置** | ⭐ V1.4 新增 |
|
||
| | **F-48** | **AI 服务商连通性测试** | ⭐ V1.4 新增 |
|
||
| | **F-49** | **多租户 AI 配置隔离** | ⭐ V1.4 新增 |
|
||
|
||
### ❌ MVP 暂不包含 (Post-MVP)
|
||
|
||
1. 高级豁免规则 (F-05-B)。
|
||
2. 版本比对 Diff 视图 (F-28)。
|
||
3. 批量操作 (F-30 批量审核/导出)。
|
||
4. 舆情监控中心 (F-41)。
|
||
5. AI 闭环训练系统 (F-46)。
|
||
|
||
---
|
||
|
||
## 4. 开发周期规划 (Roadmap)
|
||
|
||
假设配置：1 PM, 1 UI/UX, 2 Frontend, 2 Backend, 1 AI Engineer, 1 QA。
|
||
**总周期：约 11 周 (2.75 个月)** ⭐ V1.2 调整：Phase 2 延长 1 周
|
||
|
||
### Phase 1: 基础设施与 Brief 引擎 (Weeks 1-2)
|
||
|
||
* **Backend:** 搭建 FastAPI 框架，PG 数据库设计，接入 OSS。
|
||
* **Backend:** 实现 AI 服务商动态配置接口（F-47/F-48），支持品牌方配置 AI 厂商和连通性测试。
|
||
* **AI:** 调试 Brief 解析 Prompt (Layout + VLM + LLM)，搭建竞品 Logo 向量库。
|
||
* **Frontend:** 完成 PC 端框架搭建，Brief 上传与解析交互。
|
||
* **交付物:** 能够上传 PDF（含图片）并提取出 JSON 规则；品牌方可配置 AI 服务商。
|
||
|
||
### Phase 2: 核心 AI 流水线 (Weeks 3-6) ⭐ *攻坚期* (V1.2: 3周→4周)
|
||
|
||
* **Backend:** 实现 Celery 异步队列，集成 Tus 上传协议，对接弹性 GPU 集群。
|
||
* **AI:** 串联 ASR -> OCR -> NLP -> CV 模型；实现 F-09 (语境) 和 F-45 (频次) 逻辑。
|
||
* **AI:** 实现 Logo 向量检索流水线 (Grounding DINO + Vector DB)。
|
||
* **Frontend:** 开发 WebSocket 进度组件，实现"透明思考"UI。
|
||
* **交付物:** 后端可跑通"视频输入 -> 审核报告输出"的完整流程。
|
||
|
||
> ⚠️ **V1.2 排期调整说明：** Phase 2 从 3 周延长至 4 周，预留充足时间处理**多模态时间戳对齐**的工程难题（ASR/OCR/CV 的时间轴需要精确同步）。
|
||
|
||
### Phase 3: 达人端 H5 与 审核台 (Weeks 7-9)
|
||
|
||
* **Frontend (H5):** 开发达人/代理商/品牌方移动端页面（达人上传与申诉、代理商审核、品牌方审批） (响应式适配 + Wake Lock 防锁屏)。
|
||
* **Frontend (PC):** 开发复杂的"审核决策台"（视频播放器与时间轴打点的联动）。
|
||
* **Backend:** 实现申诉逻辑、审核状态流转 (State Machine)。
|
||
* **交付物:** 达人可上传，代理商可审核，流程闭环。
|
||
|
||
### Phase 4: 联调与验收 (Weeks 10-11)
|
||
|
||
* **QA:** 全链路测试，重点测试大文件上传稳定性、AI 误报率、H5 兼容性。
|
||
* **AI:** 根据测试数据微调 Prompt，优化"油腻/爹味"提示词。
|
||
* **Ops:** 部署生产环境，配置 CDN，弹性 GPU 集群压力测试。
|
||
* **交付物:** v1.0 上线。
|
||
|
||
---
|
||
|
||
## 5. 资源需求清单
|
||
|
||
| 资源类型 | 规格/服务 | 预估成本 | 备注 |
|
||
| --- | --- | --- | --- |
|
||
| **应用服务器** | 8C 16G * 2 (Web/API) | Medium | 承载 API 和 Websocket |
|
||
| **AI 推理集群** | **弹性 GPU 集群 / Serverless GPU** | High | ⭐ V1.2 修正，见下方说明 |
|
||
| **LLM API** | 豆包 Pro / Qwen-Max | 按量计费 | 核心语义分析（国内合规） |
|
||
| **ASR 服务** | 阿里云 Paraformer API | 按量计费 | 语音转文字 |
|
||
| **存储 (OSS)** | 预留 5TB | Low | 视频与图片存储 |
|
||
| **数据库** | RDS PostgreSQL (High Avail) | Medium | 业务数据 + pgvector |
|
||
| **缓存** | Redis Cluster | Medium | 队列与实时状态 |
|
||
|
||
> ⚠️ **V1.2 重要修正 - GPU 资源策略变更：**
|
||
>
|
||
> **废弃方案：** ~~单一 GPU T4/A10 * 1~~
|
||
>
|
||
> **新方案：弹性 GPU 集群 / Serverless GPU**
|
||
> - **阿里云 PAI-EAS** / **火山引擎 veFaaS** / **AWS SageMaker Serverless**
|
||
> - 按推理请求计费，支持自动扩缩容
|
||
> - 高峰期自动扩容，空闲时缩容至 0
|
||
>
|
||
> **理由：** 单个 T4 无法支撑高并发下的视频处理 SLA（5分钟内）。弹性方案可应对突发流量，同时控制成本。
|
||
|
||
---
|
||
|
||
## 6. 风险管理 (Risk Management)
|
||
|
||
| 风险点 | 可能性 | 影响程度 | 缓解措施 |
|
||
| --- | --- | --- | --- |
|
||
| **AI 误报率过高** | 中 | 高 | 上线前进行不少于 1000 条视频的“红蓝对抗”测试；初期设置较低的阈值（宁缺毋滥）。 |
|
||
| **视频处理积压** | 低 | 高 | 监控队列长度，配置**弹性伸缩 (Auto-scaling)**，当队列堆积时自动增加 AI Worker 节点。 |
|
||
| **平台规则变更** | 高 | 中 | 建立“配置化规则库”，无需改代码，运营人员在后台通过 JSON 更新违禁词。 |
|
||
| **达人 H5 兼容性** | 中 | 中 | 使用 BrowserStack 进行主流机型（iOS/Android/微信内置）的兼容性测试。 |
|
||
|
||
---
|
||
|
||
## 7. 核心数据模型 (Data Model Overview)
|
||
|
||
> 详细字段定义见数据字典文档
|
||
|
||
### 7.1 核心实体关系
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Brand │────<│ Agency │────<│ Creator │
|
||
│ (品牌方) │ │ (代理商) │ │ (达人) │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────┐ │
|
||
└───────────>│ Task │<───────────┘
|
||
│ (任务) │
|
||
└──────┬──────┘
|
||
│
|
||
┌────────────────┼────────────────┐
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Brief │ │ Video │ │ Report │
|
||
│ (Brief规则) │ │ (视频) │ │ (审核报告) │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
```
|
||
|
||
### 7.2 核心表结构概述
|
||
|
||
| 表名 | 说明 | 关键字段 |
|
||
| --- | --- | --- |
|
||
| `brands` | 品牌方 | id, name, settings_json |
|
||
| `agencies` | 代理商 | id, brand_id, name |
|
||
| `creators` | 达人 | id, agency_id, credit_score, appeal_tokens |
|
||
| `tasks` | 审核任务 | id, brand_id, agency_id, creator_id, status, platform |
|
||
| `briefs` | Brief 规则 | id, task_id, raw_file_url, parsed_rules_json |
|
||
| `videos` | 视频文件 | id, task_id, version, file_url, duration |
|
||
| `reports` | 审核报告 | id, video_id, ai_result_json, human_decision, created_at |
|
||
| `risk_items` | 风险项 | id, report_id, type, level, timestamp_start, timestamp_end, evidence_json |
|
||
| `rule_sets` | 规则库 | id, brand_id, platform, version, rules_json |
|
||
| `audit_logs` | 审计日志 | id, task_id, operator_id, action, detail_json, created_at |
|
||
|
||
---
|
||
|
||
## 8. 验收标准 (Acceptance Criteria)
|
||
|
||
引用自 `FeatureSummary.md V1.3` 第 9 章，MVP 上线前必须满足：
|
||
|
||
| 验收项 | 标准 | 测量方式 | 责任方 |
|
||
| --- | --- | --- | --- |
|
||
| **Brief 解析准确率** | 图文混排 PDF 提取准确率 **> 90%** | 标注测试集评估 | AI 团队 |
|
||
| **竞品 Logo 检测** | 遮挡 30% 场景 F1 **≥ 0.85** | 标注测试集评估 | AI 团队 |
|
||
| **语义理解误报率** | 广告/非广告语境区分误报率 **≤ 5%** | 样本量 ≥ 1,000 句 | AI 团队 |
|
||
| **ASR 字错率** | 普通话+方言 **≤ 10%** | 标注测试集评估 | AI 团队 |
|
||
| **OCR 准确率** | 含复杂背景 **≥ 95%** | 标注测试集评估 | AI 团队 |
|
||
| **时长统计误差** | **≤ 1秒** | 人工核对 | AI 团队 |
|
||
| **频次统计准确率** | **≥ 95%** | 人工核对 | AI 团队 |
|
||
| **审核报告产出时间** | ≤ 100MB 视频 **≤ 5 分钟（含排队 ≤ 2 分钟）** | 系统埋点 | 后端 |
|
||
| **审计链路完整性** | 每条结论含规则版本、证据、时间戳 | 人工抽查 | QA |
|
||
|
||
---
|
||
|
||
## 9. 测试策略 (Testing Strategy)
|
||
|
||
> ⭐ **核心原则：本项目全程遵循 TDD（测试驱动开发）**
|
||
>
|
||
> 详细实施计划参见：[featuredoc/tdd_plan.md](./featuredoc/tdd_plan.md)
|
||
|
||
### 9.0 TDD 开发规范 (Test-Driven Development)
|
||
|
||
**本项目强制采用 TDD 开发模式**，所有功能代码必须遵循「红-绿-重构」循环：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ TDD 开发流程 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. 🔴 RED → 先写一个失败的测试 │
|
||
│ 2. 🟢 GREEN → 写最少的代码让测试通过 │
|
||
│ 3. 🔄 REFACTOR → 重构代码，保持测试通过 │
|
||
│ 4. 重复循环 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**TDD 分层策略：**
|
||
|
||
| 代码类型 | TDD 策略 | 覆盖率要求 |
|
||
| --- | --- | --- |
|
||
| **业务逻辑/工具函数** | 严格 TDD（先写测试） | ≥ 80% |
|
||
| **API 接口** | 契约优先（先定义 OpenAPI） | ≥ 80% |
|
||
| **AI 模型调用** | 标注集验证 | ≥ 70% |
|
||
| **前端组件** | 组件级 TDD | ≥ 70% |
|
||
| **E2E 流程** | BDD + Playwright | 核心路径 100% |
|
||
|
||
**CI/CD 门禁：**
|
||
- PR 合并前必须通过所有测试
|
||
- 覆盖率低于阈值将阻断合并
|
||
- AI 模型指标下降将触发告警
|
||
|
||
### 9.1 测试类型
|
||
|
||
| 测试类型 | 覆盖范围 | 工具 | 负责人 |
|
||
| --- | --- | --- | --- |
|
||
| **单元测试** | 后端业务逻辑、工具函数 | pytest | 后端 |
|
||
| **集成测试** | API 接口、数据库交互 | pytest + TestContainers | 后端 |
|
||
| **E2E 测试** | 核心用户流程 | Playwright | QA |
|
||
| **AI 模型测试** | 准确率/召回率/F1 | 标注测试集 + MLflow | AI 团队 |
|
||
| **性能测试** | 并发、响应时间、队列积压 | Locust / k6 | 后端 |
|
||
| **兼容性测试** | H5 移动端适配 | BrowserStack | 前端 |
|
||
|
||
### 9.2 AI 模型专项测试
|
||
|
||
| 测试项 | 测试集规模 | 通过标准 |
|
||
| --- | --- | --- |
|
||
| 违禁词检测 | ≥ 500 正样本 + 500 负样本 | 召回率 ≥ 95%，误报率 ≤ 5% |
|
||
| 竞品 Logo 检测 | ≥ 200 张图片（含遮挡场景） | F1 ≥ 0.85 |
|
||
| 语境理解 | ≥ 1,000 句子 | 误报率 ≤ 5% |
|
||
| Brief 解析 | ≥ 50 份真实 Brief | 准确率 > 90% |
|
||
|
||
### 9.3 上线前必须通过
|
||
|
||
- [ ] 所有 P0 功能通过 E2E 测试
|
||
- [ ] AI 模型指标达到验收标准
|
||
- [ ] 100 并发压测无异常
|
||
- [ ] H5 端在 iOS/Android/微信内置浏览器通过兼容性测试
|
||
- [ ] 安全扫描无高危漏洞
|
||
|
||
---
|
||
|
||
## 10. 下一步行动 (Next Steps)
|
||
|
||
1. **架构师：** 确认 `Database Schema` (特别是 Brief 规则与审核报告的 JSON 结构)。
|
||
2. **UI 设计师：** 优先输出 **"达人端 H5 上传页"**（含防锁屏提示）和 **"代理商 PC 审核台"** 的高保真原型。
|
||
3. **AI 工程师：** 搭建 **Logo 向量检索系统** (Grounding DINO + pgvector)，验证相似度匹配效果。
|
||
4. **AI 工程师：** 调试 **Brief 解析流水线** (Layout Analysis + VLM)，确保能提取 PDF 中的参考图片。
|
||
5. **后端工程师：** 搭建 FastAPI 框架骨架，集成 Celery 异步队列，对接弹性 GPU 服务。
|
||
6. **前端工程师：** 验证 Wake Lock API 在 iOS Safari / 微信内置浏览器的兼容性。
|
||
7. **QA：** 准备 AI 模型测试集（违禁词、Logo、Brief 样本）。
|
||
|
||
---
|
||
|
||
## 11. 相关文档
|
||
|
||
| 文档 | 说明 |
|
||
| --- | --- |
|
||
| RequirementsDoc.md | 业务需求文档 |
|
||
| PRD.md | 产品需求文档 |
|
||
| FeatureSummary.md | 功能清单与优先级 |
|
||
| User_Role_Interfaces.md | 界面规范 |
|
||
| tasks.md | 开发任务清单 |
|
||
| **featuredoc/tdd_plan.md** | **TDD 实施计划（核心规范）** |
|
||
| **AIProviderConfig.md** | **AI 厂商动态配置架构设计（V2.0）** |
|
||
| 数据字典 | 待编写 |
|
||
| API 接口规范 | 待编写 |
|