diff --git a/DevelopmentPlan.md b/DevelopmentPlan.md new file mode 100644 index 0000000..ff2e9dd --- /dev/null +++ b/DevelopmentPlan.md @@ -0,0 +1,377 @@ +这是一个基于 `RequirementsDoc.md`、`FeatureSummary.md` (V1.2) 和 `User_Role_Interfaces.md` 编写的开发计划文档。 + +这份文档旨在指导技术团队进行架构设计、选型和排期,重点在于解决**视频处理的高并发/高延迟**、**多模态 AI 的集成**以及**移动端适配**等工程难点。 + +文件名:`DevelopmentPlan.md` + +--- + +# DevelopmentPlan.md - 智能视频审核系统开发计划 + +| 文档类型 | **Development Plan (技术架构与实施计划)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.1 | +| **日期** | 2026-02-03 | +| **依据** | FeatureSummary V1.2, 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 技术方案、验收标准、数据模型、测试策略 | + +--- + +## 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[消息队列 (RabbitMQ/Redis)] + Worker_Manager[任务调度器 (Celery)] + Socket_Svc[WebSocket 推送服务] + end + + subgraph AI_Engine [AI 引擎集群] + Svc_Parser[Brief 解析服务 (LangChain)] + Svc_NLP[脚本/语义分析 (LLM)] + Svc_Video[视频多模态流水线] + end + + subgraph Storage + DB[(PostgreSQL - 业务数据)] + VectorDB[(Milvus/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** | 达人端无需开发原生 App,通过 Next.js 响应式布局覆盖 iOS/Android 浏览器及微信内嵌浏览器。 | +| **后端 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 / 豆包视觉** | 处理复杂场景理解(如:环境脏乱差、具体动作判定) | +| **语音识别 (ASR)** | **Paraformer (阿里) / SenseVoice** | 高精度中文语音转写,支持时间戳对齐 | +| **文字识别 (OCR)** | **PaddleOCR v4** | 针对中文视频字幕优化,开源免费,轻量级 | +| **物体检测 (CV)** | **YOLOv8 (Fine-tuned)** | 需针对特定"竞品 Logo"进行微调训练,保证高召回率 | + +> ⚠️ **国内数据合规说明:** 根据 PRD 第 10 章"数据本地化"要求,国内客户数据必须存储于中国大陆境内服务器。因此: +> - **生产环境必须使用国内 LLM**(豆包/Qwen/DeepSeek),不可调用 GPT-4o/Claude 等海外 API +> - 海外 API 仅用于内部研发测试,不可处理客户真实数据 +> - ASR/OCR/CV 均选用国内服务或本地部署模型 + +--- + +## 2. 关键技术难点与解决方案 + +### 2.1 难点:视频上传与解压风险 (F-30) + +* **风险:** 传统表单上传大视频会导致超时;ZIP 解压消耗大量 CPU。 +* **方案:** +1. **废弃 ZIP:** 前端采用 Dropzone 实现**多文件并发上传**。 +2. **分片上传:** 使用 Tus 协议,将 100MB 视频切分为 5MB 的 chunk 上传,服务端合并。 +3. **直传 OSS:** 前端获取签名直传云存储,不经过应用服务器,节省带宽。 + + + +### 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` + +**验收标准:** +- 时长统计误差 ≤ 0.5秒 +- 频次统计准确率 ≥ 95% + +--- + +## 3. MVP (P0) 开发范围定义 + +基于 `FeatureSummary.md V1.2`,MVP 阶段必须包含的功能: + +### ✅ MVP 包含 (Must Have) - 共 18 个 P0 功能 + +基于 `FeatureSummary.md V1.2` 第 4.1 章定义: + +| 模块 | 功能编号 | 功能名称 | 备注 | +| --- | --- | --- | --- | +| **Brief 管理** | F-01 | Brief 文档上传与解析 | | +| | F-02 | 在线文档链接导入 | | +| | F-03 | 平台规则库自动加载 | | +| | 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 | 核心指标卡片 | | + +### ❌ 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。 +**总周期:约 10 周 (2.5 个月)** + +### Phase 1: 基础设施与 Brief 引擎 (Weeks 1-2) + +* **Backend:** 搭建 FastAPI 框架,PG 数据库设计,接入 OSS。 +* **AI:** 调试 Brief 解析 Prompt,搭建竞品 Logo 向量库。 +* **Frontend:** 完成 PC 端框架搭建,Brief 上传与解析交互。 +* **交付物:** 能够上传 PDF 并提取出 JSON 规则。 + +### Phase 2: 核心 AI 流水线 (Weeks 3-5) ⭐ *攻坚期* + +* **Backend:** 实现 Celery 异步队列,集成 Tus 上传协议。 +* **AI:** 串联 ASR -> OCR -> NLP -> CV 模型;实现 F-09 (语境) 和 F-45 (频次) 逻辑。 +* **Frontend:** 开发 WebSocket 进度组件,实现“透明思考”UI。 +* **交付物:** 后端可跑通“视频输入 -> 审核报告输出”的完整流程。 + +### Phase 3: 达人端 H5 与 审核台 (Weeks 6-8) + +* **Frontend (H5):** 开发达人手机端上传、查看报告、申诉页面 (响应式适配)。 +* **Frontend (PC):** 开发复杂的“审核决策台”(视频播放器与时间轴打点的联动)。 +* **Backend:** 实现申诉逻辑、审核状态流转 (State Machine)。 +* **交付物:** 达人可上传,代理商可审核,流程闭环。 + +### Phase 4: 联调与验收 (Weeks 9-10) + +* **QA:** 全链路测试,重点测试大文件上传稳定性、AI 误报率。 +* **AI:** 根据测试数据微调 Prompt,优化“油腻/爹味”提示词。 +* **Ops:** 部署生产环境,配置 CDN,压力测试。 +* **交付物:** v1.0 上线。 + +--- + +## 5. 资源需求清单 + +| 资源类型 | 规格/服务 | 预估成本 | 备注 | +| --- | --- | --- | --- | +| **应用服务器** | 8C 16G * 2 (Web/API) | Medium | 承载 API 和 Websocket | +| **AI 推理服务器** | GPU T4/A10 * 1 | High | 用于跑本地 OCR/YOLO 模型 | +| **LLM API** | GPT-4o / Doubao Pro | 按量计费 | 核心语义分析 | +| **ASR 服务** | 阿里/腾讯云 API | 按量计费 | 语音转文字 | +| **存储 (OSS)** | 预留 5TB | Low | 视频与图片存储 | +| **数据库** | RDS PostgreSQL (High Avail) | Medium | 业务数据 | +| **缓存** | Redis Cluster | Medium | 队列与实时状态 | + +--- + +## 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.2` 第 9 章,MVP 上线前必须满足: + +| 验收项 | 标准 | 测量方式 | 责任方 | +| --- | --- | --- | --- | +| **Brief 解析准确率** | 图文混排 PDF 提取准确率 **> 90%** | 标注测试集评估 | AI 团队 | +| **竞品 Logo 检测** | 遮挡 30% 场景 F1 **≥ 0.85** | 标注测试集评估 | AI 团队 | +| **语义理解误报率** | 广告/非广告语境区分误报率 **≤ 5%** | 样本量 ≥ 1,000 句 | AI 团队 | +| **ASR 字错率** | 普通话+方言 **≤ 10%** | 标注测试集评估 | AI 团队 | +| **OCR 准确率** | 含复杂背景 **≥ 95%** | 标注测试集评估 | AI 团队 | +| **时长统计误差** | **≤ 0.5秒** | 人工核对 | AI 团队 | +| **频次统计准确率** | **≥ 95%** | 人工核对 | AI 团队 | +| **审核报告产出时间** | 100MB 视频 **≤ 5 分钟** | 系统埋点 | 后端 | +| **审计链路完整性** | 每条结论含规则版本、证据、时间戳 | 人工抽查 | QA | + +--- + +## 9. 测试策略 (Testing Strategy) + +### 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 检测"** 的 YOLO 模型(需收集样本)。 +4. **后端工程师:** 搭建 FastAPI 框架骨架,集成 Celery 异步队列。 +5. **QA:** 准备 AI 模型测试集(违禁词、Logo、Brief 样本)。 + +--- + +## 11. 相关文档 + +| 文档 | 说明 | +| --- | --- | +| RequirementsDoc.md | 业务需求文档 | +| PRD.md | 产品需求文档 | +| FeatureSummary.md | 功能清单与优先级 | +| User_Role_Interfaces.md | 界面规范 | +| 数据字典 | 待编写 | +| API 接口规范 | 待编写 |