docs: product model + AUD pricing, SMS metering, location-link flow, variants, scope

docs/PRODUCT-MODEL.md

@@ -0,0 +1,74 @@
+# Where Woof — Product Model & Pricing (AUD)
+
+Scope: keep small and lean now; rebuild a larger system once there are a few thousand customers.
+**Explicitly out of scope (from the old CMS):** the page-builder/CMS flow and SMS campaigns — ignored.
+
+## Two use cases (the core split)
+
+| | **Info tags** (bulk operators: parks, trails, campgrounds) | **Owner-alert tags** (dogs, luggage, valuables) |
+|---|---|---|
+| What the finder sees | Rich info page (multilingual, custom content per tag) | Return details + call/SMS the owner |
+| SMS to owner | **Never** (no SMS → no SMS cost) | **Automatic on every scan with location** (+ finder can also message) |
+| Pricing | Per-tag or annual license | $1 tag + annual fee with **metered SMS** |
+| Cost exposure | ~zero (DB only) | SMS metered (the business's only real variable cost) |
+
+## How SMS actually fires (important)
+
+- When a finder scans and **approves location → an SMS is automatically sent to the owner**. It is not the scanner's choice (they can *also* send one via the contact form).
+- So: **every scan-with-location = 1 SMS = cost**. The throttles (250 m / 10 min, fingerprint 24 h, daily/IP caps) are *cost control*, but different finders at different spots legitimately each alert.
+- A heavily-lost dog could generate several SMS/day → that's the meter working as designed (frequent loss → credits consumed → top-ups).
+
+## Costs to design against (AUD, ex GST — 10% GST to add at checkout)
+
+| Item | Cost |
+|---|---|
+| SMSGlobal **prepaid** (current) | ~**AU$0.06 / SMS** |
+| SMSGlobal plans at volume (Build→Scale) | ~$0.03 → ~$0.013 / SMS |
+| DB/storage/bandwidth per scan | **negligible** (a scan ≈ 100–150 bytes; 10k scans/day ≈ 1.5 MB/day) — data is not a cost driver, SMS is |
+| Tag manufacture (Asia, preset) | your cost basis; retail margin on top |
+
+## Proposed retail pricing (AUD) — pinch points to tune
+
+**Owner-alert tags**
+- Tag: **$1.50–2.00** per tag (one-off)
+- Annual plan: **$5/year = 10 SMS** (your cost ≈ 60¢ prepaid → ~88% margin)
+- **Top-ups**: $2.50 / 5 SMS · $4.50 / 10 SMS · $8 / 20 SMS
+- Unused credits: roll over within the year; reset (or cap) at renewal — decide per plan
+
+**Family bundles** (pooled SMS across the account's tags)
+- **5 tags / $20 yr** (50 SMS pool) · **10 tags / $35 yr** (100) · **20 tags / $60 yr** (200)
+- Cost check @6¢: 20-tag plan = 200 SMS × 6¢ = $12 vs $60 retail → ~80% margin even if fully used
+
+**Info tags (bulk)**
+- e.g. **$1.50/tag** one-off **or** an annual operator license (e.g. $30/yr for up to 100 tags + content management) — no SMS, near-100% margin; tune with the parks use case
+
+**Pinch points to nail before launch**
+1. **Metering enforced server-side** — count only *sent* (OK:0) SMS; block when credits hit 0 → triggers the unlock flow.
+2. **Renewal reminders** (30/7/1 days before) + **grace period** (~7 days) before lapsed.
+3. **Top-up profitability at the 6¢ prepaid rate** (works above; even better on a plan).
+4. **GST** (10%) — decide ex/incl display.
+5. Finder-contact SMS counts toward the **same** meter.
+6. Bulk-operator licenses vs per-tag — pick per deal.
+
+## The missed location-link flow
+
+- Scan → owner SMS contains a **short URL** (`where-woof.com/s/Ab3xY9` — shortener needed; also keeps lat/lng out of the SMS, which is already ~160-char constrained).
+- The link opens a **location page**: embedded Google Map of the finder's position + finder details (phone if left) + link back to the tag page.
+- **Unpaid variant**: the SMS/email instead says *"your item was found — pay the $5 annual fee to unlock the details"* (the 2014 `late_payment` flow). ⚠️ No email system yet — use SMTP (hosting) or ntfy on .13 as interim.
+- Location page is the owner's private view: keyed by the unguessable short code; decide validity window.
+
+## Product range & variants (coming)
+
+- Tags are **manufactured in Asia → preset IDs** (100 in registry; new runs generate IDs per production order).
+- Broader range coming: **sizes, colours, plaques (outdoor), screw-on** etc. → needs `product_variants` (products + variant attributes) later.
+- QR/NFC **production step needed** for new runs (QR generation util — the old `qrcode.php` pattern).
+- Multilingual info pages (i18n) for the info-tag use case.
+
+## Schema implications (future, keep lean)
+
+- `sms_allocated` / `sms_used` per tag or account + a **top-up ledger** (the old `sms_billing` / `product_network_costs` concept).
+- `orders` already has status (pending/paid/lapsed/cancelled) → renewal = new order/period; add `renews_at`.
+- `users.paused` (admin pause → gate alerts) + audit log (`product_accounts_actions` pattern).
+- `url_shortened` table + `location_page` (scan → location page keyed by code).
+- `product_variants` when the range expands.
+- Email channel abstraction (ntfy now, SMTP later).