[update] init

2026-05-18 11:10:52 +08:00
commit 790afd679e
54 changed files with 5015 additions and 0 deletions
@@ -0,0 +1,61 @@
+## 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
@@ -0,0 +1,65 @@
+## 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
@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: Guide the user through Xiaomi background setup
+The app SHALL provide explicit guidance and shortcuts for the Xiaomi/HyperOS settings required for reliable background behavior.
+
+#### Scenario: User opens background setup
+- **WHEN** the user opens the app's background setup section
+- **THEN** the app MUST show checklist items for SMS permission, autostart, battery unrestricted mode, notification visibility, and keepalive service state
+
+#### Scenario: Xiaomi autostart settings shortcut is available
+- **WHEN** the app can resolve a Xiaomi/HyperOS autostart settings activity
+- **THEN** it MUST open that settings page from the setup UI
+
+#### Scenario: Xiaomi autostart shortcut is unavailable
+- **WHEN** the explicit Xiaomi settings activity cannot be resolved or launched
+- **THEN** the app MUST fall back to application details or general settings
+- **AND** it MUST keep the manual setup checklist visible
+
+### Requirement: Represent manual-only settings honestly
+The app SHALL distinguish settings that can be detected through Android APIs from settings that require manual user confirmation.
+
+#### Scenario: Battery optimization state is queried
+- **WHEN** the app checks Android battery optimization status
+- **THEN** it MUST use `PowerManager.isIgnoringBatteryOptimizations` where available
+- **AND** display whether Android reports the app as ignoring battery optimizations
+
+#### Scenario: Xiaomi autostart state cannot be read
+- **WHEN** no stable public API exists to read the Xiaomi autostart switch
+- **THEN** the app MUST ask the user to manually confirm completion instead of pretending to detect it
+
+#### Scenario: Battery unrestricted state cannot be read
+- **WHEN** no stable public API exists to read the HyperOS per-app battery unrestricted option
+- **THEN** the app MUST ask the user to manually confirm completion
+
+### Requirement: Provide battery optimization actions
+The app SHALL provide Android-standard actions for battery optimization setup.
+
+#### Scenario: User opens battery optimization settings
+- **WHEN** the user taps the battery optimization settings action
+- **THEN** the app MUST launch `Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS` when available
+
+#### Scenario: User requests direct exemption
+- **WHEN** the app offers a direct ignore-battery-optimization request
+- **THEN** it MUST use `Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`
+- **AND** explain that exemption still does not guarantee unlimited background execution
+
+### Requirement: Preserve user control
+The app SHALL keep background keepalive opt-in and reversible.
+
+#### Scenario: First app launch after install
+- **WHEN** the app is launched for the first time
+- **THEN** background keepalive MUST be disabled until the user enables it
+
+#### Scenario: User turns off keepalive
+- **WHEN** the user turns off keepalive
+- **THEN** boot restore MUST no longer restart the keepalive service