SMS-Receive/openspec/changes/add-xiaomi-background-keepalive/specs/sms-background-keepalive/spec.md

ADDED Requirements

Requirement: Keep SMS monitoring visible through a foreground service

The app SHALL provide a user-controlled foreground service that keeps SMS monitoring diagnostics visible while the app is in the background.

Scenario: User enables keepalive

• WHEN the user enables background keepalive in the app
• THEN the app MUST start a foreground service with a persistent notification
• AND the app MUST persist that the user enabled keepalive

Scenario: Foreground service is running

• WHEN the keepalive service is active
• THEN it MUST periodically update a local heartbeat timestamp
• AND it MUST NOT perform long-running SMS database scans as its normal work

Scenario: User disables keepalive

• WHEN the user disables background keepalive in the app
• THEN the app MUST stop the foreground service
• AND it MUST remove or cancel the persistent keepalive notification

Requirement: Restore keepalive after boot or package replacement

The app SHALL attempt to restore user-enabled keepalive after supported system lifecycle broadcasts.

Scenario: Device boot completes

• WHEN the app receives BOOT_COMPLETED or LOCKED_BOOT_COMPLETED
• AND the user previously enabled keepalive
• THEN the app MUST record the boot event
• AND it MUST attempt to start the keepalive foreground service

Scenario: App package is replaced

• WHEN the app receives MY_PACKAGE_REPLACED
• AND the user previously enabled keepalive
• THEN the app MUST attempt to restore the keepalive service

Scenario: Foreground service start is blocked

• WHEN Android or HyperOS rejects service startup from a boot receiver
• THEN the app MUST catch the failure
• AND it MUST store a diagnostic reason instead of crashing

Requirement: Respect Android 15 foreground service limits

The app SHALL avoid using foreground service types that Android 15 restricts from BOOT_COMPLETED receivers for this keepalive feature.

Scenario: Service is declared in the manifest

• WHEN the keepalive service is declared
• THEN it MUST NOT be declared as dataSync, camera, mediaPlayback, phoneCall, mediaProjection, or microphone for the boot-started keepalive path

Scenario: Target SDK is upgraded

• WHEN the project target SDK is upgraded to Android 15 or higher
• THEN the boot-start keepalive behavior MUST be revalidated on the Xiaomi target device

Requirement: Treat native keepalive as experimental only

The app SHALL NOT depend on a native daemon or C++ child process for reliable SMS delivery.

Scenario: Native heartbeat is added

• WHEN a native heartbeat experiment is enabled
• THEN it MUST be clearly labeled as diagnostic
• AND SMS reception MUST remain implemented through Android platform APIs

Scenario: Native process stops

• WHEN the native heartbeat stops because the app process or service is killed
• THEN the app MUST report the heartbeat loss as a keepalive limitation rather than attempting hidden restart loops