00 - Dominio Assicurativo per Developer: Prodotti, Attori e Data Model

Distribution    Underwriting     Policy Admin     Claims         Investment
    |               |                |              |               |
    v               v                v              v               v
+-----------+  +-----------+  +------------+  +-----------+  +-----------+
| Marketing |  | Risk      |  | Issue      |  | FNOL      |  | Asset     |
| Lead Gen  |  | Selection |  | Endorse    |  | Assess    |  | Mgmt      |
| Quoting   |  | Pricing   |  | Renew      |  | Adjust    |  | ALM       |
| Binding   |  | Approval  |  | Cancel     |  | Settle    |  | Reserves  |
+-----------+  +-----------+  +------------+  +-----------+  +-----------+
    |               |                |              |               |
    +-------+-------+--------+-------+------+-------+-------+------+
            |                |              |               |
       +---------+     +---------+    +---------+    +---------+
       |Reinsur. |     | Billing |    | Fraud   |    | Report  |
       |Cessions |     | Collect |    | Detect  |    | Regulat.|
       +---------+     +---------+    +---------+    +---------+

// ============================================
// Core Insurance Domain Model (TypeScript)
// ============================================

/** Tipologia di prodotto assicurativo */
type LineOfBusiness = 'LIFE' | 'PROPERTY' | 'CASUALTY' | 'HEALTH' | 'MARINE' | 'CYBER';

/** Stato della polizza nel suo ciclo di vita */
type PolicyStatus =
  | 'QUOTE'          // Preventivo
  | 'APPLICATION'    // Proposta
  | 'BOUND'          // Vincolata (impegno assunto)
  | 'ISSUED'         // Emessa
  | 'IN_FORCE'       // In vigore
  | 'SUSPENDED'      // Sospesa
  | 'LAPSED'         // Decaduta (mancato pagamento)
  | 'CANCELLED'      // Cancellata
  | 'EXPIRED'        // Scaduta
  | 'NON_RENEWED';   // Non rinnovata

/** Aggregato principale: la Polizza */
interface Policy {
  readonly id: string;
  readonly policyNumber: string;
  readonly version: number;             // Versioning per endorsement
  readonly lineOfBusiness: LineOfBusiness;
  readonly status: PolicyStatus;
  readonly effectiveDate: Date;
  readonly expirationDate: Date;
  readonly inceptionDate: Date;         // Data prima emissione
  readonly policyholder: Party;         // Contraente
  readonly insuredParties: readonly InsuredParty[];
  readonly coverages: readonly Coverage[];
  readonly premium: PremiumBreakdown;
  readonly endorsements: readonly Endorsement[];
  readonly documents: readonly Document[];
  readonly underwritingInfo: UnderwritingInfo;
  readonly createdAt: Date;
  readonly updatedAt: Date;
}

/** Parte coinvolta (persona fisica o giuridica) */
interface Party {
  readonly id: string;
  readonly type: 'INDIVIDUAL' | 'ORGANIZATION';
  readonly firstName?: string;
  readonly lastName?: string;
  readonly companyName?: string;
  readonly taxId: string;               // Codice fiscale / P.IVA
  readonly dateOfBirth?: Date;
  readonly addresses: readonly Address[];
  readonly contacts: readonly ContactInfo[];
  readonly riskProfile?: RiskProfile;
}

/** Soggetto assicurato con specifico ruolo */
interface InsuredParty {
  readonly party: Party;
  readonly role: 'PRIMARY' | 'ADDITIONAL' | 'NAMED_INSURED';
  readonly relationship: string;         // Relazione col contraente
}

/** Copertura: cosa e protetto e fino a quanto */
interface Coverage {
  readonly id: string;
  readonly code: string;                 // Es: "TPL", "CASCO", "FIRE"
  readonly name: string;
  readonly description: string;
  readonly type: 'BASE' | 'OPTIONAL' | 'MANDATORY';
  readonly limit: Money;                 // Massimale
  readonly deductible: Deductible;       // Franchigia
  readonly premium: Money;               // Premio per questa copertura
  readonly effectiveDate: Date;
  readonly expirationDate: Date;
  readonly exclusions: readonly string[];
  readonly conditions: readonly string[];
}

/** Franchigia con diverse modalità di applicazione */
interface Deductible {
  readonly type: 'FIXED' | 'PERCENTAGE' | 'WAITING_PERIOD' | 'AGGREGATE';
  readonly amount?: Money;               // Per FIXED
  readonly percentage?: number;          // Per PERCENTAGE
  readonly waitingDays?: number;         // Per WAITING_PERIOD
  readonly aggregateLimit?: Money;       // Per AGGREGATE
  readonly appliesToEach: 'CLAIM' | 'OCCURRENCE' | 'POLICY_PERIOD';
}

