143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
|
## Context
|
|||
|
|
|
|||
|
|
EmailBill 应用使用 Vue 3 + Vant UI，采用基于 CSS 变量的主题系统支持亮色/暗色模式切换。主题变量定义在 `Web/src/assets/theme.css` 中：
|
|||
|
|
|
|||
|
|
- `--bg-primary`: 主背景色（亮色: #FFFFFF, 暗色: #09090B）
|
|||
|
|
- `--bg-secondary`: 次级背景色（亮色: #F6F7F8, 暗色: #18181b）
|
|||
|
|
|
|||
|
|
**当前状态：**
|
|||
|
|
- **统计 V2 页面** (`statisticsV2/Index.vue`): 使用 `--bg-secondary` 作为页面背景（灰底），卡片使用 `--bg-primary`（白卡片/黑卡片）
|
|||
|
|
- **日历 V2 页面** (`calendarV2/Index.vue`): 使用 `--bg-primary` 作为页面背景（白底/黑底），卡片使用 `--bg-secondary`（灰卡片）
|
|||
|
|
|
|||
|
|
**问题：** 页面切换时配色反转，导致视觉不连贯，尤其在暗色模式下黑底灰卡片对比度不足。
|
|||
|
|
|
|||
|
|
**约束：**
|
|||
|
|
- 仅修改 CSS，不涉及 Vue 组件逻辑或 JavaScript 代码
|
|||
|
|
- 保持主题系统变量定义不变
|
|||
|
|
- 不影响其他页面（如 BudgetView, SettingView）
|
|||
|
|
|
|||
|
|
## Goals / Non-Goals
|
|||
|
|
|
|||
|
|
**Goals:**
|
|||
|
|
- 统一日历 V2 和统计 V2 页面的配色方案（灰底 + 白卡片/黑卡片）
|
|||
|
|
- 提升暗色模式下的视觉对比度
|
|||
|
|
- 保持主题切换功能正常工作
|
|||
|
|
- 确保修改后不影响页面功能和响应式布局
|
|||
|
|
|
|||
|
|
**Non-Goals:**
|
|||
|
|
- 不重构主题系统或引入新的 CSS 变量
|
|||
|
|
- 不修改统计 V2 页面（作为标准参考）
|
|||
|
|
- 不涉及其他 V1 版本页面（`statisticsV1/`, `CalendarView.vue`）
|
|||
|
|
- 不调整卡片内部元素的样式（如文字颜色、图表配色）
|
|||
|
|
|
|||
|
|
## Decisions
|
|||
|
|
|
|||
|
|
### 决策 1：CSS 变量替换策略
|
|||
|
|
|
|||
|
|
**选择：** 直接在 Vue 组件的 `<style>` 块中替换背景色变量
|
|||
|
|
|
|||
|
|
**理由：**
|
|||
|
|
- 最小改动原则：仅修改 4 个 Vue 文件的 CSS 部分
|
|||
|
|
- 可追溯性：改动集中在日历 V2 相关文件，易于 review 和回滚
|
|||
|
|
- 无副作用：不影响其他页面或全局样式
|
|||
|
|
|
|||
|
|
**替代方案（未采用）：**
|
|||
|
|
- ❌ 创建新的 CSS 类（如 `.page-bg-gray`）：增加复杂度，且只用于一个场景
|
|||
|
|
- ❌ 修改主题变量定义：影响范围过大，可能破坏其他页面
|
|||
|
|
|
|||
|
|
### 决策 2：修改顺序与文件范围
|
|||
|
|
|
|||
|
|
**修改文件清单：**
|
|||
|
|
1. `calendarV2/Index.vue` - 主容器 `.calendar-scroll-content`
|
|||
|
|
2. `calendarV2/modules/Stats.vue` - 统计卡片 `.stats-card`
|
|||
|
|
3. `calendarV2/modules/Calendar.vue` - 日历容器（如果有独立背景）
|
|||
|
|
4. `calendarV2/modules/TransactionList.vue` - 交易列表卡片（如果有）
|
|||
|
|
|
|||
|
|
**修改规则：**
|
|||
|
|
- **页面级容器**：`background-color: var(--bg-primary)` → `var(--bg-secondary)`
|
|||
|
|
- **卡片级容器**：`background-color: var(--bg-secondary)` → `var(--bg-primary)`
|
|||
|
|
|
|||
|
|
**验证点：**
|
|||
|
|
- 检查每个文件的 `<style>` 块中是否直接或间接（通过类名）使用了背景色
|
|||
|
|
- 使用浏览器 DevTools 检查计算后的样式，确认没有遗漏的背景声明
|
|||
|
|
|
|||
|
|
### 决策 3：暗色模式验证
|
|||
|
|
|
|||
|
|
**策略：** 在修改后同时测试亮色和暗色模式
|
|||
|
|
|
|||
|
|
**验证场景：**
|
|||
|
|
1. 切换主题后页面背景和卡片背景正确应用
|
|||
|
|
2. 文字颜色对比度符合可读性要求（WCAG AA 标准）
|
|||
|
|
3. 图表和图标颜色在灰底上清晰可见
|
|||
|
|
|
|||
|
|
**工具：**
|
|||
|
|
- Chrome DevTools 的对比度检查器
|
|||
|
|
- 手动切换应用内的主题开关
|
|||
|
|
|
|||
|
|
## Risks / Trade-offs
|
|||
|
|
|
|||
|
|
### 风险 1：遗漏子组件的背景声明
|
|||
|
|
|
|||
|
|
**风险：** 日历 V2 的子模块可能在多个层级使用背景色，遗漏修改会导致局部配色不一致
|
|||
|
|
|
|||
|
|
**缓解措施：**
|
|||
|
|
- 使用全局搜索（grep/Glob）查找 `calendarV2/` 目录下所有 `background-color` 和 `--bg-` 的使用
|
|||
|
|
- 在浏览器中使用 DevTools 的 "Computed" 面板检查每个可视元素的实际背景色
|
|||
|
|
- 对比统计 V2 页面的 DOM 结构和样式，确保层级一致
|
|||
|
|
|
|||
|
|
### 风险 2：第三方组件（Vant）的样式覆盖
|
|||
|
|
|
|||
|
|
**风险：** Vant UI 组件（如 `<van-pull-refresh>`, `<van-popup>`）可能有默认背景色，与新方案冲突
|
|||
|
|
|
|||
|
|
**缓解措施：**
|
|||
|
|
- 检查 Vant 组件是否透明或继承父容器背景
|
|||
|
|
- 如有冲突，在组件级别添加覆盖样式（如 `::v-deep .van-pull-refresh__track`）
|
|||
|
|
- 参考统计 V2 页面的 Vant 组件样式处理
|
|||
|
|
|
|||
|
|
### 风险 3：移动端真机测试
|
|||
|
|
|
|||
|
|
**风险：** CSS 变量在某些旧版 iOS Safari 或 Android WebView 中可能渲染异常
|
|||
|
|
|
|||
|
|
**缓解措施：**
|
|||
|
|
- 项目已使用 CSS 变量主题系统，现有页面正常运行，说明兼容性已验证
|
|||
|
|
- 修改后使用相同的变量，不引入新的兼容性风险
|
|||
|
|
- 如需验证，在移动端测试环境中切换主题并检查背景渲染
|
|||
|
|
|
|||
|
|
### Trade-off：设计灵活性 vs 一致性
|
|||
|
|
|
|||
|
|
**选择：** 优先保证与统计 V2 页面一致，牺牲日历页面独立的视觉风格
|
|||
|
|
|
|||
|
|
**理由：**
|
|||
|
|
- 用户在页面间频繁切换，一致性优先级高于个性化
|
|||
|
|
- 灰底白卡片方案在暗色模式下对比度更好，更符合可访问性标准
|
|||
|
|
- 如果未来需要差异化设计，可通过主题系统扩展（如增加 `--page-specific-bg`）
|
|||
|
|
|
|||
|
|
## Migration Plan
|
|||
|
|
|
|||
|
|
**部署步骤：**
|
|||
|
|
1. 在开发分支完成所有 CSS 修改
|
|||
|
|
2. 本地验证亮色/暗色模式切换正常
|
|||
|
|
3. 提交代码并运行前端 lint 和构建测试（`pnpm lint && pnpm build`）
|
|||
|
|
4. 合并到主分支并部署到测试环境
|
|||
|
|
5. 在真机上测试页面切换和主题切换
|
|||
|
|
|
|||
|
|
**回滚策略：**
|
|||
|
|
- 如有问题，回退 4 个 Vue 文件的 CSS 改动（纯样式修改，无数据或逻辑依赖）
|
|||
|
|
- Git revert 单个 commit 即可快速回滚
|
|||
|
|
|
|||
|
|
**影响范围：**
|
|||
|
|
- 低风险：仅影响日历 V2 页面视觉呈现
|
|||
|
|
- 无数据迁移或 API 变更
|
|||
|
|
- 不影响用户数据或业务逻辑
|
|||
|
|
|
|||
|
|
## Open Questions
|
|||
|
|
|
|||
|
|
1. ~~是否需要同步修改日历 V1 页面（`CalendarView.vue`）？~~
|
|||
|
|
→ 否，proposal 明确只修改 V2 页面
|
|||
|
|
|
|||
|
|
2. ~~是否需要在设计系统文档中记录统一的配色规范？~~
|
|||
|
|
→ 建议在 `.doc/` 目录添加 UI 配色指南，但不在本次变更范围内
|
|||
|
|
|
|||
|
|
3. **待确认**：`calendarV2/modules/TransactionList.vue` 是否有独立的卡片容器？
|
|||
|
|
→ 需要检查文件后确定是否需要修改
|