Add tier feature design spec, annual billing, fuel type normalization, and admin subscription management
- 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
This commit is contained in:
Ovidiu U
144
docs/superpowers/specs/2026-04-15-tier-features-design.md
Normal file
144
docs/superpowers/specs/2026-04-15-tier-features-design.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user