Capitol activStudiu de caz
Studiu de caz / 02
Un microserviciu REST autonom pentru calculul taxelor multi-jurisdicționale și al comisioanelor. Gestionează suprapunerea taxelor de vânzare din SUA, TVA din UE, sistemul britanic pe trei niveluri și GST/HST din Canada - totul susținut de decimal.js pentru zero erori de rotunjire în virgulă mobilă.
01 / Comportamentul sistemului
Un mecanism tehnic specific proiectului, bazat pe arhitectura și contextul de implementare înregistrate.
JurisLogic este un microserviciu headless de tip plug-and-play, conceput pentru a fi consumat de orice frontend, aplicație mobilă sau serviciu backend, fără dependențe sau blocare pe un furnizor. Fiecare operație monetară trece prin value objects imutabile de tip Money, susținute de decimal.js cu rotunjire bancară (ROUND_HALF_UP), garantând precizie la nivel de bănuț în toate jurisdicțiile.
Serviciul acoperă patru familii de jurisdicții: SUA (suprapunere stat + comitat + oraș), UE (rate standard și reduse per țară), Marea Britanie (standard 20%, redusă 5%, cotă zero) și Canada (provincii cu HST vs. GST+PST). Fiecare jurisdicție este implementată ca o Strategie concretă, rezolvată de un TaxStrategyFactory - adăugarea unei jurisdicții noi înseamnă scrierea unei singure clase și înregistrarea ei, fără nicio modificare la codul existent.
03 / Înregistrarea arhitecturii
O interpretare structurată a arhitecturii înregistrate pentru acest proiect.
Codebase-ul urmează o Arhitectură Hexagonală (Porturi și Adaptoare) strictă, cu trei straturi:
• Stratul de Domeniu (src/domain/) - Clase TypeScript pure, fără niciun import de framework. Conține Value Objects (Money, TaxRate, JurisdictionCode), Entități (agregatul Transaction, TaxRule, Commission) și Strategii (interfața ITaxStrategy cu implementări pentru SUA, UE, UK, CA, plus lanțul TaxRulePipeline).
• Stratul de Aplicație (src/application/) - Orchestratori de use case (CalculateTax, CalculateCommission, ProcessBatchTransaction) care construiesc obiecte de domeniu din DTO-uri, verifică cache-ul, rezolvă strategii, rulează pipeline-uri și scriu în logul de audit. Depinde exclusiv de interfețe abstracte de tip port - ICachePort, IQueuePort, IAuditLogPort, ITaxRuleRepository.
• Stratul de Infrastructură (src/infrastructure/) - Adaptoare concrete: PrismaService pentru PostgreSQL, RedisCacheAdapter, adaptor BullMQ pentru cozi și adaptor Prisma pentru logare de audit. Modulul NestJS InfrastructureModule este singura rădăcină de compoziție care conectează adaptoarele la porturi.
• Stratul de Interfață (src/interfaces/rest/) - Controlere NestJS cu decoratori Swagger și DTO-uri. Strat subțire care deleagă către use case-uri.
Design Patterns: Strategy, Factory, Chain of Responsibility, Decorator, Builder, Value Object, Repository, Ports & Adapters.
Preocupările transversale - scutiri, suprataxe, praguri minime de taxare - sunt gestionate de un pipeline Chain of Responsibility cu un builder API fluent. Stratul de aplicație orchestrează use case-urile (taxă individuală, comision, batch) prin interfețe abstracte de tip port, menținând logica de business complet independentă de framework. Adaptoarele de infrastructură conectează caching-ul Redis, procesarea asincronă batch prin BullMQ și logarea de audit în PostgreSQL.
Sistemul de comisioane suportă trei modele: sumă fixă, procentual și pe niveluri (bracket-uri progresive, similar impozitului pe venit), toate calculate cu aceleași garanții de precizie zecimală.
05 / Aspecte selectate
Deciziile și fluxurile cu cea mai mare valoare explicativă.
06 / Metrici susținute
TypeScript, NestJS, Prisma, PostgreSQL, Redis, BullMQ, decimal.js, Docker, Swagger/OpenAPI, Jest
Vezi repository-ul sursă