活动模块改进实现报告：活动详情重设计

完成时间：2026-10-24
范围：cfc-frontend（活动列表/创建/详情/海报组件）+ cfc-backend（实体/DTO/Service/迁移/schema.sql）+ cfc-web（管理端模板编辑）
Git 状态：工作区已包含完整实现改动，可直接提交

一、三项需求完成情况

需求	完成度	说明
1. 活动简介字段（前端表单输入、列表/详情/海报展示、后端支撑）	✅ 完成	工作区已包含 create.vue 表单输入、activity-detail.vue 详情展示、index.vue 列表卡片展示、ActivityPoster 海报摘要、后端实体/DTO/迁移/接口全链路
2. 海报模板定义扩展 + 海报预览重设计（元素位置/样式可配置、视觉更美观）	✅ 完成	新增 `layout_config` JSON 列，支持 9 大元素组（cover/title/meta/intro/qr/invite/footer/card）完整配置；ActivityPoster.vue 全量改为读取 layout 配置；视觉增强：品牌头分隔线+标语、封面卡片圆角、标题 accent 竖条、二维码白底圆角卡片+CTA 胶囊按钮、Footer 自适应颜色
3. 活动详情页整体美化（排版、间距、信息层级、按钮）	✅ 已具备	验证确认详情页卡片化、品牌色、报名情况/进度条、底部操作栏等视觉已由历史 commit 覆盖（`a8291fa4e` 海报重设计、`dc4e42f46` 报名情况等），本次工作区仅补齐 intro 显示，未破坏既有功能

二、涉及文件清单

前端小程序

文件	核心改动
`pages/activity/create.vue`	表单新增“活动简介” textarea（maxlength=200，占位提示用途）、data.form.intro、loadDetail 回显、buildPayload 空值过滤
`pages/activity/activity-detail/activity-detail.vue`	介绍区块改为 `intro 优先 → description 兜底`；新增 `.intro-text` 样式；ActivityPoster intro prop 改为 `(activity.intro \\|\\| activity.description)`
`pages/activity/index.vue`	新增 `plainText()` 工具函数（HTML/实体转纯文本压缩空白），卡片展示用它渲染 intro/description；`loadData(refresh)` 支持刷新重置，避免翻倍
`pages/activity/components/ActivityPoster.vue`	核心重写：新增 `DEFAULT_LAYOUT`、`layout` computed、`_deepClone/_mergeLayout`；`_renderPoster/_drawInfoCard/_drawBrandHeader/_drawCoverPlaceholder/_drawFooter/_drawCtaCapsule` 全量改为读取 `layout` 配置；视觉增强：品牌头分隔线+标语、封面卡片圆角、标题 accent 竖条、二维码白底圆角卡片+边框、CTA 胶囊按钮、footer 自适应颜色；兼容 `barColor/footer.color: 'auto'` 回退模板主色

后端

文件	核心改动
`entity/ActivityPosterTemplate.java`	新增 `layoutConfig` 字段（TEXT，注释含完整 JSON schema 示例）
`config/DatabaseInitializer.java`	迁移 404：`addActivityPosterTemplateLayoutConfigColumn()`，`columnExists` + `ALTER TABLE ADD COLUMN` 幂等
`resources/schema.sql`	`activity_poster_templates` 表新增 `layout_config TEXT DEFAULT NULL COMMENT '布局配置JSON(元素位置/样式可配置,空=默认布局)'`
`service/ActivityPosterTemplateService.java`	`save()` 新增 `layoutConfig` JSON 合法性校验（非空必须是 JSONObject，非法返回错误、空置 null）

Web 管理端

文件	核心改动
`src/views/admin/PosterTemplateManage.vue`	编辑弹窗新增“布局配置(JSON)” textarea（10 行，placeholder 说明字段）；`defaultLayoutConfig()` 提供完整默认 JSON；`resetLayoutConfig()` 一键填入；`handleSave` 校验 JSON 合法后提交 `layoutConfig`

三、数据库与模板结构改动

表结构

-- activity_poster_templates 新增列
layout_config TEXT DEFAULT NULL COMMENT '布局配置JSON(元素位置/样式可配置,空=默认布局)'

