EmailBill/openspec/changes/refactor-bill-list-component/design.md

Context

当前 EmailBill 项目中存在两个 TransactionList.vue 实现：

1. 旧版（Web/src/components/TransactionList.vue）：传统一行一卡片布局，功能完整但样式较旧
2. v2 版（Web/src/views/calendarV2/modules/TransactionList.vue）：现代卡片式设计，视觉层次更好

两个组件分别服务不同页面，导致：

• 代码重复（格式化、API 调用、交互逻辑）
• 样式不一致（用户体验割裂）
• 维护成本高（修改需同步两处）

技术栈约束：

• Vue 3 Composition API + <script setup> (JavaScript)
• Vant UI 组件库（移动端）
• Pinia 状态管理
• 后端 API：@/api/transactionRecord

重要说明：

• 项目使用 JavaScript 而非 TypeScript
• 使用 JSDoc 注释提供类型提示
• Props 和 Emits 使用 defineProps() 和 defineEmits() 的对象语法

设计目标： 创建统一的 BillListComponent.vue，整合两者优点，高内聚设计，支持筛选、排序、分页、左滑删除、详情查看。

Goals / Non-Goals

Goals:

• 创建可复用的账单列表组件 BillListComponent.vue（位于 Web/src/components/Bill/）
• 基于 v2 风格，但调整为紧凑列表（非一行一卡片）
• 内置筛选（类型、分类、日期范围）、排序（金额、时间）、分页加载
• 支持左滑删除（van-swipe-cell）、点击详情（emit 事件）
• 保留旧版的特殊功能（checkbox 选择模式）
• 迁移所有使用旧组件的页面到新组件
• 删除旧版 Web/src/components/TransactionList.vue

Non-Goals:

• 不改变后端 API 接口
• 不涉及新增数据字段
• 不处理账单编辑功能（仅展示和删除）
• 暂不支持拖拽排序

Decisions

决策 1：组件命名和位置

选择：Web/src/components/Bill/BillListComponent.vue

理由：

• 放在 Bill/ 目录下与现有 BillForm.vue、ManualBillAdd.vue 等保持一致
• 命名为 BillListComponent 而非 TransactionList，避免与旧组件混淆
• 符合项目 BEM 命名规范

备选方案：

• 直接覆盖旧版 TransactionList.vue → 拒绝：迁移期间需要并存，且容易引起冲突

决策 2：Props 设计（高内聚 vs 灵活配置）

选择：高内聚 - 组件内部管理筛选、排序、分页状态

Props 定义：

// 使用 defineProps 对象语法 + JSDoc
const props = defineProps({
  // 数据源模式
  dataSource: {
    type: String, // 'api' | 'custom'
    default: 'api'
  },
  
  // API 模式参数
  apiParams: {
    type: Object, // { dateRange?: [string, string], category?: string, type?: 0|1|2 }
    default: () => ({})
  },
  
  // Custom 模式参数
  transactions: {
    type: Array, // Transaction[]
    default: () => []
  },
  
  // 功能开关
  showDelete: {
    type: Boolean,
    default: true
  },
  showCheckbox: {
    type: Boolean,
    default: false
  },
  enableFilter: {
    type: Boolean,
    default: true
  },
  enableSort: {
    type: Boolean,
    default: true
  },
  
  // 样式配置
  compact: {
    type: Boolean,
    default: true
  },
  
  // 多选状态
  selectedIds: {
    type: Set,
    default: () => new Set()
  }
})

理由：

• 大部分场景只需传 apiParams，组件自动处理筛选、排序、分页
• dataSource='custom' 模式兼容特殊场景（如离线数据、缓存数据）
• 功能开关满足不同页面需求（如 TransactionsRecord 需要 checkbox）

备选方案：

• 低内聚（父组件管理所有状态）→ 拒绝：每个使用方都要重复实现筛选、排序逻辑，违背复用目标

决策 3：筛选 UI 实现

选择：van-dropdown-menu + van-popup（日期选择器）

布局：

[类型 ▼] [分类 ▼] [日期 ▼] [排序 ▼]

理由：

• Vant 的 van-dropdown-menu 适合移动端，节省空间
• 日期范围选择使用 van-calendar 弹出层
• 与项目现有 UI 风格一致

备选方案：

• 使用 van-tabs 切换筛选项 → 拒绝：占用空间大，不适合同时筛选多个维度

决策 4：数据加载策略

选择：虚拟滚动 + 分页加载（van-list）

实现：

• 初始加载 20 条
• 滚动到底部触发 @load 事件，追加 20 条
• 筛选/排序变更时，重置列表并重新加载

理由：

