Standardizing budget cost codes across Procore and Sage 300

from __future__ import annotations

import logging
import re
from typing import Literal

from pydantic import BaseModel, Field, field_validator

logger = logging.getLogger("construction.budget_code_sync")

MappingStatus = Literal[
    "EXACT", "PADDED", "TRUNCATED", "SEGMENT_OVERFLOW", "INVALID_CHAR", "EMPTY"
]
RoutingAction = Literal["auto_route", "human_review", "quarantine"]

# Sage 300 G/L segment widths for THIS company database. Confirm against the
# GLACCOUNT table or your ERP administrator before relying on these values.
SAGE_SEGMENT_WIDTHS: tuple[int, ...] = (4, 4, 4)

_DELIMITERS = re.compile(r"[.\-_ ]+")        # Procore mixes . - _ and spaces
_ALLOWED_SEGMENT = re.compile(r"^[A-Z0-9]+$")  # Sage 300 rejects everything else


class CostCodeMapping(BaseModel):
    """Frozen, deterministic Procore -> Sage 300 cost-code translation result."""

    model_config = {"frozen": True, "extra": "forbid"}

    procore_code: str
    sage_code: str
    segments: tuple[str, ...]
    status: MappingStatus
    confidence: float = Field(ge=0.0, le=1.0)
    detail: str | None = None

    @field_validator("procore_code", mode="before")
    @classmethod
    def _coerce_str(cls, v: object) -> str:
        # The Procore API occasionally returns numeric-looking codes as ints.
        return v if isinstance(v, str) else str(v)

    @property
    def routing(self) -> RoutingAction:
        # A lossy or malformed mapping is never safe to post, whatever the score.
        if self.status in ("TRUNCATED", "SEGMENT_OVERFLOW", "INVALID_CHAR", "EMPTY"):
            return "quarantine"
        if self.confidence >= 0.92:
            return "auto_route"
        if self.confidence >= 0.75:
            return "human_review"
        return "quarantine"


def translate_cost_code(procore_code: str) -> CostCodeMapping:
    """Normalize a Procore cost code into a Sage 300 segment string."""
    raw = (procore_code or "").strip().upper()
    if not raw:
        return CostCodeMapping(
            procore_code=procore_code, sage_code="", segments=(),
            status="EMPTY", confidence=0.0, detail="Empty or non-string input.",
        )

    # 1. Collapse every delimiter run to a single hyphen, then split.
    normalized = _DELIMITERS.sub("-", raw)
    segments = tuple(seg for seg in normalized.split("-") if seg)

    # 2. Character compliance: one bad segment fails the whole code.
    for seg in segments:
        if not _ALLOWED_SEGMENT.match(seg):
            return CostCodeMapping(
                procore_code=procore_code, sage_code="", segments=segments,
                status="INVALID_CHAR", confidence=0.0,
                detail=f"Segment {seg!r} contains characters Sage 300 rejects.",
            )

    # 3. Depth: more segments than Sage allows is a mapping error, not a pad.
    if len(segments) > len(SAGE_SEGMENT_WIDTHS):
        return CostCodeMapping(
            procore_code=procore_code, sage_code="-".join(segments), segments=segments,
            status="SEGMENT_OVERFLOW", confidence=0.0,
            detail=f"{len(segments)} segments exceed the "
                   f"{len(SAGE_SEGMENT_WIDTHS)}-segment Sage 300 structure.",
        )

    # 4. Width enforcement: left zero-fill short segments, flag any truncation.
    final: list[str] = []
    truncated = padded = False
    for i, seg in enumerate(segments):
        width = SAGE_SEGMENT_WIDTHS[i]
        if len(seg) > width:
            final.append(seg[:width])
            truncated = True
        elif len(seg) < width:
            final.append(seg.zfill(width))  # 30 -> 0030, never 3000
            padded = True
        else:
            final.append(seg)

    # 5. Backfill omitted trailing segments with zeros to reach fixed depth.
    while len(final) < len(SAGE_SEGMENT_WIDTHS):
        final.append("0" * SAGE_SEGMENT_WIDTHS[len(final)])
        padded = True

    sage_code = "-".join(final)
    if truncated:
        return CostCodeMapping(
            procore_code=procore_code, sage_code=sage_code, segments=tuple(final),
            status="TRUNCATED", confidence=0.5,
            detail="A segment exceeded its Sage 300 width; characters were dropped.",
        )
    if padded:
        return CostCodeMapping(
            procore_code=procore_code, sage_code=sage_code, segments=tuple(final),
            status="PADDED", confidence=0.80,
            detail="Short or omitted segments were zero-filled to fixed width.",
        )
    return CostCodeMapping(
        procore_code=procore_code, sage_code=sage_code, segments=tuple(final),
        status="EXACT", confidence=1.0,
    )


def sync_cost_code(procore_code: str) -> dict[str, str]:
    """Translate, route by confidence band, and emit a structured audit record."""
    mapping = translate_cost_code(procore_code)
    action = mapping.routing
    if action == "auto_route":
        logger.info("POST %s -> %s", mapping.procore_code, mapping.sage_code)
    elif action == "human_review":
        logger.warning("REVIEW %s -> %s (%s)",
                       mapping.procore_code, mapping.sage_code, mapping.detail)
    else:
        logger.error("QUARANTINE %s (%s)", mapping.procore_code, mapping.detail)
    # model_dump_json gives an immutable, replayable record for the audit trail;
    # only sage_code (never procore_code) should reach an accounting endpoint.
    return {"action": action, "record": mapping.model_dump_json()}