Implement Complete Add Patient Multi-Step Form Flow

[xkaper001]

Description

Implement the complete 4-step Add Patient flow for adding new patients with comprehensive information collection and document upload.

Design Reference

Figma Frames: Add Patient 1, Add Patient 2, Add Patient 3, Add Patient 4 (576:3113, 576:3143, 576:3170, 576:3217)

Overview

A multi-step form wizard that guides doctors through adding a new patient with:

1. Basic Information
2. Medical History
3. Insurance & Emergency Contact
4. Document Upload

Step 1: Basic Information

Requirements

• Progress indicator (1/4)
• Back button in top nav
• Form fields:
  • Full Name (required)
  • Date of Birth (required, date picker)
  • Gender (required, dropdown: Male/Female/Other)
  • Phone Number (required, formatted input)
  • Email (optional, validated)
  • Address (required, text area)
• "Next" button (disabled until valid)
• Real-time validation feedback

Validation

• Name: min 2 chars, letters/spaces only
• DOB: not future, age 0-120
• Phone: valid format (10 digits)
• Email: valid format if provided
• Address: min 10 chars

Step 2: Medical History

Requirements

• Progress indicator (2/4)
• Back button preserves step 1 data
• Form fields:
  • Current Medications (text area, important)
  • Known Allergies (text input, important)
  • Past Medical History (text area, optional)
  • Family Medical History (text area, optional)
  • Blood Group (dropdown: A+, A-, B+, B-, O+, O-, AB+, AB-, required)
  • Additional Notes (text area, optional)
• Warning banner if medications/allergies empty
• "Next" button

Step 3: Insurance & Emergency Contact

Requirements

• Progress indicator (3/4)
• Back button preserves previous data
• Form fields:
  • Insurance Provider (dropdown with common providers)
  • Insurance Policy Number (required if provider selected)
  • Emergency Contact Name (optional)
  • Emergency Contact Phone (required if name provided)
  • Emergency Contact Relationship (dropdown, required if name provided)
• Conditional validation
• "Next" button

Insurance Providers

Blue Cross Blue Shield, UnitedHealthcare, Aetna, Cigna, Humana, Medicare, Medicaid, Other

Step 4: Document Upload

Requirements

• Progress indicator (4/4)
• Back button preserves all data
• Upload sections:
  • ID/Photo (PDF/image, required)
  • Medical Reports (multiple files: Blood tests, X-rays, MRI)
  • Insurance Documents (PDF/image, if applicable)
• File picker with preview
• Remove file option
• Upload progress indicator
• "Submit" button with loading state
• Success/error feedback

File Validation

• Formats: PDF, JPG, JPEG, PNG
• Max size: 10MB per file
• Max total: 50MB
• Image compression before upload

Global Features

• Auto-save draft to local storage on each step
• Restore draft on app restart
• Bottom navigation bar on all steps
• Form state persistence across navigation
• Clear draft after successful submission
• Handle network errors gracefully
• Loading states during API calls

API Integration

• Upload documents to cloud storage
• Create patient record with all data
• Handle failures with retry logic
• Navigate to patient detail on success

Technical Implementation

Files to Create

lib/features/patients/presentation/pages/
  ├── add_patient_step1_page.dart
  ├── add_patient_step2_page.dart
  ├── add_patient_step3_page.dart
  ├── add_patient_step4_page.dart
  └── add_patient_wrapper.dart (manages flow)

lib/features/patients/presentation/bloc/
  └── add_patient_bloc.dart (manages state)

lib/features/patients/presentation/widgets/
  ├── step_progress_indicator.dart
  ├── warning_banner.dart
  └── file_upload_card.dart

lib/features/patients/domain/entities/
  └── patient_form_data.dart

lib/features/patients/data/
  ├── datasources/document_upload_service.dart
  └── repositories/patients_repository_impl.dart

lib/core/utils/
  └── image_compressor.dart

State Management

• Use BLoC pattern for form state
• Each step emits events to BLoC
• BLoC maintains complete form data
• Persist state to local storage
• Clear state on success/cancel

Dependencies

• Requires: Create Form Input Components #16 (Form components)
• Requires: Create Button and Navigation Components #17 (Buttons & navigation)
• Related to: Implement Patients List Screen #24 (Patients list)

Priority

Medium

Acceptance Criteria

• All 4 steps work seamlessly
• Data persists across steps and app restarts
• Validation works on each step
• File upload with progress indicators
• Success navigation to patient details
• Error handling and retry logic
• UI matches Figma designs exactly
• Performance is smooth with no lag

Testing Checklist

• Test forward/backward navigation
• Test validation on all fields
• Test file upload success/failure
• Test draft save/restore
• Test network error scenarios
• Test complete flow end-to-end

[github-actions]

👋 Thanks for opening this issue and contributing!

Our reviewers will check it soon 🚀

📘 If you’d like to know more about contributing, please read our CONTRIBUTING.md.