Proyecto: Nebula ERP — Centrica
Tipo: Patrón arquitectónico normativo (referencia obligatoria para la fábrica)
Referencias canónicas: Consecutivos (nebula-masters) y Embargos (nebula-treasury)
Este proyecto define cómo se construye una feature de backend en Nebula, de principio a fin: desde que llega la Historia Técnica (HT) hasta que el contenedor queda desplegado y verificado. No es teoría: cada patrón se muestra con código real de dos features ya entregadas y validadas en dev —consecutivos (catálogo/numeración, cacheable) y embargos (transaccional)— elegidas porque entre las dos ejercitan todos los patrones del ecosistema.
Reemplaza al flujo previo FLUJO_DESARROLLO_NEBULA, que usaba un ejemplo genérico inventado (Tercero/CentricaModel) y no reflejaba los patrones reales (vista @Immutable, PageResponseSupport, lightloader, WebClients de nebula-shared, @Cacheable selectivo, auditoría, Javadoc 100%, Flyway-manual).
Audiencia: desarrolladores de la fábrica. Es la fuente de verdad; ante duda, manda este patrón.
| # | Documento | Cubre |
|---|---|---|
| 0 | Este índice | Visión end-to-end + veredicto del patrón previo |
| 1 | Visión y Principios | Ecosistema Simappe/Nebula, las dos referencias, reglas de oro, glosario |
| 2 | De la HT al Diseño (HTU) | Gate de viabilidad, HTU v8.0, audit-htu, cómo se analiza la HT |
| 3 | Construcción por Capas | Código real por capa (models→…→controller) + diagramas |
| 4 | Patrones Transversales | Estado de negocio, auditoría, i18n, @Cacheable, Kafka, Javadoc |
| 5 | Pruebas y Calidad | TestCases→tests, JaCoCo >80%, audit-htu |
| 6 | Datos: DDL e i18n | DDL Oracle, i18n postgres, Flyway-manual |
| 7 | Entrega y Deploy | Gitflow, Jenkins, registry/nodos, verificación runtime |
| 8 | Checklist Canónico | Definition of Done + evaluación del patrón previo |
| 9 | Reglas Explícitas | Reglas normativas literales validadas contra código: herencia por capa, multitenant nativo, estados+enum, DTO/Record/LightLoader, contrato front, DDL, endpoints, Javadoc/SemVer, cierre de alcance |
| 10 | Flujos y Consumos de API | Integración entre módulos: provider (Consecutivos), transporte (nebula-shared WebClients blocking+reactive), consumer (Embargos) + flujo e2e validado |
| 11 | Antipatrones Detectados | Catálogo de antipatrones reales del ecosistema con su corrección canónica (tenant, status, persistencia, contrato front, pruebas/i18n) + la lección de validación en vivo |
Orden de lectura: 01 → 02 → 03 → 04 → 05 → 06 → 07 → 08; 09 (reglas normativas), 10 (consumos de API) y 11 (antipatrones) son referencia transversal de obligado cumplimiento.
Alineación (jun-2026): el patrón está alineado al barrido multitenant nativo — toda consulta de negocio es
@Query(nativeQuery=true)filtrandoclient_id+company_id+subsidiary_iddel token (el@Filterde Hibernate no se aplica). Esto incluye la paginación:get-record/page-response/pagese resuelven conNativeTenantPaginatorde SimappeCommons (que inyecta SIEMPRE el tenant), no con el default dePageResponseSupportsobrefindAll(Specification, Pageable), que no aísla tenant (ver AP-1.5 y 09 §2). Las respuestas de lectura exponen además etiquetas descriptivas i18n de enums/códigos como campos aditivos*Nombre(ver 04 §3), y el mapper implementaNebulaEnrichedMapper. Referencias vivas:nebula-masters1.3.0,nebula-treasury1.2.0 (sobre SimappeCommons 4.13.0,nebula-models0.4.4). Detalle en 09.
El flujo previo sirve como esqueleto (recibir HT → capas → tests → PR), pero quedó desactualizado. Resumen (detalle en 08_CHECKLIST_CANONICO):
| Aspecto | Patrón previo | Patrón canónico | Acción |
|---|---|---|---|
| Ejemplo | Tercero genérico inventado |
Código real consecutivos + embargos | Actualizar |
| Biblioteca de modelos | CentricaModel |
nebula-models |
Actualizar |
| get-record / page-response | No documentado | Vista @Immutable + PageResponseSupport |
Agregar |
| WebClients cross-module | No documentado | nebula-shared blocking + reactivo |
Agregar |
@Cacheable |
No documentado | Selectivo (catálogo sí, transaccional no) | Agregar |
| Kafka | No documentado | Criterio evento-de-dominio + audit-log | Agregar |
| Pruebas | "cobertura >80%" sin detalle | JaCoCo + mapeo TestCases + audit-htu | Actualizar |
| Javadoc | No exigido | 100% (criterio de aceptación) | Agregar |
| Datos | No menciona DDL/Flyway | DDL + i18n manual (Flyway no corre) | Agregar |
| HTU / viabilidad | No integrado | Gate de viabilidad + HTU v8.0 + audit-htu | Agregar |
| Versión | Fecha | Autor | Descripción |
|---|---|---|---|
| 1.0.0 | 2026-06-11 | Carlos Torres | Creación del proyecto-patrón canónico (referencias: consecutivos + embargos) |
| 1.1.0 | 2026-06-24 | Carlos Torres | Alineación de paginación a NativeTenantPaginator (cierre de fuga de tenant del default de commons, AP-1.5), mapper NebulaEnrichedMapper + aplanado descriptivo i18n (*Nombre). Referencias: nebula-masters 1.3.0, nebula-treasury 1.2.0 (Tipos Consecutivos, Consecutivos, Embargos) |