<Feature><Centre Remap> US#04:Execute Centre Remapping Cleanup

[Varaniya201]

Description

As a System, I want to orchestrate a multi-step cleanup process that uploads pending data, deletes centre-specific records, and resets the remapping state, So that the device is fully transitioned to the new centre without data loss or inconsistency.

Purpose

To ensure complete, consistent, and irreversible transition from old centre to new centre with all data preserved on server before local deletion.

Pre-requisites

• Centre remapping flag is set (issue-1045)
• No pending approval packets remain
• Device is online
• All previous cleanup steps successful (if resuming)

Basic Flow

Step 1: Verify Preconditions

1. System checks if device is online (throws error if offline)
2. System checks if any active registration operations in progress (blocks if true)
3. System checks GLOBAL_PARAM for remapping flag (must be true)
4. System acquires cleanup lock to prevent concurrent cleanups
5. If all checks pass, proceeds to Step 2

Step 2: Upload Pending Packets

1. System queries all registration packets with status PROCESSING or RE-SEND
2. System displays progress dialog: "Uploading packets. Please don't close the application"
3. System uploads each packet to server
4. On success: Marks packet as uploaded; proceeds to next packet
5. On failure: Retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s)
6. If all retries fail: Throws UploadFailedException; stops sync; allows retry
7. When all packets uploaded: Updates AUDIT with success; proceeds to Step 3

Step 3: Upload Operator Onboarding Data

1. System queries all operator records for current centre
2. System uploads operator data (credentials, biometrics, roles) to server
3. Retry logic same as Step 2
4. On success: Proceeds to Step 4
5. On failure: Throws exception; allows retry

Step 4: Delete Pre-registration Data

1. System queries all PRE_REGISTRATION records
2. System deletes all pre-registration packet files from disk
3. System deletes all PRE_REGISTRATION database records (within transaction)
4. System deletes associated metadata
5. Logs count of deleted records in AUDIT
6. Proceeds to Step 5

Step 5: Delete Registration Packets (Specific Statuses Only)

1. System queries registration packets with status: PROCESSING, PROCESSED, RE-REGISTER
2. Note: DOES NOT delete packets with status RECEIVED or RE-SEND
3. System deletes matching packet files
4. System deletes matching database records (within transaction)
5. Logs detailed deletion counts in AUDIT
6. Proceeds to Step 6

Step 6: Delete Centre-Specific Master Data

1. System deletes centre-specific document types
2. System deletes centre-specific device registrations
3. System deletes centre-specific templates/configurations
4. Note: DOES NOT delete GLOBAL_PARAM (global) or AUDIT (immutable)
5. Uses transaction to ensure atomicity
6. Logs deletion summary in AUDIT
7. Proceeds to Step 7

Step 7: Remove All Operators for Current Centre

1. System queries all OPERATOR records for current centre
2. System deletes OPERATOR records
3. System deletes OPERATOR_BIOMETRIC records
4. System deletes OPERATOR_ROLE records
5. System deletes operator preferences
6. If current operator is logged in: Forces logout
7. Logs operator IDs deleted in AUDIT
8. Proceeds to Step 8

Step 8: Reset Remapping Flag and Re-enable Auto-sync

1. System updates GLOBAL_PARAM: sets mosip.registration.centermappedchanged to 'false'
2. System clears SessionContext.centreRemapped flag
3. System re-enables automatic sync scheduling
4. System releases cleanup lock
5. Logs completion with full statistics in AUDIT
6. Displays success message on screen

Alternate Flows

Alternate Flow A1: Offline During Sync

1. Sync is running (e.g., at Step 3 uploading operator data)
2. Device loses connectivity
3. System detects offline condition
4. Current step is rolled back (transaction)
5. System pauses cleanup and saves state (last completed step = 2)
6. System displays dialog: "System went offline. Sync paused. Will resume when online."
7. When connectivity restored:
   • System displays: "Connectivity restored. Resuming cleanup..."
   • System resumes from Step 3 (continues from next step after last completed)
   • Remaining steps execute normally
8. Cleanup completes successfully

Alternate Flow A2: Cleanup Failure at Any Step

1. Step fails (e.g., database deletion throws error)
2. System catches exception
3. System rolls back transaction (no partial deletion)
4. System saves failure state in CLEANUP_STATE table
5. System displays error dialog with user-friendly message
6. Dialog includes:
   • What failed (e.g., "Failed to delete pre-registration data")
   • Why it failed (e.g., "Disk space low")
   • "RETRY" button to restart from failed step
   • "CONTACT SUPPORT" button to show error details
7. User clicks RETRY:
   • System resumes from failed step
   • If successful: Continues normally
   • If fails again: Shows error again with retry option

Alternate Flow A3: App Crashes During Cleanup

1. Cleanup is running (e.g., at Step 4)
2. App crashes or is terminated
3. Cleanup state is saved to CLEANUP_STATE table (before each step)
4. On app restart:
   • System detects incomplete cleanup (flag still true)
   • System shows dialog: "Previous cleanup interrupted. Resume?"
   • Options: "RESUME" (continues from last completed step) or "START OVER"
   • If user selects RESUME:
     • Loads cleanup state from database
     • Continues from Step 5 (last completed was Step 4)
     • Completes normally

Alternate Flow A4: Multiple Cleanup Attempts

1. First cleanup attempt partially succeeds (completes Steps 1-4, fails on Step 5)
2. User retries cleanup
3. System resumes from Step 5
4. Completes remaining steps
5. Success

Alternate Flow A5: Cleanup Completes Successfully

