Version: 1.0
Fecha: 16 de Marzo, 2026
Arquitecto: Carlos Alberto Torres Camargo
Esta seccion define que es Nebula, como esta construido y bajo que reglas opera. Es el punto de partida obligatorio para cualquier persona que se incorpore al proyecto. Los documentos siguen un hilo que va desde la vision estrategica del sistema hasta las especificaciones tecnicas de cada microservicio, pasando por los patrones de diseno y los estandares de codificacion.
Audiencia: Todo el equipo tecnico — arquitectos, desarrolladores backend y frontend, QA, DevOps.
Manifiesto → Arquitectura General → Modelo Multitenant → Inventario de Servicios → Documento Tecnico de Servicios → Patrones → Estandares → Disenos especificos.
| # | Documento | Descripcion |
|---|---|---|
| 1 | Manifiesto de Arquitectura | Punto de partida. Vision general, principios arquitectonicos y hoja de ruta del proyecto |
| 2 | Arquitectura Software Nebula | Arquitectura completa del sistema: capas, componentes, integraciones externas y diagramas |
| 3 | Modelo Multitenant | Estrategia de multitenancy basada en base de datos — decision arquitectonica fundamental |
| 4 | Inventario Global de Servicios | Catalogo de todos los microservicios organizados por dominio de negocio |
| 5 | Guia de Uso del Inventario | Como interpretar y utilizar el inventario de servicios en el dia a dia |
| 6 | Documento Tecnico de Servicios | Especificacion tecnica exhaustiva de cada microservicio: endpoints, modelos, configuraciones y dependencias |
| 7 | Patron Backend | Patron de arquitectura para microservicios backend (capas, estructura de paquetes, convenciones) |
| 8 | Patron Frontend | Patron de arquitectura para aplicaciones frontend Angular (modulos, componentes, servicios) |
| 9 | Estandares de Desarrollo | Convenciones de codificacion, nombrado, estructura de commits y reglas del equipo |
| 10 | Estandares de Calidad y Operacion | Criterios de calidad, metricas de operacion y checklist de validacion |
| 11 | Guia Visual de Implementacion | Diagramas y flujos visuales que complementan los documentos anteriores |
| 12 | Diseno Log y Auditoria MongoDB | Diseno del sistema de logs y auditoria centralizada con MongoDB |
| 13 | Diseno Reporteria BI Multitenant | Arquitectura de reporteria y Business Intelligence con aislamiento multitenant |
| 14 | Estrategia Carga de Maestros | Estrategia para la migracion y carga inicial de datos maestros en nuevos tenants |
| 15 | Arquitectura Frontend Nebula | Nx Monorepo + Component Library separada (@nebula/ui-kit). 2 repos independientes, boundary enforcement, patrones Angular 21 |
| 16 | Reglas de Desarrollo de Servicios | Reglas obligatorias para desarrollo backend y frontend: naming, estructura, validaciones |
| 17 | Estandares Mapeo DTO-Entity | Convenciones para mapeo entre DTOs y entidades JPA |
| 18 | Diseno Nebula Common/Shared | Librerias compartidas entre microservicios: nebula-commons, nebula-models, nebula-shared. Incluye tabla de decision "que va donde", anatomia de cada library y anti-patrones observados (v2.0) |
| 19 | Matriz Roles y Permisos Core | Control de acceso basado en roles (RBAC) y permisos por modulo |
| 20 | Consulta Documentacion OpenAPI | Procedimiento oficial para obtener Bearer Token y consultar el contrato OpenAPI/Swagger de los servicios Nebula |
| 21 | ADR-001 Flat Record | Procedimiento para implementar los flat record |
| 22 | ADR-002 Division Libraries Nebula | Decision arquitectonica sobre separacion de responsabilidades entre nebula-commons, nebula-models, nebula-shared y propuesta de enforcement con nebula-arch-rules (ArchUnit) |
| 23 | ADR-003 Politica Entrega QA | Decision arquitectonica sobre el flujo formal de entrega a QA: 8 fases con gates explicitos, rol QA Lead formalizado, artefactos obligatorios (QA_HANDOFF, QA_EXECUTION_REPORT, QA_CLOSURE), SLAs y criterios de aprobacion |
| 24 | Patron Canonico de Feature Backend | Proyecto-patron de referencia OBLIGATORIO: como se construye una feature de la HT al deploy, con codigo real de consecutivos y embargos (gate viabilidad + HTU, construccion por capas, transversales, pruebas/JaCoCo, datos DDL/i18n, entrega y deploy). Reemplaza el flujo previo con ejemplo generico |
| 25 | Catalogo de Acciones y Roles | Fuente de verdad del modelo de autorizacion: 26 acciones canonicas + 26 roles del ERP financiero (publico/privado) + perfiles role_action + matrices rol x accion / rol x modulo. Modelo de dos contextos (accesos en JWT / comportamientos resueltos por menu-with-actions) |
| 26 | ADR-013 Contrato date() Arquetipo Parametros | Decision arquitectonica sobre el contrato date() del arquetipo componente de parametros (regla dinamica SAR PARAM-CTX): fecha operativa persistida encapsulada en record (generico F con record por componente en nebula-models), implementacion de referencia en parametros de facturacion (GET /date) |
| 27 | Patron Canonico de Importacion de Archivos | Patron-referencia de la capa generica de importacion de SimappeCommons (TEXT/CSV/XLSX/XML/JSON): dos ejes QUE x COMO, carga de lanzamiento ImportControl (validacion completa / al primer error / fluida; abortar / parcial), contrato del dev (validate + persist), endpoint estandar /import, estructura de respuesta unica y bateria de consumo 1:1 (exito, carga parcial, formato no soportado). Implementacion de referencia: Dependencias en nebula-accounting-core |
| 28 | Patron Canonico de Exportacion de Archivos | Inverso del item 27: capa generica de exportacion en streaming de SimappeCommons (CSV/XLSX/TEXT/JSON/XML; PDF fuera del cliente Nebula). Reutiliza el page-response (nativo + tenant) como ExportBatchSupplier; columnas por @ExportColumn, opcional desde SimappeCommons 4.37.0 (sin anotaciones el record se exporta completo; anotar elige columnas, titulo y orden); contrato ExportSupport; endpoint estandar /export SINCRONO en el hilo del request (nunca StreamingResponseBody, que pierde el tenant) y param formato (no format, que colisiona con la content-negotiation). Bateria de consumo validada en dev. Implementacion de referencia: Moneda y Tasa de Cambio (HT_CON_017) en nebula-accounting-core; Dependencias y Tipos de Asiento como previas |
| 29 | ADR-014 Estrategia de Pruebas E2E Frontend | Decision arquitectonica sobre las pruebas E2E con Playwright en nebula-erp: dos variantes por modulo (*-mock.spec.ts que corre SIEMPRE en CI sin backend ni credenciales, y *-api-dev.spec.ts como evidencia de integracion para QA). Documenta los cuatro obstaculos del ERP que no son evidentes: sesion sembrada en localStorage (el guard no valida firma), el renderizado por pestaña que nace del menu (navegar por URL no monta la pantalla), la reescritura de modulo por selectedRoute y el catch-all que debe responder arrays. Implementacion de referencia: Embargos y Consecutivos (MR !198), Monedas y Tasas de Cambio (MR !201). Consigna ademas que la deuda de pruebas no venia de falta de ejecucion sino de que en angularNxPipeline las etapas de test/lint/e2e son NO bloqueantes por defecto |
| 30 | ADR-015 Mapeo de errores | Mapeo de errores remotos a SimappeException vía SimappeExceptionMapper |
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.9.1 | 2026-08-14 | Carlos Torres | Correccion del diagnostico del ADR-014. La version previa atribuia la deuda a que .gitlab-ci.yml limitaba el job a main y merge requests. Es erroneo: el CI/CD de nebula-erp es Jenkins (angularNxPipeline), que si construye develop y despliega a dev. La causa real son los defaults del patron --testsBlocking, lintBlocking y e2eBlocking en false--: las pruebas corrian, fallaban, imprimian un WARN y el pipeline seguia hasta desplegar. El .gitlab-ci.yml es residuo del andamiaje de Nx, sin runners, y no debe tomarse como señal. |
| 1.9.0 | 2026-08-14 | Carlos Torres | Incorporacion del ADR-014 Estrategia de Pruebas E2E del Frontend (item 29): dos variantes por modulo (mock en CI + api real como evidencia), soporte compartido sesion-e2e.ts y los cuatro obstaculos documentados del ERP. Origen: ningun E2E del repositorio ejercia una pantalla en el pipeline. |
| 1.8.0 | 2026-07-25 | Carlos Torres | Incorporacion del Patron Canonico de Exportacion de Archivos (item 28): capa generica de exportacion en streaming de SimappeCommons, reuso del page-response, @ExportColumn/ExportSupport, endpoint /export sincrono, y bateria de consumo (csv/xlsx/text/json/xml + pdf->400) validada en dev. Inverso del item 27. |
| 1.7.0 | 2026-07-24 | Carlos Torres | Incorporacion del Patron Canonico de Importacion de Archivos (item 27): capa generica de SimappeCommons con ImportControl, AbstractImportProcess (validate/persist), endpoint /import, respuesta unica y bateria de consumo validada en dev. |
| 1.6.0 | 2026-07-17 | Carlos Torres | Incorporacion del ADR-013 Contrato date() del arquetipo componente de parametros (item 26): fecha operativa encapsulada en record, generico F en ContextAdminParam, referencia en parametros de facturacion. |
| 1.5.0 | 2026-07-01 | Carlos Torres | Incorporacion del Catalogo de Acciones y Roles (item 25): 26 acciones + 26 roles + perfiles de accion. Alineacion de la Matriz Roles y Permisos Core (item 19) con el modelo implementado (Flujo 2, JWT sin acciones). |
| 1.4.0 | 2026-05-11 | Carlos Torres | Incorporacion del ADR-003 Politica Entrega QA (item 23). Formaliza el flujo de entrega a QA en 8 fases con gates A-G y artefactos obligatorios. |
| 1.3.0 | 2026-05-11 | Carlos Torres | Reescritura del documento de Diseno Nebula Common/Shared a v2.0 (item 18) e incorporacion del ADR-002 sobre division de libraries Nebula (item 22). |
| 1.2.0 | 2026-04-24 | Vanessa Luna | Se agrega documento ADR para flat record (item 21). |
| 1.1.0 | 2026-04-15 | Carlos Torres | Se agrega documento de consulta de documentacion OpenAPI (item 20). |
| 1.0.0 | 2026-03-16 | Carlos Torres | Creacion del indice de seccion |