DOC-02: guía API, operación y soporte¶
Estado: vigente para M11 — Versión 1 operable y demo M10 documentada. Audiencia: integrantes del proyecto, operadores de un entorno local/compartido y quien atienda un incidente sin conocimiento oral previo. El README conserva el arranque corto; esta guía concentra el uso verificable y enlaza las decisiones técnicas.
1. Arranque desde un checkout limpio¶
Requisitos: Git, Python 3.11+, Node.js 20+, npm y Docker Compose v2. Para un arranque local autocontenido:
Copy-Item .env.example .env
Set-Location backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
uvicorn schemasafe.main:app --app-dir src --reload --port 8000
En otra terminal:
Set-Location frontend
npm ci
npm run dev
La API queda en http://localhost:8000, la UI en http://localhost:5173,
Swagger en /docs y el contrato JSON en /openapi.json. Para el entorno
reproducible con PostgreSQL se puede usar:
python scripts/check_documentation.py
bash scripts/deploy.sh
En Windows sin Bash, usar docker compose --profile app up --build y comprobar
manualmente http://localhost:8000/health. El runbook de backup, restore y
rollback está en OPS-03.
Para validar todos los servicios sin iniciarlos, usar explícitamente los
perfiles: docker compose --profile app --profile mongodb --profile couchdb
--profile cassandra config. El perfil app es la ruta local con PostgreSQL;
el arranque directo sin ese perfil conserva SQLite.
2. Identidad, token y flujo mínimo¶
El perfil fixture es el camino seguro para demos y pruebas sin motores
externos. Para emitir un token local, instalar el backend y ejecutar desde
backend/:
python scripts/issue_token.py \
--subject local-analyst --role analyst \
--project default --resource demo --minutes 60
En los perfiles local y secure, configurar
AUTH_SIGNING_KEY_REF=env:SCHEMASAFE_AUTH_SIGNING_KEY y proporcionar el valor
solo en el entorno. Un token debe ser corto, tener iss, aud, exp, proyecto
y recurso permitidos, y enviarse como Authorization: Bearer <token>.
Flujo mínimo de demo:
export SCHEMASAFE_TOKEN='<token-local>'
curl --fail http://localhost:8000/health
curl --fail http://localhost:8000/api/v1/readiness
curl --fail http://localhost:8000/api/v1/engines
curl --fail -H "Authorization: Bearer $SCHEMASAFE_TOKEN" \
http://localhost:8000/api/v1/engines/mongodb/connection
curl --fail -H "Authorization: Bearer $SCHEMASAFE_TOKEN" \
http://localhost:8000/api/v1/engines/mongodb/resources
analyst o admin pueden ejecutar análisis; operator o admin consultan
conexión y recursos; analyst, reader o admin leen reportes según scope;
reader o admin exportan; únicamente admin consulta auditoría. El frontend
no se conecta directamente a un motor ni recibe secretos.
3. API y estados observables¶
La referencia completa está en API y en
/docs. Las rutas públicas de diagnóstico son:
| Ruta | Uso correcto | Fallos visibles |
|---|---|---|
GET /health |
liveness del proceso, sin consultar motores | un error HTTP del proceso |
GET /api/v1/readiness |
estado de cada adapter/configuración | 503 y dependencia not_ready, timeout, forbidden o unavailable |
GET /api/v1/metrics |
contadores agregados de requests/adapters | no contiene cuerpos, actores, URI ni secretos |
GET /api/v1/engines |
capabilities, límites, modo y tipo de recurso | capacidades ausentes quedan declaradas |
GET /api/v1/operations |
catálogo versionado de las 15 operaciones | campos/capability requerida por operación |
El flujo funcional usa POST /api/v1/analyses con engine, project_id,
resource y proposal. El resultado conserva riesgo, outcome, reglas,
hallazgos, evidencia y limitaciones. El historial usa
GET /api/v1/analyses/history; el detalle, comparación y exportación son
GET /api/v1/analyses/{id}, GET /api/v1/analyses/compare y
GET /api/v1/analyses/{id}/export?format=json|csv.
4. Catálogo de errores y recuperación¶
| Estado/código | Significado | Acción del operador |
|---|---|---|
401 |
Bearer ausente, inválido o expirado | emitir un token nuevo; no copiarlo a tickets/logs |
403 |
rol, proyecto o recurso no autorizado | revisar claims y scope con un administrador |
404 |
motor, recurso o reporte inexistente | comprobar discovery y el identificador |
400 CAPABILITY_UNSUPPORTED |
el motor no declara la capability | elegir una operación soportada o aceptar revisión manual |
400 EXPORT_FORMAT_UNSUPPORTED |
formato distinto de JSON/CSV | corregir format |
422 |
payload, filtro, fecha o campo inválido | corregir el dato señalado; no se inspecciona la fuente |
503 readiness |
una dependencia no está lista | revisar la dependencia indicada y volver a comprobar; no forzar aprobación |
timeout/incomplete |
evidencia insuficiente o límite alcanzado | conservar la limitación y solicitar revisión; no interpretar como impacto cero |
Todas las respuestas y eventos aceptan/propagan X-Correlation-Id seguro. Al
reportar un problema, conservar fecha, versión/commit, ruta, status, correlation
ID y el estado sanitizado de readiness. Nunca adjuntar tokens, URI, passphrases,
documentos, dumps ni cuerpos de error.
5. Troubleshooting por motor¶
| Motor | Síntoma | Comprobaciones seguras | Límite conocido |
|---|---|---|---|
| MongoDB | unavailable, timeout o forbidden |
MONGODB_URI_REF, MONGODB_DATABASE, timeout, rol read, MONGODB_MAX_DOCUMENTS y TLS del perfil secure; repetir /connection y /resources |
conteo/muestra acotados; no se devuelven validator ni credenciales |
| CouchDB | _up falla, base ausente o página incompleta |
URL https:// y verificación TLS en secure, referencias de usuario/contraseña, COUCHDB_DATABASE, timeout y límites; comprobar _up antes de _find |
Mango _find es read-only; design docs, validadores y conflictos quedan como limitaciones |
| Cassandra | driver ausente, auth/timeout o tabla sin evidencia documental | extra cassandra-driver, contact points/puerto/keyspace, rol SELECT, timeout y TLS; verificar discovery antes de inspección |
se consulta metadata CQL, no filas; sin partition key no hay scan ni métricas documentales |
En todos los motores, fixture evita conexiones externas y sirve para separar
un problema de configuración de un problema del núcleo. El análisis es
read-only: no solucionar un incidente ejecutando insert, update, delete,
DDL o migraciones sobre la fuente.
6. Persistencia y operación¶
SQLite (DATABASE_PATH) es el modo demo. PostgreSQL se selecciona mediante
DATABASE_URL_REF=env:SCHEMASAFE_DATABASE_URL; aplica migraciones, índices,
retención y transacciones. REPORT_RETENTION_DAYS y
AUDIT_RETENTION_DAYS son retención lógica y no sustituyen un backup.
En la demo pública M10 el frontend y los manuales se publican en Cloudflare
Pages Free y el backend usa Azure Container Apps Consumption con
minReplicas=0 y maxReplicas=1. CONNECTION_PROFILE=fixture es la opción
predeterminada; PostgreSQL es opcional y MongoDB/CouchDB/Cassandra no se
publican. Azure Static Web Apps no es parte del despliegue elegido. Si faltan
las credenciales del environment schemasafe-demo, el workflow queda
bloqueado y no debe interpretarse como una URL pública existente.
Para deploy, backup cifrado, restore verificado, rollback y política de
volúmenes, seguir OPS-03. No usar
docker compose down -v durante diagnóstico normal. Para inspeccionar un
entorno sin exponer valores, usar docker compose ps, healthchecks y
docker compose logs --no-color <servicio> revisando/redactando la salida antes
de compartirla.
7. Soporte y límites¶
Un reporte de soporte debe incluir: objetivo, entorno (fixture, local o
secure), motor, recurso lógico, commit, hora, correlation ID, endpoint y
status. Debe excluir datos reales, secretos y contenido de documentos. El
canal de seguimiento es una GitHub Issue del repositorio con la plantilla y
evidencia sanitizada.
SchemaSafe no ejecuta migraciones, no promete equivalencia entre motores, no calcula impacto global cuando la evidencia es sample/incomplete y no reemplaza un sistema de migración. La CI y los runbooks validan PostgreSQL y fixtures sintéticos; no certifican RPO/RTO, KMS, replicación, backups físicos ni restauración de volúmenes Docker.