## 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` 是否有独立的卡片容器？  
   → 需要检查文件后确定是否需要修改