ionic-planb-logistic-app-flutter/CHECKLIST.md

Plan B Logistics Flutter App - Implementation Checklist

Core Architecture & Setup

• CQRS API client with Result pattern
• Strict typing (no dynamic or untyped var)
• Serializable interface for all models
• Error handling with ApiError types
• HTTP client configuration
• API base URLs (query and command endpoints)
• Riverpod state management setup
• Provider architecture
• Responsive utilities and breakpoints
• Theme configuration (Svrnty design system)
• Material Design 3 implementation
• Dark and light themes

Authentication & Authorization

• Password Credentials OAuth2 flow with Keycloak
• Username/password login form
• JWT token management
• Secure token storage (flutter_secure_storage)
• Token validation and expiration checking
• User profile decoding from JWT
• Authentication guard in main.dart
• Login page UI with form validation
• Automatic token refresh on expiration
• Handle 401 responses with token refresh retry
• Implement logout with token revocation

Data Models

• Delivery model
• DeliveryRoute model (updated to match API)
• DeliveryAddress model
• DeliveryContact model
• DeliveryOrder model
• UserInfo model
• UserProfile model
• Command models (CompleteDelivery, MarkAsUncompleted, etc.)
• Query models with Serializable
• All models implement fromJson/toJson

API Integration

• Remove mock data from providers
• Get delivery routes endpoint
• Get deliveries by route endpoint
• Complete delivery command endpoint
• Mark delivery as uncompleted endpoint
• Bearer token injection in API requests
• Query parameter serialization
• Upload delivery picture endpoint
• Skip delivery command endpoint
• Implement pagination for routes
• Implement pagination for deliveries
• Add pull-to-refresh functionality
• Implement retry logic for failed requests

Pages & UI Components

Completed Pages

• Login page with username/password
• Routes page (list/grid view)
• Deliveries page (To Do/Delivered segments)
• Settings page

Pending Pages

• Delivery details page
• Photo capture/upload page
• Error pages (network error, not found, etc.)

UI Components

• Route card with progress indicator
• Delivery card with status chips
• Bottom sheet for delivery actions
• User profile menu
• Language selector
• Responsive grid/list layouts
• Extract reusable components to lib/components/
• Create DeliveryCard component
• Create RouteCard component
• Create CustomAppBar component
• Create LoadingIndicator component
• Create ErrorView component
• Create EmptyStateView component

Features

Completed Features

• Phone call integration (url_launcher)
• Maps/navigation integration (Google Maps)
• Mark delivery as completed
• Mark delivery as uncompleted
• Language switching (EN/FR)
• Responsive design (mobile/tablet/desktop)
• Pull-to-refresh on routes page

Pending Features

• Photo upload for delivery proof
• Skip delivery with reason
• View delivery photos
• Delivery history/timeline
• Offline mode support
• Cache management
• Push notifications
• Delivery signatures
• Barcode/QR code scanning

Internationalization (i18n)

• ARB files setup (English and French)
• 68+ translation keys defined
• Parameterized strings support
• Language provider in state management
• Replace ALL hardcoded strings in UI with translations
  • Login page strings
  • Routes page strings
  • Deliveries page strings
  • Settings page strings
  • Error messages
  • Button labels
  • Form validation messages
• Test language switching in all screens

Error Handling & UX

• Basic error display with SnackBar
• Loading states in providers
• Comprehensive error handling UI
• Specific error messages for different ApiErrorType
• Network connectivity detection
• Offline mode indicators
• Retry strategies with exponential backoff
• Error recovery flows
• User-friendly error messages
• Toast notifications for success/error

Routing & Navigation

• Basic Navigator.push navigation
• Route parameters passing
• Configure GoRouter
• Named routes
• Deep linking support
• Route guards for authentication
• Handle back navigation properly
• Navigation animations/transitions

Native Features

• Phone calls with url_launcher
• Maps integration with url_launcher
• Camera access with image_picker
• Photo gallery access
• File system access for photos
• Location services
• Background location tracking
• Local notifications

Testing

• Unit tests for AuthService
• Unit tests for CqrsApiClient
• Unit tests for data models
• Provider tests with ProviderContainer
• Widget tests for LoginPage
• Widget tests for RoutesPage
• Widget tests for DeliveriesPage
• Widget tests for SettingsPage
• Integration tests for auth flow
• Integration tests for delivery flow
• Golden tests for UI components
• Achieve >80% code coverage

Build Configuration

• Set up build flavors (dev, staging, prod)
• Environment-specific configurations
• API URL configuration per environment
• App signing for iOS
• App signing for Android
• Build scripts for CI/CD
• Icon and splash screen configuration
• Version management
• Build number automation

Performance Optimization

• Image caching (cached_network_image)
• List virtualization optimizations
• Lazy loading for deliveries
• Pagination implementation
• Memory leak detection
• App size optimization
• Startup time optimization
• Frame rate monitoring

Documentation

• CLAUDE.md project instructions
• README.md with project overview
• API documentation
• Component documentation
• Architecture documentation
• Deployment guide
• User manual
• Developer onboarding guide

Security

• Secure token storage
• No hardcoded secrets in code (client_secret removed)
• Public client configuration (no client secret in frontend)
• Certificate pinning
• Encryption for sensitive data
• Obfuscation for production builds
• Security audit
• Penetration testing
• OWASP compliance check

Deployment

• iOS App Store submission
• Android Play Store submission
• Internal testing distribution
• Beta testing program
• Production release
• Crash reporting (Sentry, Firebase Crashlytics)
• Analytics integration (Firebase Analytics)
• Remote configuration

Known Issues to Fix

• Fix macOS secure storage error (-34018)
• Update AppAuth deployment target (10.12 -> 10.13)
• Handle "Failed to foreground app" warning
• Add proper error boundaries
• Fix any linter warnings

Production Blockers (Critical)

• Authentication disabled (FIXED)
• Using mock data (FIXED)
• Photo upload not implemented
• Limited error handling
• No tests written
• Hardcoded strings instead of i18n
• No offline support

Priority Levels

HIGH PRIORITY (Must have for v1.0)

1. Replace hardcoded strings with i18n translations
2. Implement photo upload feature
3. Create delivery details page
4. Add comprehensive error handling
5. Write critical unit and widget tests
6. Implement automatic token refresh
7. Add skip delivery feature

MEDIUM PRIORITY (Should have for v1.0)

1. Configure GoRouter with named routes
2. Extract reusable components
3. Implement pagination
4. Add offline mode indicators
5. Set up build flavors
6. Add image caching

LOW PRIORITY (Nice to have for v1.0)

1. Performance optimizations
2. Golden tests
3. Enhanced animations
4. Advanced features (signatures, barcodes)
5. Push notifications

Version History

v0.1.0 (Current)

• Core architecture implemented
• Real API integration completed
• Authentication with Keycloak working
• Basic UI for routes and deliveries
• Phone and maps integration

v1.0.0 (Target)

• All production blockers resolved
• Complete i18n implementation
• Photo upload working
• Comprehensive error handling
• Test coverage >80%
• Ready for App Store/Play Store submission