gym-manage/docs/plans/2026-03-07-ui-customization-design.md

# UI模版定制功能设计文档

> 文档编号: GYM-PLAN-UI-CUSTOMIZATION-001  
> 版本: v1.0  
> 日期: 2026-03-07  
> 作者: 张翔  
> 状态: 完成

---

## 文档修订历史

| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-07 | 张翔 | 初稿 |

---

## 一、功能概述

UI模版定制功能允许租户通过配置界面定制自己的品牌展示和界面布局，包括管理后台和会员端小程序。功能分为三个层次：

**品牌定制层**：租户可以上传自己的Logo、品牌主色调、辅助色、背景图、品牌名称等基础品牌元素，系统会自动应用这些元素到所有界面，确保品牌一致性。

**布局调整层**：租户可以调整页面模块的显示顺序、隐藏不需要的功能模块、自定义首页布局（如选择轮播图、快捷入口的排列方式），以及调整导航菜单的结构。

**预设模板层**：系统提供3-5个精心设计的预设模板，覆盖不同风格（简约白、运动活力、科技蓝、高端黑等），租户可以直接选择模板，然后在模板基础上进行品牌和布局的微调，快速完成定制。

---

## 二、架构设计

UI模版定制功能采用三层架构，确保配置的灵活性和系统的稳定性：

**配置存储层**：使用JSON格式存储租户的UI配置，包括品牌元素（Logo URL、颜色值、背景图）、布局设置（模块顺序、隐藏模块、首页布局类型）、模板选择（模板ID、自定义CSS覆盖）。配置按租户ID隔离，支持版本管理，允许租户切换回历史配置。

**渲染引擎层**：前端渲染引擎在加载页面时，根据当前租户ID读取对应的UI配置，动态生成CSS变量和页面结构。对于小程序端，使用微信小程序的自定义组件能力；对于管理后台，使用Vue/React的动态样式绑定。渲染引擎支持配置热更新，无需重新部署即可生效。

**模板管理层**：预设模板存储为独立的配置包，包含完整的布局结构、组件配置和默认样式。模板支持继承机制，租户选择模板后，可以覆盖模板的特定配置项而不影响其他部分。模板管理支持版本控制和灰度发布，确保模板更新的稳定性。

---

## 三、数据模型设计

UI模版定制功能需要以下核心数据表来支撑：

**租户UI配置表（tenant_ui_config）**：存储每个租户的UI定制配置，包含租户ID、模板ID、品牌配置（Logo URL、主色调、辅助色、背景图URL）、布局配置（模块顺序JSON、隐藏模块列表、首页布局类型）、自定义CSS、配置版本号、创建时间、更新时间。支持按租户ID快速查询配置。

**预设模板表（ui_template）**：存储系统提供的预设模板，包含模板ID、模板名称、模板类型（简约/运动/科技/高端）、模板描述、预览图URL、默认配置JSON、模板状态（启用/禁用）、排序权重。支持按类型和状态查询可用模板。

**配置历史表（ui_config_history）**：记录租户的配置变更历史，包含历史ID、租户ID、旧配置JSON、新配置JSON、变更原因、操作人、变更时间。支持按租户ID和时间范围查询历史，支持配置回滚。

**资源文件表（ui_resource）**：存储租户上传的品牌资源文件，包含资源ID、租户ID、资源类型（Logo/背景图/其他）、文件URL、文件大小、上传时间、状态。支持资源管理和清理。

---

## 四、核心功能设计

UI模版定制功能分为三个核心模块：

**品牌定制模块**：提供租户上传Logo（支持PNG/JPG格式，限制2MB以内）、设置品牌主色调和辅助色（提供颜色选择器和预设色板）、上传背景图（支持轮播背景）、设置品牌名称和Slogan。支持实时预览，租户在配置时可以立即看到效果。Logo上传后自动生成多种尺寸的缩略图，适配不同设备。

**布局调整模块**：提供拖拽式界面调整模块显示顺序，支持隐藏不需要的功能模块（如小型工作室可能不需要私教模块），自定义首页布局（选择卡片式、列表式、轮播式），调整导航菜单结构（添加自定义菜单项、修改菜单名称）。布局调整支持按角色区分，店长和前台可以看到不同的菜单结构。

**模板管理模块**：提供模板预览和选择界面，展示3-5个预设模板的缩略图和描述，支持一键应用模板。模板应用后保留租户已有的品牌配置，只更新布局结构。支持模板收藏和对比功能，租户可以收藏喜欢的模板进行快速切换。模板切换支持预览模式，租户可以在正式应用前预览效果。

---

## 五、可视化配置器设计

### 5.1 配置器架构

可视化配置器采用组件化架构，分为三个核心区域：

