66161b1566
Sistema NEXUS v3.4 migrado con: Estructura principal: - core/orchestration: Sistema SIMCO + CAPVED (27 directivas, 28 perfiles) - core/catalog: Catalogo de funcionalidades reutilizables - shared/knowledge-base: Base de conocimiento compartida - devtools/scripts: Herramientas de desarrollo - control-plane/registries: Control de servicios y CI/CD - orchestration/: Configuracion de orquestacion de agentes Proyectos incluidos (11): - gamilit (submodule -> GitHub) - trading-platform (OrbiquanTIA) - erp-suite con 5 verticales: - erp-core, construccion, vidrio-templado - mecanicas-diesel, retail, clinicas - betting-analytics - inmobiliaria-analytics - platform_marketing_content - pos-micro, erp-basico Configuracion: - .gitignore completo para Node.js/Python/Docker - gamilit como submodule (git@github.com:rckrdmrd/gamilit-workspace.git) - Sistema de puertos estandarizado (3005-3199) Generated with NEXUS v3.4 Migration System EPIC-010: Configuracion Git y Repositorios
361 lines
10 KiB
Markdown
361 lines
10 KiB
Markdown
# SIMCO: MODULOS COMPARTIDOS
|
|
|
|
**Version:** 1.0.0
|
|
**Fecha:** 2026-01-03
|
|
**Aplica a:** Todos los agentes de desarrollo
|
|
**Prioridad:** OBLIGATORIA - Consultar antes de implementar funcionalidad comun
|
|
**Relacionado:** SIMCO-ESTRUCTURA-REPOS.md, PRINCIPIO-ANTI-DUPLICACION.md
|
|
|
|
---
|
|
|
|
## RESUMEN EJECUTIVO
|
|
|
|
> **El workspace NEXUS tiene DOS sistemas de codigo compartido: catalog/ y modules/**
|
|
> Consultar AMBOS antes de implementar funcionalidad que pueda existir.
|
|
> Duplicar codigo existente = deuda tecnica y mantenimiento multiplicado.
|
|
|
|
---
|
|
|
|
## DIFERENCIA: catalog/ vs modules/
|
|
|
|
### Tabla Comparativa
|
|
|
|
| Aspecto | core/catalog/ | core/modules/ |
|
|
|---------|---------------|---------------|
|
|
| **Proposito** | Documentacion + codigo de referencia | Codigo TypeScript listo para importar |
|
|
| **Contenido** | README, guias, templates, ejemplos | Archivos .ts exportables |
|
|
| **Uso** | Copiar y adaptar al proyecto | Importar directamente (@core/modules/*) |
|
|
| **Funcionalidades** | auth, payments, notifications, etc. | utils, tipos comunes, helpers |
|
|
| **Mantenimiento** | Cada proyecto mantiene su copia | Central, actualizaciones afectan a todos |
|
|
| **Cuando usar** | Funcionalidad compleja que requiere adaptacion | Utilidades genericas sin logica de negocio |
|
|
|
|
### core/catalog/ - Catalogo de Funcionalidades
|
|
|
|
```yaml
|
|
Ubicacion: /home/isem/workspace-v1/core/catalog/
|
|
|
|
Proposito: Documentar funcionalidades complejas con codigo de referencia
|
|
|
|
Estructura por funcionalidad:
|
|
core/catalog/{funcionalidad}/
|
|
+-- README.md # Descripcion y trade-offs
|
|
+-- IMPLEMENTATION.md # Pasos de implementacion
|
|
+-- _reference/ # Codigo de referencia para copiar
|
|
| +-- backend/
|
|
| +-- frontend/
|
|
| +-- database/
|
|
+-- orchestration/
|
|
+-- CONSUMIDORES.yml # Proyectos que lo usan
|
|
|
|
Funcionalidades disponibles (11):
|
|
- auth # Login, registro, JWT, OAuth
|
|
- session-management # Sesiones concurrentes
|
|
- rate-limiting # Throttle, 429
|
|
- notifications # Email, push, in-app
|
|
- websocket # Tiempo real, streaming
|
|
- multi-tenancy # Tenant, RLS
|
|
- feature-flags # Toggles dinamicos
|
|
- payments # Stripe, suscripciones
|
|
- template-saas # Template SaaS completo
|
|
- portales # Dashboards, widgets
|
|
- audit-logs # Auditoria, compliance
|
|
|
|
Como usar:
|
|
1. Buscar: grep -i "{keyword}" core/catalog/CATALOG-INDEX.yml
|
|
2. Leer: core/catalog/{funcionalidad}/README.md
|
|
3. Copiar: _reference/ al proyecto
|
|
4. Adaptar: configuracion al contexto actual
|
|
5. Validar: ejecutar tests
|
|
```
|
|
|
|
### core/modules/ - Modulos TypeScript
|
|
|
|
```yaml
|
|
Ubicacion: /home/isem/workspace-v1/core/modules/
|
|
|
|
Proposito: Codigo TypeScript compartido para importar directamente
|
|
|
|
Estructura:
|
|
core/modules/
|
|
+-- package.json # Configuracion del monorepo
|
|
+-- utils/ # Utilidades genericas
|
|
| +-- index.ts
|
|
| +-- date.util.ts
|
|
| +-- string.util.ts
|
|
| +-- validation.util.ts
|
|
+-- auth/ # Modulo de autenticacion (en desarrollo)
|
|
+-- notifications/ # Sistema de notificaciones
|
|
+-- payments/ # Integracion de pagos
|
|
+-- billing/ # Facturacion
|
|
+-- multitenant/ # Multi-tenancy
|
|
|
|
Modulos disponibles (6):
|
|
- utils # Helpers de fecha, string, validacion
|
|
- auth # Guards, decorators, JWT
|
|
- notifications # Servicio de notificaciones
|
|
- payments # Integracion Stripe
|
|
- billing # Logica de facturacion
|
|
- multitenant # Tenant context, RLS
|
|
|
|
Como usar:
|
|
1. Importar: import { funcion } from '@core/modules/utils';
|
|
2. Usar directamente en el codigo
|
|
3. NO copiar, solo importar
|
|
```
|
|
|
|
---
|
|
|
|
## FLUJO DE DECISION
|
|
|
|
### ¿Necesito funcionalidad compartida?
|
|
|
|
```
|
|
INICIO: Voy a implementar funcionalidad
|
|
|
|
|
v
|
|
¿Es funcionalidad comun (auth, payments, notifications)?
|
|
|
|
|
+-- SI --> Buscar en @CATALOG_INDEX
|
|
| |
|
|
| +-- Encontrado --> Seguir IMPLEMENTATION.md, copiar y adaptar
|
|
| |
|
|
| +-- No encontrado --> ¿Es utilidad generica?
|
|
| |
|
|
| +-- SI --> Ver core/modules/
|
|
| |
|
|
| +-- NO --> Implementar nuevo
|
|
|
|
|
+-- NO --> ¿Es utilidad generica (fecha, string, validacion)?
|
|
|
|
|
+-- SI --> import from '@core/modules/utils'
|
|
|
|
|
+-- NO --> Implementar en el proyecto
|
|
```
|
|
|
|
### ¿Catalog o Modules?
|
|
|
|
```yaml
|
|
Usar CATALOG cuando:
|
|
- Es funcionalidad completa (auth, payments, notifications)
|
|
- Requiere adaptacion al proyecto
|
|
- Tiene logica de negocio que varia
|
|
- Incluye DDL, backend, frontend
|
|
- Cada proyecto puede tener variaciones
|
|
|
|
Usar MODULES cuando:
|
|
- Es utilidad generica sin logica de negocio
|
|
- NO requiere adaptacion
|
|
- Es identico en todos los proyectos
|
|
- Son helpers puros (fecha, string, validacion)
|
|
- Cambios deben propagarse a todos los consumidores
|
|
```
|
|
|
|
---
|
|
|
|
## COMO IMPORTAR MODULOS
|
|
|
|
### Configuracion en tsconfig.json
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"paths": {
|
|
"@core/modules/*": ["../../core/modules/*"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ejemplos de Importacion
|
|
|
|
```typescript
|
|
// Importar utilidades
|
|
import { formatDate, parseDate } from '@core/modules/utils';
|
|
import { slugify, capitalize } from '@core/modules/utils/string.util';
|
|
import { isValidEmail, isValidPhone } from '@core/modules/utils/validation.util';
|
|
|
|
// Importar modulos completos
|
|
import { TenantService } from '@core/modules/multitenant';
|
|
import { NotificationService } from '@core/modules/notifications';
|
|
import { StripeService } from '@core/modules/payments';
|
|
```
|
|
|
|
### Estructura de Exportaciones
|
|
|
|
```typescript
|
|
// core/modules/utils/index.ts
|
|
export * from './date.util';
|
|
export * from './string.util';
|
|
export * from './validation.util';
|
|
```
|
|
|
|
---
|
|
|
|
## CUANDO CREAR MODULO NUEVO
|
|
|
|
### Criterios para Promocion a core/modules/
|
|
|
|
```yaml
|
|
Crear modulo nuevo SI:
|
|
- Es usado por 3+ proyectos
|
|
- Es utilidad generica (NO logica de negocio)
|
|
- NO requiere adaptacion por proyecto
|
|
- Tiene tests unitarios
|
|
- Tiene documentacion (README.md)
|
|
- Sigue patrones de los modulos existentes
|
|
|
|
NO crear modulo SI:
|
|
- Es especifico de un proyecto
|
|
- Contiene logica de negocio variable
|
|
- Requiere configuracion diferente por proyecto
|
|
- Es prototipo no probado
|
|
```
|
|
|
|
### Proceso de Promocion
|
|
|
|
```yaml
|
|
PASO_1_IDENTIFICAR:
|
|
- Codigo duplicado en 2+ proyectos
|
|
- Utilidad generica sin dependencia de negocio
|
|
|
|
PASO_2_EXTRAER:
|
|
- Crear carpeta en core/modules/{modulo}/
|
|
- Mover codigo a archivos .ts
|
|
- Crear index.ts con exports
|
|
|
|
PASO_3_DOCUMENTAR:
|
|
- Crear README.md siguiendo TEMPLATE-MODULO-COMPARTIDO.md
|
|
- Documentar API publica
|
|
- Agregar ejemplos de uso
|
|
|
|
PASO_4_CONFIGURAR:
|
|
- Actualizar core/modules/package.json
|
|
- Verificar paths en consumidores
|
|
|
|
PASO_5_VALIDAR:
|
|
- npm run build en core/modules
|
|
- npm run test (si hay tests)
|
|
- Verificar importacion desde proyecto de prueba
|
|
|
|
PASO_6_ACTUALIZAR_CONSUMIDORES:
|
|
- Reemplazar codigo duplicado por imports
|
|
- Actualizar inventarios
|
|
```
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DE MODULO
|
|
|
|
### Template de Modulo
|
|
|
|
```
|
|
core/modules/{modulo}/
|
|
+-- README.md # Documentacion del modulo
|
|
+-- package.json # (opcional) dependencias propias
|
|
+-- index.ts # Punto de entrada, exports
|
|
+-- {funcion}.ts # Archivos de funcionalidad
|
|
+-- {funcion}.spec.ts # Tests unitarios
|
|
+-- types.ts # (opcional) tipos TypeScript
|
|
```
|
|
|
|
### Ejemplo: Modulo utils
|
|
|
|
```
|
|
core/modules/utils/
|
|
+-- README.md
|
|
+-- index.ts # export * from './date.util'; ...
|
|
+-- date.util.ts # formatDate, parseDate, addDays...
|
|
+-- date.util.spec.ts # Tests de fecha
|
|
+-- string.util.ts # slugify, capitalize, truncate...
|
|
+-- string.util.spec.ts # Tests de string
|
|
+-- validation.util.ts # isValidEmail, isValidPhone...
|
|
+-- validation.util.spec.ts # Tests de validacion
|
|
```
|
|
|
|
---
|
|
|
|
## CHECKLIST DE DOCUMENTACION
|
|
|
|
### Al Crear Modulo Nuevo
|
|
|
|
```markdown
|
|
- [ ] README.md creado con:
|
|
- [ ] Descripcion del modulo
|
|
- [ ] Instalacion/configuracion
|
|
- [ ] API publica documentada
|
|
- [ ] Ejemplos de uso
|
|
- [ ] Dependencias listadas
|
|
- [ ] index.ts con exports
|
|
- [ ] Tests unitarios
|
|
- [ ] Agregar a core/modules/package.json
|
|
- [ ] Verificar paths de importacion
|
|
```
|
|
|
|
### Al Usar Modulo Existente
|
|
|
|
```markdown
|
|
- [ ] Verificar version compatible
|
|
- [ ] Configurar paths en tsconfig.json
|
|
- [ ] Importar correctamente
|
|
- [ ] NO copiar codigo (solo importar)
|
|
- [ ] Reportar bugs/mejoras al owner del modulo
|
|
```
|
|
|
|
---
|
|
|
|
## MANTENIMIENTO
|
|
|
|
### Responsabilidades
|
|
|
|
```yaml
|
|
Owner del modulo:
|
|
- Mantener documentacion actualizada
|
|
- Revisar PRs de contribuciones
|
|
- Versionar cambios breaking
|
|
- Notificar a consumidores de cambios
|
|
|
|
Consumidores:
|
|
- Importar, NO copiar
|
|
- Reportar bugs al owner
|
|
- Contribuir mejoras via PR
|
|
- Actualizar cuando hay cambios
|
|
```
|
|
|
|
### Versionado
|
|
|
|
```yaml
|
|
Reglas de versionado:
|
|
- Patch (1.0.X): Bugfixes, no rompe nada
|
|
- Minor (1.X.0): Nueva funcionalidad, retrocompatible
|
|
- Major (X.0.0): Breaking changes, requiere actualizacion
|
|
|
|
Comunicacion:
|
|
- Cambios breaking se anuncian en CHANGELOG.md
|
|
- Consumidores actualizan antes de deadline
|
|
```
|
|
|
|
---
|
|
|
|
## ERRORES COMUNES
|
|
|
|
| Error | Causa | Solucion |
|
|
|-------|-------|----------|
|
|
| Modulo no encontrado | Paths mal configurados | Verificar tsconfig.json |
|
|
| Codigo duplicado | No consulto modules/ | Refactorizar a import |
|
|
| Breaking changes | Actualizo modulo sin avisar | Versionar correctamente |
|
|
| Funcionalidad en modules que deberia estar en catalog | Tiene logica de negocio | Mover a catalog/ |
|
|
| Tests fallan despues de import | Modulo incompatible | Verificar version y deps |
|
|
|
|
---
|
|
|
|
## REFERENCIAS
|
|
|
|
- **Estructura:** `SIMCO-ESTRUCTURA-REPOS.md`
|
|
- **Anti-duplicacion:** `PRINCIPIO-ANTI-DUPLICACION.md`
|
|
- **Catalogo:** `core/catalog/CATALOG-INDEX.yml`
|
|
- **Template modulo:** `TEMPLATE-MODULO-COMPARTIDO.md`
|
|
|
|
---
|
|
|
|
**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Directiva de Modulos
|