service-finder/docs/financial_module_comprehensive_audit_2026-07-25.md

# 🔍 Comprehensive Financial Module Audit

**Date:** 2026-07-25
**Auditor:** Rendszer-Architect (🏗️ Architect Mode)
**Scope:** Full-stack financial system audit — Models, API, Services, Workers, Frontend
**Executive Summary:**

> The financial backend is **well-architected and modular**. The model layer follows DDD schema separation, the service layer splits into distinct managers, the API provides complete user-facing endpoints, and all system workers properly write to the audit ledger. The **critical gap is the frontend** — zero financial UI exists for end users despite the backend being fully ready.

---

## 1. MODELS — Schema & Architecture

### ✅ STATUS: WELL-ARCHITECTED — No Monolith

| Schema | Table | Purpose | File |
|--------|-------|---------|------|
| `identity` | `wallets` | Quadruple wallet: earned, purchased, service_coins + ActiveVouchers (FIFO) | [`models/identity/identity.py:263`](dev/service_finder/backend/app/models/identity/identity.py:263) |
| `identity` | `active_vouchers` | FIFO voucher tracking with expiration | [`models/identity/identity.py:316`](dev/service_finder/backend/app/models/identity/identity.py:316) |
| `audit` | `financial_ledger` | Immutable double-entry ledger (DEBIT/CREDIT) | [`models/system/audit.py:78`](dev/service_finder/backend/app/models/system/audit.py:78) |
| `fleet_finance` | `cost_categories` | Hierarchical cost category tree | [`models/fleet_finance/models.py:37`](dev/service_finder/backend/app/models/fleet_finance/models.py:37) |
| `fleet_finance` | `asset_costs` | Operational expense log (TCO) | [`models/fleet_finance/models.py:109`](dev/service_finder/backend/app/models/fleet_finance/models.py:109) |
| `fleet_finance` | `asset_financials` | Acquisition & depreciation | [`models/fleet_finance/models.py:180`](dev/service_finder/backend/app/models/fleet_finance/models.py:180) |
| `fleet_finance` | `insurance_providers` | Insurance company catalog | [`models/fleet_finance/models.py:219`](dev/service_finder/backend/app/models/fleet_finance/models.py:219) |
| `fleet_finance` | `vehicle_insurance_policies` | Vehicle insurance policies | [`models/fleet_finance/models.py:248`](dev/service_finder/backend/app/models/fleet_finance/models.py:248) |
| `fleet_finance` | `vehicle_tax_obligations` | Tax obligations per vehicle | [`models/fleet_finance/models.py:298`](dev/service_finder/backend/app/models/fleet_finance/models.py:298) |
| `finance` | `issuers` | Billing entities (KFT/EV/BT/ZRT) | [`models/marketplace/finance.py:27`](dev/service_finder/backend/app/models/marketplace/finance.py:27) |
| `marketplace` | `payment_intents` | Payment intent lifecycle (Double Lock) | [`models/marketplace/payment.py`](dev/service_finder/backend/app/models/marketplace/payment.py) |
| `core_logic` | `subscription_tiers` | Subscription tier definitions | [`models/core_logic.py`](dev/service_finder/backend/app/models/core_logic.py) |
| `core_logic` | `user_subscriptions` / `org_subscriptions` | Subscription state tracking | [`models/core_logic.py`](dev/service_finder/backend/app/models/core_logic.py) |

### Key Enums (Defined in [`audit.py:58`](dev/service_finder/backend/app/models/system/audit.py:58))
- `LedgerEntryType`: `DEBIT`, `CREDIT`
- `WalletType`: `EARNED`, `PURCHASED`, `SERVICE_COINS`, `VOUCHER`
- `LedgerStatus`: `PENDING`, `SUCCESS`, `FAILED`, `REFUNDED`, `REFUND`

---

## 2. API ENDPOINTS — Routing & User Access

### ✅ STATUS: WELL-COVERED

