# 活动模块改进实现报告:活动详情重设计 > 完成时间: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` | --- ## 三、数据库与模板结构改动 ### 表结构 ```sql -- 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) ```json { "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` 配置 | --- ## 六、验证步骤建议 1. **后端编译** ```bash cd cfc-backend && mvn clean compile -q # exit=0 ``` 2. **数据库迁移自测**(本地/测试库) - 启动后端,检查日志是否出现 `迁移404: 已添加 activity_poster_templates.layout_config 列` - `DESC activity_poster_templates` 确认 `layout_config` 列存在 3. **小程序端验证(HBuilderX 重新打包后)** - **创建/编辑活动**:进入“创建活动/编辑活动”页,确认“活动简介”输入框可用,保存后列表卡片/详情页显示简介;编辑回显正常 - **活动列表**:发现卡片展示纯文本摘要(HTML/实体已转纯文本,无标签残留) - **活动详情**:封面→标题/标签/状态→元信息卡片→报名情况→简介(intro 优先)→底部操作栏,排版整齐 - **生成海报**:点击“生成海报”→弹窗显示模板选择、背景色切换;切换模板即时重绘 - **模板配置生效**:Web 管理端新建模板,填入自定义 `layoutConfig`(如加大标题字号、隐藏简介、调整二维码尺寸),小程序端生成海报观察对应变化 4. **Web 管理端验证** - 进入“活动海报模板管理”,点击“新增模板”,底部出现“布局配置(JSON)”,点击“填入默认布局”自动填入完整 JSON - 修改 `title.fontSize: 28`、`meta.columns: 2`、`qr.size: 120`,保存成功 - 小程序端重新拉取模板,生成海报验证配置生效 5. **回归测试** - 报名/取消报名/签到/评价/分享/海报保存相册等既有功能正常 - 无模板配置(老模板/新建未填布局)时,海报视觉与历史版本一致 --- ## 七、遗留项 / 后续优化建议 | 项 | 优先级 | 说明 | |----|--------|------| | 管理端布局可视化编辑器(拖拽/实时预览) | P2 | 当前 JSON 文本域对运营有一定门槛,后续可引入可视化编辑器 | | `ContentSharePoster.vue` 也支持 `layoutConfig` | P3 | 统一创建页预览与详情页海报能力,需注意三引擎兼容性 | | 布局配置版本管理/回滚 | P3 | 运营误改可回滚,或模板历史版本对比 | | 模板导入/导出(含 layoutConfig) | P4 | 支持跨环境同步模板配置 | | 迁移编号 388/389 复用清理 | 低 | 后续新增迁移避免续用 388/389,建议重新排序 | --- ## 八、Git 提交记录(建议) ```bash # 仅提交本任务相关文件(排除并行会话的 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 编辑器(默认模板一键填入+校验)" ``` --- > **注**:本报告对应用户原始需求“活动模块三项改进”(活动简介 / 海报模板扩展+预览重设计 / 详情页美化)的完整落地实现记录。工作区已就绪,执行上述提交命令即可入库。