nepiedg
1eab1b99c1
- Rename all QINIU_* config/code/docs to OSS_* to match actual Alibaba Cloud OSS - Refactor upload module from internal/common/qiniu to internal/common/upload - Add backend proxy upload endpoint (POST /api/admin/marketing/upload) to avoid CORS - Auto-generate compressed thumbnail (800px, JPEG 80%) on admin image upload - Add dev-login endpoint (POST /api/v1/auth/dev-login) for H5 debugging - Add imageutil package for server-side image resizing Made-with: Cursor
141 lines
6.1 KiB
Markdown
141 lines
6.1 KiB
Markdown
# 营销图管理模块
|
||
|
||
## 概述
|
||
|
||
营销图管理模块为「营销图助手」微信小程序提供后端服务，支持模板分类管理、模板 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`
|
||
- **OSS 上传**：模板图片和用户 Logo 均通过阿里云 OSS 直传，复用 `common/upload` 模块
|
||
- **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`，或部署到任意静态文件服务。
|