• Vant 的 van-list 内置分页逻辑，简单易用
• 账单数据量通常不大（日常使用 < 1000 条），无需复杂虚拟滚动库

备选方案：

• 一次性加载全部数据 → 拒绝：账单数量多时性能差

决策 5：删除功能的事务处理

选择：组件内部调用 deleteTransaction API，删除成功后 emit 事件并派发全局事件

流程：

const handleDelete = async (transaction) => {
  await showConfirmDialog({ message: '确定删除?' })
  await deleteTransaction(transaction.id)  // API 调用
  emit('delete', transaction.id)           // 通知父组件
  window.dispatchEvent(new CustomEvent('transaction-deleted', { detail: transaction.id }))  // 全局事件
  // 刷新当前列表
}

理由：

• 保持与旧版一致的删除逻辑（已验证可用）
• 全局事件通知其他组件刷新（如统计图表）
• 父组件可通过 @delete 监听执行额外逻辑

备选方案：

• 父组件负责删除 → 拒绝：增加使用成本，每个页面都要实现删除逻辑

决策 6：样式调整（紧凑列表）

选择：修改 v2 的卡片布局，减少卡片间距和内边距

调整细节：

.bill-card {
  margin-top: 6px;        // 原 10px
  padding: 10px 12px;     // 原 var(--spacing-xl) (约 16px)
  gap: 10px;              // 原 14px
}

理由：

• v2 原始设计间距较大，适合日历单日视图
• 列表视图需要更紧凑以显示更多条目
• 保留 v2 的视觉元素（图标、标签、颜色）

Risks / Trade-offs

风险 1：迁移期间功能遗漏

风险：旧版组件可能有未文档化的特殊用法，迁移时遗漏
缓解措施：

• 迁移前全面梳理旧版所有 props 和 emits
• 保留 showCheckbox 和 selectedIds 功能（TransactionsRecord 批量操作依赖）
• 迁移分阶段进行，逐个页面验证

风险 2：性能退化

风险：新增筛选、排序逻辑可能影响渲染性能
缓解措施：

• 使用 computed 缓存筛选结果
• 大数据量时依赖后端 API 筛选（而非前端过滤）
• 测试场景：1000+ 条数据的滚动流畅度

风险 3：样式兼容性

风险：不同页面的主题色、暗黑模式可能导致显示异常
缓解措施：

• 使用 CSS 变量（var(--van-danger-color) 等），自动适配主题
• 测试暗黑模式下的视觉效果
• 提供 themeOverride prop 允许父组件覆盖样式

Trade-off：组件复杂度 vs 易用性

权衡：高内聚设计会增加组件内部复杂度（300+ 行代码）
选择：接受复杂度换取易用性
理由：

• 简化所有使用方的代码（10+ 处引用）
• 统一维护点，避免分散的重复逻辑
• 内部复杂度可通过单元测试覆盖

Migration Plan

阶段 1：组件开发（第 1-2 天）

1. 创建 Web/src/components/Bill/BillListComponent.vue
2. 实现核心功能：数据展示、分页、左滑删除
3. 实现筛选、排序 UI 和逻辑
4. 单元测试覆盖（Vue Test Utils）

阶段 2：试点迁移（第 3 天）

1. 选择一个简单页面试点（如 BillAnalysisView.vue）
2. 替换旧组件为新组件
3. 验证功能完整性和视觉效果
4. 修复发现的问题

阶段 3：全面迁移（第 4-5 天）

1. 迁移 TransactionsRecord.vue（重点验证 checkbox 功能）
2. 迁移其他引用旧组件的页面
3. 回归测试所有相关页面

阶段 4：清理（第 6 天）

1. 删除旧版 Web/src/components/TransactionList.vue
2. 删除 Web/src/views/calendarV2/modules/TransactionList.vue（如不再需要）
3. 更新文档和 AGENTS.md

Rollback 策略

• 保留旧版组件直到所有页面迁移完成
• 使用 Git 分支隔离迁移工作
• 如发现严重问题，可快速恢复旧版（修改 import 路径）

Open Questions

1. calendarV2 的 TransactionList 是否有特殊逻辑？
   需要确认 calendarV2 是否依赖其特有功能（如 Smart 按钮、日期联动）。如果有，可能需要保留该文件，仅迁移其他页面。

2. 是否需要支持自定义列渲染？
   当前设计固定显示字段（reason, amount, classify 等）。未来是否需要 slot 支持自定义？暂时不实现，等实际需求再扩展。

3. 筛选条件的持久化？
   用户设置的筛选条件是否需要保存到 localStorage？当前设计不持久化，每次刷新恢复默认。