d29f3e6487
- Add comprehensive tier feature matrix spec defining Free/Basic/Plus/Pro capabilities across recommendations, predictions, history, logs, tools, and family sharing - Add `stripe_price_id_annual` column to plans table and rename existing column to `stripe_price_id_monthly` - Normalize legacy fuel type aliases (petrol→e10, diesel→b7_standard) in users table - Implement BillingController with checkout, portal, success/cancel routes supporting monthly/annual cadence - Add admin subscription assignment in Filament user edit page with admin-granted subscription support - Add DowngradeUserOnSubscriptionDeleted listener to disable WhatsApp/SMS preferences on subscription cancellation - Add MissedNotificationsOverview widget to Filament user detail page - Add PollFuelPricesTest covering auto-refresh scenarios - Add PriceReliability enum with reliability classification based on price age - Add fuelTypes.js constants file exporting FUEL_TYPES from window global
145 lines
6.0 KiB
Markdown
145 lines
6.0 KiB
Markdown
# FuelAlert — Tier Feature Design (Free / Basic / Plus / Pro)
|
|
|
|
## Context
|
|
|
|
The existing tier rules (`.claude/rules/tiers.md`) define notification channels
|
|
per plan but not the *information* features that make each tier feel worth
|
|
paying for. This spec closes that gap by cataloguing always-on information,
|
|
personalisation, and analytics features — the value a user sees whether or not
|
|
a notification fires — and mapping them to the four tiers. Triggered channel
|
|
rules (email/push/WhatsApp/SMS) remain unchanged and are not redefined here.
|
|
|
|
Goals:
|
|
- Give each upgrade a concrete "what do I get for £X more" answer.
|
|
- Keep free tier useful enough to retain, but with clear ceiling.
|
|
- Keep Plus the commercial sweet spot (LLM prediction + fuel logs + MPG).
|
|
- Keep Pro genuinely premium (unlimited, multi-location, route planning, family sharing).
|
|
|
|
Teaser strategy: **hybrid** — headline features (prediction, extended history,
|
|
detailed confidence) are visible but blurred with an upgrade CTA on Free; minor
|
|
Pro-only features (route planner, family sharing) are hidden from lower tiers.
|
|
|
|
---
|
|
|
|
## Feature Matrix
|
|
|
|
### 1. Fill-up recommendation (from `AlertScoringService`)
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Recommendation (`fill_up` / `wait` / `no_signal`) | ✓ | ✓ | ✓ | ✓ |
|
|
| Confidence % + reason string | — | ✓ | ✓ | ✓ |
|
|
| Per-signal breakdown (which of 5 signals fired, weights) | — | — | — | ✓ |
|
|
| Accuracy self-tracking ("our last wait call saved you Xp/L") | — | — | ✓ | ✓ |
|
|
|
|
### 2. Oil price prediction (from `price_predictions`)
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Direction only (EWMA, no reasoning) | — | ✓ | ✓ | ✓ |
|
|
| Full LLM prediction (direction + confidence + reasoning) | — | — | ✓ | ✓ |
|
|
| Historical prediction accuracy view | — | — | — | ✓ |
|
|
|
|
Rationale: Basic sees *that* prices are expected to rise/fall; Plus sees *why*.
|
|
|
|
### 3. Price history & trends
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Local price today | ✓ | ✓ | ✓ | ✓ |
|
|
| Price history chart | 7 days | 14 days | 90 days | 365 days |
|
|
| Brand comparison ("Tesco avg vs Shell avg near you") | — | — | ✓ | ✓ |
|
|
| Local price leaderboard (cheapest N nearby) | top 3 / 5km | top 5 / 5km | top 10 / 15km | top 20 / 50km |
|
|
|
|
### 4. Saved data & personalisation
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Saved home postcode | ✓ | ✓ | ✓ | ✓ |
|
|
| Tracked fuel types | 1 | 1 | 1 | unlimited |
|
|
| Saved stations (favourites) | 1 | 3 | 10 | unlimited |
|
|
| Multiple locations (home/work/commute) | — | — | 2 | 5 |
|
|
| Custom price thresholds per fuel/station | — | 1 | 3 | unlimited |
|
|
|
|
(Fuel-type cap for free/basic/plus matches existing `tiers.md` rule.)
|
|
|
|
### 5. Fuel logs & personal analytics (new)
|
|
|
|
Simple log: date, litres, price per litre, optional odometer.
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Log fill-ups (basic entry) | — | last 10 | last 100 | unlimited |
|
|
| MPG / cost-per-mile (needs odometer) | — | — | ✓ | ✓ |
|
|
| Monthly spend report | — | — | ✓ | ✓ |
|
|
| "You saved £X by following our advice" attribution | — | — | — | ✓ |
|
|
| CSV export of fuel log | — | — | — | ✓ |
|
|
|
|
### 6. Tools (new, mostly Pro)
|
|
|
|
| Feature | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| Route planner — cheapest station along A→B | — | — | — | ✓ |
|
|
| Commute calculator — is the detour worth it? | — | — | — | ✓ |
|
|
| Family / household sharing (2 extra members on one account) | — | — | — | ✓ |
|
|
|
|
---
|
|
|
|
## Plan `features` JSON shape (additions)
|
|
|
|
Extend the existing `features` JSON in the `plans` table (see `tiers.md` for
|
|
existing shape). New keys to add:
|
|
|
|
```json
|
|
{
|
|
"history_days": 7,
|
|
"prediction": { "level": "none" },
|
|
"recommendation": { "confidence_visible": false, "signal_breakdown": false, "accuracy_tracking": false },
|
|
"leaderboard": { "count": 3, "radius_km": 5 },
|
|
"saved_stations": { "max": 1 },
|
|
"locations": { "max": 1 },
|
|
"thresholds": { "max": 0 },
|
|
"fuel_log": { "enabled": false, "max_entries": 0, "mpg": false, "monthly_report": false, "savings_attribution": false, "csv_export": false },
|
|
"brand_comparison": false,
|
|
"route_planner": false,
|
|
"commute_calculator": false,
|
|
"family_sharing": { "enabled": false, "max_members": 0 }
|
|
}
|
|
```
|
|
|
|
`prediction.level` values: `none` | `direction` (EWMA only) | `full` (LLM +
|
|
reasoning) | `full_with_accuracy` (Pro).
|
|
|
|
### Seeded values per tier
|
|
|
|
| Key | Free | Basic | Plus | Pro |
|
|
|---|---|---|---|---|
|
|
| `history_days` | 7 | 14 | 90 | 365 |
|
|
| `prediction.level` | `none` | `direction` | `full` | `full_with_accuracy` |
|
|
| `recommendation.confidence_visible` | false | true | true | true |
|
|
| `recommendation.signal_breakdown` | false | false | false | true |
|
|
| `recommendation.accuracy_tracking` | false | false | true | true |
|
|
| `leaderboard.count` / `radius_km` | 3 / 5 | 5 / 5 | 10 / 15 | 20 / 50 |
|
|
| `saved_stations.max` | 1 | 3 | 10 | null (unlimited) |
|
|
| `locations.max` | 1 | 1 | 2 | 5 |
|
|
| `thresholds.max` | 0 | 1 | 3 | null |
|
|
| `fuel_log.enabled` | false | true | true | true |
|
|
| `fuel_log.max_entries` | 0 | 10 | 100 | null |
|
|
| `fuel_log.mpg` | false | false | true | true |
|
|
| `fuel_log.monthly_report` | false | false | true | true |
|
|
| `fuel_log.savings_attribution` | false | false | false | true |
|
|
| `fuel_log.csv_export` | false | false | false | true |
|
|
| `brand_comparison` | false | false | true | true |
|
|
| `route_planner` | false | false | false | true |
|
|
| `commute_calculator` | false | false | false | true |
|
|
| `family_sharing.enabled` / `max_members` | false / 0 | false / 0 | false / 0 | true / 2 |
|
|
|
|
---
|
|
|
|
## Out of scope (explicit)
|
|
|
|
- Implementation of route planner, commute calculator, brand comparison, family sharing — this spec gates them but their actual logic/UI is separate projects.
|
|
- Fuel log UI/import — separate project; this spec only defines the model and caps.
|
|
- Ads on free tier — dropped per user decision.
|
|
- Public API, shareable widgets, early access flags — dropped per user decision.
|