/** Scomposizione del premio */
interface PremiumBreakdown {
  readonly grossPremium: Money;          // Premio lordo
  readonly netPremium: Money;            // Premio netto (per l'assicuratore)
  readonly taxes: Money;                 // Imposte
  readonly fees: Money;                  // Diritti e commissioni
  readonly commission: Money;            // Provvigione intermediario
  readonly components: readonly PremiumComponent[];
  readonly paymentPlan: PaymentPlan;
}

/** Variazione contrattuale in corso di polizza */
interface Endorsement {
  readonly id: string;
  readonly endorsementNumber: number;
  readonly type: 'COVERAGE_CHANGE' | 'LIMIT_CHANGE' | 'ADD_INSURED'
              | 'REMOVE_INSURED' | 'ADDRESS_CHANGE' | 'VEHICLE_CHANGE'
              | 'GENERAL_CHANGE';
  readonly effectiveDate: Date;
  readonly description: string;
  readonly premiumAdjustment: Money;     // Differenza premio (+/-)
  readonly previousVersion: number;
  readonly newVersion: number;
  readonly changes: readonly FieldChange[];
  readonly approvedBy?: string;
  readonly approvedAt?: Date;
}

/** Valore monetario con valuta */
interface Money {
  readonly amount: number;
  readonly currency: string;             // ISO 4217: "EUR", "USD", "GBP"
}

/** Singola modifica tracciata nell'endorsement */
interface FieldChange {
  readonly field: string;
  readonly oldValue: string;
  readonly newValue: string;
}

// ============================================
// Policy Lifecycle State Machine
// ============================================

/** Transizioni valide nel ciclo di vita della polizza */
type PolicyTransition =
  | { from: 'QUOTE';       to: 'APPLICATION';  action: 'SUBMIT_APPLICATION' }
  | { from: 'QUOTE';       to: 'CANCELLED';    action: 'DECLINE_QUOTE' }
  | { from: 'APPLICATION'; to: 'BOUND';        action: 'BIND_COVERAGE' }
  | { from: 'APPLICATION'; to: 'CANCELLED';    action: 'DECLINE_APPLICATION' }
  | { from: 'BOUND';       to: 'ISSUED';       action: 'ISSUE_POLICY' }
  | { from: 'ISSUED';      to: 'IN_FORCE';     action: 'ACTIVATE' }
  | { from: 'IN_FORCE';    to: 'IN_FORCE';     action: 'ENDORSE' }
  | { from: 'IN_FORCE';    to: 'SUSPENDED';    action: 'SUSPEND' }
  | { from: 'IN_FORCE';    to: 'CANCELLED';    action: 'CANCEL' }
  | { from: 'IN_FORCE';    to: 'EXPIRED';      action: 'EXPIRE' }
  | { from: 'IN_FORCE';    to: 'IN_FORCE';     action: 'RENEW' }
  | { from: 'IN_FORCE';    to: 'NON_RENEWED';  action: 'NON_RENEW' }
  | { from: 'SUSPENDED';   to: 'IN_FORCE';     action: 'REINSTATE' }
  | { from: 'SUSPENDED';   to: 'LAPSED';       action: 'LAPSE' }
  | { from: 'LAPSED';      to: 'IN_FORCE';     action: 'REINSTATE' }
  | { from: 'LAPSED';      to: 'CANCELLED';    action: 'CANCEL' };

/** Mappa delle transizioni valide per validazione runtime */
const VALID_TRANSITIONS: ReadonlyMap<PolicyStatus, readonly PolicyTransition[]> = new Map([
  ['QUOTE', [
    { from: 'QUOTE', to: 'APPLICATION', action: 'SUBMIT_APPLICATION' },
    { from: 'QUOTE', to: 'CANCELLED', action: 'DECLINE_QUOTE' },
  ]],
  ['APPLICATION', [
    { from: 'APPLICATION', to: 'BOUND', action: 'BIND_COVERAGE' },
    { from: 'APPLICATION', to: 'CANCELLED', action: 'DECLINE_APPLICATION' },
  ]],
  ['IN_FORCE', [
    { from: 'IN_FORCE', to: 'IN_FORCE', action: 'ENDORSE' },
    { from: 'IN_FORCE', to: 'SUSPENDED', action: 'SUSPEND' },
    { from: 'IN_FORCE', to: 'CANCELLED', action: 'CANCEL' },
    { from: 'IN_FORCE', to: 'EXPIRED', action: 'EXPIRE' },
    { from: 'IN_FORCE', to: 'IN_FORCE', action: 'RENEW' },
    { from: 'IN_FORCE', to: 'NON_RENEWED', action: 'NON_RENEW' },
  ]],
]);

