405 lines
16 KiB
Markdown
405 lines
16 KiB
Markdown
# 🏗️ Logic Spec: Subscription Card Upgrade (FinanceMainView)
|
|
|
|
**Date:** 2026-07-27
|
|
**Author:** System Architect (Architect Mode)
|
|
**Status:** 🔵 Blueprint — Ready for Code Mode Hand-off
|
|
**Masterbook Ref:** Master Book 2.0 / Epic 3: Financial Motor / Subscription Packages
|
|
|
|
---
|
|
|
|
## 1. 🎯 Objective
|
|
|
|
Transform the "📦 Csomagok" card (Card 2) in [`FinanceMainView.vue`](frontend_app/src/views/FinanceMainView.vue:118) from a dead display of the raw DB slug (`private_pro_v1`) into a highly functional dashboard widget showing:
|
|
|
|
| # | Feature | Priority |
|
|
|---|---------|----------|
|
|
| 1 | Human-readable display name (e.g., "Privát Pro") | P0 |
|
|
| 2 | Expiry/renewal date (e.g., "Érvényes: 2026.12.31-ig") | P0 |
|
|
| 3 | Vehicle usage capacity (e.g., "Kezelt járművek: 3 / 5") | P1 |
|
|
| 4 | Dynamic CTA button ("Csomag kezelése" / "Upgrade") | P1 |
|
|
|
|
---
|
|
|
|
## 2. 🔍 Gap Analysis
|
|
|
|
### 2.1 Current State — What Card 2 Shows Today
|
|
|
|
[`FinanceMainView.vue`](frontend_app/src/views/FinanceMainView.vue:118-154):
|
|
```ts
|
|
const subscriptionPlanName = computed(() => {
|
|
return authStore.user?.subscription_plan || '—'
|
|
})
|
|
```
|
|
This displays the raw DB slug like `private_pro_v1` with no formatting.
|
|
|
|
### 2.2 What Data IS Available
|
|
|
|
| Data Point | Source | Available in authStore? | Available via API? |
|
|
|------------|--------|------------------------|-------------------|
|
|
| `subscription_plan` (slug) | `identity.users.subscription_plan` | ✅ | `/auth/me` |
|
|
| `max_vehicles` | Resolved from `SubscriptionTier.rules.allowances` | ✅ | `/auth/me` (line 259) |
|
|
| `max_garages` | Resolved from `SubscriptionTier.rules.allowances` | ✅ | `/auth/me` (line 260) |
|
|
| `display_name` | `SubscriptionTier.rules.display_name` JSONB | ❌ | Only via `GET /subscriptions/my` |
|
|
| `subscription_expires_at` | `UserSubscription.valid_until` | ❌ NOT in `/auth/me` | `GET /subscriptions/my` |
|
|
| `vehicleCount` | `vehicleStore.vehicles.length` | N/A (vehicleStore) | N/A |
|
|
| `subscription_valid_until` | Org-level: `OrganizationSubscription.valid_until` | Partially (org data) | `GET /organizations/my` |
|
|
|
|
### 2.3 Key Gaps to Fill
|
|
|
|
1. **`subscription_expires_at` not in `/auth/me` response** — The backend `read_users_me()` already resolves `SubscriptionTier` for `max_vehicles`/`max_garages` but does NOT extract `valid_until` from the `UserSubscription`/`OrganizationSubscription` record.
|
|
|
|
2. **`subscription_display_name` not in `/auth/me` response** — The `SubscriptionTier.rules["display_name"]` JSONB field exists (e.g., `"display_name": "Privát Pro"`) but is never sent to the frontend via `/auth/me`.
|
|
|
|
3. **Card 2 doesn't use `vehicleStore`** — The vehicle count is already available in the `SubscriptionStatusWidget.vue` but not in `FinanceMainView.vue`.
|
|
|
|
---
|
|
|
|
## 3. 📐 Architecture: Data Flow (Current vs. Target)
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph "Current Flow (BROKEN)"
|
|
A1["/auth/me"] -->|subscription_plan slug| B1[authStore.user]
|
|
B1 -->|raw slug 'private_pro_v1'| C1[FinanceMainView Card 2]
|
|
end
|
|
|
|
subgraph "Target Flow (UPGRADED)"
|
|
A2["/auth/me"] -->|+ display_name + expires_at + max_vehicles| B2[authStore.user]
|
|
A2 -->|+ subscription_tier_id| B2
|
|
B2 -->|display_name 'Privát Pro'| C2[FinanceMainView Card 2]
|
|
B2 -->|expires_at '2026-12-31'| C2
|
|
B2 -->|max_vehicles 5| C2
|
|
D[vehicleStore.vehicles.length] -->|vehicleCount 3| C2
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 🛠️ Implementation Blueprint
|
|
|
|
### PHASE 1: Backend — Enrich `/auth/me` Response
|
|
|
|
**File:** [`backend/app/api/v1/endpoints/users.py`](backend/app/api/v1/endpoints/users.py)
|
|
|
|
#### Step 1.1: Resolve `subscription_expires_at` and `subscription_display_name`
|
|
|
|
In the `read_users_me()` function, after the P0 block at lines 206-253 (where `max_vehicles` and `max_garages` are resolved), add new resolution logic:
|
|
|
|
**Location:** After line 253 (`max_garages = int(allowances.get("max_garages", 1))`), add:
|
|
|
|
```python
|
|
# ── P0 Subscription Card Upgrade: resolve display_name and valid_until ──
|
|
subscription_display_name = None
|
|
subscription_valid_until = None
|
|
subscription_tier_id = None
|
|
|
|
if active_org_id is not None:
|
|
# Org-level: get valid_until from OrganizationSubscription
|
|
org_sub_full_stmt = (
|
|
select(OrganizationSubscription)
|
|
.where(
|
|
OrganizationSubscription.org_id == active_org_id,
|
|
OrganizationSubscription.is_active == True
|
|
)
|
|
.order_by(OrganizationSubscription.valid_from.desc())
|
|
.limit(1)
|
|
)
|
|
org_sub_full = (await db.execute(org_sub_full_stmt)).scalar_one_or_none()
|
|
if org_sub_full:
|
|
subscription_valid_until = org_sub_full.valid_until
|
|
subscription_tier_id = org_sub_full.tier_id
|
|
else:
|
|
# Personal mode: get valid_until from UserSubscription
|
|
user_sub_full_stmt = (
|
|
select(UserSubscription)
|
|
.where(
|
|
UserSubscription.user_id == current_user.id,
|
|
UserSubscription.is_active == True
|
|
)
|
|
.order_by(UserSubscription.valid_from.desc())
|
|
.limit(1)
|
|
)
|
|
user_sub_full = (await db.execute(user_sub_full_stmt)).scalar_one_or_none()
|
|
if user_sub_full:
|
|
subscription_valid_until = user_sub_full.valid_until
|
|
subscription_tier_id = user_sub_full.tier_id
|
|
|
|
# Resolve display_name from the already-fetched tier (reuse from lines 211-253)
|
|
if tier and tier.rules:
|
|
subscription_display_name = tier.rules.get("display_name", None)
|
|
```
|
|
|
|
#### Step 1.2: Add new fields to the response dict
|
|
|
|
After line 260 (`response_data["max_garages"] = max_garages`), add:
|
|
|
|
```python
|
|
response_data["subscription_expires_at"] = (
|
|
subscription_valid_until.isoformat() if subscription_valid_until else None
|
|
)
|
|
response_data["subscription_display_name"] = subscription_display_name
|
|
response_data["subscription_tier_id"] = subscription_tier_id
|
|
```
|
|
|
|
**Note:** The `_build_user_response()` helper at line 121-144 defines the base shape. We do NOT need to modify it — the new fields are injected after `_build_user_response()` returns, just like `max_vehicles` and `max_garages` already are.
|
|
|
|
---
|
|
|
|
### PHASE 2: Frontend — Update Type Definitions
|
|
|
|
**File:** [`frontend_app/src/stores/auth.ts`](frontend_app/src/stores/auth.ts)
|
|
|
|
#### Step 2.1: Extend `UserProfile` interface
|
|
|
|
Add two new fields to the `UserProfile` interface (after line 66 `max_garages`):
|
|
|
|
```typescript
|
|
/** P0 Subscription Card Upgrade: Human-readable plan name (e.g., "Privát Pro") */
|
|
subscription_display_name?: string | null
|
|
/** P0 Subscription Card Upgrade: FK to system.subscription_tiers */
|
|
subscription_tier_id?: number | null
|
|
```
|
|
|
|
The `subscription_expires_at` field already exists at line 63. ✅
|
|
|
|
---
|
|
|
|
### PHASE 3: Frontend — Rewrite Card 2 in FinanceMainView
|
|
|
|
**File:** [`frontend_app/src/views/FinanceMainView.vue`](frontend_app/src/views/FinanceMainView.vue)
|
|
|
|
#### Step 3.1: Import `useVehicleStore`
|
|
|
|
Add to the imports at line 228:
|
|
```typescript
|
|
import { useVehicleStore } from '../stores/vehicle'
|
|
```
|
|
|
|
#### Step 3.2: Initialize vehicle store
|
|
|
|
After line 234:
|
|
```typescript
|
|
const vehicleStore = useVehicleStore()
|
|
```
|
|
|
|
#### Step 3.3: Replace the computed property
|
|
|
|
Replace lines 249-252:
|
|
```typescript
|
|
// ── Card 2: Subscription data (upgraded) ──────────────────────────
|
|
const subscriptionDisplayName = computed(() => {
|
|
// Priority: 1) display_name from backend, 2) humanized slug, 3) fallback
|
|
const displayName = authStore.user?.subscription_display_name
|
|
if (displayName) return displayName
|
|
const plan = authStore.user?.subscription_plan
|
|
if (!plan || plan === 'FREE') return t('subscription.free')
|
|
// Simple slug→human mapping as fallback
|
|
const slugMap: Record<string, string> = {
|
|
'private_pro_v1': 'Privát Pro',
|
|
'corp_premium_v1': 'Céges Prémium',
|
|
'corp_premium_plus_v1': 'Céges Prémium Plus',
|
|
}
|
|
return slugMap[plan] || plan
|
|
})
|
|
|
|
const subscriptionExpiresAt = computed(() => {
|
|
return authStore.user?.subscription_expires_at ?? null
|
|
})
|
|
|
|
const formattedExpiry = computed(() => {
|
|
const raw = subscriptionExpiresAt.value
|
|
if (!raw) return null
|
|
const d = new Date(raw)
|
|
if (isNaN(d.getTime())) return null
|
|
return `${d.getFullYear()}.${String(d.getMonth() + 1).padStart(2, '0')}.${String(d.getDate()).padStart(2, '0')}`
|
|
})
|
|
|
|
const isExpired = computed(() => {
|
|
const raw = subscriptionExpiresAt.value
|
|
if (!raw) return false
|
|
return new Date(raw) < new Date()
|
|
})
|
|
|
|
const vehicleCount = computed(() => vehicleStore.vehicles?.length || 0)
|
|
const maxVehicles = computed(() => authStore.user?.max_vehicles ?? 0)
|
|
const vehiclePercent = computed(() => {
|
|
if (!maxVehicles.value || maxVehicles.value <= 0) return 0
|
|
return Math.min(100, (vehicleCount.value / maxVehicles.value) * 100)
|
|
})
|
|
|
|
// CTA routing depends on mode
|
|
const ctaRoute = computed(() => {
|
|
if (authStore.isCorporateMode && authStore.user?.active_organization_id) {
|
|
return `/organization/${authStore.user.active_organization_id}/subscription`
|
|
}
|
|
return '/dashboard/subscription'
|
|
})
|
|
|
|
const ctaLabel = computed(() => {
|
|
if (isExpired.value) return t('subscription.renewNow') || 'Újítás most'
|
|
return t('subscription.managePlan')
|
|
})
|
|
```
|
|
|
|
#### Step 3.4: Replace Card 2 template (lines 118-154)
|
|
|
|
Replace the entire Card 2 block with:
|
|
|
|
```vue
|
|
<!-- ═══════════════════════════════════════════════════════════════
|
|
Card 2: 📦 Csomagok (Packages) — UPGRADED
|
|
Shows display_name, expiry date, vehicle usage, dynamic CTA.
|
|
═══════════════════════════════════════════════════════════════ -->
|
|
<div
|
|
class="bg-white/95 rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.12)] overflow-hidden flex flex-col h-[350px] relative transition-all duration-300 ease-out transform hover:-translate-y-3 hover:scale-[1.02] hover:shadow-2xl"
|
|
>
|
|
<!-- Header bar -->
|
|
<div class="h-12 bg-gradient-to-r from-sky-600 to-sky-700 w-full shrink-0 flex items-center px-4">
|
|
<span class="text-white font-bold text-sm tracking-wide">📦 {{ t('subscription.title') }}</span>
|
|
<span
|
|
:class="isExpired ? 'bg-red-500/30 text-red-200' : 'bg-emerald-500/30 text-emerald-200'"
|
|
class="ml-auto inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium"
|
|
>
|
|
{{ isExpired ? t('subscription.expired') : t('subscription.active') }}
|
|
</span>
|
|
</div>
|
|
|
|
<!-- Content -->
|
|
<div class="p-4 flex-1 flex flex-col text-slate-800 overflow-hidden">
|
|
<div class="flex-1 space-y-3">
|
|
<!-- Plan name -->
|
|
<div class="rounded-xl border border-slate-200 bg-slate-50 p-3 text-center">
|
|
<p class="text-xs text-slate-500 font-semibold uppercase tracking-wider mb-1">
|
|
{{ t('subscription.active') }}
|
|
</p>
|
|
<p class="text-2xl font-extrabold text-sky-600">
|
|
{{ subscriptionDisplayName }}
|
|
</p>
|
|
</div>
|
|
|
|
<!-- Expiry date -->
|
|
<div v-if="formattedExpiry" class="rounded-lg border border-slate-200 bg-slate-50 p-2.5 text-center">
|
|
<p class="text-xs text-slate-500">
|
|
{{ t('subscription.expiresAt') }}:
|
|
<span
|
|
:class="isExpired ? 'text-red-600 font-bold' : 'text-slate-700 font-semibold'"
|
|
>{{ formattedExpiry }}</span>
|
|
</p>
|
|
</div>
|
|
|
|
<!-- Vehicle usage -->
|
|
<div v-if="maxVehicles > 0" class="space-y-1">
|
|
<div class="flex items-center justify-between text-xs text-slate-500">
|
|
<span>🚗 {{ t('subscription.vehicles') }}</span>
|
|
<span class="font-semibold text-slate-700">{{ vehicleCount }} / {{ maxVehicles }}</span>
|
|
</div>
|
|
<div class="w-full h-1.5 rounded-full bg-slate-200 overflow-hidden">
|
|
<div
|
|
class="h-full rounded-full transition-all duration-500"
|
|
:class="vehiclePercent >= 90 ? 'bg-red-500' : vehiclePercent >= 75 ? 'bg-amber-400' : 'bg-sky-500'"
|
|
:style="{ width: `${Math.min(vehiclePercent, 100)}%` }"
|
|
/>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- CTA Button -->
|
|
<div class="shrink-0 pt-2">
|
|
<router-link
|
|
:to="ctaRoute"
|
|
class="block w-full text-center px-4 py-2.5 rounded-xl text-sm font-semibold transition-all duration-200 shadow-md hover:shadow-lg active:scale-[0.98]"
|
|
:class="isExpired
|
|
? 'bg-gradient-to-r from-amber-500 to-orange-600 text-white hover:from-amber-400 hover:to-orange-500'
|
|
: 'bg-gradient-to-r from-sky-600 to-indigo-600 text-white hover:from-sky-500 hover:to-indigo-500'"
|
|
>
|
|
{{ ctaLabel }}
|
|
</router-link>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
#### Step 3.5: Add `onMounted` vehicle fetch
|
|
|
|
In the existing `onMounted` block at line 263-265, add vehicle store fetch:
|
|
```typescript
|
|
onMounted(() => {
|
|
financeStore.fetchWalletBalance()
|
|
// Ensure vehicles are loaded for usage display
|
|
if (vehicleStore.vehicles.length === 0) {
|
|
vehicleStore.fetchVehicles()
|
|
}
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
### PHASE 4: Frontend — I18n Keys
|
|
|
|
**Files:** [`frontend_app/src/i18n/hu.ts`](frontend_app/src/i18n/hu.ts), [`frontend_app/src/i18n/en.ts`](frontend_app/src/i18n/en.ts)
|
|
|
|
#### Step 4.1: Add new Hungarian keys
|
|
|
|
In `hu.ts`, inside the `subscription:` block (after line 87):
|
|
```typescript
|
|
renewNow: 'Újítás most',
|
|
upgradePlan: 'Csomag váltása',
|
|
```
|
|
|
|
#### Step 4.2: Add new English keys
|
|
|
|
In `en.ts`, inside the `subscription:` block (at corresponding position):
|
|
```typescript
|
|
renewNow: 'Renew Now',
|
|
upgradePlan: 'Upgrade Plan',
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 📋 Files Changed Summary
|
|
|
|
| # | File | Change Type | Lines Affected |
|
|
|---|------|-------------|---------------|
|
|
| 1 | [`backend/app/api/v1/endpoints/users.py`](backend/app/api/v1/endpoints/users.py) | Add `display_name` + `valid_until` resolution | ~+30 lines after L253 |
|
|
| 2 | [`frontend_app/src/stores/auth.ts`](frontend_app/src/stores/auth.ts) | Add `subscription_display_name`, `subscription_tier_id` to `UserProfile` | ~+3 lines after L66 |
|
|
| 3 | [`frontend_app/src/views/FinanceMainView.vue`](frontend_app/src/views/FinanceMainView.vue) | Rewrite Card 2 template + computed properties | Replace L118-154, add computed after L252 |
|
|
| 4 | [`frontend_app/src/i18n/hu.ts`](frontend_app/src/i18n/hu.ts) | Add `renewNow`, `upgradePlan` keys | ~+2 lines after L87 |
|
|
| 5 | [`frontend_app/src/i18n/en.ts`](frontend_app/src/i18n/en.ts) | Add `renewNow`, `upgradePlan` keys | ~+2 lines at matching position |
|
|
|
|
---
|
|
|
|
## 6. ⚠️ Risk Assessment
|
|
|
|
| Risk | Mitigation |
|
|
|------|-----------|
|
|
| `display_name` may be `null` in old tier records | Fallback chain: display_name → slug→human map → "—" |
|
|
| `valid_until` may be `None` for lifetime subscriptions | Conditionally render expiry block (`v-if="formattedExpiry"`) |
|
|
| `vehicleStore.vehicles` might not be loaded yet | `onMounted` fetches vehicles if needed |
|
|
| Corporate vs. Individual mode routing | `ctaRoute` computed handles both modes |
|
|
|
|
---
|
|
|
|
## 7. 🧪 Testing Checklist
|
|
|
|
- [ ] Card 2 shows `display_name` (e.g., "Privát Pro") instead of raw slug
|
|
- [ ] Expiry date displayed as `YYYY.MM.DD` format
|
|
- [ ] "Lejárt" badge shown when subscription is expired
|
|
- [ ] Vehicle usage bar shows correct `vehicleCount / maxVehicles`
|
|
- [ ] CTA button navigates to correct route (personal or org subscription page)
|
|
- [ ] CTA label changes to "Újítás most" when expired
|
|
- [ ] Fallback works for users without `display_name` in their tier
|
|
- [ ] No regressions on Card 1 (Wallet) and other cards
|
|
- [ ] I18n keys work in both `hu` and `en` locales
|
|
|
|
---
|
|
|
|
## 8. 📎 References
|
|
|
|
- [`SubscriptionTier` model](backend/app/models/core_logic.py:68) — `system.subscription_tiers`
|
|
- [`UserSubscription` model](backend/app/models/core_logic.py:174) — `finance.user_subscriptions`
|
|
- [`OrganizationSubscription` model](backend/app/models/core_logic.py:143) — `finance.org_subscriptions`
|
|
- [`SubscriptionService`](backend/app/services/subscription_service.py:74) — Full subscription resolution logic
|
|
- [`SubscriptionStatusWidget`](frontend_app/src/components/dashboard/SubscriptionStatusWidget.vue) — Existing rich widget (dark theme)
|
|
- [`SubscriptionInfoModal`](frontend_app/src/components/subscription/SubscriptionInfoModal.vue) — Modal with detailed info
|
|
- [P0 Subscription JSONB Audit](docs/p0_subscription_jsonb_structural_audit_report.md) — Tier JSONB structure verified
|