wx_service/docs/marketing/API.md

营销图管理 - API 文档

公共说明

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

---

小程序端接口

GET /marketing/categories

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

无需登录

响应示例：

{
  "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）

响应示例：

{
  "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

创建下载记录。需登录。

请求体：

{
  "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

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

请求体：

{
  "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

创建分类。

{
  "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

创建模板。

{
  "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

获取下载统计。

响应示例：

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