/** Funzione pura per la transizione di stato */
function transitionPolicy(
  policy: Policy,
  action: PolicyTransition['action'],
  context: TransitionContext
): Policy {
  const validTransitions = VALID_TRANSITIONS.get(policy.status);
  const transition = validTransitions?.find(t => t.action === action);

  if (!transition) {
    throw new InvalidTransitionError(
      `Cannot perform ${action} on policy in status ${policy.status}`
    );
  }

  // Crea nuova versione immutabile della polizza
  return {
    ...policy,
    status: transition.to,
    version: policy.version + 1,
    updatedAt: new Date(),
    endorsements: action === 'ENDORSE'
      ? [...policy.endorsements, context.endorsement!]
      : policy.endorsements,
  };
}

// ============================================
// Claims Domain Model
// ============================================

type ClaimStatus =
  | 'FNOL'              // First Notice of Loss - notifica iniziale
  | 'REGISTERED'        // Registrato nel sistema
  | 'UNDER_INVESTIGATION' // In fase di indagine/perizia
  | 'ASSESSED'          // Valutato dal perito
  | 'APPROVED'          // Approvato per liquidazione
  | 'PARTIALLY_APPROVED'// Parzialmente approvato
  | 'DENIED'            // Rifiutato
  | 'SETTLED'           // Liquidato
  | 'REOPENED'          // Riaperto
  | 'CLOSED'            // Chiuso definitivamente
  | 'SUBROGATION';      // In fase di recupero

interface Claim {
  readonly id: string;
  readonly claimNumber: string;
  readonly policyId: string;
  readonly policyNumber: string;
  readonly status: ClaimStatus;
  readonly lossDate: Date;              // Data del sinistro
  readonly reportDate: Date;            // Data della denuncia
  readonly lossType: string;            // Tipo di danno
  readonly lossDescription: string;
  readonly lossLocation: Address;
  readonly claimant: Party;             // Chi richiede l'indennizzo
  readonly reserves: readonly Reserve[];
  readonly payments: readonly ClaimPayment[];
  readonly assessments: readonly Assessment[];
  readonly documents: readonly Document[];
  readonly fraudIndicators: readonly FraudIndicator[];
  readonly totalIncurred: Money;        // Riserva + Pagato
  readonly totalPaid: Money;
  readonly totalReserve: Money;
}

/** Riserva: stima del costo futuro del sinistro */
interface Reserve {
  readonly id: string;
  readonly type: 'INDEMNITY' | 'EXPENSE' | 'LEGAL';
  readonly amount: Money;
  readonly setDate: Date;
  readonly setBy: string;
  readonly reason: string;
  readonly history: readonly ReserveChange[];
}

/** Pagamento effettuato sul sinistro */
interface ClaimPayment {
  readonly id: string;
  readonly type: 'INDEMNITY' | 'EXPENSE' | 'LEGAL' | 'SALVAGE' | 'SUBROGATION';
  readonly amount: Money;
  readonly payee: Party;
  readonly paymentDate: Date;
  readonly paymentMethod: string;
  readonly invoiceReference?: string;
  readonly approvedBy: string;
}

/** Valutazione peritale */
interface Assessment {
  readonly id: string;
  readonly assessor: Party;             // Perito
  readonly assessmentDate: Date;
  readonly damageEstimate: Money;
  readonly findings: string;
  readonly recommendation: 'APPROVE' | 'DENY' | 'FURTHER_INVESTIGATION';
  readonly photos: readonly string[];   // URL delle foto
  readonly report: Document;
}

/** Indicatore di potenziale frode */
interface FraudIndicator {
  readonly rule: string;
  readonly score: number;               // 0-100
  readonly description: string;
  readonly triggeredAt: Date;
}

// ============================================
// Rating Engine - Esempio RC Auto
// ============================================

/** Fattori di rischio per la tariffazione auto */
interface AutoRatingFactors {
  readonly driverAge: number;
  readonly driverExperience: number;      // Anni di patente
  readonly vehicleGroup: number;          // Gruppo tariffario 1-20
  readonly vehicleAge: number;
  readonly postalCode: string;
  readonly claimsHistory: number;         // Sinistri ultimi 5 anni
  readonly bonusMalusClass: number;       // Classe CU (1-18 in Italia)
  readonly annualMileage: number;
  readonly garaging: 'GARAGE' | 'STREET' | 'PARKING';
  readonly usage: 'PERSONAL' | 'COMMUTE' | 'BUSINESS';
}

