123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
# CID
|
||
|
||
CID 服务，承载三块业务：
|
||
|
||
1. **内容审核（现有）**：将广告素材（图片/视频）提交易盾进行内容审核，提供 REST API、定时送检调度器和前端管理页
|
||
2. **投放平台（规划中）**：外投对接广告平台营销 API（巨量/聚光/磁力等）建计划、传素材、启停调优、拉报表；自有 DSP 投自有媒体流量（PD 直投/程序化直购 + RTB 实时竞价）
|
||
3. **CID 归因平台（规划中）**：连接投放与电商平台（京东/淘宝等），记录广告点击、归因转化、回传转化给广告平台（自有流量转化回流自身优化）
|
||
|
||
## 目录结构与业务模块
|
||
|
||
分层 + 业务模块结构：顶层按层分目录，每层下按业务域分子模块，各层模块目录严格镜像。
|
||
|
||
```
|
||
controller/ HTTP 接口层，按模块分子目录
|
||
service/ 业务逻辑层，按模块分子目录
|
||
dao/ 数据访问层，按模块分子目录（各模块 db.go 提供 Model helper 选择数据源库）
|
||
model/
|
||
├── entity/ 数据库表实体（每表一个文件：Entity + Col + Cols 三段式）
|
||
├── dto/ 请求/响应结构
|
||
└── event/ 事件体（MQ/ClickHouse 消息契约，规划中）
|
||
consts/ 常量（表名、状态），按模块分子目录
|
||
resource/frontend/ 静态前端页面
|
||
sql/ DDL 与迁移脚本
|
||
```
|
||
|
||
| 模块 | 业务域 | 主要表 |
|
||
|---|---|---|
|
||
| check/ | 内容审核（现有）：易盾检测提交/回调/轮询、素材校验、送检调度 | tencent_image、tencent_video、material_verify_log、tencent_content_check_log、tencent_account_relation |
|
||
| delivery/ | 投放域（规划）：计划树四层（计划/单元/广告/创意），本地实体 + 平台 ID 双轨同步 | campaign、ad_group、ad、creative |
|
||
| material/ | 素材域（规划）：素材文件库与多通道审核状态机 | material、material_audit |
|
||
| dsp/ | 自有流量域（规划）：自有媒体/广告位、PD 预订单、RTB 请求与展示计费 | media、ad_slot、placement、bid_request_log、auction_log |
|
||
| attribution/ | 归因域（规划）：点击记录、CID 生成、订单归因与转化回传（点击→转化→回传为同一链路） | click_log、conversion_order、report_task |
|
||
| platform/ | 平台配置域（规划）：广告账户（多级层级 + API 凭据 + 能力）、下游电商平台对接配置与商品映射 | ad_account、commerce_platform_config、item_mapping |
|
||
| report/ | 报表域（规划）：统一消耗/效果汇总（外投平台报表 + DSP 聚合） | daily_report |
|
||
|
||
> 租户/广告主信息由 admin-go 承载，CID 各表以 `tenant_id` 隔离，不建账户/租户表。
|
||
|
||
## 数据流
|
||
|
||
**内容审核链路**：
|
||
|
||
```
|
||
素材表(tencent_image/tencent_video, dataengine库)
|
||
→ 定时送检调度器 / 手动送检
|
||
→ 易盾检测（回调模式或轮询模式）
|
||
→ 结果写入 material_verify_log(cid库) + 回填素材表审核状态
|
||
```
|
||
|
||
**投放链路（规划）**：
|
||
|
||
```
|
||
外投：CID 创建计划(campaign/单元/广告/创意，本地草稿)
|
||
→ 同步平台营销 API（计划/单元/广告/创意/素材上传）
|
||
→ 平台审核（素材审核状态机）→ 启停/调价 → 拉取平台报表 → daily_report
|
||
|
||
自有DSP：PD直投（placement 预订单）或 RTB 竞价（bid_request_log → auction_log）
|
||
→ 展示/点击计费 → 点击进归因链路（channel=self_dsp）
|
||
```
|
||
|
||
**CID 归因链路（规划）**：
|
||
|
||
```
|
||
用户点击广告 → 广告平台/自有媒体跳转 CID（携带广告参数）
|
||
→ 生成 click_id、记录点击（click_log）→ 302 跳转电商平台（URL 带 click_id）
|
||
→ 用户下单支付 → 电商平台回调 CID（订单 + click_id）
|
||
→ 归因去重（conversion_order，幂等）→ 回传转化给广告平台（report_task 队列 + 失败重试）
|
||
```
|
||
|
||
## 表清单
|
||
|
||
### check 模块（现有）
|
||
|
||
| 表 | 库 | 说明 |
|
||
|---|---|---|
|
||
| tencent_image | dataengine | 图片素材（外部系统共享） |
|
||
| tencent_video | dataengine | 视频素材（外部系统共享） |
|
||
| material_verify_log | cid | 素材校验日志（易盾结果落库） |
|
||
| tencent_content_check_log | cid | 送检日志 |
|
||
| tencent_account_relation | cid | 腾讯广告账户关系 |
|
||
|
||
### 投放/归因模块（规划，DDL 见技术设计.md）
|
||
|
||
| 表 | 库 | 说明 |
|
||
|---|---|---|
|
||
| ad_account | cid | 广告账户（多级层级 + API 凭据 + 能力，由 ad_platform_account 改造） |
|
||
| campaign / ad_group / ad / creative | cid | 计划树四层（本地实体 + 平台 ID 双轨） |
|
||
| material / material_audit | cid | 素材库 + 多通道审核状态机 |
|
||
| media / ad_slot / placement | cid | 自有媒体/广告位/PD 预订单 |
|
||
| bid_request_log / auction_log | cid | RTB 请求日志 / 展示计费（按 day 分区） |
|
||
| click_log | cid | 点击日志（不可变事件），按 day 分区 |
|
||
| conversion_order | cid | 转化订单（归因与回传状态） |
|
||
| report_task | cid | 转化回传任务队列（失败退避重试） |
|
||
| daily_report | cid | 统一消耗/效果汇总（外投报表 + DSP 聚合） |
|
||
| commerce_platform_config | cid | 下游电商平台对接配置 |
|
||
| item_mapping | cid | 广告商品 ↔ 电商商品映射 |
|
||
|
||
## API 清单
|
||
|
||
路由由 common 库 `http.RouteRegister` 反射注册：路径按控制器结构体名 + 方法名自动派生（如 `YidunController` 的 `DetectText` → `/yidun/controller/detect-text`）。main.go 注册的控制器：
|
||
|
||
| 控制器 | 职责 |
|
||
|---|---|
|
||
| check.YidunController | 文本/图片/视频检测提交、结果查询 |
|
||
| check.YidunCallback | 易盾回调接收、结果轮询 |
|
||
| check.ContentCheck | 送检调度器启停、状态查询、手动送检 |
|
||
| check.MaterialVerify | 素材校验列表/统计/人工审核/导出 |
|
||
|
||
## 构建与运行
|
||
|
||
```bash
|
||
# 构建
|
||
docker build -t cid .
|
||
|
||
# 本地运行（需 Go 1.26）
|
||
go mod download && go mod tidy
|
||
go run main.go
|
||
|
||
# 编译
|
||
go build -ldflags="-s -w" -o main ./main.go
|
||
```
|
||
|
||
配置入口为 `config.yml`（易盾凭据、callback_mode、content_check 调度参数、数据库连接等）。
|