cs-transacion-manage

Experience · Repository · Active

cs-transacion-manage

Transaction-first management experience with a dedicated NestJS BFF, React frontend, optional planning board, local shared contracts, platform-auth roles, platform-payments subscription tiers and dedicated PostgreSQL persistence.

• NestJS 11
• Prisma 7
• PostgreSQL
• React 19
• Vite
• Redux Toolkit
• Tailwind 4

Spec sheet

Area

Experience / CS Transaction Manage

Public host

http://transactions.cs.lvh.me:8080

Runtime shape

apps/api + apps/web + packages/shared

Backend port

3005

Frontend port

5179

Data store

Dedicated PostgreSQL

Responsibilities

• Own a transaction-first ledger experience plus secondary planning, relationship, counterparty, series, investment and agenda modules.
• Keep planning setup optional and never use strategic completeness as a workspace access gate.
• Expose a same-origin BFF that delegates login and session resolution to platform-auth-service.
• Calculate subscription-aware product capabilities from platform-auth roles and platform-payments plan status.
• Persist product state in transaction-postgres through Prisma.
• Keep frontend traffic same-origin and route all browser API calls through /api.
• Keep DTO and UI-facing types aligned through the local @casa-srl/shared package.

Interfaces and contract surface

• GET /api/health
• GET /api/auth/me
• POST /api/auth/register
• POST /api/auth/login
• GET /api/planning/setup
• POST /api/planning/setup
• GET /api/transactions
• GET /api/series
• GET /api/investments
• GET /api/agenda

Internal modules

Backend

cs transaction api

NestJS BFF for CS Transaction Manage, delegating auth/session/role flows to platform-auth-service and subscription status to platform-payments-service while owning ledger, planning setup, transaction, series, investment and agenda APIs.

Frontend

cs transaction web

React and Vite frontend for CS Transaction Manage, rendering a transaction-first ledger workspace with optional planning, agenda, series and investments through same-origin APIs.

Package

cs transaction shared

Local shared package for CS Transaction Manage contracts and TypeScript types consumed by the BFF and frontend.

Consumers

• Internal users via transactions host

Dependencies and external touchpoints

• platform-auth-service
• platform-payments-service
• platform-local-stack
• platform-status-service

Notes

• The BFF uses platform-auth-service local credentials and the cs-transacion-manage product code while keeping ledger profiles local.
• The authenticated root redirects to /transactions; /planning owns the strategic board and creates progress cycles only through explicit setup.
• ADMIN bypasses subscription limits; USER capabilities are derived from FREE, PRO or BUSINESS tiers.
• The local stack starts the shared package watcher, then API and web processes.

Source references

• cs-transacion-manage/package.json
• cs-transacion-manage/apps/api/package.json
• cs-transacion-manage/apps/web/package.json
• cs-transacion-manage/packages/shared/package.json

Accesso e subscription

Il BFF calcola l'accesso prodotto in un modulo access dedicato. Il ruolo arriva dalla membership di platform-auth-service; il tier subscription arriva da platform-payments-service tramite consumerTenantId, con fallback iniziale su subjectId quando manca il tenant.

ADMIN ha tutte le capability e bypassa i limiti subscription. Gli utenti USER ricevono capability per tier: FREE abilita workspace base e transazioni manuali, PRO aggiunge serie, investimenti, simulazione, pay-yourself-first e import/export, BUSINESS aggiunge condivisioni avanzate senza concedere privilegi amministrativi.

Le API negate rispondono 403 Forbidden; la UI usa access.capabilities solo per nascondere navigazione e azioni non disponibili.

Classificazione finanziaria

Il modulo classifica ogni entrata o uscita su due assi indipendenti:

• periodicità derivata dal dominio (RECURRING/EXTRAORDINARY);
• natura coerente con la direzione (ACTIVE/PASSIVE per le entrate, MAINTENANCE/INVESTMENT per le uscite).

La classificazione è condivisa tra ledger, Plancia, Simulazione, import CSV e wizard web. Gli investimenti restano asset; i loro interessi sono entrate passive, i rimborsi capitale sono passivi e straordinari. Pay-yourself-first genera uscite di investimento ricorrenti e le spese impreviste della simulazione sono uscite di mantenimento straordinarie.

Il rollout dati è forward-only e richiede backup PostgreSQL con checksum, ripristino in staging, blocco delle scritture durante il cutover e manifest obbligatorio per ogni vecchia uscita. La migrazione traduce automaticamente solo le entrate e rifiuta manifest incompleti o combinazioni incompatibili.

Setup della Plancia

/planning/setup raccoglie soltanto displayName e primaryObjective. La review è read-only e usa il dataset gia calcolato dal workspace per mostrare costi medi, entrate passive medie, copertura, gap e finestra di dodici mesi.

POST /api/planning/setup rilegge movimenti owner, ricorrenze attive e investimenti owner nella stessa transazione del salvataggio. Scrive solo il profilo Planning e il ProgressCycle con origin PLANNING_SETUP: non crea rapporti, controparti o ricorrenze. Il salvataggio è bloccato con PLANNING_DATASET_INSUFFICIENT quando non esiste almeno un costo reale nella finestra di baseline; le entrate passive possono essere zero. Il ledger resta utilizzabile anche senza configurazione della Plancia.

Buone abitudini

La route /habits è una superficie secondaria per una gamification personale, non monetaria e derivata dal ledger. GET /api/gamification/summary espone punti, livello, continuità, badge e le ultime azioni senza importi finanziari; il frontend carica questo riepilogo separatamente dal dataset globale della workspace.

Il MVP assegna punti solo per saldi puntuali di movimenti DEBT proprietari e per mesi completati della routine “Paga prima te stesso”. Movimenti condivisi, controparti utente collegate, voci virtuali, transazioni annullate e azioni non confermate sono esclusi. Gli award sono idempotenti, revocabili e ricostruibili con il backfill dopo la migrazione additiva GamificationAward.

Vista post-setup della Plancia

/planning è una lettura operativa dei dati già calcolati dal workspace. La prima schermata mostra stato, entrate passive medie, costi medi da coprire, gap/margine, periodo analizzato e una sola prossima azione. Il percorso è espresso con tre valori assoluti: Partenza, Oggi e Traguardo.

La UI non espone percentuali o grafici di copertura. Routine finanziaria, dettaglio cashflow e metodo di calcolo restano disponibili in pannelli richiudibili. Le anomalie di impatto vengono mostrate solo quando esistono dati reali da presidiare; i casi senza anomalie non producono sezioni vuote.