Diccionario de datos¶
Este diccionario se genera desde los modelos SQLAlchemy (app/models/*.py) y el changelog de Liquibase (infra/oracle/liquibase/changelog/). Hay dos bases distintas:
| Base | Motor | Qué guarda | Versionada con | Sección |
|---|---|---|---|---|
| Interna de la aplicación | SQLite (FRAMEWORK_DB_URL) |
Metadatos: proyectos, perfiles de conexión (sin contraseña), casos, suites, historial, eventos de uso | Alembic (alembic/versions/) |
1 |
| Objetivo | Oracle (la que se comprueba) | Los datos del usuario sobre los que se ejecutan los casos. La aplicación no es dueña de esos datos; solo se versiona con Liquibase el objeto de la demostración | Liquibase (infra/oracle/liquibase/) |
2 |
1. Base interna (SQLite)¶
Las fechas created_at/updated_at de test_cases y test_suites se guardan en UTC sin zona horaria; las demás tablas usan UTC con zona horaria. Es una inconsistencia real del código, no un error de este documento.
projects¶
Proyecto: agrupa perfiles de conexión, casos, suites e historial. Es el filtro principal de la interfaz.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador numérico del proyecto. | ||
name |
VARCHAR | no | único | sí | Nombre del proyecto. Único en toda la aplicación. | |
description |
VARCHAR | sí | Descripción libre (opcional). | |||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de creación (UTC, con zona horaria). | ||
updated_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de la última modificación (UTC, con zona horaria). |
users¶
Usuarios de la aplicación con su rol (ADMIN o TESTER). Guarda solo el hash de la contraseña, nunca la contraseña.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador del usuario. | ||
username |
VARCHAR(50) | no | único | sí | Nombre de usuario para ingresar. Único; empieza con una letra (3 a 50 caracteres). | |
full_name |
VARCHAR(120) | sí | Nombre completo para mostrar (opcional). | |||
password_hash |
VARCHAR(255) | no | Hash PBKDF2-SHA256 con sal de la contraseña (formato pbkdf2_sha256$iteraciones$sal$hash). La contraseña no se guarda. | |||
role |
VARCHAR(20) | no | 'TESTER' | Rol: ADMIN (administra usuarios, proyectos y conexiones) o TESTER (crea y ejecuta casos y suites). | ||
active |
BOOLEAN | no | True | Si puede ingresar. Las solicitudes de cuenta quedan inactivas hasta que un ADMIN las aprueba. | ||
failed_attempts |
INTEGER | no | 0 | Intentos fallidos seguidos. Al llegar a 5 la cuenta se bloquea 15 minutos y el contador vuelve a 0. | ||
locked_until |
DATETIME | sí | Hasta cuándo está bloqueada la cuenta por intentos fallidos (UTC). Vacío si no está bloqueada. | |||
session_version |
INTEGER | no | 1 | Versión de sesión: sube al cerrar sesión, cambiar la contraseña, el rol o desactivar la cuenta, y anula los tokens anteriores. | ||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de creación o de la solicitud (UTC, con zona horaria). | ||
last_login_at |
DATETIME | sí | Último ingreso correcto (UTC, con zona horaria). |
connection_profiles¶
Perfil de conexión a la base objetivo (Oracle): dónde y con qué usuario conectarse. NO guarda contraseñas.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador del perfil. | ||
project_id |
INTEGER | no | FK → projects.id | Proyecto al que pertenece el perfil. Un perfil no se usa en otro proyecto. | ||
name |
VARCHAR | no | sí | Nombre visible del perfil. | ||
engine |
VARCHAR | no | 'ORACLE' | Motor de la base objetivo. Hoy solo se acepta ORACLE. | ||
host |
VARCHAR | no | Servidor de la base objetivo. Solo caracteres de nombre de host (se valida); puede restringirse con ORACLE_ALLOWED_HOSTS. | |||
port |
INTEGER | no | 1521 | Puerto de escucha (1521 por defecto). | ||
service_name |
VARCHAR | no | Service name de Oracle (por ejemplo FREEPDB1). | |||
username |
VARCHAR | no | Usuario de Oracle con el que se conecta. La contraseña no se almacena: se pide en cada ejecución. | |||
environment_type |
VARCHAR | no | 'TEST' | Ambiente del perfil: TEST, STAGING o PRODUCTION. Determina qué sentencias se permiten y si se ocultan las filas. | ||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de creación (UTC, con zona horaria). | ||
updated_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de la última modificación (UTC, con zona horaria). |
test_cases¶
Caso de prueba: una sentencia SQL, el tipo de validación y el resultado esperado.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador del caso. | ||
project_id |
INTEGER | no | FK → projects.id | 1 | Proyecto al que pertenece el caso. | |
name |
VARCHAR | no | sí | Nombre del caso. En la importación desde Excel el nombre identifica al caso dentro del proyecto. | ||
description |
VARCHAR | sí | Descripción libre (opcional). | |||
sql_query |
TEXT | no | Sentencia SQL a ejecutar contra la base objetivo (una sola sentencia; pasa por la política de SQL). | |||
expected_result |
VARCHAR | no | Resultado esperado como texto. Significado según validation_type: entero (ROW_COUNT), valor de la primera columna (SCALAR_VALUE) o true/false (EXISTS). | |||
validation_type |
VARCHAR | no | 'ROW_COUNT' | Tipo de comparación: ROW_COUNT (cantidad de filas), SCALAR_VALUE (valor de una única fila) o EXISTS (hay filas o no). | ||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de creación (UTC, sin zona horaria: se guarda con datetime.utcnow). | ||
updated_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de la última modificación (UTC, sin zona horaria). |
test_suites¶
Suite: agrupación de casos del mismo proyecto que se ejecutan juntos.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador de la suite. | ||
project_id |
INTEGER | no | FK → projects.id | 1 | Proyecto al que pertenece la suite. Sus casos deben ser del mismo proyecto. | |
name |
VARCHAR | no | sí | Nombre de la suite. | ||
description |
VARCHAR | sí | Descripción libre (opcional). | |||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de creación (UTC, sin zona horaria). | ||
updated_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | Fecha y hora de la última modificación (UTC, sin zona horaria). |
usage_events¶
Eventos de uso que no son ejecuciones (importar o exportar Excel). Alimenta la sección «Otras acciones» del dashboard.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador del evento. | ||
event_type |
VARCHAR | no | sí | Tipo de evento (p. ej. importación o exportación de Excel). | ||
project_id |
INTEGER | sí | FK → projects.id | Proyecto asociado (opcional). | ||
source |
VARCHAR | sí | Origen del evento: UI, CLI o API. | |||
detail |
VARCHAR(500) | sí | Detalle breve (máximo 500 caracteres). No guarda contenido de archivos ni datos personales. | |||
created_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | sí | Fecha y hora del evento (UTC, con zona horaria). |
execution_history¶
Historial: evidencia de cada ejecución (qué se ejecutó, qué se esperaba, qué se obtuvo, estado y duración).
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
id |
INTEGER | no | PK | Identificador del registro (crece con cada ejecución; el historial se lista de más reciente a más antiguo). | ||
project_id |
INTEGER | no | FK → projects.id | 1 | Proyecto en el que se ejecutó. | |
test_case_id |
INTEGER | sí | FK → test_cases.id | Caso ejecutado. Vacío en las pruebas rápidas de «Inicio», que no son un caso guardado. | ||
suite_id |
INTEGER | sí | FK → test_suites.id | Suite desde la que se ejecutó. Vacío si fue un caso suelto. | ||
connection_profile_id |
INTEGER | sí | FK → connection_profiles.id | Perfil de conexión usado (las ejecuciones exigen un perfil guardado; la CLI crea uno si se le dan host, servicio y usuario). | ||
status |
VARCHAR | no | sí | Resultado: PASS (coincide con lo esperado), FAIL (se ejecutó pero no coincide) o ERROR (no se pudo ejecutar o evaluar). | ||
executed_at |
DATETIME | sí | (función de la aplicación: fecha y hora actual UTC) | sí | Fecha y hora de la ejecución (UTC, con zona horaria). | |
duration_ms |
FLOAT | no | Duración de la ejecución, en milisegundos, medida por la aplicación. | |||
statement_type |
VARCHAR | sí | Tipo de sentencia detectado (SELECT, INSERT, UPDATE, DELETE, o el rechazado, p. ej. DROP). | |||
executed_sql |
TEXT | no | SQL que se ejecutó (copia en el momento de la ejecución). | |||
validation_type |
VARCHAR | sí | Tipo de validación aplicado (copia en el momento de la ejecución). | |||
expected_result |
VARCHAR | sí | Resultado esperado (copia en el momento de la ejecución). | |||
actual_result |
TEXT | sí | Evidencia del resultado obtenido, serializada como texto y truncada a 2000 caracteres. En PRODUCTION solo guarda la cantidad de filas. | |||
rowcount |
INTEGER | sí | 0 | Filas devueltas (SELECT) o afectadas (INSERT/UPDATE/DELETE). | ||
rollback_applied |
BOOLEAN | sí | False | Verdadero si, tras un INSERT/UPDATE/DELETE, el rollback se ejecutó sin error. No prueba por sí solo que Oracle no haya conservado efectos (secuencias, transacciones autónomas). | ||
rollback_error |
TEXT | sí | Mensaje si el rollback falló (en PRODUCTION se reemplaza por un texto genérico). | |||
error_message |
TEXT | sí | Motivo del ERROR (en PRODUCTION se oculta salvo los rechazos de política). | |||
trigger_source |
VARCHAR | sí | sí | Origen: UI (módulos Casos/Suites), INICIO (recorrido guiado), CLI o GITHUB_ACTIONS. Vacío en registros anteriores a la Fase 4. | ||
run_id |
VARCHAR | sí | sí | Identificador de corrida: todas las filas de una misma ejecución de suite o de la CLI lo comparten. | ||
executed_by |
VARCHAR(50) | sí | sí | Usuario que lanzó la ejecución, o «cli» / «github-actions». Vacío sin control de acceso o en registros anteriores a los usuarios. |
suite_test_case¶
Tabla de asociación muchos-a-muchos entre suites y casos.
| Columna | Tipo | Nulo | Clave | Por defecto (en la aplicación) | Índice | Descripción |
|---|---|---|---|---|---|---|
suite_id |
INTEGER | no | PK, FK → test_suites.id | Suite que contiene el caso. | ||
test_case_id |
INTEGER | no | PK, FK → test_cases.id | Caso incluido en la suite. |
Relaciones y borrado en cascada¶
| Desde | Hacia | Cascada de borrado (ORM) |
|---|---|---|
| ConnectionProfile | ExecutionHistory | no (se rechaza o queda dependiente) |
| Project | ConnectionProfile | sí |
| Project | ExecutionHistory | no (se rechaza o queda dependiente) |
| Project | TestCase | sí |
| Project | TestSuite | sí |
| TestCase | ExecutionHistory | no (se rechaza o queda dependiente) |
| TestSuite | ExecutionHistory | no (se rechaza o queda dependiente) |
El borrado en cascada solo lo hace el ORM al eliminar un proyecto; los endpoints de borrado rechazan eliminar proyectos, suites o casos con dependencias (ver docs/seguridad.md).
Dominios de valores¶
| Campo | Valores | Fuente |
|---|---|---|
test_cases.validation_type |
ROW_COUNT, EXISTS, SCALAR_VALUE |
ValidationTypeEnum en app/models/schemas.py |
connection_profiles.environment_type |
TEST, STAGING, PRODUCTION |
EnvironmentTypeEnum en app/models/schemas.py |
execution_history.status |
PASS, FAIL, ERROR |
app/api/history.py (filtro) y execution_service.py |
execution_history.trigger_source |
CLI, GITHUB_ACTIONS, INICIO, SIN_REGISTRAR, UI (vacío = anterior a la Fase 4) |
ORIGENES en app/services/usage_service.py |
usage_events.event_type |
account_requested, demo_guided_run, demo_scenario_loaded, excel_export_cases, excel_export_results, excel_import_cases, excel_template, excel_validate_cases, table_analysis_saved, table_analyzed |
llamadas a record_event en app/ |
2. Objetos Oracle de la demostración (esquema FRAMEWORK_TEST)¶
Solo lo que versiona Liquibase. Son datos de ejemplo para las reglas de calidad de la demostración; la aplicación puede apuntar a cualquier otra base Oracle y no conoce su esquema.
FRAMEWORK_TEST_ITEMS¶
Tabla de la demostración sobre la que se ejecutan las reglas de calidad (5 productos de ejemplo).
| Columna | Definición Oracle | Descripción |
|---|---|---|
ID |
NUMBER PRIMARY KEY |
Identificador del producto (clave primaria). |
NAME |
VARCHAR2(100) NOT NULL |
Nombre del producto (obligatorio). |
ACTIVE |
NUMBER(1) DEFAULT 1 NOT NULL |
1 = activo, 0 = inactivo (por defecto 1). Una regla de la demostración comprueba que solo valga 0 o 1. |
| Objeto | Tipo | Definición | Changeset (archivo) | Descripción |
|---|---|---|---|---|
IX_FW_ITEMS_ACTIVE |
INDEX | ON FRAMEWORK_TEST_ITEMS (ACTIVE) |
002_indice_active.sql |
Índice por ACTIVE sobre FRAMEWORK_TEST_ITEMS. |
V_FW_ITEMS_ACTIVOS |
VIEW | AS SELECT ID, NAME FROM FRAMEWORK_TEST_ITEMS WHERE ACTIVE = 1 |
003_vista_items_activos.sql |
Vista con los productos activos (ID, NAME). |
La prueba test_oracle_phase2.py crea además, solo en un Oracle desechable, la tabla FW_OWNER.CANARY para comprobar el rechazo de DROP; no forma parte del esquema versionado.