cid/README.md

# CID服务商项目

## 项目概述

CID服务商项目是一个为企业提供CID（Click ID）服务的完整解决方案。该项目通过智能策略引擎，为不同级别的租户提供定制化的广告匹配服务，支持多广告源集成和转化率控制。

## 核心功能

### 1. 租户管理系统
- **多租户架构**: 支持多个企业租户同时使用
- **租户级别**: Basic、Standard、Premium三个级别
- **用户认证集成**: 通过common模块获取用户信息

### 2. 广告源管理
- **自营广告**: 系统内置的广告库存
- **Google Ads**: 集成Google广告平台
- **Facebook Ads**: 集成Meta广告平台
- **扩展性**: 支持添加更多广告源

### 3. 智能策略引擎
- **转化率控制**: 根据租户级别设置不同转化率范围
- **权重分配**: 为不同广告源配置权重比例
- **动态匹配**: 实时根据策略匹配最优广告

### 4. CID生成与追踪
- **唯一CID**: 为每次请求生成唯一标识
- **请求记录**: 完整的请求历史记录
- **性能统计**: 详细的性能和转化统计

## API接口

### 租户管理
- `POST /tenant/create` - 创建租户
- `PUT /tenant/update` - 更新租户
- `DELETE /tenant/delete` - 删除租户
- `GET /tenant/info` - 获取租户信息
- `GET /tenant/list` - 获取租户列表

### 广告源管理
- `POST /ad-source/create` - 创建广告源
- `PUT /ad-source/update` - 更新广告源
- `DELETE /ad-source/delete` - 删除广告源
- `GET /ad-source/info` - 获取广告源信息
- `GET /ad-source/list` - 获取广告源列表

### 策略管理
- `POST /strategy/create` - 创建策略
- `PUT /strategy/update` - 更新策略
- `DELETE /strategy/delete` - 删除策略
- `GET /strategy/info` - 获取策略信息
- `GET /strategy/list` - 获取策略列表

### CID核心服务
- `POST /cid/generate` - 生成CID广告
- `GET /cid/statistics` - 获取CID统计
- `GET /cid/history` - 获取CID历史记录

## 租户级别策略

### Basic级别
- 转化率范围: 1% - 5%
- 广告源: 仅自营广告
- 每次请求: 最多3个广告

### Standard级别
- 转化率范围: 5% - 15%
- 广告源: 自营(70%) + Google(20%) + Facebook(10%)
- 每次请求: 最多5个广告

### Premium级别
- 转化率范围: 15% - 100%
- 广告源: 自营(40%) + Google(30%) + Facebook(30%)
- 每次请求: 最多10个广告

## 项目结构

```
cid/
├── controller/          # 控制器层
│   ├── cid_controller.go
│   ├── ad_source_controller.go
│   ├── strategy_controller.go
│   └── ...
├── service/           # 服务层
│   ├── cid_service.go
│   ├── ad_source_service.go
│   ├── strategy_service.go
│   └── ...
├── dao/              # 数据访问层
│   ├── cid_request_dao.go
│   ├── ad_source_dao.go
│   ├── strategy_dao.go
│   └── ...
├── model/            # 数据模型
│   ├── entity/       # 数据库实体
│   ├── dto/          # 数据传输对象
│   └── types/        # 类型定义
├── database/         # 数据库脚本
│   └── init.sql      # 数据库初始化
├── config/           # 配置文件
│   └── config.example.yaml
└── README.md
```

## 架构说明

### 租户管理
- 租户信息不在当前项目中维护
- 通过common模块获取用户和租户信息
- 支持Basic、Standard、Premium三个级别的租户

### 广告源集成
- **自营广告**: 系统内置广告库存
- **Google Ads**: API集成
- **Facebook Ads**: API集成
- 可扩展支持更多广告源

### 策略引擎
- 基于租户级别的动态策略匹配
- 支持转化率阈值控制
- 灵活的广告源权重配置

## 使用示例

### 1. 生成CID广告
```json
POST /cid/generate
{
  "request_type": "web_banner",
  "position": "header",
  "count": 5
}

Response:
{
  "cid": "CID_1640995200000_1234",
  "ads": [
    {
      "id": 10001,
      "title": "优质产品推广",
      "description": "高质量的产品广告",
      "image_url": "https://example.com/ad.jpg",
      "target_url": "https://example.com/product",
      "conversion_rate": 0.08,
      "source": "self",
      "bid": 500
    }
  ],
  "total_ads": 1,
  "tenant_id": 1,
  "tenant_name": "示例公司",
  "generated_at": "2023-12-31 16:00:00"
}
```

### 2. 创建策略
```json
POST /strategy/create
{
  "name": "高级策略",
  "description": "高级租户专用策略",
  "tenant_level": "premium",
  "min_conversion": 0.15,
  "max_conversion": 1.0,
  "source_weights": {
    "self": 40,
    "google": 30,
    "facebook": 30
  },
  "max_ads_per_req": 10,
  "priority": 100,
  "status": "active"
}
```

## 部署说明

1. 确保数据库连接配置正确
2. 执行数据库迁移脚本
3. 配置广告源API密钥
4. 启动服务

## 扩展功能

### 添加新的广告源
1. 在`AdSource`表中添加新的广告源配置
2. 在`cid_service.go`中实现对应的广告获取方法
3. 在策略中配置相应权重

### 自定义策略
通过策略管理API创建自定义匹配策略，支持：
- 自定义转化率阈值
- 灵活的权重分配
- 动态优先级调整

## 监控与统计

系统提供完整的监控和统计功能：
- 请求量统计
- 成功率分析
- 处理时间监控
- 转化率追踪
- 广告源性能对比

## 安全特性

- 用户身份验证
- 租户数据隔离
- API访问控制
- 敏感信息加密

这个CID服务商项目为企业提供了一个完整、可扩展的广告CID解决方案，通过智能策略确保每个租户都能获得最适合其业务需求的广告服务。