Estado: NORMATIVO. Documento 01 del proyecto-patron canonico de feature backend de Nebula/Centrica.
Audiencia: equipo de fabrica (desarrolladores backend).
Referencias canonicas del ecosistema: CONSECUTIVOS (catalogo/numeracion,nebula-masters) y EMBARGOS (transaccional,nebula-treasury).
Este proyecto fija un unico camino correcto para construir una feature backend en Nebula, desde la llegada de la Historia Tecnica (HT) hasta su entrega y despliegue. No es una guia opcional: es el contrato de fabrica. Toda feature nueva se construye replicando estos patrones, y toda revision de codigo los exige.
El patron se ancla en dos features de referencia reales, elegidas porque entre las dos cubren el espectro completo de un ERP:
nebula-masters (esquema MASTERS). Es un catalogo estable: autoridad central de numeracion, datos de baja volatilidad, lectura intensiva. Es el arquetipo de lo cacheable.nebula-treasury (esquema treasury). Es transaccional: ciclo de vida con estados de negocio (Activo / Inactivo / Levantado), validacion fuerte, escritura y mutacion frecuente. Es el arquetipo de lo no cacheable.Cualquier feature backend nueva cae en uno de esos dos perfiles o en una combinacion de ambos. Por eso se eligen como referencia: si una feature se parece a un catalogo estable, se mira CONSECUTIVOS; si tiene ciclo de vida transaccional, se mira EMBARGOS.
La arquitectura se basa en dos capas estrictamente separadas. Simappe es el framework (inmutable); Nebula es el negocio (extensible).
com.catcsoft.simappe)Provee las bases que el desarrollador de negocio NO implementa, solo hereda:
| Pieza | Rol |
|---|---|
SimappeService |
Servicio base con CRUD, paginacion y enganche de auditoria. |
SimappeController |
Controlador base; expone el contrato REST estandar. |
SimappeRepository |
Repositorio base (paginación + specs). OJO: el filtro multitenant de Hibernate NO se aplica — el aislamiento de filas se logra con consultas nativas que filtran client_id+company_id+subsidiary_id del token (ver 09 §2). |
*BusinessBaseEntity |
Bases de entidad por tipo de ID: Identity / Sequence / Uuid / Reference·BusinessBaseEntity. |
AbstractLoadModels |
Carga de modelos (lightloader) para construir DTOs sin traer la entidad completa. |
CrudHtppServletRequestComponent |
Interfaz del contrato CRUD sobre el request. |
PageResponseSupport |
Interfaz de soporte de paginacion / page-response. |
| Auditoria | Llena createdBy / createdAt / updatedBy / updatedAt automaticamente. |
Multitenant @ConnectionContext |
Enruta la conexión al esquema del tenant según el JWT (transparente). No filtra filas: el filtrado por tenant es explícito en cada consulta nativa de negocio (ver 09 §2). |
Regla absoluta: Simappe NO se toca. Las bases se heredan, no se modifican.
com.centrica.nebula)Construye los dominios del ERP sobre las bases de Simappe. Repos:
| Repo | Contenido |
|---|---|
nebula-models |
DTOs y records de intercambio. Gobernanza estricta. |
nebula-shared |
WebClients (interfaces @HttpExchange auto-registradas). |
nebula-masters |
Modulo de maestros (incluye CONSECUTIVOS). Esquema MASTERS. |
nebula-treasury |
Modulo de Tesoreria (incluye EMBARGOS). Esquema treasury. |
nebula-accounting-core |
Modulo de Contabilidad. |
El orden de dependencia es models ← shared ← servicios: los DTOs no dependen de nadie, los WebClients dependen de los DTOs, y los servicios de negocio dependen de ambos.
| Eje | CONSECUTIVOS (nebula-masters) |
EMBARGOS (nebula-treasury) |
|---|---|---|
| Naturaleza | Catalogo estable | Transaccional |
| Cacheabilidad | Cacheable (L1/L2) | No cacheable |
| Volatilidad | Baja | Alta (ciclo de vida) |
| Estado de negocio | estado_consecutivo |
estado_embargo (Activo/Inactivo/Levantado) |
| Operaciones tipicas | emitir / reservar / confirmar / anular | crear / leer / editar / levantar / eliminar |
| Esquema | MASTERS |
treasury |
status. status (y los campos de SequenceBusinessBaseEntity) son internos. Para "vigente/activo" usar SIEMPRE el campo de negocio del dominio (estado_embargo, estado_consecutivo, estado_tercero, ...), jamas status.simappe_admin: admin.translation_keys + admin.translations, language_id EN=1 / ES=2).nexus.centricasoluciones.com/repository/centrica/).@Immutable para get-record / page-response: las proyecciones de lectura se sirven desde vista inmutable, no desde la entidad transaccional.AbstractLoadModels), sin arrastrar la entidad completa.nebula-shared se expone en los dos contextos de ejecucion, nunca en uno solo.createdBy/createdAt/updatedBy/updatedAt), heredada de Simappe.application.yml del servicio; este solo lleva bootstrap (name / profiles / config import). La configuracion va al config-server (repo simappeconfig).| Termino | Definicion |
|---|---|
| HT | Historia Tecnica. Especificacion tecnica derivada de una HU (Historia de Usuario), insumo de construccion. |
| HTU | Unidad de Historia Tecnica atomizada en artefactos (pipeline v8.0: 10 artefactos + README + manifiesto). |
| Gate de viabilidad | Control de ENTRADA que audita la calidad/consistencia del insumo HU antes de generar la HT (rubrica 0-100). |
| audit-htu | Gate de SALIDA (TRIPLE-LOCK) sobre la HT ya generada; verifica estructura y aserciones mecanicas. |
| lightloader | Mecanismo (AbstractLoadModels) para construir DTOs por carga selectiva sin traer la entidad completa. |
| Vista @Immutable | Vista JPA de solo lectura para servir proyecciones (get-record / page-response) sin riesgo de mutacion. |
| get-record / page-response | Contrato estandar de lectura unitaria y paginada servido por PageResponseSupport. |
| # | Documento | Contenido |
|---|---|---|
| 00 | 00_INDICE.md | Indice del proyecto-patron. |
| 01 | 01_VISION_Y_PRINCIPIOS.md | Este documento: ecosistema, referencias, reglas de oro, glosario. |
| 02 | 02_DE_LA_HT_AL_DISENO_HTU.md | Desde la llegada de la HT hasta el diseno (HTU): gates, estructura, analisis. |
| 03 | 03_CONSTRUCCION_POR_CAPAS.md | Construccion por capas (entity, repo, service, controller, DTO). |
| 04 | 04_PATRONES_TRANSVERSALES.md | Auditoria, multitenant, i18n, WebClients, caching. |
| 05 | 05_PRUEBAS_Y_CALIDAD.md | Pruebas, casos derivados de CA, calidad. |
| 06 | 06_DATOS_DDL_I18N.md | Datos: DDL Oracle, semillas, i18n ES+EN. |
| 07 | 07_ENTREGA_Y_DEPLOY.md | Entrega y despliegue (Nexus, nodos, healthcheck). |
| 08 | 08_CHECKLIST_CANONICO.md | Checklist canonico de cierre de feature. |
01_VISION_Y_PRINCIPIOS.md — Patron canonico de feature backend — Nebula ERP / Centrica