1. All 8 steps complete
2. System displays success dialog with statistics:
   • Pre-registration packets deleted: 23
   • Registration packets deleted: 156
   • Operators removed: 5
   • Cleanup completed at: 2:45 PM
3. Dialog has "CLOSE" button
4. User clicks CLOSE
5. System navigates to home screen
6. All blocked operations now available
7. Centre Remapping menu option disappears

Scenarios

Scenarios

Scenario	Flow	Expected Result
S1	Normal cleanup: online, no interruptions	All steps complete; success message
S2	Offline at Step 3	Pause and resume when online; complete
S3	Failure at Step 5 (database error)	Error shown; retry available
S4	App crash at Step 4	State saved; resume option on restart
S5	User retries from failed attempt	Resume from failure point; complete
S6	Network timeout during upload (Step 2)	Auto-retry with backoff; eventually succeed

---

Error Messages

Step	Error Condition	Message	Recovery
Step 1-2	Upload fails after retries	"Failed to upload packets. Please check your connection and retry."	Retry button
Step 4	Disk space insufficient	"Insufficient storage for sync. Please free up space."	Manual cleanup of files; retry
Step 6	Database locked	"System busy. Please wait and retry."	Automatic retry
General	Network offline during cleanup	"Device went offline. Sync will resume when online."	Auto-resume
General	Permission denied	"System permission required for sync. Please contact administrator."	Contact support

Data Fields

Field	Purpose	Updated At
Last completed step	Tracks progress for resume	After each step
Error details	Logging and recovery	When error occurs
Deleted packet count	Audit statistics	After deletion step
Deleted operator count	Audit statistics	After operator deletion
Cleanup start timestamp	Audit trail	Step 1
Cleanup end timestamp	Audit trail	Step 8

Business Rules (With Audit)

BR-001: Cleanup MUST execute steps in exact order; no skipping or reordering

BR-002: Before cleanup starts:

• Device MUST be online
• No active registration operations
• Remapping flag MUST be true
• No pending approval packets

BR-003: Each deletion MUST be atomic (transaction); no partial deletions

BR-004: Upload MUST complete before any deletion begins (data safety first)

BR-005: Operators cannot login after deletion (Step 7)

BR-006: GLOBAL_PARAM and AUDIT tables MUST NEVER be deleted

BR-007: Cleanup state MUST be persisted after each step (for resume capability)

BR-008: All cleanup steps MUST be logged in AUDIT table

BR-009: On success, remapping flag MUST be reset (Step 8)

BR-010: Auto-sync MUST be re-enabled after success (Step 8)

Acceptance Criteria

Criteria	Verification
All steps execute in correct order	Audit logs show sequence
No data loss; all uploaded packets before deletion	Verify server has data; local deleted
Offline detected and cleanup paused	Disconnect network; observe pause
Cleanup resumed correctly after offline	Restore connection; verify continuation
Failure at any step shows error; allows retry	Simulate failure; verify error dialog
App crash saves state; resume option works	Force crash; restart app; verify resume
Success message shows accurate statistics	Calculate expected counts; verify displayed
GLOBAL_PARAM and AUDIT untouched	Query database post-cleanup
Operators cannot login post-cleanup	Attempt login with old credentials; verify blocked
Auto-sync re-enabled after success	Verify sync scheduler running

Exceptions

Exception	Handling	Recovery
Offline detected	Roll back current transaction; pause	Resume when online
Upload failure	Retry up to 5x with backoff	Allow manual retry if all fail
Database error	Roll back transaction; log error	Manual retry after fixing issue
Permission denied	Log error; show message	Contact support; manual intervention
App crash	Save state to database	Auto-resume on restart

Documentation

No response

Reference UX

No response

Compatibility

No response

Implementation Details

Files to Create:

• lib/services/registration/centre_remapping_service.dart (main orchestration)
• lib/models/remapping_result.dart
• lib/models/remapping_stats.dart
• lib/models/cleanup_progress.dart
• lib/models/cleanup_state.dart

Files to Modify:

• lib/repositories/registration_packet_repository.dart - Add queries and delete methods
• lib/repositories/pre_registration_repository.dart - Add delete methods
• lib/repositories/operator_repository.dart - Add delete methods
• lib/repositories/cleanup_state_repository.dart - Create for state persistence
• lib/services/sync_service.dart - Use for packet upload
• lib/utils/audit_logger.dart - Add cleanup event types
• lib/utils/session_context.dart - Track cleanup progress
• lib/db/database_helper.dart - Transaction management

Key Implementation Points:

• Use database transactions for atomicity
• Implement step-by-step state saving for resume capability
• Network connectivity monitoring for pause/resume
• Comprehensive audit logging at each step
• User-friendly error messages with recovery options

---

Definition of Done

• Centre remapping service created with all 8 steps
• Step orchestration logic correct
• Transaction management for atomicity working
• Offline detection and pause/resume logic implemented
• Cleanup state persistence working (resume capability)
• Upload retry logic with exponential backoff
• Audit logging for all steps complete
• Error handling for each step
• Success/failure messages clear and actionable
• Unit tests for each step (>80% coverage)
• Integration test for full cleanup flow
• Integration test for offline scenarios
• Integration test for failure recovery
• Integration test for app crash recovery
• Manual testing with actual packet data
• Performance testing (verify <15 min duration)
• Data integrity verification (query database post-cleanup)
• Code reviewed by 2+ senior developers
• Code merged with no warnings

Non-Functional Requirements

Requirement	Specification
Sync Duration	<15 minutes for 500 packets
Data Consistency	100% accuracy; no corruption
Reliability	No data loss even on crash
Auditability	Complete trail of all operations
Error Recovery	Auto-resume capability
Security	Only authenticated cleanup; no bypass