Docker, pipeline y tu primer PR en m-b-core

# Nada de esto entra al contexto de build: ni secretos, ni entornos, ni basura.
.git
.venv
env/
*.db
.pytest_cache
.ruff_cache
.mypy_cache
.coverage
coverage.json
__pycache__
docs/
*.md

# Plantilla: copiar a env/local.env (ignorado por git) y rellenar. NUNCA valores reales aquí.
ENV=dev
APP_VERSION=dev
DB_URL=postgresql+asyncpg://USER:PASSWORD@localhost:5440/mesa_core

# syntax=docker/dockerfile:1
# ---------------------------
# Stage 1: builder
# ---------------------------
FROM python:3.12-slim AS builder
ENV PYTHONUNBUFFERED=1
WORKDIR /build
COPY requirements /build/requirements
RUN python -m venv /opt/venv \
 && /opt/venv/bin/pip install --no-cache-dir --upgrade pip \
 && /opt/venv/bin/pip install --no-cache-dir -r /build/requirements/base.txt

# ---------------------------
# Stage 2: test (reusa el venv del builder, solo agrega deps de test)
# ---------------------------
FROM builder AS test
RUN /opt/venv/bin/pip install --no-cache-dir -r /build/requirements/local.txt
WORKDIR /app
COPY . /app
ENV PYTHONPATH=/app \
    ENV=test \
    PATH="/opt/venv/bin:$PATH"
# Los tres gates dentro del build. Un fallo aquí corta el pipeline antes del push.
RUN ruff check . && ruff format --check . \
 && mypy services/api/app/availability_engine/ shared/ \
 && pytest --cov=services/api/app --cov=shared --cov-fail-under=70

