docs: 完善文档体系与一致性修复

- 新增 AI 厂商动态配置架构文档 (AIProviderConfig V2.0)
- 新增 TDD 实施计划 (featuredoc/tdd_plan.md)
- 新增文档矛盾追踪记录 (DocumentContradictions.md)
- 统一所有文档的技术指标与优先级定义
- 完善功能清单 (F-47~F-50 AI 配置功能)
- 更新任务清单支持 AI 服务配置任务

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Your Name 2026-02-03 15:49:57 +08:00
parent d7619a4511
commit 2f2f7e0f61
11 changed files with 706 additions and 197 deletions

View File

@ -27,7 +27,7 @@ SmartAudit 系统需要调用三类 AI 服务完成视频审核:
| 服务类型 | 用途 | 示例模型 |
| --- | --- | --- |
| **文字处理模型** | Brief 解析、违禁词检测、语义分析、舆情分析 | claude-opus-4-5-20251101, deepseek-chat |
| **视频分析模型** | 画面理解、Logo 检测、产品识别 | Doubao-Seed-1.6-thinking, qwen-vl-max |
| **视频分析模型** | 画面理解、场景分析、产品识别 | Doubao-Seed-1.6-thinking, qwen-vl-max |
| **音频解析模型** | 视频口播转文字 (ASR) | whisper-large-v3, paraformer-v2 |
### 1.2 设计目标
@ -236,6 +236,8 @@ MODEL_CAPABILITIES = {
"moonshot-v1-128k": [ModelCapability.TEXT],
# 视觉模型
# 注Logo 检测由系统内置 CV 模型Grounding DINO处理不受此配置影响。
# 品牌方配置的视觉模型仅用于语义场景理解(如环境分析、画面质量判定)。
"qwen-vl-max": [ModelCapability.VISION],
"qwen-vl-plus": [ModelCapability.VISION],
"Doubao-Seed-1.6-thinking": [ModelCapability.VISION],
@ -291,6 +293,10 @@ Authorization: Bearer {token}
}
```
> **模型说明:** 同一模型可能同时出现在 `text``vision` 列表中,名称保持一致,仅能力标签不同(如 `gpt-4o` 兼具文字与视觉能力)。
> **未配置说明:** 若租户未完成 AI 配置,接口返回明确错误(如 409/404前端需提示品牌方完成配置所有 AI 调用在此之前应被阻断。
### 4.2 更新配置
```
@ -342,7 +348,7 @@ Content-Type: application/json
"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)"},
{"id": "gpt-4o", "name": "GPT-4o"},
...
],
"audio": [
@ -492,7 +498,8 @@ class AIServiceRouter:
"""获取租户的 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")
# 未配置时阻断调用并提示品牌方完成配置
raise ValueError(f"AI service not configured for tenant {tenant_id}")
return config
async def chat(
@ -659,7 +666,7 @@ class AIConnectionTester:
### 6.1 API Key 加密存储
- 使用 AES-256 加密存储 API Key
- 使用 AES-256-GCM 加密存储 API Key
- 主密钥从环境变量或密钥管理服务 (Vault/KMS) 获取
- API 响应中永不返回完整 API Key仅返回脱敏版本
@ -673,12 +680,14 @@ def mask_api_key(api_key: str) -> str:
### 6.2 权限控制
| 操作 | 系统管理员 | 品牌方管理员 | 代理商 | 达人 |
| --- | :---: | :---: | :---: | :---: |
| 查看 AI 配置 | ✅ (全部) | ✅ (仅自己) | ❌ | ❌ |
| 修改 AI 配置 | ✅ | ✅ (仅自己) | ❌ | ❌ |
| 测试连接 | ✅ | ✅ (仅自己) | ❌ | ❌ |
| 查看完整 API Key | ❌ | ❌ | ❌ | ❌ |
| 操作 | 品牌方管理员 | 代理商 | 达人 |
| --- | :---: | :---: | :---: |
| 查看 AI 配置 | ✅ (本租户) | ❌ | ❌ |
| 修改 AI 配置 | ✅ (本租户) | ❌ | ❌ |
| 测试连接 | ✅ (本租户) | ❌ | ❌ |
| 查看完整 API Key | ❌ | ❌ | ❌ |
> 注系统不设独立的系统管理员角色。AI 配置由各品牌方管理员自行管理本租户的配置。
---

View File

@ -1,4 +1,4 @@
这是一个基于 `RequirementsDoc.md``FeatureSummary.md` (V1.2) 和 `User_Role_Interfaces.md` 编写的开发计划文档。
这是一个基于 `RequirementsDoc.md``FeatureSummary.md` (V1.3) 和 `User_Role_Interfaces.md` 编写的开发计划文档。
这份文档旨在指导技术团队进行架构设计、选型和排期,重点在于解决**视频处理的高并发/高延迟**、**多模态 AI 的集成**以及**移动端适配**等工程难点。
@ -11,9 +11,9 @@
| 文档类型 | **Development Plan (技术架构与实施计划)** |
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.2 |
| **版本号** | V1.5 |
| **日期** | 2026-02-03 |
| **依据** | FeatureSummary V1.2, PRD V1.0, RequirementsDoc V1.0 |
| **依据** | FeatureSummary V1.3, PRD V1.0, RequirementsDoc V1.0 |
| **侧重** | 技术选型、架构设计、MVP 范围、开发排期、验收标准 |
---
@ -26,8 +26,9 @@
| 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 厂商动态配置架构**,支持数据库配置、运行时热更新、多租户隔离 |
| V1.3 | 2026-02-03 | Claude | **确立 TDD 为项目核心开发规范**,关联 tdd_plan.md |
| V1.4 | 2026-02-03 | Claude | **新增 AI 厂商动态配置架构**,支持数据库配置、运行时热更新、多租户隔离 |
| V1.5 | 2026-02-03 | Claude | 文档一致性修复统一加密方案、采样精度、处理时间、选型决策、P0 范围、排期等 |
---
@ -54,7 +55,7 @@ graph TD
end
subgraph Async_Layer [异步处理层]
Queue[消息队列 (RabbitMQ/Redis)]
Queue[消息队列 (Redis)]
Worker_Manager[任务调度器 (Celery)]
Socket_Svc[WebSocket 推送服务]
end
@ -68,7 +69,7 @@ graph TD
subgraph Storage
DB[(PostgreSQL - 业务数据)]
VectorDB[(Milvus/pgvector - 知识库)]
VectorDB[(pgvector - 知识库)]
Cache[(Redis - 缓存/进度)]
OSS[对象存储 (视频/图片)]
end
@ -93,13 +94,13 @@ graph TD
| 模块 | 选型建议 | 理由 (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 增加防锁屏策略。 |
| **移动端** | **Responsive H5 + Wake Lock API** | 全角色(达人/代理商/品牌方)均通过 Next.js 响应式布局覆盖 iOS/Android 浏览器及微信内嵌浏览器,无需开发原生 App。⭐ V1.2 增加防锁屏策略。 |
| **后端 API** | **Python (FastAPI)** | Python 是 AI 原生语言FastAPI 具有极高的并发性能AsyncIO方便集成 AI 模型 SDK。 |
| **异步队列** | **Celery + Redis** | 视频审核是典型长耗时任务3-5分钟必须异步处理。Celery 成熟稳定。 |
| **实时通讯** | **WebSocket (Socket.io)** | 必须实现F-17用于向前端实时推送“正在检测 Logo...”等细粒度进度。 |
| **数据库** | **PostgreSQL** + **pgvector** | PG 处理关系型数据pgvector 插件直接在 PG 中处理向量搜索(竞品库/相似案例),减少架构复杂度。 |
| **文件存储** | **阿里云 OSS / AWS S3** | 视频文件大,必须上云。需配合 CDN 加速预览。 |
| **上传协议** | **Tus Protocol** (Uppy.js) | 解决大文件100MB+)上传不稳定问题,支持**断点续传**,替代 ZIP 上传。 |
| **上传协议** | **Tus Protocol** (Uppy.js) | 解决大文件(100MB上传不稳定问题支持**断点续传**,替代 ZIP 上传。 |
### 1.3 AI 模型选型 (Model Selection)
@ -122,10 +123,10 @@ graph TD
> - **多租户隔离:** 不同品牌方可配置独立的 AI 厂商和配额
> - **热更新:** 配置变更即时生效,无需重启服务
> - **故障转移:** 主厂商不可用时自动切换到备用厂商
> - **API Key 加密:** 使用 Fernet 对称加密存储敏感信息
> - **API Key 加密:** 使用 AES-256-GCM 加密存储敏感信息
>
> **支持的厂商类型:**
> - 国内厂商DeepSeek、通义千问、豆包、智谱、百川、Moonshot
> - 国内厂商DeepSeek、通义千问、豆包、智谱、Moonshot
> - 海外厂商OpenAI、Anthropic需注意合规
> - 中转服务OneAPI、OpenRouter
> - 本地部署Ollama、vLLM
@ -138,16 +139,16 @@ graph TD
> ```
> 1. 品牌方上传竞品 Logo 图片
> 2. Grounding DINO 提取 Logo 区域 → CLIP/DINOv2 生成 Embedding
> 3. 存入 Vector DB (pgvector/Milvus)
> 3. 存入 Vector DB (pgvector)
> 4. 视频帧检测时:提取候选区域 → 生成 Embedding → 向量相似度匹配
> ```
>
> **优势:** 支持 SaaS 模式下品牌**动态添加竞品 Logo**,无需重新训练模型,**即刻生效**。
> ⚠️ **国内数据合规说明:** 根据 PRD 第 10 章"数据本地化"要求,国内客户数据必须存储于中国大陆境内服务器。因此:
> - **生产环境必须使用国内 LLM**(豆包/Qwen/DeepSeek不可调用 GPT-4o/Claude 等海外 API
> - 海外 API 仅用于内部研发测试,不可处理客户真实数据
> - ASR/OCR/CV 均选用国内服务或本地部署模型
> ⚠️ **数据合规说明:** 根据 PRD 第 10 章"数据本地化"要求,国内客户数据原则上存储于中国大陆境内;若涉及跨境处理,需用户明示同意并符合监管要求。因此:
> - 生产环境允许国内/海外厂商(可通过 OneAPI/OpenRouter 等中转统一接入),但涉及境外处理需完成合规评估与客户授权
> - 若无法满足出境合规要求,则仅允许使用国内模型
> - ASR/OCR/CV 同样需满足对应合规与数据本地化要求
---
@ -157,8 +158,8 @@ graph TD
* **风险:** 传统表单上传大视频会导致超时ZIP 解压消耗大量 CPU。
* **方案:**
1. **废弃 ZIP** 前端采用 Dropzone 实现**多文件并发上传**。
2. **分片上传:** 使用 Tus 协议,将 100MB 视频切分为 5MB 的 chunk 上传,服务端合并。
1. **废弃 ZIP** 前端采用 Uppy.js 实现**多文件并发上传**。
2. **分片上传:** 使用 Tus 协议,将 100MB 视频切分为 5MB 的 chunk 上传,服务端合并。
3. **直传 OSS** 前端获取签名直传云存储,不经过应用服务器,节省带宽。
### 2.1.1 难点H5 移动端上传中断 ⭐ V1.2 新增
@ -208,7 +209,7 @@ graph TD
3. 累加总时长:`产品同框总时长 = 8s + 7s = 15s`
**验收标准:**
- 时长统计误差 ≤ 0.5
- 时长统计误差 ≤ 1
- 频次统计准确率 ≥ 95%
### 2.5 多模态时间戳对齐流程 ⭐ V1.2 补充
@ -251,17 +252,17 @@ sequenceDiagram
## 3. MVP (P0) 开发范围定义
基于 `FeatureSummary.md V1.2`MVP 阶段必须包含的功能:
基于 `FeatureSummary.md V1.3`MVP 阶段必须包含的功能:
### ✅ MVP 包含 (Must Have) - 共 18 个 P0 功能
### ✅ MVP 包含 (Must Have) - 共 21 个 P0 功能
基于 `FeatureSummary.md V1.2` 第 4.1 章定义:
基于 `FeatureSummary.md V1.3` 第 4.1 章定义:
| 模块 | 功能编号 | 功能名称 | 备注 |
| --- | --- | --- | --- |
| **Brief 管理** | F-01 | Brief 文档上传与解析 | |
| | F-02 | 在线文档链接导入 | |
| | F-03 | 平台规则库自动加载 | |
| | F-03 | 平台规则库自动加载 | 平台规则变更 ≤ 1 工作日同步 |
| | F-04 | 区域合规规则切换 | |
| | **F-05-A** | **基础黑白名单与竞品库** | ⭐ MVP 必须能防竞品 |
| **脚本预审** | F-07 | 文本脚本提交与预审 | |
@ -277,6 +278,9 @@ sequenceDiagram
| **审核台** | F-19 | 风险列表展示 | |
| | F-20 | 确认/驳回操作 | |
| **数据看板** | F-33 | 核心指标卡片 | |
| **AI 配置** | **F-47** | **AI 服务商动态配置** | ⭐ V1.4 新增 |
| | **F-48** | **AI 服务商连通性测试** | ⭐ V1.4 新增 |
| | **F-49** | **多租户 AI 配置隔离** | ⭐ V1.4 新增 |
### ❌ MVP 暂不包含 (Post-MVP)
@ -296,9 +300,10 @@ sequenceDiagram
### Phase 1: 基础设施与 Brief 引擎 (Weeks 1-2)
* **Backend:** 搭建 FastAPI 框架PG 数据库设计,接入 OSS。
* **Backend:** 实现 AI 服务商动态配置接口F-47/F-48支持品牌方配置 AI 厂商和连通性测试。
* **AI:** 调试 Brief 解析 Prompt (Layout + VLM + LLM),搭建竞品 Logo 向量库。
* **Frontend:** 完成 PC 端框架搭建Brief 上传与解析交互。
* **交付物:** 能够上传 PDF含图片并提取出 JSON 规则。
* **交付物:** 能够上传 PDF含图片并提取出 JSON 规则;品牌方可配置 AI 服务商
### Phase 2: 核心 AI 流水线 (Weeks 3-6) ⭐ *攻坚期* (V1.2: 3周→4周)
@ -312,7 +317,7 @@ sequenceDiagram
### Phase 3: 达人端 H5 与 审核台 (Weeks 7-9)
* **Frontend (H5):** 开发达人手机端上传、查看报告、申诉页面 (响应式适配 + Wake Lock 防锁屏)。
* **Frontend (H5):** 开发达人/代理商/品牌方移动端页面(达人上传与申诉、代理商审核、品牌方审批) (响应式适配 + Wake Lock 防锁屏)。
* **Frontend (PC):** 开发复杂的"审核决策台"(视频播放器与时间轴打点的联动)。
* **Backend:** 实现申诉逻辑、审核状态流转 (State Machine)。
* **交付物:** 达人可上传,代理商可审核,流程闭环。
@ -407,7 +412,7 @@ sequenceDiagram
## 8. 验收标准 (Acceptance Criteria)
引用自 `FeatureSummary.md V1.2` 第 9 章MVP 上线前必须满足:
引用自 `FeatureSummary.md V1.3` 第 9 章MVP 上线前必须满足:
| 验收项 | 标准 | 测量方式 | 责任方 |
| --- | --- | --- | --- |
@ -416,9 +421,9 @@ sequenceDiagram
| **语义理解误报率** | 广告/非广告语境区分误报率 **≤ 5%** | 样本量 ≥ 1,000 句 | AI 团队 |
| **ASR 字错率** | 普通话+方言 **≤ 10%** | 标注测试集评估 | AI 团队 |
| **OCR 准确率** | 含复杂背景 **≥ 95%** | 标注测试集评估 | AI 团队 |
| **时长统计误差** | **0.5秒** | 人工核对 | AI 团队 |
| **时长统计误差** | **1秒** | 人工核对 | AI 团队 |
| **频次统计准确率** | **≥ 95%** | 人工核对 | AI 团队 |
| **审核报告产出时间** | 100MB 视频 **≤ 5 分钟** | 系统埋点 | 后端 |
| **审核报告产出时间** | 100MB 视频 **≤ 5 分钟(含排队 ≤ 2 分钟)** | 系统埋点 | 后端 |
| **审计链路完整性** | 每条结论含规则版本、证据、时间戳 | 人工抽查 | QA |
---
@ -513,6 +518,6 @@ sequenceDiagram
| User_Role_Interfaces.md | 界面规范 |
| tasks.md | 开发任务清单 |
| **featuredoc/tdd_plan.md** | **TDD 实施计划(核心规范)** |
| **AIProviderConfig.md** | **AI 厂商动态配置架构设计V1.3 新增** |
| **AIProviderConfig.md** | **AI 厂商动态配置架构设计V2.0** |
| 数据字典 | 待编写 |
| API 接口规范 | 待编写 |

63
DocumentContradictions.md Normal file
View File

@ -0,0 +1,63 @@
# 设计文档矛盾与模糊点分析 (V1.2)
本文档用于记录并跟踪 `SmartAudit` 项目各设计文档之间的矛盾点与模糊点。以下条目均已对齐并给出统一结论。
---
## 1. 核心功能与技术实现
### 1.1 移动端交付形态 (已统一)
- **结论:** 统一为 **响应式 H5 / 小程序**,不开发原生 App。
- **对齐文档:** `DevelopmentPlan.md``User_Role_Interfaces.md`
### 1.2 Logo 检测职责边界 (已澄清)
- **结论:** 视觉模型仅用于画面语义/场景风险分析;竞品 Logo 检测由内置 CV 模型处理,不受配置影响。
- **对齐文档:** `AIProviderConfig.md``UIDesign.md``User_Role_Interfaces.md`
### 1.3 文件上传方案 (已同步)
- **结论:** 批量上传采用 **多文件拖拽并发上传 + Tus 断点续传**,弃用 ZIP。
- **对齐文档:** `PRD.md``RequirementsDoc.md``FeatureSummary.md``DevelopmentPlan.md`
---
## 2. 权限与工作流
### 2.1 强制通过与特例关系 (已统一)
- **结论:** “强制通过”弹窗内提供 **保存为特例** 勾选项(默认不勾选);勾选后生成豁免条款并等待品牌方确认生效。
- **对齐文档:** `PRD.md``UIDesign.md``User_Role_Interfaces.md`
### 2.2 强制通过禁用后的流程 (已统一)
- **结论:** 品牌方关闭授权后,代理商端按钮文案变为“申请强制通过”,填写理由并提交品牌方审批。
- **对齐文档:** `PRD.md``UIDesign.md``User_Role_Interfaces.md`
### 2.3 AI 配置可见性 (已统一)
- **结论:** 代理商/达人 **不可见** AI 配置,仅品牌方管理员可查看与修改。
- **对齐文档:** `UIDesign.md``User_Role_Interfaces.md`
---
## 3. AI 功能与 UI
### 3.1 多模态模型的 UI 呈现 (已统一)
- **结论:** 模型下拉选项显示能力标签(如 `gpt-4o [文字/视觉]`),便于识别多模态模型。
- **对齐文档:** `UIDesign.md``User_Role_Interfaces.md`
### 3.2 多租户 AI 配置范围 (已统一)
- **结论:** F-49 提升为 **P0**MVP 必须包含多租户 AI 配置隔离能力。
- **对齐文档:** `FeatureSummary.md``tasks.md``DevelopmentPlan.md``PRD.md`
---
## 4. 文档一致性
### 4.1 TDD 计划文档缺失 (已补齐)
- **结论:** 新增 `featuredoc/tdd_plan.md`,作为 `tasks.md` 中 TDD 引用的正式文档。
- **对齐文档:** `tasks.md`
### 4.2 视频采样率假设 (已同步)
- **结论:** CV 采样率默认 **2fps**,并在该采样率下验证时长统计准确性。
- **对齐文档:** `PRD.md``FeatureSummary.md`
---
**当前状态:** 无待决策项。

View File

@ -3,8 +3,8 @@
| 文档类型 | **Feature Summary (产品功能文档)** |
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.2 |
| **发布日期** | 2026-02-02 |
| **版本号** | V1.3 |
| **发布日期** | 2026-02-03 |
| **关联文档** | RequirementsDoc.md, PRD.md, User_Role_Interfaces.md |
| **侧重** | 功能清单、优先级、验收标准、界面映射、边界说明 |
@ -97,9 +97,9 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
| 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-05-A | 基础黑白名单与竞品库 | **P0** | US-10A | 品牌方 |
| F-05-B | 高级豁免规则配置 | P1 | US-10B | 品牌方 |
| F-06 | 规则版本管理与审计 | P1 | US-10B | 品牌方 |
#### F-01 Brief 文档上传与解析
@ -304,6 +304,8 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
**功能描述:** 根据 Brief 中的时序要求,自动校验视频是否满足时长和频次指标。
**技术约束:** CV 检测采样率默认 2fps在该采样率下验证时长统计准确性。
**典型场景:**
- Brief 要求"产品同框必须 > 5秒"
- Brief 要求"口播提及品牌名 ≥ 3次"
@ -315,7 +317,7 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
✅ 频次达标:品牌名提及 4次Brief 要求 ≥ 3次
```
**验收标准:** 时长统计误差 ≤ 0.5秒,频次统计准确率 ≥ 95%
**验收标准:** 时长统计误差 ≤ 1秒,频次统计准确率 ≥ 95%
**界面映射:** 代理商端 → 审核决策台 → AI 检查单 → 时序校验
@ -348,7 +350,7 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
- 👁️ 正在逐帧检测竞品 Logo...
- 🧠 正在分析口播情感色彩...
**验收标准:** 报告产出时间 ≤ 5 分钟
**验收标准:** 报告产出时间 ≤ 5 分钟(含排队 ≤ 2 分钟)
**为什么是 P0** 视频上传+审核通常需要 3-5 分钟。如果 MVP 只有一个旋转的"Loading"图标而没有具体的文字进度,用户会以为死机了而关闭页面,导致用户流失。
@ -370,7 +372,7 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
| --- | --- | --- | --- | --- |
| F-19 | 风险列表展示 | P0 | US-08 | 代理商 |
| F-20 | 确认/驳回操作 | P0 | US-08 | 代理商 |
| F-21 | 强制通过权 | P1 | US-09 | 品牌方 |
| F-21 | 强制通过权 | P1 | US-09 | 品牌方(默认授权代理商) |
| F-22 | 特例记录与白名单 | P1 | US-09 | 品牌方 |
| F-23 | 规则依据与证据查看 | P1 | US-08 | 代理商/品牌方 |
@ -401,10 +403,11 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
#### F-21 强制通过权
**功能描述:** 品牌方可手动放行过于保守的误报(如达人玩的新梗)。
**功能描述:** 品牌方可手动放行过于保守的误报(如达人玩的新梗)。**默认授权代理商独立使用强制通过功能**;品牌方可在设置中**按代理商**关闭授权,关闭后代理商需发起审批流程。
**约束条件:**
- 必须填写放行原因
- 弹窗提供“保存为特例”勾选项(勾选后生成豁免条款,需品牌方确认)
- 记录审批人与操作时间,纳入审计日志
**界面映射:** 代理商端 → 审核决策台 → 决策栏 → [强制通过]
@ -420,7 +423,7 @@ SmartAudit 是一款**基于多模态大模型的 B2B SaaS 审核工具**,定
- 如需用于模型优化,必须确保数据授权与合规评估
**界面映射:**
- 代理商端 → 审核决策台 → 决策栏 → [记录为特例]
- 代理商端 → 审核决策台 → [强制通过] 弹窗 → 勾选“保存为特例”
- 品牌方端 → 规则配置 → 特例记录
---
@ -557,7 +560,7 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| F-34 | 趋势图表 | P1 | - | 品牌方 |
| F-35 | 风险预警 | P1 | - | 品牌方 |
| F-36 | 代理商绩效对比 | P1 | - | 品牌方 |
| F-37 | 达人排行榜 | P2 | - | 代理商 |
| F-37 | 达人排行榜 | P1 | - | 代理商 |
#### F-33 核心指标卡片
@ -653,7 +656,7 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| --- | --- | --- | --- | --- |
| F-41 | 舆情风险视频监控 | P2 | US-06 | 品牌方 |
| F-42 | 舆情案例库 | P2 | - | 品牌方 |
| F-43 | 舆情阈值设置 | P1 | US-10 | 品牌方 |
| F-43 | 舆情阈值设置 | P1 | US-10B | 品牌方 |
#### F-41 舆情风险视频监控
@ -681,7 +684,21 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
---
### 3.10 AI 闭环学习 (新增)
### 3.10 代理商管理
| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 |
| --- | --- | --- | --- | --- |
| F-44 | 代理商管理 | P1 | - | 品牌方 |
#### F-44 代理商管理
**功能描述:** 管理合作代理商与授权范围(可见 Brief 范围、**按代理商**强制通过授权、申诉仲裁权限、绩效评分卡)。
**界面映射:** 品牌方端 → 代理商管理
---
### 3.11 AI 闭环学习 (新增)
| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 |
| --- | --- | --- | --- | --- |
@ -689,24 +706,25 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
---
### 3.11 系统管理 - AI 厂商配置 (V1.4 新增)
### 3.12 系统管理 - AI 厂商配置 (V1.4 新增)
| 功能编号 | 功能名称 | 优先级 | 用户故事 | 使用角色 |
| --- | --- | --- | --- | --- |
| F-47 | AI 厂商动态配置 | P0 | - | 系统管理员 |
| F-48 | AI 厂商连通性测试 | P0 | - | 系统管理员 |
| F-49 | 多租户 AI 配置隔离 | P1 | - | 系统管理员/品牌方 |
| F-50 | API Key 轮换管理 | P1 | - | 系统管理员 |
| F-47 | AI 厂商动态配置 | P0 | - | 品牌方管理员 |
| F-48 | AI 厂商连通性测试 | P0 | - | 品牌方管理员 |
| F-49 | 多租户 AI 配置隔离 | **P0** | - | 品牌方管理员/品牌方 |
| F-50 | API Key 轮换管理 | P1 | - | 品牌方管理员 |
#### F-47 AI 厂商动态配置 ⭐ P0
**功能描述:** 系统管理员可在后台配置多个 AI 厂商DeepSeek、OpenAI、通义千问、OneAPI 中转等),配置存储在数据库中,运行时动态加载,无需修改代码或重启服务。
**功能描述:** 品牌方管理员可在后台配置多个 AI 厂商DeepSeek、OpenAI、通义千问、OneAPI 中转等),配置存储在数据库中,运行时动态加载,无需修改代码或重启服务。
**核心功能:**
- 支持添加、编辑、删除 AI 厂商配置
- 配置 Base URL、API Key加密存储、默认模型
- 配置 Base URL、API KeyAES-256-GCM 加密存储)、默认模型
- 为不同使用场景Brief 解析、脚本预审、视频审核)指定不同厂商
- 配置优先级和备用厂商(故障转移)
- 未配置时阻断调用并提示品牌方完成配置
**为什么是 P0** 这是 AI 服务的基础设施,所有 AI 功能都依赖此配置。
@ -784,9 +802,12 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| F-33 | 核心指标卡片 | 数据看板 | |
| F-47 | AI 厂商动态配置 | 系统管理 | ⭐ V1.3 新增AI 基础设施 |
| F-48 | AI 厂商连通性测试 | 系统管理 | ⭐ V1.3 新增 |
| F-49 | 多租户 AI 配置隔离 | 系统管理 | ⭐ V1.3 新增 |
### 4.2 V1.1 (P1) - 首版后快速迭代
**P1 共 22 个功能(表中区间行如 F-24~27、F-34~36、F-38~40 为合并展示)**
| 功能编号 | 功能名称 | 模块 | 备注 |
| --- | --- | --- | --- |
| F-05-B | 高级豁免规则配置 | Brief 管理 | 从 F-05 拆分 |
@ -799,9 +820,10 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| F-23 | 规则依据与证据查看 | 审核台 | |
| F-24~27 | 申诉与仲裁 | 申诉 | |
| F-34~36 | 趋势图表与预警 | 数据看板 | |
| F-37 | 达人排行榜 | 数据报表 | |
| F-38~40 | 审计日志与证据导出 | 审计 | |
| F-43 | 舆情阈值设置 | 舆情 | |
| F-49 | 多租户 AI 配置隔离 | 系统管理 | ⭐ V1.3 新增 |
| F-44 | 代理商管理 | 系统管理 | |
| F-50 | API Key 轮换管理 | 系统管理 | ⭐ V1.3 新增 |
> ⚠️ **注意:** F-09 (语境理解) 和 F-17 (进度展示) 已提升至 P0
@ -810,9 +832,9 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| 功能编号 | 功能名称 | 模块 | 备注 |
| --- | --- | --- | --- |
| F-28~29 | 版本差异报告与双屏播放 | 版本比对 | |
| F-30~32 | 批量上传/审核/导出 | 批量处理 | F-30 改为多文件拖拽 |
| F-37 | 达人排行榜 | 数据报表 | |
| F-28 | 版本差异报告 | 版本比对 | |
| F-29 | 双屏同步播放 | 版本比对 | |
| F-41~42 | 舆情监控与案例库 | 舆情 | |
| F-46 | 负样本清洗与回流 | AI 闭环 | ⭐ 新增,让 AI 真正学习 |
@ -831,6 +853,7 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| 批量处理 | ❌ | ✅ | ✅ |
| 数据看板 | 个人进度 | 项目/达人 | 全局 |
| 规则配置 | ❌ | ❌ | ✅ |
| 代理商管理 | ❌ | ❌ | ✅ |
| 审计日志 | ❌ | 所管辖 | 全部 |
| 舆情预警 | ❌ | ❌ | ✅ |
@ -841,8 +864,8 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| 类别 | 要求 |
| --- | --- |
| **可用性** | 月度可用性 ≥ 99.5%,支持灰度发布与快速回滚 |
| **性能** | 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(排队 ≤ 2 分钟) |
| **安全** | 传输与存储加密;基于角色权限控制;关键操作二次确认 |
| **性能** | 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(排队 ≤ 2 分钟) |
| **安全** | 传输与存储加密AES-256-GCM;基于角色权限控制;关键操作二次确认 |
| **隐私** | 数据最小化;默认保留 30 天;符合《个保法》与 GDPR |
| **数据本地化** | 国内客户数据存储于中国大陆境内服务器 |
| **审计** | 操作日志可审计且不可篡改 |
@ -890,7 +913,7 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| **语义理解误报率** | 广告极限词与非广告语境区分误报率 **≤ 5%** | 样本量 ≥ 1,000 句 |
| **ASR 字错率** | 普通话 + 主流方言字错率 **≤ 10%** | 标注测试集评估 |
| **OCR 准确率** | 含复杂背景字幕准确率 **≥ 95%** | 标注测试集评估 |
| **审核报告产出时间** | 100MB 以内视频,报告产出时间 **≤ 5 分钟** | 系统埋点统计 |
| **审核报告产出时间** | 100MB 视频,报告产出时间 **≤ 5 分钟(含排队 ≤ 2 分钟)** | 系统埋点统计 |
| **审计链路完整性** | 每条结论包含规则版本、模型版本、证据截图/片段与时间戳 | 人工抽查验证 |
---
@ -902,7 +925,7 @@ V1 版本指出 3 个违规点:✅ 已修复 2 个 | ❌ 未修复 1 个
| RequirementsDoc.md | 业务需求文档(用户故事、成功指标) |
| PRD.md | 产品需求文档(功能需求、技术架构) |
| User_Role_Interfaces.md | 用户角色与界面规范 |
| **AIProviderConfig.md** | **AI 厂商动态配置架构设计V1.3 新增** |
| **AIProviderConfig.md** | **AI 厂商动态配置架构设计V2.0** |
| 技术设计文档 (TDD) | 待编写 |
| API 接口规范 | 待编写 |
| 数据字典 | 待编写 |

86
PRD.md
View File

@ -4,7 +4,7 @@
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.0 |
| **发布日期** | 2026-01-30 |
| **发布日期** | 2026-02-03 |
| **状态** | 草稿 (Draft) |
| **负责人** | 产品经理 |
@ -101,17 +101,21 @@
- 脚本预审 → [US-03]
- 视频自动审核(竞品、违禁词、画面风险) → [US-05]
- 审核台风险打点与确认/驳回 → [US-08]
- 语境理解降低误报 → [US-04]
- 审核进度展示与时间戳修改清单 → [US-07]
- 基础黑白名单与竞品库F-05-A → [US-10A]
- 时长与频次校验F-45 → [US-05]
- AI 服务配置与连通性测试F-47/F-48
- 多租户 AI 配置隔离F-49
**P1首版发布后快速迭代**
- 语境理解降低误报 → [US-04]
- Brand Safety 软性风险提示 → [US-06]
- 审核进度展示与时间戳修改清单 → [US-07]
- 强制通过权与特例记录 → [US-09]
- 品牌私有规则管理与版本记录 → [US-10]
- 高级豁免规则F-05-B与版本记录 → [US-10B]
- 证据链导出 → [US-12]
**P2中长期规划**
- 批量上传/导出 → [US-11]
- 批量上传/导出(多文件拖拽并发 + Tus 断点续传,弃用 ZIP → [US-11]
- 版本差异报告 → [US-13]
---
@ -125,6 +129,7 @@
- **分区执法逻辑:** 智能区分"广告段"与"剧情段",应用不同审核尺度
- **舆情风控雷达:** 针对"油腻感"、"价值观风险"、"错别字"的专项检测
- **交互式审核台:** 支持时间戳打点、风险高亮、版本比对 (Diff) 的 Web 界面
- **移动端支持:** 响应式 H5 覆盖达人/代理商/品牌方(可作为小程序 WebView 承载)
- **信用与申诉体系:** 包含申诉令牌管理和人工仲裁流程
- **规则库管理与版本控制:** 支持平台规则库更新、品牌私有规则与白名单配置
- **权限与多租户隔离:** 支持品牌/代理/达人不同角色的权限与数据隔离
@ -137,6 +142,7 @@
- 发布后数据监测:不负责视频发布后的点赞/评论/转化数据分析
- 自动下架/投诉处理:不直接触发平台处罚或下架动作
- 直播流/实时切片审核:本期仅支持离线上传视频文件
- 原生 App本期不做
---
@ -144,7 +150,7 @@
> 说明:以下以模块划分,标注优先级 (P0/P1/P2),并引用 RD 用户故事编号。
### 6.1 Brief 与规则管理 [US-01, US-02, US-10]
### 6.1 Brief 与规则管理 [US-01, US-02, US-10A, US-10B]
**P0**
- 支持 PDF/Word/Excel/PPT/图片上传与解析
@ -154,13 +160,17 @@
- 平台规则库按投放平台抖音、小红书、B站等自动加载并校验冲突
- **区域合规支持**:不同地区投放需切换对应法规与平台规则版本
**P0**
- 基础黑白名单与竞品库F-05-A品牌私有禁用词、白名单、竞品列表的基础管理
**P1**
- 品牌私有规则管理(禁用词、白名单、竞品列表)
- 高级豁免规则F-05-B品牌私有规则的高级豁免与例外配置
- 规则版本管理与变更审计(可追溯的变更记录)
**验收要点**
- 图文混排 Brief 解析准确率 > 90%
- 规则冲突提示清晰可追溯
- 平台规则变更 ≤ 1 工作日内同步
### 6.2 脚本预审 (Pre-production) [US-03, US-04]
@ -169,7 +179,7 @@
- 输出违规项、遗漏卖点、建议修改
- 帮助达人在拍摄前发现问题,避免拍完重拍的沉没成本
**P1**
**P0**
- 语境理解降低误报(区分广告语境与日常语境)
- 例如:不应将"最开心的一天"误判为广告极限词违规
@ -182,20 +192,26 @@
- 支持视频上传(≤ 100MB1080p
- ASR/OCR/CV 联合检测
- 检测竞品 Logo、不雅背景、违禁词口播
- **时长与频次校验:** 根据 Brief 的时序要求校验产品同框时长与口播提及频次
- 输出时间戳级别的风险点(精确到秒数)
**P0**
- **审核进度展示**:在等待期间显示 AI 处理进度(如"正在核对口播..."
- **时长与频次校验**F-45根据 Brief 要求校验产品同框时长、品牌提及频次等硬性指标
**P1**
- Brand Safety 软性风险提示(油腻、爹味说教、性别偏见等)
- **仅提示不强制拦截**,需人工复核确认
- 广告段/剧情段分区审核规则
- **审核进度展示**:在等待期间显示 AI 处理进度(如"正在核对口播..."
- 审核完成后提供带时间戳的修改清单
**验收要点**
- 竞品 Logo F1 ≥ 0.85(含画面角落遮挡 30% 场景)
- ASR 字错率 ≤ 10%(普通话 + 主流方言)
- OCR 准确率 ≥ 95%(含复杂背景)
- 报告产出时间 ≤ 5 分钟
- 时长统计误差 ≤ 1 秒;频次统计准确率 ≥ 95%
- 视频分析采样率默认 2fps并在该采样率下验证时长统计准确性
- 报告产出时间 ≤ 5 分钟(含排队 ≤ 2 分钟)
### 6.4 审核台与人工复核 [US-08, US-09]
@ -204,26 +220,52 @@
- 支持确认/驳回操作,无需从头看视频
**P1**
- 品牌方"强制通过权":可手动放行过于保守的误报(需记录原因与审批人)
- 支持将特例记录为规则白名单/豁免条款(需品牌方确认
- 品牌方"强制通过权":可手动放行过于保守的误报(需记录原因与审批人)**默认授权代理商独立使用,可在品牌方设置中按代理商关闭,关闭后需走审批流程**。强制通过弹窗需填写原因,并提供“保存为特例”可选项(**默认不勾选**,勾选后形成豁免条款,需品牌方确认生效)
- 特例可沉淀为规则白名单/豁免条款(含来源:强制通过勾选或手动记录
- 如需用于模型优化,必须确保数据授权与合规评估
- 可查看规则依据与证据片段
**验收要点**
- 每条结论包含规则版本、模型版本、证据截图/片段与时间戳
### 6.5 申诉与仲裁
### 6.5 代理商管理
**P1**
- 代理商列表与绑定项目展示
- 可配置可见 Brief 范围、仲裁权限
- 强制通过授权开关(**按代理商配置**,默认开启,可关闭)
- 绩效评分卡(审核量、通过率、问题率、平均周期)
**验收要点**
- 权限配置可保存并即时生效
- 绩效指标口径与数据看板一致
### 6.6 申诉与仲裁
**P1**
- 申诉令牌管理与工单流转
- 人工仲裁流程与记录
- 审计日志完整可追溯
### 6.6 版本差异与批量处理 [US-11, US-13]
### 6.7 版本差异与批量处理 [US-11, US-13]
**P2**
- **新旧版本差异报告**AI 明确告知"V1版本中指出的N个违规点有X个已修复Y个未修复"
- 批量上传与批量导出审核报告
- 批量上传与批量导出审核报告(多文件拖拽并发 + Tus 断点续传,弃用 ZIP
### 6.8 AI 服务配置与连通性测试
**P0**
- 品牌方管理员可配置 AI 提供商、Base URL、API Key、默认模型文本/视觉/音频)
- API Key 使用 AES-256-GCM 加密存储
- 提供连通性测试(并行测试三类模型)
- 多租户隔离;代理商/达人自动继承品牌方配置
- **未配置时阻断调用并提示品牌方完成配置**
**验收要点**
- 未配置时返回明确错误与引导
- 连通性测试结果明确展示成功/失败及错误原因
- 配置变更即时生效(无需重启)
---
@ -262,8 +304,8 @@
| 角色 | 可见范围 | 关键权限 |
| --- | --- | --- |
| 品牌方 | 品牌内任务与规则 | 强制通过、规则管理、报告导出、私有规则配置 |
| 代理商 | 代理商管理范围 | 任务创建、审核确认/驳回、批量处理、人工仲裁 |
| 品牌方(含品牌方管理员) | 品牌内任务与规则 | 强制通过、规则管理、报告导出、私有规则配置、AI 服务商配置与管理 |
| 代理商 | 代理商管理范围 | 任务创建、审核确认/驳回、批量处理、人工仲裁、强制通过(按代理商授权,默认开启,可关闭) |
| 达人 | 自己的任务 | 上传脚本/视频、查看报告、申诉 |
---
@ -290,7 +332,7 @@
## 10. 非功能性需求 (NFR)
- **可用性**:月度可用性 ≥ 99.5%,支持灰度发布与快速回滚
- **性能**1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(排队时间不超过 2 分钟)
- **性能**1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(含排队 ≤ 2 分钟)
- **安全**:传输与存储加密;基于角色的权限控制;关键操作二次确认
- **隐私**:数据最小化访问;默认保留原始视频/报告 30 天,可按品牌配置延长或缩短
- **合规**:符合《个人信息保护法》与 GDPR支持数据导出/删除;明确告知数据用途
@ -301,7 +343,7 @@
## 11. 假设与约束 (Assumptions & Constraints)
- **技术约束:** 视频处理极其消耗算力,需接受"非实时"反馈(深度审核需 1-3 分钟延迟)
- **技术约束:** 视频处理极其消耗算力,需接受"非实时"反馈(深度审核需 3-5 分钟延迟)
- **数据隐私:** 品牌方的 Brief 和私有数据必须严格隔离,不得用于训练通用模型
- **平台依赖:** 若抖音/小红书的审核规则发生重大变更,系统需在一个工作日内更新规则库
- **规则来源:** 具体合规规则由品牌/法务提供并确认,平台规则以官方公告为准
@ -352,14 +394,14 @@
- **ASR/OCR**:支持普通话及主流方言的语音识别,支持复杂背景字幕识别
- **计算机视觉**Logo 检测、物体识别、场景分类
- **消息队列**:异步处理视频审核任务,支持优先级调度
- **AI 厂商动态配置**支持在数据库中配置多个 AI 厂商DeepSeek/OpenAI/OneAPI 等),运行时动态加载,支持多租户隔离和故障转移(详见 AIProviderConfig.md
- **AI 厂商动态配置**品牌方管理员可在后台配置多个 AI 厂商DeepSeek/OpenAI/OneAPI 等),运行时动态加载,支持多租户隔离和故障转移(详见 AIProviderConfig.md
---
## 14. 里程碑与发布计划 (Milestones)
- **MVP (P0)**Brief 解析、规则加载、脚本预审、视频审核、审核台
- **V1.1 (P1)**Brand Safety 提示、规则版本、证据链导出、强制通过权、审核进度展示
- **MVP (P0)**Brief 解析、规则加载、脚本预审、视频审核、审核台、语境理解降低误报、审核进度展示、基础黑白名单与竞品库、时长与频次校验、AI 服务商配置
- **V1.1 (P1)**Brand Safety 提示、规则版本、证据链导出、强制通过权、高级豁免规则
- **V2 (P2)**:批量处理、版本差异报告
---

View File

@ -4,7 +4,7 @@
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.0 |
| **发布日期** | 2026-01-30 |
| **发布日期** | 2026-02-03 |
| **状态** | **修订 (Revised)** |
| **侧重** | 商业背景、用户价值、用户故事、成功指标 |
@ -77,13 +77,13 @@
### 4.2 场景二:脚本预审 (Pre-production)
* **[US-03] [P0]** 作为 **达人**,我希望在拍摄前先提交文字脚本进行预审,让系统帮我检查是否遗漏了卖点或触犯了广告法,避免拍完重拍的巨大沉没成本。
* **[US-04] [P1]** 作为 **达人**,我希望审核系统能"读懂上下文",不要因为我在讲故事时说了"最开心的一天"就报"广告极限词违规",减少对创作的干扰。
* **[US-04] [P0]** 作为 **达人**,我希望审核系统能"读懂上下文",不要因为我在讲故事时说了"最开心的一天"就报"广告极限词违规",减少对创作的干扰。
### 4.3 场景三:视频智能审核 (Post-production)
* **[US-05] [P0]** 作为 **代理商**,我希望系统能自动检测视频画面中是否出现了"竞品Logo"或"不雅背景",并精确到秒数标出来,因为人工肉眼看视频很容易走神漏掉。
* **[US-06] [P1]** 作为 **品牌方**,我希望系统具备"舆情敏感度",能提示达人视频中是否存在"油腻"、"爹味说教"或"性别偏见"的内容帮助我规避潜在的公关风险Brand Safety
* **[US-07] [P1]** 作为 **达人**,我希望在视频上传后的等待期间能看到 AI 的处理进度(如"正在核对口播..."),并在审核完成后收到一份带时间戳的修改清单。
* **[US-07] [P0]** 作为 **达人**,我希望在视频上传后的等待期间能看到 AI 的处理进度(如"正在核对口播..."),并在审核完成后收到一份带时间戳的修改清单。
### 4.4 场景四:人工复核与决策
@ -92,8 +92,9 @@
### 4.5 场景五:规则运营与审计
* **[US-10] [P1]** 作为 **品牌方合规/法务**,我希望能配置"品牌私有规则"(如禁用词、竞品列表、白名单),并且对规则版本做可追溯的变更记录。
* **[US-11] [P2]** 作为 **代理商**,我希望支持批量上传与批量导出审核报告,便于一次处理多条达人任务。
* **[US-10A] [P0]** 作为 **品牌方合规/法务**,我希望能配置"品牌私有规则"的基础部分(禁用词、竞品列表、白名单),确保最低合规要求可落地。
* **[US-10B] [P1]** 作为 **品牌方合规/法务**,我希望能配置高级豁免规则与舆情阈值,并对规则版本做可追溯的变更记录。
* **[US-11] [P2]** 作为 **代理商**,我希望支持**多文件拖拽并发上传 + Tus 断点续传**的批量上传,并可批量导出审核报告,便于一次处理多条达人任务(弃用 ZIP 方案)。
* **[US-12] [P1]** 作为 **品牌方**,我希望在争议发生时能导出完整的审核证据链(时间戳、截图、规则依据、审核人)。
### 4.6 场景六:版本迭代与比对
@ -147,7 +148,7 @@
## 7. 假设与约束 (Assumptions & Constraints)
* **技术约束:** 视频处理极其消耗算力,需接受“非实时”反馈(深度审核需 1-3 分钟延迟)。
* **技术约束:** 视频处理极其消耗算力,需接受“非实时”反馈(深度审核需 3-5 分钟延迟)。
* **数据隐私:** 品牌方的 Brief 和私有数据必须严格隔离,不得用于训练通用模型。
* **平台依赖:** 若抖音/小红书的审核规则发生重大变更,系统需在一个工作日内更新规则库。
* **规则来源:** 具体合规规则由品牌/法务提供并确认,平台规则以官方公告为准。
@ -194,8 +195,8 @@
## 8. 非功能性需求 (Non-Functional Requirements)
* **可用性:** 月度可用性 ≥ 99.5%,支持灰度发布与快速回滚。
* **性能:** 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(排队时间不超过 2 分钟)。
* **安全:** 传输与存储加密;基于角色的权限控制;关键操作二次确认。
* **性能:** 1080p、≤ 100MB 视频生成报告 ≤ 5 分钟(含排队 ≤ 2 分钟)。
* **安全:** 传输与存储采用 AES-256-GCM 加密;基于角色的权限控制;关键操作二次确认。
* **数据保留:** 默认保留原始视频/报告 30 天,可按品牌配置延长或缩短。
* **合规与隐私:** 支持数据脱敏与最小化访问;操作日志可审计且不可篡改。
* **个人信息保护:** 符合《个人信息保护法》及 GDPR 要求;用户数据可导出、可删除;明确告知数据用途。
@ -209,8 +210,9 @@
* **多模态检测:** 在标注测试集中,系统能识别画面角落里遮挡 30% 的竞品 LogoF1 ≥ 0.85。
* **语义理解:** 对广告极限词与非广告语境的区分误报率 ≤ 5%(样本量 ≥ 1,000 句)。
* **ASR/OCR:** 普通话 ASR 字错率 ≤ 10%,字幕 OCR 字准确率 ≥ 95%(含复杂背景)。
* **性能:** 100MB 以内的视频上传后AI 预审报告产出时间不超过 5 分钟。
* **性能:** 100MB 视频上传后AI 预审报告产出时间不超过 5 分钟(含排队 ≤ 2 分钟)
* **审计链路:** 每条结论包含规则版本、模型版本、证据截图/片段与时间戳。
* **F-45 时长与频次统计:** 时长统计误差 ≤ 1秒频次统计准确率 ≥ 95%。
---

View File

@ -3,8 +3,8 @@
| 文档类型 | **UI Design System (设计系统规范)** |
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.0 |
| **发布日期** | 2026-02-02 |
| **版本号** | V1.1 |
| **发布日期** | 2026-02-03 |
| **设计风格** | Apple Human Interface Guidelines 浅色系 |
| **关联文档** | PRD.md, FeatureSummary.md, User_Role_Interfaces.md, DevelopmentPlan.md |
@ -806,10 +806,10 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
│ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │
│ │ │ │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ │ 驳回 │ │ 强制通过 │ │ 记录特例 │ │ 通过 │ │ │
│ │ │ │ #FF3B30 │ │ #FF9500 │ │ #86868B │ │ #34C759 │ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ │ 驳回 │ │ 强制通过 │ │ 通过 │ │ │
│ │ │ │ #FF3B30 │ │ #FF9500 │ │ #34C759 │ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │
│ │ │
@ -819,7 +819,9 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
**设计要点:**
- 左侧 60%:视频播放器 + 智能进度条(红/黄/绿点)
- 右侧 40%AI 检查单,分为"硬性合规"、"Brief 完成度"、"舆情雷达"三区
- 底部固定操作栏,四个决策按钮
- 底部固定操作栏,三个决策按钮
- 品牌方**按代理商**关闭授权时,“强制通过”按钮改为“申请强制通过”,点击弹出原因并提交审批
- 强制通过弹窗包含“保存为特例”勾选项(默认不勾选),勾选后生成豁免条款并等待品牌方确认
- Brief 参考图可悬浮在视频角落对比
### 8.6 版本比对视窗
@ -990,7 +992,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
- **所属角色:** 品牌方管理员Brand Admin
- **入口位置:** 品牌方端侧边栏「系统设置」→「AI 服务配置」
- **核心功能:** 配置 AI 提供商、模型选择、连接参数
- **权限控制:** 仅品牌管理员可见和操作
- **权限控制:** 仅品牌管理员可见和操作;代理商/达人不可见
### 10.2 界面布局
@ -1023,7 +1025,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
│ ━━━━━━ │ │ ┌──────────────────────────────────────────────────────┐ ││
│ │ │ │ doubao-seed-1.6-thinking-vision ▼ │ ││
│ │ │ └──────────────────────────────────────────────────────┘ ││
│ │ │ 用于 Logo 检测、画面分析、竞品识别 ││
│ │ │ 用于画面语义分析、场景/风险识别Logo 检测由系统内置 CV 完成) ││
│ │ │ ││
│ │ │ 音频解析模型 (ASR) ││
│ │ │ ┌──────────────────────────────────────────────────────┐ ││
@ -1184,6 +1186,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
| --- | --- | --- |
| **AI 提供商下拉** | 高度 44px圆角 12px | 下拉选项OneAPI / Anthropic / OpenAI / DeepSeek / 自定义 |
| **模型选择下拉** | 高度 44px圆角 12px | 动态从 API 获取可用模型列表 |
| **模型能力标签** | 标签 12px | 下拉项标注能力(如 `gpt-4o [文字/视觉]` |
| **Base URL 输入** | 高度 44px圆角 12px | 默认显示 placeholder |
| **API Key 输入** | 高度 44px圆角 12px | 密码模式,带显示/隐藏切换按钮 |
| **Temperature 滑块** | 高度 8px滑块 24px | 范围 0-1步进 0.1 |
@ -1196,7 +1199,8 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
| 交互 | 行为 |
| --- | --- |
| **切换 AI 提供商** | 自动填充该提供商的默认 Base URL清空并重新获取模型列表 |
| **获取模型列表** | 输入 Base URL 和 API Key 后,调用 `/v1/models` 接口获取可用模型 |
| **获取模型列表** | 输入 Base URL 和 API Key 后,调用 `/api/v1/ai-config/models` 获取可用模型(后端代理厂商 `/v1/models` |
| **模型能力提示** | 模型下拉项展示能力标签,帮助识别多模态模型 |
| **显示/隐藏 API Key** | 点击眼睛图标切换密码显示/隐藏状态 |
| **拖动 Temperature 滑块** | 实时显示当前数值 |
| **点击测试连接** | 并行测试三个模型,弹窗显示结果;按钮显示加载状态 |
@ -1229,7 +1233,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
## 11. 动效规范 (Motion Design)
### 10.1 动效原则
### 11.1 动效原则
| 原则 | 说明 |
| --- | --- |
@ -1238,7 +1242,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
| **快速** | 保持流畅,不阻塞操作 |
| **一致** | 相似交互使用相同动效 |
### 10.2 缓动曲线
### 11.2 缓动曲线
```css
/* 标准缓动 - 用于大多数过渡 */
@ -1254,7 +1258,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
--ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
```
### 10.3 时长规范
### 11.3 时长规范
| 动效类型 | 时长 | 用途 |
| --- | --- | --- |
@ -1263,7 +1267,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
| **Medium** | 300ms | 模态框、卡片展开 |
| **Long** | 500ms | 页面切换、复杂动画 |
### 10.4 特殊动效
### 11.4 特殊动效
| 场景 | 动效描述 |
| --- | --- |
@ -1277,14 +1281,14 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
## 12. 图标系统 (Iconography)
### 11.1 图标风格
### 12.1 图标风格
- **线条粗细:** 1.5px (与 SF Symbols 一致)
- **圆角:** 与组件圆角保持一致
- **尺寸:** 16px / 20px / 24px / 32px
- **颜色:** 继承文字颜色或使用语义色
### 11.2 核心图标清单
### 12.2 核心图标清单
| 图标 | 名称 | 用途 |
| --- | --- | --- |
@ -1308,7 +1312,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
## 13. 无障碍设计 (Accessibility)
### 12.1 色彩对比度
### 13.1 色彩对比度
| 组合 | 对比度 | 合规等级 |
| --- | --- | --- |
@ -1317,21 +1321,21 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
| Primary (#007AFF) on White (#FFFFFF) | 4.5:1 | AA |
| White (#FFFFFF) on Primary (#007AFF) | 4.5:1 | AA |
### 12.2 键盘导航
### 13.2 键盘导航
- 所有交互元素可通过 Tab 键访问
- Enter/Space 触发主要操作
- Escape 关闭模态框
- 方向键在列表中导航
### 12.3 屏幕阅读器
### 13.3 屏幕阅读器
- 所有图标提供 `aria-label`
- 状态变化通过 `aria-live` 通知
- 表单元素关联 `<label>`
- 错误提示通过 `aria-describedby` 关联
### 12.4 动效偏好
### 13.4 动效偏好
```css
@media (prefers-reduced-motion: reduce) {
@ -1346,7 +1350,7 @@ font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
## 14. 响应式策略 (Responsive Strategy)
### 13.1 达人端 (Mobile-First)
### 14.1 达人端 (Mobile-First)
```
Mobile (< 768px) Tablet (768px - 1024px)
@ -1359,7 +1363,7 @@ Mobile (< 768px) Tablet (768px - 1024px)
└─────────────────┘ └─────────────────────────┘
```
### 13.2 代理商/品牌方端 (Desktop-First)
### 14.2 代理商/品牌方端 (Desktop-First)
```
Desktop (> 1024px) Tablet (768px - 1024px)
@ -1376,7 +1380,7 @@ Desktop (> 1024px) Tablet (768px - 1024px)
## 15. 设计资源 (Design Resources)
### 14.1 设计工具
### 15.1 设计工具
| 工具 | 用途 |
| --- | --- |
@ -1384,7 +1388,7 @@ Desktop (> 1024px) Tablet (768px - 1024px)
| **Lottie** | 复杂动效 |
| **Phosphor Icons** | 图标库 (与 SF Symbols 风格一致) |
### 14.2 交付物清单
### 15.2 交付物清单
| 交付物 | 格式 | 说明 |
| --- | --- | --- |
@ -1394,7 +1398,7 @@ Desktop (> 1024px) Tablet (768px - 1024px)
| 动效文件 | Lottie JSON | AI 动画 |
| 设计标注 | Figma Dev Mode | 开发交接 |
### 14.3 参考资源
### 15.3 参考资源
- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
- [SF Symbols](https://developer.apple.com/sf-symbols/)
@ -1411,15 +1415,18 @@ Desktop (> 1024px) Tablet (768px - 1024px)
| | 审核结果页 | P0 | 待设计 |
| | 申诉弹窗 | P1 | 待设计 |
| | 消息中心 | P1 | 待设计 |
| | 历史记录 | P2 | 待设计 |
| **代理商** | 工作台 | P0 | 待设计 |
| | Brief 配置 | P0 | 待设计 |
| | 审核决策台 | P0 | 待设计 |
| | 版本比对 | P1 | 待设计 |
| | 版本比对 | P2 | 待设计 |
| | 达人管理 | P1 | 待设计 |
| | 数据报表 | P1 | 待设计 |
| **品牌方** | 数据看板 | P0 | 待设计 |
| | 规则配置 | P0 | 待设计 |
| | AI 服务配置 | P0 | 已设计 |
| | 审计日志 | P1 | 待设计 |
| | 代理商管理 | P1 | 待设计 |
| | 舆情预警 | P2 | 待设计 |
---

View File

@ -3,9 +3,9 @@
| 文档类型 | **UI/UX Spec (Interface Definitions)** |
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.0 |
| **发布日期** | 2026-01-30 |
| **关联文档** | RequirementsDoc.md (RD), PRD.md |
| **版本号** | V1.3 |
| **发布日期** | 2026-02-03 |
| **关联文档** | RequirementsDoc.md, PRD.md, FeatureSummary.md, DevelopmentPlan.md, AIProviderConfig.md, UIDesign.md, tasks.md |
| **侧重** | 角色权限、核心页面布局、交互逻辑 |
---
@ -38,7 +38,7 @@
| **申诉功能** | ✅ 发起申诉 (消耗令牌) | ✅ 仲裁申诉 | ❌ 无需申诉 |
| **证据链导出** | ❌ 无权 | ✅ 导出所管辖任务 | ✅ 导出全部 [US-12] |
| **数据看板** | 仅看个人任务进度 | 整体进度 / 达人排名 | 全局合规率 / 舆情风控 |
| **系统配置** | ❌ 无权 | ❌ 无权 | ✅ 规则库/阈值/白名单/区域合规 [US-10] |
| **系统配置** | ❌ 无权 | ❌ 无权 | ✅ 规则库/阈值/白名单/区域合规 [US-10A/US-10B] |
| **AI 服务配置** | ❌ 无权 | ❌ 无权(继承品牌方配置) | ✅ 配置 AI 提供商/模型/参数 |
| **用户管理** | ❌ 无权 | ✅ 管理所属达人 | ✅ 管理代理商与达人 |
@ -128,7 +128,7 @@
> 👁️ *正在逐帧检测竞品 Logo...*
> 🧠 *正在分析口播情感色彩...*
> ✅ *口播检测完成,正在核对卖点覆盖...*
* **离开提示:** 深度审核约需 1-3 分钟,可选择离开并通过微信通知结果
* **离开提示:** 深度审核约需 3-5 分钟,可选择离开并通过微信通知结果
@ -175,7 +175,7 @@
* 💬 **申诉结果:** "您的申诉已通过AI 已学习您的反馈"
* **通知渠道:**
* App 内消息中心(必选)
* H5 内消息中心(必选)
* 微信服务号推送(可选)
* 短信提醒(仅紧急/超时)
@ -250,12 +250,10 @@
* **底部:决策栏 (Action Bar)**
* `[ 驳回 ]`:点击后,自动将勾选的问题打包发送给达人
* `[ 强制通过 ]` [US-09]忽略 AI 的黄色警告,强制放行
* `[ 强制通过 ]` [US-09]强制通过(默认可用;品牌方关闭授权时按钮改为“申请强制通过”,提交后进入审批)
* **必须填写放行原因**(如"达人玩的新梗,品牌方认可"
* 弹窗提供“**保存为特例**”可选项(**默认不勾选**,勾选后形成豁免条款,需品牌方确认后生效)
* **记录审批人**与操作时间,纳入审计日志
* `[ 记录为特例 ]`:将当前判断记录为规则白名单/豁免条款
* 需品牌方确认后生效
* 如需用于模型优化,必须确保数据授权与合规评估
* `[ 通过 ]`:流程结束
@ -316,7 +314,7 @@
### 3.7 批量操作中心 (Batch Operations) [US-11]
* **批量上传:** 支持 ZIP 压缩包批量上传多个视频
* **批量上传:** 支持 Uppy.js 多文件拖拽并发上传Tus 协议断点续传)
* **批量审核:** 对无问题项批量通过(需二次确认)
* **批量导出:** 一键导出选中任务的审核报告
* 支持 Excel/PDF 格式
@ -325,7 +323,7 @@
### 3.8 移动端界面 (Mobile Portal) 📱
**设计目标:** 外出场景下的紧急审核处理、进度监控、即时通知响应。
**核心设备:** 手机浏览器 / 小程序 / App
**核心设备:** 手机浏览器 / 小程序。
**定位:** 桌面端的轻量补充,复杂操作引导至桌面端完成。
#### 3.8.1 移动端工作台 (Mobile Dashboard)
@ -388,6 +386,7 @@
* 点击问题条目自动跳转到视频对应时间点
* 横屏模式下视频全屏播放,问题列表收起为浮层
* "强制通过"需输入原因,记录审批人
* 若品牌方关闭授权,按钮改为“申请强制通过”,提交后进入审批流
* 复杂编辑(如修改 Brief提示"请在电脑端操作"
#### 3.8.3 移动端任务列表 (Task List)
@ -464,7 +463,7 @@
* 🟠 **关注:** "达人B连续3次提交未通过建议沟通"
* 🟡 **舆情:** "本周舆情风险拦截数异常上升,建议检查阈值设置"
### 4.2 全局规则配置 (Rule Engine) [US-10]
### 4.2 全局规则配置 (Rule Engine) [US-10A/US-10B]
* **黑白名单管理:**
* **禁用词库:** 支持分类管理(广告法 / 平台规则 / 品牌私有)
@ -497,7 +496,7 @@
* **权限配置:**
* 可见的 Brief 范围
* 是否允许"强制通过"
* 授权代理商独立使用强制通过:**按代理商配置**,默认开启,可关闭;关闭后代理商需提交审批
* 申诉仲裁权限
* **绩效评估:**
@ -541,7 +540,7 @@
### 4.6 AI 服务配置 (AI Configuration) 🤖
**入口位置:** 系统设置 → AI 服务配置
**权限控制:** 仅品牌管理员可配置,代理商和达人自动继承品牌方配置
**权限控制:** 仅品牌管理员可配置,代理商和达人自动继承品牌方配置
#### 4.6.1 配置界面
@ -570,7 +569,7 @@
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ doubao-seed-1.6-thinking-vision ▼ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ 用于 Logo 检测、画面分析、竞品识别
│ 用于画面语义分析、场景/风险识别Logo 检测由系统内置 CV 完成)
│ │
│ 音频解析模型 (ASR) │
│ ┌───────────────────────────────────────────────────────────┐ │
@ -613,10 +612,12 @@
| 功能 | 说明 |
| --- | --- |
| **AI 提供商选择** | 下拉选择OneAPI / Anthropic / OpenAI / DeepSeek / 自定义 |
| **模型动态获取** | 输入 Base URL 和 API Key 后,调用 `/v1/models` 接口获取可用模型列表 |
| **模型动态获取** | 输入 Base URL 和 API Key 后,调用 `/api/v1/ai-config/models` 获取可用模型列表(后端代理厂商 `/v1/models` |
| **三类模型配置** | 分别配置文字处理LLM、视频分析Vision、音频解析ASR模型 |
| **能力标签** | 模型下拉选项标注能力标签(如 `gpt-4o [文字/视觉]`),多模态模型会显示多标签 |
| **测试连接** | 并行测试三个模型的连通性,弹窗显示每个模型的测试结果 |
| **配置继承** | 品牌方配置后,所属代理商和达人自动使用此配置,无需单独设置 |
| **配置继承** | 品牌方配置后,所属代理商和达人自动使用此配置,代理商/达人不可见 |
| **未配置拦截** | 未配置时阻断 AI 调用并提示品牌方完成配置 |
#### 4.6.3 配置继承关系
@ -633,7 +634,7 @@
│ ┌────────┴────────┐ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 👥 代理商A │ │ 👥 代理商B │ ← 自动继承,只读查看
│ │ 👥 代理商A │ │ 👥 代理商B │ ← 自动继承,不可见
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ ┌─────┴─────┐ ┌─────┴─────┐ │
@ -649,13 +650,13 @@
* **API Key 加密存储:** 使用 AES-256-GCM 加密,密钥与数据分离存储
* **传输安全:** 所有 API 请求强制 HTTPS
* **权限隔离:** 仅品牌管理员可查看/修改 AI 配置
* **权限隔离:** 仅品牌管理员可查看/修改 AI 配置,代理商/达人不可见
* **审计日志:** 配置变更记录操作人、时间、变更内容
### 4.7 移动端界面 (Mobile Portal) 📱
**设计目标:** 随时掌握关键指标、即时响应舆情预警、紧急审批处理。
**核心设备:** 手机浏览器 / 小程序 / App
**核心设备:** 手机浏览器 / 小程序。
**定位:** 数据查看与紧急响应,规则配置等复杂操作引导至桌面端完成。
#### 4.7.1 移动端数据看板 (Mobile Dashboard)
@ -720,7 +721,7 @@
#### 4.7.3 移动端审批中心 (Approval Center)
**场景:** 代理商申请"强制通过",品牌方需审批。
**场景:** 当品牌方关闭授权时,代理商申请"强制通过",品牌方需审批。
```
┌─────────────────────────────────────────────┐
@ -791,7 +792,7 @@
| --- | --- | --- |
| **上传中** | 进度条 + 剩余时间预估 | "正在上传视频 (35%)... 请勿关闭页面" |
| **排队中** | 队列位置提示 | "前面还有 3 个任务AI 马上就到..." |
| **处理中 (长时)** | 允许离开提示 | "深度审核约需 3 分钟。您可以先去喝杯咖啡,结果将通过微信通知您。" |
| **处理中 (长时)** | 允许离开提示 | "深度审核约需 3-5 分钟。您可以先去喝杯咖啡,结果将通过微信通知您。" |
| **解析失败** | 错误引导 + 手动兜底 | "无法读取此 PDF 内容。请检查文件是否加密,或[切换到文本输入模式]。" |
| **申诉成功** | 激励动效 (Confetti) | "申诉生效令牌已返还。AI 正在学习您的反馈。" |
@ -907,9 +908,9 @@
| **代理商** | 工作台 | P0 | MVP |
| | Brief 配置 | P0 | MVP |
| | 审核决策台 | P0 | MVP |
| | 版本比对 | P1 | |
| | 版本比对 | P2 | |
| | 达人管理 | P1 | |
| | 数据报表 | P2 | |
| | 数据报表 | P1 | |
| **品牌方** | 数据看板 | P0 | MVP |
| | 规则配置 | P0 | MVP |
| | AI 服务配置 | P0 | MVP - 品牌方专属 |

140
ai-config-demo.html Normal file
View File

@ -0,0 +1,140 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>SmartAudit · AI 服务配置(说明版)</title>
<style>
:root {
--bg: #0b0c0f;
--panel: #141621;
--panel-2: #1b1e2b;
--text: #eef1f6;
--muted: #9aa3b2;
--accent: #4ea1ff;
--ok: #34c759;
--warn: #ff9f0a;
--danger: #ff453a;
--chip: #23283a;
--border: #2a2f43;
--glow: rgba(78,161,255,0.25);
}
* { box-sizing: border-box; }
body {
margin: 0; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Arial, sans-serif;
background: radial-gradient(1200px 600px at 10% -10%, #1a2140 0%, transparent 60%),
radial-gradient(900px 500px at 110% 10%, #1b2a32 0%, transparent 55%),
var(--bg);
color: var(--text);
}
.wrap { max-width: 1100px; margin: 32px auto; padding: 0 20px 48px; }
.header {
display: flex; justify-content: space-between; align-items: center; margin-bottom: 24px;
}
.title { font-size: 24px; font-weight: 700; letter-spacing: 0.2px; }
.badge {
padding: 6px 10px; border-radius: 999px; background: #1f2b3d; color: #b7d4ff; font-size: 12px;
border: 1px solid #2d3d56;
}
.grid { display: grid; grid-template-columns: 1.2fr 1fr; gap: 16px; }
.card {
background: linear-gradient(180deg, var(--panel), var(--panel-2));
border: 1px solid var(--border);
border-radius: 14px; padding: 16px 18px; box-shadow: 0 10px 30px rgba(0,0,0,0.25);
}
.card h3 { margin: 0 0 10px; font-size: 15px; color: #d7deea; }
.row { display: flex; align-items: center; gap: 8px; margin: 8px 0; }
.label { color: var(--muted); font-size: 12px; min-width: 120px; }
.value { font-size: 14px; }
.chip { background: var(--chip); border: 1px solid var(--border); padding: 4px 8px; border-radius: 10px; font-size: 12px; }
.pill-ok { color: var(--ok); border-color: rgba(52,199,89,0.3); }
.pill-warn { color: var(--warn); border-color: rgba(255,159,10,0.3); }
.pill-danger { color: var(--danger); border-color: rgba(255,69,58,0.3); }
.divider { height: 1px; background: var(--border); margin: 12px 0; }
.cta {
background: var(--accent); color: #08111d; font-weight: 600; border: 0; border-radius: 10px;
padding: 10px 14px; box-shadow: 0 0 0 6px var(--glow);
}
.muted { color: var(--muted); font-size: 12px; }
.mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; }
.list { margin: 0; padding-left: 18px; color: var(--muted); font-size: 13px; }
.tag { display: inline-block; font-size: 11px; padding: 3px 8px; border-radius: 8px; background: #1c2436; border: 1px solid #2a3350; color: #cdd6e5; }
</style>
</head>
<body>
<div class="wrap">
<div class="header">
<div class="title">AI 服务配置 · 品牌方管理员</div>
<div class="badge">权限:仅品牌管理员可见(代理商/达人不可见)</div>
</div>
<div class="grid">
<div class="card">
<h3>1) 选择服务商(支持中转)</h3>
<div class="row">
<div class="label">AI 提供商</div>
<div class="value chip">OneAPI / OpenRouter</div>
<div class="value chip">OpenAI / Anthropic / DeepSeek / 豆包 / Qwen</div>
</div>
<div class="row">
<div class="label">Base URL</div>
<div class="value mono">https://oneapi.intelligrow.cn</div>
</div>
<div class="row">
<div class="label">API Key</div>
<div class="value mono">sk-****...****</div>
</div>
<div class="muted">说明:生产环境允许海外厂商,但需满足数据合规与客户授权。</div>
</div>
<div class="card">
<h3>2) 选择模型(文本 / 视觉 / 音频)</h3>
<div class="row">
<div class="label">文本模型</div>
<div class="value chip">claude-opus-4-5-20251101</div>
</div>
<div class="row">
<div class="label">视觉模型</div>
<div class="value chip">gpt-4o</div>
<span class="tag">多模态模型可同时出现在 text/vision 列表</span>
</div>
<div class="row">
<div class="label">音频模型</div>
<div class="value chip">whisper-large-v3</div>
</div>
<div class="muted">注:视觉模型用于画面语义/场景风险;竞品 Logo 检测由内置 CV 模型处理。</div>
</div>
<div class="card">
<h3>3) 连通性测试</h3>
<div class="row">
<div class="label">文本</div>
<div class="chip pill-ok">✓ 成功 342ms</div>
</div>
<div class="row">
<div class="label">视觉</div>
<div class="chip pill-ok">✓ 成功 528ms</div>
</div>
<div class="row">
<div class="label">音频</div>
<div class="chip pill-ok">✓ 成功 215ms</div>
</div>
<div class="divider"></div>
<button class="cta">保存并启用</button>
<div class="muted">保存后立即生效,无需重启。</div>
</div>
<div class="card">
<h3>4) 核心约束与状态</h3>
<ul class="list">
<li>未配置时:所有 AI 调用阻断,提示品牌方完成配置</li>
<li>多租户隔离:品牌方配置互不影响</li>
<li>API Key 加密AES-256-GCM 存储</li>
<li>模型列表获取:前端调用 <span class="mono">/api/v1/ai-config/models</span>(后端代理厂商 <span class="mono">/v1/models</span></li>
<li>代理商/达人:继承配置但不可见</li>
</ul>
</div>
</div>
</div>
</body>
</html>

50
featuredoc/tdd_plan.md Normal file
View File

@ -0,0 +1,50 @@
# tdd_plan.md - TDD 实施计划
本计划作为 `tasks.md` 的配套说明用于统一项目的测试驱动开发TDD实践与验收口径。
---
## 1. 目标与范围
- 所有功能代码遵循「红-绿-重构」循环
- 覆盖后端 API、核心业务逻辑、前端组件与关键流程
- 与 CI/CD 强绑定,未通过测试不得合并
---
## 2. 测试分层与覆盖要求
| 层级 | 目标 | 工具 | 覆盖要求 |
| --- | --- | --- | --- |
| 单元测试 | 业务逻辑与边界条件 | pytest / Vitest | 后端 ≥ 80%,前端 ≥ 70% |
| 接口测试 | API 契约与错误处理 | pytest + httpx | 关键接口 100% 覆盖 |
| 组件测试 | 关键交互与渲染 | Vitest + RTL | 关键组件覆盖 |
| E2E | 核心用户路径 | Playwright | 关键路径覆盖 |
| AI 模型测试 | 模型封装与关键规则验证 | pytest + 标注集 | P0 规则样本覆盖 ≥ 90%P1 ≥ 70%,回归集 100% |
---
## 3. 统一约定
- 每个任务必须包含:
- 至少 1 个失败测试用例(先写)
- 核心成功路径测试
- 关键异常路径测试
- 合并前需满足:
- 测试全部通过
- 覆盖率达标
- 关键路径无回归
---
## 4. 任务验收基线
- 任务完成即具备可运行测试与最小化覆盖
- 关键功能如审核台、AI 配置、上传链路)必须包含 E2E 测试
---
## 5. 变更与维护
- 覆盖率阈值调整需经过 PM + 技术负责人确认
- 重大功能变更需同步更新本计划

261
tasks.md
View File

@ -3,8 +3,8 @@
| 文档类型 | **Development Tasks (开发任务清单)** |
| --- | --- |
| **项目名称** | SmartAudit (AI 营销内容合规审核平台) |
| **版本号** | V1.3 |
| **发布日期** | 2026-02-02 |
| **版本号** | V1.4 |
| **发布日期** | 2026-02-03 |
| **依据文档** | PRD.md, FeatureSummary.md, DevelopmentPlan.md, UIDesign.md, User_Role_Interfaces.md, AIProviderConfig.md |
| **总周期** | 11 周 (2.75 个月) |
@ -87,9 +87,70 @@
| 优先级 | 功能数量 | 说明 |
| --- | --- | --- |
| **P0 (MVP)** | 18 | 必须实现 |
| **P1** | 16 | 首版后快速迭代 |
| **P2** | 12 | 中长期规划 |
| **P0 (MVP)** | 21 | 必须实现 |
| **P1** | 22 | 首版后快速迭代(以 FeatureSummary 的 P1 清单为准) |
| **P2** | 8 | 中长期规划 |
---
### 1.4 功能编号 ↔ 任务编号映射表
| 功能编号 | 对应任务 |
| --- | --- |
| F-01 | TASK-008, TASK-009, TASK-012 |
| F-02 | TASK-010, TASK-012 |
| F-03 | TASK-011, TASK-012, TASK-037E |
| F-04 | TASK-011, TASK-012, TASK-037E |
| F-05 | TASK-037E |
| F-05-A | TASK-013 |
| F-05-B | TASK-045 |
| F-06 | TASK-046 |
| F-07 | TASK-027 |
| F-08 | TASK-020, TASK-028 |
| F-09 | TASK-020 |
| F-10 | TASK-003, TASK-014, TASK-015, TASK-027 |
| F-11 | TASK-016, TASK-017, TASK-022 |
| F-12 | TASK-013, TASK-018 |
| F-13 | TASK-016 |
| F-14 | TASK-019, TASK-028 |
| F-15 | TASK-047 |
| F-16 | TASK-048 |
| F-17 | TASK-004, TASK-023, TASK-024, TASK-027 |
| F-18 | TASK-063 |
| F-19 | TASK-032, TASK-033, TASK-037B |
| F-20 | TASK-034, TASK-037B |
| F-21 | TASK-037H, TASK-064 |
| F-22 | TASK-064 |
| F-23 | TASK-065 |
| F-24 | TASK-029, TASK-035 |
| F-25 | TASK-029, TASK-035 |
| F-26 | TASK-035, TASK-036 |
| F-27 | TASK-030, TASK-030-B |
| F-28 | TASK-054 |
| F-29 | TASK-055 |
| F-30 | TASK-014, TASK-056 |
| F-31 | TASK-057 |
| F-32 | TASK-058 |
| F-33 | TASK-037, TASK-037F |
| F-34 | TASK-037D |
| F-35 | TASK-037D, TASK-037G |
| F-36 | TASK-037D |
| F-37 | TASK-059 |
| F-38 | TASK-037I, TASK-050 |
| F-39 | TASK-050 |
| F-40 | TASK-037I, TASK-051 |
| F-41 | TASK-037G, TASK-060 |
| F-42 | TASK-061 |
| F-43 | TASK-049 |
| F-44 | TASK-068 |
| F-45 | TASK-018, TASK-019, TASK-021 |
| F-46 | TASK-062 |
| F-47 | TASK-005-D, TASK-005-E, TASK-005-F |
| F-48 | TASK-005-E |
| F-49 | TASK-066 |
| F-50 | TASK-067 |
> 注F-05 已拆分为 F-05-A/B历史任务中仍可能出现 F-05 标记。
---
@ -101,7 +162,7 @@
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend |
| **优先级** | P0 |
| **优先级** | P1 |
| **预估工时** | 2d |
| **依赖** | - |
| **功能编号** | 基础设施 |
@ -123,7 +184,7 @@
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend |
| **优先级** | P0 |
| **优先级** | P1 |
| **预估工时** | 2d |
| **依赖** | TASK-001 |
| **功能编号** | 基础设施 |
@ -304,6 +365,7 @@
- [ ] 测试连接并行执行三个模型
- [ ] 仅品牌管理员可访问配置接口
- [ ] 代理商/达人请求自动继承品牌方配置
- [ ] 未配置时返回明确错误并引导品牌方完成配置
---
@ -445,8 +507,8 @@
| **功能编号** | F-02 |
**任务描述:**
- 实现飞书文档 API 接入
- 实现 Notion API 接入
- 实现飞书文档分享链接解析
- 实现 Notion 分享链接解析
- 提取在线文档内容
- 触发 Brief 解析流程
@ -559,7 +621,7 @@
**技术方案参考:** DevelopmentPlan.md 第 2.1 章
**验收标准:**
- [ ] 100MB 视频可分片上传
- [ ] 100MB 视频可分片上传
- [ ] 断网后可断点续传
- [ ] 上传完成触发回调
@ -673,7 +735,7 @@
**技术方案参考:** DevelopmentPlan.md 第 2.5 章
**验收标准:**
- [ ] 时长统计误差 ≤ 0.5
- [ ] 时长统计误差 ≤ 1
- [ ] 频次统计准确率 ≥ 95%
---
@ -718,7 +780,7 @@
- 输出时长/频次校验报告
**验收标准:**
- [ ] 时长统计误差 ≤ 0.5
- [ ] 时长统计误差 ≤ 1
- [ ] 频次统计准确率 ≥ 95%
---
@ -740,7 +802,7 @@
- 存储到数据库
**验收标准:**
- [ ] 100MB 视频审核 ≤ 5 分钟
- [ ] 100MB 视频审核 ≤ 5 分钟(含排队 ≤ 2 分钟)
- [ ] 审核报告包含所有检测结果
---
@ -1025,21 +1087,19 @@
| **优先级** | P0 |
| **预估工时** | 3d |
| **依赖** | TASK-032 |
| **功能编号** | F-19, F-23 |
| **功能编号** | F-19 |
**任务描述:**
- 实现硬性合规区块
- 实现 Brief 完成度区块
- 实现舆情雷达区块
- 实现展开详情
- 实现规则依据查看
**界面参考:** UIDesign.md 第 8.5 章
**验收标准:**
- [ ] 三个区块正常展示
- [ ] 详情可展开
- [ ] 规则依据可查看
---
@ -1050,18 +1110,15 @@
| **优先级** | P0 |
| **预估工时** | 2d |
| **依赖** | TASK-033 |
| **功能编号** | F-20, F-21 |
| **功能编号** | F-20 |
**任务描述:**
- 实现驳回按钮(自动打包问题)
- 实现通过按钮
- 实现强制通过按钮(需填原因)
- 实现记录特例按钮
- 实现审核状态流转 API
**验收标准:**
- [ ] 驳回后达人收到通知
- [ ] 强制通过需填写原因
- [ ] 审计日志记录操作
---
@ -1219,10 +1276,9 @@
| **优先级** | P0 |
| **预估工时** | 3d |
| **依赖** | TASK-006, TASK-037 |
| **功能编号** | F-33, F-34, F-35 |
| **功能编号** | F-34, F-35, F-36 |
**任务描述:**
- 实现顶部指标卡片(审核总量/通过率/召回率/舆情拦截/周期)
- 实现趋势图与问题分布饼图
- 实现代理商对比柱状图
- 实现风险预警区
@ -1230,7 +1286,6 @@
**界面参考:** User_Role_Interfaces.md 第 4.1 章
**验收标准:**
- [ ] 指标数据正确
- [ ] 图表交互正常
- [ ] 预警列表实时更新
@ -1521,7 +1576,7 @@
**验收标准:**
- [ ] 100 并发无异常
- [ ] 视频审核 ≤ 5 分钟
- [ ] ≤ 100MB 视频审核 ≤ 5 分钟(含排队 ≤ 2 分钟)
---
@ -1697,33 +1752,146 @@
---
### 6.4 数据看板增强
### 6.4 数据看板与报表
#### TASK-052: 趋势图表
| 属性 | 内容 |
| --- | --- |
| **负责人** | Frontend |
| **优先级** | P1 |
| **功能编号** | F-34 |
**任务描述:**
- 实现审核量趋势图
- 实现问题分布饼图
- 实现热力图
---
#### TASK-053: 风险预警
#### TASK-059: 达人排行榜(数据报表)
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-35 |
| **功能编号** | F-37 |
| **依赖** | TASK-031, TASK-002 |
**任务描述:**
- 实现异常检测算法
- 实现预警卡片展示
- 实现通知推送
- 实现达人排行榜(通过率/响应速度/问题率)
- 支持按平台/时间范围筛选
- 标记问题达人并支持跳转详情
**验收标准:**
- [ ] 排行榜排序正确
- [ ] 筛选生效
- [ ] 问题达人标记清晰可用
---
### 6.5 代理商管理
#### TASK-068: 代理商管理
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-44 |
**任务描述:**
- 实现代理商列表与绑定项目展示
- 支持配置可见 Brief 范围与仲裁权限
- 支持强制通过授权开关(**按代理商配置**,默认开启,可关闭)
- 绩效评分卡指标展示
**验收标准:**
- [ ] 代理商列表与详情可查看
- [ ] 权限配置可保存并生效
---
### 6.6 审核台与视频审核增强
#### TASK-063: 时间戳修改清单
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-18 |
| **依赖** | TASK-022, TASK-028 |
**任务描述:**
- 生成带时间戳的修改清单(问题点 + 建议)
- 支持按时间点跳转并高亮
- 与审核报告联动展示
**验收标准:**
- [ ] 清单内容与审核报告一致
- [ ] 时间戳跳转准确
---
#### TASK-064: 强制通过与特例记录
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-21, F-22 |
| **依赖** | TASK-034, TASK-037E |
**任务描述:**
- 实现强制通过逻辑(默认授权,支持品牌方**按代理商**关闭授权)
- 关闭授权后,代理商需提交审批
- 强制通过弹窗提供“保存为特例”勾选项(默认不勾选)
- 实现特例记录并写入白名单/豁免条款(品牌方确认后生效)
**验收标准:**
- [ ] 强制通过需填写原因并写入审计日志
- [ ] 授权开关生效(关闭后进入审批流程)
- [ ] 特例记录可落地并可追溯
---
#### TASK-065: 规则依据与证据查看
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-23 |
| **依赖** | TASK-033, TASK-022 |
**任务描述:**
- 展示每条结论的规则依据与证据片段
- 支持截图/片段预览与跳转
**验收标准:**
- [ ] 规则依据可查看
- [ ] 证据片段可预览并定位
---
### 6.7 AI 配置增强
#### TASK-066: 多租户 AI 配置隔离
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend |
| **优先级** | P0 |
| **功能编号** | F-49 |
| **依赖** | TASK-005-D, TASK-005-E |
**任务描述:**
- 不同品牌方租户配置完全隔离
- 配置读取严格按租户鉴权
- 支持审计与变更记录
**验收标准:**
- [ ] 跨租户访问被拒绝
- [ ] 租户配置读取正确
---
#### TASK-067: API Key 轮换管理
| 属性 | 内容 |
| --- | --- |
| **负责人** | Backend + Frontend |
| **优先级** | P1 |
| **功能编号** | F-50 |
| **依赖** | TASK-005-D, TASK-005-F |
**任务描述:**
- 支持轮换 API Key不影响现有服务
- 记录轮换时间与操作人
- 提供轮换后连通性验证
**验收标准:**
- [ ] 轮换后调用可用
- [ ] 轮换记录可追溯
---
@ -1740,7 +1908,6 @@
| TASK-056 | 批量上传(多文件拖拽) | F-30 |
| TASK-057 | 批量审核 | F-31 |
| TASK-058 | 批量导出 | F-32 |
| TASK-059 | 达人排行榜 | F-37 |
| TASK-060 | 舆情风险视频监控 | F-41 |
| TASK-061 | 舆情案例库 | F-42 |
| TASK-062 | 负样本清洗与回流 | F-46 |
@ -1852,9 +2019,9 @@ graph TD
| 语境理解误报率 | ≤ 5% | TASK-020 |
| ASR 字错率 | ≤ 10% | TASK-016 |
| OCR 准确率 | ≥ 95% | TASK-017 |
| 时长统计误差 | ≤ 0.5秒 | TASK-021 |
| 时长统计误差 | ≤ 1秒 | TASK-021 |
| 频次统计准确率 | ≥ 95% | TASK-021 |
| 审核报告产出时间 | ≤ 5 分钟 | TASK-022 |
| 审核报告产出时间 | ≤ 5 分钟(含排队 ≤ 2 分钟) | TASK-022 |
| 并发支持 | 100 并发 | TASK-041 |
| H5 兼容性 | iOS/Android/微信 | TASK-042 |
| 响应式断点适配 | Mobile/Tablet/Desktop | TASK-037J |