docs(marketing): 新增营销图模块文档

- docs/README.md: 文档目录补充营销图模块入口 - docs/marketing/README.md: 模块概述、代码结构、数据模型、路由表、依赖说明、管理后台 - docs/marketing/API.md: 完整 API 文档（小程序端+管理后台，含请求/响应示例） Made-with: Cursor
2026-03-06 07:50:42 +00:00
parent ac49e1458c
commit 76fd425ca7
3 changed files with 352 additions and 1 deletions
@@ -0,0 +1,205 @@
+# 营销图管理 - 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
+  }
+}
+```