**品牌配置区**：左侧面板提供品牌元素的上传和设置，包括Logo上传组件（支持拖拽上传、实时预览、自动裁剪）、颜色选择器组件（提供色板、自定义颜色、RGB/HEX输入）、背景图上传组件（支持多图上传、轮播设置）、品牌信息输入（品牌名称、Slogan）。所有组件都支持实时预览，配置立即反映在右侧预览区。

**布局配置区**：中间面板提供布局调整功能，包括模块顺序组件（拖拽排序、分组管理、搜索过滤）、模块开关组件（开关控制、批量操作、保存提示）、首页布局组件（布局类型选择、快捷入口配置、轮播图设置）、导航菜单组件（菜单树形展示、添加/编辑/删除、图标选择）。布局调整支持撤销/重做，防止误操作。

**模板选择区**：右侧面板提供模板浏览和选择功能，包括模板网格组件（缩略图展示、类型筛选、收藏标记）、模板详情组件（大图预览、功能说明、一键应用）、模板对比组件（并排对比、差异高亮、切换建议）。模板选择支持快速切换，无需重新配置品牌元素。

### 5.2 交互设计

**拖拽交互**：模块顺序调整使用原生HTML5拖拽API，提供视觉反馈（拖拽时高亮、放置时动画、冲突时提示）。拖拽支持跨区域移动，可以隐藏的模块拖到显示区域，或反之。拖拽过程中显示放置指示器，明确可放置位置。

**实时预览**：所有配置变更都实时反映在预览区，包括Logo更换、颜色调整、布局变更、模板切换。预览区模拟真实页面结构，展示不同设备尺寸（手机、平板、桌面）的效果。预览支持全屏模式，方便查看整体效果。

**智能提示**：配置器提供上下文相关的提示和建议，包括品牌一致性提示（颜色搭配建议、Logo尺寸建议）、布局优化提示（模块分组建议、隐藏建议）、模板推荐提示（根据行业推荐模板）。提示以气泡形式展示，点击可展开详细说明。

**快捷操作**：提供常用操作的快捷入口，包括一键重置（恢复默认配置）、一键预览（全屏预览）、一键保存（保存配置）、一键发布（发布配置到生产环境）。快捷操作支持键盘快捷键，提升操作效率。

### 5.3 配置器组件

**Logo上传组件**：
- 支持拖拽上传和点击上传
- 实时预览Logo效果
- 自动生成多种尺寸缩略图
- 支持Logo裁剪和旋转
- 提供Logo尺寸建议和最佳实践提示

**颜色选择器组件**：
- 提供预设色板（包含流行配色方案）
- 支持自定义颜色输入（RGB/HEX格式）
- 实时显示颜色对比效果
- 支持颜色历史记录（最近使用的颜色）
- 提供颜色搭配建议（基于色彩理论）

**模块顺序组件**：
- 拖拽式排序界面
- 支持模块分组管理
- 提供搜索和过滤功能
- 支持批量操作（全选、反选、批量隐藏）
- 显示模块依赖关系提示

**模板选择组件**：
- 网格式模板展示（响应式布局）
- 支持模板类型筛选（简约/运动/科技/高端）
- 显示模板缩略图和预览图
- 支持模板收藏和快速切换
- 提供模板应用前的确认对话框

### 5.4 配置器技术实现

**前端技术栈**：
- 框架：Vue 3 / React 18
- 拖拽库：Vue Draggable / React DnD
- 颜色选择器：vue-color-picker / react-color
- 预览组件：iframe沙箱或虚拟DOM渲染
- 状态管理：Pinia / Redux

**配置器状态管理**：
- 使用响应式状态存储当前配置
- 配置变更自动触发预览更新
- 支持配置快照和恢复
- 实现撤销/重做功能栈

**预览渲染机制**：
- 使用虚拟DOM模拟页面渲染
- 注入CSS变量和布局配置
- 支持多设备尺寸预览切换
- 预览更新使用防抖优化性能

**配置导出功能**：
- 支持导出当前配置为JSON文件
- 支持导入配置文件恢复配置
- 导出配置包含版本信息和元数据
- 支持配置分享和备份

---

## 六、数据流设计

UI模版定制功能的数据流分为三个主要流程：

**配置保存流程**：租户在管理后台进行UI定制操作，前端实时预览效果，点击保存时，前端将配置JSON发送到后端API，后端验证配置格式和合法性，生成新的配置版本号，保存到租户UI配置表，同时记录到配置历史表，返回成功响应。前端收到成功响应后更新本地缓存，确保配置立即生效。

**配置加载流程**：用户访问小程序或管理后台时，前端首先从本地缓存读取租户UI配置，如果缓存不存在或已过期，则调用后端API获取最新配置，后端根据租户ID查询配置，返回配置JSON，前端解析配置并应用CSS变量和布局结构，渲染页面。配置加载失败时使用默认配置，确保系统可用性。