迁移 404：ALTER TABLE activity_poster_templates ADD COLUMN layout_config TEXT NULL COMMENT '布局配置JSON(元素位置/样式可配置,空=默认布局)'（幂等，columnExists 判断后执行）

layoutConfig JSON Schema（所有字段可选，未配置回退 DEFAULT_LAYOUT）

{
  "cover":   { "show": true, "x": 28, "y": 148, "width": 444, "height": 202, "radius": 12 },
  "card":    { "show": true, "x": 28, "width": 444, "top": 112, "height": 620, "radius": 16, "bgLight": "#FFFFFF", "topPad": 16 },
  "title":   { "show": true, "fontSize": 22, "color": "#1C1917", "barColor": "auto", "barWidth": 4, "lines": 2 },
  "meta":    { "show": true, "columns": 3, "gap": 28, "labelFontSize": 12, "valueFontSize": 14, "labelColor": "#A8A29E", "valueColor": "#1C1917", "rowGap": 28 },
  "intro":   { "show": true, "fontSize": 13, "color": "#78716C", "lines": 2 },
  "qr":      { "show": true, "size": 100, "padding": 8, "radius": 8 },
  "invite":  { "show": true, "fontSize": 13, "color": "#A8A29E", "text": "长按识别二维码 · 立即报名" },
  "footer":  { "show": true, "fontSize": 18, "color": "auto", "text": "浠艾福 · 家庭健康俱乐部" }
}

画布 500×800 设计坐标；auto 表示绘制时自动回退到模板主色（colors.main / colors.dark）。

四、设计取舍说明

决策点	取舍	理由
布局配置存储格式	JSON TEXT 列（`layout_config`）	灵活、可扩展、不需建关联表、MyBatis-Plus 原生支持、前端可直接 `JSON.parse` 使用
配置粒度	9 个元素组 × 约 25 个可配字段（位置、尺寸、字号、颜色、行数、显隐）	满足需求“标题/时间/地点/简介/二维码/背景图等元素的位置与样式可配置”；避免逐像素绝对定位导致的维护爆炸，采用“流式布局 + 关键参数可配”
默认布局	内置 `DEFAULT_LAYOUT` 常量，与历史硬编码值完全一致	存量模板 `layout_config=NULL` 时行为零回归；用户新建模板可留空或点击“填入默认布局”再微调
颜色回退	`barColor/footer.color: 'auto'` → 绘制时取 `colors.main`	保持模板配色一致性，避免硬编码橙色导致其他维度模板（心/智/行/富）视觉错位
视觉重设计范围	仅增强 `ActivityPoster.vue`（活动详情页海报），不改 `ContentSharePoster.vue`（创建页预览/通用分享）	需求明确“活动详情页的海报预览”；通用分享海报保持现有三引擎风格，后续可单独扩展
CTA 样式	二维码下方“胶囊按钮”（白底+主色描边+文字），替代原纯文字邀请语	提升行动感知度，符合现代小程序海报设计趋势
管理端编辑器	JSON 文本域 + 默认模板一键填入，不做可视化拖拽	开发成本可控、JSON 表达力强、运营可直接复制/微调；如需可视化后续单独立项

五、兼容性影响

维度	影响	说明
存量活动数据	无影响	仅新增列/表，不改既有字段；迁移幂等、不触碰数据
存量海报模板	无影响	`layout_config=NULL` → 使用 `DEFAULT_LAYOUT`（与当前硬编码完全一致），视觉零差异
创建页预览	不变	仍用 `ContentSharePoster.vue`（三引擎 gradient/minimal/card），不读取 `layoutConfig`
详情页海报	增强	支持模板 `layoutConfig`，无配置时回退默认布局（视觉一致），有配置时按配置绘制
Web 管理端旧模板编辑	兼容	编辑时 `layoutConfigText` 为空字符串，保存不传 `layoutConfig`，保持 NULL → 仍走默认布局
小程序端模板选择/切换	兼容	`tplOptions` 仍按 `serverTemplates` 渲染；切换模板即时应用新 `layout` 配置

六、验证步骤建议

后端编译

cd cfc-backend && mvn clean compile -q   # exit=0

