38 lines
3.1 KiB
Markdown
38 lines
3.1 KiB
Markdown
## 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.
|