flutter: Transactions Phase B1 — grouping persistence + unit test

docs/FEATURE_TX_FILTERS_GROUPING.md

@@ -0,0 +1,78 @@
+# Transactions Filters & Grouping — Phase B Design (草案)
+
+Purpose
+- Deliver practical, performant filtering + grouping for transactions.
+- Keep UI declarative, leverage existing providers; avoid duplicating domain rules.
+
+Scope
+- Filters: text (描述/备注/收款方), 日期范围, 类型(支出/收入/转账), 账户, 分类, 标签, 金额区间。
+- Grouping: 按 日期 / 分类 / 账户；每组显示小计，总计在页眉/页脚。
+- Persist: 轻量本地记忆最近一次筛选与分组（per-ledger）。
+- Non-goals: 复杂多级排序、跨家庭聚合、导出（独立PR）。
+
+UX Outline
+- TransactionsScreen 顶部显示 FilterBar（收起/展开）。
+- FilterBar：
+  - 搜索框（回车触发）、“筛选”按钮打开面板（日期/类型/账户/分类/标签/金额）、“重置”按钮。
+  - 右侧“分组切换”：日期/分类/账户；在移动端为 Segmented 形式。
+- 列表：
+  - 分组头包含：组名 + 小计金额（正/负色），可折叠。
+  - 空状态支持“清空筛选”。
+
+State & Providers
+- transactionControllerProvider（现有）：
+  - 扩展：`applyFilter(TransactionQuery q)`、`clearFilter()`、`setGrouping(Grouping g)`、`toggleGroupCollapse(key)`。
+  - 状态新增：`currentQuery`、`grouping`、`groupCollapse: Set<String>`。
+- Query 模型（新）：
+  ```dart
+  class TransactionQuery {
+    final String? text;
+    final DateTimeRange? dateRange;
+    final Set<TransactionType>? types;
+    final Set<String>? accountIds;
+    final Set<String>? categoryIds;
+    final Set<String>? tagIds;
+    final double? amountMin;
+    final double? amountMax;
+    const TransactionQuery({ ... });
+    TransactionQuery copyWith(...);
+    bool get isEmpty;
+  }
+  ```
+- Grouping（新枚举）：`date | category | account`。
+- 组合选择器：账户/分类/标签用现有 providers 源数据，支持多选（Chip/BottomSheet）。
+
+Data Flow
+- UI → controller.applyFilter(query) → 计算/筛选 in-memory（Phase B）
+- 未来 Phase C：若列表很大，落地到服务端 query（分页 + 去抖）。
+
+API/Backend Impact
+- Phase B：无服务端改动。
+- Phase C（另案）：增量新增 `/transactions/search` 支持字段与分页；Rust 侧生成 SQLx 查询 + .sqlx 更新。
+
+Persistence
+- SharedPreferences key: `tx_ui_<ledgerId>_{query,grouping}`；
+- 在 initState 读取并应用。
+
+Accessibility & i18n
+- 分组头可聚焦；筛选面板控件提供语义标签；所有文案纳入 i18n 字典（后续批量替换）。
+
+Performance
+- 过滤与分组在内存进行：
+  - 先按日期预分桶（Map<Date, List>）复用；
+  - 计算小计 O(n)；
+  - 大列表按需构建（ListView.builder）。
+
+Acceptance Criteria
+- 可对任意组合条件过滤，切换分组视图，显示正确小计与总计。
+- 刷新后保留上次筛选/分组。
+- analyzer 0 hard errors；tests 通过。
+
+Phasing
+- B1：完成 Query 模型 + 控制器 + UI 面板（不含服务端）。
+- B2：分组小计 + 折叠 + 持久化。
+- B3：微交互与过渡动画；边界测试。
+
+Risks / Out of Scope
+- 非线性金额转换/多货币换算（另案）。
+- 高维度组合过滤在低端机的性能（必要时分页）。

jive-flutter/lib/providers/transaction_provider.dart

@@ -4,11 +4,16 @@ import 'package:jive_money/services/api/transaction_service.dart';
 import 'package:jive_money/models/transaction.dart';
 import 'package:jive_money/models/transaction_filter.dart';
 import 'package:shared_preferences/shared_preferences.dart';
