progress on batches

group-batches.md

@@ -0,0 +1,83 @@
+# Plan: Groups & Batches Feature
+
+## API Surface (from Postman)
+
+### Groups
+- `GET /api/public/recipient-groups?userId={userId}` — list groups
+- `GET /api/public/recipient-groups/members?recipientGroupId={id}` — list members
+- `POST /api/public/recipient-groups` — create group
+  - Body: `{ name, description, userId, recipients: [{name, phoneNumber, latestProviderLabel, account}] }`
+
+### Batches
+- `GET /api/public/group-batches?recipientGroupId={id}&sort=createdAt,desc` — list batches
+- `GET /api/public/group-batches/items?groupBatchId={id}&sort=createdAt,desc` — list batch items
+- `POST /api/public/group-batches` — create batch (recipientGroupId, userId, currency, amount, paymentProcessorLabel, paymentProcessorName, paymentProcessorImage, transactionTemplate)
+- `POST /api/public/group-batches/{batchId}/confirm` — confirm batch
+- `POST /api/public/group-batches/{batchId}/request` — request batch (payment)
+- `POST /api/public/group-batches/{batchId}/poll` — poll batch status
+
+## Files To Create
+
+### Phase 1: Models
+- `lib/models/recipient_group_model.dart` — RecipientGroup, RecipientMember, CreateGroupRequest
+- `lib/models/group_batch_model.dart` — GroupBatch, GroupBatchItem, CreateBatchRequest (transactionTemplate typed as TransactionModel from lib/screens/transactions/transaction_model.dart), BatchActionRequest. No separate TransactionTemplate class needed.
+
+### Phase 2: Controllers
+- `lib/screens/groups/group_controller.dart` — ChangeNotifier, list/create groups, list members
+- `lib/screens/groups/batch_controller.dart` — ChangeNotifier, list/create batches, list items, confirm/request/poll
+
+### Phase 3: Screens
+- `lib/screens/groups/groups_screen.dart` — list all groups
+- `lib/screens/groups/group_create_screen.dart` — create group form (name, description, multiline textarea: one recipient per line as `name,account`; phoneNumber defaults to account value)
+- `lib/screens/groups/group_detail_screen.dart` — tabbed view: Batches first (default), Members second; receives RecipientGroup via extra; FAB on Batches tab to create new batch
+- `lib/screens/groups/batch_create_screen.dart` — create batch form (provider, processor, amount, currency); on success navigate to BatchDetailScreen passing created batch via extra
+- `lib/screens/groups/batch_detail_screen.dart` — batch items list + Confirm/Request/Poll action buttons
+- `lib/screens/groups/batch_item_screen.dart` — single batch item detail view
+
+### Phase 4: Integration
+- `lib/navbar.dart` — add Groups as 3rd nav item (index 2)
+- `lib/main.dart` — add routes + GroupController + BatchController providers
+
+## Routes
+- `/groups` → GroupsScreen
+- `/groups/create` → GroupCreateScreen
+- `/groups/:groupId` → GroupDetailScreen
+- `/groups/:groupId/batches/create` → BatchCreateScreen
+- `/groups/:groupId/batches/:batchId` → BatchDetailScreen
+- `/groups/:groupId/batches/:batchId/items/:itemId` → BatchItemScreen
+
+## Action Return Types
+- `createBatch` → `ApiResponse<GroupBatch>`
+- `confirmBatch` → `ApiResponse<GroupBatch>`
+- `requestBatch` → `ApiResponse<TransactionModel>` (reuses TransactionModel)
+- `pollBatch` → `ApiResponse<GroupBatch>`
+- List endpoints → `ApiResponse<PageableModel<T>>`
+
+## BatchDetailScreen Auto-Poll Logic
+After **Request** action:
+1. `requestBatch()` returns `TransactionModel`
+2. Check `transaction.pollingStatus` — if successful (e.g. `SUCCESS`, `COMPLETE`) → no poll needed, refresh batch
+3. Otherwise → auto-trigger `pollBatch()` immediately without user input
+4. If auto-poll fails (network error / non-terminal status) → show **Poll** button for manual retry
+5. Batch status from poll response drives UI state (show/hide action buttons)
+
+## Key Patterns
+- Controllers extend ChangeNotifier
+- Models use `@JsonSerializable` with generated `.g.dart` files
+- All network calls use `ApiResponse<T>` wrapping pattern (try/catch in controller)
+- Use `ListenableBuilder` in screens
+- Read `userId`/`token` from SharedPreferences
+- Pass extra data via GoRouter `extra:` parameter
+- `idempotencyKey` for batch actions generated as `"batch-{batchId}-{action}-{timestamp}"`
+- Navbar: add Groups at index 2, update `_handleTap` + `_calculateSelectedIndex`
+
+## Member Input Parsing (group_create_screen)
+- One recipient per line: `name,account`
+- `phoneNumber` defaults to `account` value
+- `latestProviderLabel` defaults to `""`
+
+## Decisions
+- `TransactionModel` reused as-is for `transactionTemplate` field — no wrapper class
+- No pagination on groups/batches lists in this iteration
+- No edit/delete for groups or batches in scope
+- Poll button only shown as manual fallback after auto-poll failure