# 营销图管理 - API 文档

## 公共说明

- 基础路径：`/api/v1`
- 鉴权方式：`Authorization: Bearer <session_key>`
- 管理后台鉴权：`X-Admin-Token: <admin_token>`
- 响应格式：`{ "code": 200, "message": "success", "data": ... }`

---

## 小程序端接口

### GET /marketing/categories

获取启用的分类列表（按 sort_order DESC 排序）。

**无需登录**

**响应示例：**

```json
{
  "code": 200,
  "message": "success",
  "data": [
    { "id": 1, "name": "节日海报", "sort_order": 10, "icon": "https://cdn.example.com/icon1.png", "status": 1 }
  ]
}
```

### GET /marketing/templates

获取模板列表（仅启用状态，按 sort_order DESC 排序）。

**无需登录**

**Query 参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | uint | 否 | 按分类筛选 |
| page | int | 否 | 页码（默认 1） |
| page_size | int | 否 | 每页数量（默认 20，最大 100） |

**响应示例：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "templates": [
      {
        "id": 1,
        "category_id": 1,
        "title": "春节促销",
        "image_url": "https://cdn.example.com/tpl1.jpg",
        "thumbnail_url": "https://cdn.example.com/tpl1_thumb.jpg",
        "width": 1080,
        "height": 1920,
        "sort_order": 10,
        "status": 1,
        "download_count": 42,
        "category": { "id": 1, "name": "节日海报" }
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

### GET /marketing/templates/:id

获取模板详情。

**无需登录**

### POST /marketing/downloads

创建下载记录。**需登录**。

**请求体：**

```json
{
  "template_id": 1,
  "logo_url": "https://cdn.example.com/user_logo.png",
  "logo_x": 0.35,
  "logo_y": 0.80,
  "logo_w": 0.30,
  "logo_h": 0.10
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| template_id | uint | 模板 ID（必填） |
| logo_url | string | 用户 Logo CDN 地址 |
| logo_x/logo_y | float | Logo 位置（相对比例 0~1） |
| logo_w/logo_h | float | Logo 大小（相对比例 0~1） |

**响应**：返回创建的下载记录对象（含 `id`）。

### POST /marketing/ad_callback

标记广告已完成。**需登录**。

**请求体：**

```json
{
  "download_id": 1
}
```

### GET /marketing/downloads

获取当前用户的下载历史。**需登录**。

**Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| page | int | 页码（默认 1） |
| page_size | int | 每页数量（默认 20） |

---

## 管理后台接口

所有管理后台接口需要 `X-Admin-Token` 请求头。

### GET /admin/marketing/categories

获取所有分类（含禁用状态）。

### POST /admin/marketing/categories

创建分类。

```json
{
  "name": "节日海报",
  "icon": "https://cdn.example.com/icon.png",
  "sort_order": 10,
  "status": 1
}
```

### PUT /admin/marketing/categories/:id

更新分类（请求体同创建）。

### DELETE /admin/marketing/categories/:id

删除分类（分类下有模板时返回 400 错误）。

### GET /admin/marketing/templates

获取所有模板（含禁用状态，支持 `category_id`、`page`、`page_size` 参数）。

### POST /admin/marketing/templates

创建模板。

```json
{
  "category_id": 1,
  "title": "春节促销",
  "image_url": "https://cdn.example.com/tpl.jpg",
  "thumbnail_url": "https://cdn.example.com/tpl_thumb.jpg",
  "width": 1080,
  "height": 1920,
  "sort_order": 10,
  "status": 1
}
```

### PUT /admin/marketing/templates/:id

更新模板（请求体同创建）。

### DELETE /admin/marketing/templates/:id

删除模板。

### GET /admin/marketing/stats

获取下载统计。

**响应示例：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "TotalDownloads": 1234,
    "TodayDownloads": 56
  }
}
```