Irving López
99544639e6
Reemplaza el placeholder mínimo previo por el scaffold canónico del golden path rest-api/python (entry point para tier free-trial): - code/app/main.py — FastAPI con /health (sin DB), /metrics, middleware correlation_id, settings Pydantic - code/tests/ — pytest + httpx TestClient (sin testcontainers, sin Docker) - helm/APP_NAME/ — chart minimal: Deployment, Service, IngressRoute, NetworkPolicy. SIN Job Alembic, SIN ServiceMonitor, SIN claim de BD - coralware-shape.yaml — shapeVersion 1.0.0, minTier free-trial, promotionPath -> web-backend-python cuando se requiera persistencia - .gitea/workflows/APP_NAME-build.yaml — invoca reusable workflow ADR-038 + job helm-deploy con KUBECONFIG_TENANT_B64 Diferencias con web-backend/python: sin alembic, sin BD, sin testcontainers, NetworkPolicy sin acceso a ns-addons. Placeholders __APP_NAME__, __TIER__, __TENANT_ID__, __TENANT_ID_NODASHES__ serán sustituidos server-side por repo-provisioner. El openspec/ del golden path NO se sincroniza al repo Gitea (gobernanza interna de Coralware). Refs: ADR-027 (Golden Paths), ADR-038 (CI), ADR-053 (referencia anatomía).
101 lines
2.7 KiB
Markdown
101 lines
2.7 KiB
Markdown
# __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 (sin hooks)
|
|
└── .gitea/workflows/ ← CI: tests + build + deploy
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|