Un módulo FastAPI como cities/

"""Códigos de error como constantes con nombre (van en el campo `error` de la respuesta).

Centralizados aquí para que un rename se propague a todos los módulos.
"""

# 400 — validation
VALIDATION_ERROR = "VALIDATION_ERROR"

# 404 — recursos
LOCAL_NOT_FOUND = "LOCAL_NOT_FOUND"

# 500 — internal
INTERNAL_ERROR = "INTERNAL_ERROR"

"""Formato estándar de error para toda la API (y los workers)."""

from enum import Enum
from typing import Any


def error_response(
    error_code: str | Enum,
    message: str,
    status_code: int = 400,
    detail: str | None = None,
) -> dict[str, Any]:
    """Crea la respuesta de error estándar.

    Estructura: {"success": False, "error": <CODE>, "message": <texto>, "detail": <opcional>}
    `status_code` no va en el cuerpo: se pasa a JSONResponse; aquí queda como referencia.
    """
    error_value = error_code.value if isinstance(error_code, Enum) else str(error_code)
    response: dict[str, Any] = {"success": False, "error": error_value, "message": message}
    if detail:
        response["detail"] = detail
    return response

"""Error response utilities: mismo contrato que shared/errors en m-b-core."""

from .codes import LOCAL_NOT_FOUND, VALIDATION_ERROR
from .responses import error_response

__all__ = ["error_response", "LOCAL_NOT_FOUND", "VALIDATION_ERROR"]

"""Configuración centralizada: el ÚNICO módulo que lee variables de entorno.

Como en m-b-core (`shared/settings.py`), es una clase plana que se lee al importar.
En código: `from shared.settings import settings` y luego `settings.ENV`.
"""

import os


class Settings:
    ENV: str = os.getenv("ENV", "dev")
    SERVICE_NAME: str = os.getenv("SERVICE_NAME", "api")
    APP_VERSION: str = os.getenv("APP_VERSION", "dev")


settings = Settings()

"""Mesa Core (prácticas) — API FastAPI.

Expone:
    - GET /health         (versión + estado)
    - GET /v1/locales…    (módulo locales)
"""

from __future__ import annotations

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from datetime import UTC, datetime

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

from shared.settings import settings

from .router import build_api_router

IS_PROD = settings.ENV == "prod"
STARTED_AT = datetime.now(UTC)


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    # Aquí irían pools de DB, clientes HTTP compartidos, etc. (prácticas 2 y 4)
    yield


app = FastAPI(
    title="Mesa Core (prácticas)",
    version=settings.APP_VERSION,
    lifespan=lifespan,
    # En m-b-core la API los deja abiertos también en prod (vicio 38 de la guía);
    # worker y bridge los apagan fuera de staging. Aquí seguimos la versión buena.
    docs_url=None if IS_PROD else "/docs",
    redoc_url=None if IS_PROD else "/redoc",
    openapi_url=None if IS_PROD else "/openapi.json",
    default_response_class=ORJSONResponse,
)


@app.get("/health", tags=["health"])
async def health() -> dict[str, str]:
    """Estado del servicio y versión desplegada (commit sha en prod)."""
    return {
        "status": "ok",
        "version": settings.APP_VERSION,
        "env": settings.ENV,
        "started_at": STARTED_AT.isoformat(),
    }


app.include_router(build_api_router(), prefix="/v1")

"""Router: cada módulo se incluye aquí con su prefijo (como router.py de m-b-core)."""

from fastapi import APIRouter

from .locales.routes import router as locales_router


def build_api_router() -> APIRouter:
    api = APIRouter()
    api.include_router(locales_router)
    return api

"""Modelos de entrada/salida de /v1/locales (Pydantic v2 → OpenAPI)."""

from __future__ import annotations

from pydantic import BaseModel, Field, field_validator


class LocalDTO(BaseModel):
    id: int = Field(..., ge=1, description="Id legacy del local")
    nombre: str = Field(..., min_length=1, description="Nombre comercial")
    pais: str = Field(..., min_length=2, max_length=2, description="ISO 3166-1 alpha-2: 'PE', 'CL'")
    ciudad: str = Field(..., min_length=1)
    zona_horaria: str = Field(..., min_length=1, description="IANA tz, p.ej. 'America/Lima'")
    activo: bool = Field(..., description="EstadoId == 1")

    @field_validator("pais")
    @classmethod
    def pais_mayusculas(cls, v: str) -> str:
        if not v.isupper():
            raise ValueError("pais debe ser ISO 3166-1 alpha-2 en mayúsculas")
        return v


class LocalesResponse(BaseModel):
    total: int = Field(..., ge=0, description="Cantidad de locales devueltos")
    locales: list[LocalDTO] = Field(..., description="Locales activos, ordenados por nombre")

