# __APP_NAME__ — REST API Python (FastAPI)

App generada desde el Golden Path **`rest-api/python`** de Coralware Cove IDP.

Scaffold para API HTTP stateless en FastAPI. **Sin persistencia por
diseño** — si tu app necesita base de datos, migra al shape
`web-backend/python` (que incluye Alembic + MariaDB).

> **Contrato del shape:** ver `coralware-shape.yaml`. Define los endpoints
> obligatorios y la versión del shape. No elimines ese archivo — la
> plataforma lo lee.

---

## Estructura

```
.
├── coralware-shape.yaml          ← contrato con la plataforma
├── catalog-info.yaml             ← entidad Backstage
├── code/
│   ├── app/main.py               ← FastAPI app
│   ├── tests/                    ← pytest + httpx TestClient
│   ├── pyproject.toml
│   ├── requirements.txt
│   └── Dockerfile
├── helm/__APP_NAME__/            ← Helm chart minimal
└── .gitea/workflows/             ← CI: tests + build + deploy
```

> **Hooks Helm:** el `ServiceAccount` se materializa como hook
> `pre-install,pre-upgrade` (`hook-weight: -5`,
> `hook-delete-policy: before-hook-creation`) por **paridad** con el shape
> `web-backend/python`. Este shape no tiene Job de migración, así que el hook
> no es estrictamente necesario aquí — se mantiene para que ambos charts sean
> coherentes. `helm upgrade --install` funciona sin `--no-hooks`.

---

## Endpoints obligatorios

| Path | Auth | Propósito |
|------|------|-----------|
| `/health` | none | Liveness + readiness; devuelve `{status: "ok"}` |
| `/docs` | configurable | Swagger UI |
| `/openapi.json` | configurable | Schema OpenAPI |
| `/metrics` | restringido vía NetworkPolicy | Métricas Prometheus |

---

## Variables de entorno

| Variable | Default | Descripción |
|----------|---------|-------------|
| `LOG_LEVEL` | `INFO` | `DEBUG` para troubleshooting |
| `CORRELATION_ID_HEADER` | `X-Correlation-ID` | Header de trazabilidad |
| `OPENAPI_REQUIRE_AUTH` | `false` | Activar JWT en `/docs` |
| `KEYCLOAK_ISSUER` | — | URL del realm cuando auth activado |

---

## Desarrollo local

```bash
cd code
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000
```

Probar:

```bash
curl http://localhost:8000/health
curl http://localhost:8000/docs
```

---

## Plan de salida

Sin lock-in técnico:

| Componente | Cómo lo exportas |
|-----------|------------------|
| Código | `git remote add github && git push github main` |
| Imagen | `docker pull` desde Harbor + push a tu registry |
| Manifests | Ya están en `helm/` — `helm template` genera YAML aplicable |

---

## Cuándo migrar a `web-backend/python`

Si tu app empieza a:
- Necesitar persistencia (base de datos relacional)
- Usar migraciones de schema
- Servir frontend estático en `/demo`
- Manejar sesiones o estado entre requests

→ migra al shape `web-backend/python` (un repo nuevo, un nuevo template).

---

## Referencias

- `docs/adr-027-product-design-golden-paths.md` — Golden Paths Fase 5
- `docs/adr-053-shape-web-backend-python.md` — anatomía de shapes (referencia)
- `docs/adr-038-ci-cd-standardization.md` — pipeline Python