+<<<<<<< HEAD
+=======
 import 'package:jive_money/providers/ledger_provider.dart';
 
 enum TransactionGrouping { date, category, account }
+>>>>>>> origin/main
 
 /// 交易状态
+enum TransactionGrouping { date, category, account }
+
 class TransactionState {
   final List<Transaction> transactions;
   final List<Transaction> filteredTransactions;
@@ -18,6 +23,10 @@ class TransactionState {
   final int totalCount;
   final double totalIncome;
   final double totalExpense;
+<<<<<<< HEAD
+  // Phase B scaffolding: grouping + collapsed groups
+=======
+>>>>>>> origin/main
   final TransactionGrouping grouping;
   final Set<String> groupCollapse;
 
@@ -302,6 +311,65 @@ class TransactionController extends StateNotifier<TransactionState> {
     state = state.copyWith(error: null);
   }
 
+  /// 设置分组方式（Phase B）
+  void setGrouping(TransactionGrouping grouping) {
+    if (state.grouping == grouping) return;
+    state = state.copyWith(grouping: grouping);
+    _persistGrouping();
+  }
+
+  /// 切换分组折叠状态（Phase B）
+  void toggleGroupCollapse(String key) {
+    final collapsed = Set<String>.from(state.groupCollapse);
+    if (collapsed.contains(key)) {
+      collapsed.remove(key);
+    } else {
+      collapsed.add(key);
+    }
+    state = state.copyWith(groupCollapse: collapsed);
+    _persistGroupCollapse(collapsed);
+  }
+
+  // ---- View preference persistence (Phase B1) ----
+  Future<void> _loadViewPrefs() async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+      final groupingStr = prefs.getString("tx_grouping");
+      TransactionGrouping grouping = state.grouping;
+      if (groupingStr != null) {
+        grouping = TransactionGrouping.values.firstWhere(
+          (g) => g.name == groupingStr,
+          orElse: () => TransactionGrouping.date,
+        );
+      }
+      final collapsedList =
+          prefs.getStringList("tx_group_collapse") ?? const <String>[];
+      if (grouping != state.grouping ||
+          collapsedList.length != state.groupCollapse.length) {
+        state = state.copyWith(
+          grouping: grouping,
+          groupCollapse: collapsedList.toSet(),
+        );
+      }
+    } catch (_) {
+      // Ignore persistence errors
+    }
+  }
+
+  Future<void> _persistGrouping() async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+      await prefs.setString("tx_grouping", state.grouping.name);
+    } catch (_) {}
+  }
+
+  Future<void> _persistGroupCollapse(Set<String> collapsed) async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+      await prefs.setStringList("tx_group_collapse", collapsed.toList());
+    } catch (_) {}
+  }
+
   /// 更新状态并计算统计数据
   void _updateState(List<Transaction> transactions) {
     final filteredTransactions = state.filter != null

jive-flutter/lib/screens/dashboard/dashboard_screen.dart

@@ -86,7 +86,10 @@ class DashboardScreen extends ConsumerWidget {
             RecentTransactions(
               transactions: recentTransactions,
               onViewAll: () {
-                // 导航到交易页面
+                context.go(AppRoutes.transactions);
+              },
+              onFilter: () {
+                context.go(AppRoutes.transactions);
               },
             ),
             const SizedBox(height: 24),

jive-flutter/lib/screens/transactions/transactions_screen.dart

@@ -4,7 +4,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:jive_money/core/router/app_router.dart';
 import 'package:jive_money/providers/transaction_provider.dart';
-import 'package:jive_money/ui/components/transactions/transaction_list_item.dart';
+import 'package:jive_money/ui/components/transactions/transaction_list.dart';
 import 'package:jive_money/models/transaction.dart';
 
 class TransactionsScreen extends ConsumerStatefulWidget {
@@ -35,6 +35,7 @@ class _TransactionsScreenState extends ConsumerState<TransactionsScreen>
   @override
   Widget build(BuildContext context) {
     final transactionState = ref.watch(transactionControllerProvider);
+    final groupByDate = transactionState.grouping == TransactionGrouping.date;
 
     return Scaffold(
       appBar: AppBar(
@@ -49,6 +50,23 @@ class _TransactionsScreenState extends ConsumerState<TransactionsScreen>
           ],
         ),
         actions: [
+          PopupMenuButton<TransactionGrouping>(
+            tooltip: "分组方式",
+            onSelected: (g) {
+              ref.read(transactionControllerProvider.notifier).setGrouping(g);
+              if (g != TransactionGrouping.date) {
+                ScaffoldMessenger.of(context).showSnackBar(
+                  const SnackBar(content: Text("分类/账户分组预览中，暂以平铺显示")),
+                );
+              }
+            },
+            itemBuilder: (context) => const [
+              PopupMenuItem(value: TransactionGrouping.date, child: Text("按日期分组")),
+              PopupMenuItem(value: TransactionGrouping.category, child: Text("按分类分组(预览)")),
+              PopupMenuItem(value: TransactionGrouping.account, child: Text("按账户分组(预览)")),
+            ],
+            icon: const Icon(Icons.view_list),
+          ),
           IconButton(
             icon: const Icon(Icons.filter_list),
             onPressed: _showFilterDialog,
@@ -131,22 +149,27 @@ class _TransactionsScreenState extends ConsumerState<TransactionsScreen>
       return _buildEmptyState(type);
     }
 
-    return RefreshIndicator(
+    return TransactionList(
+      transactions: filtered,
+      groupByDate: groupByDate,
+      showSearchBar: true,
+      onSearch: (q) =>
+          ref.read(transactionControllerProvider.notifier).search(q),
+      onClearSearch: () =>
+          ref.read(transactionControllerProvider.notifier).search(''),
+      onToggleGroup: () {
+        final next = groupByDate ? TransactionGrouping.account : TransactionGrouping.date;
+        ref.read(transactionControllerProvider.notifier).setGrouping(next);
+        if (next != TransactionGrouping.date) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text("非日期分组预览中，暂以平铺显示")),
+          );
+        }
+      },
       onRefresh: () =>
           ref.read(transactionControllerProvider.notifier).refresh(),
-      child: ListView.builder(
-        padding: const EdgeInsets.only(bottom: 80),
-        itemCount: filtered.length,
-        itemBuilder: (context, index) {
-          final transaction = filtered[index];
-          return TransactionListItem(
-            transaction: transaction,
-            onTap: () {
-              context.go('${AppRoutes.transactions}/${transaction.id}');
-            },
-          );
-        },
-      ),
+      onTransactionTap: (t) =>
+          context.go('${AppRoutes.transactions}/${t.id}'),
     );
   }
 

jive-flutter/lib/ui/components/dashboard/recent_transactions.dart

@@ -5,6 +5,7 @@ import 'package:jive_money/models/transaction.dart';
 import 'package:jive_money/ui/components/cards/transaction_card.dart';
 
 class RecentTransactions extends StatelessWidget {
+  final VoidCallback? onFilter;
   final List<Transaction> transactions;
   final String title;
   final VoidCallback? onViewAll;
@@ -16,6 +17,7 @@ class RecentTransactions extends StatelessWidget {
     this.title = '最近交易',
     this.onViewAll,
     this.maxItems = 5,
+    this.onFilter,
   });
 
   @override
@@ -43,6 +45,12 @@ class RecentTransactions extends StatelessWidget {
                   ),
                 ),
                 const Spacer(),
+                if (onFilter != null)
+                  IconButton(
+                    tooltip: "筛选",
+                    icon: const Icon(Icons.filter_list),
+                    onPressed: onFilter,
+                  ),
                 if (onViewAll != null)
                   TextButton(
                     onPressed: onViewAll,
@@ -130,13 +138,15 @@ class GroupedRecentTransactions extends StatelessWidget {
   final List<Transaction> transactions;
   final String title;
   final VoidCallback? onViewAll;
+  final VoidCallback? onFilter;
   final int maxDays;
 
   const GroupedRecentTransactions({
     super.key,
     required this.transactions,
     this.title = '最近交易',
     this.onViewAll,
+    this.onFilter,
     this.maxDays = 3,
   });
 
@@ -166,6 +176,12 @@ class GroupedRecentTransactions extends StatelessWidget {
                   ),
                 ),
                 const Spacer(),
+                if (onFilter != null)
+                  IconButton(
+                    tooltip: "筛选",
+                    icon: const Icon(Icons.filter_list),
+                    onPressed: onFilter,
+                  ),
                 if (onViewAll != null)
                   TextButton(
                     onPressed: onViewAll,