From 612e0951ed62113ff6c2b9925dbeb71c591f4c11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E7=BF=94?= <xiangzhang1024@gmail.com>
Date: Sat, 7 Mar 2026 16:51:08 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0UI=E6=A8=A1=E7=89=88?=
 =?UTF-8?q?=E5=AE=9A=E5=88=B6=E5=8A=9F=E8=83=BD=E8=AE=BE=E8=AE=A1=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增UI模版定制功能设计文档
- 包含功能概述、架构设计、数据模型、核心功能、数据流、错误处理、测试设计
- 支持品牌定制、布局调整、预设模板三个层次
- 适用于小程序和管理后台的UI定制
---
 .../2026-03-07-ui-customization-design.md     | 166 ++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 docs/plans/2026-03-07-ui-customization-design.md

diff --git a/docs/plans/2026-03-07-ui-customization-design.md b/docs/plans/2026-03-07-ui-customization-design.md
new file mode 100644
index 0000000..7512c23
--- /dev/null
+++ b/docs/plans/2026-03-07-ui-customization-design.md
@@ -0,0 +1,166 @@
+# 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个预设模板的缩略图和描述，支持一键应用模板。模板应用后保留租户已有的品牌配置，只更新布局结构。支持模板收藏和对比功能，租户可以收藏喜欢的模板进行快速切换。模板切换支持预览模式，租户可以在正式应用前预览效果。
+
+---
+
+## 五、数据流设计
+
+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：兼容性问题**
+- 缓解措施：提供默认配置，确保降级可用
+- 测试方案：测试所有预设模板的兼容性
+
+---
+
+**文档结束**