nepiedg
76fd425ca7
- docs/README.md: 文档目录补充营销图模块入口 - docs/marketing/README.md: 模块概述、代码结构、数据模型、路由表、依赖说明、管理后台 - docs/marketing/API.md: 完整 API 文档（小程序端+管理后台，含请求/响应示例） Made-with: Cursor
206 lines
3.8 KiB
Markdown
206 lines
3.8 KiB
Markdown
# 营销图管理 - 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
|
||
}
|
||
}
|
||
```
|