flutter-migration

Flutter Migration

Full reference: template.md

Key rules

• Audit first: run grep -r "import 'package:" lib/ — every direct third-party import outside a wrapper is a violation to fix.
• Wrapper rule: each third-party package gets one *_impl.dart wrapper. All app code imports the interface, not the package.
• Phase 1 — DI centralization: introduce service_locator.dart and register existing singletons there. Don't change behavior yet.
• Phase 2 — Wrap dependencies: wrap logging, networking, storage, analytics one-by-one. Each wrapper is independently testable.
• Phase 3 — Feature migration: migrate one feature at a time to clean architecture (entity → use case → cubit → page). Don't big-bang rewrite.
• Verification script: scripts/check_wrapper_rule.sh — run after each phase. Checks: (1) no direct third-party imports outside *_impl.dart, (2) no DI registrations outside core/di/ or features/*/di/, (3) no getIt<T>() calls outside composition boundaries. Target ≥ 85% before next phase.
• Keep old code paths alive during transition — use feature flags to switch between old and new implementations.
• Never break tests during migration — existing tests are a safety net, not a migration blocker.
• State management agnostic: wrapper rule works with BLoC, Riverpod, or Provider. Don't switch state management during migration — wrap dependencies first, change state management later (if ever).

Quick-start checklist

- [ ] Phase 0: Run audit (`grep -r "import 'package:" lib/`) — document all violations
- [ ] Phase 1 PR1: Create `service_locator.dart` — move all scattered registrations
- [ ] Phase 1 PR2: Wrap logger — `AppLogger` interface + `LoggerImpl`
- [ ] Phase 1 PR3: Wrap HTTP — `DioClient` + `ApiClient` interface
- [ ] Phase 1 PR4: Wrap storage — `KeyValueStore` + `SecureStorage` interfaces
- [ ] Phase 1: Run `check_wrapper_rule.sh` — verify ≥ 85% compliance
- [ ] Phase 2: Migrate features one-by-one (simplest first, auth last)
- [ ] Phase 3: Add `ErrorHandler` + zone guard + test fakes + coverage baseline
- [ ] Add `check_wrapper_rule.sh` to CI — prevent regression