# 营销图管理模块

## 概述

营销图管理模块为「营销图助手」微信小程序提供后端服务，支持模板分类管理、模板 CRUD、用户下载记录和管理后台。

前端小程序仓库：[hello-dd-code/marketing](https://github.com/hello-dd-code/marketing)

## 功能

- **分类管理**：营销图模板分类的增删改查、排序、启用/禁用
- **模板管理**：模板的增删改查、图片URL、缩略图、尺寸、排序、启用/禁用
- **下载记录**：记录用户下载的模板、Logo CDN URL、Logo 位置信息、广告完成状态
- **下载统计**：总下载次数、今日下载次数
- **Web 管理后台**：单页面 Vue3 + Element Plus 管理界面

## 代码结构

```
internal/marketing/
├── model/
│   ├── category.go              # MarketingCategory 分类模型
│   ├── template.go              # MarketingTemplate 模板模型
│   └── download.go              # MarketingDownload 下载记录模型
├── repository/
│   ├── category_repo.go         # 分类数据访问（CRUD + 关联查询）
│   ├── template_repo.go         # 模板数据访问（CRUD + 分页 + 下载计数）
│   └── download_repo.go         # 下载记录数据访问（创建 + 列表 + 统计）
├── service/
│   ├── category_service.go      # 分类业务逻辑（验证 + 删除保护）
│   ├── template_service.go      # 模板业务逻辑（验证 + CRUD）
│   └── download_service.go      # 下载业务逻辑（创建 + 广告回调 + 错误分类）
├── handler/
│   ├── category_handler.go      # 分类 HTTP 处理（公开 + Admin）
│   ├── template_handler.go      # 模板 HTTP 处理（公开 + Admin）
│   ├── download_handler.go      # 下载/广告回调/统计 HTTP 处理
│   └── admin_middleware.go      # Admin Token 鉴权中间件

internal/routes/
└── marketing_routes.go          # 路由注册（公开/登录/Admin 三组）

web/marketing/
└── index.html                   # Web 管理后台（Vue3 + Element Plus CDN）
```

## 数据模型

### marketing_categories

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint (PK) | 主键 |
| name | varchar(50) | 分类名称 |
| sort_order | int | 排序权重（越大越靠前） |
| icon | varchar(500) | 图标 URL |
| status | int | 状态（1=启用, 0=禁用） |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### marketing_templates

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint (PK) | 主键 |
| category_id | uint (FK) | 所属分类 ID |
| title | varchar(100) | 模板名称 |
| image_url | varchar(500) | 模板图片 URL |
| thumbnail_url | varchar(500) | 缩略图 URL |
| width | int | 图片宽度 px |
| height | int | 图片高度 px |
| sort_order | int | 排序权重 |
| status | int | 状态（1=启用, 0=禁用） |
| download_count | int | 下载次数（自动递增） |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### marketing_user_downloads

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint (PK) | 主键 |
| user_id | uint (FK) | 用户 ID |
| template_id | uint (FK) | 模板 ID |
| logo_url | varchar(500) | 用户 Logo CDN 地址 |
| logo_x | double | Logo X 坐标（相对比例 0~1） |
| logo_y | double | Logo Y 坐标（相对比例 0~1） |
| logo_w | double | Logo 宽度（相对比例 0~1） |
| logo_h | double | Logo 高度（相对比例 0~1） |
| ad_completed | bool | 是否已观看广告 |
| created_at | datetime | 创建时间 |

## 路由

### 公开接口（无需登录）

| 方法 | 路径 | Handler | 说明 |
|------|------|---------|------|
| GET | `/api/v1/marketing/categories` | CategoryHandler.ListEnabled | 获取启用的分类列表 |
| GET | `/api/v1/marketing/templates` | TemplateHandler.ListEnabled | 模板列表（分页、分类筛选） |
| GET | `/api/v1/marketing/templates/:id` | TemplateHandler.GetDetail | 模板详情 |

### 需登录接口（Bearer Token）

| 方法 | 路径 | Handler | 说明 |
|------|------|---------|------|
| POST | `/api/v1/marketing/downloads` | DownloadHandler.Create | 创建下载记录 |
| POST | `/api/v1/marketing/ad_callback` | DownloadHandler.AdCallback | 广告完成回调 |
| GET | `/api/v1/marketing/downloads` | DownloadHandler.ListByUser | 我的下载历史 |

### 管理后台接口（X-Admin-Token）

| 方法 | 路径 | Handler | 说明 |
|------|------|---------|------|
| GET | `/api/v1/admin/marketing/categories` | CategoryHandler.AdminList | 分类列表（含禁用） |
| POST | `/api/v1/admin/marketing/categories` | CategoryHandler.AdminCreate | 创建分类 |
| PUT | `/api/v1/admin/marketing/categories/:id` | CategoryHandler.AdminUpdate | 更新分类 |
| DELETE | `/api/v1/admin/marketing/categories/:id` | CategoryHandler.AdminDelete | 删除分类 |
| GET | `/api/v1/admin/marketing/templates` | TemplateHandler.AdminList | 模板列表（含禁用） |
| POST | `/api/v1/admin/marketing/templates` | TemplateHandler.AdminCreate | 创建模板 |
| PUT | `/api/v1/admin/marketing/templates/:id` | TemplateHandler.AdminUpdate | 更新模板 |
| DELETE | `/api/v1/admin/marketing/templates/:id` | TemplateHandler.AdminDelete | 删除模板 |
| GET | `/api/v1/admin/marketing/stats` | DownloadHandler.AdminStats | 下载统计 |

## 依赖的公共服务

- **鉴权**：复用 `middleware.AuthMiddleware` + `middleware.RequireUserMiddleware`
- **七牛上传**：模板图片和用户 Logo 均通过七牛直传，复用 `common/qiniu` 模块
- **Admin Token**：通过 `X-Admin-Token` 请求头鉴权，Token 来自 `.env` 的 `ADMIN_API_TOKEN`

## Web 管理后台

位于 `web/marketing/index.html`，单文件 HTML，通过 CDN 加载 Vue 3 和 Element Plus。

功能：
- 登录：输入 API 地址 + Admin Token
- 分类管理：增删改查、排序、启用/禁用
- 模板管理：增删改查、图片预览、排序、启用/禁用、分类筛选
- 数据概览：分类总数、模板总数、总下载次数、今日下载数

使用方式：浏览器直接打开 `index.html`，或部署到任意静态文件服务。