EmailBill/openspec/changes/archive/2026-02-15-refactor-bill-list-component/tasks.md

1. 组件基础结构搭建

• 1.1 创建 Web/src/components/Bill/BillListComponent.vue 文件
• 1.2 定义 TypeScript Props 接口（dataSource, apiParams, transactions, showDelete, showCheckbox, enableFilter, enableSort, compact）
• 1.3 定义 Emits 接口（load, click, delete, update:selectedIds）
• 1.4 创建组件骨架（template、script setup、style scoped）
• 1.5 添加必要的 Vant 组件导入（van-list, van-swipe-cell, van-dropdown-menu, van-loading, van-empty, van-icon, van-tag）

2. 数据管理和状态

• 2.1 实现 dataSource 模式切换逻辑（api vs custom）
• 2.2 创建响应式数据状态（transactions, loading, finished, page, pageSize）
• 2.3 实现筛选状态管理（selectedType, selectedCategory, dateRange, sortBy）
• 2.4 实现多选状态管理（localSelectedIds, 与 prop 同步）
• 2.5 创建 computed 计算属性用于筛选和排序逻辑

3. API 数据加载

• 3.1 导入 @/api/transactionRecord 的相关 API 方法
• 3.2 实现初始加载逻辑（fetchTransactions 方法）
• 3.3 实现分页加载逻辑（onLoad 方法，支持 van-list）
• 3.4 实现筛选条件变更时的数据重载逻辑
• 3.5 处理 API 错误和加载状态

4. 筛选功能实现

• 4.1 创建筛选栏 UI（van-dropdown-menu，包含类型、分类、日期、排序四个下拉菜单）
• 4.2 实现类型筛选（支出、收入、不计入、全部）
• 4.3 实现分类筛选（动态获取分类列表或预设常用分类）
• 4.4 实现日期范围筛选（使用 van-calendar 弹出层）
• 4.5 实现排序功能（金额降序、金额升序、时间降序、时间升序）
• 4.6 添加筛选重置功能
• 4.7 根据 enableFilter prop 控制筛选栏显示/隐藏

5. 账单列表展示

• 5.1 创建账单卡片布局（基于 v2 风格，左侧图标、中间内容、右侧金额）
• 5.2 实现紧凑模式样式（减少卡片间距至 6px，内边距至 10px）
• 5.3 实现账单图标显示（根据分类映射图标，使用 getIconByClassify 方法）
• 5.4 实现金额格式化（带符号、颜色区分支出/收入）
• 5.5 实现类型标签显示（右上角，支出红色、收入绿色）
• 5.6 实现时间格式化显示（HH:MM 或 YYYY-MM-DD HH:MM）
• 5.7 实现空状态展示（van-empty，带友好文案）

6. 左滑删除功能

• 6.1 为每个账单项添加 van-swipe-cell 包裹
• 6.2 创建删除按钮插槽（右侧滑出，红色按钮）
• 6.3 实现删除确认对话框（van-dialog）
• 6.4 实现删除 API 调用（deleteTransaction）
• 6.5 删除成功后更新本地列表（移除对应项）
• 6.6 显示删除成功/失败提示（van-toast）
• 6.7 派发全局事件 transaction-deleted
• 6.8 触发父组件 @delete 事件
• 6.9 根据 showDelete prop 控制删除功能启用/禁用

7. 点击详情功能

• 7.1 为账单卡片添加 @click 事件监听
• 7.2 实现 handleClick 方法，触发 @click 事件并传递账单对象
• 7.3 确保点击复选框或删除按钮时不触发详情事件（事件冒泡处理）

8. 多选功能

• 8.1 在账单项左侧添加 van-checkbox（根据 showCheckbox prop 控制显示）
• 8.2 实现 checkbox 选中状态与 selectedIds prop 同步
• 8.3 实现 toggleSelection 方法（切换选中状态）
• 8.4 触发 @update:selectedIds 事件更新父组件状态
• 8.5 添加全选/取消全选功能（可选，视需求）

9. 样式和主题适配

• 9.1 使用 SCSS 编写组件样式
• 9.2 使用 CSS 变量适配 Vant 主题（var(--van-danger-color) 等）
• 9.3 实现暗黑模式适配（检查暗色背景下的显示效果）
• 9.4 根据 compact prop 调整卡片间距和内边距
• 9.5 确保移动端响应式布局（处理小屏幕、横屏等情况）
• 9.6 添加过渡动画（卡片删除、列表加载等）

10. 页面迁移 - TransactionsRecord

• 10.1 在 TransactionsRecord.vue 中导入新组件 BillListComponent
• 10.2 替换旧 TransactionList 组件为 BillListComponent
• 10.3 传递必要的 props（showCheckbox, selectedIds, apiParams）
• 10.4 更新事件监听（@click, @delete, @update:selectedIds）
• 10.5 验证批量操作功能正常（选中、删除、导出等）
• 10.6 测试页面功能完整性

11. 页面迁移 - BillAnalysisView

• 11.1 在 BillAnalysisView.vue 中导入新组件 BillListComponent (页面未使用旧组件，跳过)
• 11.2 替换旧组件为 BillListComponent (页面未使用旧组件，跳过)
• 11.3 传递筛选参数（如按分类、日期范围）(页面未使用旧组件，跳过)
• 11.4 更新事件监听 (页面未使用旧组件，跳过)
• 11.5 测试页面功能正常 (页面未使用旧组件，跳过)

12. 页面迁移 - 其他引用页面

• 12.1 使用 grep 搜索所有引用旧 TransactionList 的文件
• 12.2 逐个页面进行迁移（重复步骤 10-11 的流程）
• 12.3 验证每个页面的功能和样式
• 12.4 检查是否有遗漏的引用

13. CalendarV2 模块处理

• 13.1 评估 calendarV2/modules/TransactionList.vue 的特殊功能（Smart 按钮、日期联动等）
• 13.2 决定是保留该文件还是迁移到新组件
• 13.3 如保留，添加注释说明其特殊性；如迁移，确保功能对等
• 13.4 测试 CalendarV2 的交易列表功能

14. 清理旧代码

• 14.1 删除 Web/src/components/TransactionList.vue
• 14.2 检查并删除相关的未使用导入
• 14.3 更新 AGENTS.md 或相关文档，说明新组件的使用方式
• 14.4 提交代码变更（Git commit）

15. 测试和验证

• 15.1 编写单元测试（Vue Test Utils，测试 props、emits、筛选、排序逻辑）
• 15.2 手动测试所有功能点（筛选、排序、分页、删除、多选、详情）
• 15.3 测试暗黑模式显示效果
• 15.4 测试不同屏幕尺寸的响应式布局
• 15.5 测试 API 错误处理和边界情况（空数据、网络错误等）
• 15.6 回归测试所有迁移页面，确保无功能丢失
• 15.7 性能测试（加载 1000+ 条数据时的流畅度）

16. 文档和收尾

• 16.1 编写组件使用文档（Props、Emits、Slots 说明）
• 16.2 更新 Web/src/views/AGENTS.md（如有）
• 16.3 在组件文件顶部添加 JSDoc 注释
• 16.4 代码格式化（pnpm lint）
• 16.5 构建测试（pnpm build）
• 16.6 最终代码审查