Este documento describe el propósito de libs/shared, libs/domain y libs/data-access, y propone una guía para ubicar código nuevo mientras se migra gradualmente desde las aplicaciones.
libs/sharedAgrupa capacidades reutilizables por varias aplicaciones o módulos. Está dividido por tipo de responsabilidad:
| Carpeta | Propósito | Qué ubicar aquí |
|---|---|---|
data-access/ |
Acceso transversal a servicios y recursos comunes de la aplicación. | HTTP común, autenticación, autorización, configuración API, interceptores, CRUD reutilizable, importación/exportación y servicios globales. Los servicios propios de un módulo de negocio deben preferir libs/data-access. |
domain/ |
Contratos y reglas de dominio compartidos entre módulos. | Modelos, tipos, reglas puras y conceptos compartidos. Si el concepto pertenece a un dominio de negocio general y tiene su propia librería, ubicarlo en libs/domain. |
master/ |
Elementos de catálogos o maestros compartidos. | Componentes, formularios, adaptadores y lógica de presentación para datos maestros reutilizados por varias áreas. |
ui/ |
Componentes visuales reutilizables y sin propiedad de un módulo funcional específico. | Componentes, directivas, pipes y patrones visuales comunes. Evitar llamadas API y reglas de negocio aquí. |
util/ |
Funciones y herramientas genéricas. | Funciones puras, formato, conversión y helpers que no dependan de una pantalla o área particular. |
Como regla general, los componentes reutilizables de interfaz van en shared/ui; los componentes especializados en maestros, en shared/master. Lo que solo utiliza un módulo debe permanecer en ese módulo hasta que exista una necesidad real de compartirlo.
nebula-erpLas rutas siguientes corresponden al árbol develop del repositorio frontend. Los enlaces abren directamente cada ubicación en GitLab y sirven como punto de partida para localizar dónde modificar una funcionalidad.
nebula-erplibs/libs/data-access/libs/data-access/src/libs/data-access/src/centros-costos/ — ejemplo de carpeta funcional.libs/domain/src/lib/El código de una funcionalidad se agrupa bajo libs/data-access/src/<funcionalidad>/. Por ejemplo, para centros de costos:
libs/data-access/src/centros-costos/
centros-costos.service.ts
centros-costos.service.spec.ts
index.ts
El servicio contiene las llamadas HTTP y sus transformaciones de respuesta. Su spec contiene las pruebas unitarias del servicio. El index.ts de la carpeta publica los elementos de esa funcionalidad y libs/data-access/src/index.ts reexporta la carpeta para que los consumidores importen desde la API pública de la librería. Para una funcionalidad con varias responsabilidades, pueden crearse más archivos, manteniendo el nombre de la carpeta como prefijo funcional.
Los tipos exclusivos del transporte o de una API pueden estar junto al servicio propietario. Los contratos de dominio compartidos deben ir en libs/domain.
libs/domainContiene los contratos compartidos del dominio: estructuras y vocabulario de negocio que necesitan consumir distintos módulos. La ubicación real de sus categorías es libs/domain/src/lib/; cada categoría agrupa los archivos por funcionalidad y publica sus exports mediante index.ts hasta llegar a libs/domain/src/index.ts.
| Categoría | Ruta real | Contenido |
|---|---|---|
| Constantes | libs/domain/src/lib/constants/ |
Constantes de negocio, agrupadas por funcionalidad. |
| DTOs | libs/domain/src/lib/dtos/ |
Tipos de datos compartidos entre capas o servicios. |
| Enums | libs/domain/src/lib/enums/ |
Enumeraciones compartidas. |
| i18n | libs/domain/src/lib/i18n/ |
Claves tipadas de traducción del dominio. |
| Modelos e interfaces | libs/domain/src/lib/models/ |
Modelos e interfaces de negocio. |
| Utilidades | libs/domain/src/lib/util/ |
Funciones auxiliares de dominio. |
| Validadores | libs/domain/src/lib/validators/ |
Validadores reutilizables. |
En cada categoría, agrupar los archivos por funcionalidad y usar ese nombre en los archivos y pruebas cuando correspondan. Por ejemplo:
libs/domain/src/lib/
constants/<funcionalidad>/
dtos/<funcionalidad>/
enums/<funcionalidad>/
i18n/<funcionalidad>/
models/<funcionalidad>/
util/<funcionalidad>/
validators/<funcionalidad>/
Las funciones o validadores con comportamiento deben contar con su spec unitaria en la misma carpeta; las interfaces, DTOs, enums y constantes declarativas no requieren una prueba aislada si no tienen comportamiento que verificar. Mantener los índices de cada carpeta y categoría al día, además del src/index.ts público.
El src/index.ts de la librería expone los barriles públicos de estas categorías:
| Carpeta | Propósito |
|---|---|
models/ |
Entidades y modelos de dominio. |
dtos/ |
Tipos para representar datos intercambiados entre capas o servicios. |
enums/ |
Enumeraciones compartidas y conjuntos cerrados de valores. |
constants/ |
Constantes de dominio que no son configuración específica de una aplicación. |
i18n/ |
Claves o recursos de traducción asociados al dominio, si se comparten. |
util/ |
Funciones auxiliares de dominio, preferiblemente puras. |
validators/ |
Validaciones reutilizables de datos y conceptos de dominio. |
Mantener esta librería independiente de Angular, componentes, almacenamiento y transporte HTTP siempre que sea posible. Un tipo que solo sirve a una pantalla o servicio debe quedarse junto a ese consumidor hasta que haya una necesidad de compartirlo.
libs/data-accessEs la librería destino para servicios de negocio y comunicación con APIs. Sus carpetas bajo src/ agrupan capacidades por funcionalidad (por ejemplo, proyectos/, terceros/, invoicing/, bank-closures/ y budget-line-items/). El src/index.ts centraliza sus exportaciones públicas; cada funcionalidad debe exponer sus elementos mediante su propio index.ts.
Aquí ubicar servicios Angular que consultan o modifican APIs, adaptadores de API, repositorios, mapeadores relacionados con persistencia y tipos de petición/respuesta que sean específicos de la integración. Las reglas, modelos y contratos de negocio compartidos deben vivir en libs/domain; la presentación debe permanecer en la aplicación o en libs/shared/ui cuando sea realmente transversal.
libs/data-access/src/<funcionalidad>/
<funcionalidad>.service.ts
<funcionalidad>.service.spec.ts
index.ts
El archivo index.ts exporta solo la API pública del área. Agregar la exportación de la carpeta al libs/data-access/src/index.ts para permitir importaciones desde el paquete público, manteniendo el orden y evitando exportaciones duplicadas. La misma regla de barriles aplica a las categorías y funcionalidades de domain.
libs/shared/ui.libs/shared/master.libs/domain.libs/data-access/<funcionalidad>.libs/shared/data-access.Para mover código existente, hacerlo por funcionalidad y en pasos pequeños:
domain), la integración (data-access) y la presentación (shared/ui o shared/master).index.ts de la funcionalidad y añadir su exportación al barril raíz que corresponda.src.domain debe ser la capa más independiente; data-access puede consumir domain; la UI puede consumir ambas, pero las librerías de dominio no deben depender de la UI.La migración no implica mover de inmediato todos los servicios ni componentes: conviene avanzar por área funcional y conservar una única fuente de verdad para cada implementación.
Los proyectos Nx incluyen objetivos de build y test. Desde la raíz se pueden ejecutar, según corresponda:
npx nx build domain
npx nx build data-access
npx nx test domain
npx nx test data-access
Consultar project.json de cada librería si cambian los nombres de los objetivos o la configuración.