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
identity	active_vouchers	FIFO voucher tracking with expiration	models/identity/identity.py:316
audit	financial_ledger	Immutable double-entry ledger (DEBIT/CREDIT)	models/system/audit.py:78
fleet_finance	cost_categories	Hierarchical cost category tree	models/fleet_finance/models.py:37
fleet_finance	asset_costs	Operational expense log (TCO)	models/fleet_finance/models.py:109
fleet_finance	asset_financials	Acquisition & depreciation	models/fleet_finance/models.py:180
fleet_finance	insurance_providers	Insurance company catalog	models/fleet_finance/models.py:219
fleet_finance	vehicle_insurance_policies	Vehicle insurance policies	models/fleet_finance/models.py:248
fleet_finance	vehicle_tax_obligations	Tax obligations per vehicle	models/fleet_finance/models.py:298
finance	issuers	Billing entities (KFT/EV/BT/ZRT)	models/marketplace/finance.py:27
marketplace	payment_intents	Payment intent lifecycle (Double Lock)	models/marketplace/payment.py
core_logic	subscription_tiers	Subscription tier definitions	models/core_logic.py
core_logic	user_subscriptions / org_subscriptions	Subscription state tracking	models/core_logic.py

Key Enums (Defined in 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)

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

Architecture Decision: Strategy Pattern

The financial_interfaces.py defines BasePaymentGateway and BaseInvoicingService 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	✅	ACCOUNT_SUSPENDED_INACTIVITY	0.0	EARNED
subscription_worker.py	✅	SUBSCRIPTION_EXPIRED	0.0	SYSTEM
subscription_monitor_worker.py	✅	SUBSCRIPTION_EXPIRED	0.0	EARNED

⚠️ Minor Inconsistency

• subscription_worker.py line 75 uses WalletType.SYSTEM — this value does NOT exist in the WalletType enum (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) — 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 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.