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

openspec/changes/scan-flow/specs/database/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: sms_enabled column
+The `tags` table SHALL include an `sms_enabled` boolean column, NOT NULL with default TRUE. The schema SHALL add it idempotently so existing databases migrate cleanly.
+
+#### Scenario: Fresh database
+- **WHEN** `db/schema.sql` is applied to an empty database
+- **THEN** `tags.sms_enabled` exists, defaulting to TRUE
+
+#### Scenario: Existing database
+- **WHEN** `db/schema.sql` is re-applied to a database created before this column existed
+- **THEN** the column is added without error and existing rows default to TRUE

openspec/changes/scan-flow/specs/finder-contact/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Finder contact form
+The active tag page SHALL provide an input for the finder to leave their mobile number. Submitting SHALL store the number on the latest scan (`scans.scanner_phone`) and notify the owner by SMS with the finder's number.
+
+#### Scenario: Finder leaves a number
+- **WHEN** the finder submits a valid mobile number
+- **THEN** the number is stored in `scans.scanner_phone` and the owner receives an SMS containing it
+
+#### Scenario: Invalid input
+- **WHEN** the finder submits an empty or malformed number
+- **THEN** an inline error is shown and nothing is stored

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

@@ -0,0 +1,41 @@
+## ADDED Requirements
+
+### Requirement: Geolocation prompt on scan
+When a visitor opens the page of an active tag over HTTPS, the system SHALL request the visitor's location via the browser geolocation API. Granting SHALL send the coordinates to the server with the scan; denying SHALL NOT block the page.
+
+#### Scenario: Location granted
+- **WHEN** the finder allows location on an active tag page
+- **THEN** the coordinates are posted to the server and recorded with `location_shared = true`
+
+#### Scenario: Location denied
+- **WHEN** the finder denies the location request
+- **THEN** the page still shows the return details and the scan is recorded with `location_shared = false`
+
+### Requirement: Re-check location
+The tag page SHALL offer a "re-check location" button while no location has been shared. Activating it SHALL re-request the browser location. Once a location has been shared, the button SHALL be hidden.
+
+#### Scenario: Re-request after denial
+- **WHEN** the finder initially denied and presses "re-check location"
+- **THEN** the browser prompts again, and if granted the coordinates are sent to the server
+
+#### Scenario: Button hidden after share
+- **WHEN** a location has been successfully shared
+- **THEN** the re-check button is not displayed
+
+### Requirement: Scan recorded for every visit
+Every visit to an active tag page SHALL record a scan row (with or without location), flagged by `location_shared`.
+
+#### Scenario: Scan with location
+- **WHEN** a scan is posted with coordinates
+- **THEN** a `scans` row exists with lat/lng and `location_shared = true`
+
+#### Scenario: Scan without location
+- **WHEN** a scan is posted without coordinates
+- **THEN** a `scans` row exists with `location_shared = false` and null lat/lng
+
+### Requirement: SMS link to the owner
+The active tag page SHALL provide an `sms:` link to the owner's number with a prefilled message asking the finder for their phone number.
+
+#### Scenario: Finder opens the SMS link
+- **WHEN** the finder taps the "Send SMS" link
+- **THEN** the device SMS app opens with the owner's number and the prefilled message

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

openspec/changes/scan-flow/specs/tag-management/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Per-tag SMS alert toggle
+The tag edit form SHALL let the owner enable or disable SMS alerts for that tag (`sms_enabled`). The default for new and existing tags SHALL be enabled.
+
+#### Scenario: Disable alerts
+- **WHEN** the owner unchecks "Send SMS alerts when scanned" and saves
+- **THEN** the tag's `sms_enabled` is false and no alerts are sent for future scans (scans are still recorded)
+
+#### Scenario: Re-enable alerts
+- **WHEN** the owner checks the option and saves
+- **THEN** the tag's `sms_enabled` is true and alerts resume per the alerting rules