Fase 4: dashboard de uso e integraciones¶
Estado: implementado y probado en local. Lo que depende de GitHub o Azure está marcado como pendiente de verificar.
1. Dashboard «Uso del producto»¶
Se calcula en el servidor (GET /api/usage/summary?days=30&project_id=) con datos guardados: execution_history, test_cases, test_suites, connection_profiles y usage_events. Las fechas están en UTC.
| Métrica | Qué cuenta | Límite |
|---|---|---|
| Ejecuciones | Filas de historial del periodo. Un caso ejecutado una vez cuenta 1. | Una suite de 5 casos suma 5. |
| Corridas de suite | Ejecuciones agrupadas por run_id. En registros antiguos sin run_id se agrupa por suite y minuto. |
Para registros antiguos es aproximado. |
| Tasa de PASS | PASS / total del periodo. | FAIL = se ejecutó pero no coincide. ERROR = no se pudo ejecutar o evaluar. |
| Casos distintos | Casos guardados ejecutados al menos una vez. | Las pruebas rápidas no cuentan como caso. |
| Proyectos activos | Proyectos con al menos una ejecución. | — |
| Duración media | Media de duration_ms medido por la aplicación. |
No incluye la latencia del navegador. |
| Por fecha | Ejecuciones por día y resultado, con días vacíos en cero. | — |
| Origen | Interfaz web, recorrido «Inicio», CLI o GitHub Actions. | Los registros anteriores a la Fase 4 quedan sin origen. |
| Altas | Casos, suites y conexiones creados en el periodo. | — |
| Otras acciones | Importaciones y exportaciones de Excel (usage_events). |
Solo desde la Fase 4. |
Estados vacíos: sin ejecuciones, el panel explica qué hacer (ejecutar un caso o una suite) en vez de mostrar ceros sin contexto. Si la API falla, hay un botón para reintentar.
El uso por persona se mide desde que existen cuentas individuales (columna executed_by); las ejecuciones anteriores aparecen como «sin usuario».
2. Excel (importar y exportar)¶
Interfaz: sección Casos → «Plantilla Excel», «Importar Excel», «Exportar casos», «Exportar resultados».
- Plantilla
.xlsxcon hoja «Casos» y columnas Nombre, Descripción, SQL, Validación (lista desplegable), Esperado y Suites (separadas por;). - Importación todo o nada: primero se valida sin guardar y se informa fila por fila. Solo se guarda si no hay errores y la persona confirma.
- Validaciones: SQL con la misma política que la ejecución (DDL/DML prohibido, una sola sentencia), esperado coherente con el tipo, nombres no repetidos, fórmulas rechazadas, máximo 2 MB y 500 filas, rechazo de macros y de archivos comprimidos sospechosos.
- Exportación: los textos que empiezan por
=,+,-o@se escriben como texto literal (evita inyección de fórmulas). Los resultados salen con PASS/FAIL/ERROR coloreado. - Las mismas operaciones existen en la CLI (
import-excel,export-excel).
3. CLI¶
python -m app.cli init-db --db checks.sqlite
python -m app.cli import-excel checks/reglas_demo.xlsx --project Demo --create-project --db checks.sqlite
export FW_ORACLE_PASSWORD='<clave-ficticia-reemplace-por-la-de-su-cuenta-de-prueba>' # nunca como argumento
python -m app.cli run --project Demo --suite "Reglas de calidad (demo)" \
--host 127.0.0.1 --port 1521 --service FREEPDB1 --user FRAMEWORK_TEST --env TEST \
--junit reporte.xml --markdown reporte.md --json reporte.json --db checks.sqlite
Códigos de salida: 0 todo PASS · 1 hay FAIL · 2 hay ERROR (incluye no poder conectar) · 3 uso incorrecto · 4 no hay casos que ejecutar.
Si GITHUB_ACTIONS=true, el origen guardado es GITHUB_ACTIONS; si no, CLI.
4. GitHub Actions (.github/workflows/sql-checks.yml)¶
Se ejecuta en pull_request (por rutas), workflow_dispatch y workflow_call. Levanta un Oracle desechable (gvenzl), aplica Liquibase con scripts/db/liquibase_demo.sh, importa checks/reglas_demo.xlsx, ejecuta la suite con la CLI y publica Markdown en el resumen del job, más un artefacto reporte-sql-checks (Markdown, JUnit, JSON y Excel de resultados). El job falla con el código de la CLI. Las claves se generan en la ejecución y se enmascaran; no usa secretos del repositorio ni toca Azure.
Para ver el fallo a propósito: ejecutar manualmente con provocar_dato_invalido = true.
5. Evaluación crítica frente a la consigna¶
| Integración | Qué sí demuestra | Qué no demuestra / riesgo |
|---|---|---|
| CLI | Ejecuta casos/suites con el mismo motor y política, devuelve código útil y reportes. Sirve como compuerta de CI. | Es otro cliente de la misma aplicación: si el ingeniero exige una herramienta externa, por sí sola es débil. |
| GitHub Actions | Ejecuta el producto (no solo sus pruebas) contra un Oracle desechable y conserva el informe. | Nunca se ejecutó en GitHub: solo hay pruebas estáticas del YAML. No corre contra la base de Azure. |
| Excel | Flujo de ida y vuelta con validaciones. | Es una integración por formato de archivo, no con un servicio. Preguntar al ingeniero si cuenta como integración. |
6. Aclaración sobre Liquibase (Fase 3)¶
Ver el informe de Fase 4 en la conversación: la ejecución con H2 en modo Oracle solo valida la sintaxis y el orden de los changesets contra un motor distinto; no es prueba contra Oracle real. La verificación real queda para el workflow db-objects.yml/sql-checks.yml en GitHub.
7. Qué se probó y qué falta¶
Probado en local: migración (subida, bajada, alembic check), métricas con reloj fijo, API, Excel con openpyxl real, CLI en proceso y como subproceso, interfaz con navegador sin cabeza. El objetivo de los casos de CLI/API fue un sustituto SQLite de Oracle (tests/fake_oracle.py), no Oracle.
Pendiente: ejecutar sql-checks.yml en GitHub; repetir la demostración contra un Oracle real desechable; capturas reales (las generadas usan historial sintético).
8. Demostración corta (Kevin y Gerald, ~5 min)¶
- Kevin: «Casos» → «Plantilla Excel», completar 2 filas, «Importar Excel» → confirmar. Mostrar también un Excel con errores (rechazo fila por fila).
- Gerald: en terminal,
runde la suite con la CLI; mostrarreporte.mdyecho $?. - Kevin: «Uso del producto» → ver las corridas con origen CLI; abrir «Cómo leer estas cifras».
- Gerald: en GitHub, ejecutar
SQL checksmanualmente conprovocar_dato_invalidoy mostrar el resumen y el artefacto.
9. Capturas que deben tomar¶
Dashboard sin datos; dashboard con datos reales; importación con errores; importación correcta; terminal con run y código de salida; resumen del job y artefacto en GitHub; Excel de resultados abierto.
6. Integración con Visual Studio Code (tareas, skill y extensión)¶
Estado: creado y probado en local (pruebas estáticas y la CLI real con SQLite; no se abrió VS Code en esta verificación ni se ejecutó contra Oracle).
| Pieza | Dónde | Qué hace |
|---|---|---|
| Tareas | .vscode/tasks.json |
Terminal → Ejecutar tarea: ejecutar suite, validar/importar Excel y exportar resultados. La contraseña se pide oculta y viaja por FW_ORACLE_PASSWORD. |
| Skill para agentes | .claude/skills/comprobaciones-sql/SKILL.md |
Enseña a un agente (p. ej. Claude Code) a usar la CLI, leer los códigos de salida y respetar las reglas de seguridad (sin contraseña en comandos, solo TEST). |
| Extensión | vscode-extension/ (framework-sql-qa-1.0.0.vsix) |
Comandos «SQL QA: Ejecutar suite / Importar casos desde Excel / Exportar resultados a Excel». Lanza la CLI, muestra el código de salida y abre el reporte Markdown. |
Instalar la extensión: Extensiones → «⋯» → «Instalar desde VSIX…». Reconstruirla: cd vscode-extension && npx @vscode/vsce package --no-dependencies.
Límite: la extensión es un lanzador de la CLI (no tiene panel propio ni lista de casos); requiere Python con las dependencias del proyecto.
7. Logs¶
Una línea por evento en la salida estándar (docker logs framework_api_prod): peticiones a /api/* (método, ruta, código, ms), ingresos correctos, fallidos y bloqueos, y cada ejecución de una prueba (resultado, duración, origen, usuario). Nunca se registran contraseñas, SQL ni resultados. Nivel con LOG_LEVEL (INFO por defecto). Código: app/core/logs.py.