01 - Cloud-Native Policy Management: API-First Architecture

from dataclasses import dataclass, field
from datetime import date, datetime
from decimal import Decimal
from enum import Enum
from typing import Optional
from uuid import UUID


class PolicyStatus(str, Enum):
    QUOTED = "QUOTED"
    APPLICATION = "APPLICATION"
    BOUND = "BOUND"
    IN_FORCE = "IN_FORCE"
    SUSPENDED = "SUSPENDED"
    RENEWED = "RENEWED"
    CANCELLED = "CANCELLED"
    EXPIRED = "EXPIRED"


@dataclass(frozen=True)
class Money:
    """Immutable value object for monetary amounts."""
    amount: Decimal
    currency: str = "EUR"

    def __add__(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError(f"Cannot add {self.currency} and {other.currency}")
        return Money(self.amount + other.amount, self.currency)


@dataclass(frozen=True)
class Coverage:
    """A single insurance coverage within a policy."""
    coverage_id: UUID
    coverage_type: str
    limit: Money
    deductible: Money
    premium: Money
    effective_date: date
    expiry_date: date
    is_active: bool = True


@dataclass
class Endorsement:
    """A mid-term modification to the original policy."""
    endorsement_id: UUID
    policy_id: UUID
    endorsement_type: str  # ADD_COVERAGE, REMOVE_COVERAGE, CHANGE_LIMIT, etc.
    effective_date: date
    description: str
    premium_adjustment: Money
    previous_state: dict
    new_state: dict
    created_at: datetime = field(default_factory=datetime.utcnow)


@dataclass
class Policy:
    """Root entity of the policy aggregate."""
    policy_id: UUID
    policy_number: str
    product_code: str
    status: PolicyStatus
    coverages: list[Coverage]
    endorsements: list[Endorsement]
    effective_date: date
    expiry_date: date
    annual_premium: Money
    created_at: datetime

    def is_active(self) -> bool:
        return self.status == PolicyStatus.IN_FORCE

    def can_file_claim(self) -> bool:
        today = date.today()
        return (
            self.is_active()
            and self.effective_date <= today <= self.expiry_date
        )

from fastapi import FastAPI, HTTPException, Depends, BackgroundTasks
from pydantic import BaseModel, Field, validator
from decimal import Decimal
from datetime import date
from uuid import UUID

app = FastAPI(title="Policy Management API", version="1.0.0")


class QuoteRequest(BaseModel):
    product_code: str = Field(..., pattern="^[A-Z_]+$")
    holder_fiscal_code: str
    effective_date: date
    desired_coverages: list[str]
    channel: str = "DIRECT"

    @validator("effective_date")
    def effective_date_not_past(cls, v: date) -> date:
        if v < date.today():
            raise ValueError("Effective date cannot be in the past")
        return v


class QuoteResponse(BaseModel):
    quote_id: UUID
    product_code: str
    total_annual_premium: Decimal
    currency: str = "EUR"
    valid_until: date
    terms_version: str


class PolicyResponse(BaseModel):
    policy_id: UUID
    policy_number: str
    status: str
    effective_date: date
    expiry_date: date
    annual_premium: Decimal
    currency: str = "EUR"


@app.post("/v1/quotes", response_model=QuoteResponse, status_code=201)
async def create_quote(
    request: QuoteRequest,
    service: PolicyService = Depends(get_policy_service)
):
    try:
        return await service.create_quote(request)
    except ValueError as e:
        raise HTTPException(status_code=422, detail=str(e))


@app.post("/v1/quotes/{quote_id}/bind", response_model=PolicyResponse, status_code=201)
async def bind_policy(
    quote_id: UUID,
    request: BindRequest,
    background_tasks: BackgroundTasks,
    service: PolicyService = Depends(get_policy_service)
):
    try:
        return await service.bind_policy(quote_id, request, background_tasks)
    except ValueError as e:
        raise HTTPException(status_code=422, detail=str(e))

from dataclasses import dataclass
from datetime import datetime
from uuid import UUID


@dataclass(frozen=True)
class PolicyBound:
    event_type: str = "PolicyBound"
    policy_id: UUID = None
    policy_number: str = None
    effective_date: str = None
    expiry_date: str = None
    occurred_at: datetime = None


@dataclass(frozen=True)
class PolicyCancelled:
    event_type: str = "PolicyCancelled"
    policy_id: UUID = None
    cancellation_reason: str = None
    refund_amount: dict = None
    requested_by: str = None  # "HOLDER", "INSURER", "REGULATOR"
    occurred_at: datetime = None


class PolicyEventStore:
    """Append-only store for policy events."""

    def __init__(self, db_pool):
        self.db = db_pool

    async def append(self, policy_id: UUID, event) -> int:
        async with self.db.acquire() as conn:
            row = await conn.fetchrow(
                """
                INSERT INTO policy_events
                    (policy_id, event_type, event_data, occurred_at)
                VALUES ($1, $2, $3, $4)
                RETURNING sequence_number
                """,
                str(policy_id),
                event.event_type,
                event.__dict__,
                datetime.utcnow()
            )
            return row["sequence_number"]

    async def rebuild_state(self, policy_id: UUID) -> dict:
        """Rebuild current state from event history."""
        events = await self.get_history(policy_id)
        state = {}
        for evt in events:
            state = self._apply_event(state, evt)
        return state

from decimal import Decimal
from datetime import date


class EndorsementCalculator:
    """Calculates premium adjustment for a mid-term endorsement."""

    def calculate_prorata_adjustment(
        self,
        current_annual_premium: Decimal,
        new_annual_premium: Decimal,
        endorsement_date: date,
        policy_expiry: date
    ) -> Decimal:
        """
        Returns positive amount (charge) or negative amount (refund).
        """
        remaining_days = (policy_expiry - endorsement_date).days
        total_days = 365
        premium_difference = new_annual_premium - current_annual_premium
        prorata_factor = Decimal(remaining_days) / Decimal(total_days)
        return premium_difference * prorata_factor


class EndorsementService:
    async def add_driver(
        self,
        policy_id: str,
        driver_data: dict,
        effective_date: date
    ) -> dict:
        """Add an additional driver to an auto policy."""
        policy = await self.repo.get_policy(policy_id)
        if not policy.is_active():
            raise ValueError("Cannot endorse inactive policy")

        new_premium = await self._reprice_with_driver(policy, driver_data)
        adjustment = self.calculator.calculate_prorata_adjustment(
            current_annual_premium=policy.annual_premium.amount,
            new_annual_premium=new_premium,
            endorsement_date=effective_date,
            policy_expiry=policy.expiry_date
        )

        endorsement_id = await self.repo.create_endorsement(
            policy_id=policy_id,
            type="ADD_DRIVER",
            effective_date=effective_date,
            driver_data=driver_data,
            premium_adjustment=adjustment
        )

        return {
            "endorsement_id": str(endorsement_id),
            "premium_adjustment": float(adjustment),
            "currency": "EUR",
            "effective_date": effective_date.isoformat()
        }

from datetime import date, timedelta
import asyncio


class RenewalOrchestrator:
    RENEWAL_WINDOWS = [60, 45, 30, 15, 7]  # Days before expiry

    async def run_daily_renewal_batch(self) -> dict:
        today = date.today()
        stats = {"processed": 0, "quoted": 0, "errors": 0}

        for days_ahead in self.RENEWAL_WINDOWS:
            target_date = today + timedelta(days=days_ahead)
            candidates = await self.repo.get_expiring_policies(target_date)

            tasks = [
                self._process_renewal_candidate(p_id, days_ahead)
                for p_id in candidates
            ]
            results = await asyncio.gather(*tasks, return_exceptions=True)

            for r in results:
                stats["processed"] += 1
                if isinstance(r, Exception):
                    stats["errors"] += 1
                else:
                    stats["quoted"] += 1

        return stats

    async def _process_renewal_candidate(
        self,
        policy_id: str,
        days_to_expiry: int
    ) -> dict:
        policy = await self.repo.get_policy(policy_id)
        renewal_premium = await self.pricer.calculate_renewal(policy)

        renewal_quote = await self.repo.save_renewal_quote(
            policy_id=policy_id,
            renewal_premium=renewal_premium,
            valid_days=days_to_expiry + 30
        )

        template = "renewal_early_notice" if days_to_expiry == 60 else "renewal_reminder"
        await self.notification.send_renewal_outreach(
            holder_email=policy["holder"]["email"],
            template=template,
            context={
                "policy_number": policy["policy_number"],
                "renewal_premium": renewal_premium,
                "renewal_link": f"https://portal.insurer.com/renew/{renewal_quote['id']}"
            }
        )
        return renewal_quote