Convenciones de nombrado

Resumen

Este documento establece la convención única de nombrado que se aplica a todos los recursos AWS del proyecto Pedido Sugerido. La convención cubre 14 tipos de recurso, especifica el patrón, ejemplos concretos y los límites de longitud aplicables. Se alinea con dos referencias técnicas:

1. aje-cdk-libs (librería estándar AJE para CDK Python) — define los suffixes abreviados y la lógica de NameBuilder.
2. Recursos ya desplegados en la cuenta dev 832257724409 — los stacks CdkDatalakeIngest* y mlops-* muestran el patrón verbose efectivamente usado en producción.

Decisión clave del proyecto: se adopta el patrón verbose (suffixes legibles como codepipeline, dynamodb, lambda) en lugar del patrón abreviado de aje-cdk-libs (cp, ddb, fn). Razón: el infra ya desplegado por Joseph en AjeDevPsInfraStack usa verbose, y mantener consistencia es más valioso que adoptar un sufijo más corto. La diferencia visual entre aje-dev-ps-config-ddb y aje-dev-ps-configtable-dynamodb no justifica una migración disruptiva.

Patrón general

Todos los recursos del proyecto siguen el patrón:

{enterprise}-{stage}-{project}-{descriptive_name}-{service_suffix}

Restricciones de caracteres aplicables a todos los recursos:

• Solo minúsculas, dígitos y guiones medios (-)
• Sin guiones consecutivos
• Sin guion al inicio ni al final
• Longitud máxima por recurso varía según el tipo (ver tabla)

Tabla por tipo de recurso

Excepciones documentadas

Tres tipos de recurso no siguen el patrón general por restricciones técnicas:

1. S3 Buckets · unicidad global

S3 bucket names son únicos a nivel global de AWS (no por cuenta, no por región). Si el proyecto necesita un bucket con nombre extremadamente común (ej. data), debe incorporar account_id y region al pattern:

aje-dev-ps-832257724409-us-east-2-data-s3

Aplicado solo cuando el descriptive_name no es suficientemente único. En este proyecto, el bucket de CodePipeline artifacts (aje-dev-ps-codepipelinebucket-s3) usa el patrón compacto porque codepipelinebucket ya es lo bastante específico.

2. CloudFormation Stack names

Los stacks deployados por CDK usan PascalCase porque CDK genera nombres de stack desde el construct_id (PascalCase):

• AjeDevPsInfraStack · stack principal
• aje-dev-ps-sagemaker-domain-stack · stack del Domain (creado por separado, sigue el patrón snake-case)

Aceptamos ambos formatos porque coexisten en la cuenta hoy. Para futuros stacks CDK, mantener PascalCase con el patrón Aje{Stage}Ps{Descriptive}Stack (ej. AjeDevPsMLOpsStack, AjeQaPsInfraStack).

3. EventBridge Rules · scoping por país

Las rules de schedule por país incluyen el código del país en descriptive_name (no como token aparte):

• aje-dev-ps-schedulerule-EC-eventbridge
• aje-dev-ps-schedulerule-MX-eventbridge
• aje-dev-ps-schedulerule-PE-eventbridge

El código del país se mantiene en mayúsculas (EC, MX, PE) por trazabilidad con la columna code_country de DynamoDB y los code_country que el Lambda recibe del event.

Tags estándar

Independientemente del nombre, todos los recursos deben llevar la siguiente tabla de tags. La librería aje-cdk-libs aplica estos tags automáticamente vía ResourceBuilder.tag_resource().

Tags opcionales recomendados (no aplicados automáticamente; sugerencia para producción):

• CostCenter · necesario para FinOps a escala
• BusinessProcess · pedido_sugerido (útil cuando convivan múltiples proyectos)
• Country · solo en recursos scoped a un país específico
• DeploymentMethod · CDK o Manual

Validación contra aje-cdk-libs

aje-cdk-libs (rama main del repo DimAje/aje-cdk-libs) define NameBuilder con suffixes abreviados:

Implicación: cuando se incorpore aje-cdk-libs al proyecto en Niveles 2-3, hay dos opciones:

• Opción A (recomendada) — mantener verbose en este proyecto y ajustar la lib internamente con un override del enum Services para el contexto de Pedido Sugerido. Cero cambios a recursos ya desplegados.
• Opción B — migrar gradualmente a los suffixes de aje-cdk-libs. Requiere renombrar los ~20 recursos ya creados (reemplazo + propagación a todos los lugares donde se referencien los ARNs). Costo alto, beneficio mínimo.

Esta decisión queda registrada acá y se confirma con AJE en la Sesión 2.

Validación contra recursos existentes en la cuenta dev

El patrón verbose adoptado se valida contra los recursos aje-dev-ps-* ya desplegados (extraídos de la consola al 15-may-2026):

Conclusión: el patrón verbose adoptado está implementado consistentemente en los recursos productivos del proyecto.

Naming dentro de S3 · prefixes y keys

Los nombres de buckets S3 siguen la convención general. Los prefixes/keys dentro del bucket siguen una convención separada que documentamos acá para evitar ambigüedad.

Bucket aje-dev-analytics-artifacts-s3 (inputs del pipeline)

pedido_sugerido/
└── <pais_lowercase>/                  · ej. ecuador/ · cam/ · mexico/ · peru/
    ├── maestro_productos_<pais>000        *(raw, ;-separated)*
    ├── visitas_<pais>000                  *(raw, ;-separated)*
    ├── ventas_<pais>000                   *(raw, ;-separated)*
    ├── D_stock_<pais>.csv                 *(raw, ,-separated)*
    └── <PAIS>_maestro_productos.csv       *(procesado, output de Limpieza)*

Bucket aje-dev-ps-codepipelinebucket-s3 (artifacts del CodePipeline)

SourceOutput/<execution-id>/    · output del stage Source (GitLab pull)
BuildOutput/<execution-id>/     · output del stage Build (Docker push log)

Generados automáticamente por CodePipeline · no requieren naming manual.

Bucket aje-dev-analytics-artifacts-s3/ps-pipeline/ (outputs del SM Pipeline)

ps-pipeline/<PAIS>/
├── limpieza/                       · output del step Limpieza
│   ├── <PAIS>_maestro_productos.csv
│   ├── <pais>_ventas_manana.parquet
│   ├── mapeo_diccionario.json
│   └── rutas/D_<cod_ruta>_ventas.csv  *(uno por ruta)*
├── modelado/                       · output del step Modelado
│   └── *.csv / *.parquet
└── reglas_negocio/                 · output final
    └── recomendaciones_<fecha>.csv

Próximos pasos

1. Sesión 2 (Mié 20-may) · validar con AJE la decisión de mantener el patrón verbose vs migrar a suffixes abreviados de aje-cdk-libs (decisión registrada como Opción A en este doc).
2. Antes de Desarrollo Nivel 2 · al crear los primeros recursos del Nivel 2 (Feature Store, Model Registry), confirmar que sus nombres siguen el patrón propuesto en la tabla (ej. aje-dev-ps-cliente-features-featurestore, aje-dev-ps-recmodel-EC-sagemaker).
3. CI guard rail · agregar un check en el CodePipeline DeployStack stage que falle si algún recurso CDK no matchea el regex ^aje-{stage}-ps-[a-z0-9-]+(-[a-z]+)?$. Esto previene drift del estándar a futuro.