velocity-pay-flutter/group-batches.md

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