/** Risultato del calcolo tariffario */
interface RatingResult {
  readonly baseRate: Money;
  readonly factors: readonly AppliedFactor[];
  readonly technicalPremium: Money;       // Premio tecnico (puro rischio)
  readonly loadings: readonly Loading[];
  readonly grossPremium: Money;           // Premio lordo finale
  readonly taxes: Money;
  readonly totalPremium: Money;           // Totale da pagare
  readonly ratingDate: Date;
  readonly rateTableVersion: string;
  readonly auditTrail: readonly string[];
}

interface AppliedFactor {
  readonly name: string;
  readonly inputValue: string | number;
  readonly factor: number;                // Moltiplicatore (es: 1.25 = +25%)
  readonly source: string;                // Tabella di riferimento
}

interface Loading {
  readonly type: 'EXPENSE' | 'COMMISSION' | 'PROFIT' | 'CATASTROPHE' | 'REINSURANCE';
  readonly percentage: number;
  readonly amount: Money;
}

/** Rating Engine: funzione pura che calcola il premio */
function calculateAutoRate(
  factors: AutoRatingFactors,
  rateTables: RateTableSet
): RatingResult {
  const auditTrail: string[] = [];

  // 1. Base Rate dalla tabella territoriale
  const baseRate = rateTables.territorial.lookup(factors.postalCode);
  auditTrail.push(`Base rate for ${factors.postalCode}: ${baseRate}`);

  // 2. Applicazione fattori moltiplicativi
  const ageMultiplier = rateTables.ageFactors.lookup(factors.driverAge);
  const vehicleMultiplier = rateTables.vehicleGroups.lookup(factors.vehicleGroup);
  const bonusMalusMultiplier = rateTables.bonusMalus.lookup(factors.bonusMalusClass);
  const experienceMultiplier = rateTables.experience.lookup(factors.driverExperience);
  const mileageMultiplier = rateTables.mileage.lookup(factors.annualMileage);

  const appliedFactors: AppliedFactor[] = [
    { name: 'Age', inputValue: factors.driverAge, factor: ageMultiplier, source: 'AGE_TABLE_v3' },
    { name: 'Vehicle Group', inputValue: factors.vehicleGroup, factor: vehicleMultiplier, source: 'VEH_TABLE_v2' },
    { name: 'Bonus/Malus', inputValue: factors.bonusMalusClass, factor: bonusMalusMultiplier, source: 'BM_TABLE_v1' },
    { name: 'Experience', inputValue: factors.driverExperience, factor: experienceMultiplier, source: 'EXP_TABLE_v1' },
    { name: 'Mileage', inputValue: factors.annualMileage, factor: mileageMultiplier, source: 'KM_TABLE_v2' },
  ];

  // 3. Premio tecnico = base * prodotto dei fattori
  const combinedFactor = appliedFactors.reduce((acc, f) => acc * f.factor, 1);
  const technicalPremium = baseRate * combinedFactor;
  auditTrail.push(`Technical premium: ${baseRate} * ${combinedFactor.toFixed(4)} = ${technicalPremium.toFixed(2)}`);

  // 4. Caricamenti (expense loading, commissioni, profitto)
  const loadings: Loading[] = [
    { type: 'EXPENSE', percentage: 0.15, amount: { amount: technicalPremium * 0.15, currency: 'EUR' } },
    { type: 'COMMISSION', percentage: 0.12, amount: { amount: technicalPremium * 0.12, currency: 'EUR' } },
    { type: 'PROFIT', percentage: 0.05, amount: { amount: technicalPremium * 0.05, currency: 'EUR' } },
    { type: 'CATASTROPHE', percentage: 0.02, amount: { amount: technicalPremium * 0.02, currency: 'EUR' } },
  ];

  const totalLoadingPct = loadings.reduce((acc, l) => acc + l.percentage, 0);
  const grossPremium = technicalPremium * (1 + totalLoadingPct);

  // 5. Imposte (22.25% per RC Auto in Italia)
  const taxRate = 0.2225;
  const taxes = grossPremium * taxRate;
  const totalPremium = grossPremium + taxes;

  return {
    baseRate: { amount: baseRate, currency: 'EUR' },
    factors: appliedFactors,
    technicalPremium: { amount: technicalPremium, currency: 'EUR' },
    loadings,
    grossPremium: { amount: grossPremium, currency: 'EUR' },
    taxes: { amount: taxes, currency: 'EUR' },
    totalPremium: { amount: totalPremium, currency: 'EUR' },
    ratingDate: new Date(),
    rateTableVersion: 'RC_AUTO_2026_Q1',
    auditTrail,
  };
}

