Regole di Business - Microservices

Questo documento elenca le regole di business fondamentali del dominio Microservices, identificate con codice univoco BR-NNN. Ogni regola è technology-independent e descrive un vincolo invariante sull'architettura a servizi distribuiti.

---

BR-001 - Un servizio possiede i propri dati

Codice: BR-001 Nome: Ogni Servizio è l'unico proprietario del proprio datastore Descrizione: Nessun servizio accede direttamente al database di un altro servizio. La condivisione dei dati avviene solo tramite l'API pubblica o eventi del servizio proprietario. Questo garantisce loose coupling e autonomia di deploy. Motivazione: Prevenire accoppiamento nascosto a livello di schema; consentire evoluzione indipendente. Priorità: CRITICA Attori: Service Owner Violazione: accesso cross-database rilevato in code review → rifiuto del merge. Tracciabilità: glossary "Loose Coupling", "Polyglot Persistence", "Bounded Context"; BC-01.

---

BR-002 - Idempotenza dei consumatori di messaggi

Codice: BR-002 Nome: Ogni handler di un MessaggioBroker deve essere idempotente Descrizione: Poiché i broker garantiscono tipicamente consegna at-least-once, lo stesso messaggio può arrivare più volte. Il consumatore deve produrre lo stesso effetto a fronte di consegne duplicate, deduplicando per chiave di messaggio. Motivazione: Evitare effetti duplicati (doppio addebito, doppia creazione) in presenza di ritrasmissioni. Priorità: ALTA Attori: Service Owner, Service Mesh Tracciabilità: glossary "Idempotency", "Dead Letter Queue (DLQ)", "Outbox Pattern".

---

BR-003 - Comunicazione sincrona protetta da Circuit Breaker

Codice: BR-003 Nome: Ogni chiamata sincrona cross-servizio è protetta da un CircuitBreaker Descrizione: Le chiamate sincrone tra servizi devono passare per un circuit breaker con timeout esplicito. Quando il tasso di errori supera la soglia, il circuito si apre e le chiamate falliscono velocemente (fail-fast) con eventuale fallback, prevenendo l'esaurimento delle risorse. Motivazione: Evitare il cascading failure in cui un servizio lento fa cadere l'intero sistema. Priorità: CRITICA Attori: Service Owner, Service Mesh Violazione: una chiamata sincrona senza protezione viene segnalata come anti-pattern di resilienza. Tracciabilità: glossary "Circuit Breaker", "Fault Tolerance", "Resilience", "Bulkhead"; state-machines/circuit-breaker-lifecycle.md.

---

BR-004 - Transazioni distribuite gestite via Saga

Codice: BR-004 Nome: Una transazione che attraversa più servizi è realizzata come SagaTransaction Descrizione: Non esistono transazioni ACID distribuite. Un'operazione che coinvolge più servizi è una sequenza di transazioni locali con azioni compensative per ogni step, coordinate via orchestration o choreography. In caso di fallimento, si esegue il rollback compensativo. Motivazione: Garantire consistenza eventuale senza lock distribuiti. Priorità: ALTA Attori: Orchestratore Saga, Service Owner Tracciabilità: glossary "Saga", "Eventual Consistency", "Orchestration", "Choreography"; workflows/saga-transaction.md.

---

BR-005 - Registrazione e health check obbligatori

Codice: BR-005 Nome: Ogni Servizio si registra nel Service Registry ed espone un health check Descrizione: Un'istanza di servizio si registra all'avvio ed espone un endpoint di health/readiness. Le istanze non sane sono rimosse dal routing. La service discovery si basa sul registro per instradare il traffico solo verso istanze sane. Motivazione: Consentire scaling dinamico e routing affidabile senza configurazione statica. Priorità: ALTA Attori: Service Mesh, Service Owner Tracciabilità: glossary "Service Discovery", "Service Registry", "Service-Level Objective (SLO)"; events/domain-events.md evento HealthCheckFallito.

---

BR-006 - Versionamento dei contratti senza rotture

Codice: BR-006 Nome: Un ContrattoServizio evolve in modo backward-compatible o introduce una nuova versione Descrizione: Modifiche a un'API o a uno schema di evento non devono rompere i consumatori esistenti. I cambiamenti additivi sono ammessi; i cambiamenti breaking richiedono una nuova versione del contratto e un periodo di coesistenza. I consumer-driven contract test verificano la compatibilità. Motivazione: Permettere deploy indipendenti senza coordinare il rilascio di tutti i consumatori. Priorità: ALTA Attori: Service Owner, API Consumer Tracciabilità: glossary "Consumer-Driven Contract", "Ubiquitous Language"; BC-02.

---

BR-007 - Tracciabilità distribuita su ogni richiesta

Codice: BR-007 Nome: Ogni richiesta cross-servizio propaga un trace context Descrizione: Ogni richiesta o messaggio propaga un identificatore di traccia (trace-id, span-id) attraverso i confini di servizio, così che un'operazione end-to-end possa essere ricostruita per debugging e osservabilità. Motivazione: Rendere debuggabile un flusso che attraversa molti servizi. Priorità: MEDIA Attori: Service Mesh, Service Owner Tracciabilità: glossary "Distributed Tracing", "Observability".

---

BR-008 - Confini di servizio allineati ai Bounded Context

Codice: BR-008 Nome: I confini di un Servizio derivano da un Bounded Context del dominio Descrizione: La scomposizione in servizi segue i confini del dominio (DDD), non i livelli tecnici. Ogni servizio incapsula un bounded context con il proprio linguaggio ubiquo, evitando servizi anemici o eccessivamente fini (nano-servizi). Motivazione: Massimizzare la coesione e minimizzare la chattiness inter-servizio. Priorità: ALTA Attori: Service Owner Tracciabilità: glossary "Domain-Driven Design (DDD)", "Bounded Context", "Modular Monolith", "Strangler Fig Pattern"; BC-01.