# Multi-Model Adaptation Design (Android)

## Goals
- Keep one code path for core remote-control logic.
- Isolate ROM/device-specific behavior in policy resolvers.
- Prevent one-device hotfix from breaking other models.

## Current Architecture (implemented)
- `util/adaptation/DeviceAdaptationStrategy.kt`
  - Defines strategy interface + runtime fingerprint model:
    - `DeviceAdaptationStrategy`
    - `DeviceRuntimeInfo`
- `util/adaptation/KeepAliveAdaptationRegistry.kt`
  - Registers and resolves keepalive strategies by priority.
  - Current built-in strategies:
    - `oppo_family_android14_conservative`
    - `xiaomi_legacy_aggressive`
    - `default_balanced`
- `util/adaptation/WebRtcTransportAdaptationRegistry.kt`
  - Registers and resolves WebRTC/MediaProjection tuning policies.
  - Current built-in strategies:
    - `xiaomi13_hyperos_android14`
    - `xiaomi_android14_balanced`
    - `oppo_family_android14`
    - `default_webrtc_transport`
- `util/DeviceDetector.kt`
  - Keeps public compatibility APIs (`getKeepAlivePolicy`, `getWebRtcTransportPolicy`, `shouldUseActivityKeepAlive`).
  - Internally delegates strategy selection to adaptation registries.
- `util/ForegroundServiceStarter.kt`
  - Centralized, throttled starter for `RemoteControlForegroundService`.
  - Prevents repeated `startForegroundService` storms.
- Keepalive modules wired to policy:
  - `service/KeepAliveService.kt`
  - `service/EffectiveKeepAliveManager.kt`
  - `service/WorkManagerKeepAliveService.kt`

## Strategy Rules
- OPPO/VIVO/REALME/ONEPLUS on Android 14+:
  - Conservative mode.
  - Disable aggressive WorkManager one-shot recovery workers.
  - Increase keepalive check interval.
  - Throttle foreground-service restart frequency.
- Xiaomi <= Android 13:
  - Keep aggressive recovery and auto behavior (legacy-compatible).
- Others:
  - Balanced defaults.

- Xiaomi13 / HyperOS (Android 14+):
  - Prefer default-display capture intent.
  - Use shorter projection refresh cooldown and longer auto-retry window.
  - Force mediaProjection FGS upgrade before WebRTC capture.

## Why this avoids regressions
- Device-specific branching is no longer spread across multiple services.
- New ROM hotfixes are added by appending one strategy class, not editing many call sites.
- Same APIs remain for existing modules; behavior changes through policy values.

## Extension Template
1. Add a new strategy class implementing `DeviceAdaptationStrategy`.
2. Assign a `priority` (higher value wins).
3. Implement `matches(info)` and `keepAlivePolicy(info)`.
4. Register it in `KeepAliveAdaptationRegistry.strategies`.
5. Validate with smoke matrix:
   - OPPO Android 15
   - Xiaomi Android 13
   - Vivo/Realme target model
   - One default-model baseline

## Next Step (recommended)
- Extend policy scope to permission-flow strictness:
  - Add `PermissionFlowPolicy` for dialog step order, spinner selection strategy, and timeout budget.
  - Move remaining manufacturer-specific permission ordering from `MainActivity`/orchestrator into one resolver.
- Add per-device smoke matrix in CI:
  - Profile set: Xiaomi13, OPPO A5/Android15, Vivo, Samsung.
  - Gate release on baseline pass rate.