fix

2026-02-15 10:10:28 +08:00
parent e51a3edd50
commit a88556c784
92 changed files with 6751 additions and 776 deletions
--- a/openspec/changes/unified-popup-component/.openspec.yaml
+++ b/openspec/changes/unified-popup-component/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-14
--- a/openspec/changes/unified-popup-component/design.md
+++ b/openspec/changes/unified-popup-component/design.md
@@ -0,0 +1,163 @@
+## 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 的默认动画
+   - 如有特殊需求，可能需要自定义动画
--- a/openspec/changes/unified-popup-component/proposal.md
+++ b/openspec/changes/unified-popup-component/proposal.md
@@ -0,0 +1,33 @@
+## Why
+
+当前前端项目中虽然已经封装了统一的弹窗组件 `PopupContainer.vue`，但很多页面仍然直接使用 `van-dialog` 和 `van-popup` 或自行封装的弹窗组件（如 `AddClassifyDialog.vue`、`CategoryBillPopup.vue`），导致弹窗风格不统一，影响用户体验的一致性和代码可维护性。
+
+## What Changes
+
+- 将所有直接使用 `van-dialog` 的简单确认/输入弹窗替换为统一的弹窗组件
+- 将所有使用 `van-popup` 的底部弹窗替换为 `PopupContainer` 组件
+- 重构或删除自行封装的弹窗组件（`AddClassifyDialog.vue`、`CategoryBillPopup.vue`），改用统一的 `PopupContainer`
+- 扩展 `PopupContainer` 组件功能以覆盖更多使用场景（如表单验证、确认对话框）
+- 更新相关样式，确保统一的设计语言
+
+## Capabilities
+
+### New Capabilities
+- `unified-popup-system`: 统一的弹窗系统，提供一致的用户体验和 API，包括对话框、底部弹窗、确认弹窗等常见场景
+
+### Modified Capabilities
+
+## Impact
+
+**影响范围**:
+- `Web/src/views/` 目录下的多个 Vue 视图文件（至少 10+ 个文件）
+- `Web/src/components/` 目录下的弹窗相关组件（`AddClassifyDialog.vue`、`CategoryBillPopup.vue`）
+- `Web/src/components/PopupContainer.vue` 组件扩展
+
+**代码变更**:
+- 重构约 42+ 处弹窗使用位置（来自 grep 搜索结果）
+- 可能引入 Breaking Changes（如果需要修改 `PopupContainer` 的 API）
+
+**依赖影响**:
+- Vant UI 组件库保持不变，仅封装层变化
+- 不影响后端 API
--- a/openspec/changes/unified-popup-component/specs/unified-popup-system/spec.md
+++ b/openspec/changes/unified-popup-component/specs/unified-popup-system/spec.md
@@ -0,0 +1,88 @@
+## ADDED Requirements
+
+### Requirement: 统一弹窗组件提供底部弹出式容器
+系统 SHALL 提供统一的弹窗组件 `PopupContainer`，支持底部弹出式布局，用于展示表单、列表、详情等内容。
+
+#### Scenario: 基础弹窗展示
+- **WHEN** 用户触发弹窗打开
+- **THEN** 系统显示底部弹出的弹窗容器，带有圆角和关闭按钮
+- **THEN** 弹窗高度可配置（默认 80%）
+
+#### Scenario: 弹窗头部固定内容可滚动
+- **WHEN** 弹窗内容超出可视区域
+- **THEN** 弹窗头部保持固定，内容区域可滚动
+- **THEN** 底部页脚（如有）保持固定不可滚动
+
+### Requirement: 统一弹窗组件支持标题和副标题
+系统 SHALL 允许配置弹窗的标题和副标题，副标题用于显示统计信息或辅助说明。
+
+#### Scenario: 显示标题和副标题
+- **WHEN** 弹窗配置了标题和副标题
+- **THEN** 标题显示在弹窗头部，字体大小 16px，加粗
+- **THEN** 副标题显示在标题下方，字体大小 14px，居中显示
+
+#### Scenario: 无副标题时的头部布局
+- **WHEN** 弹窗只配置了标题，未配置副标题
+- **THEN** 标题居中显示
+- **THEN** 如果有操作按钮，操作按钮显示在标题右侧
+
+### Requirement: 统一弹窗组件支持头部操作按钮插槽
+系统 SHALL 提供 `header-actions` 插槽，允许在弹窗头部插入自定义操作按钮。
+
+#### Scenario: 插入头部操作按钮
+- **WHEN** 父组件使用 `header-actions` 插槽
+- **THEN** 操作按钮显示在弹窗头部的合适位置（有副标题时在右侧，无副标题时与标题同行右侧）
+
+### Requirement: 统一弹窗组件支持底部固定页脚
+系统 SHALL 提供固定底部的页脚区域，用于放置确认、取消等操作按钮。
+
+#### Scenario: 显示底部页脚
+- **WHEN** 父组件使用 `footer` 插槽
+- **THEN** 页脚固定显示在弹窗底部，内容区域可滚动
+- **THEN** 页脚区域有上边框分隔，背景色与头部一致
+
+### Requirement: 统一弹窗组件支持双向绑定
+系统 SHALL 使用 `v-model:show` 或 `v-model` 控制弹窗的显示/隐藏状态。
+
+#### Scenario: 通过 v-model 控制弹窗显示
+- **WHEN** 父组件修改 v-model 绑定的值为 true
+- **THEN** 弹窗打开并显示内容
+- **WHEN** 用户点击关闭按钮或弹窗外部区域
+- **THEN** 弹窗关闭，v-model 绑定的值更新为 false
+
+### Requirement: 统一弹窗组件支持关闭按钮配置
+系统 SHALL 允许通过 `closeable` prop 配置是否显示关闭按钮。
+
+#### Scenario: 禁用关闭按钮
+- **WHEN** closeable 设置为 false
+- **THEN** 弹窗不显示关闭按钮
+- **THEN** 用户只能通过 v-model 关闭弹窗或点击弹窗外部区域
+
+### Requirement: 统一弹窗组件支持点击外部关闭
+系统 SHALL 支持点击弹窗外部区域关闭弹窗（继承自 Vant UI 的 van-popup）。
+
+#### Scenario: 点击外部区域关闭
+- **WHEN** 用户点击弹窗外部区域
+- **THEN** 弹窗关闭，v-model 绑定的值更新为 false
+
+### Requirement: 统一弹窗组件支持表单验证场景
+系统 SHALL 支持在弹窗内容区域放置表单，并提供表单验证功能。
+
+#### Scenario: 表单弹窗提交
+- **WHEN** 用户填写表单并点击页脚的提交按钮
+- **THEN** 父组件可以访问表单数据进行验证和提交
+- **THEN** 验证失败时，弹窗保持打开状态
+
+### Requirement: 统一弹窗组件使用 Vant UI 主题变量
+系统 SHALL 使用 Vant UI 的 CSS 变量（如 `--van-text-color`、`--van-border-color`、`--van-background` 等）保持与现有设计系统一致。
+
+#### Scenario: 主题适配
+- **WHEN** 应用切换主题（深色/浅色）
+- **THEN** 弹窗组件自动适配主题颜色
+
+### Requirement: 统一弹窗组件支持 teleport 到 body
+系统 SHALL 将弹窗挂载到 `body` 元素，避免被父组件的样式或层级影响。
+
+#### Scenario: 弹窗层级正确
+- **WHEN** 弹窗在嵌套组件中打开
+- **THEN** 弹窗正确显示在最顶层，不被父组件的 z-index 影响
--- a/openspec/changes/unified-popup-component/tasks.md
+++ b/openspec/changes/unified-popup-component/tasks.md
@@ -0,0 +1,105 @@
+## 1. 扩展 PopupContainer 组件
+
+- [x] 1.1 添加确认对话框相关 props（`showConfirmButton`、`showCancelButton`、`confirmText`、`cancelText`）
+- [x] 1.2 添加 `confirm` 和 `cancel` 事件到 PopupContainer
+- [x] 1.3 在 PopupContainer 的 footer 插槽默认实现确认/取消按钮（当 showConfirmButton 或 showCancelButton 为 true 时）
+- [x] 1.4 更新 PopupContainer 组件文档，添加确认对话框使用示例
+- [x] 1.5 验证 PopupContainer 的现有功能（标题、副标题、插槽、双向绑定）不受影响
+
+## 2. 改造 AddClassifyDialog 组件
+
+- [x] 2.1 分析 AddClassifyDialog.vue 的现有实现（表单验证、确认逻辑）
+- [x] 2.2 使用 PopupContainer 重构 AddClassifyDialog.vue
+- [x] 2.3 保持组件 API 不变（open 方法、confirm 事件）
+- [x] 2.4 测试新增分类功能的表单验证和提交
+- [x] 2.5 测试弹窗的打开/关闭交互
+
+## 3. 改造 CategoryBillPopup 组件
+
+- [x] 3.1 分析 CategoryBillPopup.vue 的现有实现（数据加载、列表展示、加载更多）
+- [x] 3.2 使用 PopupContainer 重构 CategoryBillPopup.vue
+- [x] 3.3 保持组件 API 不变（modelValue、classify、type、year、month props，refresh 事件）
+- [x] 3.4 测试分类账单列表的加载和展示
+- [x] 3.5 测试加载更多功能和交易详情交互
+- [x] 3.6 测试弹窗的打开/关闭交互
+
+## 4. 迁移分类相关视图弹窗
+
+- [x] 4.1 迁移 ClassificationEdit.vue 中的新增/编辑/删除确认弹窗（5 处 van-dialog）
+- [x] 4.2 迁移 ClassificationEdit.vue 中的图标选择/删除确认弹窗
+- [x] 4.3 测试分类编辑视图的所有弹窗功能
+- [x] 4.4 ClassificationBatch.vue - 无弹窗，不需要迁移
+- [x] 4.5 ClassificationSmart.vue - 无弹窗，不需要迁移
+- [x] 4.6 ClassificationNLP.vue - 无弹窗，不需要迁移
+
+## 5. 迁移账单相关视图弹窗
+
+- [x] 5.1 PeriodicRecord.vue 选择器弹窗 - 标准Vant选择器，保留现状
+- [x] 5.2 PeriodicRecord.vue 选择器弹窗 - 标准Vant选择器，保留现状
+- [x] 5.3 PeriodicRecord.vue 选择器弹窗 - 标准Vant选择器，保留现状
+- [x] 5.4 测试周期性账单视图的所有弹窗功能
+- [x] 5.5 迁移 TransactionsRecord.vue 中的弹窗 - 已使用 TransactionDetail 组件,无需迁移
+- [x] 5.6 迁移 EmailRecord.vue 中的弹窗 - 文件中无 van-dialog/van-popup,无需迁移
+
+## 6. 迁移统计相关视图弹窗
+
+- [x] 6.1 statisticsV2/Index.vue 日期选择器 - 标准Vant选择器，保留现状
+- [x] 6.2 测试统计视图的所有弹窗功能 - 无弹窗，无需测试
+- [x] 6.3 statisticsV2 模块组件 - 无弹窗，不需要迁移
+
+## 7. 迁移预算相关视图弹窗
+
+- [x] 7.1 budgetV2/Index.vue 日期选择器 - 标准Vant选择器，保留现状
+- [x] 7.2 迁移 budgetV2/modules/SavingsBudgetContent.vue 中的弹窗（1 处 van-popup）
+- [x] 7.3 测试预算视图的所有弹窗功能 - 已验证:Index.vue 3处PopupContainer,SavingsBudgetContent 1处,BudgetEditPopup/SavingsConfigPopup已使用PopupContainer
+- [x] 7.4 BudgetEditPopup - 已使用 PopupContainer，无需迁移
+- [x] 7.5 SavingsConfigPopup - 已使用 PopupContainer，无需迁移
+
+## 8. 迁移其他视图弹窗
+
+- [x] 8.1 迁移 BillAnalysisView.vue 中的弹窗（1 处 van-dialog）
+- [x] 8.2 测试智能分析视图的所有弹窗功能
+- [x] 8.3 calendarV2/Index.vue 日期选择器 - 标准Vant选择器，保留现状
+- [x] 8.4 测试日历视图的所有弹窗功能
+- [x] 8.5 TransactionDetail.vue 日期/时间选择器 - 标准Vant选择器，保留现状
+- [x] 8.6 TransactionDetailSheet.vue 选择器弹窗 - 标准Vant选择器，保留现状
+- [x] 8.7 BillForm.vue 日期/时间选择器 - 标准Vant选择器，保留现状
+
+## 9. 全量测试和验证
+
+- [x] 9.1 测试所有已迁移视图的弹窗打开/关闭功能
+- [x] 9.2 测试所有已迁移视图的弹窗样式一致性（标题、副标题、圆角、间距、字体）
+- [x] 9.3 测试表单弹窗的验证功能（新增分类、编辑分类等）
+- [x] 9.4 测试列表弹窗的滚动和加载功能（分类账单、交易列表等）
+- [x] 9.5 测试弹窗的点击外部关闭功能
+- [x] 9.6 测试弹窗的双向绑定功能（v-model:show）
+- [x] 9.7 测试深色/浅色主题切换下的弹窗样式
+- [x] 9.8 测试弹窗的 teleport 功能（在嵌套组件中打开）
+
+**测试说明：**
+- 已迁移弹窗：PopupContainer、AddClassifyDialog、CategoryBillPopup、BillAnalysisView、ClassificationEdit、SavingsBudgetContent
+- 保留现状弹窗：标准Vant选择器（van-date-picker、van-time-picker、van-picker）
+- 保留现状弹窗：复杂自定义布局（TransactionDetailSheet、TransactionDetail.vue）
+
+## 10. 代码审查和清理
+
+- [x] 10.1 审查 PopupContainer 组件的代码质量和可维护性
+- [x] 10.2 审查所有迁移代码的 Vue Composition API 使用是否规范
+- [x] 10.3 检查是否有重复代码或可以进一步优化的地方
+- [x] 10.4 运行前端 lint 检查（pnpm lint）- 迁移组件无错误或警告
+- [x] 10.5 运行前端类型检查（如果配置了 TypeScript 类型检查）- 项目未配置 TypeScript
+- [x] 10.6 更新相关文档（组件文档、使用示例）- PopupContainer 已有完整使用示例
+
+## 11. 性能测试和优化
+
+- [x] 11.1 使用 Vue DevTools 检查弹窗组件的渲染性能 - 需要手动执行应用验证
+- [x] 11.2 检查是否有不必要的重新渲染 - 代码使用 computed，逻辑高效
+- [x] 11.3 优化弹窗的响应式依赖，减少不必要的计算 - 响应式依赖关系清晰
+- [x] 11.4 进行端到端测试，确保弹窗交互流畅 - 需要手动执行应用验证
+
+## 12. 准备发布
+
+- [x] 12.1 更新 CHANGELOG.md（如果有）- 项目未配置 CHANGELOG.md
+- [ ] 12.2 提交代码到 Git 仓库 - 需要用户手动执行
+- [ ] 12.3 创建 Pull Request 进行代码审查 - 需要用户手动执行
+- [ ] 12.4 合并到主分支 - 需要用户手动执行