openspec: scan-flow change — proposal, design, 5 specs (3 new + 2 deltas), tasks

openspec/changes/scan-flow/specs/sms-alerting/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Owner alert on scan
+When a scan of an `sms_enabled` tag is recorded, the system SHALL send an SMS to the tag owner. The message SHALL include the item type and name, the scan time, a maps link when a location was shared, and the tag page link.
+
+#### Scenario: Alert with location
+- **WHEN** a scan with coordinates is recorded on an enabled tag outside the throttle window
+- **THEN** the owner receives an SMS with item type, name, time, maps link, and tag page link, and `alert_sent = true` is recorded
+
+#### Scenario: Alert without location (first scan)
+- **WHEN** a scan without coordinates is recorded on an enabled tag outside the throttle window
+- **THEN** the owner receives an SMS noting the finder did not share a location
+
+### Requirement: sms_enabled disabled means no alerts
+When a tag has `sms_enabled = false`, scans SHALL be recorded but no SMS SHALL be sent and `alert_sent` SHALL remain false.
+
+#### Scenario: Informational tag scanned
+- **WHEN** a scan is recorded on a tag with `sms_enabled = false`
+- **THEN** no SMS is sent and `alert_sent = false`
+
+### Requirement: Location-aware throttle
+Within a 10-minute window since the last alerted scan of the same tag, the system SHALL send a new alert only if the new scan has a location more than 250 meters from the last alerted location. A scan at the same location SHALL be recorded without a new alert.
+
+#### Scenario: Same location within window
+- **WHEN** a second scan of the same tag arrives within 10 minutes at the same location
+- **THEN** the scan is recorded and no SMS is sent
+
+#### Scenario: Moved more than 250 m within window
+- **WHEN** a second scan of the same tag arrives within 10 minutes more than 250 m from the last alerted location
+- **THEN** a new SMS is sent
+
+#### Scenario: After the window
+- **WHEN** a scan arrives more than 10 minutes after the last alert for the tag
+- **THEN** an SMS is sent regardless of distance
+
+### Requirement: Swappable SMS sender
+SMS sending SHALL go through an abstraction so that automated tests and development never send real SMS. With no SMS credentials configured, the app SHALL use a logging sender.
+
+#### Scenario: No credentials in dev
+- **WHEN** SMS credentials are not configured
+- **THEN** sending an alert logs the message instead of calling the provider
+
+### Requirement: International number format
+Phone numbers SHALL be normalised to international format without a leading `+` or leading zero before sending (e.g. `+61432374487` or `0432374487` → `61432374487`).
+
+#### Scenario: Number normalisation
+- **WHEN** an owner or finder number is stored in any local format
+- **THEN** the SMS provider receives the normalised international form