| Method | Endpoint | Purpose | User-Facing? | RBAC |
|--------|----------|---------|-------------|------|
| `POST` | `/billing/upgrade` | Package upgrade | ✅ Yes | Auth required |
| `POST` | `/billing/payment-intent/create` | Create PaymentIntent | ✅ Yes | Auth required |
| `POST` | `/billing/payment-intent/{id}/stripe-checkout` | Initiate Stripe checkout | ✅ Yes | Auth required |
| `POST` | `/billing/payment-intent/{id}/process-internal` | Internal gifting deduction | ✅ Yes | Auth required |
| `POST` | `/billing/stripe-webhook` | Stripe callback | N/A (webhook) | Signature |
| `GET` | `/billing/payment-intent/{id}/status` | PaymentIntent status | ✅ Yes | Auth required |
| `GET` | `/billing/wallet/balance` | User wallet balances | ✅ Yes | Auth required |
| `GET` | `/billing/wallet/transactions` | User transaction History | ✅ Yes | Auth required |
| `POST` | `/financial-manager/purchase-package` | Full purchase lifecycle | ✅ Yes | Auth required |
| `GET` | `/financial-manager/status` | Service health check | ✅ Yes | Auth required |
| `GET` | `/finance/issuers/` | List billing issuers | ❌ Admin | `finance:view` |
| `PATCH` | `/finance/issuers/{id}` | Update issuer | ❌ Admin | `finance:edit` |
| `GET` | `/admin/finance/ledger` | Admin ledger view | ❌ Admin | `finance:view` |
| `POST` | `/expenses/` | Create expense (TCO) | ✅ Yes | Auth + Capability |
| `PUT` | `/expenses/{id}` | Update expense | ✅ Yes | Auth |
| `GET` | `/expenses/` | List all expenses | ❌ Admin | Auth |
| `GET` | `/expenses/{asset_id}` | Asset-specific expenses | ✅ Yes | Auth |
| `GET` | `/subscriptions/public` | Public package catalog | ✅ Public | None |
| `GET` | `/subscriptions/my` | Current subscription | ✅ Yes | Auth |
| `GET` | `/subscriptions/feature-flags` | Resolved feature flags | ✅ Yes | Auth |

### Router Registration (in [`api/v1/api.py:1`](dev/service_finder/backend/app/api/v1/api.py:1))
- `billing.router` → `/billing` ✅
- `financial_manager.router` → `/financial-manager` ✅
- `finance_admin.router` → `/finance/issuers` + `/admin/finance` ✅

---

## 3. SERVICES — Monolith vs. Modular Managers

### ✅ STATUS: MODULAR & SEPARATED — Minor Overlap Risk

| Service File | Responsibility | Lines | 
|-------------|---------------|-------|
| [`billing_engine.py`](dev/service_finder/backend/app/services/billing_engine.py:1) | Core: PricingCalculator, SmartDeduction (FIFO), AtomicTransactionManager (double-entry) | ~1070 | 
| [`financial_manager.py`](dev/service_finder/backend/app/services/financial_manager.py:1) | Orchestrator: full purchase lifecycle (validate→price→intent→pay→activate→commission) | ~520 | 
| [`financial_interfaces.py`](dev/service_finder/backend/app/services/financial_interfaces.py:1) | ABCs: `BasePaymentGateway`, `BaseInvoicingService` + exceptions | ~186 | 
| [`financial_orchestrator.py`](dev/service_finder/backend/app/services/financial_orchestrator.py:1) | Unit of Work: payment processing with issuer selection (vetésforgó) | ~449 | 
| [`payment_router.py`](dev/service_finder/backend/app/services/payment_router.py:1) | Router: PaymentIntent creation, Stripe Double Lock, internal gifting | ~495 | 
| [`cost_service.py`](dev/service_finder/backend/app/services/cost_service.py:1) | Fleet operational cost tracking with telemetry | ~140 | 
| [`subscription_activator.py`](dev/service_finder/backend/app/services/subscription_activator.py:1) | Subscription activation (user/org with stacking) | ~unknown | 
| [`commission_service.py`](dev/service_finder/backend/app/services/commission_service.py:1) | MLM commission distribution | ~unknown | 
| [`stripe_adapter.py`](dev/service_finder/backend/app/services/stripe_adapter.py:1) | Stripe API adapter | ~unknown | 
| [`mock_payment_gateway.py`](dev/service_finder/backend/app/services/mock_payment_gateway.py:1) | Test gateway (auto-approve mode) | ~unknown | 

### Architecture Decision: Strategy Pattern
The [`financial_interfaces.py`](dev/service_finder/backend/app/services/financial_interfaces.py:1) defines [`BasePaymentGateway`](dev/service_finder/backend/app/services/financial_interfaces.py:13) and [`BaseInvoicingService`](dev/service_finder/backend/app/services/financial_interfaces.py:91) ABCs. `FinancialManager` accepts any gateway implementation via constructor injection.

### ⚠️ Concern: Overlap Between `financial_orchestrator` and `billing_engine`
- Both create `FinancialLedger` entries
- `financial_orchestrator.process_payment()` writes ledger entries with raw `update()` SQL instead of using `AtomicTransactionManager`
- `financial_orchestrator` accesses `Wallet` fields directly via raw SQL updates
- This is a **code duplication risk** — two different ledger-writing paths exist

### Recommendation
- Either retire `FinancialOrchestrator.process_payment()` in favor of `AtomicTransactionManager` + `PaymentRouter`, or refactor `FinancialOrchestrator` to delegate to `BillingEngine` classes.

---

## 4. WORKERS — Ledger Integration

### ✅ STATUS: FULLY CONNECTED — All workers write to audit ledger

