# 默认主题修改为浅色模式 - 设计文档

**日期：** 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/)