admin/wx_service
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
- docs/README.md: 文档目录补充营销图模块入口
- docs/marketing/README.md: 模块概述、代码结构、数据模型、路由表、依赖说明、管理后台
- docs/marketing/API.md: 完整 API 文档（小程序端+管理后台，含请求/响应示例）

Made-with: Cursor
This commit is contained in:
nepiedg
2026-03-06 07:50:42 +00:00
parent ac49e1458c
commit 76fd425ca7
3 changed files with 352 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+7 -1
View File
@@ -21,6 +21,12 @@
- `docs/smoke/README.md`
- `docs/smoke/API.md`
## 营销图管理小程序
- `docs/marketing/README.md`
- `docs/marketing/API.md`
- 前端仓库：[hello-dd-code/marketing](https://github.com/hello-dd-code/marketing)
## 律师信息上报接口
- `docs/lawyer/README.md`
@@ -44,7 +50,7 @@ go run ./cmd/api
启动流程：
1. 加载 `.env`。
2. 初始化数据库连接（参见 `internal/database/database.go`）。
3. 自动迁移相关数据表（用户表、去水印日志表、戒烟记录表等）。
3. 自动迁移相关数据表（用户表、去水印日志表、戒烟记录表、营销图表等）。
4. 注册路由并启动 Gin HTTP 服务。
## 数据表
docs/marketing/API.md
+205
View File
@@ -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
}
}
```
docs/marketing/README.md
+140
View File
@@ -0,0 +1,140 @@
# 营销图管理模块
## 概述
营销图管理模块为「营销图助手」微信小程序提供后端服务，支持模板分类管理、模板 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`，或部署到任意静态文件服务。