[update] init

2026-05-18 11:10:52 +08:00
commit 790afd679e
54 changed files with 5015 additions and 0 deletions
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Receive new SMS messages through the system broadcast path
+The app SHALL use Android's new SMS received broadcast path as the primary mechanism for capturing verification SMS messages on the user's own device.
+
+#### Scenario: SMS broadcast is received with permission granted
+- **WHEN** the app has `RECEIVE_SMS` permission and the device receives a text SMS
+- **THEN** the app MUST process `Telephony.Sms.Intents.SMS_RECEIVED_ACTION` and extract message objects from the received intent
+
+#### Scenario: SMS broadcast is unavailable because permission is missing
+- **WHEN** the app does not have `RECEIVE_SMS` permission
+- **THEN** the app MUST report that the primary SMS capture path is blocked by missing permission
+
+### Requirement: Parse complete SMS message bodies
+The app SHALL parse SMS bodies using Android SMS message APIs rather than ad hoc PDU handling in business logic.
+
+#### Scenario: Multi-part SMS is received
+- **WHEN** the received intent contains multiple SMS message segments
+- **THEN** the app MUST combine the message bodies in received order before verification code extraction
+
+#### Scenario: Sender and timestamp are available
+- **WHEN** Android exposes sender address or timestamp for the SMS message
+- **THEN** the app MUST attach those values to the capture result for diagnostics and display
+
+### Requirement: Extract verification code candidates
+The app SHALL extract verification code candidates from SMS bodies with a conservative parser optimized for common Chinese and English verification messages.
+
+#### Scenario: Chinese verification keyword is present
+- **WHEN** the SMS body contains a keyword such as `验证码`、`校验码` or `动态码` near a 4-8 character code
+- **THEN** the app MUST extract the nearby code as the preferred verification code candidate
+
+#### Scenario: English verification keyword is present
+- **WHEN** the SMS body contains a keyword such as `code`, `verification` or `OTP` near a 4-8 character code
+- **THEN** the app MUST extract the nearby code as the preferred verification code candidate
+
+#### Scenario: Code contains spaces or hyphens
+- **WHEN** the SMS body contains a verification code formatted with spaces or hyphens
+- **THEN** the app MUST normalize the code before displaying it
+
+#### Scenario: No reliable code candidate exists
+- **WHEN** the SMS body does not contain a reliable verification code candidate
+- **THEN** the app MUST return a structured parse failure instead of displaying a guessed code
+
+### Requirement: Support optional Google SMS verification APIs
+The app SHALL support Google SMS verification APIs only as optional paths and MUST NOT depend on them for the primary capture behavior.
+
+#### Scenario: SMS User Consent path is available
+- **WHEN** Google Play services supports SMS User Consent and the user authorizes reading a single SMS
+- **THEN** the app MUST parse that SMS body through the same verification code parser used by the primary path
+
+#### Scenario: SMS Retriever path is used with app hash
+- **WHEN** a controlled test SMS includes the app hash required by SMS Retriever
+- **THEN** the app MUST accept the retrieved message and parse the verification code
+
+#### Scenario: Google SMS API is unavailable
+- **WHEN** Google Play services is missing, disabled, incompatible, times out, or the user declines consent
+- **THEN** the app MUST keep the system SMS broadcast path usable and report the optional path failure separately
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Validate on the target Xiaomi Android 15 device
+The app SHALL be validated on the user's Xiaomi 12S running HyperOS 3 and Android 15 before the SMS capture behavior is considered complete.
+
+#### Scenario: Foreground validation
+- **WHEN** the app is open in the foreground and a test SMS containing `验证码 123456` is received
+- **THEN** the app MUST show `123456` as the latest parsed verification code
+
+#### Scenario: Background validation
+- **WHEN** the app has been moved to the background and a test SMS containing a new verification code is received
+- **THEN** the app MUST either show the new code after returning to the app or report that background delivery was blocked
+
+#### Scenario: Lock screen validation
+- **WHEN** the device is locked and a test SMS is received
+- **THEN** the app MUST show the received result after unlock or report that delivery was blocked under lock screen conditions
+
+### Requirement: Validate parser behavior with representative samples
+The verification parser SHALL be validated with representative verification SMS examples and negative examples.
+
+#### Scenario: Common valid samples
+- **WHEN** parser tests include Chinese verification codes, English OTP messages, space-separated codes, hyphen-separated codes, and multiple candidates
+- **THEN** all expected verification codes MUST be extracted with the correct normalized value
+
+#### Scenario: Negative samples
+- **WHEN** parser tests include messages with phone numbers, dates, money amounts, tracking numbers, or no verification code
+- **THEN** the parser MUST avoid returning a false verification code unless a stronger keyword-nearby rule applies
+
+### Requirement: Validate optional API assumptions separately
+The app SHALL validate Google SMS APIs independently from the primary system broadcast path.
+
+#### Scenario: Google Play services is available
+- **WHEN** Google Play services is installed and supports SMS User Consent or SMS Retriever
+- **THEN** the app MUST run an explicit optional-path test and record the result separately from system broadcast validation
+
+#### Scenario: Google Play services is unavailable
+- **WHEN** Google Play services is unavailable or incompatible on the target phone
+- **THEN** the app MUST mark Google SMS API validation as skipped or unavailable without failing the primary SMS broadcast validation
+
+### Requirement: Validate implementation without rebuilding development environment
+The app SHALL reuse the existing local Android build environment reference and MUST NOT require reinstalling Android Studio, Gradle, or JDK as part of the implementation validation.
+
+#### Scenario: Build configuration is prepared
+- **WHEN** implementation begins after spec approval
+- **THEN** the project MUST align its build setup with the existing Weather project environment or document any minimal project-specific difference
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Display SMS permission state
+The app SHALL display whether the SMS receive permission is granted, denied, or blocked by system settings.
+
+#### Scenario: Permission is granted
+- **WHEN** `RECEIVE_SMS` permission is granted
+- **THEN** the app MUST show that the primary SMS capture path can be attempted
+
+#### Scenario: Permission is denied
+- **WHEN** `RECEIVE_SMS` permission is denied
+- **THEN** the app MUST show that incoming SMS cannot be captured through the primary path until permission is granted
+
+### Requirement: Explain capture path status
+The app SHALL expose diagnostic state for each supported SMS capture path.
+
+#### Scenario: Primary path receives an SMS
+- **WHEN** the system broadcast path receives and parses an SMS
+- **THEN** the app MUST show the latest receive time, source path, sender summary, parsed code, and parse strategy
+
+#### Scenario: Primary path fails before parsing
+- **WHEN** the app cannot receive or parse an SMS through the primary path
+- **THEN** the app MUST show a specific reason such as missing permission, no broadcast received, empty body, or parser failure
+
+#### Scenario: Optional Google API path fails
+- **WHEN** SMS User Consent or SMS Retriever cannot complete
+- **THEN** the app MUST show whether the failure came from unavailable Google Play services, timeout, user cancellation, or unmatched SMS format
+
+### Requirement: Avoid unnecessary SMS content retention
+The app SHALL minimize retention and logging of full SMS content.
+
+#### Scenario: Verification code is parsed successfully
+- **WHEN** the app extracts a verification code from an SMS
+- **THEN** the app MUST display or retain the code, sender summary, timestamp, and parse metadata without requiring persistent storage of the full SMS body
+
+#### Scenario: Debug body visibility is enabled
+- **WHEN** a debug-only setting enables full body visibility
+- **THEN** the app MUST keep that behavior local to the device and clearly separate it from normal display state
+
+### Requirement: Provide recovery actions for permission problems
+The app SHALL provide a clear recovery path when Android or HyperOS blocks SMS capture permissions.
+
+#### Scenario: Permission cannot be granted in normal prompt
+- **WHEN** the runtime permission prompt does not grant usable SMS access
+- **THEN** the app MUST provide an action to open the system application details or permission settings page