"""Datos en memoria: simulan las filas que en la práctica 4 vendrán de `legacy_db_read`.

Misma forma que una fila de `Local` + `Ubigeo` del legacy: claves con el nombre de columna.
"""

from __future__ import annotations

from typing import Any

LOCALES_ROWS: list[dict[str, Any]] = [
    {"Id": 11, "Nombre": "Maido", "Pais": "PE", "Depa": "Lima", "EstadoId": 1, "ZonaHoraria": "America/Lima"},
    {"Id": 873, "Nombre": "Boragó", "Pais": "CL", "Depa": "Santiago", "EstadoId": 1, "ZonaHoraria": None},
    {"Id": 2246, "Nombre": "Nuema", "Pais": "EC", "Depa": "Quito", "EstadoId": 1, "ZonaHoraria": "America/Guayaquil"},
    {"Id": 999, "Nombre": "Cerrado SAC", "Pais": "PE", "Depa": "Lima", "EstadoId": 0, "ZonaHoraria": "America/Lima"},
]


async def fetch_locales(pais: str | None = None) -> list[dict[str, Any]]:
    """Devuelve filas de locales; en la práctica 4 esta función pasa a `queries.py` con SQL real."""
    rows = LOCALES_ROWS
    if pais is not None:
        rows = [r for r in rows if r["Pais"] == pais]
    return list(rows)


async def fetch_local(local_id: int) -> dict[str, Any] | None:
    for row in LOCALES_ROWS:
        if row["Id"] == local_id:
            return row
    return None

"""Funciones puras del módulo locales: sin I/O, sin estado, fáciles de testear."""

from __future__ import annotations

from typing import Any

from .schemas import LocalDTO

ESTADO_ACTIVO = 1
DEFAULT_TIMEZONE = "America/Lima"


def to_local_dto(row: dict[str, Any]) -> LocalDTO:
    """Convierte una fila legacy (claves = columnas) en el DTO público.

    `ZonaHoraria` NULL cae a DEFAULT_TIMEZONE; la práctica 6 lo reemplaza por `tz_for()`.
    """
    return LocalDTO(
        id=row["Id"],
        nombre=row["Nombre"],
        pais=row["Pais"],
        ciudad=row["Depa"],
        zona_horaria=row.get("ZonaHoraria") or DEFAULT_TIMEZONE,
        activo=row["EstadoId"] == ESTADO_ACTIVO,
    )


