Trazabilidad¶
Cómo leer la matriz¶
La columna Estado distingue IMPLEMENTADO en el bootstrap, PLANIFICADO para el desarrollo pendiente y GAP cuando falta una decisión o evidencia. El Issue lógico se transforma en número real después de la creación en GitHub. Ningún requisito puede quedar sin módulo, prueba y milestone.
| Requisito | Feature/tarea | Issue lógico | Módulo | Prueba/evidencia | Milestone | Estado |
|---|---|---|---|---|---|---|
| RF-01 | health/readiness | OPS-01 | api/routes, ops | test_api, test_observability, smoke | M8 | Implementado: /health distingue vida de la app y /api/v1/readiness verifica dependencias |
| RF-02 | capabilities | CORE-01, M2/M3/M4 | adapters/registry | adapter contract tests | M1–M4 | Parcial |
| RF-03 | inspección | CORE-01, MONGO-02/COUCH/CASS-02 | adapters, snapshot | snapshot contract, Mongo/Couch/Cassandra inspection tests | M1–M4 | MONGO-02 y COUCH-02 implementados para inspección documental; CASS-02 conserva metadata CQL sin equivalencia documental |
| RF-04 | propuesta | CORE-02, UI-02 | core/api/frontend | test_contracts, test_api, frontend/src/api.test.ts |
M1/M6 | UI-02 construye propuestas desde el catálogo API y mantiene al backend como autoridad |
| RF-05..RF-10 | reglas estructurales | CORE-04, MONGO-02, COUCH-02, CASS-02, ANALYSIS-01, UI-02 | core/normalization, core/rules, adapters, frontend | test_normalization, inspección Mongo/Couch/Cassandra, analyzer, catálogo y frontend/src/api.test.ts |
M1–M6/M7 | UI-02 comunica la capability requerida y no envía propuestas de operaciones no soportadas; la validación final permanece en backend |
| RF-11..RF-13 | métricas/riesgo/outcome | CORE-03, ANALYSIS-02 | core/risk, core/rules, core/analyzer | test_risk_policy, test_analyzer, test_analysis_evidence | M1/M5 | ANALYSIS-02 distingue evidencia exacta, muestra e incompleta; solo la exacta publica porcentaje |
| RF-14 | historial | REPORT-02, UI-03, OPS-02 | store/api/frontend/infra | test_history, test_persistence, test_postgres_integration, api.test.ts |
M5/M6/M8 | UI-03 presenta filtros, páginas, vacío, error y detalle; OPS-02 conserva el contrato en SQLite/PostgreSQL |
| RF-15 | auditoría | AUDIT-01 | store/security | test_audit |
M5 | AUDIT-01 registra acciones protegidas, exportaciones y denegaciones con redacción defensiva |
| RF-16 | conexiones | MONGO-01, MONGO/COUCH/CASS-01, UI-01, SEC-02 | adapters/frontend/security | Mongo/Couch/Cassandra connection tests, test_secure_configuration.py, frontend/src/api.test.ts |
M2–M4/M6/M8 | SEC-02 resuelve solo referencias de secreto y exige TLS verificable en el perfil secure; UI-01 no muestra secretos |
| RF-17 | recursos | MONGO-01, MONGO/COUCH/CASS-01, UI-01 | adapters/frontend | Mongo/Couch/Cassandra discovery/API tests, frontend/src/api.test.ts |
M2–M4/M6 | UI-01 solo permite seleccionar recursos devueltos por el backend y vuelve al fixture; Cassandra aún no inspecciona columnas ni filas |
| RF-18 | escenarios | TEST-01, MONGO-04/COUCH-04/CASS-04, E2E-02 | escenarios/CI | test_core_matrix, runners MongoDB/CouchDB/Cassandra, gate 50 | M1–M4/M7 | Los tres runners cubren 50 entradas; E2E-02 consolida el catálogo y detecta 14/14 críticos |
| RF-19 | exportación | REPORT-01, UI-03 | api/export, api/routes, frontend | test_exports, api.test.ts, flujo manual UI-03 |
M5/M6 | UI-03 descarga JSON/CSV como revisor local y valida el nombre de archivo antes de descargar |
| RF-20 | identidad/RBAC | SEC-01 | infrastructure/auth, api/dependencies, api/routes | test_auth_rbac, test_api, test_history, test_audit, test_exports |
M8 | Implementado: Bearer firmado, roles, expiración, scope por proyecto/recurso y auditoría de denegaciones |
| RF-21 | auditoría consultable | AUDIT-01 | security/store | test_audit |
M5 | Consulta exclusiva de administrador, filtros de actor/fecha y retención configurable |
| RF-22 | readiness | OPS-01 | api/ops | test_observability, dependency failure smoke |
M8 | Implementado: estado por adapter, HTTP 503 y detalle sanitizado cuando una dependencia no está lista |
| RF-23 | límites | ANALYSIS-02, MONGO-02, COUCH-02, CASS-02, adapters-03 | core/adapters | timeout, pagination and incomplete-evidence tests | M2–M5 | ANALYSIS-02 registra tamaño, límite y duración; muestra/timeout mantienen métricas globales nulas |
| RF-24 | comparación | REPORT-02, UI-03 | core/comparison, api/frontend | test_history, api.test.ts, flujo manual UI-03 |
M5/M6 | UI-03 muestra deltas solo para respuestas comparables y razones cuando la evidencia no permite compararlos |
| RF-25 | OpenAPI/documentación | REPORT-01, DOC-02 | api/docs | test_exports, OpenAPI/link checker | M5/M8 | REPORT-01 documenta exportación, formatos y errores en OpenAPI; documentación operativa posterior |
| RNF-01 | no mutación | MONGO-02/03, COUCH-02/03, CASS-03, E2E-03 | adapters/tests | auditoría CQL, roles read-only, hash del smoke y release gate | M2–M4/M7 | E2E-03 compara el hash de la fuente sintética antes/después del análisis; los conectores conservan lectura preventiva |
| RNF-02 | explicabilidad | CORE-03, ANALYSIS-01, UI-04 | core/risk, core/rules, core/report, frontend | test_risk_policy, test_analyzer, test_analysis_rules, api.test.ts, checklist UI-04 |
M1/M5/M6 | UI-04 comunica que la muestra o evidencia incompleta no es una garantía y conserva reglas, evidencia y limitaciones visibles |
| RNF-03 | extensibilidad | CORE-01/04 | core/normalization, core/adapters | import boundary review, test_normalization | M1 | CORE-04 implementado; adapters live pendientes |
| RNF-04 | seguridad | MONGO-01/03, COUCH-01, CASS-01, SEC-01/02 | adapters/security/ops | sanitized connection/error tests, read-only role, secret scanner y TLS | M2–M4/M8 | SEC-01 protege identidad/RBAC y SEC-02 aplica referencias, TLS y perfiles verificables; no persiste secretos |
| RNF-05 | trazabilidad | TEST-01, MONGO-04, COUCH-04, CASS-04, E2E-02, DOC-01 | docs/CI | matriz core, runners/resultados por motor y gate de 50 escenarios | M1–M4/M7 | E2E-02 ejecuta los 50 casos y detecta 14/14 críticos; ACAD-02 conserva la evidencia final |
| RNF-06 | reproducibilidad | MONGO-03, E2E-01/02 | fixtures/Docker | run_e2e_smoke.sh, seed MongoDB sintético, CI e2e-smoke |
M2/M7 | E2E-01 verifica perfiles app/MongoDB aislados; E2E-02 conserva el gate del catálogo completo |
| RNF-07 | disponibilidad local | E2E-01, OPS-01 | health/readiness | /health, /api/v1/readiness, Compose --wait y smoke de UI/API |
M7/M8 | E2E-01 verifica disponibilidad local y OPS-01 distingue liveness de readiness por dependencia |
| RNF-08 | rendimiento | E2E-03, ANALYSIS-02 | core/ops | test_analysis_evidence, release gate local | M5/M7 | E2E-03 exige menos de dos segundos para el fixture local, sin afirmar un SLO de producción |
| RNF-09 | errores seguros | MONGO-01/02/03, COUCH-01/02/03, CASS-03, UI-04 | adapters/api/frontend | pruebas de permiso, timeout, driver e inspección, api.test.ts, checklist UI-04 |
M2–M6 | UI-04 presenta errores accionables y reintentos solo de consultas read-only; no expone trazas ni secretos |
| RNF-10 | mantenibilidad | DOC-02, E2E-03 | repo/CI | lint/test/build, guía operativa, checker de enlaces y matriz de variables | M7/M8 | DOC-02 completa la guía de soporte y hace verificable el walkthrough desde checkout limpio |
| RNF-11 | observabilidad | OPS-01 | ops | logs JSON y /api/v1/metrics |
M8 | Implementado: agregados de requests/adapters sin PII ni secretos |
| RNF-12 | timeout live | MONGO-03, COUCH-03, CASS-03, E2E-03 | adapters/release gate | pruebas de timeout y run_e2e_release.py |
M2–M4/M7 | E2E-03 controla un timeout local, conserva evidencia incompleta y una limitación visible |
| RNF-13..RNF-16 | privacidad, disponibilidad, versionado y recuperación | SEC-02, OPS-01/02/03 | security/ops/infra | scanner, rotación sin reescritura, logs, métricas, migración PostgreSQL, backup cifrado y restore sintético | M8 | OPS-03 añade runbook, despliegue/rollback reproducibles, backup externo cifrado y CI de pérdida/recuperación; las limitaciones de RPO/RTO y KMS permanecen visibles |
Gaps detectados¶
- CouchDB ya tiene conexión, discovery e inspección live read-only acotada en COUCH-01/02; COUCH-03 verifica superficie HTTP, permisos simulados, timeout, ausencia de retry y no mutación. Design docs, validadores y conflictos de revisión quedan explícitamente limitados hasta issues posteriores. Cassandra tiene conexión, discovery y metadata CQL limitada en CASS-01/02; CASS-03 rechaza CQL fuera de su allowlist, scans de filas sin partition key y verifica en Docker que el rol reader no puede insertar. CASS-04 ejecuta sus 16 escenarios con fixture y marca índices, validaciones, restricciones y acciones específicas como no observables, sin leer filas. MongoDB inspecciona colecciones reales con límite y CI verifica permisos, timeout y no mutación.
- UI-01/UI-04 cubren la selección, propuesta, historial, comparación, exportación y UX accesible; autenticación productiva permanece fuera del frontend local.
- SEC-01 no gestiona usuarios, SSO, rotación de llaves, TLS ni un secret manager; SEC-02 cubre la configuración y protección de despliegue restante.
- SQLite conserva el modo demo; OPS-02 añade PostgreSQL desplegable con concurrencia, migraciones, índices y retención. OPS-03 añade
postgres_backup.py, el runbook, rollback sin borrar volúmenes yrun_operational_recovery.pycon datos sintéticos; no automatiza backups desde la API ni afirma RPO/RTO. - El manifest tiene 50 entradas; E2E-02 consolida los runners deterministas y resultados versionados de MongoDB, CouchDB y Cassandra. El runner live multimotor permanece fuera de alcance hasta E2E-03.
- Las plantillas DOCX de visión, SRS, arquitectura, informe final y propuesta tienen placeholders académicos.
- La observabilidad local no depende de un stack externo: los logs JSON y métricas agregadas se consultan desde la API; el workflow de integración live conserva sus jobs por motor.
Evidencia de CORE-01¶
CORE-01 implementa el contrato versionado 1.0 en backend/src/schemasafe/core/models.py y backend/src/schemasafe/adapters/base.py. Las pruebas backend/tests/test_contracts.py cubren serialización, validación de conteos, provenance, recursos documento/tabla y evidencia incompleta; backend/tests/test_adapters.py verifica que los tres adapters emitan snapshots compatibles sin borrar sus diferencias de recurso.
Evidencia de CORE-02¶
CORE-02 implementa el catálogo de 15 operaciones en backend/src/schemasafe/core/operation_catalog.py, la validación semántica de ChangeProposal en backend/src/schemasafe/core/models.py y el endpoint GET /api/v1/operations. backend/tests/test_contracts.py cubre propuestas válidas para todo el catálogo y backend/tests/test_api.py cubre errores 422, capability engine_specific no soportada (400) y ausencia de inspección para payloads inválidos. La evidencia incompleta permanece visible y sin impacto numérico.
Evidencia de CORE-03¶
CORE-03 centraliza los umbrales y el ranking en backend/src/schemasafe/core/risk.py, calcula un único conjunto afectado en backend/src/schemasafe/core/rules.py y aplica el mapping de outcome en backend/src/schemasafe/core/analyzer.py. backend/tests/test_risk_policy.py cubre las fronteras 0/1/50/80/100, denominadores inválidos y evidencia incompleta; backend/tests/test_analyzer.py cubre tipos, nulls, ausencia, no doble conteo y determinismo.
Evidencia de CORE-04¶
CORE-04 implementa la normalización provider-neutral en backend/src/schemasafe/core/normalization.py, la integra en el adapter de fixtures y hace que core/rules.py resuelva la misma gramática de rutas. backend/tests/test_normalization.py cubre objetos anidados, claves literales con puntos, arrays mixtos, null/ausencia y rutas inválidas; backend/tests/test_adapters.py verifica perfiles normalizados y backend/tests/test_analyzer.py verifica que Cassandra marque anidamiento no aplicable. No se cambia el contrato de adapters ni se ejecutan mutaciones.
Evidencia de TEST-01¶
TEST-01 implementa la matriz parametrizada en backend/tests/test_core_matrix.py: cubre las 50 entradas de escenarios/manifest.json, las reglas positivas/negativas, las siete limitaciones de capability, evidencia incompleta y fronteras de riesgo. La guía 02-matriz-pruebas-core.md enlaza cada requisito con su prueba y documenta el límite respecto a conectores live y E2E.
Evidencia de MONGO-01¶
MONGO-01 implementa conexión y discovery read-only en backend/src/schemasafe/adapters/mongodb.py, modelos sanitizados en core/models.py y endpoints /api/v1/engines/mongodb/connection y /api/v1/engines/mongodb/resources. backend/tests/test_adapters.py cubre fixture, ping mockeado, timeout configurable, base permitida, permisos, driver opcional y ausencia de secretos; backend/tests/test_api.py cubre respuestas de conexión/discovery y limitación explícita de otros adapters.
Evidencia de MONGO-02¶
MONGO-02 implementa inspección live read-only en backend/src/schemasafe/adapters/mongodb.py: conteo exacto, muestra limitada por MONGODB_MAX_DOCUMENTS, perfiles recursivos de CORE-04, índices, presencia de validator, scope por base y provenance full/sample:n/total. backend/tests/test_mongodb_inspection.py cubre colección vacía, mixed/null/missing, nested, muestra incompleta, índices, validator, errores sanitizados, scope y conservación del modo fixture. La integración Docker/read-only y la evidencia before/after quedan para MONGO-03.
Evidencia de MONGO-03¶
MONGO-03 añade scripts/mongodb/init.js y el perfil MongoDB de Compose con una base sintética, validator, índice y usuario restringido al rol read. backend/tests/test_mongodb_integration.py calcula un hash before/after, inspecciona con el adapter, confirma que el insert_one es rechazado con código 13, y verifica timeout como evidencia incompleta sin filtrar credenciales. El job mongodb-integration de .github/workflows/ci.yml instala el extra live, levanta el seed con docker compose --wait y limpia el contenedor al finalizar; los datos son sintéticos y no se versionan.
Evidencia de MONGO-04¶
MONGO-04 implementa scripts/run_mongodb_scenarios.py, que ejecuta las 17 entradas MongoDB del manifest sobre el fixture controlado y produce escenarios/resultados/mongodb-scenarios.json sin datos reales. backend/tests/test_mongodb_scenarios.py comprueba la cobertura exacta de las 15 operaciones del contrato, los cinco escenarios críticos, el escenario de evidencia incompleta y la trazabilidad de cada reporte mediante rules_applied, findings, evidence y recommendation.
Evidencia de COUCH-01¶
COUCH-01 implementa CouchDBAdapter.check_connection() con GET /_up y discover_resources() con GET /_all_dbs, scope por COUCHDB_DATABASE, timeout acotado y credenciales separadas. backend/tests/test_couchdb.py cubre fixture, health, discovery, deduplicación, errores HTTP, timeout, ausencia de secretos y uso exclusivo de GET; backend/tests/test_couchdb_integration.py se ejecuta contra el perfil Docker couchdb en CI. En esa issue la lectura de documentos aún no estaba implementada; COUCH-02 la añade mediante _find.
Evidencia de COUCH-02¶
COUCH-02 implementa CouchDBAdapter.inspect() con consulta Mango read-only POST /{db}/_find, bookmark, límites COUCHDB_PAGE_SIZE/COUCHDB_MAX_DOCUMENTS, normalización CORE-04 y conservación de _id/_rev. backend/tests/test_couchdb.py cubre páginas múltiples, base vacía, bookmark repetido sin duplicación, respuesta sin bookmark, error HTTP, ausencia y null; backend/tests/test_couchdb_integration.py valida tres documentos sintéticos y paginación contra CouchDB Docker. Design docs, validadores y conflictos de revisión quedan visibles como limitaciones, sin falsos positivos ni escrituras.
Evidencia de COUCH-03¶
COUCH-03 restringe CouchDBAdapter a GET /_up, GET /_all_dbs y el POST Mango read-only de COUCH-02 con selector vacío y update=false. backend/tests/test_couchdb.py audita rutas, payloads y una sola llamada, además de HTTP 5xx, timeout, ausencia de secretos y evidencia incompleta. El POST se documenta como consulta necesaria para bookmark, no como mutación; no se exponen endpoints de escritura ni se agregan reintentos.
Evidencia de COUCH-04¶
COUCH-04 implementa scripts/run_couchdb_scenarios.py, que ejecuta las 17 entradas CouchDB del manifest sobre el fixture controlado y produce escenarios/resultados/couchdb-scenarios.json sin documentos sensibles. backend/tests/test_couchdb_scenarios.py comprueba las 15 operaciones del contrato, los cinco escenarios críticos, el escenario cross-02 de evidencia incompleta y la trazabilidad de cada reporte mediante rules_applied, findings, evidence y recommendation. Índices, validadores, restricciones y acciones específicas del motor se modelan como capabilities no observables para CouchDB y generan revisión explícita, sin falsos positivos.
Evidencia de OPS-01¶
OPS-01 implementa el middleware HTTP de backend/src/schemasafe/infrastructure/observability.py, el endpoint público de liveness /health, readiness /api/v1/readiness por adapter y consulta agregada /api/v1/metrics. Cada respuesta incluye X-Correlation-Id y X-Response-Time-Ms; los eventos JSON registran ruta, estado, duración, conteo, error y modo sin cuerpos, headers, actores, recursos ni excepciones. Las métricas en memoria agregan requests por ruta y operaciones por adapter con modo, duración y cantidad observada. backend/tests/test_observability.py cubre dependencias fixture, motor no disponible con HTTP 503, conteos de adapter, logs parseables y redacción de correlation IDs inválidos.
Evidencia de OPS-02¶
OPS-02 implementa PostgresReportStore detrás del contrato ReportStore, mantiene SQLiteReportStore para demo y selecciona el proveedor mediante DATABASE_URL_REF. backend/migrations/001_initial.sql y infrastructure/migrations.py versionan el esquema, índices y compatibilidad con tablas SQLite legadas. Los stores aplican retención separada de reportes/auditoría; SQLite serializa escrituras y PostgreSQL usa conexiones transaccionales por operación, upsert y rollback explícito. backend/tests/test_persistence.py cubre migración, índices, concurrencia, retención y rollback; backend/tests/test_postgres_integration.py cubre migración limpia, concurrencia e índices contra PostgreSQL en CI. No se cambia el contrato HTTP ni se guardan credenciales o datos reales.
Regla de mantenimiento¶
Cada PR debe actualizar la fila afectada y reemplazar “Parcial/Planificado” por evidencia concreta. Si aparece una issue sin requisito, se clasifica como técnica, calidad, infraestructura, documentación o deuda técnica en su body.
Evidencia de ACAD-02¶
ACAD-02 (#39) transforma los artefactos E2E-02/E2E-03 en
escenarios/resultados/acad-02-evidence.json y .md. Cada una de las 50 filas
conserva entrada, esperado, obtenido, severidad, reglas y findings; el bundle
incluye aceptación API/UI, 14/14 críticos, no mutación, timeout controlado,
logs sanitizados y capturas SVG. scripts/build_academic_evidence.py y
backend/tests/test_academic_evidence.py fallan si el bundle se desactualiza,
se pierde la evidencia incompleta o aparecen secretos.
Evidencia de ACAD-01¶
ACAD-01 (#38) entrega documentacion/academica/entregables/01-vision-producto.md,
02-srs-requisitos.md y 03-sad-arquitectura.md. Los documentos relacionan
RF-01..RF-25 y RNF-01..RNF-16 con actores, casos de uso, componentes, pruebas,
diagramas y limitaciones verificables. scripts/check_academic_documents.py y
backend/tests/test_academic_documents.py cubren existencia, enlaces,
metadatos, secciones y ausencia de placeholders; los originales DOCX quedan
conservados como fuente histórica.
Evidencia de ACAD-03¶
ACAD-03 (#40) entrega documentacion/academica/entregables/04-informe-final.md.
El informe consolida el cronograma observado en GitHub, el alcance MVP/V1,
el presupuesto sin cifras no aprobadas y conclusiones con límites explícitos.
scripts/check_academic_final.py y backend/tests/test_academic_final.py
verifican enlaces, ausencia de placeholders y que B/C, VAN y TIR permanezcan
NO CALCULADO mientras no existan costos, beneficios, flujos y tasa aprobados.
Evidencia de M10 inicial¶
- CLOUD-01 (#82) documenta la topología Azure, fixtures sintéticos, escala cero,
límites, costos posibles y ausencia de NoSQL público en
documentacion/base/02-arquitectura/11-arquitectura-azure-demo.md. - CLOUD-02 (#83) añade
infra/azure/main.bicep, parámetros de ejemplo, documentación yscripts/check_azure_iac.py; el jobazure-iaccompila sin desplegar y bloquea secretos, NoSQL público o límites ausentes. - CLOUD-04 (#85) añade
frontend/src/readiness.ts, probes de health/readiness, ventana de 90 segundos, backoff y pruebas frontend; la interfaz no habilita análisis antes de readiness y comunica el arranque en frío. - M10-DOC-01 (#87) mantiene cuatro fuentes Mermaid en
documentacion/diagramas, sus SVG generados yscripts/build_diagrams.py --check; el jobdiagram-checkfalla ante fuentes inválidas, artefactos obsoletos o cambios fuera del generador. - OPS-04 (#90) añade los scripts equivalentes de PowerShell y Bash, el runbook
22-operacion-demo-azure.mdycheck_azure_operations.py; pausa, reanuda y revierte sin borrar PostgreSQL, y exige confirmación para destruir el grupo.
Referencias GitHub reales¶
| Requisito | Issue GitHub principal |
|---|---|
| RF-01 | #34 |
| RF-02 | #3, #8, #12, #16 |
| RF-03 | #3, #9, #13, #17 |
| RF-04 | #4, #26 |
| RF-05–RF-10 | #6, #20 |
| RF-11–RF-13 | #5, #21 |
| RF-14 | #23, #27, #35 |
| RF-15 | #24 |
| RF-16 | #8, #12, #16, #33 |
| RF-17 | #8, #12, #16, #25 |
| RF-18 | #11, #15, #19, #30 |
| RF-19 | #22, #27 |
| RF-20 | #32 |
| RF-21 | #24 |
| RF-22 | #34 |
| RF-23 | #21, #9, #13, #17 |
| RF-24 | #23, #27 |
| RF-25 | #22, #37 |
| RNF-01 | #10, #14, #18, #31 |
| RNF-02 | #5, #20 |
| RNF-03 | #3, #6 |
| RNF-04 | #32, #33, #36 |
| RNF-05 | #7, #30, #39 |
| RNF-06 | #29, #30 |
| RNF-07 | #29, #34 |
| RNF-08 | #21, #31 |
| RNF-09 | #10, #14, #18, #28 |
| RNF-10 | #31, #37 |
| RNF-11–RNF-16 | #34, #35, #36 |