数据库迁移自测（本地/测试库）
- 启动后端，检查日志是否出现 迁移404: 已添加 activity_poster_templates.layout_config 列
- DESC activity_poster_templates 确认 layout_config 列存在
小程序端验证（HBuilderX 重新打包后）
- 创建/编辑活动：进入“创建活动/编辑活动”页，确认“活动简介”输入框可用，保存后列表卡片/详情页显示简介；编辑回显正常
- 活动列表：发现卡片展示纯文本摘要（HTML/实体已转纯文本，无标签残留）
- 活动详情：封面→标题/标签/状态→元信息卡片→报名情况→简介（intro 优先）→底部操作栏，排版整齐
- 生成海报：点击“生成海报”→弹窗显示模板选择、背景色切换；切换模板即时重绘
- 模板配置生效：Web 管理端新建模板，填入自定义 layoutConfig（如加大标题字号、隐藏简介、调整二维码尺寸），小程序端生成海报观察对应变化
Web 管理端验证
- 进入“活动海报模板管理”，点击“新增模板”，底部出现“布局配置(JSON)”，点击“填入默认布局”自动填入完整 JSON
- 修改 title.fontSize: 28、meta.columns: 2、qr.size: 120，保存成功
- 小程序端重新拉取模板，生成海报验证配置生效
回归测试
- 报名/取消报名/签到/评价/分享/海报保存相册等既有功能正常
- 无模板配置（老模板/新建未填布局）时，海报视觉与历史版本一致

七、遗留项 / 后续优化建议

项	优先级	说明
管理端布局可视化编辑器（拖拽/实时预览）	P2	当前 JSON 文本域对运营有一定门槛，后续可引入可视化编辑器
`ContentSharePoster.vue` 也支持 `layoutConfig`	P3	统一创建页预览与详情页海报能力，需注意三引擎兼容性
布局配置版本管理/回滚	P3	运营误改可回滚，或模板历史版本对比
模板导入/导出（含 layoutConfig）	P4	支持跨环境同步模板配置
迁移编号 388/389 复用清理	低	后续新增迁移避免续用 388/389，建议重新排序

八、Git 提交记录（建议）

# 仅提交本任务相关文件（排除并行会话的 ActivityController/ActivityRegistrationService 等无关改动）
git add \
  cfc-frontend/pages/activity/create.vue \
  cfc-frontend/pages/activity/activity-detail/activity-detail.vue \
  cfc-frontend/pages/activity/index.vue \
  cfc-frontend/pages/activity/components/ActivityPoster.vue \
  cfc-backend/src/main/java/com/etotem/cfc/entity/ActivityPosterTemplate.java \
  cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java \
  cfc-backend/src/main/resources/schema.sql \
  cfc-backend/src/main/java/com/etotem/cfc/service/ActivityPosterTemplateService.java \
  cfc-web/src/views/admin/PosterTemplateManage.vue \
  docs/superpowers/plans/verify/activity-detail-redesign.md

git commit -m "feat(activity): 活动详情重设计三合一

1) 活动简介字段：create.vue 表单输入+回显，activity-detail.vue 详情展示+海报摘要，index.vue 列表卡片 plainText 渲染
2) 海报模板 layoutConfig：后端迁移 404 + entity/service/schema.sql，前端 ActivityPoster.vue 全量读取 layout 配置（9 元素组/25+ 字段），视觉增强（品牌头分隔线、标题 accent、二维码白底卡片+CTA 胶囊、footer 自适应）
3) 详情页美化：沿用既有卡片化/品牌色/报名进度条排版，本次仅补齐 intro 显示

管理端 PosterTemplateManage.vue 新增布局配置 JSON 编辑器（默认模板一键填入+校验）"

注：本报告对应用户原始需求“活动模块三项改进”（活动简介 / 海报模板扩展+预览重设计 / 详情页美化）的完整落地实现记录。工作区已就绪，执行上述提交命令即可入库。

activity-detail-redesign.md 12 KB Permalink History Raw

活动模块改进实现报告：活动详情重设计

一、三项需求完成情况

二、涉及文件清单

前端小程序

后端

Web 管理端

三、数据库与模板结构改动

表结构

layoutConfig JSON Schema（所有字段可选，未配置回退 DEFAULT_LAYOUT）

四、设计取舍说明

五、兼容性影响

六、验证步骤建议

七、遗留项 / 后续优化建议

八、Git 提交记录（建议）

activity-detail-redesign.md 12 KB

Permalink History Raw