wx_service/docs/marketing/README.md

营销图管理模块

概述

营销图管理模块为「营销图助手」微信小程序提供后端服务，支持模板分类管理、模板 CRUD、用户下载记录和管理后台。

前端小程序仓库：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，或部署到任意静态文件服务。