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

openspec/changes/scan-flow/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+Phase 1 built the foundation (auth, tag setup, public page), but the core product moment is missing: a finder scans a lost item's tag and the **owner is alerted** so the item can be returned. Phase 2 delivers the scan flow — geolocation on scan, SMS alert to the owner via SMSGlobal, a finder-contact channel, and the branding polish ("Where Woof", werewolf wordplay).
+
+## What Changes
+
+- **Scan recording**: `POST /t/{tag_code}/scan` records every scan (with or without location) into the existing `scans` table.
+- **Geolocation flow** (vanilla JS on the public tag page): prompt for location on load (HTTPS), send coordinates with the scan, **re-check location** button, button hidden once shared.
+- **SMS alerts to owner (SMSGlobal)**: on scan of an `sms_enabled` tag, send the owner an SMS with item type + name, time, maps link, and tag page link. No location shared → alert still sent (first time) with "no location" wording.
+- **Location-aware throttle**: within a 10-minute window per tag, only re-send if the new location is **>250 m** from the last alerted location. Same spot → record the scan but do not re-alert.
+- **`sms_enabled` per tag**: new column (default true); owners can switch a tag to purely informational (no SMS at all) from the edit form.
+- **Finder contact**: finder can leave their mobile → stored in `scans.scanner_phone` → owner is SMS'd with the finder's number.
+- **`sms:` link** on the tag page (prefilled message asking the finder for their number).
+- **Branding**: "WhereWoof" → **"Where Woof"**, page title **"Where Woof !"** (play on *werewolf*).
+- Provider detail (confirmed with owner): SMSGlobal, **pooled/shared sender number** (origin blank; upgrade to registered sender later), real test number `+61432374487`.
+
+## Capabilities
+
+### New Capabilities
+
+- `scan-flow`: geolocation prompt, scan recording, re-check button, hide-after-share, `sms:` link.
+- `sms-alerting`: SMSGlobal integration behind a swappable `Sender` interface, message template, location-aware throttle (250 m / 10 min), `sms_enabled` respected, `alert_sent` tracking.
+- `finder-contact`: finder phone input → stored → owner notified.
+
+### Modified Capabilities
+
+- `tag-management`: ADDED — per-tag `sms_enabled` toggle on the edit form (default on).
+- `database`: ADDED — `tags.sms_enabled` column (idempotent `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, default TRUE).
+
+## Impact
+
+- **New Go**: `internal/sms` (Sender interface, `smsglobal` HTTP client, `log` fake, haversine distance), `internal/handlers/scan.go`.
+- **Modified Go**: `internal/handlers/tags.go` (sms_enabled in edit), `internal/db/queries.sql` (InsertScan, GetLastScan, UpdateTagDetails + sms_enabled), `main.go` (2 routes + sender wiring).
+- **Modified templates**: `tag-public.html` (geolocation JS, sms: link, contact form), `tag-edit.html` (sms_enabled checkbox), all templates + README (branding).
+- **Schema**: `db/schema.sql` gains idempotent `sms_enabled` column.
+- **Secrets (never in repo)**: `SMS_API_KEY`, `SMS_API_SECRET` (SMSGlobal MXT), optional `SMS_FROM` (blank = pooled number). No key set → app uses the log sender (safe dev default).
+- **No changes** to auth, deployment, or billing phases.