**模板切换流程**：租户选择预设模板时，前端调用模板API获取模板详情，展示模板预览，确认应用后，前端将模板ID和租户品牌配置发送到后端，后端合并模板的默认配置和租户的品牌配置，保存到租户UI配置表，记录配置历史，返回成功响应。前端重新加载配置并刷新页面展示。

---

## 六、错误处理和边界情况

UI模版定制功能需要考虑以下错误处理和边界情况：

**配置验证错误**：租户上传的Logo文件格式不支持或大小超限时，前端实时验证并提示错误信息；颜色值格式不正确时，前端颜色选择器限制输入范围；配置JSON格式错误时，后端返回详细的错误位置和建议。所有错误都提供友好的错误提示和修复建议。

**资源上传失败**：Logo或背景图上传失败时（网络错误、服务器错误），前端显示重试按钮，支持断点续传；上传成功但处理失败时，后端记录错误日志并通知管理员，前端显示"上传成功但处理中，请稍后查看"的提示。

**配置回滚失败**：租户尝试回滚到历史配置时，如果历史配置已不存在或数据损坏，后端返回错误并提示"该历史配置不可用，请选择其他版本"，同时保留当前配置不变，避免租户丢失现有配置。

**模板应用冲突**：租户应用新模板时，如果模板已被禁用或不存在，后端返回错误并提示"该模板不可用，请选择其他模板"；如果模板配置与租户当前品牌配置冲突，后端尝试自动合并，无法合并时提示"模板应用失败，请调整品牌配置后重试"。

**缓存失效**：前端缓存失效或配置加载失败时，自动降级到默认配置，记录错误日志，同时显示"使用默认样式，配置加载中"的提示，后台静默重试加载配置，成功后自动刷新页面。

---

## 七、测试设计

UI模版定制功能需要以下测试用例来确保质量：

**品牌定制测试**：验证Logo上传（支持格式、大小限制、缩略图生成）、颜色设置（颜色选择器准确性、色板应用、实时预览）、背景图上传（轮播背景、响应式适配）、品牌元素应用（所有页面一致性、缓存更新）。测试覆盖正常流程和异常情况（文件过大、格式不支持）。

**布局调整测试**：验证模块顺序调整（拖拽功能、保存生效、缓存更新）、模块隐藏（隐藏后不显示、数据安全）、首页布局（不同布局类型渲染、响应式适配）、导航菜单（自定义菜单、角色区分）。测试覆盖不同角色（店长、前台、会员）的布局差异。

**模板管理测试**：验证模板选择（模板加载、预览展示、一键应用）、模板切换（配置合并、品牌保留、历史记录）、模板收藏（收藏功能、快速切换）、模板预览（预览模式、正式应用）。测试覆盖所有预设模板（3-5个）的兼容性。

**配置历史测试**：验证配置保存（版本号生成、历史记录）、配置回滚（历史版本恢复、数据完整性）、配置对比（新旧配置差异、变更原因）。测试覆盖多次配置变更和回滚场景。

**性能测试**：验证配置加载速度（首次加载、缓存命中）、预览响应时间（实时预览延迟）、资源加载（Logo、背景图加载速度）、并发配置（多租户同时配置）。确保定制功能不影响系统整体性能。

---

## 八、实施建议

### 8.1 开发优先级

**P0（必须实现）**：
- 可视化配置器核心功能（品牌配置区、布局配置区、模板选择区）
- 品牌定制基础功能（Logo上传、颜色设置）
- 布局调整基础功能（模块顺序、模块隐藏）
- 配置保存和加载机制
- 预设模板基础功能（模板选择、模板应用）
- 实时预览功能
- 拖拽交互和快捷操作

**P1（重要实现）**：
- 配置历史和回滚功能
- 模板收藏功能
- 配置缓存机制
- 配置导出和导入功能
- 智能提示和建议

**P2（可选实现）**：
- 自定义CSS覆盖
- 模板对比功能
- 模板市场（第三方上传）

### 8.2 技术选型建议

**前端技术**：
- 小程序端：使用微信小程序自定义组件和动态样式
- 管理后台：使用Vue/React的动态样式绑定和CSS变量

**后端技术**：
- 配置存储：使用JSON格式，支持版本管理
- 资源存储：使用对象存储（如阿里云OSS）
- 缓存：使用Redis缓存配置，提升加载速度

**数据库设计**：
- 租户UI配置表：使用JSONB类型存储配置
- 预设模板表：支持模板版本和灰度发布
- 配置历史表：支持配置回滚和对比

### 8.3 风险和缓解措施

**风险1：配置冲突**
- 缓解措施：提供配置验证和自动合并机制
- 备份方案：支持配置回滚和历史记录

**风险2：性能影响**
- 缓解措施：使用缓存机制，避免频繁查询数据库
- 监控方案：监控配置加载时间，优化慢查询

**风险3：兼容性问题**
- 缓解措施：提供默认配置，确保降级可用
- 测试方案：测试所有预设模板的兼容性

---

**文档结束**