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

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