wurenzhi
2748456d8a
- 将服务文件按功能分类到core、ai、analytics、security等目录 - 修复logger导入路径问题，统一使用相对路径 - 更新相关文件的导入路径引用 - 添加新的批量操作组件导出文件 - 修复dashboard页面中的类型错误 - 添加dotenv依赖到package.json
839 lines
38 KiB
Markdown
839 lines
38 KiB
Markdown
# 19 广告系统业务闭环 v1.0
|
||
|
||
> 本文档包含广告系统的完整设计：维度体系、数据库结构、后端服务、前端组件、数据源抽象、订阅等级、AI权限、交叉学习架构
|
||
|
||
---
|
||
|
||
## 1️⃣ 广告系统概述
|
||
|
||
### 1.1 系统定位
|
||
|
||
广告系统是**业务核心页**，直接影响利润放大。系统需要：
|
||
- 管理多平台广告（Amazon/TikTok/Shopee/eBay等）
|
||
- 提供AI驱动的优化建议
|
||
- 支持人工与AI协作决策
|
||
- 记录运营经验实现跨平台学习
|
||
|
||
### 1.2 核心理念
|
||
|
||
| 理念 | 说明 |
|
||
|------|------|
|
||
| **AI建议一直有** | 不管什么订阅等级，AI建议永不中断 |
|
||
| **AI执行看等级** | 能不能自动执行，看用户付费多少 |
|
||
| **数据分层索引** | AI处理能力有限，数据要分层索引/模型化 |
|
||
| **跨平台学习** | 通用指标交叉学习，平台专用指标独立学习 |
|
||
|
||
---
|
||
|
||
## 2️⃣ 广告维度体系（四层结构）
|
||
|
||
### 2.1 维度层级图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 📊 最终结果层：实际消耗 / 实际营收 / 净收益 / ROI │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↑
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 1️⃣ 广告计划维度（Campaign Level） │
|
||
│ 预算/消耗/收入/ROI/ROAS/订单数/开始时间 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↑
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 2️⃣ 商品维度（Product Level）← 你刚补充的 │
|
||
│ 商品图片/名称/状态/消耗/订单数/收入/ROI │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↑
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 3️⃣ 素材维度（Creative Level） │
|
||
│ 创意ID/视频指标/CTR/CVR/完播率 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↑
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 4️⃣ 人工操作维度（Human Operation Level） │
|
||
│ 运营经验/干预成功率/响应时间/操作记录 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 第一层：广告计划维度（Campaign）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| campaignId | string | 广告计划唯一ID |
|
||
| campaignName | string | 广告计划名称 |
|
||
| status | enum | ACTIVE/PAUSED/ENDED/DRAFTED |
|
||
| roasBid | decimal | ROAS出价（目标ROAS） |
|
||
| targetRoi | decimal | 目标ROI |
|
||
| budget | decimal | 预算 |
|
||
| dailyBudget | decimal | 日预算 |
|
||
| netSpend | decimal | 净花费 |
|
||
| totalSpend | decimal | 总花费 |
|
||
| totalRevenue | decimal | 总收入 |
|
||
| totalOrders | integer | 总订单数 |
|
||
| avgOrderCost | decimal | 平均订单成本 = 净花费/订单数 |
|
||
| roi | decimal | ROI = 总收入/总花费 |
|
||
| startDate | date | 开始时间 |
|
||
| endDate | date | 结束时间 |
|
||
| platform | enum | AMAZON/TIKTOK/SHOPEE/EBUY等 |
|
||
| shopId | string | 店铺ID |
|
||
| advertiserName | string | 广告主名称 |
|
||
|
||
### 2.3 第二层：商品维度（Product）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| productId | string | 商品ID |
|
||
| productName | string | 商品名称 |
|
||
| productImage | string | 商品图片URL |
|
||
| campaignId | string | 所属广告计划ID |
|
||
| seriesName | string | 推广系列名称 |
|
||
| status | enum | ACTIVE/PAUSED |
|
||
| spend | decimal | 该商品消耗金额 |
|
||
| orders | integer | 该商品订单数 |
|
||
| avgOrderCost | decimal | 平均订单成本 |
|
||
| revenue | decimal | 该商品收入 |
|
||
| roi | decimal | 该商品ROI |
|
||
| shopName | string | 店铺名称 |
|
||
| advertiserName | string | 广告主名称 |
|
||
|
||
### 2.4 第三层：素材维度（Creative）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| creativeId | string | 创意ID |
|
||
| seriesId | string | 推广系列ID |
|
||
| seriesName | string | 推广系列名称 |
|
||
| productId | string | 商品ID |
|
||
| statDate | date | 统计日期 |
|
||
| spend | decimal | 消耗金额 |
|
||
| orderCost | decimal | 单订单成本 |
|
||
| revenue | decimal | 总收入 |
|
||
| roi | decimal | 投资回报率 |
|
||
| currency | enum | USD/CNY/EUR等 |
|
||
| orders | integer | 订单数 |
|
||
| productCtr | decimal | 商品点击率 = clicks/impressions |
|
||
| productClicks | integer | 商品点击数 |
|
||
| productImpressions | integer | 商品展示数 |
|
||
| adCtr | decimal | 广告点击率 |
|
||
| adCvr | decimal | 广告转化率 |
|
||
| videoWatch2s | decimal | 2秒视频观看率（TikTok） |
|
||
| videoWatch6s | decimal | 6秒视频观看率（TikTok） |
|
||
| videoWatch25 | decimal | 25%视频观看率 |
|
||
| videoWatch50 | decimal | 50%视频观看率 |
|
||
| videoWatch75 | decimal | 75%视频观看率 |
|
||
| videoWatch100 | decimal | 100%视频观看率 |
|
||
| creativeStatus | enum | 投放中/暂停/结束 |
|
||
| shopName | string | 店铺名称 |
|
||
| advertiserName | string | 广告主名称 |
|
||
|
||
### 2.5 第四层：人工操作维度（Human Operation）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| operatorId | string | 操作人ID |
|
||
| operatorName | string | 操作人名称 |
|
||
| operateTime | datetime | 操作时间 |
|
||
| operateType | enum | 启动/暂停/调预算/调出价/换素材/审核通过/审核拒绝等 |
|
||
| targetType | enum | 广告计划/商品/素材 |
|
||
| targetId | string | 操作对象ID |
|
||
| beforeValue | json | 操作前的值 |
|
||
| afterValue | json | 操作后的值 |
|
||
| reason | string | 操作原因 |
|
||
| expectedEffect | string | 预期效果 |
|
||
| actualEffect | json | 实际效果（事后回填） |
|
||
| success | boolean | 是否成功（事后评估） |
|
||
|
||
**操作类型枚举：**
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| RESUME | 启动广告 |
|
||
| PAUSE | 暂停广告 |
|
||
| ADJUST_BUDGET | 调整预算 |
|
||
| ADJUST_BID | 调整出价 |
|
||
| CHANGE_CREATIVE | 更换素材 |
|
||
| APPROVE | 审核通过 |
|
||
| REJECT | 审核拒绝 |
|
||
| CHANGE_SCHEDULE | 修改投放时间 |
|
||
| ADD_KEYWORDS | 添加关键词 |
|
||
| REMOVE_KEYWORDS | 删除关键词 |
|
||
|
||
---
|
||
|
||
## 3️⃣ 数据库设计（cf_ad_* 表结构）
|
||
|
||
### 3.1 表清单
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| cf_ad_campaign | 广告计划表 |
|
||
| cf_ad_product | 广告商品表 |
|
||
| cf_ad_creative | 广告素材表 |
|
||
| cf_ad_human_operation | 人工操作记录表 |
|
||
| cf_ad_platform_metrics | 平台原始指标表（每日） |
|
||
| cf_ad_ai_suggestion | AI建议记录表 |
|
||
|
||
### 3.2 cf_ad_campaign（广告计划表）
|
||
|
||
```sql
|
||
CREATE TABLE cf_ad_campaign (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
tenant_id VARCHAR(36) NOT NULL COMMENT '租户ID',
|
||
shop_id VARCHAR(36) NOT NULL COMMENT '店铺ID',
|
||
campaign_id VARCHAR(64) NOT NULL COMMENT '平台广告计划ID',
|
||
campaign_name VARCHAR(256) NOT NULL COMMENT '广告计划名称',
|
||
platform VARCHAR(32) NOT NULL COMMENT '平台：AMAZON/TIKTOK/SHOPEE等',
|
||
status ENUM('DRAFTED','ACTIVE','PAUSED','ENDED') DEFAULT 'DRAFTED',
|
||
budget DECIMAL(12,2) DEFAULT 0 COMMENT '总预算',
|
||
daily_budget DECIMAL(12,2) DEFAULT 0 COMMENT '日预算',
|
||
roas_bid DECIMAL(10,4) DEFAULT 0 COMMENT 'ROAS出价',
|
||
target_roi DECIMAL(10,4) DEFAULT 0 COMMENT '目标ROI',
|
||
net_spend DECIMAL(12,2) DEFAULT 0 COMMENT '净花费',
|
||
total_spend DECIMAL(12,2) DEFAULT 0 COMMENT '总花费',
|
||
total_revenue DECIMAL(12,2) DEFAULT 0 COMMENT '总收入',
|
||
total_orders INT DEFAULT 0 COMMENT '总订单数',
|
||
avg_order_cost DECIMAL(10,2) DEFAULT 0 COMMENT '平均订单成本',
|
||
roi DECIMAL(10,4) DEFAULT 0 COMMENT 'ROI',
|
||
start_date DATE COMMENT '开始时间',
|
||
end_date DATE COMMENT '结束时间',
|
||
advertiser_name VARCHAR(128) COMMENT '广告主名称',
|
||
ai_confidence DECIMAL(5,4) DEFAULT 1.0 COMMENT 'AI信心指数',
|
||
last_optimized_at DATETIME COMMENT '最后优化时间',
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
UNIQUE KEY uk_tenant_campaign (tenant_id, campaign_id, platform),
|
||
INDEX idx_tenant_shop (tenant_id, shop_id),
|
||
INDEX idx_platform_status (platform, status)
|
||
) COMMENT='广告计划表';
|
||
```
|
||
|
||
### 3.3 cf_ad_product（广告商品表）
|
||
|
||
```sql
|
||
CREATE TABLE cf_ad_product (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
tenant_id VARCHAR(36) NOT NULL,
|
||
shop_id VARCHAR(36) NOT NULL,
|
||
campaign_id VARCHAR(36) NOT NULL COMMENT '关联广告计划',
|
||
product_id VARCHAR(64) NOT NULL COMMENT '商品ID',
|
||
product_name VARCHAR(256) COMMENT '商品名称',
|
||
product_image VARCHAR(512) COMMENT '商品图片',
|
||
series_name VARCHAR(128) COMMENT '推广系列名称',
|
||
status ENUM('ACTIVE','PAUSED') DEFAULT 'ACTIVE',
|
||
spend DECIMAL(12,2) DEFAULT 0 COMMENT '消耗',
|
||
orders INT DEFAULT 0 COMMENT '订单数',
|
||
avg_order_cost DECIMAL(10,2) DEFAULT 0 COMMENT '平均订单成本',
|
||
revenue DECIMAL(12,2) DEFAULT 0 COMMENT '收入',
|
||
roi DECIMAL(10,4) DEFAULT 0 COMMENT 'ROI',
|
||
shop_name VARCHAR(128) COMMENT '店铺名称',
|
||
advertiser_name VARCHAR(128) COMMENT '广告主名称',
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
UNIQUE KEY uk_campaign_product (campaign_id, product_id),
|
||
INDEX idx_tenant_shop (tenant_id, shop_id)
|
||
) COMMENT='广告商品表';
|
||
```
|
||
|
||
### 3.4 cf_ad_creative（广告素材表）
|
||
|
||
```sql
|
||
CREATE TABLE cf_ad_creative (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
tenant_id VARCHAR(36) NOT NULL,
|
||
campaign_id VARCHAR(36) NOT NULL,
|
||
product_id VARCHAR(36) NOT NULL,
|
||
creative_id VARCHAR(64) NOT NULL COMMENT '平台素材ID',
|
||
series_id VARCHAR(64) COMMENT '推广系列ID',
|
||
series_name VARCHAR(128) COMMENT '推广系列名称',
|
||
creative_url VARCHAR(512) COMMENT '素材URL',
|
||
creative_type ENUM('IMAGE','VIDEO') DEFAULT 'IMAGE',
|
||
status ENUM('RUNNING','PAUSED','ENDED') DEFAULT 'RUNNING',
|
||
spend DECIMAL(12,2) DEFAULT 0,
|
||
revenue DECIMAL(12,2) DEFAULT 0,
|
||
roi DECIMAL(10,4) DEFAULT 0,
|
||
currency VARCHAR(8) DEFAULT 'USD',
|
||
orders INT DEFAULT 0,
|
||
product_ctr DECIMAL(8,4) DEFAULT 0 COMMENT '商品点击率',
|
||
product_clicks INT DEFAULT 0,
|
||
product_impressions INT DEFAULT 0,
|
||
ad_ctr DECIMAL(8,4) DEFAULT 0,
|
||
ad_cvr DECIMAL(8,4) DEFAULT 0,
|
||
video_watch_2s DECIMAL(8,4) DEFAULT 0 COMMENT '2秒观看率',
|
||
video_watch_6s DECIMAL(8,4) DEFAULT 0,
|
||
video_watch_25 DECIMAL(8,4) DEFAULT 0,
|
||
video_watch_50 DECIMAL(8,4) DEFAULT 0,
|
||
video_watch_75 DECIMAL(8,4) DEFAULT 0,
|
||
video_watch_100 DECIMAL(8,4) DEFAULT 0,
|
||
shop_name VARCHAR(128),
|
||
advertiser_name VARCHAR(128),
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
UNIQUE KEY uk_campaign_creative (campaign_id, creative_id),
|
||
INDEX idx_product (product_id)
|
||
) COMMENT='广告素材表';
|
||
```
|
||
|
||
### 3.5 cf_ad_human_operation（人工操作记录表）
|
||
|
||
```sql
|
||
CREATE TABLE cf_ad_human_operation (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
tenant_id VARCHAR(36) NOT NULL,
|
||
operator_id VARCHAR(36) NOT NULL,
|
||
operator_name VARCHAR(64) NOT NULL,
|
||
operate_time DATETIME NOT NULL,
|
||
operate_type ENUM('RESUME','PAUSE','ADJUST_BUDGET','ADJUST_BID','CHANGE_CREATIVE',
|
||
'APPROVE','REJECT','CHANGE_SCHEDULE','ADD_KEYWORDS','REMOVE_KEYWORDS') NOT NULL,
|
||
target_type ENUM('CAMPAIGN','PRODUCT','CREATIVE') NOT NULL,
|
||
target_id VARCHAR(36) NOT NULL,
|
||
before_value JSON COMMENT '操作前值',
|
||
after_value JSON COMMENT '操作后值',
|
||
reason TEXT COMMENT '操作原因',
|
||
expected_effect TEXT COMMENT '预期效果',
|
||
actual_effect JSON COMMENT '实际效果',
|
||
success BOOLEAN COMMENT '是否成功',
|
||
evaluated_at DATETIME COMMENT '评估时间',
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
INDEX idx_tenant_operator (tenant_id, operator_id),
|
||
INDEX idx_target (target_type, target_id),
|
||
INDEX idx_operate_time (operate_time)
|
||
) COMMENT='人工操作记录表';
|
||
```
|
||
|
||
### 3.6 cf_ad_ai_suggestion（AI建议记录表）
|
||
|
||
```sql
|
||
CREATE TABLE cf_ad_ai_suggestion (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
tenant_id VARCHAR(36) NOT NULL,
|
||
shop_id VARCHAR(36) NOT NULL,
|
||
campaign_id VARCHAR(36),
|
||
product_id VARCHAR(36),
|
||
creative_id VARCHAR(36),
|
||
suggestion_type ENUM('RESUME','PAUSE','ADJUST_BUDGET','ADJUST_BID',
|
||
'CHANGE_CREATIVE','CREATE','DELETE') NOT NULL,
|
||
target_type ENUM('CAMPAIGN','PRODUCT','CREATIVE') NOT NULL,
|
||
target_id VARCHAR(36) NOT NULL,
|
||
current_value JSON NOT NULL COMMENT '当前值',
|
||
suggested_value JSON NOT NULL COMMENT '建议值',
|
||
confidence DECIMAL(5,4) NOT NULL COMMENT '置信度 0-1',
|
||
risk_level ENUM('LOW','MEDIUM','HIGH','CRITICAL') DEFAULT 'LOW',
|
||
estimated_impact JSON COMMENT '预估影响',
|
||
reason TEXT COMMENT 'AI推理原因',
|
||
status ENUM('PENDING','APPROVED','REJECTED','EXECUTED','EXPIRED') DEFAULT 'PENDING',
|
||
required_action ENUM('AUTO_EXECUTE','PENDING_REVIEW','AUTO_REJECT') DEFAULT 'PENDING_REVIEW',
|
||
reviewed_by VARCHAR(36),
|
||
reviewed_at DATETIME,
|
||
executed_at DATETIME,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
INDEX idx_tenant_campaign (tenant_id, campaign_id),
|
||
INDEX idx_status (status),
|
||
INDEX idx_required_action (required_action)
|
||
) COMMENT='AI建议记录表';
|
||
```
|
||
|
||
---
|
||
|
||
## 4️⃣ 后端API结构
|
||
|
||
### 4.1 Controller层
|
||
|
||
```
|
||
server/src/api/controllers/
|
||
├── AdController.ts # 广告计划CRUD
|
||
├── AdProductController.ts # 广告商品CRUD
|
||
├── AdCreativeController.ts # 广告素材CRUD
|
||
├── AdOperationController.ts # 人工操作记录
|
||
└── AdAnalyticsController.ts # 数据分析
|
||
```
|
||
|
||
### 4.2 Service层
|
||
|
||
```
|
||
server/src/services/
|
||
├── AdCampaignService.ts # 广告计划服务
|
||
├── AdProductService.ts # 广告商品服务
|
||
├── AdCreativeService.ts # 广告素材服务
|
||
├── AdHumanOperationService.ts # 人工操作服务
|
||
├── AdAnalyticsService.ts # 数据分析服务
|
||
└── AdAIRecommendationService.ts # AI建议服务
|
||
```
|
||
|
||
### 4.3 核心API接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/v1/ad/campaigns | 获取广告计划列表 |
|
||
| POST | /api/v1/ad/campaigns | 创建广告计划 |
|
||
| GET | /api/v1/ad/campaigns/:id | 获取广告计划详情 |
|
||
| PUT | /api/v1/ad/campaigns/:id | 更新广告计划 |
|
||
| PUT | /api/v1/ad/campaigns/:id/status | 更新广告状态 |
|
||
| POST | /api/v1/ad/campaigns/:id/resume | 启动广告 |
|
||
| POST | /api/v1/ad/campaigns/:id/pause | 暂停广告 |
|
||
| GET | /api/v1/ad/campaigns/:id/products | 获取广告商品列表 |
|
||
| GET | /api/v1/ad/campaigns/:id/analytics | 获取广告分析数据 |
|
||
| GET | /api/v1/ad/ai-suggestions | 获取AI建议列表 |
|
||
| POST | /api/v1/ad/ai-suggestions/:id/approve | 审批AI建议 |
|
||
| POST | /api/v1/ad/ai-suggestions/:id/reject | 拒绝AI建议 |
|
||
| GET | /api/v1/ad/operations | 获取操作记录 |
|
||
| POST | /api/v1/ad/operations | 记录人工操作 |
|
||
|
||
### 4.4 Service接口定义
|
||
|
||
```typescript
|
||
// AdCampaignService.ts
|
||
export class AdCampaignService {
|
||
// 基础CRUD
|
||
static async createCampaign(params: CreateCampaignParams): Promise<AdCampaign>;
|
||
static async getCampaignById(id: string): Promise<AdCampaign>;
|
||
static async updateCampaign(id: string, updates: Partial<AdCampaign>): Promise<AdCampaign>;
|
||
static async deleteCampaign(id: string): Promise<void>;
|
||
|
||
// 状态操作
|
||
static async resumeCampaign(id: string, userId: string): Promise<AdCampaign>;
|
||
static async pauseCampaign(id: string, userId: string): Promise<AdCampaign>;
|
||
|
||
// 查询
|
||
static async listCampaigns(tenantId: string, shopId: string, filters?: CampaignFilters): Promise<AdCampaign[]>;
|
||
static async getCampaignAnalytics(id: string, dateRange: DateRange): Promise<CampaignAnalytics>;
|
||
|
||
// AI相关
|
||
static async getAISuggestions(campaignId: string): Promise<AISuggestion[]>;
|
||
static async applyAISuggestion(suggestionId: string, approved: boolean, userId: string): Promise<void>;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5️⃣ 前端组件结构
|
||
|
||
### 5.1 页面结构
|
||
|
||
```
|
||
dashboard/src/pages/Ad/
|
||
├── index.tsx # 广告主页
|
||
├── CampaignList.tsx # 广告计划列表
|
||
├── CampaignDetail.tsx # 广告计划详情
|
||
├── ProductList.tsx # 广告商品列表
|
||
├── CreativeList.tsx # 广告素材列表
|
||
├── AIOptimization/ # AI优化模块
|
||
│ ├── index.tsx # AI优化主页
|
||
│ ├── SuggestionList.tsx # 建议列表
|
||
│ └── SuggestionDetail.tsx # 建议详情
|
||
├── Analytics/ # 数据分析模块
|
||
│ ├── index.tsx # 分析主页
|
||
│ ├── PerformanceChart.tsx # 效果图表
|
||
│ └── TrendAnalysis.tsx # 趋势分析
|
||
└── OperationLog/ # 操作记录模块
|
||
└── index.tsx # 操作日志
|
||
```
|
||
|
||
### 5.2 DataSource抽象层
|
||
|
||
```typescript
|
||
// dashboard/src/services/adDataSource.ts
|
||
|
||
// ==================== 类型定义 ====================
|
||
export interface AdCampaign {
|
||
id: string;
|
||
campaignName: string;
|
||
platform: Platform;
|
||
status: CampaignStatus;
|
||
budget: number;
|
||
spend: number;
|
||
revenue: number;
|
||
roi: number;
|
||
// ... 其他字段
|
||
}
|
||
|
||
export interface AdProduct {
|
||
id: string;
|
||
productId: string;
|
||
productName: string;
|
||
productImage: string;
|
||
campaignId: string;
|
||
status: ProductStatus;
|
||
spend: number;
|
||
orders: number;
|
||
revenue: number;
|
||
roi: number;
|
||
}
|
||
|
||
export interface AdCreative {
|
||
id: string;
|
||
creativeId: string;
|
||
productId: string;
|
||
creativeUrl: string;
|
||
creativeType: 'IMAGE' | 'VIDEO';
|
||
status: CreativeStatus;
|
||
spend: number;
|
||
orders: number;
|
||
roi: number;
|
||
videoMetrics?: VideoMetrics;
|
||
}
|
||
|
||
export interface AISuggestion {
|
||
id: string;
|
||
suggestionType: SuggestionType;
|
||
targetType: 'CAMPAIGN' | 'PRODUCT' | 'CREATIVE';
|
||
targetId: string;
|
||
currentValue: any;
|
||
suggestedValue: any;
|
||
confidence: number;
|
||
riskLevel: RiskLevel;
|
||
status: SuggestionStatus;
|
||
}
|
||
|
||
// ==================== DataSource接口 ====================
|
||
export interface IAdDataSource {
|
||
// 广告计划
|
||
fetchCampaigns(params?: CampaignQueryParams): Promise<AdCampaign[]>;
|
||
fetchCampaignById(id: string): Promise<AdCampaign>;
|
||
createCampaign(data: CreateCampaignData): Promise<AdCampaign>;
|
||
updateCampaign(id: string, data: UpdateCampaignData): Promise<AdCampaign>;
|
||
resumeCampaign(id: string): Promise<AdCampaign>;
|
||
pauseCampaign(id: string): Promise<AdCampaign>;
|
||
|
||
// 广告商品
|
||
fetchProductsByCampaign(campaignId: string): Promise<AdProduct[]>;
|
||
|
||
// 广告素材
|
||
fetchCreativesByProduct(productId: string): Promise<AdCreative[]>;
|
||
|
||
// AI建议
|
||
fetchAISuggestions(campaignId?: string): Promise<AISuggestion[]>;
|
||
approveSuggestion(id: string): Promise<AISuggestion>;
|
||
rejectSuggestion(id: string): Promise<AISuggestion>;
|
||
|
||
// 分析数据
|
||
fetchCampaignAnalytics(campaignId: string, dateRange: DateRange): Promise<CampaignAnalytics>;
|
||
|
||
// 操作记录
|
||
fetchOperations(params?: OperationQueryParams): Promise<OperationRecord[]>;
|
||
recordOperation(data: OperationRecordData): Promise<OperationRecord>;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6️⃣ 订阅等级与AI权限映射
|
||
|
||
### 6.1 订阅等级定义
|
||
|
||
| 等级 | 说明 | 典型用户 |
|
||
|------|------|---------|
|
||
| FREE | 免费版 | 个人卖家/试用用户 |
|
||
| BASIC | 基础版 | 小型卖家 |
|
||
| PROFESSIONAL | 专业版 | 中型卖家 |
|
||
| ENTERPRISE | 企业版 | 大型卖家/代理商 |
|
||
|
||
### 6.2 AI权限映射
|
||
|
||
| 功能 | FREE | BASIC | PROFESSIONAL | ENTERPRISE |
|
||
|------|------|-------|--------------|------------|
|
||
| AI建议 | ✅ 始终有 | ✅ 始终有 | ✅ 始终有 | ✅ 始终有 |
|
||
| 广告计划创建 | 人工 | 人工 | AI辅助 | AI自动 |
|
||
| 广告启动/暂停 | 人工 | 人工+低风险AI | AI中风险 | AI高风险 |
|
||
| 预算调整 | 人工 | ≤1000自动 | ≤10000自动 | 无限制 |
|
||
| 素材更换 | 人工 | 人工 | AI辅助 | AI自动 |
|
||
| 数据分析深度 | 基础 | 进阶 | 高级 | 全部 |
|
||
| 跨平台学习 | ❌ | ❌ | ✅ | ✅ |
|
||
| 自定义阈值 | ❌ | ❌ | ✅ | ✅ |
|
||
|
||
### 6.3 阈值配置示例
|
||
|
||
```typescript
|
||
const AI_PERMISSION_CONFIG = {
|
||
FREE: {
|
||
autoExecuteConfidence: 1.0, // 必须100%置信度（实际上不可能）
|
||
maxAutoBudget: 0,
|
||
allowedRiskLevels: [],
|
||
requireHumanApproval: true,
|
||
},
|
||
BASIC: {
|
||
autoExecuteConfidence: 0.95,
|
||
maxAutoBudget: 1000,
|
||
allowedRiskLevels: ['LOW'],
|
||
requireHumanApproval: true,
|
||
},
|
||
PROFESSIONAL: {
|
||
autoExecuteConfidence: 0.80,
|
||
maxAutoBudget: 10000,
|
||
allowedRiskLevels: ['LOW', 'MEDIUM'],
|
||
requireHumanApproval: false,
|
||
},
|
||
ENTERPRISE: {
|
||
autoExecuteConfidence: 0.55,
|
||
maxAutoBudget: Infinity,
|
||
allowedRiskLevels: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'],
|
||
requireHumanApproval: false,
|
||
},
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 7️⃣ 交叉学习架构
|
||
|
||
### 7.1 设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| 通用指标交叉学习 | spend/revenue/orders/roi/ctr/cvr 所有平台通用 |
|
||
| 平台专用指标独立学习 | video_watch_*/acos等只在对应平台学习 |
|
||
| 分层模型架构 | 通用层 → 平台专用层 |
|
||
|
||
### 7.2 交叉学习架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 数据输入层 │
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||
│ │Amazon │ │ TikTok │ │ Shopee │ │ eBay │ │
|
||
│ │ 数据 │ │ 数据 │ │ 数据 │ │ 数据 │ │
|
||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||
└───────┼───────────┼───────────┼───────────┼────────────────┘
|
||
↓ ↓ ↓ ↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 指标提取层 │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ 通用指标提取 │ │
|
||
│ │ spend, revenue, orders, roi, ctr, cvr │ │
|
||
│ │ → 进入跨平台学习池 │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Amazon专用 │ │ TikTok专用 │ │ Shopee专用 │ │
|
||
│ │ ACoS指标 │ │ 视频指标 │ │ 平台互动指标 │ │
|
||
│ │ → 独立学习 │ │ → 独立学习 │ │ → 独立学习 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 模型训练层 │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ 跨平台通用模型 │ │
|
||
│ │ 学到：预算分配原则/出价策略/效果预测 │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Amazon模型 │ │ TikTok模型 │ │ Shopee模型 │ │
|
||
│ │ ACoS优化 │ │ 视频优化 │ │ 互动优化 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 建议输出层 │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ 通用建议：预算怎么分/要不要暂停/要不要加投 │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │Amazon建议 │ │TikTok建议 │ │Shopee建议 │ │
|
||
│ │ 降低ACoS │ │ 优化视频开头 │ │ 提高互动率 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 7.3 维度索引/模型
|
||
|
||
| 索引/模型 | 说明 | AI调用场景 |
|
||
|-----------|------|-----------|
|
||
| campaign_aggregation | 广告计划聚合统计 | 需要计划级汇总时 |
|
||
| product_ranking | 商品效果排序 | 需要商品级排名时 |
|
||
| creative_scoring | 素材效能评分 | 需要素材对比时 |
|
||
| human_experience | 运营经验提取 | 需要学习人工策略时 |
|
||
| time_series_trend | 时间序列趋势 | 需要看周期性规律时 |
|
||
|
||
---
|
||
|
||
## 8️⃣ 决策流程与人工介入点
|
||
|
||
### 8.1 完整业务流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 1️⃣ 创建产品（本地库） │
|
||
│ 人工/系统创建 → 本地产品表 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 2️⃣ 复制产品 │
|
||
│ 手动触发 或 广告需要时自动触发 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 3️⃣ 一对多刊登 │
|
||
│ 单平台×多产品 / 多平台×多产品 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 4️⃣ AI换图 │
|
||
│ 自动生成5倍主图+详情图 → 人工确认 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 5️⃣ 创建广告计划 │
|
||
│ 人工确认预算/关键词 → PENDING_REVIEW（预算>10000） │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 6️⃣ 广告启停 │
|
||
│ AI监控数据 → 给出建议 → 人工确认/执行 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 7️⃣ 人工操作记录 │
|
||
│ 记录操作 → 评估效果 → 学习经验 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 📊 最终结果：实际消耗 / 实际营收 / ROI │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 8.2 人工介入点汇总
|
||
|
||
| 阶段 | 介入条件 | 介入原因 |
|
||
|------|---------|---------|
|
||
| 产品复制 | 无API平台 | AI无法自动操作 |
|
||
| AI换图 | 生成完成 | 确认图片质量 |
|
||
| 创建广告 | 预算>10000 | 金额大需确认 |
|
||
| 广告启停 | 置信度55-80% | AI拿不准 |
|
||
| 广告重建 | 始终 | 新决策需确认 |
|
||
| 素材更换 | 始终 | 人工确认素材 |
|
||
| **批量操作** | **看订阅等级** | **AI可能接管** |
|
||
|
||
### 8.3 AI批量操作接管逻辑
|
||
|
||
#### 8.3.1 批量操作AI接管原则
|
||
|
||
| 操作类型 | AI可接管 | 条件 |
|
||
|----------|---------|------|
|
||
| 修改价格 | ✅ | 订阅等级 ≥ BASIC + 置信度 ≥ 阈值 |
|
||
| 修改库存 | ✅ | 订阅等级 ≥ BASIC + 置信度 ≥ 阈值 |
|
||
| 修改标题 | ✅ | 订阅等级 ≥ PROFESSIONAL + AI生成 |
|
||
| 修改类目 | ❌ | 始终人工（涉及分类逻辑） |
|
||
| 修改包装重量/尺寸 | ✅ | 订阅等级 ≥ BASIC |
|
||
| 修改是否到货付款 | ❌ | 始终人工（涉及风控） |
|
||
| 修改Seller SKU | ❌ | 始终人工（涉及映射） |
|
||
| **批量上架** | ✅ | 订阅等级 ≥ PROFESSIONAL + AI分析通过 |
|
||
| **批量下架** | ✅ | 订阅等级 ≥ PROFESSIONAL + AI分析通过 |
|
||
|
||
#### 8.3.2 批量操作AI流程
|
||
|
||
```
|
||
用户发起批量操作
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ 判断：订阅等级 ≥ BASIC？ │
|
||
├──────────────┬──────────────────────┤
|
||
│ 是 │ 否 │
|
||
↓ ↓
|
||
AI分析数据 人工执行
|
||
+ 生成建议 （无AI介入）
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ 判断：置信度 ≥ 阈值？ │
|
||
├──────────────┬──────────────────────┤
|
||
│ 是 │ 否 │
|
||
↓ ↓
|
||
AI自动执行 人工确认
|
||
+ 记录经验 + 记录经验
|
||
↓
|
||
AI学习这次操作
|
||
```
|
||
|
||
#### 8.3.3 批量操作统一入口
|
||
|
||
所有批量操作统一在 **OperationAgent（AI运营中心）** 执行：
|
||
|
||
```
|
||
pages/OperationAgent/
|
||
├── components/
|
||
│ ├── ProductBatch/
|
||
│ │ ├── BatchEditModal.tsx # 批量编辑（价格/库存/标题等）
|
||
│ │ ├── BatchListingModal.tsx # 批量上架
|
||
│ │ └── BatchDelistModal.tsx # 批量下架
|
||
│ ├── AdBatch/
|
||
│ │ ├── AdCreateModal.tsx # 新建广告
|
||
│ │ ├── AdBatchResume.tsx # 批量启动
|
||
│ │ └── AdBatchPause.tsx # 批量暂停
|
||
│ ├── AISuggestionList.tsx # AI建议
|
||
│ └── HumanOperationLog.tsx # 人工操作记录
|
||
```
|
||
|
||
**产品页面只保留：列表查看 + 详情查看，禁止放置任何操作功能**
|
||
|
||
#### 8.3.4 批量操作类型定义
|
||
|
||
```typescript
|
||
enum BatchOperationType {
|
||
// 产品批量操作
|
||
BATCH_EDIT_PRICE = 'BATCH_EDIT_PRICE', // 批量修改价格
|
||
BATCH_EDIT_INVENTORY = 'BATCH_EDIT_INVENTORY', // 批量修改库存
|
||
BATCH_EDIT_TITLE = 'BATCH_EDIT_TITLE', // 批量修改标题
|
||
BATCH_EDIT_CATEGORY = 'BATCH_EDIT_CATEGORY', // 批量修改类目
|
||
BATCH_EDIT_PACKAGE_WEIGHT = 'BATCH_EDIT_PACKAGE_WEIGHT', // 批量修改包装重量
|
||
BATCH_EDIT_PACKAGE_SIZE = 'BATCH_EDIT_PACKAGE_SIZE', // 批量修改包装尺寸
|
||
BATCH_EDIT_COD = 'BATCH_EDIT_COD', // 批量修改到货付款
|
||
BATCH_EDIT_SELLER_SKU = 'BATCH_EDIT_SELLER_SKU', // 批量修改Seller SKU
|
||
BATCH_LISTING = 'BATCH_LISTING', // 批量上架
|
||
BATCH_DELIST = 'BATCH_DELIST', // 批量下架
|
||
|
||
// 广告批量操作
|
||
BATCH_AD_CREATE = 'BATCH_AD_CREATE', // 批量创建广告
|
||
BATCH_AD_RESUME = 'BATCH_AD_RESUME', // 批量启动广告
|
||
BATCH_AD_PAUSE = 'BATCH_AD_PAUSE', // 批量暂停广告
|
||
BATCH_AD_ADJUST_BUDGET = 'BATCH_AD_ADJUST_BUDGET', // 批量调整预算
|
||
BATCH_AD_CHANGE_CREATIVE = 'BATCH_AD_CHANGE_CREATIVE', // 批量更换素材
|
||
}
|
||
```
|
||
|
||
### 8.4 AI建议 → 人工确认流程
|
||
|
||
```
|
||
AI分析数据
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ 置信度 ≥ 阈值（按订阅等级）？ │
|
||
├──────────────┬──────────────────────┤
|
||
│ 是 │ 否 │
|
||
↓ ↓
|
||
AI自动执行 推送给用户
|
||
（按订阅等级） 人工确认
|
||
↓
|
||
┌──────┴──────┐
|
||
✅ 确认 ❌ 拒绝
|
||
↓ ↓
|
||
执行 记录拒绝
|
||
```
|
||
|
||
---
|
||
|
||
## 9️⃣ 术语表
|
||
|
||
| 术语 | 说明 |
|
||
|------|------|
|
||
| ROAS | Return on Ad Spend，广告支出回报率 = 收入/支出 |
|
||
| ACoS | Advertising Cost of Sales，广告成本销售比 = 支出/收入 |
|
||
| CTR | Click Through Rate，点击率 = 点击/展示 |
|
||
| CVR | Conversion Rate，转化率 = 转化/点击 |
|
||
| CPA | Cost Per Acquisition，获客成本 = 支出/订单 |
|
||
| CPC | Cost Per Click，点击成本 = 支出/点击 |
|
||
| SKU | Stock Keeping Unit，库存单位 |
|
||
| Creative | 广告素材（图片/视频） |
|
||
| Campaign | 广告计划/广告系列 |
|
||
|
||
---
|
||
|
||
## 🔟 参考文档
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| AI自动化域 | docs/LOOPS/10_AI_Automation.md |
|
||
| 广告页面前端 | docs/ARCHIVE/01_Architecture/frontend/03_Ad.md |
|
||
| 后端广告服务 | docs/ARCHIVE/00_Business/tasks/backend/08_advertisement.md |
|
||
| 统一类型管理 | docs/ARCHIVE/01_Architecture/16_Unified_Type_Management.md |
|
||
|
||
---
|
||
|
||
*本文档为 v1.1 版本，包含AI批量操作接管逻辑*
|