android/docs/multi_model_adaptation.md

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.