workspace-v1/projects/erp-suite/docs/ANALISIS-ARQUITECTURA-ERP-SUITE.md

ANALISIS ARQUITECTONICO: ERP-SUITE

Fecha: 2025-12-08 Agente: Architecture Analyst Alcance: erp-core + 5 verticales (construccion, mecanicas-diesel, clinicas, retail, vidrio-templado)

---

1. RESUMEN EJECUTIVO

ERP-Suite es una suite empresarial multi-vertical diseñada con una arquitectura modular que maximiza la reutilizacion de codigo. El sistema se compone de:

• erp-core: Base generica que proporciona 60-70% del codigo compartido
• 5 verticales: Extensiones especializadas por giro de negocio

Estado General

Componente	Progreso	Estado
erp-core	60%	En desarrollo activo
Construccion	35%	Backend parcial, DDL 50%
Mecanicas Diesel	95% docs / 30% codigo	DDL 100%, listo para dev
Clinicas	25%	Solo documentacion
Retail	25%	Solo documentacion
Vidrio Templado	25%	Solo documentacion

---

2. ARQUITECTURA DE ERP-CORE

2.1 Stack Tecnologico

Capa	Tecnologia	Version
Backend	Node.js + Express + TypeScript	20+ / 4.18 / 5.3
Frontend	React + Vite + TypeScript	18.3 / 5.4 / 5.6
Base de Datos	PostgreSQL con RLS	15+
State Management	Zustand	5.0
Validacion	Zod	3.22+
ORM/Driver	pg (raw queries)	8.11

2.2 Estructura de Modulos Backend (14 modulos)

erp-core/backend/src/modules/
├── auth/          # JWT, bcryptjs, refresh tokens
├── users/         # CRUD usuarios
├── companies/     # Multi-company management
├── core/          # Catalogos (monedas, paises, UoM)
├── partners/      # Clientes/proveedores
├── inventory/     # Productos, almacenes, stock
├── financial/     # Contabilidad (cuentas, diarios)
├── purchases/     # Ordenes de compra
├── sales/         # Cotizaciones, pedidos
├── projects/      # Proyectos, tareas, timesheets
├── system/        # Mensajes, notificaciones
├── crm/           # Leads, oportunidades
└── hr/            # Nomina basica

2.3 Patrones de Arquitectura

BaseService Generico

Ubicacion: backend/src/shared/services/base.service.ts

abstract class BaseService<T, CreateDto, UpdateDto> {
  // CRUD con multi-tenancy automatico
  findAll(tenantId, filters): PaginatedResult<T>
  findById(id, tenantId): T | null
  softDelete(id, tenantId, userId): boolean
  withTransaction<R>(fn): Promise<R>
}

Beneficios:

• Elimina duplicacion de codigo CRUD
• Multi-tenancy integrado (RLS)
• Paginacion, filtros, busqueda full-text
• Soft-delete por defecto

Multi-Tenancy (Schema-Level + RLS)

-- Todas las tablas tienen:
tenant_id UUID NOT NULL REFERENCES auth.tenants(id)

-- RLS Policy estandar
CREATE POLICY tenant_isolation ON {tabla}
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

2.4 Base de Datos (12 Schemas, 144 tablas)

Schema	Proposito	Tablas
auth	Usuarios, roles, sesiones	10
core	Partners, catalogos	12
analytics	Contabilidad analitica	7
financial	Facturas, pagos	15
inventory	Productos, movimientos	10
purchase	Ordenes de compra	8
sales	Cotizaciones, pedidos	10
projects	Tareas, timesheets	10
system	Notificaciones, logs	13
billing	SaaS subscriptions	11
crm	Leads, pipeline	6
hr	Empleados, nomina	6

---

3. ANALISIS DE VERTICALES

3.1 Matriz Comparativa

Aspecto	Construccion	Mecanicas	Clinicas	Retail	Vidrio
Progreso	35%	95% docs	25%	25%	25%
Modulos	18	6	12	10	8
Story Points	692	241	451	353	259
DDL	50%	100%	0%	0%	0%
Backend	22%	30%	0%	0%	0%
Frontend	5%	0%	0%	0%	0%
Docs	100%	100%	100%	100%	100%

3.2 Porcentaje de Reutilizacion del Core

Vertical	% Core	Modulos Heredados	Modulos Nuevos
Construccion	61%	Auth, RBAC, Catalogos, Reportes	Proyectos, Presupuestos, INFONAVIT, HSE
Mecanicas	60-70%	Auth, RBAC, Inventario	Ordenes servicio, Diagnosticos
Clinicas	30-50%	Auth, RBAC, Farmacia	Expediente, Telemedicina, DICOM
Retail	40-70%	Auth, RBAC, Inventario, Reportes	POS, Caja, E-commerce
Vidrio	50-60%	Auth, RBAC, Inventario	Corte (nesting), Templado