# ---------------------------
# Stage 3: runtime
# ---------------------------
FROM python:3.12-slim AS runtime
ARG APP_VERSION=dev
ENV APP_VERSION=${APP_VERSION} \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH" \
    PYTHONPATH=/app
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
# Solo lo que se ejecuta: nada de tests, env/, docs ni .git
COPY shared /app/shared
COPY services/api /app/services/api
# Usuario sin privilegios (m-b-core aún corre como root: es un pendiente conocido)
RUN useradd --system --uid 10001 --no-create-home app \
 && rm -rf /app/services/api/app/*/tests /app/services/api/app/conftest.py
USER app
EXPOSE 8080
CMD ["uvicorn", "services.api.app.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1"]

# La imagen corre los tests dentro del build: si fallan, no hay imagen.
docker-test:
	docker build --target test -t mesa-core-practicas:test .

docker-build:
	docker build --target runtime --build-arg APP_VERSION=$$(git rev-parse --short HEAD) -t mesa-core-practicas:local .

name: CI

on:
  push:
    branches: [prod, staging]
  pull_request:
    branches: [prod, staging]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      # Actions pineadas por SHA (no por tag): un tag se puede mover, un SHA no.
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
        with:
          python-version: "3.12"
      - run: pip install ruff==0.6.9
      - run: ruff check .
      - run: ruff format --check .

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
        with:
          python-version: "3.12"
      - run: pip install -r requirements/local.txt
      - run: mypy services/api/app/availability_engine/ shared/ --explicit-package-bases

  test:
    runs-on: ubuntu-latest
    env:
      PYTHONPATH: ${{ github.workspace }}
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
        with:
          python-version: "3.12"
      - run: pip install -r requirements/local.txt
      - name: Tests con umbral de cobertura
        run: |
          python -m pytest services/api/app shared \
            --cov=services/api/app --cov=shared \
            --cov-report=term-missing --cov-report=json:coverage.json \
            --cov-fail-under=70 -q
      - name: Gate por módulo (motor ≥ 90 %)
        run: python3 scripts/check_coverage.py coverage.json

#!/usr/bin/env python3
"""Gate de cobertura por módulo (versión mínima del scripts/check_coverage.py de m-b-core).

Uso: python3 scripts/check_coverage.py coverage.json
Salida 0 si todos los módulos cumplen; 1 si alguno no; 2 si el reporte falta.
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

GATES: list[tuple[str, float]] = [
    ("services/api/app/availability_engine/", 90.0),
    ("services/api/app/locales/", 70.0),
]


def main(path: str) -> int:
    report = Path(path)
    if not report.exists():
        print(f"reporte no encontrado: {path}", file=sys.stderr)
        return 2
    files = json.loads(report.read_text())["files"]
    ok = True
    for prefix, minimum in GATES:
        covered = total = 0
        for name, data in files.items():
            if prefix in name and "/tests/" not in name:
                covered += data["summary"]["covered_lines"]
                total += data["summary"]["num_statements"]
        pct = 100.0 * covered / total if total else 100.0
        status = "ok " if pct >= minimum else "BAJO"
        print(f"{status} {prefix:<45} {pct:5.1f}% (mínimo {minimum:.0f}%)")
        ok = ok and pct >= minimum
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "coverage.json"))

# Pipeline de despliegue (mismo esqueleto que services/api/cloudbuild.yaml de m-b-core, con
# tres correcciones que la auditoría del 16-ago pidió: variables obligatorias validadas,
# secretos por --set-secrets y sin --allow-unauthenticated/ingress abierto).
#
# Se dispara desde un trigger de Cloud Build en la rama `staging` o `prod`.
# El trigger define las variables _ENV, _PROJECT_ID, _REGION, _IMAGE, _SERVICE,
# _LEGACY_SQL_INSTANCE, _DB_SECRET, _JWT_SECRET. Ninguna tiene default aquí.

steps:
  # 0) Validar variables del trigger ANTES de gastar minutos de build.
  #    Incluye _LEGACY_SQL_INSTANCE: si falta, `gcloud run deploy` desplegaría SIN
  #    --add-cloudsql-instances y, como el comando es declarativo, la nueva revisión
  #    perdería el conector de Cloud SQL (causa raíz del incidente del 16-ago-2026).
  - id: validate-vars
    name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
    entrypoint: bash
    args:
      - -c
      - |
        set -euo pipefail
        for v in _ENV _PROJECT_ID _REGION _IMAGE _SERVICE _LEGACY_SQL_INSTANCE _DB_SECRET _JWT_SECRET; do
          eval "val=\$$v"
          if [ -z "$$val" ]; then echo "ERROR: $$v must be set in the trigger."; exit 1; fi
        done

  # 1) Etapa test: corre ruff + mypy + pytest DENTRO del build. Si falla, el pipeline muere aquí.
  - id: test
    name: gcr.io/cloud-builders/docker
    args: ["build", "--target", "test", "-t", "${_IMAGE}:test", "."]

  # 2) Imagen de runtime, etiquetada por SHA (inmutable). Nunca :latest para desplegar.
  - id: build
    name: gcr.io/cloud-builders/docker
    args:
      - build
      - --target=runtime
      - --build-arg=APP_VERSION=$SHORT_SHA
      - -t
      - ${_IMAGE}:$SHORT_SHA
      - .

  - id: push
    name: gcr.io/cloud-builders/docker
    args: ["push", "${_IMAGE}:$SHORT_SHA"]

  # 3) Migraciones antes del deploy, con la MISMA imagen que se va a desplegar.
  #    La URL de la BD viene de un secreto; alembic la enmascara con
  #    make_url(...).render_as_string(hide_password=True), nunca con split('@')[0].
  - id: migrate
    name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
    entrypoint: bash
    args:
      - -c
      - |
        set -euo pipefail
        DB_URL="$$(gcloud secrets versions access latest --secret=${_DB_SECRET})"
        docker run --rm -e DB_URL="$$DB_URL" -e PYTHONPATH=/app "${_IMAGE}:$SHORT_SHA" alembic upgrade head

  # 4) Deploy declarativo y COMPLETO: cada flag que omitas se pierde en la nueva revisión.
  #    Secretos por clave (--set-secrets), no un .env volcado a --env-vars-file.
  #    Servicio privado detrás del balanceador: sin --allow-unauthenticated, ingress restringido.
  - id: deploy
    name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
    entrypoint: gcloud
    args:
      - run
      - deploy
      - ${_SERVICE}
      - --image=${_IMAGE}:$SHORT_SHA
      - --region=${_REGION}
      - --platform=managed
      - --no-allow-unauthenticated
      - --ingress=internal-and-cloud-load-balancing
      - --add-cloudsql-instances=${_LEGACY_SQL_INSTANCE}
      - --set-env-vars=ENV=${_ENV},APP_VERSION=$SHORT_SHA
      - --set-secrets=DB_URL=${_DB_SECRET}:latest,JWT_SECRET=${_JWT_SECRET}:latest
      - --min-instances=0
      - --max-instances=10
      - --concurrency=30

options:
  logging: CLOUD_LOGGING_ONLY
substitutions:
  _ENV: ""            # sin defaults: la validación del paso 0 exige que el trigger los defina
  _PROJECT_ID: ""
  _REGION: ""
  _IMAGE: ""
  _SERVICE: ""
  _LEGACY_SQL_INSTANCE: ""
  _DB_SECRET: ""
  _JWT_SECRET: ""

deploy-force:
	# Force deploy by creating an empty commit and pushing to trigger Cloud Build
	@git checkout $$ENV 2>/dev/null || (echo "Branch $$ENV no existe"; exit 1)
	@git commit --allow-empty -m "force deploy to $$ENV [skip ci]" || true
	@git push origin $$ENV

## Qué
Dos tests de `cities/utils.py::to_city_dto` que faltaban: ciudad sin coordenadas
y ciudad con `Foto` nula (placeholder).

## Por qué
`check_coverage.py` marca `cities/` en 68 % (mínimo 70 %). Las dos ramas sin cubrir
son justo las que producen filas raras en prod (Colombia sin lat/lng; ciudades nuevas
sin foto). Si alguien cambia el fallback del placeholder, estos tests lo atrapan.

## Cómo probar
    docker compose exec -T api python3 -m pytest /app/services/api/app/cities -q

## Checklist
- [x] Función pura → parametrize sin mocks (TESTING.md §1)
- [x] Sin cambios de comportamiento; solo tests
- [x] ruff check / format limpios
- [x] Commit `test(cities): …` con el porqué
- [x] Puedo explicar cada línea