app/api/catalog.py

"""Public template catalog — section codes and labels per RICS product tier."""

from fastapi import APIRouter, Query, Request

from app.models.schemas import TemplateCatalogResponse, TemplateCatalogSection
from app.templates.registry import get_survey_pack, resolve_survey_level

router = APIRouter()


def _hint_for_template(expected_fields: list[str]) -> str:
    if not expected_fields:
        return ""
    return " · ".join(f.replace("_", " ") for f in expected_fields[:12])


@router.get("/templates/catalog", response_model=TemplateCatalogResponse)
async def templates_catalog(
    request: Request,
    survey_level: int | None = Query(
        default=None,
        ge=1,
        le=3,
        description="1 = Condition Report, 2 = HomeBuyer / Level 2, 3 = Building Survey. Omit → 3.",
    ),
) -> TemplateCatalogResponse:
    """Return ordered sections, group headings, and export title for the given tier.

    The UI should call this after the user chooses a survey level so section cards
    match the selected RICS product (codes differ between tiers, e.g. Level 1 uses
    a single ``E`` for all external elements; Level 3 uses ``E1``–``E9``).
    """
    _ = request.state.tenant_id  # enforce middleware
    lvl = resolve_survey_level(survey_level)
    pack = get_survey_pack(lvl)
    sections: list[TemplateCatalogSection] = []
    for code in pack.section_order:
        tmpl = pack.get(code)
        if tmpl is None:
            continue
        sections.append(
            TemplateCatalogSection(
                code=tmpl.code,
                title=tmpl.title,
                group=tmpl.group,
                hint=_hint_for_template(tmpl.expected_fields),
            )
        )
    return TemplateCatalogResponse(
        survey_level=lvl,
        product_name=pack.product_label,
        docx_title=pack.docx_title,
        sections=sections,
        group_labels=pack.group_labels,
    )