videos1.0/DevelopmentPlan.md

这是一个基于 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 微服务化 的架构，以应对视频处理的高算力需求和长尾延迟。

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 接口规范	待编写