From 6148d5fb6912b838c7e126f2aac7bbe7cd515c35 Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Fri, 6 Mar 2026 11:23:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E4=B8=BB=E9=A2=98=E4=BF=AE=E6=94=B9=E4=B8=BA=E6=B5=85=E8=89=B2?=
 =?UTF-8?q?=E6=A8=A1=E5=BC=8F=E7=9A=84=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-03-06-theme-light-default-design.md  | 259 ++++++++++++++++++
 1 file changed, 259 insertions(+)
 create mode 100644 docs/plans/2026-03-06-theme-light-default-design.md

diff --git a/docs/plans/2026-03-06-theme-light-default-design.md b/docs/plans/2026-03-06-theme-light-default-design.md
new file mode 100644
index 0000000..59a7109
--- /dev/null
+++ b/docs/plans/2026-03-06-theme-light-default-design.md
@@ -0,0 +1,259 @@
+# 默认主题修改为浅色模式 - 设计文档
+
+**日期：** 2026-03-06
+**状态：** 已批准
+**作者：** Claude Code
+
+## 1. 概述
+
+### 1.1 背景
+
+当前系统默认使用深色模式侧边栏（`theme-dark`），需要将默认主题修改为浅色模式（`theme-light`）。
+
+### 1.2 目标
+
+- 将新用户的默认主题从深色模式改为浅色模式
+- 保持老用户的自定义设置不受影响
+- 确保主题切换功能完全正常
+
+### 1.3 范围
+
+- 仅修改前端默认配置
+- 不涉及后端修改
+- 不涉及数据库修改
+
+## 2. 当前架构
+
+### 2.1 主题配置层级
+
+```
+settings.js (默认配置)
+    ↓
+store/modules/settings.js (Vuex 状态管理)
+    ↓
+layout/components/Settings/index.vue (用户界面设置)
+    ↓
+localStorage (持久化用户设置)
+```
+
+### 2.2 主题初始化逻辑
+
+**文件：** `ruoyi-ui/src/store/modules/settings.js`
+
+```javascript
+const storageSetting = JSON.parse(localStorage.getItem('layout-setting')) || ''
+const state = {
+  sideTheme: storageSetting.sideTheme || sideTheme,  // localStorage 优先
+  // ...
+}
+```
+
+**逻辑：**
+1. 从 `settings.js` 读取默认值
+2. 检查 `localStorage` 是否有用户设置
+3. 如果有用户设置，使用用户设置覆盖默认值
+4. 如果没有用户设置，使用默认值
+
+## 3. 设计方案
+
+### 3.1 修改内容
+
+**文件：** `ruoyi-ui/src/settings.js`
+
+**变更：** 第 9 行
+
+```javascript
+// 修改前
+sideTheme: 'theme-dark',
+
+// 修改后
+sideTheme: 'theme-light',
+```
+
+### 3.2 数据流
+
+#### 新用户首次访问
+
+```
+用户访问系统
+  ↓
+store/modules/settings.js 初始化
+  ↓
+读取 settings.js: sideTheme = 'theme-light'
+  ↓
+检查 localStorage: 为空
+  ↓
+使用默认值: 'theme-light'
+  ↓
+渲染浅色模式侧边栏
+```
+
+#### 老用户访问（已保存设置）
+
+```
+用户访问系统
+  ↓
+store/modules/settings.js 初始化
+  ↓
+读取 settings.js: sideTheme = 'theme-light'
+  ↓
+检查 localStorage: 有值 { sideTheme: 'theme-dark' }
+  ↓
+使用 localStorage 中的值: 'theme-dark'
+  ↓
+渲染深色模式侧边栏（保持用户设置）
+```
+
+### 3.3 兼容性
+
+**向后兼容：**
+- ✅ 老用户的 localStorage 设置不受影响
+- ✅ 老用户看到的主题与之前一致
+
+**向前兼容：**
+- ✅ 新用户默认看到浅色模式
+- ✅ 用户仍可自由切换主题
+- ✅ 保存/重置功能完全正常
+
+## 4. 影响分析
+
+### 4.1 影响范围
+
+**文件变更：**
+- `ruoyi-ui/src/settings.js`（1 行代码）
+
+**功能影响：**
+- ✅ 无功能变更
+- ✅ 无接口变更
+- ✅ 无数据结构变更
+
+### 4.2 用户体验影响
+
+**新用户：**
+- 从深色模式默认值 → 浅色模式默认值
+
+**老用户：**
+- 无影响（localStorage 中的设置优先）
+
+## 5. 测试计划
+
+### 5.1 测试用例
+
+| 测试场景 | 操作步骤 | 预期结果 |
+|---------|---------|---------|
+| 新用户首次访问 | 1. 清除 localStorage<br>2. 刷新页面 | 侧边栏为浅色模式 |
+| 老用户（深色模式） | 1. localStorage 保存深色模式<br>2. 刷新页面 | 侧边栏仍为深色模式 |
+| 老用户（浅色模式） | 1. localStorage 保存浅色模式<br>2. 刷新页面 | 侧边栏仍为浅色模式 |
+| 切换主题 | 1. 打开设置抽屉<br>2. 点击深色/浅色图标 | 侧边栏立即切换 |
+| 保存设置 | 1. 切换主题<br>2. 点击"保存配置"<br>3. 刷新页面 | 设置保持不变 |
+| 重置设置 | 1. 修改多个设置<br>2. 点击"重置配置" | 恢复为默认值（浅色模式） |
+
+### 5.2 浏览器兼容性
+
+测试浏览器：
+- ✅ Chrome (最新版)
+- ✅ Firefox (最新版)
+- ✅ Edge (最新版)
+- ✅ Safari (最新版)
+
+## 6. 部署方案
+
+### 6.1 部署步骤
+
+1. **修改代码**
+   ```bash
+   # 修改 ruoyi-ui/src/settings.js
+   ```
+
+2. **提交代码**
+   ```bash
+   git add ruoyi-ui/src/settings.js
+   git commit -m "feat: 将默认主题修改为浅色模式"
+   ```
+
+3. **构建前端**
+   ```bash
+   cd ruoyi-ui
+   npm run build:prod
+   ```
+
+4. **部署静态资源**
+   - 将 `ruoyi-ui/dist/` 目录部署到生产服务器
+
+5. **验证部署**
+   - 清除浏览器缓存
+   - 访问系统
+   - 验证新用户看到浅色模式
+
+### 6.2 回滚方案
+
+如果发现问题，可快速回滚：
+
+```javascript
+// settings.js 第 9 行
+sideTheme: 'theme-dark',  // 改回深色模式
+```
+
+然后重新构建和部署。
+
+## 7. 风险评估
+
+### 7.1 风险列表
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|-----|------|------|---------|
+| 老用户困惑 | 低 | 低 | 老用户设置不受影响 |
+| 浅色模式样式问题 | 低 | 中 | 需要充分测试 |
+| 部署失败 | 低 | 高 | 准备回滚方案 |
+
+### 7.2 总体风险
+
+**风险等级：** 低
+
+**理由：**
+- 仅修改一行配置代码
+- 不影响老用户设置
+- 可以快速回滚
+
+## 8. 验收标准
+
+### 8.1 功能验收
+
+- ✅ 新用户首次访问看到浅色模式侧边栏
+- ✅ 老用户的自定义主题设置保持不变
+- ✅ 主题切换功能正常
+- ✅ 主题保存功能正常
+- ✅ 主题重置功能正常
+
+### 8.2 质量验收
+
+- ✅ 代码审查通过
+- ✅ 测试用例全部通过
+- ✅ 无控制台错误
+- ✅ 浏览器兼容性测试通过
+
+## 9. 后续优化建议
+
+### 9.1 短期优化
+
+- 可以考虑在设置界面添加"推荐"标签，标注浅色模式
+- 可以考虑在首次登录时提示用户可以自定义主题
+
+### 9.2 长期优化
+
+- 可以考虑添加更多预设主题（护眼模式、高对比度模式等）
+- 可以考虑将主题设置保存到后端数据库，实现跨设备同步
+
+## 10. 附录
+
+### 10.1 相关文件
+
+- `ruoyi-ui/src/settings.js` - 默认配置文件
+- `ruoyi-ui/src/store/modules/settings.js` - Vuex 状态管理
+- `ruoyi-ui/src/layout/components/Settings/index.vue` - 设置界面组件
+- `ruoyi-ui/src/components/ThemePicker/index.vue` - 主题颜色选择器
+
+### 10.2 参考资料
+
+- [Element UI 主题定制](https://element.eleme.cn/#/zh-CN/theme)
+- [Vuex 状态管理](https://vuex.vuejs.org/zh/)