FD05 — Informe final (borrador editable)¶
Sigue el índice de la plantilla oficial
FD05-EPIS-Informe ProyectoFinal.docx(Antecedentes, Planteamiento del problema, Marco teórico, Desarrollo de la solución, Presupuesto, Conclusiones, Recomendaciones, Bibliografía, Anexos). Es texto para pegar en esa plantilla; no se generó el.docx. Datos de portada: Universidad Privada de Tacna · Facultad de Ingeniería · EPIS · Curso: Calidad y Pruebas de Software · Docente: Ing. Patrick Cuadros Quiroga · Integrantes: Kevin Elvis Hinojosa Calloapaza (2023078335), Gerald Deybi Zevallos Pinto (2023078691) · Tacna – Perú · 2026. Control de versiones: 1.0, KHC/GZP, fecha de la entrega (borrar el ejemplo «MPV/ELV/ARV 10/10/2020» de la plantilla). Convención: [Hecho] verificado en el repositorio · [Fuente] respaldado por una fuente leída · [Meta]/[Hipótesis] sin medir · [Futuro] no implementado. Las capturas con datos sintéticos, H2 o sustitutos SQLite se rotulan «ilustrativa».
1. Antecedentes¶
El proyecto nace en el curso Calidad y Pruebas de Software: el docente propuso proyectos y los dos integrantes eligieron este (FD01 §resumen, FD06 §1). No hubo organización cliente, entrevistas, convenio ni medición de beneficios. Dos exigencias reales de entidades peruanas muestran por qué se documentan pruebas sobre bases de datos: el TdR de la Contraloría General de la República (2024) pide, en sus anexos 04.1 a 04.3, pruebas funcionales con casos de prueba, un plan de pruebas que incluye «pruebas de datos e integridad de Base de Datos» y un informe de pruebas con evidencias, y el TdR del Ministerio del Ambiente (s. f.) pide, en su apartado V, un «Documento de Pruebas de Base de Datos» aprobado por el administrador de la base, con Oracle 11g como motor (anexo 1). Este producto no serviría para esa entidad tal como está: exige Oracle 12.1 o posterior (modo Thin). Estos documentos son ejemplos; no prueban que esas entidades tengan el problema ni que usarían este producto.
2. Planteamiento del problema¶
2.1 Problema¶
Quien modifica una consulta u operación sobre datos Oracle debe comprobar que sigue dando lo esperado. Si la comprobación queda aislada, cuesta repetirla, compararla y conservar qué se ejecutó. Es una necesidad potencial, no observada en una organización. Detalle y fuentes: docs/problema-y-objetivos.md.
2.2 Justificación¶
Reunir en un lugar la sentencia, la conexión, lo esperado y cada resultado permite repetir y revisar. Oracle SQL Developer ya ofrece suites de pruebas unitarias y línea de comandos [Fuente]; por eso no se afirma novedad ni superioridad. El aporte es una alternativa web con prueba rápida guiada, reglas por ambiente, Excel, CLI y un panel de uso, cuya utilidad no se midió (hipótesis H1–H3).
2.3 Alcance¶
Implementado, demostración académica y trabajo futuro: ver la tabla de tres capas en docs/problema-y-objetivos.md §3 y §6 de este informe. Fuera de alcance: otros motores, Oracle anterior a 12.1 (el modo Thick con cliente Oracle 19 alcanzaría la 11.2 según la documentación del controlador; no verificado, no implementado), usuarios individuales, carga, vulnerabilidades, alta disponibilidad.
2.4 Objetivos¶
Los de investigación (OI‑1…3) y los de solución (OS‑1…9) con su estado están en docs/problema-y-objetivos.md §4. Resumen del estado: OI‑1…3 hechos (documentales); OS‑3…6, 8 y 9 verificados en local (OS‑3…6 también con Oracle real local en la Fase 2); OS‑1, OS‑2 y OS‑7 sin medir/verificar.
3. Marco teórico¶
3.1 Transacciones y reversión en Oracle¶
Mientras no se confirma, un cambio de datos solo es visible para su sesión y puede deshacerse con ROLLBACK; Oracle emite un COMMIT implícito antes y después de cualquier sentencia DDL (Oracle, s. f.-a). De aquí salen dos decisiones: se bloquean las sentencias que confirman solas, y el DML permitido se ejecuta con autocommit desactivado y se revierte. El rollback no deshace secuencias, transacciones autónomas ni llamadas a paquetes que escriben fuera de la transacción: por eso se exige una cuenta de privilegio mínimo.
3.2 Análisis de sentencias¶
sqlparse se declara «intencionalmente no validador» (sqlparse, s. f.). Se usa para separar sentencias, ignorar comentarios y literales y reconocer palabras clave; no demuestra que una sentencia sea inocua.
3.3 Pruebas de base de datos y comparación de resultados¶
Una comprobación consiste en una sentencia, una regla de comparación y un resultado esperado. El patrón Strategy (Gamma et al., 1994) desacopla la regla: RowCountValidation, ScalarValueValidation y ExistenceValidation.
3.4 Herramienta existente: Oracle SQL Developer (comparación documental)¶
Según la página leída (Oracle, s. f.-b): agrupa pruebas en suites (incluso anidadas, con startup/teardown), las ejecuta sobre una conexión, muestra resultados y reportes, y tiene línea de comandos (sdcli). No hubo pruebas de uso de ninguna de las dos herramientas; la tabla compara funciones declaradas, no desempeño.
| Criterio | SQL Developer (documentación) | Este producto (repositorio) |
|---|---|---|
| Casos / pruebas | Pruebas unitarias sobre objetos y consultas | Casos SQL con ROW_COUNT, SCALAR_VALUE, EXISTS |
| Grupos | Suites (anidables, startup/teardown) | Suites planas, sin startup/teardown |
| Reportes | Reportes del repositorio de pruebas | Historial, panel de uso, Markdown/JUnit/JSON, Excel |
| Historial | Resultados en tablas del repositorio de pruebas | execution_history en SQLite |
| Ambientes | No se leyó una política por ambiente | TEST / STAGING / PRODUCTION con reglas distintas |
| Línea de comandos | sdcli |
python -m app.cli (código de salida 0/1/2/3/4) |
| Interfaz | Aplicación de escritorio | Web |
| Instalación | Cliente + repositorio en la base | Servicio web + SQLite; sin esquema propio en la Oracle objetivo |
4. Desarrollo de la solución¶
4.1 Análisis de factibilidad¶
Técnica, económica, operativa, legal y ambiental: ver FD01 (Anexo 01). Las cifras económicas son escenarios de planificación. Operativa y legal: el historial guarda SQL y resultados esperados (puede contener datos sensibles) y no existe archivo LICENSE.
4.2 Tecnología de desarrollo [Hecho: requirements.txt, Dockerfile]¶
Python 3.12 · FastAPI/Uvicorn · SQLAlchemy y Alembic (SQLite interna) · python-oracledb Thin · sqlparse · openpyxl · HTML/JavaScript con Bootstrap · pytest · Docker/Compose y Caddy · Terraform (azurerm) · Liquibase (objetos Oracle de la demostración) · GitHub Actions · MkDocs (documentación). Arquitectura: ver FD04 y los diagramas generados (docs/generated/diagramas.md).
4.3 Metodología de implementación¶
Se trabajó por fases sobre el repositorio: base funcional (14‑sep a 06‑oct‑2026, según los commits), y las fases 1–5 (18 a 20‑oct‑2026, trabajo local sin commit): recorrido guiado, reglas sobre datos con Oracle desechable, automatizaciones de infraestructura/base/copias/release, dashboard e integraciones, y documentación generada. Cada fase cerró con pruebas ejecutadas y un informe que separa lo creado, lo probado en local, lo probado con Oracle real, lo ejecutado en GitHub y lo desplegado en Azure. No se declara una metodología formal (Scrum, etc.) porque no hay registros que la respalden.
4.4 Documentos de visión, SRS y SAD¶
Anexos 02, 03 y 04. Versiones corregidas propuestas: docs/informes/.
4.5 Cronograma¶
| Periodo | Hecho | Fuente |
|---|---|---|
| 14‑sep a 06‑oct‑2026 | Aplicación base, FD01–FD04 y FD06 en PDF | git log (35 commits) |
| 18 a 20‑oct‑2026 | Fases 1–5 (local) | Informes de fase |
| Pendiente → 13‑nov‑2026 | Ejecutar en GitHub/Azure lo preparado, medir usabilidad, regenerar PDF/Word, presentación | Propuesta del plan de la Fase 0; fecha límite de entrega: 15‑nov‑2026 00:00 (consigna) |
5. Presupuesto¶
Los costos de un escenario de implantación (VM de nube, copias, dominio, soporte) están en FD01 §7–§9 y son estimaciones con precios consultados el 1‑oct‑2026 (no reverificados). No se registraron horas ni desembolsos del prototipo; la demostración usó créditos educativos informados por el equipo. El estimador de costos de Terraform (scripts/costs/estimate_costs.py) distingue estimado de real y no inventa cifras si falla la API de precios; no se ejecutó con un plan real.
6. Resultados y estado de verificación¶
6.1 Qué hace hoy la aplicación [Hecho]¶
Proyectos, perfiles sin contraseña, casos y suites (ROW_COUNT, SCALAR_VALUE, EXISTS) con comparación automática, ejecución individual/de suite/rápida, política SQL por ambiente, historial con origen, corrida y «ejecutado por», «Inicio» con resultado explicado, asistente de reglas, demostración guiada, Analizar una tabla (propone reglas desde el diccionario de datos y los datos actuales y las guarda como suite), comparación con la ejecución anterior y tendencia por suite, reporte HTML y Excel por corrida, panel «Uso del producto» (cifras desde datos guardados, también por persona y origen), usuarios con roles ADMIN/TESTER con solicitud de cuenta y aprobación, Excel (plantilla, importar todo-o-nada, exportar), CLI con informes y códigos de salida. Endpoints: docs/generated/api-endpoints.md. Datos: docs/generated/diccionario-datos.md. Seguridad del acceso: docs/seguridad.md.
6.2 Estado por componente¶
«Probado local» incluye el uso de Oracle simulado (sustituto SQLite de las pruebas) o H2: no es Oracle real. Pruebas con Oracle real (Oracle Free en Docker local desechable): 18‑oct‑2026 (Fase 2) y 26‑oct‑2026 (tras usuarios, análisis de tablas y comparación: 28 pruebas Oracle, suite completa 490 superadas y 0 omitidas; además, la imagen Docker nueva se probó de punta a punta contra ese Oracle: 13 de 13 comprobaciones). Según el equipo, los checks del PR #6 pasaron en GitHub, incluidos Liquibase y Alembic contra un Oracle desechable de CI; no se guardó aquí el enlace ni se comprobó qué commit cubrieron.
| Componente | Creado | Probado local | Probado con Oracle real | Ejecutado en GitHub | Desplegado en Azure |
|---|---|---|---|---|---|
| API, motor y política SQL | Sí | Sí (suite pytest) | Sí (Fase 2: SELECT, INSERT revertido, DROP/TRUNCATE/ALTER rechazados, suite 5 PASS→FAIL→5 PASS; repetido 26‑oct) |
Según el equipo, sí (PR #6) | No verificado |
| Inicio / prueba rápida y comparación automática | Sí | Sí (Oracle simulado) | Sí (26‑oct, tests/test_oracle_fase_c.py) |
Pendiente de confirmar | No |
| Usuarios, roles y «ejecutado por» | Sí | Sí (tests/test_usuarios.py, matriz de 52 operaciones) |
Sí (26‑oct, imagen Docker + Oracle) | Pendiente de confirmar | No |
| Analizar una tabla | Sí | Sí (sustituto SQLite con vistas del diccionario) | Sí (26‑oct, diccionario real USER_TAB_COLUMNS) |
Pendiente de confirmar | No |
| Comparación con la vez anterior y reporte por corrida | Sí | Sí | Sí (26‑oct) | Pendiente de confirmar | No |
| Dashboard de uso | Sí | Sí (reloj fijo; datos sembrados) | No aplica (usa solo la SQLite interna) | No | No |
| Excel | Sí | Sí (openpyxl real) | No aplica a importar; exportar resultados usa el historial | No | No |
| CLI | Sí | Sí (sustituto SQLite de Oracle; subproceso) | No | No | No |
Workflow sql-checks.yml |
Sí | Solo análisis estático del YAML | No | No | No |
| Terraform | Sí | fmt, validate, reglas de variables |
No aplica | No | No (sin plan real) |
| Liquibase | Sí | update-sql y 2 ejecuciones sobre H2 en modo Oracle; idempotente |
No (no es prueba contra Oracle) | No | No |
| Copias de la SQLite y restauración aislada | Sí | Sí (pytest) | No aplica | No | No |
| Release / despliegue con reversa | Sí | docker build; bash -n |
No | No | No |
| Documentación generada (Fase 5) | Sí | Generadores, validación de Mermaid y construcción del sitio MkDocs | No aplica | No (workflows creados, no ejecutados) | Pages no publicado |
| Usabilidad (OS‑1/OS‑2) | Protocolo | No medido | — | — | — |
6.3 Pruebas ejecutadas (comando y resultado)¶
Revisión del 28‑oct‑2026 (Windows, Python 3.11.9, sin Oracle porque Docker estaba apagado), desde framework-pruebas-sql/: python -m pytest -q → 469 superadas, 28 omitidas (Oracle), 0 fallidas (497 recogidas); igual con GITHUB_ACTIONS=true y con -m "not oracle_integration"; alembic upgrade head → downgrade base → upgrade head y alembic check sin diferencias sobre una SQLite desechable; 17 archivos JavaScript sin errores de sintaxis; gen_docs.py --check, mkdocs build --strict y git diff --check sin errores. La imagen Docker (Python 3.12) se construyó y probó el 26‑oct‑2026.
Ejecutadas el 20‑oct‑2026 en un equipo Windows con Python 3.11.9 (el Dockerfile y GitHub Actions usan 3.12: no se probó con 3.12 en esa fecha), desde framework-pruebas-sql/:
| Comando | Resultado |
|---|---|
python -m pytest -q (sin variables Oracle) |
330 superadas, 23 omitidas, 0 fallidas (48 s; Fase 7). Las 23 omitidas son las pruebas Oracle y no cuentan como aprobadas. --collect-only: 353 pruebas |
python -m pytest -q tests/test_phase5_docs.py |
24 superadas (más 21 de tests/test_oracle_guard.py) |
python scripts/docs/gen_docs.py --check |
«OK: 40 archivos generados al día» |
python -m mkdocs build --strict |
Sitio construido sin avisos (1,6 s) |
node --check de cada .js de frontend/ |
15 archivos, sin errores |
| Validación de Mermaid (Mermaid 10.9.1 en Edge sin cabeza, necesita internet) | 6 diagramas generados: análisis y dibujo correctos |
git diff --check |
0 errores de espacios (solo avisos de fin de línea CRLF/LF) |
Con Oracle real (Oracle Free en Docker local desechable, 18‑oct‑2026, Fase 2): python -m pytest -m oracle_integration -v -s → 23 superadas; suite completa con Oracle → 198 superadas. No se repitió el 20‑oct‑2026 (en las Fases 3 y 4 Docker Desktop dejó de arrancar contenedores en ese equipo; en la Fase 5 no se reintentó ni se reinició) y desde entonces cambió el código de las Fases 3 a 5.
Cobertura de la documentación del código (Fase 6, docs/generated/cobertura-docstrings.md, generada): módulos con docstring 25/28; clases 11/41; funciones públicas 52/81; métodos públicos 6/25; propiedades con docstring 0/226, de las que 56 columnas ORM se describen en el diccionario de datos y 170 (145 de ellas campos Pydantic de schemas.py) no tienen descripción. El sitio muestra clases, métodos y propiedades, pero muchos sin texto explicativo: es una brecha de contenido, no de herramienta.
Hallazgos corregidos en la Fase 6: un Excel rechazado importado con --create-project dejaba un proyecto vacío (ahora se valida antes de crearlo, con prueba); el panel contaba los intentos de importar Excel rechazados como «importaciones» (la etiqueta y las limitaciones ahora lo dicen).
Falla real encontrada por estas pruebas en la Fase 5: pages.yml tenía un nombre de paso con dos puntos que lo hacía YAML inválido; se corrigió.
7. Conclusiones¶
- Existe una aplicación que permite definir, ejecutar, repetir y registrar comprobaciones SQL sobre Oracle con reglas por ambiente; su comportamiento central se verificó con pruebas automáticas y, en un Oracle local desechable, con SELECT, INSERT revertido y rechazo de DDL.
- El rollback y el bloqueo de DDL son controles, con límites declarados; no garantizan inocuidad. Un PASS solo significa coincidencia con la regla configurada.
- La utilidad (tiempo al primer resultado, ahorro) no está medida; son metas e hipótesis con un protocolo listo.
- La automatización de infraestructura, copias, release y documentación está preparada y probada en local; falta ejecutarla en GitHub y Azure.
- No hubo cliente ni entrevistas; los documentos deben decirlo siempre.
8. Recomendaciones¶
Ejecutar el protocolo de usabilidad con compañeros; guardar los enlaces de las ejecuciones de GitHub Actions y sus artefactos; desplegar la versión nueva en Azure y comprobar ingreso, roles y panel de uso con datos reales; decidir si la solicitud de cuentas queda abierta en Azure; decidir la licencia; verificar los antecedentes que se citen por número de anexo.
9. Bibliografía (fuentes abiertas y leídas el 20‑oct‑2026)¶
- Contraloría General de la República (2024). Términos de referencia para el servicio de mejora para el software de gestión de la línea de producción de microformas digitales. https://doc.contraloria.gob.pe/BID/2024/BID_SCC635/TDR.pdf
- Ministerio del Ambiente (s. f.). Servicio de consultoría para el fortalecimiento del enfoque de economía circular en la Huella de Carbono Perú… https://www.minam.gob.pe/wp-content/uploads/2022/01/TdR-Actualizaci%C3%B3n-HC-Per%C3%BA.pdf
- Oracle (s. f.-a). About DML statements and transactions. https://docs.oracle.com/en/database/oracle/oracle-database/23/tdddg/dml-and-transactions.html
- Oracle (s. f.-b). SQL Developer: Unit testing. https://docs.oracle.com/database/sql-developer-17.4/RPTUG/sql-developer-unit-testing.htm
- sqlparse (s. f.). Introduction. https://sqlparse.readthedocs.io/en/stable/intro.html
- python-oracledb (s. f.). Introduction (versiones soportadas en modo Thin). https://python-oracledb.readthedocs.io/en/latest/user_guide/introduction.html
- Gamma, E., Helm, R., Johnson, R. y Vlissides, J. (1994). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley.
- Citadas en FD01/FD02/FD06 y no reabiertas en la Fase 5: DigitalOcean, SQLite (API de respaldo), SBS, Punto.pe, ANPD, Docker, Presidencia del Consejo de Ministros.
Anexos¶
- Anexo 01: Informe de factibilidad (FD01, con
FD01-parche.md). - Anexo 02: Documento de visión (FD02, con
FD02-parche.md). - Anexo 03: SRS (FD03, con
FD03-fuente-corregida.md). - Anexo 04: SAD (FD04, con
FD04-fuente-corregida.md). - Anexo 05: Manuales y otros documentos:
docs/manual-usuario.md,docs/manual-tecnico.md,docs/operacion-fase3.md,docs/integraciones-fase4.md, diccionario y diagramas generados, estándar de programación, guion de demostración.
Anexo A — Sentencias, reversibilidad y política (derivada de app/security/sql_policy.py)¶
| Sentencia | Según Oracle (23ai) | TEST | STAGING | PRODUCTION |
|---|---|---|---|---|
SELECT |
No cambia datos | Permitida | Permitida | Permitida, filas ocultas; FOR UPDATE rechazado |
INSERT/UPDATE/DELETE |
Reversible con ROLLBACK mientras no haya COMMIT |
Permitida; rollback | Permitida con confirmación; rollback | Rechazada |
CREATE/ALTER/DROP/TRUNCATE/GRANT/REVOKE |
DDL: COMMIT implícito (no reversible) |
Rechazada | Rechazada | Rechazada |
COMMIT/ROLLBACK |
Control transaccional | Rechazada | Rechazada | Rechazada |
CALL/EXECUTE/BEGIN/DECLARE (PL/SQL) |
Pueden hacer cualquier cosa | Rechazada | Rechazada | Rechazada |
MERGE |
DML | Rechazada | Rechazada | Rechazada |
| Varias sentencias | — | Rechazada | Rechazada | Rechazada |
WITH |
Según su sentencia final | Permitida si sqlparse la clasifica como SELECT/INSERT/UPDATE/DELETE |
Ídem | Solo si es SELECT |
SELECT que invoca funciones con transacción autónoma, DBMS_*, UTL_* o enlaces |
Efectos fuera del rollback | No detectado (análisis léxico) | No detectado | No detectado |
La política se evalúa antes de conectar: una sentencia rechazada no abre conexión (comprobado con Oracle real local: 0 conexiones y tabla intacta).
Anexo B — Trazabilidad de columnas con los requisitos¶
| Tabla | Columnas | Requisito |
|---|---|---|
projects |
id, name, description, created_at, updated_at | RF‑02 |
connection_profiles |
project_id, name, engine, host, port, service_name, username, environment_type | RF‑03, RF‑06 (ambiente), RNF‑03/04 |
test_cases |
project_id, name, description, sql_query, expected_result, validation_type | RF‑04, RF‑12 |
test_suites, suite_test_case |
project_id, name, description; suite_id, test_case_id | RF‑05 |
execution_history |
status, executed_at, duration_ms, statement_type, executed_sql, validation_type, expected_result, actual_result, rowcount, rollback_applied, rollback_error, error_message | RF‑07, RF‑08, RF‑06 |
execution_history |
project_id, test_case_id, suite_id, connection_profile_id, trigger_source, run_id | RF‑08, RF‑11 |
usage_events |
event_type, project_id, source, detail, created_at | RF‑11, RF‑12 |
Cobertura: las 7 tablas y todas sus columnas tienen descripción en el diccionario generado (el generador falla si falta alguna).