| Worker | Ledger Entry? | Transaction Type | Amount | WalletType |
|--------|--------------|-----------------|--------|------------|
| [`inactivity_monitor_worker.py`](dev/service_finder/backend/app/workers/system/inactivity_monitor_worker.py:1) | ✅ | `ACCOUNT_SUSPENDED_INACTIVITY` | 0.0 | `EARNED` |
| [`subscription_worker.py`](dev/service_finder/backend/app/workers/system/subscription_worker.py:1) | ✅ | `SUBSCRIPTION_EXPIRED` | 0.0 | `SYSTEM` |
| [`subscription_monitor_worker.py`](dev/service_finder/backend/app/workers/system/subscription_monitor_worker.py:1) | ✅ | `SUBSCRIPTION_EXPIRED` | 0.0 | `EARNED` |

### ⚠️ Minor Inconsistency
- `subscription_worker.py` line 75 uses `WalletType.SYSTEM` — this value does NOT exist in the [`WalletType` enum](dev/service_finder/backend/app/models/system/audit.py:63) (which only has `EARNED`, `PURCHASED`, `SERVICE_COINS`, `VOUCHER`). This would raise an `AttributeError` at runtime.
- `subscription_monitor_worker.py` correctly uses `WalletType.EARNED`.

---

## 5. FRONTEND — Wallet & Transaction Views

### ❌ STATUS: COMPLETELY MISSING

A search across the entire `frontend/src/` directory for Vue files containing `wallet`, `transaction`, `balance`, `purchase`, `subscription`, or `billing` returned **zero results**.

The backend already provides:
- `GET /billing/wallet/balance` → Returns quadruple wallet balances
- `GET /billing/wallet/transactions` → Returns paginated transaction history with filtering
- `GET /subscriptions/my` → Returns current subscription details
- `GET /subscriptions/feature-flags` → Returns feature flags

But **no frontend component calls any of these endpoints**.

### What Needs Building

1. **WalletBalanceCard.vue** — Display earned/purchased/service_coins/voucher balances
2. **TransactionHistory.vue** — Paginated transaction list with type/wallet filters
3. **SubscriptionStatusBanner.vue** — Current tier, expiry, upgrade CTA
4. **CheckoutView.vue** — Package selection → PaymentIntent → Stripe/internal redirect
5. **PaymentStatusView.vue** — Success/cancel pages after Stripe redirect
6. **Admin Ledger View** (already spec'd in [`docs/sf/epic_10_admin_frontend_spec.md`](dev/service_finder/docs/sf/epic_10_admin_frontend_spec.md)) — Paginated financial ledger with user join data

---

## 6. GAP ANALYSIS SUMMARY

| Area | Status | Criticality | Action |
|------|--------|-------------|--------|
| **Backend Models** | ✅ Complete | — | No action needed |
| **Backend API — User-facing** | ✅ Complete | — | No action needed |
| **Backend API — Admin** | ✅ Complete | — | No action needed |
| **Backend Services** | ✅ Mostly modular | ⚠️ Medium | Refactor `FinancialOrchestrator` to delegate ledger writes to `AtomicTransactionManager` |
| **Workers → Ledger** | ✅ Connected | 🔴 Bug | Fix `subscription_worker.py:75` — `WalletType.SYSTEM` does not exist |
| **Frontend — Wallet** | ❌ Missing | 🔴 Critical | Build `WalletBalanceCard.vue` + `TransactionHistory.vue` |
| **Frontend — Checkout** | ❌ Missing | 🔴 Critical | Build subscription purchase flow (catalog → intent → payment → confirmation) |
| **Frontend — Admin Ledger** | ❌ Missing | 🟡 Medium | Build admin ledger view (already spec'd) |

---

## 7. RECOMMENDED ACTIONS (Priority Order)

### 🔴 P0 — Critical Bugs
1. **Fix `subscription_worker.py:75`**: Change `WalletType.SYSTEM` to `WalletType.EARNED` (or add `SYSTEM` to the enum)
2. **Fix `FinancialOrchestrator.refund_payment()` line 399/403**: Code references `Wallet.wallet_type` field which doesn't exist on the Wallet model; also references `wallet.balance` which doesn't exist. This code would **crash at runtime**.

### 🔴 P0 — Missing Frontend
3. Build `WalletBalanceCard.vue` — user wallet summary display
4. Build `TransactionHistory.vue` — paginated transaction list
5. Build subscription checkout flow (catalog → Intent → payment → confirmation)

### 🟡 P1 — Code Quality
6. Refactor `FinancialOrchestrator.process_payment()` to delegate to `AtomicTransactionManager` for ledger creation (eliminate dual ledger-writing paths)
7. Audit `FinancialOrchestrator.refund_payment()` — it references non-existent fields (`Wallet.wallet_type`, `Wallet.balance`)

### 🟢 P2 — Documentation
8. Update [`epic_3_financial_motor_architecture.md`](dev/service_finder/docs/sf/epic_3_financial_motor_architecture.md:1) with current service file structure
9. Create `logic_spec_financial_manager.md` documenting the full purchase lifecycle flow with Mermaid sequence diagram

---

*Audit completed by Rendszer-Architect. Ready for Gitea ticket creation.*