pénzügyi modul továbbfejlesztése (csomagkezelés)

2026-07-29 09:46:10 +00:00
parent 6f28d3e70d
commit 75904cd2f8
50 changed files with 5851 additions and 312 deletions
--- a/plans/logic_spec_subscription_card_upgrade.md
+++ b/plans/logic_spec_subscription_card_upgrade.md
@@ -0,0 +1,404 @@
+# 🏗️ 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