3.3 Analisis por Vertical

CONSTRUCCION (35% completado)

Modulos implementados:

• DDL: 3/7 schemas (construction, hr, hse)
• Backend: 4 modulos con entidades TypeORM
• 449 archivos de documentacion

Fases:

Fase 1 (MAI): 14 modulos, ~670 SP
Fase 2 (MAE): 3 modulos enterprise, 210 SP
Fase 3 (MAA): 1 modulo HSE

Gaps identificados:

• DDL faltante: estimates, infonavit, inventory-ext, purchase-ext
• Servicios backend MAI-003 a MAI-013 pendientes
• Frontend no iniciado

MECANICAS DIESEL (95% documentado)

Estado: Listo para desarrollo

DDL completo (43 tablas):

• workshop_core: 9 tablas
• service_management: 14 tablas
• parts_management: 12 tablas
• vehicle_management: 8 tablas

Modulos MVP:

Codigo	Modulo	SP	US
MMD-001	Fundamentos	42	9
MMD-002	Ordenes de Servicio	55	11
MMD-003	Diagnosticos	42	8
MMD-004	Inventario Refacciones	42	10
MMD-005	Vehiculos	34	8
MMD-006	Cotizaciones	26	7

Directivas especificas documentadas:

• DIRECTIVA-ORDENES-TRABAJO.md
• DIRECTIVA-INVENTARIO-REFACCIONES.md

CLINICAS (25% documentado)

12 modulos planificados (451 SP):

• CL-004 Consultas: 0% core (nuevo)
• CL-010 Telemedicina: 0% core (WebRTC)
• CL-012 Imagenologia: 0% core (DICOM)

Consideraciones especiales:

• Cumplimiento: NOM-024-SSA3, LFPDPPP
• Encriptacion de datos medicos obligatoria
• Integraciones: PACS, timbrado CFDI

RETAIL (25% documentado)

10 modulos planificados (353 SP):

• RT-002 POS: PWA con capacidad offline
• RT-007 Caja: Arqueos y cortes
• RT-009 E-commerce: Integracion tienda online

Consideraciones especiales:

• Sincronizacion bidireccional offline
• Integracion hardware (impresoras, cajas)

VIDRIO TEMPLADO (25% documentado)

8 modulos planificados (259 SP):

• VT-005 Corte: Algoritmo nesting (0% core)
• VT-006 Templado: Control de hornos (0% core)

Consideraciones especiales:

• Cotizacion por dimensiones (alto x ancho)
• Trazabilidad de lotes obligatoria
• Pruebas de fragmentacion QC

---

4. SISTEMA DE HERENCIA

4.1 Jerarquia de 3 Niveles

NIVEL 0: CORE GLOBAL
└── /home/isem/workspace/core/orchestration/
    ├── directivas/simco/    # Sistema SIMCO v2.2.0
    ├── templates/           # Templates reutilizables
    └── checklists/          # Validaciones

NIVEL 1: ERP-CORE
└── apps/erp-core/orchestration/
    ├── directivas/          # Directivas ERP
    └── 00-guidelines/       # Contexto proyecto

NIVEL 2: VERTICALES
└── apps/verticales/{vertical}/orchestration/
    ├── 00-guidelines/       # CONTEXTO-PROYECTO.md
    ├── directivas/          # Directivas especificas
    └── inventarios/         # SSOT del vertical

4.2 Regla Fundamental

Las verticales EXTIENDEN, nunca MODIFICAN el core

4.3 Documentos de Herencia Requeridos

Cada vertical debe tener en orchestration/00-guidelines/:

Archivo	Proposito	Estado
CONTEXTO-PROYECTO.md	Vision y alcance	Todas tienen
HERENCIA-ERP-CORE.md	Modulos heredados	Mecanicas OK
HERENCIA-SPECS-CORE.md	SPECS aplicables	Mecanicas OK
HERENCIA-DIRECTIVAS.md	Jerarquia directivas	Mecanicas OK
HERENCIA-SIMCO.md	Sistema orquestacion	Mecanicas OK

---

5. HALLAZGOS Y PROBLEMAS

5.1 Estado de Documentacion de Herencia

A. Documentacion de Herencia - ACTUALIZADO

Vertical	HERENCIA-ERP-CORE	HERENCIA-SPECS	HERENCIA-SIMCO	HERENCIA-DIRECTIVAS
Construccion	OK	OK	OK	OK
Mecanicas	OK	OK	OK	OK
Clinicas	OK	OK	OK	OK
Retail	OK	OK	OK	OK
Vidrio	OK	OK	OK	OK

