feat(android): support multiple simultaneous foreground services

[ppamorim]

Summary

• Introduces a multi-service architecture for Android, allowing multiple independent foreground services to run simultaneously, each with its own notification, task handler, Dart isolate, and SharedPreferences scope.
• Adds FlutterForegroundServiceBase (abstract), FlutterForegroundServiceRegistry, and ForegroundServiceRuntime on the Android side; FlutterForegroundTaskController.of(id) on the Dart side.
• Makes the default ForegroundService manifest entry optional — the library validates the manifest at runtime and throws a clear error (or silently skips at boot) if a service class is not declared.

Changes

Android (Kotlin)

• FlutterForegroundServiceBase — new abstract base class containing all service logic; ForegroundService becomes a thin serviceId="default" subclass.
• FlutterForegroundServiceRegistry — singleton mapping serviceId → Service class, with auto-registration of the default in a static initializer (available at cold boot). Includes isServiceDeclaredInManifest() for runtime validation.
• ForegroundServiceRuntime — per-id running state, task references, and lifecycle listeners (replaces companion-object statics).
• ForegroundServiceManager — all methods accept serviceId; start() validates the manifest before proceeding.
• RebootReceiver / RestartReceiver — iterate registered ids, skip services not declared in the manifest.
• All model companions — accept optional serviceId for scoped SharedPreferences.
• ForegroundTask — sends onServiceIdSet to the Dart isolate so sendDataToMain routes correctly.
• MethodCallHandlerImpl — extracts serviceId from method channel args.

Dart

• FlutterForegroundTaskController — instance-based API (init, start, stop, update, restart, communication ports, storage) scoped by service id.
• FlutterForegroundTask — static API now delegates to FlutterForegroundTaskController.of('default') for full backward compatibility.
• currentServiceId — set by the native layer on isolate start; sendDataToMain auto-routes to the correct port.
• Platform interface / method channel — serviceId parameter threaded through all service methods.

Documentation

• documentation/multiple_services.md — full guide: Kotlin subclassing, manifest entries, Application.onCreate registration, Dart controller usage, communication ports, backward-compatibility table, limitations.
• documentation/android_shared_preferences_usage.md — updated architecture diagram and class references.
• README.md — new "Multiple services (Android)" section linking to the guide.

Backward compatibility

Existing single-service apps require zero changes. All public API signatures are preserved. SharedPreferences file names for the "default" id are identical to the pre-refactor layout.

Test plan

• All 81 existing Dart tests pass (flutter test)
• flutter analyze clean (only pre-existing deprecation infos)
• Build and run the example app on a physical Android device with the default single-service setup
• Add a second <service> subclass to the example, verify both services run simultaneously with independent notifications
• Remove the default <service> entry from the manifest, verify startService throws IllegalStateException with a helpful message
• Verify autoRunOnBoot works for declared services and is skipped for undeclared ones
• Verify sendDataToMain delivers data to the correct UI-side controller for non-default services

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.5% Duplication on New Code

See analysis details on SonarQube Cloud