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

ADDED Requirements

Requirement: Diagnose missing SMS receiver delivery

The app SHALL explain why SmsReceiver.onReceive may not be called when a new SMS arrives.

Scenario: SMS permission is missing or unusable

• WHEN RECEIVE_SMS is not granted or is unusable because of restricted permission behavior
• THEN the app MUST report that the system SMS broadcast path is blocked by permission state

Scenario: App was force-stopped

• WHEN diagnostics indicate the app has not run since a user force-stop or package inactive state
• THEN the app MUST report that force-stopped apps are not expected to receive background broadcasts until manually opened

Scenario: HyperOS background policy is likely blocking delivery

• WHEN SMS appears in the inbox fallback path but no system SMS broadcast was recorded
• THEN the app MUST report that HyperOS autostart or battery policy may be blocking receiver delivery
• AND it MUST point the user to the background setup checklist

Requirement: Correlate broadcast and inbox fallback results

The app SHALL record enough source metadata to distinguish SMS broadcast success from inbox fallback success.

Scenario: System broadcast receives SMS

• WHEN SmsReceiver handles SMS_RECEIVED_ACTION
• THEN the app MUST store the source as system_sms_broadcast
• AND update the latest broadcast receive timestamp

Scenario: Inbox observer sees SMS

• WHEN the ContentObserver or manual inbox reader finds a new SMS
• THEN the app MUST store an inbox source such as sms_inbox_observer, sms_inbox_manual, or sms_inbox_polling
• AND keep it distinct from system broadcast delivery

Scenario: Inbox succeeds after broadcast silence

• WHEN inbox fallback finds a verification SMS newer than the last recorded broadcast
• THEN the app MUST show a diagnostic message that the SMS was present in the inbox but was not delivered through the receiver path

Requirement: Keep diagnostics local and privacy-minimized

The app SHALL diagnose receiver delivery without unnecessarily retaining full SMS bodies.

Scenario: Diagnostic record is saved

• WHEN the app stores SMS delivery diagnostics
• THEN it MUST store timestamp, source, sender summary, parse status, and failure reason
• AND it SHOULD avoid persistent storage of full SMS body unless a debug-only setting is enabled

Scenario: Logcat output is produced

• WHEN receiver or keepalive code logs diagnostic details
• THEN it MUST avoid logging full SMS body by default
• AND it MUST make source path and failure reason visible enough for debugging

Requirement: Validate delivery across target device states

The app SHALL validate SMS receiver delivery under foreground, background, lockscreen, reboot, and force-stop states.

Scenario: Background keepalive is enabled

• WHEN the app is backgrounded and the keepalive notification is visible
• THEN receiving a test SMS MUST either update the latest result through system_sms_broadcast
• OR report a specific fallback/blocked state

Scenario: Device reboots

• WHEN the target Xiaomi phone reboots
• AND the user previously enabled keepalive and Xiaomi autostart
• THEN the app MUST record whether boot restore ran
• AND whether the first post-boot SMS reached SmsReceiver

Scenario: User force-stops the app

• WHEN the user force-stops the app from system settings
• THEN the app MUST NOT claim reliable SMS delivery until the user manually opens the app again