commit d7619a45118f532098ee52e0723ff166f07e4b5d Author: Your Name Date: Mon Feb 2 22:34:00 2026 +0800 Add docs and Pencil UI design diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..4710e12 Binary files /dev/null and b/.DS_Store differ diff --git a/AIProviderConfig.md b/AIProviderConfig.md new file mode 100644 index 0000000..53dc452 --- /dev/null +++ b/AIProviderConfig.md @@ -0,0 +1,712 @@ +# AIProviderConfig.md - AI 服务配置架构设计 + +| 文档类型 | **Technical Design (技术设计文档)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V2.0 | +| **日期** | 2026-02-02 | +| **侧重** | AI 服务动态配置、多租户隔离、模型选择 | + +--- + +## 版本历史 (Version History) + +| 版本 | 日期 | 作者 | 变更说明 | +| --- | --- | --- | --- | +| V1.0 | 2026-02-02 | Claude | 初稿：AI 厂商动态配置架构设计 | +| V2.0 | 2026-02-02 | Claude | 重构：简化为统一提供商+三模型配置方案 | + +--- + +## 1. 设计背景与目标 + +### 1.1 业务需求 + +SmartAudit 系统需要调用三类 AI 服务完成视频审核： + +| 服务类型 | 用途 | 示例模型 | +| --- | --- | --- | +| **文字处理模型** | Brief 解析、违禁词检测、语义分析、舆情分析 | claude-opus-4-5-20251101, deepseek-chat | +| **视频分析模型** | 画面理解、Logo 检测、产品识别 | Doubao-Seed-1.6-thinking, qwen-vl-max | +| **音频解析模型** | 视频口播转文字 (ASR) | whisper-large-v3, paraformer-v2 | + +### 1.2 设计目标 + +| 目标 | 描述 | +| --- | --- | +| **灵活配置** | 品牌方可在后台自由选择 AI 提供商和模型 | +| **统一接入** | 支持 OneAPI/OpenRouter 中转，一套配置调用多种模型 | +| **直连支持** | 也支持直连 Anthropic、OpenAI、DeepSeek 等厂商 | +| **多租户隔离** | 不同品牌方使用独立的 AI 配置和配额 | +| **动态模型列表** | 根据 API Key 自动获取可用模型 | +| **连接测试** | 保存前可测试三个模型的连通性 | + +### 1.3 使用流程 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ AI 配置使用流程 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🛡️ 品牌方配置 AI 服务 │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ • 选择 AI 提供商 (OneAPI/Anthropic/OpenAI/...) │ │ +│ │ • 填写 Base URL 和 API Key │ │ +│ │ • 选择三个模型 (文字处理/视频分析/音频解析) │ │ +│ │ • 配置参数 (Temperature/Max Tokens) │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ 自动继承 │ +│ ▼ │ +│ 👥 代理商 / 👤 达人 │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ 上传视频 → 系统自动调用品牌方配置的 AI 服务 → 获得审核结果 │ │ +│ │ (用户无感知，不知道也不需要关心使用的是哪个 AI) │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 系统架构 + +### 2.1 架构概览 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 品牌方管理后台 (Brand Admin) │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ 系统设置 → AI 服务配置 │ │ +│ │ • 选择提供商 │ │ +│ │ • 配置连接信息 │ │ +│ │ • 选择模型 │ │ +│ │ • 测试连接 │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ API 层 (FastAPI) │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ GET /api/v1/ai-config - 获取当前配置 │ │ +│ │ PUT /api/v1/ai-config - 更新配置 │ │ +│ │ POST /api/v1/ai-config/models - 获取可用模型列表 │ │ +│ │ POST /api/v1/ai-config/test - 测试连接 (三个模型) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ AI 服务路由器 (AIServiceRouter) │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ • 根据租户 ID 获取对应的 AI 配置 │ │ +│ │ • 根据任务类型选择对应的模型 │ │ +│ │ • 创建 AI 客户端并调用 │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ 文字处理 │ │ 视频分析 │ │ 音频解析 │ + │ Claude │ │ 豆包 VL │ │ Whisper │ + └─────────────┘ └─────────────┘ └─────────────┘ +``` + +### 2.2 核心组件 + +| 组件 | 职责 | +| --- | --- | +| **AIConfig** | 数据模型，存储品牌方的 AI 配置 | +| **AIServiceRouter** | 路由器，根据租户和任务类型选择模型 | +| **AIClientFactory** | 工厂类，创建 OpenAI 兼容客户端 | +| **ModelRegistry** | 模型注册表，缓存可用模型列表 | +| **SecretsManager** | 加密存储和解密 API Key | + +--- + +## 3. 数据模型设计 + +### 3.1 AI 配置表 (ai_configs) + +```sql +CREATE TABLE ai_configs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + + -- 租户 + tenant_id UUID NOT NULL UNIQUE, -- 品牌方 ID，一个品牌方只有一条配置 + + -- 提供商 + provider VARCHAR(50) NOT NULL, -- 提供商类型 + + -- 连接配置 + base_url VARCHAR(500) NOT NULL, -- API Base URL + api_key_encrypted BYTEA NOT NULL, -- 加密后的 API Key + + -- 模型配置 + text_model VARCHAR(100) NOT NULL, -- 文字处理模型 + vision_model VARCHAR(100) NOT NULL, -- 视频分析模型 + audio_model VARCHAR(100) NOT NULL, -- 音频解析模型 + + -- 参数配置 + temperature DECIMAL(3,2) DEFAULT 0.7, -- 温度参数 + max_tokens INT DEFAULT 2000, -- 最大 Token 数 + + -- 缓存的可用模型列表 + available_models JSONB DEFAULT '{}', -- {"text": [...], "vision": [...], "audio": [...]} + models_updated_at TIMESTAMPTZ, -- 模型列表更新时间 + + -- 状态 + is_configured BOOLEAN DEFAULT false, -- 是否已完成配置 + last_test_at TIMESTAMPTZ, -- 最后测试时间 + last_test_result JSONB, -- 最后测试结果 + + -- 元数据 + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW(), + updated_by UUID, + + -- 外键 + CONSTRAINT fk_tenant FOREIGN KEY (tenant_id) REFERENCES brands(id) +); + +-- 索引 +CREATE INDEX idx_ai_config_tenant ON ai_configs(tenant_id); +``` + +### 3.2 提供商类型枚举 + +```python +from enum import Enum + +class AIProvider(str, Enum): + """支持的 AI 提供商""" + + # 中转服务 + ONEAPI = "oneapi" # OneAPI 中转 + OPENROUTER = "openrouter" # OpenRouter + + # 直连厂商 - 国际 + ANTHROPIC = "anthropic" # Anthropic Claude + OPENAI = "openai" # OpenAI + + # 直连厂商 - 国内 + DEEPSEEK = "deepseek" # DeepSeek + QWEN = "qwen" # 阿里云通义千问 + DOUBAO = "doubao" # 字节豆包 + ZHIPU = "zhipu" # 智谱 GLM + MOONSHOT = "moonshot" # Moonshot (Kimi) + + +# 提供商默认 Base URL +PROVIDER_DEFAULT_URLS = { + AIProvider.ANTHROPIC: "https://api.anthropic.com/v1", + AIProvider.OPENAI: "https://api.openai.com/v1", + AIProvider.DEEPSEEK: "https://api.deepseek.com/v1", + AIProvider.QWEN: "https://dashscope.aliyuncs.com/compatible-mode/v1", + AIProvider.DOUBAO: "https://ark.cn-beijing.volces.com/api/v3", + AIProvider.ZHIPU: "https://open.bigmodel.cn/api/paas/v4", + AIProvider.MOONSHOT: "https://api.moonshot.cn/v1", +} +``` + +### 3.3 模型能力分类 + +```python +class ModelCapability(str, Enum): + """模型能力类型""" + TEXT = "text" # 文字处理 + VISION = "vision" # 视觉理解 + AUDIO = "audio" # 音频处理 + + +# 已知模型的能力映射（用于分类显示） +MODEL_CAPABILITIES = { + # 文字处理模型 + "claude-opus-4-5-20251101": [ModelCapability.TEXT, ModelCapability.VISION], + "claude-sonnet-4-20250514": [ModelCapability.TEXT, ModelCapability.VISION], + "gpt-4o": [ModelCapability.TEXT, ModelCapability.VISION], + "gpt-4o-mini": [ModelCapability.TEXT, ModelCapability.VISION], + "deepseek-chat": [ModelCapability.TEXT], + "deepseek-reasoner": [ModelCapability.TEXT], + "qwen-max": [ModelCapability.TEXT], + "qwen-plus": [ModelCapability.TEXT], + "glm-4": [ModelCapability.TEXT], + "moonshot-v1-128k": [ModelCapability.TEXT], + + # 视觉模型 + "qwen-vl-max": [ModelCapability.VISION], + "qwen-vl-plus": [ModelCapability.VISION], + "Doubao-Seed-1.6-thinking": [ModelCapability.VISION], + "doubao-vision-pro": [ModelCapability.VISION], + "glm-4v": [ModelCapability.VISION], + + # 音频模型 + "whisper-large-v3": [ModelCapability.AUDIO], + "whisper-1": [ModelCapability.AUDIO], + "paraformer-v2": [ModelCapability.AUDIO], + "sensevoice": [ModelCapability.AUDIO], +} +``` + +--- + +## 4. API 接口设计 + +### 4.1 获取当前配置 + +``` +GET /api/v1/ai-config +Authorization: Bearer {token} +``` + +**响应：** +```json +{ + "provider": "oneapi", + "base_url": "https://oneapi.intelligrow.cn", + "api_key_masked": "sk-****...****", + "models": { + "text": "claude-opus-4-5-20251101", + "vision": "Doubao-Seed-1.6-thinking", + "audio": "whisper-large-v3" + }, + "parameters": { + "temperature": 0.7, + "max_tokens": 2000 + }, + "available_models": { + "text": ["claude-opus-4-5-20251101", "deepseek-chat", "gpt-4o", ...], + "vision": ["Doubao-Seed-1.6-thinking", "qwen-vl-max", "gpt-4o", ...], + "audio": ["whisper-large-v3", "paraformer-v2", ...] + }, + "is_configured": true, + "last_test_at": "2026-02-02T10:30:00Z", + "last_test_result": { + "text": {"success": true, "latency_ms": 342}, + "vision": {"success": true, "latency_ms": 528}, + "audio": {"success": true, "latency_ms": 215} + } +} +``` + +### 4.2 更新配置 + +``` +PUT /api/v1/ai-config +Authorization: Bearer {token} +Content-Type: application/json + +{ + "provider": "oneapi", + "base_url": "https://oneapi.intelligrow.cn", + "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx", + "models": { + "text": "claude-opus-4-5-20251101", + "vision": "Doubao-Seed-1.6-thinking", + "audio": "whisper-large-v3" + }, + "parameters": { + "temperature": 0.7, + "max_tokens": 2000 + } +} +``` + +### 4.3 获取可用模型列表 + +``` +POST /api/v1/ai-config/models +Authorization: Bearer {token} +Content-Type: application/json + +{ + "provider": "oneapi", + "base_url": "https://oneapi.intelligrow.cn", + "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx" +} +``` + +**响应：** +```json +{ + "success": true, + "models": { + "text": [ + {"id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5"}, + {"id": "deepseek-chat", "name": "DeepSeek Chat"}, + {"id": "gpt-4o", "name": "GPT-4o"}, + ... + ], + "vision": [ + {"id": "Doubao-Seed-1.6-thinking", "name": "豆包 Seed 1.6"}, + {"id": "qwen-vl-max", "name": "通义千问 VL Max"}, + {"id": "gpt-4o", "name": "GPT-4o (Vision)"}, + ... + ], + "audio": [ + {"id": "whisper-large-v3", "name": "Whisper Large V3"}, + {"id": "paraformer-v2", "name": "Paraformer V2"}, + ... + ] + } +} +``` + +### 4.4 测试连接 + +``` +POST /api/v1/ai-config/test +Authorization: Bearer {token} +Content-Type: application/json + +{ + "provider": "oneapi", + "base_url": "https://oneapi.intelligrow.cn", + "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx", + "models": { + "text": "claude-opus-4-5-20251101", + "vision": "Doubao-Seed-1.6-thinking", + "audio": "whisper-large-v3" + } +} +``` + +**响应：** +```json +{ + "success": false, + "results": { + "text": { + "success": true, + "latency_ms": 342, + "model": "claude-opus-4-5-20251101" + }, + "vision": { + "success": true, + "latency_ms": 528, + "model": "Doubao-Seed-1.6-thinking" + }, + "audio": { + "success": false, + "error": "Model not found or unauthorized", + "model": "whisper-large-v3" + } + }, + "message": "1 个模型连接失败，请检查模型名称或 API 权限" +} +``` + +--- + +## 5. 核心代码设计 + +### 5.1 配置模型 (Pydantic) + +```python +# app/models/ai_config.py + +from pydantic import BaseModel, Field, SecretStr +from typing import Optional, Dict, List +from decimal import Decimal + +from app.models.enums import AIProvider + + +class AIModelsConfig(BaseModel): + """三个模型配置""" + text: str = Field(..., description="文字处理模型") + vision: str = Field(..., description="视频分析模型") + audio: str = Field(..., description="音频解析模型") + + +class AIParametersConfig(BaseModel): + """参数配置""" + temperature: Decimal = Field(default=Decimal("0.7"), ge=0, le=1) + max_tokens: int = Field(default=2000, ge=100, le=32000) + + +class AIConfigUpdate(BaseModel): + """更新 AI 配置请求""" + provider: AIProvider + base_url: str + api_key: SecretStr + models: AIModelsConfig + parameters: AIParametersConfig = AIParametersConfig() + + +class AIConfigResponse(BaseModel): + """AI 配置响应""" + provider: AIProvider + base_url: str + api_key_masked: str # 脱敏后的 API Key + models: AIModelsConfig + parameters: AIParametersConfig + available_models: Dict[str, List[dict]] + is_configured: bool + last_test_at: Optional[str] + last_test_result: Optional[dict] + + +class ModelTestResult(BaseModel): + """单个模型测试结果""" + success: bool + latency_ms: Optional[int] = None + error: Optional[str] = None + model: str + + +class TestConnectionResponse(BaseModel): + """测试连接响应""" + success: bool # 三个都成功才为 True + results: Dict[str, ModelTestResult] + message: str +``` + +### 5.2 AI 服务路由器 + +```python +# app/services/ai/router.py + +from typing import Optional +from uuid import UUID + +from app.models.ai_config import AIModelsConfig, AIParametersConfig +from app.repositories.ai_config_repo import AIConfigRepository +from app.services.ai.client_factory import AIClientFactory + + +class AIServiceRouter: + """AI 服务路由器 - 根据租户获取配置并调用对应模型""" + + def __init__( + self, + config_repo: AIConfigRepository, + client_factory: AIClientFactory, + ): + self.config_repo = config_repo + self.client_factory = client_factory + + async def get_config(self, tenant_id: UUID) -> dict: + """获取租户的 AI 配置""" + config = await self.config_repo.get_by_tenant(tenant_id) + if not config or not config.is_configured: + raise ValueError(f"Tenant {tenant_id} has not configured AI service") + return config + + async def chat( + self, + tenant_id: UUID, + messages: list, + model_type: str = "text", # text / vision / audio + **kwargs + ) -> dict: + """统一的对话接口""" + config = await self.get_config(tenant_id) + + # 根据类型选择模型 + model = getattr(config.models, model_type) + + # 获取客户端 + client = await self.client_factory.get_client( + base_url=config.base_url, + api_key=config.api_key, + ) + + # 调用 + return await client.chat( + messages=messages, + model=model, + temperature=float(config.parameters.temperature), + max_tokens=config.parameters.max_tokens, + **kwargs + ) + + async def transcribe( + self, + tenant_id: UUID, + audio_file: bytes, + ) -> dict: + """音频转文字""" + config = await self.get_config(tenant_id) + + client = await self.client_factory.get_client( + base_url=config.base_url, + api_key=config.api_key, + ) + + return await client.transcribe( + audio=audio_file, + model=config.models.audio, + ) +``` + +### 5.3 测试连接服务 + +```python +# app/services/ai/connection_tester.py + +import asyncio +from typing import Dict +from openai import AsyncOpenAI + +from app.models.ai_config import ModelTestResult, TestConnectionResponse + + +class AIConnectionTester: + """AI 连接测试服务""" + + async def test_all_models( + self, + base_url: str, + api_key: str, + models: Dict[str, str], # {"text": "...", "vision": "...", "audio": "..."} + ) -> TestConnectionResponse: + """并行测试三个模型""" + + # 并行执行测试 + tasks = [ + self._test_model(base_url, api_key, model_type, model_id) + for model_type, model_id in models.items() + ] + results = await asyncio.gather(*tasks, return_exceptions=True) + + # 整理结果 + result_dict = {} + all_success = True + failed_count = 0 + + for model_type, result in zip(models.keys(), results): + if isinstance(result, Exception): + result_dict[model_type] = ModelTestResult( + success=False, + error=str(result), + model=models[model_type] + ) + all_success = False + failed_count += 1 + else: + result_dict[model_type] = result + if not result.success: + all_success = False + failed_count += 1 + + # 生成消息 + if all_success: + message = "所有模型连接成功" + else: + message = f"{failed_count} 个模型连接失败，请检查模型名称或 API 权限" + + return TestConnectionResponse( + success=all_success, + results=result_dict, + message=message + ) + + async def _test_model( + self, + base_url: str, + api_key: str, + model_type: str, + model_id: str, + ) -> ModelTestResult: + """测试单个模型""" + import time + + client = AsyncOpenAI(base_url=base_url, api_key=api_key) + + start_time = time.time() + + try: + if model_type == "audio": + # ASR 模型测试 - 检查模型是否存在 + models = await client.models.list() + model_exists = any(m.id == model_id for m in models.data) + if not model_exists: + return ModelTestResult( + success=False, + error="Model not found", + model=model_id + ) + else: + # 文字/视觉模型测试 - 发送简单请求 + await client.chat.completions.create( + model=model_id, + messages=[{"role": "user", "content": "Hi"}], + max_tokens=5, + ) + + latency_ms = int((time.time() - start_time) * 1000) + + return ModelTestResult( + success=True, + latency_ms=latency_ms, + model=model_id + ) + + except Exception as e: + return ModelTestResult( + success=False, + error=str(e), + model=model_id + ) +``` + +--- + +## 6. 安全设计 + +### 6.1 API Key 加密存储 + +- 使用 AES-256 加密存储 API Key +- 主密钥从环境变量或密钥管理服务 (Vault/KMS) 获取 +- API 响应中永不返回完整 API Key，仅返回脱敏版本 + +```python +def mask_api_key(api_key: str) -> str: + """API Key 脱敏""" + if len(api_key) <= 8: + return "****" + return f"{api_key[:4]}...{api_key[-4:]}" +``` + +### 6.2 权限控制 + +| 操作 | 系统管理员 | 品牌方管理员 | 代理商 | 达人 | +| --- | :---: | :---: | :---: | :---: | +| 查看 AI 配置 | ✅ (全部) | ✅ (仅自己) | ❌ | ❌ | +| 修改 AI 配置 | ✅ | ✅ (仅自己) | ❌ | ❌ | +| 测试连接 | ✅ | ✅ (仅自己) | ❌ | ❌ | +| 查看完整 API Key | ❌ | ❌ | ❌ | ❌ | + +--- + +## 7. 界面设计 + +> 详见 UIDesign.md 第 10 章「AI 服务配置界面」 + +### 7.1 界面入口 + +品牌方端 → 系统设置 → AI 服务配置 + +### 7.2 界面结构 + +1. **提供商选择** - 下拉选择 AI 提供商 +2. **连接配置** - Base URL 和 API Key 输入 +3. **获取模型按钮** - 点击后从 API 获取可用模型列表 +4. **模型配置** - 三个下拉框分别选择文字/视觉/音频模型 +5. **参数配置** - Temperature 滑块和 Max Tokens 输入 +6. **测试连接按钮** - 并行测试三个模型 +7. **保存配置按钮** + +--- + +## 8. 相关文档 + +| 文档 | 说明 | +| --- | --- | +| UIDesign.md | UI 设计规范（第 10 章 AI 配置界面） | +| User_Role_Interfaces.md | 用户角色与界面规范 | +| tasks.md | 开发任务清单 | +| DevelopmentPlan.md | 开发计划与技术架构 | diff --git a/DevelopmentPlan.md b/DevelopmentPlan.md new file mode 100644 index 0000000..371b86a --- /dev/null +++ b/DevelopmentPlan.md @@ -0,0 +1,518 @@ +这是一个基于 `RequirementsDoc.md`、`FeatureSummary.md` (V1.2) 和 `User_Role_Interfaces.md` 编写的开发计划文档。 + +这份文档旨在指导技术团队进行架构设计、选型和排期，重点在于解决**视频处理的高并发/高延迟**、**多模态 AI 的集成**以及**移动端适配**等工程难点。 + +文件名：`DevelopmentPlan.md` + +--- + +# DevelopmentPlan.md - 智能视频审核系统开发计划 + +| 文档类型 | **Development Plan (技术架构与实施计划)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.2 | +| **日期** | 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 技术方案、验收标准、数据模型、测试策略 | +| V1.2 | 2026-02-03 | Claude | Reviewer 修正：Logo检测改向量检索、Brief解析增VLM、弹性GPU、H5防锁屏、排期调整 | +| V1.2.1 | 2026-02-03 | Claude | 补充多模态时间戳对齐流程图 (Gemini 建议) | +| V1.3 | 2026-02-02 | Claude | **确立 TDD 为项目核心开发规范**，关联 tdd_plan.md | +| V1.4 | 2026-02-02 | Claude | **新增 AI 厂商动态配置架构**，支持数据库配置、运行时热更新、多租户隔离 | + +--- + +## 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 解析服务 (Layout+VLM+LLM)] + Svc_NLP[脚本/语义分析 (LLM)] + Svc_Video[视频多模态流水线] + Svc_Logo[Logo 向量检索服务] + 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 + Wake Lock API** | 达人端无需开发原生 App，通过 Next.js 响应式布局覆盖 iOS/Android 浏览器及微信内嵌浏览器。⭐ 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 加密：** 使用 Fernet 对称加密存储敏感信息 +> +> **支持的厂商类型：** +> - 国内厂商：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/Milvus) +> 4. 视频帧检测时：提取候选区域 → 生成 Embedding → 向量相似度匹配 +> ``` +> +> **优势：** 支持 SaaS 模式下品牌**动态添加竞品 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.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` + +**验收标准：** +- 时长统计误差 ≤ 0.5秒 +- 频次统计准确率 ≥ 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.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。 +**总周期：约 11 周 (2.75 个月)** ⭐ V1.2 调整：Phase 2 延长 1 周 + +### Phase 1: 基础设施与 Brief 引擎 (Weeks 1-2) + +* **Backend:** 搭建 FastAPI 框架，PG 数据库设计，接入 OSS。 +* **AI:** 调试 Brief 解析 Prompt (Layout + VLM + LLM)，搭建竞品 Logo 向量库。 +* **Frontend:** 完成 PC 端框架搭建，Brief 上传与解析交互。 +* **交付物:** 能够上传 PDF（含图片）并提取出 JSON 规则。 + +### 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.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) + +> ⭐ **核心原则：本项目全程遵循 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 厂商动态配置架构设计（V1.3 新增）** | +| 数据字典 | 待编写 | +| API 接口规范 | 待编写 | diff --git a/FeatureSummary.md b/FeatureSummary.md new file mode 100644 index 0000000..a1e946e --- /dev/null +++ b/FeatureSummary.md @@ -0,0 +1,909 @@ +# FeatureSummary.md - 产品功能清单 + +| 文档类型 | **Feature Summary (产品功能文档)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.2 | +| **发布日期** | 2026-02-02 | +| **关联文档** | RequirementsDoc.md, PRD.md, User_Role_Interfaces.md | +| **侧重** | 功能清单、优先级、验收标准、界面映射、边界说明 | + +--- + +## 版本历史 (Version History) + +| 版本 | 日期 | 作者 | 变更说明 | +| --- | --- | --- | --- | +| V1.0 | 2026-02-02 | Claude | 基于 RD/PRD/UI 文档整合产出功能清单 | +| V1.1 | 2026-02-02 | Claude | 根据 Gemini 修订意见调整：补充验收标准、Out of Scope、核心痛点细化 | +| V1.2 | 2026-02-02 | Claude | 根据 Gemini 关键改进意见：优先级调整、功能拆分、新增功能、移动端适配 | +| V1.3 | 2026-02-02 | Claude | **新增 AI 厂商动态配置功能模块 (F-47~F-50)**，支持数据库配置、多租户隔离 | + +**Gemini 修订意见采纳情况：** + +| 意见 | 采纳 | 说明 | +| --- | --- | --- | +| F-09 语境理解 P1→P0 | ✅ | 避免"人工智障"体验，是用户体验底线 | +| F-17 进度展示 P1→P0 | ✅ | 3-5分钟等待无反馈会导致用户流失 | +| F-30 ZIP→多文件拖拽 | ✅ | 降低服务器解压风险，体验更好 | +| F-05 拆分基础/高级 | ✅ | MVP必须能防竞品，拆分为 F-05-A (P0) / F-05-B (P1) | +| 新增移动端 H5 适配 | ✅ | 达人工作场景多在移动端 | +| 新增时长/频次校验 | ✅ | 新增 F-45，满足 Brief 硬性指标 (如 >5s) | +| 新增 AI 闭环学习 | ✅ | 新增 F-46 (P2)，完善产品闭环 | + +--- + +## 1. 产品概述 + +### 1.1 产品定位 + +SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**，定位为**"智能预审员"**，在人工介入前**自动化拦截 80% 的基础错误和合规风险**，将审核流转周期从"天"缩短到"小时"。 + +### 1.2 核心价值 + +| 用户角色 | 核心痛点 | 痛点详细描述 | 产品价值 | +| --- | --- | --- | --- | +| **品牌方** | 担心达人内容导致品牌翻车 | 害怕由于达人"口无遮拦"或"价值观不当"导致品牌翻车；人工疲劳导致漏判（如竞品露出、边缘违禁词），极易引发公关危机 | 舆情风险提前预警，证据链完整可追溯 | +| **代理商** | 大量人力浪费在低价值审核工作 | 深陷于"传话筒"困境，大量人力浪费在检查错别字、Brief 对齐等低价值工作上；人工审核一条 3 分钟视频+对比 Brief 平均耗时 15-20 分钟，且需反复修改 3-5 轮 | 效率提升 4 倍（20分钟→5分钟），批量处理 | +| **达人** | 反馈模糊，反复修改 | 痛恨模糊的反馈（如"感觉不对"），希望获得即时、明确的修改指令，以便尽快结算；不同审核员对"品牌调性"理解不同，导致达人无所适从 | 即时明确的修改指令，带时间戳的修改清单 | + +### 1.3 成功指标 + +| 指标 | 目标值 | +| --- | --- | +| 单条视频人工投入时长 | 从 20 分钟降至 ≤ 5 分钟 | +| AI 脚本预审后首次通过率 | 提升 ≥ 30% | +| 违禁词/竞品 Logo 召回率 | ≥ 95% | +| 违禁词/竞品 Logo 误报率 | ≤ 5% | +| 舆情/价值观判断一致性 | ≥ 80% | +| 代理商 NPS | 提升 ≥ 10 分 | + +--- + +## 2. 功能模块总览 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SmartAudit 功能架构 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Brief 解析 │ │ 脚本预审 │ │ 视频审核 │ │ +│ │ 与规则管理 │ │ (Pre-prod) │ │ (Post-prod) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 审核台 │ │ 申诉与仲裁 │ │ 版本比对 │ │ +│ │ 人工复核 │ │ │ │ 批量处理 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 数据看板 │ │ 规则配置 │ │ 审计日志 │ │ +│ │ │ │ 舆情预警 │ │ 证据导出 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 3. 功能清单详解 + +### 3.1 Brief 解析与规则管理 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-01 | Brief 文档上传与解析 | P0 | US-01 | 代理商 | +| F-02 | 在线文档链接导入 | P0 | US-01 | 代理商 | +| F-03 | 平台规则库自动加载 | P0 | US-02 | 品牌方/代理商 | +| F-04 | 区域合规规则切换 | P0 | US-02 | 品牌方 | +| F-05-A | 基础黑白名单与竞品库 | **P0** | US-10 | 品牌方 | +| F-05-B | 高级豁免规则配置 | P1 | US-10 | 品牌方 | +| F-06 | 规则版本管理与审计 | P1 | US-10 | 品牌方 | + +#### F-01 Brief 文档上传与解析 + +**功能描述：** 支持上传 PDF/Word/Excel/PPT/图片格式的 Brief 文档，AI 自动提取核心卖点、禁忌词、品牌调性要求。 + +**验收标准：** +- 图文混排 Brief 解析准确率 > 90% +- 支持加密 PDF 的解析失败提示与手动输入降级 + +**界面映射：** 代理商端 → Brief 配置中心 → 全能解析器 + +--- + +#### F-02 在线文档链接导入 + +**功能描述：** 支持导入飞书/Notion 等已授权的在线文档分享链接。 + +**约束条件：** +- 仅支持用户授权的分享链接 +- 不得绕过权限或抓取受限内容 + +**界面映射：** 代理商端 → Brief 配置中心 → 在线文档链接导入 + +--- + +#### F-03 平台规则库自动加载 + +**功能描述：** 选择投放平台（抖音/小红书/B站等）后，自动加载对应平台的最新违禁词库，并校验 Brief 要求与平台规则是否冲突。 + +**验收标准：** +- 规则冲突提示清晰可追溯 +- 平台规则变更后 ≤ 1 工作日内更新 + +**界面映射：** 代理商端 → Brief 配置中心 → 投放平台选择 + +--- + +#### F-04 区域合规规则切换 + +**功能描述：** 不同地区投放可切换对应法规与平台规则版本（中国大陆/港澳台/海外）。 + +**界面映射：** +- 代理商端 → Brief 配置中心 → 区域合规切换 +- 品牌方端 → 规则配置 → 区域合规配置 + +--- + +#### F-05-A 基础黑白名单与竞品库 ⭐ P0 + +**功能描述：** 品牌方可配置基础私有规则，确保 MVP 具备核心防御能力。 + +**核心功能：** +- 禁用词库分类管理（广告法/平台规则/品牌私有） +- 竞品 Logo 图库上传，支持相似度阈值设置 +- 基础白名单配置 + +**为什么是 P0：** 品牌方购买本系统的核心动力之一是"防竞品"，MVP 必须具备此能力。 + +**界面映射：** 品牌方端 → 规则配置 → 黑白名单管理 + +--- + +#### F-05-B 高级豁免规则配置 + +**功能描述：** 品牌方可配置高级豁免规则，支持复杂的条件逻辑。 + +**子功能：** +- 特定达人豁免规则 +- 特定场景豁免规则 +- 条件组合逻辑（如：达人A + 平台B = 豁免规则C） + +**界面映射：** 品牌方端 → 规则配置 → 高级豁免规则 + +--- + +#### F-06 规则版本管理与审计 + +**功能描述：** 规则变更历史可追溯，支持回滚，变更需审批生效。 + +**验收标准：** +- 记录变更人、变更时间、变更内容 +- 支持回滚到历史版本 + +**界面映射：** 品牌方端 → 规则配置 → 规则版本管理 + +--- + +### 3.2 脚本预审 (Pre-production) + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-07 | 文本脚本提交与预审 | P0 | US-03 | 达人 | +| F-08 | 违规检测与修改建议 | P0 | US-03 | 达人 | +| F-09 | 语境理解降低误报 | **P0** | US-04 | 达人 | + +#### F-07 文本脚本提交与预审 + +**功能描述：** 达人在拍摄前提交文字脚本，系统检查是否遗漏卖点或触犯广告法。 + +**核心价值：** 避免拍完重拍的巨大沉没成本 + +**界面映射：** 达人端 → 智能上传页 + +--- + +#### F-08 违规检测与修改建议 + +**功能描述：** 输出违规项、遗漏卖点，并给出具体修改建议。 + +**输出示例：** +- 错误类型：广告法违禁词 +- 原内容："全网第一" +- AI建议：建议改为"深受喜爱"或"销量领先" + +**界面映射：** 达人端 → 审核结果页 → 修改清单 + +--- + +#### F-09 语境理解降低误报 ⭐ P0 + +**功能描述：** AI 区分广告语境与日常语境，避免将非广告内容误判为违规。 + +**示例：** 不将"最开心的一天"误判为广告极限词违规 + +**验收标准：** 广告极限词与非广告语境的区分误报率 ≤ 5%（样本量 ≥ 1,000 句） + +**为什么是 P0：** 如果 MVP 版本把"我**最**开心的一天"误判为广告法极限词违规，达人会认为这个 AI 是"人工智障"，导致口碑崩盘。这是用户体验的底线。 + +**界面映射：** 达人端 → 审核结果页 + +--- + +### 3.3 视频智能审核 (Post-production) + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-10 | 视频上传 | P0 | US-05 | 达人 | +| F-11 | 多模态联合检测 | P0 | US-05 | 系统 | +| F-12 | 竞品 Logo 检测 | P0 | US-05 | 系统 | +| F-13 | 违禁词口播检测 | P0 | US-05 | 系统 | +| F-14 | 时间戳风险标注 | P0 | US-05 | 系统 | +| F-45 | 时长与频次校验 | **P0** | US-05 | 系统 | +| F-15 | Brand Safety 软性风险提示 | P1 | US-06 | 系统 | +| F-16 | 分区审核规则 | P1 | US-06 | 系统 | +| F-17 | 审核进度实时展示 | **P0** | US-07 | 达人 | +| F-18 | 时间戳修改清单 | P1 | US-07 | 达人 | + +#### F-10 视频上传 + +**功能描述：** 支持视频文件上传 + +**约束条件：** +- 文件大小 ≤ 100MB +- 分辨率支持 1080p +- 格式支持 MP4/MOV + +**界面映射：** 达人端 → 智能上传页 + +--- + +#### F-11 多模态联合检测 + +**功能描述：** ASR（语音识别）+ OCR（字幕识别）+ CV（画面检测）联合检测 + +**验收标准：** +- ASR 字错率 ≤ 10%（普通话 + 主流方言） +- OCR 准确率 ≥ 95%（含复杂背景） + +**技术依赖：** 多模态 LLM、ASR 引擎、OCR 引擎、CV 检测 + +--- + +#### F-12 竞品 Logo 检测 + +**功能描述：** 自动检测视频画面中是否出现竞品 Logo 或不雅背景，精确到秒数标注。 + +**验收标准：** 竞品 Logo F1 ≥ 0.85（含画面角落遮挡 30% 场景） + +**界面映射：** 代理商端 → 审核决策台 → 智能进度条（红点标注） + +--- + +#### F-13 违禁词口播检测 + +**功能描述：** 通过 ASR 识别口播内容，检测违禁词。 + +**界面映射：** 代理商端 → 审核决策台 → AI 检查单 → 硬性合规 + +--- + +#### F-14 时间戳风险标注 + +**功能描述：** 输出时间戳级别的风险点（精确到秒数） + +**界面映射：** +- 代理商端 → 审核决策台 → 智能进度条 +- 达人端 → 审核结果页 → 时间轴跳转 + +--- + +#### F-45 时长与频次校验 ⭐ P0 (新增) + +**功能描述：** 根据 Brief 中的时序要求，自动校验视频是否满足时长和频次指标。 + +**典型场景：** +- Brief 要求"产品同框必须 > 5秒" +- Brief 要求"口播提及品牌名 ≥ 3次" +- Brief 要求"产品特写镜头 ≥ 2个" + +**输出示例：** +``` +⚠️ 时长不足：产品同框仅 3.2秒，Brief 要求 > 5秒 +✅ 频次达标：品牌名提及 4次，Brief 要求 ≥ 3次 +``` + +**验收标准：** 时长统计误差 ≤ 0.5秒，频次统计准确率 ≥ 95% + +**界面映射：** 代理商端 → 审核决策台 → AI 检查单 → 时序校验 + +--- + +#### F-15 Brand Safety 软性风险提示 + +**功能描述：** 检测油腻、爹味说教、性别偏见等舆情风险。 + +**重要约束：** **仅作提示，不强制拦截**，需人工复核确认 + +**界面映射：** 代理商端 → 审核决策台 → AI 检查单 → 舆情雷达 + +--- + +#### F-16 分区审核规则 + +**功能描述：** 智能区分"广告段"与"剧情段"，应用不同审核尺度。 + +**界面映射：** 代理商端 → 审核决策台 + +--- + +#### F-17 审核进度实时展示 ⭐ P0 + +**功能描述：** 在等待期间显示 AI 处理进度。 + +**展示示例：** +- 🔍 正在解析 Brief 核心卖点... +- 👁️ 正在逐帧检测竞品 Logo... +- 🧠 正在分析口播情感色彩... + +**验收标准：** 报告产出时间 ≤ 5 分钟 + +**为什么是 P0：** 视频上传+审核通常需要 3-5 分钟。如果 MVP 只有一个旋转的"Loading"图标而没有具体的文字进度，用户会以为死机了而关闭页面，导致用户流失。 + +**界面映射：** 达人端 → 智能上传页 → 透明思考 UI + +--- + +#### F-18 时间戳修改清单 + +**功能描述：** 审核完成后提供带时间戳的修改清单。 + +**界面映射：** 达人端 → 审核结果页 → 修改清单 + +--- + +### 3.4 审核台与人工复核 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-19 | 风险列表展示 | P0 | US-08 | 代理商 | +| F-20 | 确认/驳回操作 | P0 | US-08 | 代理商 | +| F-21 | 强制通过权 | P1 | US-09 | 品牌方 | +| F-22 | 特例记录与白名单 | P1 | US-09 | 品牌方 | +| F-23 | 规则依据与证据查看 | P1 | US-08 | 代理商/品牌方 | + +#### F-19 风险列表展示 + +**功能描述：** 审核台展示 AI 标记的风险点（红/黄/绿分级）与时间戳。 + +**风险等级：** +- 🔴 红色：硬性违规，必须处理 +- 🟡 黄色：舆情风险，建议检查 +- 🟢 绿色：合规/卖点识别 + +**界面映射：** 代理商端 → 审核决策台 → AI 检查单 + +--- + +#### F-20 确认/驳回操作 + +**功能描述：** 审核员只需点击确认或驳回，无需从头看视频。 + +**操作说明：** +- 驳回：自动将勾选的问题打包发送给达人 +- 通过：流程结束 + +**界面映射：** 代理商端 → 审核决策台 → 决策栏 + +--- + +#### F-21 强制通过权 + +**功能描述：** 品牌方可手动放行过于保守的误报（如达人玩的新梗）。 + +**约束条件：** +- 必须填写放行原因 +- 记录审批人与操作时间，纳入审计日志 + +**界面映射：** 代理商端 → 审核决策台 → 决策栏 → [强制通过] + +--- + +#### F-22 特例记录与白名单 + +**功能描述：** 将当前判断记录为规则白名单/豁免条款。 + +**约束条件：** +- 需品牌方确认后生效 +- 如需用于模型优化，必须确保数据授权与合规评估 + +**界面映射：** +- 代理商端 → 审核决策台 → 决策栏 → [记录为特例] +- 品牌方端 → 规则配置 → 特例记录 + +--- + +#### F-23 规则依据与证据查看 + +**功能描述：** 可查看每条结论的规则依据与证据片段。 + +**验收标准：** 每条结论包含规则版本、模型版本、证据截图/片段与时间戳 + +**界面映射：** 代理商端 → 审核决策台 → AI 检查单（点击展开详情） + +--- + +### 3.5 申诉与仲裁 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-24 | 发起申诉 | P1 | - | 达人 | +| F-25 | 申诉令牌管理 | P1 | - | 系统 | +| F-26 | 人工仲裁 | P1 | - | 代理商 | +| F-27 | 申诉结果通知 | P1 | - | 达人 | + +#### F-24 发起申诉 + +**功能描述：** 达人可对每条报错发起申诉。 + +**操作要求：** +- 提供理由输入框（必填，≥ 10 字） +- 可上传补充证据（截图、链接等） +- 消耗申诉令牌 + +**界面映射：** 达人端 → 审核结果页 → [申诉] 按钮 + +--- + +#### F-25 申诉令牌管理 + +**功能描述：** 基于达人信用评分分配令牌配额，申诉成功后令牌返还。 + +**规则说明：** +- 历史表现越好，配额越高 +- 申诉成功后令牌自动返还 + +**界面映射：** 达人端 → 审核结果页 → 申诉弹窗（显示剩余令牌） + +--- + +#### F-26 人工仲裁 + +**功能描述：** 代理商对申诉进行仲裁，记录仲裁结论。 + +**界面映射：** 代理商端 → 工作台 → 申诉待仲裁 + +--- + +#### F-27 申诉结果通知 + +**功能描述：** 申诉结果通过消息中心通知达人。 + +**通知文案：** "您的申诉已通过，AI 已学习您的反馈。" + +**界面映射：** 达人端 → 消息通知中心 + +--- + +### 3.6 版本比对与批量处理 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-28 | 版本差异报告 | P2 | US-13 | 代理商 | +| F-29 | 双屏同步播放 | P2 | US-13 | 代理商 | +| F-30 | 批量上传 | P2 | US-11 | 代理商 | +| F-31 | 批量审核 | P2 | US-11 | 代理商 | +| F-32 | 批量导出 | P2 | US-11 | 代理商 | + +#### F-28 版本差异报告 + +**功能描述：** AI 明确告知"V1版本中指出的N个违规点，有X个已修复，Y个未修复"。 + +**展示示例：** +``` +V1 版本指出 3 个违规点：✅ 已修复 2 个 | ❌ 未修复 1 个 +``` + +**界面映射：** 代理商端 → 版本比对视窗 → 顶部统计摘要 + +--- + +#### F-29 双屏同步播放 + +**功能描述：** 左侧 V1，右侧 V2 同步播放，点击条目可跳转到对应时间戳。 + +**界面映射：** 代理商端 → 版本比对视窗 → 双屏模式 + +--- + +#### F-30 批量上传 + +**功能描述：** 支持多文件拖拽上传 (Multi-file Drag & Drop)，利用现代浏览器的并发上传能力。 + +**技术说明：** +- ~~原方案：ZIP 压缩包上传~~ (已废弃) +- 新方案：多文件拖拽 + 并发上传 +- 废弃原因：ZIP 在 Web 端上传会带来带宽压力、超时断连风险及服务器解压算力消耗 + +**界面映射：** 代理商端 → 批量操作中心 + +--- + +#### F-31 批量审核 + +**功能描述：** 对无问题项批量通过（需二次确认）。 + +**界面映射：** 代理商端 → 批量操作中心 + +--- + +#### F-32 批量导出 + +**功能描述：** 一键导出选中任务的审核报告。 + +**导出格式：** Excel/PDF，包含完整审核证据链 + +**界面映射：** 代理商端 → 批量操作中心 / 数据报表 + +--- + +### 3.7 数据看板与报表 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-33 | 核心指标卡片 | P0 | - | 品牌方 | +| F-34 | 趋势图表 | P1 | - | 品牌方 | +| F-35 | 风险预警 | P1 | - | 品牌方 | +| F-36 | 代理商绩效对比 | P1 | - | 品牌方 | +| F-37 | 达人排行榜 | P2 | - | 代理商 | + +#### F-33 核心指标卡片 + +**功能描述：** 展示审核总量、初审通过率、硬性召回率、舆情拦截数、平均审核周期。 + +**界面映射：** 品牌方端 → 数据看板 → 顶部指标卡片 + +--- + +#### F-34 趋势图表 + +**功能描述：** +- 近 30 天审核量与通过率趋势 +- 问题分布饼图（违禁词/竞品/舆情/卖点遗漏） +- 问题高发时段热力图 + +**界面映射：** 品牌方端 → 数据看板 → 可视化图表区 + +--- + +#### F-35 风险预警 + +**功能描述：** 实时预警异常情况。 + +**预警类型：** +- 🔴 紧急：竞品露出集中爆发 +- 🟠 关注：达人连续未通过 +- 🟡 舆情：舆情拦截数异常上升 + +**界面映射：** 品牌方端 → 数据看板 → 风险预警区 + +--- + +#### F-36 代理商绩效对比 + +**功能描述：** 柱状图对比各代理商的审核效率与通过率。 + +**界面映射：** 品牌方端 → 数据看板 → 代理商对比 + +--- + +#### F-37 达人排行榜 + +**功能描述：** 按通过率、响应速度对达人排名，预警问题达人。 + +**界面映射：** 代理商端 → 数据报表 → 达人维度 + +--- + +### 3.8 审计日志与证据导出 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-38 | 审核记录查询 | P1 | US-12 | 品牌方 | +| F-39 | 完整审核链路查看 | P1 | US-12 | 品牌方 | +| F-40 | 证据链 PDF 导出 | P1 | US-12 | 品牌方/代理商 | + +#### F-38 审核记录查询 + +**功能描述：** 查看所有审核记录，支持高级筛选（时间/代理商/达人/结果）。 + +**界面映射：** 品牌方端 → 审计日志 → 列表视图 + +--- + +#### F-39 完整审核链路查看 + +**功能描述：** 点击任意记录查看完整审核链路，包含原始视频、AI 报告、人工决策、申诉记录。 + +**界面映射：** 品牌方端 → 审计日志 → 详情页 + +--- + +#### F-40 证据链 PDF 导出 + +**功能描述：** 生成符合法务要求的 PDF 报告。 + +**报告内容：** +- 时间戳：所有操作的精确时间记录 +- 截图：AI 报错对应的视频截图 +- 规则依据：触发的规则版本与具体条款 +- 审核人：操作人身份与电子签名 +- 规则版本号、模型版本号 +- 完整操作日志（不可篡改） + +**界面映射：** 品牌方端 → 审计日志 → 证据链导出 + +--- + +### 3.9 舆情预警中心 + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-41 | 舆情风险视频监控 | P2 | US-06 | 品牌方 | +| F-42 | 舆情案例库 | P2 | - | 品牌方 | +| F-43 | 舆情阈值设置 | P1 | US-10 | 品牌方 | + +#### F-41 舆情风险视频监控 + +**功能描述：** 近期被 AI 标记为"舆情风险"的视频列表，按风险等级排序。 + +**界面映射：** 品牌方端 → 舆情预警中心 → 实时监控 + +--- + +#### F-42 舆情案例库 + +**功能描述：** 历史舆情事件归档，作为培训素材供代理商学习。 + +**界面映射：** 品牌方端 → 舆情预警中心 → 案例库 + +--- + +#### F-43 舆情阈值设置 + +**功能描述：** 调整 AI 对"油腻"、"性感"、"争议话题"的敏感度，支持按平台差异化配置。 + +**重要约束：** 舆情风险仅作提示，不作为强制拦截依据 + +**界面映射：** 品牌方端 → 规则配置 → 舆情阈值设置 + +--- + +### 3.10 AI 闭环学习 (新增) + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-46 | 负样本清洗与回流 | P2 | - | 系统 | + +--- + +### 3.11 系统管理 - AI 厂商配置 (V1.4 新增) + +| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 | +| --- | --- | --- | --- | --- | +| F-47 | AI 厂商动态配置 | P0 | - | 系统管理员 | +| F-48 | AI 厂商连通性测试 | P0 | - | 系统管理员 | +| F-49 | 多租户 AI 配置隔离 | P1 | - | 系统管理员/品牌方 | +| F-50 | API Key 轮换管理 | P1 | - | 系统管理员 | + +#### F-47 AI 厂商动态配置 ⭐ P0 + +**功能描述：** 系统管理员可在后台配置多个 AI 厂商（DeepSeek、OpenAI、通义千问、OneAPI 中转等），配置存储在数据库中，运行时动态加载，无需修改代码或重启服务。 + +**核心功能：** +- 支持添加、编辑、删除 AI 厂商配置 +- 配置 Base URL、API Key（加密存储）、默认模型 +- 为不同使用场景（Brief 解析、脚本预审、视频审核）指定不同厂商 +- 配置优先级和备用厂商（故障转移） + +**为什么是 P0：** 这是 AI 服务的基础设施，所有 AI 功能都依赖此配置。 + +**界面映射：** 系统管理后台 → AI 厂商管理 + +**技术文档：** 详见 [AIProviderConfig.md](./AIProviderConfig.md) + +--- + +#### F-48 AI 厂商连通性测试 + +**功能描述：** 配置 AI 厂商后，可测试连通性，验证 API Key 是否有效。 + +**界面映射：** 系统管理后台 → AI 厂商管理 → [测试连通性] + +--- + +#### F-49 多租户 AI 配置隔离 + +**功能描述：** 不同品牌方可配置独立的 AI 厂商，实现租户级别的配置隔离和配额管理。 + +**界面映射：** 品牌方后台 → 系统设置 → AI 配置 + +--- + +#### F-50 API Key 轮换管理 + +**功能描述：** 支持定期轮换 API Key，无需重启服务即可生效。 + +**界面映射：** 系统管理后台 → AI 厂商管理 → [轮换密钥] + +#### F-46 负样本清洗与回流 (Feedback Loop) + +**功能描述：** 系统自动收集"人工驳回 AI 判定"的案例，清洗为微调数据集，用于后续模型优化。 + +**工作流程：** +1. 收集：记录所有"人工推翻 AI 判定"的案例 +2. 清洗：过滤噪声数据，标注有效负样本 +3. 回流：定期将清洗后的数据用于模型微调 +4. 验证：A/B 测试验证模型效果提升 + +**数据合规：** +- 需确保数据授权与合规评估 +- 品牌方私有数据需单独授权 + +**界面映射：** 后台管理 → 模型优化 → 负样本管理 + +> 💡 **说明：** F-22 提到了"特例记录"，F-27 提到了"AI 已学习您的反馈"，但这只是前端文案。本功能是真正让 AI 变聪明的机制。 + +--- + +## 4. 功能优先级汇总 + +### 4.1 MVP (P0) - 必须实现 + +| 功能编号 | 功能名称 | 模块 | 备注 | +| --- | --- | --- | --- | +| F-01 | Brief 文档上传与解析 | Brief 管理 | | +| F-02 | 在线文档链接导入 | Brief 管理 | | +| F-03 | 平台规则库自动加载 | Brief 管理 | | +| F-04 | 区域合规规则切换 | Brief 管理 | | +| F-05-A | 基础黑白名单与竞品库 | Brief 管理 | ⭐ 从 F-05 拆分，MVP 必须能防竞品 | +| F-07 | 文本脚本提交与预审 | 脚本预审 | | +| F-08 | 违规检测与修改建议 | 脚本预审 | | +| F-09 | 语境理解降低误报 | 脚本预审 | ⭐ P1→P0，避免"人工智障"体验 | +| F-10 | 视频上传 | 视频审核 | | +| F-11 | 多模态联合检测 | 视频审核 | | +| F-12 | 竞品 Logo 检测 | 视频审核 | | +| F-13 | 违禁词口播检测 | 视频审核 | | +| F-14 | 时间戳风险标注 | 视频审核 | | +| F-45 | 时长与频次校验 | 视频审核 | ⭐ 新增，满足 Brief 硬性指标 | +| F-17 | 审核进度实时展示 | 视频审核 | ⭐ P1→P0，缓解等待焦虑 | +| F-19 | 风险列表展示 | 审核台 | | +| F-20 | 确认/驳回操作 | 审核台 | | +| F-33 | 核心指标卡片 | 数据看板 | | +| F-47 | AI 厂商动态配置 | 系统管理 | ⭐ V1.3 新增，AI 基础设施 | +| F-48 | AI 厂商连通性测试 | 系统管理 | ⭐ V1.3 新增 | + +### 4.2 V1.1 (P1) - 首版后快速迭代 + +| 功能编号 | 功能名称 | 模块 | 备注 | +| --- | --- | --- | --- | +| F-05-B | 高级豁免规则配置 | Brief 管理 | 从 F-05 拆分 | +| F-06 | 规则版本管理与审计 | Brief 管理 | | +| F-15 | Brand Safety 软性风险提示 | 视频审核 | | +| F-16 | 分区审核规则 | 视频审核 | | +| F-18 | 时间戳修改清单 | 视频审核 | | +| F-21 | 强制通过权 | 审核台 | | +| F-22 | 特例记录与白名单 | 审核台 | | +| F-23 | 规则依据与证据查看 | 审核台 | | +| F-24~27 | 申诉与仲裁 | 申诉 | | +| F-34~36 | 趋势图表与预警 | 数据看板 | | +| F-38~40 | 审计日志与证据导出 | 审计 | | +| F-43 | 舆情阈值设置 | 舆情 | | +| F-49 | 多租户 AI 配置隔离 | 系统管理 | ⭐ V1.3 新增 | +| F-50 | API Key 轮换管理 | 系统管理 | ⭐ V1.3 新增 | + +> ⚠️ **注意：** F-09 (语境理解) 和 F-17 (进度展示) 已提升至 P0 + +### 4.3 V2 (P2) - 中长期规划 + +| 功能编号 | 功能名称 | 模块 | 备注 | +| --- | --- | --- | --- | +| F-28~29 | 版本差异报告与双屏播放 | 版本比对 | | +| F-30~32 | 批量上传/审核/导出 | 批量处理 | F-30 改为多文件拖拽 | +| F-37 | 达人排行榜 | 数据报表 | | +| F-41~42 | 舆情监控与案例库 | 舆情 | | +| F-46 | 负样本清洗与回流 | AI 闭环 | ⭐ 新增，让 AI 真正学习 | + +--- + +## 5. 角色-功能映射 + +| 功能模块 | 达人 | 代理商 | 品牌方 | +| --- | --- | --- | --- | +| Brief 管理 | 查看 | 上传/编辑 | 配置规则 | +| 脚本预审 | ✅ 提交 | 查看 | 查看 | +| 视频审核 | ✅ 上传 | 查看报告 | 查看报告 | +| 审核台 | ❌ | ✅ 初审 | ✅ 终审/强制通过 | +| 申诉 | ✅ 发起 | ✅ 仲裁 | ❌ | +| 版本比对 | ❌ | ✅ | ✅ | +| 批量处理 | ❌ | ✅ | ✅ | +| 数据看板 | 个人进度 | 项目/达人 | 全局 | +| 规则配置 | ❌ | ❌ | ✅ | +| 审计日志 | ❌ | 所管辖 | 全部 | +| 舆情预警 | ❌ | ❌ | ✅ | + +--- + +## 6. 非功能性要求 + +| 类别 | 要求 | +| --- | --- | +| **可用性** | 月度可用性 ≥ 99.5%，支持灰度发布与快速回滚 | +| **性能** | 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟（排队 ≤ 2 分钟） | +| **安全** | 传输与存储加密；基于角色权限控制；关键操作二次确认 | +| **隐私** | 数据最小化；默认保留 30 天；符合《个保法》与 GDPR | +| **数据本地化** | 国内客户数据存储于中国大陆境内服务器 | +| **审计** | 操作日志可审计且不可篡改 | +| **移动端适配** | **达人端（上传/查看报告）必须适配移动端 H5 竖屏操作** | + +> ⚠️ **移动端适配说明：** 达人的工作场景多在拍摄现场（移动端），需要在手机上完成脚本上传、查看审核结果等操作。如果只做 PC 网页版，达人无法在拍摄现场即时使用，产品价值会大打折扣。 + +--- + +## 7. 合规约束 + +| 约束类型 | 说明 | +| --- | --- | +| **规则来源** | 必须基于公开法规、平台官方规则或品牌方授权的 Brief | +| **可解释性** | AI 不做黑盒决策，每条结论必须给出证据与规则依据 | +| **辅助决策** | 系统为"辅助工具"，不直接触发平台处罚，最终责任由人工承担 | +| **软性风控边界** | 主观风险（油腻/爹味等）仅作提示，不强制拦截 | +| **数据隔离** | 品牌方 Brief 和私有数据严格隔离，不得用于训练通用模型 | +| **在线文档** | 仅支持用户授权的分享链接，不得绕过权限抓取 | + +--- + +## 8. Out of Scope（本期不做） + +为明确产品边界，以下功能**不在本期范围内**： + +| 序号 | 排除功能 | 说明 | +| --- | --- | --- | +| 1 | **视频剪辑工具** | 不提供在线剪辑功能，仅提供修改意见 | +| 2 | **支付与结算** | 不涉及品牌与达人的资金交易 | +| 3 | **发布后数据监测** | 不负责视频发布后的点赞/评论/转化数据分析 | +| 4 | **自动下架/投诉处理** | 不直接触发平台处罚或下架动作，系统定位为"辅助工具" | +| 5 | **直播流/实时切片审核** | 本期仅支持离线上传视频文件，不支持直播流的实时接入与毫秒级审核 | + +--- + +## 9. 验收标准 (Acceptance Criteria) + +产品上线前必须满足以下验收标准： + +| 验收项 | 标准 | 测量方式 | +| --- | --- | --- | +| **Brief 解析准确率** | 图文混排 PDF Brief 提取准确率 **> 90%** | 标注测试集评估 | +| **竞品 Logo 检测** | 画面角落遮挡 30% 的竞品 Logo，F1 **≥ 0.85** | 标注测试集评估 | +| **语义理解误报率** | 广告极限词与非广告语境区分误报率 **≤ 5%** | 样本量 ≥ 1,000 句 | +| **ASR 字错率** | 普通话 + 主流方言字错率 **≤ 10%** | 标注测试集评估 | +| **OCR 准确率** | 含复杂背景字幕准确率 **≥ 95%** | 标注测试集评估 | +| **审核报告产出时间** | 100MB 以内视频，报告产出时间 **≤ 5 分钟** | 系统埋点统计 | +| **审计链路完整性** | 每条结论包含规则版本、模型版本、证据截图/片段与时间戳 | 人工抽查验证 | + +--- + +## 10. 相关文档 + +| 文档名称 | 说明 | +| --- | --- | +| RequirementsDoc.md | 业务需求文档（用户故事、成功指标） | +| PRD.md | 产品需求文档（功能需求、技术架构） | +| User_Role_Interfaces.md | 用户角色与界面规范 | +| **AIProviderConfig.md** | **AI 厂商动态配置架构设计（V1.3 新增）** | +| 技术设计文档 (TDD) | 待编写 | +| API 接口规范 | 待编写 | +| 数据字典 | 待编写 | +| 测试计划 | 待编写 | diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..ef43242 --- /dev/null +++ b/PRD.md @@ -0,0 +1,402 @@ +# PRD.md - 智能视频合规审核系统 + +| 文档类型 | **PRD (Product Requirement Document)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.0 | +| **发布日期** | 2026-01-30 | +| **状态** | 草稿 (Draft) | +| **负责人** | 产品经理 | + +--- + +## 版本历史 (Version History) + +| 版本 | 日期 | 作者 | 变更说明 | +| --- | --- | --- | --- | +| V0.1 | 2026-01-30 | - | 基于 RequirementsDoc.md 产出首版 PRD | +| V0.2 | 2026-01-30 | ClaudeCode | 根据 RD 审阅修订：补充技术架构、术语定义、用户故事引用、品牌方工作流 | +| V0.3 | 2026-01-30 | Codex | 合规一致性修订：补充一致性定义、软性风控提示边界与特例记录规范 | +| V0.4 | 2026-01-30 | Claude | 审阅调整：补充产品愿景与量化目标、假设与约束章节、细化背景数据 | +| V1.0 | 2026-02-02 | Claude | 新增 AI 厂商动态配置架构引用 | + +--- + +## 1. 背景与目标 (Background & Goals) + +### 1.1 背景 + +品牌短视频投放已成主流，但当前人工审核存在严重瓶颈： + +1. **效率低下：** 人工审核一条 3 分钟视频+对比 Brief 平均耗时 15-20 分钟，且需反复修改 3-5 轮 +2. **标准不一：** 不同审核员对"品牌调性"理解不同，导致达人无所适从 +3. **风险高企：** 人工疲劳导致漏判（如竞品露出、边缘违禁词），极易引发公关危机 + +### 1.2 产品愿景 + +打造一款**基于多模态大模型的 B2B SaaS 审核工具**。系统定位为**"智能预审员"**，在人工介入前**自动化拦截 80% 的基础错误和合规风险**，将审核流转周期从"天"缩短到"小时"。 + +### 1.3 目标 + +- 建立可复用的多模态审核能力，实现文本、语音、画面一致审核 +- 在保持合规的前提下，将审核周期从天级缩短至小时级 +- 形成可审计、可申诉、可追溯的审核证据链 + +### 1.4 非目标 (Non-Goals) + +- 不提供视频剪辑或制作工具。 +- 不涉及支付与结算。 +- 不负责发布后数据监测。 +- 不支持直播流实时审核。 +- 不自动触发平台处罚或下架动作。 + +--- + +## 2. 术语与定义 (Glossary) + +| 术语 | 定义 | +| --- | --- | +| Brief | 品牌投放要求文件，包含卖点、禁忌、话术、素材规范等 | +| 违禁词库 | 平台与法律合规要求的规则集合（含极限词、功效词、敏感话题等） | +| 初审通过率 | 仅经过 AI 预审后一次性通过的比例（不进入人工返工） | +| 召回率/误报率 | 在标注测试集中识别到"确实违规"的比例 / 误判为违规的比例 | +| Brand Safety | 涉及价值观、偏见、歧视、舆情争议等非硬性违规风险 | +| 一致性 | 软性风控结论与人工复核结论一致的比例（以人工复核为基准） | +| 版本比对 (Diff) | 针对同一任务的不同版本视频，自动识别修改点和未修改点的能力 | + +--- + +## 3. 成功指标 (Success Metrics) + +| 指标类别 | 指标名称 | 目标值 | 测量方式 | 责任方 | +| --- | --- | --- | --- | --- | +| 效率 | 单条视频人工投入时长 | 从 20 分钟降至 ≤ 5 分钟 | 系统埋点统计（30 天样本） | 产品经理 | +| 质量 | AI 脚本预审后首次通过率 | 提升 ≥ 30% | 对比上线前 30 天基线 | 算法团队 | +| 硬性召回 | 违禁词/竞品 Logo 召回率 | ≥ 95% | 标注测试集评估 | 算法团队 | +| 硬性误报 | 违禁词/竞品 Logo 误报率 | ≤ 5% | 标注测试集评估 | 算法团队 | +| 软性一致性 | 舆情/价值观判断一致性 | ≥ 80% | 人工复核抽样比对 | 运营团队 | +| 用户满意度 | 代理商 NPS | 提升 ≥ 10 分 | 季度问卷调研 | 客户成功 | + +**基线数据采集计划：** 上线前 30 天内完成现有流程的数据埋点，建立各项指标的基线值。 + +--- + +## 4. 目标用户与核心场景 (Personas & Key Scenarios) + +### 4.1 用户角色 + +| 角色 | 描述 | 核心动机 | 典型行为 | +| --- | --- | --- | --- | +| **品牌方 MKT (Brand)** | 甲方市场部负责人，对内容安全负最终责任 | **安全第一**：宁可错杀，不可放过 | 下达 Brief，抽查视频，处理争议 | +| **代理商媒介 (Agency)** | 连接品牌与达人的中间方，系统高频使用者 | **效率至上**：快速过审，减少沟通成本 | 上传 Brief，初审任务，仲裁 | +| **达人/KOL (Creator)** | 内容创作者，系统的被审核端 | **通过率与结算**：希望反馈明确 | 上传脚本/视频，查看报告，申诉 | + +### 4.2 核心场景与优先级 + +> 引用 RequirementsDoc.md 用户故事编号 + +**P0（MVP 必须实现）** +- Brief 上传解析与规则提取 → [US-01] +- 平台规则库加载 → [US-02] +- 脚本预审 → [US-03] +- 视频自动审核（竞品、违禁词、画面风险） → [US-05] +- 审核台风险打点与确认/驳回 → [US-08] + +**P1（首版发布后快速迭代）** +- 语境理解降低误报 → [US-04] +- Brand Safety 软性风险提示 → [US-06] +- 审核进度展示与时间戳修改清单 → [US-07] +- 强制通过权与特例记录 → [US-09] +- 品牌私有规则管理与版本记录 → [US-10] +- 证据链导出 → [US-12] + +**P2（中长期规划）** +- 批量上传/导出 → [US-11] +- 版本差异报告 → [US-13] + +--- + +## 5. 产品范围 (Scope) + +### 5.1 In Scope + +- **全能文档解析引擎：** 支持 PDF/Word/Excel/PPT/图片/在线链接 的 Brief 自动解析与规则结构化 +- **多模态审核核心：** 包含 NLP (文本/语义)、ASR (语音)、OCR (字幕)、CV (画面/物体) 综合检测能力 +- **分区执法逻辑：** 智能区分"广告段"与"剧情段"，应用不同审核尺度 +- **舆情风控雷达：** 针对"油腻感"、"价值观风险"、"错别字"的专项检测 +- **交互式审核台：** 支持时间戳打点、风险高亮、版本比对 (Diff) 的 Web 界面 +- **信用与申诉体系：** 包含申诉令牌管理和人工仲裁流程 +- **规则库管理与版本控制：** 支持平台规则库更新、品牌私有规则与白名单配置 +- **权限与多租户隔离：** 支持品牌/代理/达人不同角色的权限与数据隔离 +- **审计日志与报告导出：** 支持导出可追溯的审核证据链 + +### 5.2 Out of Scope + +- 视频剪辑工具：不提供在线剪辑功能，仅提供修改意见 +- 支付与结算：不涉及品牌与达人的资金交易 +- 发布后数据监测：不负责视频发布后的点赞/评论/转化数据分析 +- 自动下架/投诉处理：不直接触发平台处罚或下架动作 +- 直播流/实时切片审核：本期仅支持离线上传视频文件 + +--- + +## 6. 功能需求 (Functional Requirements) + +> 说明：以下以模块划分，标注优先级 (P0/P1/P2)，并引用 RD 用户故事编号。 + +### 6.1 Brief 与规则管理 [US-01, US-02, US-10] + +**P0** +- 支持 PDF/Word/Excel/PPT/图片上传与解析 +- 支持已授权在线文档链接导入（如飞书/Notion分享链接） + - **重要约束**：仅支持用户授权的分享链接；不得绕过权限或抓取受限内容 +- 自动提取核心卖点、禁忌词、品牌调性要求 +- 平台规则库按投放平台（抖音、小红书、B站等）自动加载并校验冲突 +- **区域合规支持**：不同地区投放需切换对应法规与平台规则版本 + +**P1** +- 品牌私有规则管理（禁用词、白名单、竞品列表） +- 规则版本管理与变更审计（可追溯的变更记录） + +**验收要点** +- 图文混排 Brief 解析准确率 > 90% +- 规则冲突提示清晰可追溯 + +### 6.2 脚本预审 (Pre-production) [US-03, US-04] + +**P0** +- 支持文本脚本提交与预审 +- 输出违规项、遗漏卖点、建议修改 +- 帮助达人在拍摄前发现问题，避免拍完重拍的沉没成本 + +**P1** +- 语境理解降低误报（区分广告语境与日常语境） + - 例如：不应将"最开心的一天"误判为广告极限词违规 + +**验收要点** +- 广告极限词与非广告语境的区分误报率 ≤ 5%（样本量 ≥ 1,000 句） + +### 6.3 视频智能审核 (Post-production) [US-05, US-06, US-07] + +**P0** +- 支持视频上传（≤ 100MB，1080p） +- ASR/OCR/CV 联合检测 +- 检测竞品 Logo、不雅背景、违禁词口播 +- 输出时间戳级别的风险点（精确到秒数） + +**P1** +- Brand Safety 软性风险提示（油腻、爹味说教、性别偏见等） + - **仅提示不强制拦截**，需人工复核确认 +- 广告段/剧情段分区审核规则 +- **审核进度展示**：在等待期间显示 AI 处理进度（如"正在核对口播..."） +- 审核完成后提供带时间戳的修改清单 + +**验收要点** +- 竞品 Logo F1 ≥ 0.85（含画面角落遮挡 30% 场景） +- ASR 字错率 ≤ 10%（普通话 + 主流方言） +- OCR 准确率 ≥ 95%（含复杂背景） +- 报告产出时间 ≤ 5 分钟 + +### 6.4 审核台与人工复核 [US-08, US-09] + +**P0** +- 审核台展示风险列表（红/黄/绿分级）与时间戳 +- 支持确认/驳回操作，无需从头看视频 + +**P1** +- 品牌方"强制通过权"：可手动放行过于保守的误报（需记录原因与审批人） +- 支持将特例记录为规则白名单/豁免条款（需品牌方确认） + - 如需用于模型优化，必须确保数据授权与合规评估 +- 可查看规则依据与证据片段 + +**验收要点** +- 每条结论包含规则版本、模型版本、证据截图/片段与时间戳 + +### 6.5 申诉与仲裁 + +**P1** +- 申诉令牌管理与工单流转 +- 人工仲裁流程与记录 +- 审计日志完整可追溯 + +### 6.6 版本差异与批量处理 [US-11, US-13] + +**P2** +- **新旧版本差异报告**：AI 明确告知"V1版本中指出的N个违规点，有X个已修复，Y个未修复" +- 批量上传与批量导出审核报告 + +--- + +## 7. 关键流程 (Key User Flows) + +### 7.1 品牌方工作流 + +1. 制定并下达 Brief 投放要求 +2. 配置品牌私有规则（禁用词、竞品列表、白名单） +3. 抽查最终视频审核报告 +4. 处理严重争议与风险决策 +5. 行使"强制通过权"处理误报 +6. 导出审核证据链用于合规归档 + +### 7.2 代理商工作流 + +1. 创建任务并上传 Brief +2. 系统解析 Brief 并生成规则集 +3. 创建达人任务并发起脚本预审 +4. 达人上传视频，系统自动审核 +5. 审核员在审核台确认/驳回（基于红/黄/绿风险标记） +6. 进行人工仲裁（如有争议） +7. 导出报告与证据链 + +### 7.3 达人工作流 + +1. 上传脚本进行预审 +2. 根据建议修改并提交视频 +3. 查看 AI 审核进度（如"正在核对口播..."） +4. 收到带时间戳的修改清单 +5. 触发申诉或修改再提交 + +--- + +## 8. 权限与多租户 (Permissions) + +| 角色 | 可见范围 | 关键权限 | +| --- | --- | --- | +| 品牌方 | 品牌内任务与规则 | 强制通过、规则管理、报告导出、私有规则配置 | +| 代理商 | 代理商管理范围 | 任务创建、审核确认/驳回、批量处理、人工仲裁 | +| 达人 | 自己的任务 | 上传脚本/视频、查看报告、申诉 | + +--- + +## 9. 数据与审计 (Data & Audit) + +### 9.1 核心对象 + +- **任务**：品牌、代理、达人、投放平台、版本号 +- **Brief**：原始文件、解析结构化内容 +- **规则集**：平台规则 + 品牌私有规则 + 白名单 + 规则版本记录 +- **审核记录**：风险项、时间戳、证据片段、风险等级（红/黄/绿） +- **人工决策**：确认/驳回/强制通过 + 操作人 + 操作时间 +- **申诉记录**：申诉原因、仲裁结论、令牌消耗 + +### 9.2 审计要求 [US-12] + +- 全流程日志可追溯、不可篡改 +- 导出报告包含规则版本、模型版本、证据截图/片段与时间戳 +- 支持争议场景下完整审核证据链导出 + +--- + +## 10. 非功能性需求 (NFR) + +- **可用性**：月度可用性 ≥ 99.5%，支持灰度发布与快速回滚 +- **性能**：1080p、≤ 100MB 视频生成报告 ≤ 5 分钟（排队时间不超过 2 分钟） +- **安全**：传输与存储加密；基于角色的权限控制；关键操作二次确认 +- **隐私**：数据最小化访问；默认保留原始视频/报告 30 天，可按品牌配置延长或缩短 +- **合规**：符合《个人信息保护法》与 GDPR；支持数据导出/删除；明确告知数据用途 +- **数据本地化**：国内客户数据存储于中国大陆境内服务器；跨境传输需用户明示同意并符合监管要求 +- **操作日志**：可审计且不可篡改 + +--- + +## 11. 假设与约束 (Assumptions & Constraints) + +- **技术约束：** 视频处理极其消耗算力，需接受"非实时"反馈（深度审核需 1-3 分钟延迟） +- **数据隐私：** 品牌方的 Brief 和私有数据必须严格隔离，不得用于训练通用模型 +- **平台依赖：** 若抖音/小红书的审核规则发生重大变更，系统需在一个工作日内更新规则库 +- **规则来源：** 具体合规规则由品牌/法务提供并确认，平台规则以官方公告为准 +- **在线文档接入：** 仅支持用户授权的分享链接；不得绕过权限或抓取受限内容 +- **区域合规：** 不同地区投放需切换对应法规与平台规则版本 + +--- + +## 12. 合规原则与风控 (Compliance) + +- **规则来源合法**：所有审核标准均需基于公开法律法规、平台官方规则或品牌方授权的私有 Brief；不得未经授权抓取或绕过登录限制 +- **可解释与可申诉**：AI 不做黑盒决策，每条结论必须给出证据片段与规则依据，并支持申诉与人工仲裁 +- **数据授权与最小化**：训练与评测数据需确保授权合规；默认最小化留存，过期自动清理 +- **辅助决策定位**：系统明确定义为"辅助工具"，不直接触发下架、投诉或平台处罚动作，最终责任由人工操作员承担 +- **偏见与歧视控制**：涉及主观评价的模型需经过偏见评估与定期复核，确保结论可解释且可追溯 +- **软性风控边界**：主观风险仅作提示，不作为强制拦截依据 + +--- + +## 13. 技术架构概述 (Technical Architecture Overview) + +> 详细架构见技术设计文档 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 用户接入层 │ +│ Web Dashboard │ API Gateway │ 飞书/企微机器人 │ SDK │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ 业务服务层 │ +│ Brief 解析服务 │ 脚本预审服务 │ 视频审核服务 │ 规则管理服务 │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ AI 能力层 │ +│ 多模态 LLM │ ASR 引擎 │ OCR 引擎 │ CV 检测 │ 向量检索 │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ 数据与存储层 │ +│ 对象存储 (视频/图片) │ 关系数据库 │ 向量数据库 │ 消息队列 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**核心技术依赖：** +- **多模态大模型**：用于语义理解、Brief 解析、舆情判断 +- **ASR/OCR**：支持普通话及主流方言的语音识别，支持复杂背景字幕识别 +- **计算机视觉**：Logo 检测、物体识别、场景分类 +- **消息队列**：异步处理视频审核任务，支持优先级调度 +- **AI 厂商动态配置**：支持在数据库中配置多个 AI 厂商（DeepSeek/OpenAI/OneAPI 等），运行时动态加载，支持多租户隔离和故障转移（详见 AIProviderConfig.md） + +--- + +## 14. 里程碑与发布计划 (Milestones) + +- **MVP (P0)**：Brief 解析、规则加载、脚本预审、视频审核、审核台 +- **V1.1 (P1)**：Brand Safety 提示、规则版本、证据链导出、强制通过权、审核进度展示 +- **V2 (P2)**：批量处理、版本差异报告 + +--- + +## 15. 风险与开放问题 (Open Questions) + +| 问题 | 详细描述 | 建议解决方向 | 决策责任人 | +| --- | --- | --- | --- | +| 规则迭代频率 | 平台规则变更频繁，如何确保及时同步？ | 建立官方公告订阅 + 人工值班巡检，SLA ≤ 1 工作日 | 运营负责人 | +| 训练数据来源 | 标注成本高、数据授权复杂、敏感数据脱敏 | 优先使用品牌方授权的历史审核数据，建立数据脱敏 Pipeline | 算法 + 法务 | +| 舆情判断边界 | "油腻/爹味"等主观标签由谁最终定义？ | 建立"品牌方确认"机制，软性风控仅作提示，不作为强制拦截 | 产品经理 | +| 多语言支持 | 海外投放需支持英语、日语等 | 本期仅支持中文（普通话 + 主流方言），多语言作为 V2 规划 | 产品经理 | +| 模型幻觉风险 | LLM 可能产生不准确的审核结论 | 关键判断必须提供证据片段，人工复核覆盖高风险内容 | 算法团队 | +| 定价与商业模式 | 按视频条数、时长还是座席收费？ | 待商业化团队确定，技术架构需支持多种计费维度 | 商业化负责人 | + +--- + +## 16. 相关文档 (References) + +- RequirementsDoc.md - 业务需求文档 +- **AIProviderConfig.md - AI 厂商动态配置架构设计** +- 技术设计文档 (TDD) - 待编写 +- API 接口规范 - 待编写 +- 数据字典 - 待编写 +- 测试计划 - 待编写 + +--- + +## 17. 缩略语 (Abbreviations) + +| 缩略语 | 全称 | 说明 | +| --- | --- | --- | +| ASR | Automatic Speech Recognition | 自动语音识别 | +| OCR | Optical Character Recognition | 光学字符识别 | +| CV | Computer Vision | 计算机视觉 | +| NLP | Natural Language Processing | 自然语言处理 | +| LLM | Large Language Model | 大语言模型 | +| NPS | Net Promoter Score | 净推荐值 | +| SLA | Service Level Agreement | 服务级别协议 | +| GDPR | General Data Protection Regulation | 通用数据保护条例（欧盟） | diff --git a/RequirementsDoc.md b/RequirementsDoc.md new file mode 100644 index 0000000..4acde0f --- /dev/null +++ b/RequirementsDoc.md @@ -0,0 +1,261 @@ +# RequirementsDoc.md - 智能视频合规审核系统 + +| 文档类型 | **RD (Requirements Document)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.0 | +| **发布日期** | 2026-01-30 | +| **状态** | **修订 (Revised)** | +| **侧重** | 商业背景、用户价值、用户故事、成功指标 | + +--- + +## 版本历史 (Version History) + +| 版本 | 日期 | 作者 | 变更说明 | +| --- | --- | --- | --- | +| V0.1 | 2026-01-30 | - | 初稿创建 | +| V0.2 | 2026-01-30 | Gemini | 修订用户故事、成功指标 | +| V0.3 | 2026-01-30 | Codex | 优化合规建议 | +| V1.0 | 2026-01-30 | Claude | 综合审核：增加优先级、技术架构、合规细化 | + +--- + +## 1. 业务背景与市场机会 (Business Context) + +### 1.1 市场现状 + +随着短视频营销（TikTok, 小红书, B站）成为品牌投放的主流阵地，品牌方每年需要审核数千甚至数万条达人视频。目前的审核流程存在严重瓶颈： + +1. **效率低下：** 人工审核一条 3 分钟视频+对比 Brief 平均耗时 15-20 分钟，且需反复修改 3-5 轮。 +2. **标准不一：** 不同审核员对“品牌调性”理解不同，导致达人无所适从。 +3. **风险高企：** 人工疲劳导致漏判（如竞品露出、边缘违禁词），极易引发公关危机。 + +### 1.2 核心痛点 + +* **对于品牌方：** 害怕由于达人“口无遮拦”或“价值观不当”导致品牌翻车。 +* **对于代理商：** 深陷于“传话筒”困境，大量人力浪费在检查错别字、Brief 对齐等低价值工作上。 +* **对于达人：** 痛恨模糊的反馈（如“感觉不对”），希望获得即时、明确的修改指令，以便尽快结算。 + +### 1.3 产品愿景 + +打造一款**基于多模态大模型的 B2B SaaS 审核工具**。它不是要取代人工，而是作为**“智能预审员”**，在人工介入前自动化拦截 80% 的基础错误和合规风险，将审核流转周期从“天”缩短到“小时”。 + +--- + +## 2. 术语与定义 (Glossary) + +* **Brief：** 品牌投放要求文件，包含卖点、禁忌、话术、素材规范等。 +* **违禁词库：** 平台与法律合规要求的规则集合（含极限词、功效词、敏感话题等）。 +* **初审通过率：** 仅经过 AI 预审后一次性通过的比例（不进入人工返工）。 +* **召回率/误报率：** 在标注测试集中，系统识别到“确实违规”的比例 / 误判为违规的比例。 +* **Brand Safety：** 涉及价值观、偏见、歧视、舆情争议等非硬性违规风险。 +* **一致性：** 软性风控结论与人工复核结论一致的比例（以人工复核为基准）。 +* **版本比对 (Diff)：** 针对同一任务的不同版本视频，自动识别修改点和未修改点的能力。 + +--- + +## 3. 用户角色 (Personas) + +| 角色 | 描述 | 核心动机 (Motivation) | 典型行为 | +| --- | --- | --- | --- | +| **品牌方 MKT (Brand)** | 甲方市场部负责人，对内容安全负最终责任。 | **安全第一**。宁可错杀，不可放过；维护品牌高端形象。 | 下达 Brief，抽查最终视频，处理严重争议。 | +| **代理商媒介 (Agency)** | 连接品牌与达人的中间方，系统的高频使用者。 | **效率至上**。希望快速过审，减少沟通成本，同时管理上百个达人。 | 上传 Brief，初审达人作业，进行仲裁。 | +| **达人/KOL (Creator)** | 内容创作者，系统的被审核端。 | **通过率与结算**。希望反馈明确，不要反复折腾。 | 上传脚本/视频，查看报错，申诉，修改。 | + +--- + +## 4. 用户故事 (User Stories) + +我们将需求拆解为具体的场景故事，以确保功能设计满足真实业务流。 + +### 4.1 场景一：任务启动与规则定义 + +* **[US-01] [P0]** 作为 **代理商**，我希望能够直接上传各种格式的原始 Brief（PDF扫描件、Excel分镜表、Word文档）**以及已授权的在线文档链接（如飞书/Notion分享链接）**，让系统自动提取出"核心卖点"和"禁忌词"，无需手动录入。 +* **[US-02] [P0]** 作为 **品牌方**，我希望系统能自动根据投放平台（如抖音、小红书）加载最新的平台违禁词库，确保 Brief 的要求不违反平台底线。 + +### 4.2 场景二：脚本预审 (Pre-production) + +* **[US-03] [P0]** 作为 **达人**，我希望在拍摄前先提交文字脚本进行预审，让系统帮我检查是否遗漏了卖点或触犯了广告法，避免拍完重拍的巨大沉没成本。 +* **[US-04] [P1]** 作为 **达人**，我希望审核系统能"读懂上下文"，不要因为我在讲故事时说了"最开心的一天"就报"广告极限词违规"，减少对创作的干扰。 + +### 4.3 场景三：视频智能审核 (Post-production) + +* **[US-05] [P0]** 作为 **代理商**，我希望系统能自动检测视频画面中是否出现了"竞品Logo"或"不雅背景"，并精确到秒数标出来，因为人工肉眼看视频很容易走神漏掉。 +* **[US-06] [P1]** 作为 **品牌方**，我希望系统具备"舆情敏感度"，能提示达人视频中是否存在"油腻"、"爹味说教"或"性别偏见"的内容，帮助我规避潜在的公关风险（Brand Safety）。 +* **[US-07] [P1]** 作为 **达人**，我希望在视频上传后的等待期间能看到 AI 的处理进度（如"正在核对口播..."），并在审核完成后收到一份带时间戳的修改清单。 + +### 4.4 场景四：人工复核与决策 + +* **[US-08] [P0]** 作为 **代理商审核员**，我希望在审核台看到 AI 已经标记好的风险点（红/黄/绿），我只需要点击确认或驳回，而不是从头把视频看一遍。 +* **[US-09] [P1]** 作为 **品牌方**，我希望拥有"强制通过权"，当 AI 因为过于保守而报错（例如达人玩了一个很新的梗）时，我可以手动放行，并让系统记住这个特例。 + +### 4.5 场景五：规则运营与审计 + +* **[US-10] [P1]** 作为 **品牌方合规/法务**，我希望能配置"品牌私有规则"（如禁用词、竞品列表、白名单），并且对规则版本做可追溯的变更记录。 +* **[US-11] [P2]** 作为 **代理商**，我希望支持批量上传与批量导出审核报告，便于一次处理多条达人任务。 +* **[US-12] [P1]** 作为 **品牌方**，我希望在争议发生时能导出完整的审核证据链（时间戳、截图、规则依据、审核人）。 + +### 4.6 场景六：版本迭代与比对 + +* **[US-13] [P2]** 作为 **代理商**，当达人上传修改版视频 (V2) 时，我希望看到 **"新旧版本差异报告"**，AI 明确告知"V1版本中指出的3个违规点，有2个已修复，1个未修复"，从而极大缩短复审时间。 + +> **优先级说明：** P0 = MVP必须实现；P1 = 首版发布后快速迭代；P2 = 中长期规划 + +--- + +## 5. 成功指标 (Success Metrics / KPIs) + +如果项目上线后达到以下指标，视为成功： + +| 指标类别 | 指标名称 | 目标值 | 测量方式 | 责任方 | +| --- | --- | --- | --- | --- | +| **效率 (Efficiency)** | 单条视频人工投入时长 | 从 20 分钟降至 **≤ 5 分钟** | 系统埋点统计（30 天样本） | 产品经理 | +| **质量 (Quality)** | AI 脚本预审后首次通过率 | 提升 **≥ 30%** | 对比上线前 30 天基线 | 算法团队 | +| **硬性召回 (Hard Rules)** | 违禁词/竞品 Logo 召回率 | **≥ 95%** | 标注测试集评估 | 算法团队 | +| **硬性误报 (Hard Rules)** | 违禁词/竞品 Logo 误报率 | **≤ 5%** | 标注测试集评估 | 算法团队 | +| **软性一致性 (Soft Sentiment)** | 舆情/价值观判断一致性 | **≥ 80%** | 人工复核抽样比对 | 运营团队 | +| **用户满意度 (NPS)** | 代理商 NPS | 提升 **≥ 10 分** | 季度问卷调研 | 客户成功 | + +**基线数据采集计划：** 上线前 30 天内完成现有流程的数据埋点，建立各项指标的基线值。 + +--- + +## 6. 高层功能列表 (High-Level Features) + +### ✅ In Scope (核心功能) + +1. **全能文档解析引擎:** 支持 PDF/Word/Excel/PPT/图片/在线链接 的 Brief 自动解析与规则结构化。 +2. **多模态审核核心:** 包含 NLP (文本/语义)、ASR (语音)、OCR (字幕)、CV (画面/物体) 综合检测能力。 +3. **分区执法逻辑:** 智能区分“广告段”与“剧情段”，应用不同的审核尺度。 +4. **舆情风控雷达:** 针对“油腻感”、“价值观风险”、“错别字”的专项检测模型。 +5. **交互式审核台:** 支持时间戳打点、风险高亮、版本比对 (Diff) 的 Web 界面。 +6. **信用与申诉体系:** 包含申诉令牌管理和人工仲裁流程。 +7. **规则库管理与版本控制:** 支持平台规则库更新、品牌私有规则与白名单配置。 +8. **权限与多租户隔离:** 支持品牌/代理/达人不同角色的权限与数据隔离。 +9. **审计日志与报告导出:** 支持导出可追溯的审核证据链。 + +### ❌ Out of Scope (本期不做) + +1. **视频剪辑工具:** 不提供在线剪辑功能，仅提供修改意见。 +2. **支付与结算:** 不涉及品牌与达人的资金交易。 +3. **发布后数据监测:** 不负责视频发布后的点赞/评论/转化数据分析。 +4. **自动下架/投诉处理:** 不直接触发平台处罚或下架动作。 +5. **直播流/实时切片审核:** 本期仅支持离线上传视频文件，不支持直播流的实时接入与毫秒级审核。 + +--- + +## 7. 假设与约束 (Assumptions & Constraints) + +* **技术约束:** 视频处理极其消耗算力，需接受“非实时”反馈（深度审核需 1-3 分钟延迟）。 +* **数据隐私:** 品牌方的 Brief 和私有数据必须严格隔离，不得用于训练通用模型。 +* **平台依赖:** 若抖音/小红书的审核规则发生重大变更，系统需在一个工作日内更新规则库。 +* **规则来源:** 具体合规规则由品牌/法务提供并确认，平台规则以官方公告为准。 +* **在线文档接入:** 仅支持用户授权的分享链接；不得绕过权限或抓取受限内容。 +* **区域合规:** 不同地区投放需切换对应法规与平台规则版本。 + +--- + +## 7.1 技术架构概述 (Technical Architecture Overview) + +本节仅为高层技术选型参考，详细架构见技术设计文档。 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 用户接入层 │ +│ Web Dashboard │ API Gateway │ 飞书/企微机器人 │ SDK │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ 业务服务层 │ +│ Brief 解析服务 │ 脚本预审服务 │ 视频审核服务 │ 规则管理服务 │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ AI 能力层 │ +│ 多模态 LLM │ ASR 引擎 │ OCR 引擎 │ CV 检测 │ 向量检索 │ +└────────────────────────────┬────────────────────────────────────┘ + │ +┌────────────────────────────▼────────────────────────────────────┐ +│ 数据与存储层 │ +│ 对象存储 (视频/图片) │ 关系数据库 │ 向量数据库 │ 消息队列 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**核心技术依赖：** +* **多模态大模型：** 用于语义理解、Brief 解析、舆情判断 +* **ASR/OCR：** 支持普通话及主流方言的语音识别，支持复杂背景字幕识别 +* **计算机视觉：** Logo 检测、物体识别、场景分类 +* **消息队列：** 异步处理视频审核任务，支持优先级调度 +* **AI 厂商动态配置：** 支持在数据库中配置多个 AI 厂商（DeepSeek/OpenAI/OneAPI 等），运行时动态加载，支持多租户隔离和故障转移（详见 AIProviderConfig.md） + +--- + +## 8. 非功能性需求 (Non-Functional Requirements) + +* **可用性:** 月度可用性 ≥ 99.5%，支持灰度发布与快速回滚。 +* **性能:** 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟（排队时间不超过 2 分钟）。 +* **安全:** 传输与存储加密；基于角色的权限控制；关键操作二次确认。 +* **数据保留:** 默认保留原始视频/报告 30 天，可按品牌配置延长或缩短。 +* **合规与隐私:** 支持数据脱敏与最小化访问；操作日志可审计且不可篡改。 +* **个人信息保护:** 符合《个人信息保护法》及 GDPR 要求；用户数据可导出、可删除；明确告知数据用途。 +* **数据本地化:** 国内客户数据存储于中国大陆境内服务器；跨境传输需用户明示同意并符合监管要求。 + +--- + +## 9. 验收标准 (Acceptance Criteria) + +* **Brief 解析:** 能够正确解析包含图文混排的 PDF Brief，提取准确率 > 90%。 +* **多模态检测:** 在标注测试集中，系统能识别画面角落里遮挡 30% 的竞品 Logo，F1 ≥ 0.85。 +* **语义理解:** 对广告极限词与非广告语境的区分误报率 ≤ 5%（样本量 ≥ 1,000 句）。 +* **ASR/OCR:** 普通话 ASR 字错率 ≤ 10%，字幕 OCR 字准确率 ≥ 95%（含复杂背景）。 +* **性能:** 100MB 以内的视频上传后，AI 预审报告产出时间不超过 5 分钟。 +* **审计链路:** 每条结论包含规则版本、模型版本、证据截图/片段与时间戳。 + +--- + +## 10. 风险与合规原则 (Risks & Compliance Principles) + +### 10.1 系统合规性原则 + +* **规则来源合法：** 所有审核标准均需基于公开法律法规、平台官方规则或品牌方授权的私有 Brief；不得未经授权抓取或绕过登录限制。 +* **可解释与可申诉：** AI 不做黑盒决策，每条结论必须给出证据片段与规则依据，并支持申诉与人工仲裁。 +* **数据授权与最小化：** 训练与评测数据需确保授权合规；默认最小化留存，过期自动清理。 +* **辅助决策定位：** 系统明确定义为“辅助工具”，不直接触发下架、投诉或平台处罚动作，最终责任由人工操作员承担。 +* **偏见与歧视控制：** 涉及主观评价的模型需经过偏见评估与定期复核，确保结论可解释且可追溯。 + +### 10.2 开放问题 (Open Questions) + +| 问题 | 详细描述 | 建议解决方向 | 决策责任人 | +| --- | --- | --- | --- | +| **规则迭代频率** | 平台规则变更频繁，如何确保及时同步？ | 建立官方公告订阅 + 人工值班巡检，SLA ≤ 1 工作日 | 运营负责人 | +| **训练数据来源** | 标注成本高、数据授权复杂、敏感数据脱敏 | 优先使用品牌方授权的历史审核数据，建立数据脱敏 Pipeline | 算法 + 法务 | +| **舆情判断边界** | "油腻/爹味"等主观标签由谁最终定义？ | 建立"品牌方确认"机制，软性风控仅作提示，不作为强制拦截 | 产品经理 | +| **多语言支持** | 海外投放需支持英语、日语等 | 本期仅支持中文（普通话 + 主流方言），多语言作为 V2 规划 | 产品经理 | +| **模型幻觉风险** | LLM 可能产生不准确的审核结论 | 关键判断必须提供证据片段，人工复核覆盖高风险内容 | 算法团队 | +| **定价与商业模式** | 按视频条数、时长还是座席收费？ | 待商业化团队确定，技术架构需支持多种计费维度 | 商业化负责人 | + +--- + +## 11. 附录 (Appendix) + +### 11.1 相关文档 + +* 技术设计文档 (TDD) - 待编写 +* **AIProviderConfig.md - AI 厂商动态配置架构设计** +* API 接口规范 - 待编写 +* 数据字典 - 待编写 +* 测试计划 - 待编写 + +### 11.2 缩略语 + +| 缩略语 | 全称 | 说明 | +| --- | --- | --- | +| ASR | Automatic Speech Recognition | 自动语音识别 | +| OCR | Optical Character Recognition | 光学字符识别 | +| CV | Computer Vision | 计算机视觉 | +| NLP | Natural Language Processing | 自然语言处理 | +| LLM | Large Language Model | 大语言模型 | +| NPS | Net Promoter Score | 净推荐值 | +| SLA | Service Level Agreement | 服务级别协议 | +| GDPR | General Data Protection Regulation | 通用数据保护条例（欧盟） | diff --git a/UIDesign.md b/UIDesign.md new file mode 100644 index 0000000..197b1c2 --- /dev/null +++ b/UIDesign.md @@ -0,0 +1,1434 @@ +# UIDesign.md - 智能视频审核系统 UI 设计规范 + +| 文档类型 | **UI Design System (设计系统规范)** | +| --- | --- | +| **项目名称** | SmartAudit (AI 营销内容合规审核平台) | +| **版本号** | V1.0 | +| **发布日期** | 2026-02-02 | +| **设计风格** | Apple Human Interface Guidelines 浅色系 | +| **关联文档** | PRD.md, FeatureSummary.md, User_Role_Interfaces.md, DevelopmentPlan.md | + +--- + +## 版本历史 (Version History) + +| 版本 | 日期 | 作者 | 变更说明 | +| --- | --- | --- | --- | +| V1.0 | 2026-02-02 | Claude | 初稿：设计原则、色彩系统、组件库、三端界面规范 | +| V1.1 | 2026-02-02 | Claude | 新增第10章：AI 服务配置界面设计规范 | + +--- + +## 1. 设计原则 (Design Principles) + +借鉴 Apple Human Interface Guidelines，SmartAudit 的设计遵循以下核心原则： + +### 1.1 核心设计理念 + +| 原则 | 描述 | 在 SmartAudit 中的体现 | +| --- | --- | --- | +| **Clarity (清晰)** | 文字清晰易读，图标精确传意，功能显而易见 | 审核结论用红/黄/绿 + 文字 + 图标三重表达 | +| **Deference (克制)** | UI 退居幕后，内容为王 | 审核台以视频和报告为核心，界面元素轻量化 | +| **Depth (层次)** | 通过视觉层次和流畅动效建立空间感 | 卡片悬浮阴影、模态弹窗、进度条层叠 | + +### 1.2 SmartAudit 专属原则 + +| 原则 | 说明 | +| --- | --- | +| **透明 AI** | 不做黑盒，AI 的每一步思考都向用户展示（"正在检测 Logo..."） | +| **减少焦虑** | 长时任务（3-5分钟）提供精细进度反馈，允许用户离开并通知结果 | +| **轻量操作** | 达人端操作不超过 3 步完成核心任务（上传 → 等待 → 查看） | +| **专业高效** | 代理商/品牌方端追求信息密度与操作效率的平衡 | + +--- + +## 2. 色彩系统 (Color System) + +### 2.1 主色板 (Primary Palette) + +采用 Apple 风格浅色系，以纯净白色为基底，辅以柔和的功能色。 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 主色板 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ │ │ │ │ │ │ │ │ +│ │ Primary │ │Secondary │ │ Accent │ │ Dark │ │ +│ │ #007AFF │ │ #5856D6 │ │ #34C759 │ │ #1D1D1F │ │ +│ │ │ │ │ │ │ │ │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ 品牌蓝 智能紫 成功绿 深空黑 │ +│ 主要操作 AI 相关 通过状态 标题文字 │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| 色彩名称 | 色值 | 用途 | +| --- | --- | --- | +| **Primary Blue** | `#007AFF` | 主要按钮、链接、选中状态 | +| **AI Purple** | `#5856D6` | AI 相关元素、进度指示、智能提示 | +| **Success Green** | `#34C759` | 通过、合规、正确 | +| **Warning Orange** | `#FF9500` | 舆情风险、建议修改 | +| **Error Red** | `#FF3B30` | 硬性违规、必须处理 | +| **Dark** | `#1D1D1F` | 主标题、重要文字 | +| **Secondary** | `#86868B` | 次要文字、说明文字 | +| **Tertiary** | `#AEAEB2` | 占位符、禁用状态 | + +### 2.2 背景色 (Background Colors) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 背景色 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ ░░░░░░░░ │ │ ░░░░░░░░ │ │ ░░░░░░░░ │ │ ░░░░░░░░ │ │ +│ │ Primary │ │Secondary │ │ Tertiary │ │Elevated │ │ +│ │ #FFFFFF │ │ #F5F5F7 │ │ #E8E8ED │ │ #FFFFFF │ │ +│ │ ░░░░░░░░ │ │ ░░░░░░░░ │ │ ░░░░░░░░ │ │ +shadow │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ 纯白 浅灰 分隔线 悬浮卡片 │ +│ 页面底色 区块背景 边框/分隔 卡片/弹窗 │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| 背景名称 | 色值 | 用途 | +| --- | --- | --- | +| **Background Primary** | `#FFFFFF` | 页面主背景 | +| **Background Secondary** | `#F5F5F7` | 区块背景、侧边栏 | +| **Background Tertiary** | `#E8E8ED` | 分隔线、输入框边框 | +| **Background Elevated** | `#FFFFFF` + `shadow` | 悬浮卡片、弹窗、下拉菜单 | + +### 2.3 语义色 (Semantic Colors) + +用于审核状态标识，需同时搭配图标和文字，满足无障碍要求。 + +| 状态 | 色值 | 图标 | 文案示例 | +| --- | --- | --- | --- | +| **通过 (Pass)** | `#34C759` | ✓ | 审核通过 | +| **警告 (Warning)** | `#FF9500` | ⚠ | 建议修改 | +| **拒绝 (Reject)** | `#FF3B30` | ✕ | 硬性违规 | +| **进行中 (Processing)** | `#5856D6` | ◐ | AI 审核中 | +| **待处理 (Pending)** | `#86868B` | ○ | 等待审核 | + +--- + +## 3. 排版系统 (Typography) + +### 3.1 字体选择 + +| 平台 | 主字体 | 备选字体 | +| --- | --- | --- | +| **iOS/macOS** | SF Pro Display / SF Pro Text | -apple-system | +| **Android** | Roboto | Noto Sans SC | +| **Windows** | Segoe UI | Microsoft YaHei | +| **Web 通用** | Inter | -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto | + +**CSS Font Stack:** +```css +font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", + "Helvetica Neue", "Segoe UI", Roboto, "Noto Sans SC", + "PingFang SC", "Hiragino Sans GB", sans-serif; +``` + +### 3.2 字号规范 + +| 层级 | 字号 (Desktop) | 字号 (Mobile) | 行高 | 字重 | 用途 | +| --- | --- | --- | --- | --- | --- | +| **Display Large** | 34px | 28px | 1.2 | Bold (700) | 页面大标题 | +| **Display Medium** | 28px | 22px | 1.25 | Bold (700) | 区块标题 | +| **Title Large** | 22px | 20px | 1.3 | Semibold (600) | 卡片标题 | +| **Title Medium** | 17px | 17px | 1.35 | Semibold (600) | 列表项标题 | +| **Body Large** | 17px | 17px | 1.5 | Regular (400) | 正文主体 | +| **Body Medium** | 15px | 15px | 1.5 | Regular (400) | 次要正文 | +| **Caption** | 13px | 13px | 1.4 | Regular (400) | 说明文字 | +| **Footnote** | 12px | 12px | 1.4 | Regular (400) | 脚注、时间戳 | + +### 3.3 文字颜色 + +| 层级 | 颜色 | 色值 | 用途 | +| --- | --- | --- | --- | +| **Primary** | Dark | `#1D1D1F` | 主标题、重要内容 | +| **Secondary** | Gray | `#86868B` | 次要文字、说明 | +| **Tertiary** | Light Gray | `#AEAEB2` | 占位符、禁用 | +| **Link** | Blue | `#007AFF` | 链接、可点击文字 | +| **Inverse** | White | `#FFFFFF` | 深色背景上的文字 | + +--- + +## 4. 间距与布局 (Spacing & Layout) + +### 4.1 间距系统 + +采用 8px 基准网格系统： + +| 间距名称 | 数值 | 用途 | +| --- | --- | --- | +| **xs** | 4px | 图标与文字间距 | +| **sm** | 8px | 紧凑元素间距 | +| **md** | 16px | 组件内间距 | +| **lg** | 24px | 区块间距 | +| **xl** | 32px | 大区块间距 | +| **xxl** | 48px | 页面级间距 | + +### 4.2 布局断点 + +| 断点名称 | 宽度范围 | 适用场景 | +| --- | --- | --- | +| **Mobile** | < 768px | 达人端主要 | +| **Tablet** | 768px - 1024px | 达人端辅助 | +| **Desktop** | 1024px - 1440px | 代理商/品牌方端 | +| **Wide** | > 1440px | 大屏展示 | + +### 4.3 内容区最大宽度 + +| 场景 | 最大宽度 | 说明 | +| --- | --- | --- | +| **阅读内容** | 680px | 报告详情、说明文字 | +| **表单** | 560px | 输入表单 | +| **卡片网格** | 1200px | Dashboard 卡片 | +| **全宽** | 100% | 视频播放器、数据表格 | + +--- + +## 5. 圆角与阴影 (Radius & Shadow) + +### 5.1 圆角规范 + +| 元素类型 | 圆角值 | 示例 | +| --- | --- | --- | +| **Small** | 6px | 标签、徽章 | +| **Medium** | 12px | 按钮、输入框 | +| **Large** | 16px | 卡片、模态框 | +| **XLarge** | 24px | 底部弹出面板 | +| **Full** | 9999px | 圆形按钮、头像 | + +### 5.2 阴影规范 + +```css +/* 悬浮卡片 */ +.shadow-card { + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04), + 0 4px 24px rgba(0, 0, 0, 0.08); +} + +/* 弹窗/模态框 */ +.shadow-modal { + box-shadow: 0 8px 32px rgba(0, 0, 0, 0.12), + 0 2px 8px rgba(0, 0, 0, 0.06); +} + +/* 下拉菜单 */ +.shadow-dropdown { + box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08), + 0 1px 4px rgba(0, 0, 0, 0.04); +} + +/* 按钮悬停 */ +.shadow-button-hover { + box-shadow: 0 2px 12px rgba(0, 122, 255, 0.3); +} +``` + +--- + +## 6. 组件设计 (Component Library) + +### 6.1 按钮 (Buttons) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 按钮样式 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ +│ │ Primary │ │ Secondary │ │ Tertiary │ │ +│ │ ██████████ │ │ ░░░░░░░░░░ │ │ Text │ │ +│ │ #007AFF │ │ #F5F5F7 │ │ #007AFF │ │ +│ └────────────────┘ └────────────────┘ └────────────────┘ │ +│ │ +│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ +│ │ Success │ │ Warning │ │ Destructive │ │ +│ │ ██████████ │ │ ██████████ │ │ ██████████ │ │ +│ │ #34C759 │ │ #FF9500 │ │ #FF3B30 │ │ +│ └────────────────┘ └────────────────┘ └────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| 类型 | 背景色 | 文字色 | 用途 | +| --- | --- | --- | --- | +| **Primary** | `#007AFF` | `#FFFFFF` | 主要操作：上传、提交、确认 | +| **Secondary** | `#F5F5F7` | `#1D1D1F` | 次要操作：取消、返回 | +| **Tertiary** | 透明 | `#007AFF` | 文字链接：查看详情 | +| **Success** | `#34C759` | `#FFFFFF` | 成功操作：通过 | +| **Destructive** | `#FF3B30` | `#FFFFFF` | 危险操作：驳回、删除 | + +**按钮尺寸：** + +| 尺寸 | 高度 | 内边距 | 字号 | 用途 | +| --- | --- | --- | --- | --- | +| **Large** | 50px | 24px | 17px | 移动端主按钮 | +| **Medium** | 44px | 20px | 15px | 桌面端主按钮 | +| **Small** | 32px | 12px | 13px | 内联操作按钮 | + +### 6.2 输入框 (Input Fields) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 输入框状态 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Default Focus │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ 请输入内容... │ │ 输入内容 │ │ +│ │ ────────────────────│ │ ════════════════════│ │ +│ │ #E8E8ED │ │ #007AFF │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +│ Error Disabled │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ 错误内容 │ │ 禁用状态 │ │ +│ │ ════════════════════│ │ ────────────────────│ │ +│ │ #FF3B30 │ │ #F5F5F7 │ │ +│ │ ⚠️ 请输入有效内容 │ │ │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| 状态 | 边框色 | 背景色 | 说明 | +| --- | --- | --- | --- | +| **Default** | `#E8E8ED` | `#FFFFFF` | 默认状态 | +| **Focus** | `#007AFF` | `#FFFFFF` | 聚焦状态，2px 边框 | +| **Error** | `#FF3B30` | `#FFFFFF` | 错误状态，显示错误提示 | +| **Disabled** | `#E8E8ED` | `#F5F5F7` | 禁用状态 | + +### 6.3 卡片 (Cards) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 卡片样式 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ╭─────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ 📋 Brief 解析完成 │ │ +│ │ │ │ +│ │ ───────────────────────────────────────────── │ │ +│ │ │ │ +│ │ 已提取 3 个核心卖点，2 个禁忌词 │ │ +│ │ 投放平台：抖音 │ │ +│ │ │ │ +│ │ ┌──────────┐ ┌──────────┐ │ │ +│ │ │ 查看详情 │ │ 编辑 │ │ │ +│ │ └──────────┘ └──────────┘ │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────╯ │ +│ │ +│ 背景: #FFFFFF │ +│ 圆角: 16px │ +│ 阴影: shadow-card │ +│ 内边距: 24px │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.4 标签与徽章 (Tags & Badges) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 标签与徽章 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 状态标签 (Status Tags) │ +│ ╭──────────╮ ╭──────────╮ ╭──────────╮ ╭──────────╮ │ +│ │ ✓ 已通过 │ │ ⚠ 待修改 │ │ ✕ 已驳回 │ │ ◐ 审核中 │ │ +│ ╰──────────╯ ╰──────────╯ ╰──────────╯ ╰──────────╯ │ +│ #E8F5E9 #FFF3E0 #FFEBEE #EDE7F6 │ +│ #34C759 #FF9500 #FF3B30 #5856D6 │ +│ │ +│ 数量徽章 (Count Badges) │ +│ ╭────╮ ╭────╮ ╭────╮ │ +│ │ 12 │ │ 3 │ │ 99+│ │ +│ ╰────╯ ╰────╯ ╰────╯ │ +│ #FF3B30 (红点通知) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 6.5 进度指示器 (Progress Indicators) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 进度指示器 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 线性进度条 (Linear Progress) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ 45% - 正在检测竞品 Logo... │ +│ │ +│ 环形进度 (Circular Progress) │ +│ ╭───────╮ │ +│ ╱ ╭───╮ ╲ │ +│ │ │ 45%│ │ │ +│ ╲ ╰───╯ ╱ │ +│ ╰───────╯ │ +│ │ +│ 步骤进度 (Step Progress) - AI 透明思考 │ +│ ● ──────── ● ──────── ◐ ──────── ○ ──────── ○ │ +│ Brief解析 ASR转写 Logo检测 语义分析 生成报告 │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. 达人端界面设计 (Creator Portal) + +### 7.1 设计定位 + +- **核心设备：** 手机浏览器 / 微信内嵌浏览器 +- **设计风格：** 极简、友好、减少焦虑 +- **参考：** Apple Music / Apple Podcasts 移动端 + +### 7.2 底部导航栏 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ │ +│ [ 页面内容区域 ] │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 🏠 📤 🔔 👤 │ +│ 任务 上传 消息 我的 │ +│ │ +│ ━━━━━━ ──── ──── ──── │ +│ (选中态) (3) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ + +选中态：图标 + 文字变为 Primary Blue (#007AFF) +未选中：图标 + 文字为 Secondary (#86868B) +消息角标：红色圆点徽章显示未读数 +``` + +### 7.3 任务列表页 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ◀ 返回 任务中心 ⚙️ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ [ 全部 ] [ 待提交 ] [ 审核中 ] [ 已完成 ] │ +│ ━━━━━━ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ 📋 XX品牌 618 推广 │ │ +│ │ │ │ +│ │ 投放平台：抖音 │ │ +│ │ 截止时间：2026-02-15 │ │ +│ │ │ │ +│ │ ╭────────────╮ │ │ +│ │ │ ⚠ 待修改 │ │ │ +│ │ ╰────────────╯ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ 查看修改意见 │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ 📋 YY品牌 新品发布 │ │ +│ │ ... │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ 🏠 📤 🔔 👤 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 7.4 智能上传页 (透明思考 UI) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ◀ 返回 上传视频 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ╭─────────────╮ │ +│ ╱ ╲ │ +│ │ ╭─────╮ │ │ +│ │ │ ◐ │ │ AI 正在思考... │ +│ │ │ 45% │ │ │ +│ │ ╰─────╯ │ │ +│ ╲ ╱ │ +│ ╰─────────────╯ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────── │ +│ │ +│ 👁️ 正在逐帧检测竞品 Logo... │ +│ │ +│ ✅ Brief 解析完成 00:05 │ +│ ✅ ASR 语音转写完成 00:23 │ +│ ◐ Logo 检测中... 进行中 │ +│ ○ 语义分析 等待中 │ +│ ○ 生成审核报告 等待中 │ +│ │ +│ ───────────────────────────────────────────────────────── │ +│ │ +│ 💡 预计还需 2 分钟。您可以先离开， │ +│ 结果将通过微信通知您。 │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 离开并稍后查看 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ⚠️ 上传中请保持屏幕常亮，切勿锁屏或切换应用 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**设计要点：** +- 中央环形进度，显示整体进度百分比 +- 步骤列表实时更新，已完成项显示耗时 +- 当前步骤高亮，带动态指示器 +- 底部提供"离开"选项，减少用户被困感 +- 上传时显示防锁屏提示（Wake Lock API） + +### 7.5 审核结果页 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ◀ 返回 审核报告 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ 🔴 未通过 - 存在 2 处硬性违规 │ │ +│ │ │ │ +│ │ 请根据以下意见修改后重新提交 │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ▶ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ +│ │ 🔴 🔴 🟡 │ │ +│ │ 00:15 00:42 01:28 │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ 修改清单 │ +│ ───────────────────────────────────────────────────────── │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ 🔴 00:15 广告法违禁词 │ │ +│ │ │ │ +│ │ 原内容："全网第一的产品" │ │ +│ │ │ │ +│ │ 💡 建议：改为"深受喜爱"或"销量领先" │ │ +│ │ │ │ +│ │ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ 跳转 │ │ 申诉 │ │ │ +│ │ └────────────┘ └────────────┘ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ 🔴 00:42 竞品 Logo 露出 │ │ +│ │ │ │ +│ │ [截图预览] │ │ +│ │ │ │ +│ │ 检测到画面中出现竞品 Logo（置信度 92%） │ │ +│ │ │ │ +│ │ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ 跳转 │ │ 申诉 │ │ │ +│ │ └────────────┘ └────────────┘ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ 🟡 01:28 舆情风险提示 │ │ +│ │ │ │ +│ │ AI 检测到可能存在"油腻"风险（建议检查） │ │ +│ │ 此为软性提示，不影响通过 │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 重新上传 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**设计要点：** +- 顶部结果横幅用语义色背景，一目了然 +- 视频进度条上标注问题时间点（红/黄点） +- 点击时间点可跳转视频对应位置 +- 每条问题提供"跳转"和"申诉"两个操作 +- 软性提示明确标注"不影响通过" + +### 7.6 申诉弹窗 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ 发起申诉 ✕ │ │ +│ │ │ │ +│ │ ─────────────────────────────────────────────────── │ │ +│ │ │ │ +│ │ 问题类型：广告法违禁词 │ │ +│ │ 时间点：00:15 │ │ +│ │ │ │ +│ │ ─────────────────────────────────────────────────── │ │ +│ │ │ │ +│ │ 申诉理由 * │ │ +│ │ ┌─────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ │ 请详细说明您的申诉理由（至少10字） │ │ │ +│ │ │ │ │ │ +│ │ │ │ │ │ +│ │ └─────────────────────────────────────────────────┘ │ │ +│ │ 0/200 │ │ +│ │ │ │ +│ │ 上传补充证据（可选） │ │ +│ │ ┌──────────┐ │ │ +│ │ │ + 添加 │ │ │ +│ │ └──────────┘ │ │ +│ │ │ │ +│ │ ─────────────────────────────────────────────────── │ │ +│ │ │ │ +│ │ 💡 剩余申诉令牌：2 次 │ │ +│ │ 申诉成功后令牌将自动返还 │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ 提交申诉 │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 8. 代理商端界面设计 (Agency Console) + +### 8.1 设计定位 + +- **核心设备：** 桌面端 (1280px+) +- **设计风格：** 高效、专业、信息密集 +- **参考：** Apple Developer Console / Notion + +### 8.2 侧边栏导航 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ ┌──────────┐ ┌────────────────────────────────────────────────────────┐ │ +│ │ │ │ │ │ +│ │ SmartAudit│ │ 页面内容区域 │ │ +│ │ │ │ │ │ +│ ├──────────┤ │ │ │ +│ │ │ │ │ │ +│ │ 📊 工作台 │ │ │ │ +│ │ ━━━━━━━━ │ │ │ │ +│ │ │ │ │ │ +│ │ 📋 Brief │ │ │ │ +│ │ 管理 │ │ │ │ +│ │ │ │ │ │ +│ │ ✅ 审核台 │ │ │ │ +│ │ (12) │ │ │ │ +│ │ │ │ │ │ +│ │ 👥 达人 │ │ │ │ +│ │ 管理 │ │ │ │ +│ │ │ │ │ │ +│ │ 📈 数据 │ │ │ │ +│ │ 报表 │ │ │ │ +│ │ │ │ │ │ +│ ├──────────┤ │ │ │ +│ │ │ │ │ │ +│ │ ⚙️ 设置 │ │ │ │ +│ │ │ │ │ │ +│ │ 张三 │ │ │ │ +│ │ 代理商 │ │ │ │ +│ │ │ │ │ │ +│ └──────────┘ └────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────────┘ + +侧边栏宽度：240px（可折叠为 64px 图标模式） +选中项：左侧 3px Primary Blue 边框 + 浅蓝背景 +徽章：审核台显示待处理数量 +``` + +### 8.3 工作台 (Dashboard) + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 张三 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 工作台 │ 工作台 │ +│ ━━━━━━━━ │ │ +│ │ ┌─────────────────────────────────────────────────────────┐ │ +│ 📋 Brief │ │ │ │ +│ 管理 │ │ 待办事项 │ │ +│ │ │ │ │ +│ ✅ 审核台 │ │ ╭──────────────╮ ╭──────────────╮ ╭──────────────╮ │ │ +│ (12) │ │ │ │ │ │ │ │ │ │ +│ │ │ │ 12 │ │ 3 │ │ 5 │ │ │ +│ 👥 达人 │ │ │ 待人工复核 │ │ 申诉待仲裁 │ │ 超时预警 │ │ │ +│ 管理 │ │ │ │ │ │ │ │ │ │ +│ │ │ ╰──────────────╯ ╰──────────────╯ ╰──────────────╯ │ │ +│ 📈 数据 │ │ │ │ +│ 报表 │ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ ┌─────────────────────────────────────────────────────────┐ │ +│ ⚙️ 设置 │ │ │ │ +│ │ │ 进行中的项目 │ │ +│ │ │ │ │ +│ │ │ XX品牌 618 推广 │ │ +│ │ │ ████████████████████░░░░░░░░░░░░ 12/20 完成 │ │ +│ │ │ │ │ +│ │ │ YY品牌 新品发布 │ │ +│ │ │ ██████████░░░░░░░░░░░░░░░░░░░░░░ 5/15 完成 │ │ +│ │ │ │ │ +│ │ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ ┌─────────────────────────────────────────────────────────┐ │ +│ │ │ │ │ +│ │ │ 最近活动 │ │ +│ │ │ │ │ +│ │ │ 🟢 达人A 的视频已通过审核 5分钟前 │ │ +│ │ │ 🔴 达人B 的视频被驳回 12分钟前 │ │ +│ │ │ 📋 新 Brief 已上传解析完成 1小时前 │ │ +│ │ │ │ │ +│ │ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +### 8.4 Brief 配置中心 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 张三 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 工作台 │ Brief 配置中心 │ +│ │ │ +│ 📋 Brief │ ┌──────────────────────────────────────────────────────────┐ │ +│ 管理 │ │ │ │ +│ ━━━━━━━━ │ │ ╭─────────────────────────────────────────────────╮ │ │ +│ │ │ │ │ │ │ +│ ✅ 审核台 │ │ │ 📄 拖拽文件到此处上传 │ │ │ +│ │ │ │ │ │ │ +│ 👥 达人 │ │ │ 支持 PDF / Word / Excel / PPT / 图片 │ │ │ +│ 管理 │ │ │ │ │ │ +│ │ │ │ ────────── 或 ────────── │ │ │ +│ 📈 数据 │ │ │ │ │ │ +│ 报表 │ │ │ ┌───────────┐ ┌───────────────────────┐ │ │ │ +│ │ │ │ │ 选择文件 │ │ 粘贴在线文档链接 │ │ │ │ +│ │ │ │ └───────────┘ └───────────────────────┘ │ │ │ +│ ⚙️ 设置 │ │ │ │ │ │ +│ │ │ ╰─────────────────────────────────────────────────╯ │ │ +│ │ │ │ │ +│ │ │ 投放平台 │ │ +│ │ │ ╭────────╮ ╭────────╮ ╭────────╮ ╭────────╮ │ │ +│ │ │ │ 抖音 │ │ 小红书 │ │ B站 │ │ 快手 │ │ │ +│ │ │ │ ━━━ │ │ │ │ │ │ │ │ │ +│ │ │ ╰────────╯ ╰────────╯ ╰────────╯ ╰────────╯ │ │ +│ │ │ │ │ +│ │ │ 投放区域 │ │ +│ │ │ ╭────────────╮ ╭────────────╮ ╭────────────╮ │ │ +│ │ │ │ 中国大陆 │ │ 港澳台 │ │ 海外 │ │ │ +│ │ │ │ ━━━ │ │ │ │ │ │ │ +│ │ │ ╰────────────╯ ╰────────────╯ ╰────────────╯ │ │ +│ │ │ │ │ +│ │ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +### 8.5 审核决策台 (核心页面) + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 张三 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 工作台 │ 审核决策台 ⬅️ ➡️ │ +│ │ │ +│ 📋 Brief │ ┌────────────────────────┬─────────────────────────────────┐ │ +│ 管理 │ │ │ │ │ +│ │ │ ┌──────────────────┐ │ AI 检查单 │ │ +│ ✅ 审核台 │ │ │ │ │ │ │ +│ ━━━━━━━━ │ │ │ │ │ 硬性合规 │ │ +│ │ │ │ │ │ ───────────────────────────── │ │ +│ 👥 达人 │ │ │ 视频播放器 │ │ │ │ +│ 管理 │ │ │ │ │ 🔴 00:15 广告法违禁词 │ │ +│ │ │ │ │ │ "全网第一" │ │ +│ 📈 数据 │ │ │ │ │ [展开详情] │ │ +│ 报表 │ │ │ │ │ │ │ +│ │ │ └──────────────────┘ │ 🔴 00:42 竞品 Logo 露出 │ │ +│ │ │ │ 置信度 92% │ │ +│ ⚙️ 设置 │ │ ──────────────────── │ [展开详情] [查看截图] │ │ +│ │ │ 🔴 🔴 🟡 │ │ │ +│ │ │ ▼ ▼ ▼ │ Brief 完成度 │ │ +│ │ │ ░░░░░░░░░░░░░░░░░░░░ │ ───────────────────────────── │ │ +│ │ │ 00:00 02:30 │ │ │ +│ │ │ │ ✅ 卖点1：美白 │ │ +│ │ │ ┌──────────────────┐ │ ✅ 卖点2：补水 │ │ +│ │ │ │ │ │ ❌ 卖点3：24小时持妆 (未提及) │ │ +│ │ │ │ Brief 参考图 │ │ │ │ +│ │ │ │ (画中画悬浮) │ │ 舆情雷达 │ │ +│ │ │ │ │ │ ───────────────────────────── │ │ +│ │ │ └──────────────────┘ │ │ │ +│ │ │ │ 🟡 01:28 油腻风险 (仅提示) │ │ +│ │ │ │ 达人表情过于夸张 │ │ +│ │ │ │ │ │ +│ │ └────────────────────────┴─────────────────────────────────┘ │ +│ │ │ +│ │ ┌──────────────────────────────────────────────────────────┐ │ +│ │ │ │ │ +│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ │ │ 驳回 │ │ 强制通过 │ │ 记录特例 │ │ 通过 │ │ │ +│ │ │ │ #FF3B30 │ │ #FF9500 │ │ #86868B │ │ #34C759 │ │ │ +│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ +│ │ │ │ │ +│ │ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +**设计要点：** +- 左侧 60%：视频播放器 + 智能进度条（红/黄/绿点） +- 右侧 40%：AI 检查单，分为"硬性合规"、"Brief 完成度"、"舆情雷达"三区 +- 底部固定操作栏，四个决策按钮 +- Brief 参考图可悬浮在视频角落对比 + +### 8.6 版本比对视窗 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ 版本比对 ✕ │ +├────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 📊 版本差异报告 │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ V1 版本指出 3 个违规点： ✅ 已修复 2 个 │ ❌ 未修复 1 个 │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────┬────────────────────────────┐ │ +│ │ │ │ │ +│ │ V1 版本 │ V2 版本 │ │ +│ │ │ │ │ +│ │ ┌──────────────────────┐ │ ┌──────────────────────┐ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ 视频播放器 │ │ │ 视频播放器 │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ +│ │ └──────────────────────┘ │ └──────────────────────┘ │ │ +│ │ │ │ │ +│ │ ░░░░░░░░░░░░░░░░░░░░░░░░ │ ░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ +│ │ 🔴 🔴 🟡 │ 🟢 🟢 🔴 │ │ +│ │ │ │ │ +│ └────────────────────────────┴────────────────────────────┘ │ +│ │ +│ 修改点对比 │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ ╭───────────────────────────────────────────────────────────────────╮ │ +│ │ 00:15 广告法违禁词 ✅ 已修复 │ │ +│ │ V1: "全网第一" → V2: "销量领先" │ │ +│ ╰───────────────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭───────────────────────────────────────────────────────────────────╮ │ +│ │ 00:42 竞品 Logo 露出 ✅ 已修复 │ │ +│ │ V1: 可见 → V2: 已遮挡 │ │ +│ ╰───────────────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭───────────────────────────────────────────────────────────────────╮ │ +│ │ 01:28 卖点遗漏 ❌ 未修复 │ │ +│ │ 仍未提及"24小时持妆" │ │ +│ ╰───────────────────────────────────────────────────────────────────╯ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────────┐│ +│ │ 快速通过 ││ +│ └──────────────────────────────────────────────────────────────────────┘│ +│ │ +└────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 9. 品牌方端界面设计 (Brand Admin) + +### 9.1 设计定位 + +- **核心设备：** 桌面端 (1280px+) +- **设计风格：** 监管视角、数据驱动、风险预警 +- **参考：** Apple Business Manager / Analytics Dashboard + +### 9.2 数据看板 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 王总 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 数据 │ 数据看板 本月 ▼ 导出报告 ▼ │ +│ 看板 │ │ +│ ━━━━━━━━ │ ┌───────────┬───────────┬───────────┬───────────┬───────────┐│ +│ │ │ │ │ │ │ ││ +│ 🛡️ 规则 │ │ 1,234 │ 78.5% │ 96.2% │ 23 │ 4.2 小时 ││ +│ 配置 │ │ │ │ │ │ ││ +│ │ │ 审核总量 │ 初审通过率 │ 硬性召回率 │ 舆情拦截 │ 平均周期 ││ +│ 📋 审计 │ │ ↑12% │ ↑5.2% │ 目标≥95% │ ↓18% │ 目标≤5分钟││ +│ 日志 │ │ │ │ │ │ ││ +│ │ └───────────┴───────────┴───────────┴───────────┴───────────┘│ +│ 👥 代理商 │ │ +│ 管理 │ ┌─────────────────────────────┬─────────────────────────────┐│ +│ │ │ │ ││ +│ 🔔 舆情 │ │ 审核量与通过率趋势 │ 问题类型分布 ││ +│ 预警 │ │ │ ││ +│ │ │ ╱╲ ╱╲ │ ╭─────╮ ││ +│ ⚙️ 系统 │ │ ╱ ╲ ╱ ╲ ╱╲ │ ╱ 违禁词╲ ││ +│ 设置 │ │ ╱ ╲╱ ╲ ╱ ╲ │ │ 35% │ ││ +│ │ │ ╱ ╲╱ ╲ │ ╲_______╱ 竞品 25% ││ +│ │ │ ───────────────────── │ 舆情 20% 卖点 20% ││ +│ │ │ 1月 2月 3月 4月 5月 │ ││ +│ │ │ │ ││ +│ │ └─────────────────────────────┴─────────────────────────────┘│ +│ │ │ +│ │ ┌────────────────────────────────────────────────────────────┐│ +│ │ │ ││ +│ │ │ 风险预警 ││ +│ │ │ ││ +│ │ │ 🔴 紧急 代理商A 24小时内 5 条视频触发"竞品露出"，请关注 ││ +│ │ │ 🟠 关注 达人B 连续 3 次提交未通过，建议沟通 ││ +│ │ │ 🟡 舆情 本周舆情拦截数异常上升 (+45%) ││ +│ │ │ ││ +│ │ └────────────────────────────────────────────────────────────┘│ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +### 9.3 规则配置 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 王总 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 数据 │ 规则配置 │ +│ 看板 │ │ +│ │ [ 黑白名单 ] [ 竞品库 ] [ 舆情阈值 ] [ 版本管理 ] │ +│ 🛡️ 规则 │ ━━━━━━━ │ +│ 配置 │ │ +│ ━━━━━━━━ │ ┌────────────────────────────────────────────────────────────┐│ +│ │ │ ││ +│ 📋 审计 │ │ 禁用词库 + 添加词条 ││ +│ 日志 │ │ ││ +│ │ │ ┌─────────────────────────────────────────────────────┐ ││ +│ 👥 代理商 │ │ │ │ ││ +│ 管理 │ │ │ 分类筛选： [ 全部 ] [ 广告法 ] [ 平台 ] [ 私有 ] │ ││ +│ │ │ │ │ ││ +│ 🔔 舆情 │ │ │ ╭──────────────────────────────────────────────╮ │ ││ +│ 预警 │ │ │ │ 全网第一 广告法 系统内置 ✕ │ │ ││ +│ │ │ │ ╰──────────────────────────────────────────────╯ │ ││ +│ ⚙️ 系统 │ │ │ ╭──────────────────────────────────────────────╮ │ ││ +│ 设置 │ │ │ │ 最好的 广告法 系统内置 ✕ │ │ ││ +│ │ │ │ ╰──────────────────────────────────────────────╯ │ ││ +│ │ │ │ ╭──────────────────────────────────────────────╮ │ ││ +│ │ │ │ │ 独家 平台规则 抖音 ✕ │ │ ││ +│ │ │ │ ╰──────────────────────────────────────────────╯ │ ││ +│ │ │ │ ╭──────────────────────────────────────────────╮ │ ││ +│ │ │ │ │ 竞品A 品牌私有 自定义 ✕ │ │ ││ +│ │ │ │ ╰──────────────────────────────────────────────╯ │ ││ +│ │ │ │ │ ││ +│ │ │ └─────────────────────────────────────────────────────┘ ││ +│ │ │ ││ +│ │ │ 白名单 + 添加词条 ││ +│ │ │ ───────────────────────────────────────────────────── ││ +│ │ │ ││ +│ │ │ ╭──────────────────────────────────────────────────────╮ ││ +│ │ │ │ 我们的产品 允许达人使用此表述 ✕ │ ││ +│ │ │ ╰──────────────────────────────────────────────────────╯ ││ +│ │ │ ││ +│ │ └────────────────────────────────────────────────────────────┘│ +│ │ │ +│ │ ┌──────────────────────────────────────────────────────────┐ │ +│ │ │ 保存更改 │ │ +│ │ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 10. AI 服务配置界面 (AI Configuration) + +### 10.1 设计定位 + +- **所属角色：** 品牌方管理员（Brand Admin） +- **入口位置：** 品牌方端侧边栏「系统设置」→「AI 服务配置」 +- **核心功能：** 配置 AI 提供商、模型选择、连接参数 +- **权限控制：** 仅品牌管理员可见和操作 + +### 10.2 界面布局 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ SmartAudit 🔔 (3) 👤 王总 │ +├──────────┬─────────────────────────────────────────────────────────────────┤ +│ │ │ +│ 📊 数据 │ AI 服务配置 │ +│ 看板 │ │ +│ │ ┌────────────────────────────────────────────────────────────┐│ +│ 🛡️ 规则 │ │ ││ +│ 配置 │ │ AI 提供商 ││ +│ │ │ ┌──────────────────────────────────────────────────────┐ ││ +│ 📋 审计 │ │ │ OneAPI 中转服务 ▼ │ ││ +│ 日志 │ │ └──────────────────────────────────────────────────────┘ ││ +│ │ │ 💡 支持 OneAPI、Anthropic Claude、OpenAI、DeepSeek 等 ││ +│ 👥 代理商 │ │ ││ +│ 管理 │ │ ───────────────────────────────────────────────────── ││ +│ │ │ ││ +│ 🔔 舆情 │ │ 模型配置 ││ +│ 预警 │ │ ││ +│ │ │ 文字处理模型 (LLM) ││ +│ ⚙️ 系统 │ │ ┌──────────────────────────────────────────────────────┐ ││ +│ 设置 │ │ │ claude-opus-4-5-20251101 ▼ │ ││ +│ ━━━━━━━━ │ │ └──────────────────────────────────────────────────────┘ ││ +│ │ │ 用于 Brief 解析、语义分析、报告生成 ││ +│ └ 🤖 AI │ │ ││ +│ 配置 │ │ 视频分析模型 (Vision) ││ +│ ━━━━━━ │ │ ┌──────────────────────────────────────────────────────┐ ││ +│ │ │ │ doubao-seed-1.6-thinking-vision ▼ │ ││ +│ │ │ └──────────────────────────────────────────────────────┘ ││ +│ │ │ 用于 Logo 检测、画面分析、竞品识别 ││ +│ │ │ ││ +│ │ │ 音频解析模型 (ASR) ││ +│ │ │ ┌──────────────────────────────────────────────────────┐ ││ +│ │ │ │ whisper-large-v3 ▼ │ ││ +│ │ │ └──────────────────────────────────────────────────────┘ ││ +│ │ │ 用于语音转文字、口播内容提取 ││ +│ │ │ ││ +│ │ └────────────────────────────────────────────────────────────┘│ +│ │ │ +└──────────┴─────────────────────────────────────────────────────────────────┘ +``` + +### 10.3 连接配置区域 + +``` +┌────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 连接配置 │ │ +│ │ │ │ +│ │ Base URL │ │ +│ │ ┌──────────────────────────────────────────────────────────────┐ │ │ +│ │ │ https://oneapi.intelligrow.cn │ │ │ +│ │ └──────────────────────────────────────────────────────────────┘ │ │ +│ │ API 服务端点地址，需支持 OpenAI 兼容接口 │ │ +│ │ │ │ +│ │ API Key │ │ +│ │ ┌──────────────────────────────────────────────────────┐ ┌────┐ │ │ +│ │ │ sk-•••••••••••••••••••••••••••••••• │ │ 👁️ │ │ │ +│ │ └──────────────────────────────────────────────────────┘ └────┘ │ │ +│ │ API 密钥将加密存储，仅用于后端调用 │ │ +│ │ │ │ +│ │ ───────────────────────────────────────────────────────────── │ │ +│ │ │ │ +│ │ 生成参数 │ │ +│ │ │ │ +│ │ Temperature │ │ +│ │ ┌──────────────────────────────────────────────────────────────┐ │ │ +│ │ │ ░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ +│ │ │ 0 0.7 1.0 │ │ │ +│ │ └──────────────────────────────────────────────────────────────┘ │ │ +│ │ 控制输出的随机性。0 = 确定性输出，1 = 高创意性 │ │ +│ │ │ │ +│ │ Max Tokens │ │ +│ │ ┌──────────────────────────────────────────────────────────────┐ │ │ +│ │ │ 2000 │ │ │ +│ │ └──────────────────────────────────────────────────────────────┘ │ │ +│ │ 单次请求的最大输出 token 数量 │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ┌───────────────┐ ┌───────────────┐ │ │ +│ │ │ 测试连接 │ │ 保存 │ │ │ +│ │ │ #F5F5F7 │ │ #007AFF │ │ │ +│ │ └───────────────┘ └───────────────┘ │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────────────┘ +``` + +### 10.4 测试连接结果弹窗 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ │ +│ 测试连接结果 ✕ │ +│ │ +│ ─────────────────────────────────────────────────────────── │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ✅ 文字处理模型 (LLM) │ │ +│ │ claude-opus-4-5-20251101 │ │ +│ │ 响应时间: 1.2s │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ✅ 视频分析模型 (Vision) │ │ +│ │ doubao-seed-1.6-thinking-vision │ │ +│ │ 响应时间: 0.8s │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ✅ 音频解析模型 (ASR) │ │ +│ │ whisper-large-v3 │ │ +│ │ 响应时间: 0.5s │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ─────────────────────────────────────────────────────────── │ +│ │ +│ 🎉 所有模型连接正常！ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 确定 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 10.5 测试失败状态 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ │ +│ 测试连接结果 ✕ │ +│ │ +│ ─────────────────────────────────────────────────────────── │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ✅ 文字处理模型 (LLM) │ │ +│ │ claude-opus-4-5-20251101 │ │ +│ │ 响应时间: 1.2s │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ❌ 视频分析模型 (Vision) │ │ +│ │ doubao-seed-1.6-thinking-vision │ │ +│ │ │ │ +│ │ 错误: 模型不存在或无访问权限 │ │ +│ │ 请确认模型名称正确且 API Key 有访问权限 │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ╭─────────────────────────────────────────────────────────╮ │ +│ │ │ │ +│ │ ✅ 音频解析模型 (ASR) │ │ +│ │ whisper-large-v3 │ │ +│ │ 响应时间: 0.5s │ │ +│ │ │ │ +│ ╰─────────────────────────────────────────────────────────╯ │ +│ │ +│ ─────────────────────────────────────────────────────────── │ +│ │ +│ ⚠️ 部分模型连接失败，请检查配置后重试 │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 确定 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 10.6 组件规格 + +| 组件 | 规格 | 说明 | +| --- | --- | --- | +| **AI 提供商下拉** | 高度 44px，圆角 12px | 下拉选项：OneAPI / Anthropic / OpenAI / DeepSeek / 自定义 | +| **模型选择下拉** | 高度 44px，圆角 12px | 动态从 API 获取可用模型列表 | +| **Base URL 输入** | 高度 44px，圆角 12px | 默认显示 placeholder | +| **API Key 输入** | 高度 44px，圆角 12px | 密码模式，带显示/隐藏切换按钮 | +| **Temperature 滑块** | 高度 8px，滑块 24px | 范围 0-1，步进 0.1 | +| **Max Tokens 输入** | 高度 44px，圆角 12px | 数字输入，范围 100-32000 | +| **测试连接按钮** | 高度 44px，圆角 12px | Secondary 样式 (#F5F5F7) | +| **保存按钮** | 高度 44px，圆角 12px | Primary 样式 (#007AFF) | + +### 10.7 交互说明 + +| 交互 | 行为 | +| --- | --- | +| **切换 AI 提供商** | 自动填充该提供商的默认 Base URL；清空并重新获取模型列表 | +| **获取模型列表** | 输入 Base URL 和 API Key 后，调用 `/v1/models` 接口获取可用模型 | +| **显示/隐藏 API Key** | 点击眼睛图标切换密码显示/隐藏状态 | +| **拖动 Temperature 滑块** | 实时显示当前数值 | +| **点击测试连接** | 并行测试三个模型，弹窗显示结果；按钮显示加载状态 | +| **点击保存** | 表单验证通过后保存配置；成功显示 Toast 提示 | + +### 10.8 表单验证规则 + +| 字段 | 验证规则 | 错误提示 | +| --- | --- | --- | +| **AI 提供商** | 必选 | 请选择 AI 提供商 | +| **文字处理模型** | 必选 | 请选择文字处理模型 | +| **视频分析模型** | 必选 | 请选择视频分析模型 | +| **音频解析模型** | 必选 | 请选择音频解析模型 | +| **Base URL** | 必填，URL 格式 | 请输入有效的 API 地址 | +| **API Key** | 必填，以 `sk-` 开头 | 请输入有效的 API Key | +| **Temperature** | 0-1 之间 | Temperature 必须在 0-1 之间 | +| **Max Tokens** | 100-32000 之间的整数 | Max Tokens 必须在 100-32000 之间 | + +### 10.9 状态说明 + +| 状态 | 说明 | +| --- | --- | +| **未配置** | 首次进入，所有字段为空，提示"请配置 AI 服务以启用智能审核功能" | +| **已配置** | 显示已保存的配置，API Key 以掩码形式显示 | +| **加载模型列表中** | 模型下拉框显示加载指示器 | +| **测试连接中** | 测试按钮显示 Spinner，禁用保存按钮 | +| **保存中** | 保存按钮显示 Spinner | + +--- + +## 11. 动效规范 (Motion Design) + +### 10.1 动效原则 + +| 原则 | 说明 | +| --- | --- | +| **目的性** | 动效服务于功能，非装饰 | +| **自然** | 遵循物理规律，缓入缓出 | +| **快速** | 保持流畅，不阻塞操作 | +| **一致** | 相似交互使用相同动效 | + +### 10.2 缓动曲线 + +```css +/* 标准缓动 - 用于大多数过渡 */ +--ease-standard: cubic-bezier(0.4, 0.0, 0.2, 1); + +/* 减速缓动 - 用于进入动画 */ +--ease-decelerate: cubic-bezier(0.0, 0.0, 0.2, 1); + +/* 加速缓动 - 用于退出动画 */ +--ease-accelerate: cubic-bezier(0.4, 0.0, 1, 1); + +/* 弹性缓动 - 用于强调动画 */ +--ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1); +``` + +### 10.3 时长规范 + +| 动效类型 | 时长 | 用途 | +| --- | --- | --- | +| **Micro** | 100ms | 按钮状态、图标变化 | +| **Short** | 200ms | 下拉菜单、提示框 | +| **Medium** | 300ms | 模态框、卡片展开 | +| **Long** | 500ms | 页面切换、复杂动画 | + +### 10.4 特殊动效 + +| 场景 | 动效描述 | +| --- | --- | +| **AI 思考中** | 环形进度 + 柔和脉冲波纹 (使用 AI Purple) | +| **上传进度** | 线性进度条 + 数字跳动 | +| **审核通过** | 绿色对勾 ✓ 从中心放大弹出 (ease-bounce) | +| **审核驳回** | 红色叉号 ✕ 轻微震动 | +| **申诉成功** | 彩色纸屑动效 (Confetti) | + +--- + +## 12. 图标系统 (Iconography) + +### 11.1 图标风格 + +- **线条粗细：** 1.5px (与 SF Symbols 一致) +- **圆角：** 与组件圆角保持一致 +- **尺寸：** 16px / 20px / 24px / 32px +- **颜色：** 继承文字颜色或使用语义色 + +### 11.2 核心图标清单 + +| 图标 | 名称 | 用途 | +| --- | --- | --- | +| 📊 | chart-bar | 数据看板 | +| 📋 | document | Brief / 任务 | +| ✅ | checkmark-circle | 通过 / 完成 | +| ❌ | xmark-circle | 驳回 / 错误 | +| ⚠️ | exclamation-triangle | 警告 / 风险 | +| 🔍 | magnifying-glass | 搜索 / 检测中 | +| 👁️ | eye | 查看 / Logo 检测 | +| 🧠 | brain | AI / 语义分析 | +| 📤 | arrow-up-doc | 上传 | +| 📥 | arrow-down-doc | 下载 / 导出 | +| 🔔 | bell | 通知 | +| ⚙️ | gear | 设置 | +| 👤 | person | 用户 / 达人 | +| 👥 | person-2 | 团队 / 代理商 | +| 🛡️ | shield | 品牌方 / 规则 | + +--- + +## 13. 无障碍设计 (Accessibility) + +### 12.1 色彩对比度 + +| 组合 | 对比度 | 合规等级 | +| --- | --- | --- | +| Dark (#1D1D1F) on White (#FFFFFF) | 16.1:1 | AAA | +| Secondary (#86868B) on White (#FFFFFF) | 4.6:1 | AA | +| Primary (#007AFF) on White (#FFFFFF) | 4.5:1 | AA | +| White (#FFFFFF) on Primary (#007AFF) | 4.5:1 | AA | + +### 12.2 键盘导航 + +- 所有交互元素可通过 Tab 键访问 +- Enter/Space 触发主要操作 +- Escape 关闭模态框 +- 方向键在列表中导航 + +### 12.3 屏幕阅读器 + +- 所有图标提供 `aria-label` +- 状态变化通过 `aria-live` 通知 +- 表单元素关联 `