# Web 管理端定义活动海报模板

**日期**: 2026-10-17
**状态**: 已实现（迁移381）
**关联**: 活动海报生成（`cfc-frontend/components/ContentSharePoster.vue`）、活动分享注册链路（`2026-10-07-activity-share-referral-design.md`）

---

## 需求概述

活动详情页「生成海报」此前使用**前端写死**的三套模板（渐变/深色/卡片）与内置配色，运营无法调整海报样式。
本次改造为：

> 作为平台运营，我想在 Web 管理端定义海报模板（名称、类型、配色、二维码尺寸、排序、启停），
> 以便小程序端「生成海报」弹窗展示我配置的模板，用户点选后按我的设计渲染画布。

---

## 方案设计

### 数据模型：`activity_poster_templates`（迁移381）

| 字段 | 说明 |
|------|------|
| `name` | 模板名称（管理端与小程序端展示名，唯一） |
| `template_key` | 绘制引擎：`gradient`（渐变）/ `minimal`（深色）/ `card`（白底卡片）——必须与小程序现有引擎匹配 |
| `main_color` / `dark_color` / `light_color` | 主色/深色/浅色（渐变起点/渐变终点/内容卡背景） |
| `bg_colors` | 可选背景色板 JSON 数组（渐变模板下用户可切换） |
| `qr_size` | 二维码尺寸（rpx，活动海报建议 100） |
| `sort_order` | 排序，越小越前 |
| `status` | 1 启用 / 0 停用（停用后小程序不展示） |

迁移同时**种子 3 套默认模板**（暖橙渐变 / 深色极简 / 白色卡片），与原有前端内置三套等价，保证行为连续。

### 后端接口

| 接口 | 方法 | 权限 | 说明 |
|------|------|------|------|
| `/api/admin/poster-template/list` | POST | admin / operator | 模板列表（含停用） |
| `/api/admin/poster-template/save` | POST | admin / operator | 新增/更新（name 唯一、templateKey 白名单、色板 JSON 校验、默认值兜底） |
| `/api/admin/poster-template/delete` | POST | admin / operator | 删除 |
| `/api/poster-template/list` | POST | 登录（生成海报场景） | 小程序端可用模板（status=1） |

### Web 管理端（cfc-web）

- 页面 `views/admin/PosterTemplateManage.vue`：列表（名称/类型/配色预览/二维码尺寸/排序/状态）+ 编辑弹窗（el-color-picker 三色 + 动态色板 + 数量/排序/启停）
- 路由：`poster-template-manage`（`perm: activity:poster_template`）
- 菜单：活动管理分组下「海报模板管理」
- API 封装：`api/posterTemplate.js`

### 小程序端（cfc-frontend）

- `ContentSharePoster.vue` 新增 `templates` prop：配置了模板时渲染管理端模板列表（默认选第一个，emit 同步 template/bgColor），模板 `qrSize` 优先于 `qrSizeOverride`；**未配置任何模板时隐藏模板/背景色选择行**（与 `4cdc515d7` 移除硬编码选择行的决策保持一致，海报仍按默认 gradient 引擎绘制）
- `activity-detail.vue` `generatePoster()` 拉取 `/api/poster-template/list`（接口失败时 `posterTemplates=[]`，不阻塞海报生成）
- `utils/api.js` 新增 `getPosterTemplates()`

---

## 验收标准

- [x] 管理端可对模板增删改查，配色带可视化色块预览
- [x] 小程序端海报弹窗展示管理端配置的模板列表，点选实时重绘
- [x] 管理端停用模板后小程序不再展示该模板
- [x] 管理端无任何模板时（如全删），小程序隐藏选择行、按默认引擎出图，海报功能不白屏
- [x] `mvn clean compile` 通过；改动 .vue 文件 script 语法校验通过

## 兼容性说明

- 商品/文章/个人中心海报未传 `templates`（`serverTemplates` 为空），不渲染选择行，零影响
- 迁移381 幂等（CREATE TABLE IF NOT EXISTS + INSERT IGNORE 按名称去重），重复执行无副作用