// ============================================
// Bounded Context Map
// ============================================
//
// +------------------+     +------------------+     +------------------+
// |   Distribution   |     |   Underwriting   |     |  Policy Admin    |
// |                  |     |                  |     |                  |
// |  - Lead          |     |  - Submission    |     |  - Policy        |
// |  - Opportunity   |---->|  - Risk          |---->|  - Coverage      |
// |  - Quote Request |     |  - Rating        |     |  - Endorsement   |
// |  - Channel       |     |  - Decision      |     |  - Renewal       |
// +------------------+     +------------------+     +------------------+
//         |                        |                        |
//         |                        |                        |
//         v                        v                        v
// +------------------+     +------------------+     +------------------+
// |   CRM / Party    |     |    Reinsurance   |     |     Claims       |
// |                  |     |                  |     |                  |
// |  - Customer      |     |  - Treaty        |     |  - Claim         |
// |  - Agent         |     |  - Cession       |     |  - Reserve       |
// |  - Broker        |     |  - Recovery      |     |  - Payment       |
// |  - Address       |     |  - Bordereaux    |     |  - Assessment    |
// +------------------+     +------------------+     +------------------+
//         |                        |                        |
//         v                        v                        v
// +------------------+     +------------------+     +------------------+
// |     Billing      |     |   Compliance     |     |  Fraud Detection |
// |                  |     |                  |     |                  |
// |  - Invoice       |     |  - Filing        |     |  - Alert         |
// |  - Payment       |     |  - Report        |     |  - Investigation |
// |  - Collection    |     |  - Audit         |     |  - Score         |
// |  - Installment   |     |  - Solvency      |     |  - Rule          |
// +------------------+     +------------------+     +------------------+

// Context Mapping Relationships:
// Distribution --[Conformist]--> Underwriting
// Underwriting --[Published Language]--> Policy Admin
// Policy Admin --[Shared Kernel]--> Billing
// Policy Admin --[Customer/Supplier]--> Claims
// Claims --[Anti-Corruption Layer]--> Fraud Detection
// Underwriting --[Partnership]--> Reinsurance
// All Contexts --[Conformist]--> Compliance

// ============================================
// Insurance Domain Events
// ============================================

interface DomainEvent {
  readonly eventId: string;
  readonly eventType: string;
  readonly occurredAt: Date;
  readonly aggregateId: string;
  readonly aggregateType: string;
  readonly version: number;
  readonly correlationId: string;
  readonly causationId?: string;
}

// --- Policy Events ---

interface PolicyQuoted extends DomainEvent {
  readonly eventType: 'POLICY_QUOTED';
  readonly aggregateType: 'Policy';
  readonly quoteNumber: string;
  readonly premium: Money;
  readonly validUntil: Date;
}

interface PolicyIssued extends DomainEvent {
  readonly eventType: 'POLICY_ISSUED';
  readonly aggregateType: 'Policy';
  readonly policyNumber: string;
  readonly effectiveDate: Date;
  readonly premium: Money;
  readonly coverages: readonly string[];
}

interface PolicyEndorsed extends DomainEvent {
  readonly eventType: 'POLICY_ENDORSED';
  readonly aggregateType: 'Policy';
  readonly endorsementNumber: number;
  readonly changes: readonly FieldChange[];
  readonly premiumAdjustment: Money;
}

// --- Claim Events ---

interface ClaimFiled extends DomainEvent {
  readonly eventType: 'CLAIM_FILED';
  readonly aggregateType: 'Claim';
  readonly policyNumber: string;
  readonly lossDate: Date;
  readonly lossType: string;
  readonly initialReserve: Money;
}

interface ClaimSettled extends DomainEvent {
  readonly eventType: 'CLAIM_SETTLED';
  readonly aggregateType: 'Claim';
  readonly settlementAmount: Money;
  readonly payee: string;
}

// --- Cross-Context Reactions ---
// PolicyIssued  -> Billing: createInvoice()
// PolicyIssued  -> Reinsurance: calculateCession()
// ClaimFiled    -> FraudDetection: screenClaim()
// ClaimFiled    -> Reinsurance: notifyCession()
// ClaimSettled  -> Billing: adjustReserve()
// ClaimSettled  -> Reinsurance: calculateRecovery()