Estado: Todas las verticales tienen documentacion de herencia completa.

B. Nomenclatura de Schemas Inconsistente

erp-core:     auth, core, financial, inventory...
construccion: construction, hr, hse
mecanicas:    workshop_core, service_management, parts_management

Documento de estandarizacion creado: docs/ESTANDAR-NOMENCLATURA-SCHEMAS.md

Prefijos definidos:

• erp_* para erp-core
• con_* para construccion
• mec_* para mecanicas
• cli_* para clinicas
• ret_* para retail
• vit_* para vidrio templado

C. Estructura de Directorios Variable

erp-core/backend/src/modules/{modulo}/
  ├── {modulo}.controller.ts
  ├── {modulo}.service.ts
  └── {modulo}.routes.ts

construccion/backend/src/modules/{modulo}/
  ├── entities/             # Diferente
  ├── services/             # Diferente
  └── controllers/          # Diferente

Recomendacion: Unificar estructura en todas las verticales.

5.2 Gaps de Implementacion

erp-core

• MGN-001 Auth: En desarrollo (JWT implementado)
• MGN-002-014: Solo DDL, sin backend completo
• Frontend: Estructura base, features incompletas

Verticales

• Construccion: 4 schemas DDL pendientes
• Mecanicas: Backend y frontend pendientes
• Clinicas/Retail/Vidrio: Todo pendiente

5.3 Dependencias Criticas

erp-core DEBE completarse primero:
├── MGN-001 Auth        → Todas las verticales dependen
├── MGN-002 Users       → Todas las verticales dependen
├── MGN-003 Roles       → Todas las verticales dependen
├── MGN-004 Tenants     → Todas las verticales dependen
├── MGN-005 Catalogs    → Todas las verticales dependen
└── MGN-011 Inventory   → Mecanicas, Retail, Vidrio, Construccion

---

6. RECOMENDACIONES

6.1 Prioridad CRITICA (Hacer inmediatamente)

R1: Completar Documentacion de Herencia

# Para cada vertical (construccion, clinicas, retail, vidrio):
apps/verticales/{vertical}/orchestration/00-guidelines/
  ├── HERENCIA-ERP-CORE.md      # Copiar de mecanicas, adaptar
  ├── HERENCIA-SPECS-CORE.md    # Listar SPECS aplicables
  ├── HERENCIA-DIRECTIVAS.md    # Jerarquia de directivas
  └── HERENCIA-SIMCO.md         # Configuracion SIMCO

R2: Estandarizar Estructura de Modulos Backend

Adoptar estructura unificada:

modules/{nombre}/
├── {nombre}.module.ts      # Opcional si no usa NestJS
├── {nombre}.controller.ts
├── {nombre}.service.ts
├── {nombre}.routes.ts
├── entities/
│   └── {entidad}.entity.ts
├── dto/
│   ├── create-{nombre}.dto.ts
│   └── update-{nombre}.dto.ts
└── __tests__/

R3: Definir Convencion de Schemas

-- Propuesta de prefijos
erp_core.*      -- Schemas del core
con_*           -- Construccion
mec_*           -- Mecanicas diesel
cli_*           -- Clinicas
ret_*           -- Retail
vit_*           -- Vidrio templado

6.2 Prioridad ALTA (Proximas 2-4 semanas)

R4: Completar MGN-001 a MGN-005 en erp-core

Orden de implementacion:

1. MGN-001 Auth (JWT, refresh tokens, 2FA)
2. MGN-002 Users (CRUD completo)
3. MGN-003 Roles (RBAC)
4. MGN-004 Tenants (Multi-tenancy)
5. MGN-005 Catalogs (Datos maestros)

R5: Crear Inventario Unificado por Vertical

Cada vertical debe tener en orchestration/inventarios/:

# MASTER_INVENTORY.yml
project:
  name: {vertical}
  version: 1.0.0
  parent: erp-core

metrics:
  total_modules: X
  implemented_modules: Y
  total_tables: Z
  total_endpoints: N

modules:
  inherited:
    - MGN-001: 100%
    - MGN-002: 100%
  extended:
    - MGN-005: +30%
  new:
    - {vertical}-001: Descripcion

R6: Iniciar Frontend de Mecanicas Diesel

El DDL esta 100% completo. Siguiente paso:

1. Crear estructura React + Vite
2. Implementar modulo de autenticacion (heredar de core)
3. Desarrollar UI de ordenes de servicio

6.3 Prioridad MEDIA (1-2 meses)

R7: Crear Tests de Integracion Core-Vertical

// test/integration/vertical-inheritance.spec.ts
describe('Vertical inherits from Core', () => {
  it('should use core auth service', () => {...})
  it('should extend catalog service', () => {...})
  it('should have RLS policies', () => {...})
})

