## Context

当前前端项目使用 Vue 3 + Vant UI 构建，虽然已有封装的 `PopupContainer.vue` 组件，但项目中存在多种弹窗实现方式：

1. **PopupContainer.vue**: 统一的底部弹出式弹窗，支持标题、副标题、固定头部/页脚、内容滚动
2. **AddClassifyDialog.vue**: 基于 `van-dialog` 的独立对话框组件，用于新增分类
3. **CategoryBillPopup.vue**: 基于 `van-popup` 的独立底部弹窗组件，用于展示分类账单列表
4. **直接使用 van-dialog**: 多个视图文件中直接使用（如 ClassificationEdit.vue、BillAnalysisView.vue）
5. **直接使用 van-popup**: 多个视图文件中用于选择器、表单等场景（如 PeriodicRecord.vue、statisticsV2/Index.vue）

这种分散的实现导致：
- 弹窗风格不统一（标题样式、圆角、间距、字体大小等）
- 代码重复度高，维护成本高
- 用户体验不一致

## Goals / Non-Goals

**Goals:**
- 统一所有弹窗组件使用 `PopupContainer` 或其扩展组件
- 确保弹窗的视觉风格和交互行为一致
- 减少代码重复，提高可维护性
- 扩展 `PopupContainer` 功能以覆盖现有所有使用场景

**Non-Goals:**
- 不修改 Vant UI 组件库本身
- 不改变弹窗的业务逻辑（仅重构 UI 层）
- 不影响后端 API

## Decisions

### 1. 扩展现有 PopupContainer 组件而非创建新组件

**选择理由:**
- `PopupContainer.vue` 已有成熟的底部弹窗布局和样式
- 仅需扩展其功能即可覆盖大部分使用场景
- 避免引入新的组件，减少学习成本

**扩展点:**
- 添加 `confirm` 和 `cancel` 事件，支持简单确认对话框场景
- 添加 `showConfirmButton` 和 `showCancelButton` props，控制按钮显示
- 添加 `confirmText` 和 `cancelText` props，自定义按钮文本
- 保留插槽机制，支持复杂表单场景

### 2. 保留 PopupContainer 的插槽设计

**选择理由:**
- 插槽提供最大的灵活性，支持任意复杂的内容
- 现有代码已使用插槽模式（header-actions、footer），保持向后兼容
- 避免 API 过度设计，保持组件简洁

### 3. 渐进式迁移策略

**选择理由:**
- 42+ 处弹窗修改，一次性重构风险高
- 分批迁移便于测试和回滚
- 降低对现有功能的影响

**迁移顺序:**
1. 扩展 `PopupContainer` 组件
2. 迁移 `AddClassifyDialog.vue` 和 `CategoryBillPopup.vue`
3. 迁移 `views/` 目录中的弹窗，按功能模块分批

### 4. 不删除 AddClassifyDialog 和 CategoryBillPopup 组件文件

**选择理由:**
- 这两个组件封装了特定的业务逻辑（如表单验证、数据加载）
- 可以将它们改造为使用 `PopupContainer` 的组合组件，保留业务逻辑
- 避免破坏其他引用这些组件的地方

**改造方式:**
- 将 `AddClassifyDialog.vue` 改造为使用 `PopupContainer` 的组合组件
- 将 `CategoryBillPopup.vue` 改造为使用 `PopupContainer` 的组合组件
- 组件 API 保持不变，仅内部实现变更

### 5. 使用 Vant UI 的 CSS 变量

**选择理由:**
- 项目已使用 Vant UI，保持视觉一致性
- 支持深色/浅色主题切换
- 减少自定义 CSS 代码量

## Risks / Trade-offs

### 1. 扩展 PopupContainer 可能导致 API 膨胀

**风险**: 扩展功能过多后，组件变得复杂，难以维护

**缓解措施**:
- 保持核心 API 简洁，使用插槽处理复杂场景
- 添加清晰的文档和示例
- 考虑拆分为多个专用组件（如 ConfirmDialog、FormDialog）如果过于复杂

### 2. 迁移过程中可能引入 Bug

**风险**: 重构可能破坏现有功能

**缓解措施**:
- 渐进式迁移，每批迁移后进行完整测试
- 保留旧代码作为参考，直到新代码稳定
- 重点测试弹窗的打开/关闭、表单验证、数据加载等交互

### 3. 某些场景可能不适用 PopupContainer

**风险**: 一些特殊的弹窗场景（如全屏弹窗、居中弹窗）无法用底部弹窗实现

**缓解措施**:
- 识别这些特殊场景，评估是否需要保留 `van-dialog` 或创建新的专用组件
- 优先统一常见场景，特殊场景可以例外

### 4. 性能影响

**风险**: 组件封装层可能增加轻微的性能开销

**缓解措施**:
- 保持组件轻量化，避免不必要的响应式依赖
- 使用 Vue 3 的 `<script setup>` 语法，减少运行时开销
- 进行性能测试，确保没有明显退化

## Migration Plan

### 阶段 1: 扩展 PopupContainer 组件
1. 添加确认对话框相关 props（`showConfirmButton`、`showCancelButton`、`confirmText`、`cancelText`）
2. 添加 `confirm` 和 `cancel` 事件
3. 更新样式，确保与现有设计一致
4. 编写组件文档和示例

### 阶段 2: 改造现有封装组件
1. 改造 `AddClassifyDialog.vue`，使用 `PopupContainer` 实现
2. 改造 `CategoryBillPopup.vue`，使用 `PopupContainer` 实现
3. 测试改造后的组件功能

### 阶段 3: 迁移 views/ 目录中的弹窗
按功能模块分批迁移：
1. 分类相关视图（ClassificationEdit.vue、ClassificationBatch.vue 等）
2. 账单相关视图（PeriodicRecord.vue、TransactionsRecord.vue 等）
3. 统计相关视图（statisticsV2/Index.vue 等）
4. 预算相关视图（budgetV2/*.vue）
5. 其他视图（BillAnalysisView.vue、calendarV2/Index.vue 等）

### 阶段 4: 验证和优化
1. 全量测试所有弹窗功能
2. 性能测试和优化
3. 代码审查和清理
4. 更新文档

### 回滚策略
- 使用 Git 分支进行开发，主分支保持稳定
- 每个阶段完成后打 Tag，便于快速回滚
- 保留旧的实现代码，直到新代码完全稳定

## Open Questions

1. 是否需要创建专门的 `ConfirmDialog` 组件？
   - 当前考虑扩展 `PopupContainer` 以支持确认对话框场景
   - 如果确认对话框的使用场景较多且简单，可以考虑独立组件

2. 如何处理全屏弹窗场景？
   - 识别项目中是否存在全屏弹窗需求
   - 如有，评估是否需要扩展 `PopupContainer` 或创建新组件

3. 弹窗动画是否需要统一？
   - 当前依赖 Vant UI 的默认动画
   - 如有特殊需求，可能需要自定义动画