Resumen
Este documento es el contrato técnico del proyecto. Convierte cada requerimiento de la propuesta v2 en un criterio de aceptación testeable, le asigna un componente concreto, un método de validación, un owner y la Validación Técnica donde se valida. Es el insumo principal de:
- Las Validaciones Técnicas (VT1 · VT2 · VT3) · cada VT revisa el RTM como checklist
- El control de scope · cualquier requerimiento no listado acá es change order
- La trazabilidad del proyecto · evidencia auditable de qué se construyó y por qué
Estructura: el RTM cubre los 13 requerimientos de la propuesta v2 (4 del Nivel 1, 5 del Nivel 2, 4 del Nivel 3). La Definition of Done por Nivel es una checklist de cierre que sintetiza qué significa "nivel terminado".
Estructura de la matriz
Una fila por requerimiento con las siguientes columnas:
| Columna |
Significado |
| ID |
Identificador único · formato N{nivel}.R{req} (ej. N1.R1) |
| Descripción |
Texto del requerimiento citado de la propuesta v2 |
| Componente |
Pieza técnica que lo implementa (ver DOC-AF-05) |
| Criterio de aceptación |
Condición testeable · concreta · medible (no "el sistema funciona") |
| Método de validación |
Cómo se prueba (test automatizado · inspección manual · demo · revisión de logs) |
| Owner |
Tuxpas o AJE |
| VT donde se valida |
VT1 (sem 4) · VT2 (sem 8) · VT3 (sem 10) |
| Status |
Pending → In progress → Done (al iniciar el AF todos están Pending) |
RTM · Nivel 1 · Automatización
Cubre los 4 requerimientos del Nivel 1 según la propuesta v2.
N1.R1 · Pipeline parametrizado por país
| Campo |
Valor |
| Descripción |
"Un solo pipeline en SageMaker donde el país es un parámetro" |
| Componente |
aje-dev-ps-pipeline-sagemaker (SM Pipeline) + scripts canónicos cicd/src/PS_MP_*.py |
| Criterio de aceptación |
El mismo SM Pipeline ejecuta los 7 países (CR, EC, GT, MX, NI, PA, PE) sin cambios al código del pipeline, recibiendo solo el parámetro code_country distinto. Outputs por país segregados en s3://aje-dev-analytics-artifacts-s3/ps-pipeline/<PAIS>/. |
| Método de validación |
Test automatizado: ejecutar pipeline para EC y MX con mismo código fuente · verificar outputs presentes en ambos prefixes S3 |
| Owner |
Tuxpas |
| Valida en |
VT1 |
| Status |
Pending (refactor parcialmente hecho; queda completar parametrización de configs especiales como pe_special) |
N1.R2 · Orquestación diaria automática
| Campo |
Valor |
| Descripción |
"Ejecución L-S por país/horario (EventBridge + Lambda)" |
| Componente |
aje-dev-ps-schedulerule-{CR/EC/GT/MX/NI/PA/PE}-eventbridge + aje-dev-ps-triggerfunction-lambda |
| Criterio de aceptación |
Los 7 schedules disparan automáticamente L-V (L-S si AJE lo pide), escalonados cada 10 min (10:00 → 11:00 UTC). Cada disparo invoca el Lambda, que ejecuta sagemaker:StartPipelineExecution con el code_country correcto. |
| Método de validación |
Revisión de logs de CloudWatch durante 3 días consecutivos · 21 ejecuciones esperadas (7 países × 3 días) · contar que todas se dispararon en su ventana de 10 min |
| Owner |
Tuxpas |
| Valida en |
VT1 |
| Status |
Pending (schedules ya configurados, validación en VT) |
N1.R3 · Monitoreo operativo
| Campo |
Valor |
| Descripción |
"Dashboard por país. Alertas por email en <5 min ante fallos o duraciones anómalas (CloudWatch + SNS)" |
| Componente |
aje-dev-ps-monitoringdashboard-cloudwatch + 2 CloudWatch Alarms + aje-dev-ps-alert-topic-sns |
| Criterio de aceptación |
(a) Dashboard CloudWatch muestra ejecuciones por país en las últimas 24h con semáforo verde/rojo. (b) Cuando un step falla, llega email a los suscriptores del SNS topic en <5 min (medido desde el end time del ProcessingJob). |
| Método de validación |
Demo en sesión de VT: provocar fallo en un step (ej. comentar línea crítica del script) · cronometrar tiempo hasta llegada del email. Inspección del dashboard. |
| Owner |
Tuxpas |
| Valida en |
VT1 |
| Status |
Pending (monitoring catalog detallado en DOC-AF-08) |
N1.R4 · Código y datos versionados
| Campo |
Valor |
| Descripción |
"Scripts en Docker con versionado semántico. Datos de entrada versionados para reproducibilidad y rollback (ECR + S3 Versioning)" |
| Componente |
ECR repos aje-dev-ps-{processing,spark} con tags semánticos + S3 Versioning habilitado en buckets críticos |
| Criterio de aceptación |
(a) Cada push a main del repo GitLab genera una imagen Docker tagueada con SHA del commit y con tag latest. (b) S3 Versioning habilitado en aje-dev-analytics-artifacts-s3/ps-pipeline/. (c) Demo de rollback: deployar versión anterior de Docker image y validar que el pipeline corre con esa versión. |
| Método de validación |
(a) aws ecr describe-images muestra al menos 3 versiones taggeadas. (b) aws s3api get-bucket-versioning retorna Enabled. (c) Demo de rollback ejecutado en VT1. |
| Owner |
Tuxpas |
| Valida en |
VT1 |
| Status |
Pending (versionado existe a nivel de tag latest; falta agregar tag con SHA) |
RTM · Nivel 2 · Gestión del modelo
Cubre los 5 requerimientos del Nivel 2.
N2.R1 · Model Registry por país
| Campo |
Valor |
| Descripción |
"Cada modelo registrado con métricas, datos y versión de código" |
| Componente |
SageMaker Model Package Group × 7 (aje-dev-ps-recmodel-{pais}-sagemaker) + DynamoDB aje-dev-ps-modelmetrics-dynamodb |
| Criterio de aceptación |
(a) Existe un Model Package Group por país. (b) Cada Model Package incluye: model artifact en S3, métricas (NDCG@10, Precision@K, Coverage) en metadata, commit SHA del código de entrenamiento, fecha de training data. (c) Promoción a Approved cambia el modelo activo en el pipeline de inferencia. |
| Método de validación |
(a) aws sagemaker list-model-package-groups retorna 7 groups con prefijo aje-dev-ps-recmodel-. (b) aws sagemaker describe-model-package muestra metadata completa para un modelo de muestra. (c) Demo: cambiar approval status de un modelo y validar que la siguiente inferencia usa el nuevo. |
| Owner |
Tuxpas |
| Valida en |
VT2 |
| Status |
Pending |
N2.R2 · Feature Store
| Campo |
Valor |
| Descripción |
"Features centralizadas y consistentes entre 7 países. Reutilizables para futuros modelos" |
| Componente |
SageMaker Feature Store · Feature Group aje-dev-ps-cliente-features-featurestore (scope acordado en DT-N2) |
| Criterio de aceptación |
(a) Existe al menos 1 Feature Group operativo en SageMaker Feature Store con features de cliente (frecuencia, recencia, ticket_promedio, categoria_principal). (b) Las features se computan diariamente en el pipeline de entrenamiento y se persisten offline en S3. (c) El pipeline de inferencia las lee del Feature Store, no de archivos sueltos. |
| Método de validación |
(a) aws sagemaker describe-feature-group retorna el group con schema esperado. (b) Demo: ejecutar aws sagemaker-featurestore-runtime y obtener record para un id_cliente de muestra. (c) Inspección del pipeline de inferencia: confirmar que lee de Feature Store. |
| Owner |
Tuxpas |
| Valida en |
VT2 |
| Status |
Pending (scope final se acuerda en Touchpoint N2) |
N2.R3 · Métricas de calidad y Model Monitor
| Campo |
Valor |
| Descripción |
"Métricas específicas (Precision@K, NDCG@K, Coverage) y umbrales se definen en el análisis funcional con baseline del modelo actual" + "Calidad post-entrenamiento y drift post-deploy como mecanismos separados (Model Monitor)" |
| Componente |
Código de evaluación en cicd/src/PS_MP_2_modelado.py + SageMaker Model Monitor schedule × 7 (uno por país) |
| Criterio de aceptación |
(a) Cada pipeline de entrenamiento computa NDCG@10, Precision@K (K=5, K=10) y Coverage contra holdout temporal de 30 días. (b) Las métricas se persisten en la metadata del Model Package y en DynamoDB. (c) Model Monitor con baseline desde el último Approved · genera reporte diario en s3://aje-dev-analytics-artifacts-s3/ps-pipeline/<PAIS>/drift_reports/. (d) Si Model Monitor detecta drift, dispara CloudWatch alarm. |
| Método de validación |
(a) Inspección del Model Package · campo ModelMetrics. (b) Query a DynamoDB · al menos 1 row por modelo registrado. (c) Inspección de S3 · reportes diarios presentes. (d) Demo: simular drift en input y validar que la alarm se dispara. |
| Owner |
Tuxpas |
| Valida en |
VT2 |
| Status |
Pending (definiciones en DOC-AF-04; implementación en sem 5-6) |
N2.R4 · Pipelines train + inference separados
| Campo |
Valor |
| Descripción |
"Pipeline de entrenamiento (semanal) + Pipeline de inferencia (diario): Separados e independientes" |
| Componente |
aje-dev-ps-trainpipeline-sagemaker + aje-dev-ps-infpipeline-sagemaker |
| Criterio de aceptación |
(a) Existen 2 SM Pipelines distintos. (b) El de entrenamiento corre semanalmente (domingos por defecto) y termina en el step Register del Model Registry. (c) El de inferencia corre diariamente L-V, carga el último modelo Approved del Registry y produce recomendaciones. (d) Si el pipeline de inferencia falla, el de entrenamiento no se ve afectado. |
| Método de validación |
(a) aws sagemaker list-pipelines retorna 2 pipelines con prefijos trainpipeline- e infpipeline-. (b) Inspección de definición · steps distintos. (c) Demo: detener manualmente el pipeline de inferencia · ejecutar pipeline de entrenamiento · validar que termina OK. |
| Owner |
Tuxpas |
| Valida en |
VT2 |
| Status |
Pending (actualmente hay un solo pipeline mezclado) |
N2.R5 · CI/CD con build, tests, staging, aprobación
| Campo |
Valor |
| Descripción |
"CodePipeline o GitHub Actions: De código a producción con build, tests, staging y aprobación manual antes del deploy" |
| Componente |
aje-dev-ps-pipeline-codepipeline (ya existe) enriquecido con stages Test, Staging, Approval, Prod |
| Criterio de aceptación |
(a) Cada push a main dispara CodePipeline. (b) Stages secuenciales: Source → DeployStack → Build → Test → Staging → ManualApproval → Deploy. (c) Stage Test ejecuta tests unitarios + integration tests · falla detiene el pipeline. (d) ManualApproval requiere clic humano antes del deploy a prod. |
| Método de validación |
(a) aws codepipeline get-pipeline retorna 7 stages. (b) Demo: introducir test failure intencional · validar que stage Test falla y bloquea el pipeline. (c) Demo: aprobar manualmente desde consola. |
| Owner |
Tuxpas |
| Valida en |
VT2 |
| Status |
Pending (actualmente 4 stages, faltan Test/Staging/Approval) |
RTM · Nivel 3 · Automatización completa
Cubre los 4 requerimientos del Nivel 3.
N3.R1 · Reentrenamiento automático por drift
| Campo |
Valor |
| Descripción |
"Drift detectado → reentrenamiento → staging → deploy solo si supera al modelo actual" |
| Componente |
EventBridge rules de drift × 7 + aje-dev-ps-retraintrigger-lambda + lógica de promoción condicionada |
| Criterio de aceptación |
(a) Cuando Model Monitor detecta data drift (PSI > 0.25 en 2+ features clave), CloudWatch alarm dispara EventBridge rule → invoca Lambda de retrain → Lambda ejecuta el pipeline de entrenamiento. (b) El modelo resultante pasa por los 3 gates de aprobación (DOC-AF-04). (c) Si pasa, se deploya automáticamente. Si no, se marca Rejected y queda en el Registry. (d) Cooldown de 14 días entre retrains. |
| Método de validación |
Demo en VT3: simular drift inyectando datos sintéticos · validar que se dispara el retraining · inspeccionar el Model Registry tras el flujo. |
| Owner |
Tuxpas |
| Valida en |
VT3 |
| Status |
Pending |
N3.R2 · Multi-modelo por país
| Campo |
Valor |
| Descripción |
"Grid de hiper parámetros ALS. Selección automática por mejor precisión (SageMaker Experiments)" |
| Componente |
SageMaker Experiments + tuning job + lógica de selección por NDCG@10 |
| Criterio de aceptación |
(a) En al menos 2 países piloto (según propuesta v2 textual: "2 países con modelos independientes"), el entrenamiento ejecuta un grid de al menos 12 combinaciones de hiperparámetros (rank × regParam × alpha). (b) La selección automática toma el modelo con mejor NDCG@10. (c) El modelo seleccionado entra al Registry con metadata de los hiperparámetros usados. |
| Método de validación |
(a) Inspección del Experiment en consola SageMaker · ver 12+ trials registrados. (b) Inspección del Model Package elegido · campo de hiperparámetros presente y coherente. |
| Owner |
Tuxpas |
| Valida en |
VT3 |
| Status |
Pending |
N3.R3 · Gobernanza y auditoría
| Campo |
Valor |
| Descripción |
"Trazabilidad completa: quién aprobó, qué versión, con qué datos (Model Cards + CloudTrail)" |
| Componente |
SageMaker Model Cards + aje-dev-ps-audittrail-cloudtrail |
| Criterio de aceptación |
(a) Cada Model Package registrado tiene Model Card adjunta con campos mínimos: model owner, intended use, training data summary, métricas, limitations, ethical considerations. (b) CloudTrail capturando todos los eventos del proyecto en aje-dev-ps-audittrailbucket-s3. (c) Demo: dado un modelo aprobado, recuperar de CloudTrail el evento UpdateModelPackage con el principal que lo aprobó y la fecha. |
| Método de validación |
(a) aws sagemaker describe-model-card retorna Model Card completa. (b) aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=UpdateModelPackage retorna eventos. (c) Demo de "audit walkthrough" en consola SageMaker. |
| Owner |
Tuxpas |
| Valida en |
VT3 |
| Status |
Pending |
N3.R4 · Plantilla replicable
| Campo |
Valor |
| Descripción |
"IaC (CDK/CloudFormation): IaC para lanzar nuevos modelos de AJE en días, no semanas" |
| Componente |
aje-analytics-model-pedido-sugerido/infra/ · stack CDK parametrizable |
| Criterio de aceptación |
(a) El stack CDK acepta como context parameter stage (dev/qa/prod) y una lista de países habilitados. (b) Un cdk deploy con stage distinto y mismo código genera un ambiente equivalente. (c) Demo: deployar un "stage de prueba" (stage=test-replicable) y validar que aparecen recursos paralelos sin conflicto. (d) Documentación: README en el repo explica paso a paso "Cómo lanzar un nuevo modelo replicando esta plantilla". |
| Método de validación |
Demo de deploy a stage de prueba + revisión del README. |
| Owner |
Tuxpas |
| Valida en |
VT3 |
| Status |
Pending |
Definition of Done · Nivel 1
El Nivel 1 se considera DONE cuando todos los siguientes criterios se cumplen y son verificados en VT1:
- ☐ Pipeline corre los 7 países L-V automáticamente, escalonado, sin intervención manual durante 3 días consecutivos.
- ☐ Si un país falla, los otros 6 siguen ejecutándose normalmente (aislamiento).
- ☐ Alertas SNS llegan a los suscriptores en <5 min desde el momento del fallo.
- ☐ Dashboard CloudWatch funcional con semáforo verde/rojo por país y métricas de duración.
- ☐ Imágenes Docker en ECR tageadas con SHA del commit + tag
latest (versionado semántico).
- ☐ S3 Versioning habilitado en buckets críticos · demo de rollback de Docker probada.
- ☐ Tests automatizados ejecutándose en cada push a
main · cobertura mínima de schema y volumen del output.
- ☐ Runbooks 1 y 2 entregados (operación diaria · respuesta a alertas).
- ☐ Acta de Validación Técnica 1 firmada por AJE dentro de 5 días hábiles post-VT1.
Bloqueador conocido (dependencia externa): AJE debe garantizar que los datos de los 7 países llegan al bucket dev. Si MX y PE no se cargan, criterio #1 no se puede cumplir (DOC-AF-02 riesgo #1).
Definition of Done · Nivel 2
El Nivel 2 se considera DONE cuando todos los siguientes criterios se cumplen y son verificados en VT2:
- ☐ Pipeline de entrenamiento (semanal) y pipeline de inferencia (diario) ejecutándose separados e independientes.
- ☐ Modelos registrados en Model Registry con métricas NDCG@10, Precision@K, Coverage en metadata · 7 países cubiertos.
- ☐ Al menos 1 Feature Group operativo (cliente o producto, según acordado en DT-N2) con ingestion diaria activa.
- ☐ Model Monitor configurado para los 7 países con baseline definido · genera reporte de drift diario en S3.
- ☐ CI/CD con stages Source → DeployStack → Build → Test → Staging → ManualApproval → Deploy.
- ☐ Stage Test bloquea el deploy si los tests unitarios o de integración fallan (demo: introducir test failure y validar).
- ☐ Workflow de aprobación humana del modelo · notificación SNS al analista · clic en consola → cambio a Approved → deploy al pipeline de inferencia.
- ☐ Runbooks 3 y 4 entregados (promoción manual de modelo · agregar feature al Feature Store).
- ☐ Acta de Validación Técnica 2 firmada por AJE dentro de 5 días hábiles post-VT2.
Definition of Done · Nivel 3
El Nivel 3 se considera DONE cuando todos los siguientes criterios se cumplen y son verificados en VT3:
- ☐ Demo de reentrenamiento por drift simulado end-to-end: inyectar drift sintético → Model Monitor lo detecta → EventBridge dispara Lambda → pipeline de entrenamiento corre → modelo nuevo pasa Gates 1+2 → deploy automático.
- ☐ Al menos 2 países piloto con grid de hiperparámetros (12+ trials) ejecutado · modelo elegido por NDCG@10.
- ☐ Cooldown de 14 días entre retrains funcionando · validar con segundo intento de drift dentro de la ventana.
- ☐ Model Cards completas para todos los modelos en el Registry (campos mínimos: owner, intended use, training data, métricas, limitations).
- ☐ CloudTrail capturando eventos del proyecto · demo de "audit walkthrough" para un modelo aprobado.
- ☐ Stack CDK parametrizable por
stage · demo de deploy a stage de prueba (o documentación equivalente si AJE no quiere recursos extra).
- ☐ Documentación completa entregada · arquitectura · manual de usuario · 6 runbooks (1-6).
- ☐ 6 sesiones de capacitación a AJE ejecutadas · agenda según DOC-AF-09.
- ☐ Criterios "AJE autónomo" verificados (DOC-AF-09): AJE ejecuta corrida manual sin asistencia · AJE responde a alerta sin asistencia · AJE aprueba modelo sin asistencia.
- ☐ Acta de Validación Técnica 3 + Acta de Entrega firmadas por AJE dentro de 5 días hábiles post-VT3.
Cláusula de change order
Cualquier requerimiento o capacidad no listada en este RTM que AJE solicite durante el Desarrollo se considera fuera del alcance acordado y dispara la cláusula de change order de la propuesta v2 ("modificaciones a los requerimientos establecidos durante la fase de implementación... podrían implicar ajustes en los plazos de entrega y en los costos asociados").
Esto incluye, pero no se limita a:
- Soporte de un país adicional fuera de los 7 listados
- Migración de algún componente a
VpcOnly (si no estaba previsto)
- Endpoint persistente en lugar de batch transform
- Multi-modelo en 7 países (en lugar de 2 piloto) en VT3
- Integraciones con sistemas externos (ej. envío de recomendaciones a Salesforce) no contempladas
- Métricas de modelo distintas a las acordadas en DOC-AF-04
- Aprobaciones humanas adicionales o workflows custom de aprobación
Próximos pasos
- Sesión 2 (Mié 20-may) · revisar el RTM línea por línea con AJE. Cada fila debe ser confirmada o ajustada antes del cierre del AF. Los criterios de aceptación son la fuente de verdad que evita ambigüedades en las VT.
- Status tracking · al iniciar el Desarrollo Nivel 1 (sem 2), el squad mueve los status de Pending → In progress → Done a medida que avanza. Visible para AJE en revisiones semanales.
- DoD checklists · al final de cada Nivel, el squad confirma que cada checkbox se cumple antes de solicitar la VT. AJE valida los checkboxes en la VT y firma el acta correspondiente.
- Change order tracking · si surge una solicitud de AJE fuera del RTM durante el Desarrollo, se documenta en un anexo a este documento y se evalúa impacto antes de aceptar.