R8: Documentar API Contracts

Crear en cada vertical:

docs/api-contracts/
├── {vertical}-api.yml      # OpenAPI 3.0
└── README.md               # Endpoints documentados

R9: Implementar CI/CD Pipeline

# .github/workflows/vertical-ci.yml
- Lint (ESLint)
- Type check (tsc)
- Unit tests (Jest)
- Build check
- DDL validation

6.4 Prioridad BAJA (3+ meses)

R10: Crear SDK Compartido

shared-libs/
├── @erp-suite/core-types/    # Tipos TypeScript compartidos
├── @erp-suite/ui-components/ # Componentes React reutilizables
└── @erp-suite/api-client/    # Cliente HTTP tipado

R11: Implementar Feature Flags

Para deployment gradual de verticales:

const featureFlags = {
  'construccion.hse': process.env.FF_CONSTRUCCION_HSE,
  'mecanicas.diagnosticos': process.env.FF_MECANICAS_DIAG,
}

---

7. ROADMAP RECOMENDADO

Fase 1: Fundamentos (Semanas 1-4)

• Completar MGN-001 a MGN-005 en erp-core
• Crear documentos HERENCIA-* en todas las verticales
• Estandarizar estructura de modulos

Fase 2: Vertical Piloto - Mecanicas (Semanas 5-8)

• Implementar frontend React
• Completar servicios backend
• Testing E2E
• Deploy MVP

Fase 3: Verticales Secundarias (Semanas 9-16)

• Construccion: Completar DDL + Backend
• Clinicas/Retail/Vidrio: Iniciar DDL

Fase 4: Consolidacion (Semanas 17-24)

• SDK compartido
• CI/CD completo
• Documentacion de usuario

---

8. METRICAS DE ALINEACION

Checklist de Alineacion por Vertical

Criterio	Peso	Construccion	Mecanicas	Clinicas	Retail	Vidrio
CONTEXTO-PROYECTO.md	10%	OK	OK	OK	OK	OK
HERENCIA-ERP-CORE.md	15%	OK	OK	OK	OK	OK
HERENCIA-SPECS-CORE.md	10%	OK	OK	OK	OK	OK
HERENCIA-DIRECTIVAS.md	10%	OK	OK	OK	OK	OK
DDL con RLS	20%	50%	100%	0%	0%	0%
Backend hereda BaseService	15%	NO	NO	NO	NO	NO
Inventarios SSOT	10%	OK	OK	OK	OK	OK
Tests unitarios	10%	NO	NO	NO	NO	NO

Score de Alineacion (Actualizado 2025-12-08):

• Construccion: 65% (+40%)
• Mecanicas Diesel: 85% (+10%)
• Clinicas: 55% (+40%)
• Retail: 55% (+40%)
• Vidrio Templado: 55% (+40%)

---

9. CONCLUSION

El proyecto ERP-Suite tiene una arquitectura bien disenada con:

• Separacion clara entre core y verticales
• Sistema de herencia documentado (SIMCO)
• Multi-tenancy robusto con RLS
• Documentacion exhaustiva

Estado Post-Analisis (Actualizado 2025-12-08)

Mejoras implementadas durante este analisis:

1. Documentacion de herencia: Todas las verticales ahora tienen documentos HERENCIA-* completos
2. Inventarios SSOT: Todas las verticales tienen MASTER_INVENTORY.yml y archivos relacionados
3. Estandar de schemas: Documento ESTANDAR-NOMENCLATURA-SCHEMAS.md creado con convenciones

Pendientes criticos:

1. erp-core incompleto (60%) - Bloquea desarrollo de verticales
2. Migracion de schemas - Aplicar prefijos estandarizados
3. Tests de integracion - No existen entre core y verticales
4. Backend BaseService - Ninguna vertical hereda del patron base

Proximos Pasos Recomendados

Prioridad	Accion	Responsable
P0	Completar MGN-001 a MGN-005 en erp-core	Backend Team
P0	Iniciar frontend de Mecanicas Diesel	Frontend Team
P1	Migrar schemas a nomenclatura estandar	Database Team
P1	Completar DDL de Construccion (4 schemas)	Database Team
P2	Crear tests de integracion core-vertical	QA Team

---

10. DOCUMENTOS GENERADOS

Documento	Ubicacion	Proposito
Analisis Arquitectonico	docs/ANALISIS-ARQUITECTURA-ERP-SUITE.md	Este documento
Estandar de Schemas	docs/ESTANDAR-NOMENCLATURA-SCHEMAS.md	Convencion de nomenclatura BD

---

Documento generado automaticamente por Architecture Analyst Agent Sistema NEXUS - Fabrica de Software con Agentes IA Fecha: 2025-12-08