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`

```typescript
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)

```sql
-- 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

```bash
# 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

```sql
-- 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/`:
```yaml
# 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

```typescript
// 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

```yaml
# .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:
```typescript
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*