def solo_activos(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
    return [r for r in rows if r["EstadoId"] == ESTADO_ACTIVO]


def ordenar_por_nombre(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
    return sorted(rows, key=lambda r: r["Nombre"].casefold())

"""GET /v1/locales y GET /v1/locales/{local_id}.

Pipeline (igual que cities/ en m-b-core):
    1. Validar query params      → Pydantic/Annotated en la firma
    2. Traer filas               → data.py (práctica 4: queries.py con SQL)
    3. Transformar               → utils.py (funciones puras)
    4. Responder                 → response_model / error_response
"""

from __future__ import annotations

from typing import Annotated

from fastapi import APIRouter, Query
from fastapi.responses import JSONResponse

from shared.errors import LOCAL_NOT_FOUND, error_response

from .data import fetch_local, fetch_locales
from .schemas import LocalDTO, LocalesResponse
from .utils import ordenar_por_nombre, solo_activos, to_local_dto

router = APIRouter(tags=["locales"])


@router.get("/locales", response_model=LocalesResponse)
async def list_locales(
    pais: Annotated[
        str | None,
        Query(
            min_length=2, max_length=2, pattern="^[A-Z]{2}$", description="ISO alpha-2, p.ej. PE"
        ),
    ] = None,
) -> LocalesResponse:
    """Locales activos, opcionalmente filtrados por país, ordenados por nombre."""
    rows = await fetch_locales(pais)
    activos = ordenar_por_nombre(solo_activos(rows))
    return LocalesResponse(total=len(activos), locales=[to_local_dto(r) for r in activos])


@router.get("/locales/{local_id}", response_model=LocalDTO)
async def get_local(local_id: int) -> LocalDTO | JSONResponse:
    """Un local por id. 404 con código de error si no existe."""
    row = await fetch_local(local_id)
    if row is None:
        return JSONResponse(
            status_code=404,
            content=error_response(LOCAL_NOT_FOUND, f"Local {local_id} no existe"),
        )
    return to_local_dto(row)

"""Funciones puras → parametrizar bordes, sin mocks."""

import pytest

from services.api.app.locales.utils import ordenar_por_nombre, solo_activos, to_local_dto

FILA_LIMA = {"Id": 11, "Nombre": "Maido", "Pais": "PE", "Depa": "Lima", "EstadoId": 1, "ZonaHoraria": "America/Lima"}


def test_to_local_dto_mapea_columnas_legacy():
    dto = to_local_dto(FILA_LIMA)
    assert dto.id == 11
    assert dto.ciudad == "Lima"
    assert dto.zona_horaria == "America/Lima"
    assert dto.activo is True


@pytest.mark.parametrize(
    "zona, esperada",
    [("America/Santiago", "America/Santiago"), (None, "America/Lima"), ("", "America/Lima")],
)
def test_to_local_dto_zona_horaria_con_fallback(zona, esperada):
    dto = to_local_dto({**FILA_LIMA, "ZonaHoraria": zona})
    assert dto.zona_horaria == esperada


def test_solo_activos_filtra_estado_distinto_de_1():
    rows = [FILA_LIMA, {**FILA_LIMA, "Id": 12, "EstadoId": 0}, {**FILA_LIMA, "Id": 13, "EstadoId": 3}]
    assert [r["Id"] for r in solo_activos(rows)] == [11]


def test_ordenar_por_nombre_ignora_mayusculas():
    rows = [{**FILA_LIMA, "Nombre": "zeta"}, {**FILA_LIMA, "Nombre": "Alfa"}, {**FILA_LIMA, "Nombre": "beta"}]
    assert [r["Nombre"] for r in ordenar_por_nombre(rows)] == ["Alfa", "beta", "zeta"]

"""Rutas → TestClient + patch de la función que la ruta importa (un nivel abajo, no la ruta)."""

from unittest.mock import AsyncMock, patch

from fastapi.testclient import TestClient

from services.api.app.main import app

client = TestClient(app)

_MOCK_LIST = "services.api.app.locales.routes.fetch_locales"
_MOCK_ONE = "services.api.app.locales.routes.fetch_local"

LIMA = {"Id": 11, "Nombre": "Maido", "Pais": "PE", "Depa": "Lima", "EstadoId": 1, "ZonaHoraria": "America/Lima"}
CERRADO = {**LIMA, "Id": 999, "Nombre": "Cerrado SAC", "EstadoId": 0}


def test_list_200_solo_activos_y_ordenados():
    with patch(_MOCK_LIST, new=AsyncMock(return_value=[CERRADO, LIMA])):
        r = client.get("/v1/locales")
    assert r.status_code == 200
    body = r.json()
    assert body["total"] == 1
    assert body["locales"][0] == {
        "id": 11, "nombre": "Maido", "pais": "PE", "ciudad": "Lima",
        "zona_horaria": "America/Lima", "activo": True,
    }


def test_list_pasa_el_pais_a_la_capa_de_datos():
    fake = AsyncMock(return_value=[LIMA])
    with patch(_MOCK_LIST, new=fake):
        r = client.get("/v1/locales", params={"pais": "PE"})
    assert r.status_code == 200
    fake.assert_awaited_once_with("PE")


def test_list_422_si_el_pais_no_es_alpha2():
    r = client.get("/v1/locales", params={"pais": "peru"})  # lo valida FastAPI; sin mock
    assert r.status_code == 422
    assert r.json()["detail"][0]["loc"] == ["query", "pais"]


def test_get_200():
    with patch(_MOCK_ONE, new=AsyncMock(return_value=LIMA)):
        r = client.get("/v1/locales/11")
    assert r.status_code == 200
    assert r.json()["nombre"] == "Maido"


def test_get_404_con_codigo_de_error():
    with patch(_MOCK_ONE, new=AsyncMock(return_value=None)):
        r = client.get("/v1/locales/404404")
    assert r.status_code == 404
    assert r.json() == {"success": False, "error": "LOCAL_NOT_FOUND", "message": "Local 404404 no existe"}


def test_get_422_si_el_id_no_es_entero():
    r = client.get("/v1/locales/abc")
    assert r.status_code == 422


def test_health_devuelve_version():
    r = client.get("/health")
    assert r.status_code == 200
    assert r.json()["status"] == "ok"
    assert "version" in r.json()

# locales

`GET /v1/locales?pais=PE` — locales activos ordenados por nombre.
`GET /v1/locales/{id}` — un local; `404 {"success": false, "error": "LOCAL_NOT_FOUND", …}` si no existe.

Capas: `routes.py` (HTTP, delgado) → `data.py` (I/O; en la práctica 4 pasa a `queries.py`) → `utils.py` (puro).
Contrato de salida: `schemas.py` (`LocalDTO`, `LocalesResponse`).
Tests: `tests/test_utils.py` (puros, parametrizados) · `tests/test_routes.py` (TestClient + patch de `fetch_*` en `routes`).