fix

2026-02-20 13:56:29 +08:00
parent 2cf19a45e5
commit 6e95568906
13 changed files with 1038 additions and 1269 deletions
--- a/openspec/changes/archive/2026-02-20-refactor-popup-container-component/.openspec.yaml
+++ b/openspec/changes/archive/2026-02-20-refactor-popup-container-component/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-20
--- a/openspec/changes/archive/2026-02-20-refactor-popup-container-component/design.md
+++ b/openspec/changes/archive/2026-02-20-refactor-popup-container-component/design.md
@@ -0,0 +1,107 @@
+## Context
+
+项目中已有 `PopupContainer.vue` 通用弹窗组件（位于 `Web/src/components/PopupContainer.vue`），但其样式设计与 `TransactionDetailSheet.vue` 不同：
+- PopupContainer: 使用 Vant 主题变量，默认高度 80%，标准化的布局
+- TransactionDetailSheet: 使用 Inter 字体，16px 圆角，纯白背景（#ffffff / #18181b），更现代化的视觉风格
+
+`TransactionDetailSheet.vue` 当前实现（位于 `Web/src/components/Transaction/TransactionDetailSheet.vue`）：
+- 直接使用 `van-popup` + 自定义样式
+- 头部：自定义标题 + 关闭按钮（`.sheet-header`）
+- 内容区域：金额、表单字段、分类选择器（无固定滚动容器）
+- 底部操作按钮：删除、保存（`.actions-section`）
+- 样式特点：`borderTopLeftRadius: 16px`, Inter 字体, `#ffffff` 背景, `gap: 24px`
+
+当前问题：头部和底部未固定，内容较多时滚动体验不佳。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 创建 `PopupContainerV2.vue` 通用组件，采用 TransactionDetailSheet 的样式风格
+- 提供固定头部（标题 + 可选关闭按钮）、可滚动内容、固定底部的布局能力
+- 支持暗色模式（`#18181b` 背景）
+- 将 TransactionDetailSheet 重构为使用 PopupContainerV2
+- 保持 TransactionDetailSheet 所有现有功能和对外 API 不变
+
+**Non-Goals:**
+- 不修改现有的 `PopupContainer.vue`（v1 版本保持不变）
+- 不强制项目中其他组件迁移到 v2（自愿迁移）
+- 不改变 TransactionDetailSheet 的业务逻辑
+- 不引入新的 UI 库或依赖
+
+## Decisions
+
+### 决策 1：创建新组件 PopupContainerV2 而不是修改 PopupContainer
+
+**选择**: 创建新的 `PopupContainerV2.vue` 组件
+
+**理由**:
+- PopupContainer 已在项目中广泛使用（CategoryBillPopup 等），修改可能影响现有组件
+- TransactionDetailSheet 的样式风格更现代，适合作为新版本
+- v1 和 v2 可以并存，逐步迁移，降低风险
+- **替代方案**: 直接修改 PopupContainer → 不采用，破坏性太大，需要验证所有使用方
+
+### 决策 2：PopupContainerV2 的样式来源
+
+**选择**: 完全采用 TransactionDetailSheet 的样式风格
+
+**理由**:
+- TransactionDetailSheet 的样式已经过验证，用户体验良好
+- Inter 字体、16px 圆角、纯白背景是现代化设计趋势
+- 保持样式一致性，避免混合不同的设计语言
+- **替代方案**: 混合 PopupContainer 和 TransactionDetailSheet 的样式 → 不采用，会导致样式不统一
+
+### 决策 3：PopupContainerV2 的 API 设计
+
+**选择**: 提供 title prop、default 插槽、footer 插槽，关闭按钮默认显示
+
+**理由**:
+- title prop 简化使用，覆盖 80% 场景
+- default 插槽放可滚动内容，最大灵活性
+- footer 插槽放固定底部操作按钮
+- 关闭按钮默认显示，符合 TransactionDetailSheet 的行为
+- **替代方案**: 提供 header 插槽替代 title prop → 不采用，增加使用复杂度，大多数场景只需简单标题
+
+### 决策 4：内容区域的 padding 处理
+
+**选择**: PopupContainerV2 的内容插槽不提供默认 padding，由使用方控制
+
+**理由**:
+- TransactionDetailSheet 的不同区域有不同的 padding 需求（金额区域 16px 16px 24px，表单区域 0 16px 16px）
+- 组件不应预设 padding，保持灵活性
+- 使用方可以根据内容自行调整间距
+- **替代方案**: 提供统一的 padding → 不采用，会限制布局灵活性
+
+### 决策 5：TransactionDetailSheet 的迁移策略
+
+**选择**: 完全移除原有的头部和外层布局代码，使用 PopupContainerV2 的插槽
+
+**理由**:
+- 避免代码重复，减少维护成本
+- PopupContainerV2 已提供所有需要的布局能力
+- 保持 TransactionDetailSheet 的职责单一（业务逻辑）
+- **替代方案**: 保留部分原有代码 → 不采用，会造成样式冲突和维护混乱
+
+## Risks / Trade-offs
+
+### 风险 1：新增 PopupContainerV2 组件增加项目复杂度
+**缓解措施**: 
+- 在组件文件顶部添加清晰的文档注释，说明 v1 和 v2 的区别
+- v2 组件设计简洁，API 清晰，易于理解和使用
+- 在使用 TransactionDetailSheet 时验证 v2 的稳定性后，再考虑推广到其他组件
+
+### 风险 2：样式迁移可能遗漏细节
+**缓解措施**: 
+- 仔细对比 TransactionDetailSheet 的原有样式
+- 使用 Chrome DevTools 对比重构前后的渲染效果
+- 验证暗色模式的样式一致性
+
+### 风险 3：日期选择器（van-datetime-picker）的嵌套弹窗可能存在 z-index 冲突
+**缓解措施**: van-datetime-picker 使用 `teleport="body"`，应与 PopupContainerV2 的弹窗层级独立，测试时重点验证
+
+### Trade-off 1：创建 v2 而不是统一到一个组件
+**影响**: 项目中会同时存在两个弹窗组件，增加学习成本  
+**权衡**: 保护现有代码稳定性的收益大于维护两个组件的成本，且 v2 可以逐步替代 v1
+
+### Trade-off 2：PopupContainerV2 不提供默认 padding
+**影响**: 使用方需要自行管理内容区域的间距  
+**权衡**: 灵活性优于便利性，避免样式冲突
--- a/openspec/changes/archive/2026-02-20-refactor-popup-container-component/proposal.md
+++ b/openspec/changes/archive/2026-02-20-refactor-popup-container-component/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+`TransactionDetailSheet.vue` 组件有良好的样式设计（圆角、Inter 字体、清晰的布局层次），但头部标题和底部操作按钮没有固定定位，当内容较多时会随着滚动而移动，影响用户体验。同时，项目中其他弹窗可能也需要类似的固定头部/底部布局。因此需要将 TransactionDetailSheet 的样式和布局模式抽取为通用的 PopupContainer v2 组件，提供固定头部和底部的能力，方便在项目中复用。
+
+## What Changes
+
+- 创建新的 `PopupContainerV2.vue` 通用弹窗组件
+  - 使用 TransactionDetailSheet 的样式风格（`borderTopLeftRadius: 16px`, Inter 字体, `#ffffff` / `#18181b` 背景）
+  - 提供固定头部区域（标题 + 可选关闭按钮）
+  - 提供可滚动内容区域（default 插槽）
+  - 提供固定底部区域（footer 插槽）
+  - 支持暗色模式
+- 重构 `TransactionDetailSheet.vue` 使用新的 PopupContainerV2 组件
+  - 移除原有的头部和布局代码
+  - 将内容和操作按钮迁移到对应插槽
+  - 保持所有业务逻辑和功能不变
+
+## Capabilities
+
+### New Capabilities
+
+- `popup-container-v2`: 新的通用弹窗组件，提供固定头部/底部布局，采用 TransactionDetailSheet 的样式风格
+
+### Modified Capabilities
+
+- `transaction-detail-ui`: TransactionDetailSheet 的 UI 布局从直接使用 van-popup 改为使用 PopupContainerV2，头部和底部固定，内容区域可滚动
+
+## Impact
+
+- **新增文件**: `Web/src/components/PopupContainerV2.vue`
+- **受影响文件**: `Web/src/components/Transaction/TransactionDetailSheet.vue`
+- **用户影响**: 改善交易详情弹窗的交互体验，头部和操作按钮始终可见
+- **可复用性**: 新组件可用于项目中其他需要固定头部/底部的弹窗场景
+- **兼容性**: TransactionDetailSheet 对外 API（props、events）保持不变，不影响调用方
--- a/openspec/changes/archive/2026-02-20-refactor-popup-container-component/specs/transaction-detail-ui/spec.md
+++ b/openspec/changes/archive/2026-02-20-refactor-popup-container-component/specs/transaction-detail-ui/spec.md
@@ -0,0 +1,119 @@
+## ADDED Requirements
+
+### Requirement: PopupContainerV2 提供固定布局能力
+
+PopupContainerV2 组件 SHALL 提供固定头部、可滚动内容、固定底部的布局模式，并采用 TransactionDetailSheet 的样式风格（16px 圆角、Inter 字体、纯白背景）。
+
+#### Scenario: PopupContainerV2 基础结构
+
+- **WHEN** 使用 PopupContainerV2 组件
+- **THEN** 组件基于 van-popup 实现底部弹窗
+- **THEN** 弹窗顶部圆角为 16px（borderTopLeftRadius 和 borderTopRightRadius）
+- **THEN** 背景色为 #ffffff（亮色模式）或 #18181b（暗色模式）
+
+#### Scenario: PopupContainerV2 固定头部
+
+- **WHEN** 传入 title prop
+- **THEN** 头部显示标题文本，字体为 Inter，18px，font-weight 600
+- **THEN** 头部右侧显示关闭按钮（van-icon cross）
+- **THEN** 头部固定在顶部，不随内容滚动
+
+#### Scenario: PopupContainerV2 可滚动内容区域
+
+- **WHEN** 在 default 插槽中放置内容
+- **THEN** 内容区域可独立滚动
+- **THEN** 滚动时头部和底部保持固定
+- **THEN** 内容区域不提供默认 padding，由使用方控制
+
+#### Scenario: PopupContainerV2 固定底部
+
+- **WHEN** 在 footer 插槽中放置操作按钮
+- **THEN** 底部区域固定在底部，不随内容滚动
+- **THEN** 底部区域保持与内容区域的视觉分隔
+
+#### Scenario: PopupContainerV2 暗色模式支持
+
+- **WHEN** 系统启用暗色模式（prefers-color-scheme: dark）
+- **THEN** 背景色切换为 #18181b
+- **THEN** 标题文本颜色切换为 #fafafa
+- **THEN** 关闭按钮颜色切换为 #a1a1aa
+
+## MODIFIED Requirements
+
+### Requirement: TransactionDetailSheet 使用 PopupContainerV2 实现固定布局
+
+TransactionDetailSheet 组件 SHALL 使用 PopupContainerV2 组件实现底部弹窗，并确保头部标题和底部操作按钮固定不随内容滚动。
+
+#### Scenario: 打开交易详情弹窗
+
+- **WHEN** 用户点击交易记录打开详情弹窗
+- **THEN** 弹窗从底部弹出，使用 PopupContainerV2 组件
+- **THEN** 弹窗顶部圆角为 16px
+- **THEN** 头部显示固定标题"交易详情"，字体为 Inter 18px
+- **THEN** 底部固定显示"删除"和"保存"按钮
+- **THEN** 中间内容区域（金额、时间、备注、类型、分类）可独立滚动
+
+#### Scenario: 滚动交易详情内容
+
+- **WHEN** 用户在交易详情弹窗中滚动内容
+- **THEN** 头部标题始终固定在顶部可见
+- **THEN** 底部操作按钮（删除、保存）始终固定在底部可见
+- **THEN** 只有中间内容区域发生滚动
+
+#### Scenario: 展开分类选择器后滚动
+
+- **WHEN** 用户点击"分类"字段展开分类选择器
+- **THEN** 分类选择器在内容区域内展开
+- **THEN** 如果内容超出可视区域，用户可以滚动查看所有分类选项
+- **THEN** 头部标题和底部按钮仍然保持固定
+
+### Requirement: 保持现有功能和交互不变
+
+TransactionDetailSheet 组件在重构后 SHALL 保持所有现有的功能和交互逻辑不变，包括但不限于金额编辑、日期选择、分类选择、保存、删除等操作。
+
+#### Scenario: 金额编辑功能保持不变
+
+- **WHEN** 用户点击金额数值进入编辑模式
+- **THEN** 金额输入框自动聚焦并选中当前值
+- **THEN** 用户输入新金额后失焦时自动格式化为两位小数
+
+#### Scenario: 日期时间选择功能保持不变
+
+- **WHEN** 用户点击"时间"字段
+- **THEN** 弹出 van-datetime-picker 日期时间选择器
+- **THEN** 选择器显示在最顶层（不受 PopupContainerV2 层级影响）
+- **THEN** 确认后时间更新为选择的值
+
+#### Scenario: 分类选择功能保持不变
+
+- **WHEN** 用户点击"分类"字段
+- **THEN** 展开 ClassifySelector 组件
+- **THEN** 用户可以选择分类
+- **THEN** 选择后自动触发保存
+
+#### Scenario: 保存和删除功能保持不变
+
+- **WHEN** 用户点击"保存"按钮
+- **THEN** 验证必填字段（金额、分类、时间）
+- **THEN** 调用 updateTransaction API 更新数据
+- **THEN** 成功后显示提示并关闭弹窗
+- **WHEN** 用户点击"删除"按钮
+- **THEN** 显示确认对话框
+- **THEN** 确认后调用 deleteTransaction API 删除数据
+- **THEN** 成功后显示提示并关闭弹窗
+
+### Requirement: 组件对外 API 兼容
+
+TransactionDetailSheet 组件的 props 和 events SHALL 保持与重构前完全一致，确保零破坏性变更。
+
+#### Scenario: Props 保持不变
+
+- **WHEN** 父组件传递 `show` 和 `transaction` props
+- **THEN** TransactionDetailSheet 正常接收并响应这些 props
+- **THEN** 不需要修改任何调用方代码
+
+#### Scenario: Events 保持不变
+
+- **WHEN** 用户保存或删除交易
+- **THEN** TransactionDetailSheet 触发 `update:show`, `save`, `delete` 事件
+- **THEN** 事件参数格式与重构前完全一致
--- a/openspec/changes/archive/2026-02-20-refactor-popup-container-component/tasks.md
+++ b/openspec/changes/archive/2026-02-20-refactor-popup-container-component/tasks.md
@@ -0,0 +1,60 @@
+## 1. 创建 PopupContainerV2.vue 组件
+
+- [x] 1.1 创建文件 `Web/src/components/PopupContainerV2.vue`
+- [x] 1.2 实现基础结构（基于 van-popup，16px 圆角，#ffffff / #18181b 背景）
+- [x] 1.3 实现固定头部区域（标题 + 关闭按钮，Inter 18px font-weight 600）
+- [x] 1.4 实现可滚动内容区域（default 插槽，flex: 1, overflow-y: auto）
+- [x] 1.5 实现固定底部区域（footer 插槽，border-top 分隔线）
+- [x] 1.6 实现暗色模式支持（@media prefers-color-scheme: dark）
+- [x] 1.7 添加组件文档注释（说明 API、使用示例、与 v1 的区别）
+
+## 2. 重构 TransactionDetailSheet.vue 使用 PopupContainerV2
+
+- [x] 2.1 引入 PopupContainerV2 组件
+- [x] 2.2 将 van-popup 替换为 PopupContainerV2
+- [x] 2.3 移除自定义 `.sheet-header` 头部区域（使用 PopupContainerV2 的 title prop）
+- [x] 2.4 将金额区域、表单区域、分类选择器保留在 default 插槽中
+- [x] 2.5 将操作按钮区域（删除、保存）移入 PopupContainerV2 的 `#footer` 插槽
+- [x] 2.6 移除 handleClose 方法（PopupContainerV2 自动处理）
+
+## 3. 调整 TransactionDetailSheet 样式
+
+- [x] 3.1 移除 `.transaction-detail-sheet` 外层容器样式
+- [x] 3.2 调整各内容区域的 padding（金额区域、表单区域、分类选择器）
+- [x] 3.3 移除 `.sheet-header` 相关样式
+- [x] 3.4 调整暗色模式样式（移除已由 PopupContainerV2 处理的部分）
+
+## 4. 功能验证
+
+- [x] 4.1 测试弹窗打开/关闭功能
+- [x] 4.2 测试金额编辑功能（点击进入编辑模式、输入、失焦格式化）
+- [x] 4.3 测试日期时间选择功能（弹出选择器、确认更新）
+- [x] 4.4 测试类型切换功能（支出/收入/不计）
+- [x] 4.5 测试分类选择功能（展开选择器、选择分类、自动保存）
+- [x] 4.6 测试备注输入功能
+- [x] 4.7 测试保存功能（验证、API 调用、成功提示）
+- [x] 4.8 测试删除功能（确认对话框、API 调用、成功提示）
+
+## 5. 布局验证
+
+- [x] 5.1 验证头部标题固定不滚动
+- [x] 5.2 验证底部操作按钮固定不滚动
+- [x] 5.3 验证内容区域可独立滚动
+- [x] 5.4 验证分类选择器展开后的滚动体验
+- [x] 5.5 验证不同内容长度下的布局表现
+- [x] 5.6 验证弹窗圆角为 16px
+- [x] 5.7 验证标题字体为 Inter 18px font-weight 600
+
+## 6. 兼容性验证
+
+- [x] 6.1 验证 Props 接口不变（show, transaction）
+- [x] 6.2 验证 Events 接口不变（update:show, save, delete）
+- [x] 6.3 验证调用方无需修改代码
+- [x] 6.4 测试日期选择器弹窗的 z-index 层级（确保在 PopupContainerV2 之上）
+- [x] 6.5 验证暗色模式下的样式表现
+
+## 7. 清理和文档
+
+- [x] 7.1 移除不再使用的代码和注释
+- [x] 7.2 确保代码符合项目 ESLint 规范（`pnpm lint`）
+- [x] 7.3 在本地运行前端项目验证无报错（`pnpm build`）
--- a/openspec/specs/transaction-detail-ui/spec.md
+++ b/openspec/specs/transaction-detail-ui/spec.md
@@ -0,0 +1,119 @@
+## ADDED Requirements
+
+### Requirement: PopupContainerV2 提供固定布局能力
+
+PopupContainerV2 组件 SHALL 提供固定头部、可滚动内容、固定底部的布局模式，并采用 TransactionDetailSheet 的样式风格（16px 圆角、Inter 字体、纯白背景）。
+
+#### Scenario: PopupContainerV2 基础结构
+
+- **WHEN** 使用 PopupContainerV2 组件
+- **THEN** 组件基于 van-popup 实现底部弹窗
+- **THEN** 弹窗顶部圆角为 16px（borderTopLeftRadius 和 borderTopRightRadius）
+- **THEN** 背景色为 #ffffff（亮色模式）或 #18181b（暗色模式）
+
+#### Scenario: PopupContainerV2 固定头部
+
+- **WHEN** 传入 title prop
+- **THEN** 头部显示标题文本，字体为 Inter，18px，font-weight 600
+- **THEN** 头部右侧显示关闭按钮（van-icon cross）
+- **THEN** 头部固定在顶部，不随内容滚动
+
+#### Scenario: PopupContainerV2 可滚动内容区域
+
+- **WHEN** 在 default 插槽中放置内容
+- **THEN** 内容区域可独立滚动
+- **THEN** 滚动时头部和底部保持固定
+- **THEN** 内容区域不提供默认 padding，由使用方控制
+
+#### Scenario: PopupContainerV2 固定底部
+
+- **WHEN** 在 footer 插槽中放置操作按钮
+- **THEN** 底部区域固定在底部，不随内容滚动
+- **THEN** 底部区域保持与内容区域的视觉分隔
+
+#### Scenario: PopupContainerV2 暗色模式支持
+
+- **WHEN** 系统启用暗色模式（prefers-color-scheme: dark）
+- **THEN** 背景色切换为 #18181b
+- **THEN** 标题文本颜色切换为 #fafafa
+- **THEN** 关闭按钮颜色切换为 #a1a1aa
+
+## MODIFIED Requirements
+
+### Requirement: TransactionDetailSheet 使用 PopupContainerV2 实现固定布局
+
+TransactionDetailSheet 组件 SHALL 使用 PopupContainerV2 组件实现底部弹窗，并确保头部标题和底部操作按钮固定不随内容滚动。
+
+#### Scenario: 打开交易详情弹窗
+
+- **WHEN** 用户点击交易记录打开详情弹窗
+- **THEN** 弹窗从底部弹出，使用 PopupContainerV2 组件
+- **THEN** 弹窗顶部圆角为 16px
+- **THEN** 头部显示固定标题"交易详情"，字体为 Inter 18px
+- **THEN** 底部固定显示"删除"和"保存"按钮
+- **THEN** 中间内容区域（金额、时间、备注、类型、分类）可独立滚动
+
+#### Scenario: 滚动交易详情内容
+
+- **WHEN** 用户在交易详情弹窗中滚动内容
+- **THEN** 头部标题始终固定在顶部可见
+- **THEN** 底部操作按钮（删除、保存）始终固定在底部可见
+- **THEN** 只有中间内容区域发生滚动
+
+#### Scenario: 展开分类选择器后滚动
+
+- **WHEN** 用户点击"分类"字段展开分类选择器
+- **THEN** 分类选择器在内容区域内展开
+- **THEN** 如果内容超出可视区域，用户可以滚动查看所有分类选项
+- **THEN** 头部标题和底部按钮仍然保持固定
+
+### Requirement: 保持现有功能和交互不变
+
+TransactionDetailSheet 组件在重构后 SHALL 保持所有现有的功能和交互逻辑不变，包括但不限于金额编辑、日期选择、分类选择、保存、删除等操作。
+
+#### Scenario: 金额编辑功能保持不变
+
+- **WHEN** 用户点击金额数值进入编辑模式
+- **THEN** 金额输入框自动聚焦并选中当前值
+- **THEN** 用户输入新金额后失焦时自动格式化为两位小数
+
+#### Scenario: 日期时间选择功能保持不变
+
+- **WHEN** 用户点击"时间"字段
+- **THEN** 弹出 van-datetime-picker 日期时间选择器
+- **THEN** 选择器显示在最顶层（不受 PopupContainerV2 层级影响）
+- **THEN** 确认后时间更新为选择的值
+
+#### Scenario: 分类选择功能保持不变
+
+- **WHEN** 用户点击"分类"字段
+- **THEN** 展开 ClassifySelector 组件
+- **THEN** 用户可以选择分类
+- **THEN** 选择后自动触发保存
+
+#### Scenario: 保存和删除功能保持不变
+
+- **WHEN** 用户点击"保存"按钮
+- **THEN** 验证必填字段（金额、分类、时间）
+- **THEN** 调用 updateTransaction API 更新数据
+- **THEN** 成功后显示提示并关闭弹窗
+- **WHEN** 用户点击"删除"按钮
+- **THEN** 显示确认对话框
+- **THEN** 确认后调用 deleteTransaction API 删除数据
+- **THEN** 成功后显示提示并关闭弹窗
+
+### Requirement: 组件对外 API 兼容
+
+TransactionDetailSheet 组件的 props 和 events SHALL 保持与重构前完全一致，确保零破坏性变更。
+
+#### Scenario: Props 保持不变
+
+- **WHEN** 父组件传递 `show` 和 `transaction` props
+- **THEN** TransactionDetailSheet 正常接收并响应这些 props
+- **THEN** 不需要修改任何调用方代码
+
+#### Scenario: Events 保持不变
+
+- **WHEN** 用户保存或删除交易
+- **THEN** TransactionDetailSheet 触发 `update:show`, `save`, `delete` 事件
+- **THEN** 事件参数格式与重构前完全一致