"""Shared ``HandleResult`` dataclass for handlers (SP27).

Every per-file-type handler returns the same shape so the
scheduler's ``_handle_one`` and the FastAPI parse endpoints can
process them uniformly.
"""
from __future__ import annotations

from dataclasses import dataclass


@dataclass
class HandleResult:
    """Outcome of one handler invocation.

    Attributes:
        parser_used: The parser name written to
            ``processed_inbound_files.parser_used`` (e.g. ``"parse_999"``)
            and surfaced in the UI.
        claim_count: The number of claim rows persisted (or batch
            records, depending on the file type). For 999/TA1 this
            is the receipt count; for 835 this is the per-claim
            remittance count; for 277CA this is the per-claim
            status count.
        batch_id: The persisted batch id (when the handler creates a
            row in ``batches``). ``None`` for handlers that persist
            into per-file-type ack tables (999/TA1/277CA) rather
            than into the unified ``batches`` table.
        matched_count: For 835, the number of remits that were
            matched to an existing claim by ``reconcile.match``.
            Zero for other handlers.
    """

    parser_used: str
    claim_count: int
    batch_id: str | None = None
    matched_count: int = 0
