# Contexto del Proyecto: ERP Core

## Metadatos

| Campo | Valor |
|-------|-------|
| **Nombre** | ERP Core - Base Generica Reutilizable |
| **Tipo** | CORE-BASE (Proyecto Independiente) |
| **Nivel** | BASE para verticales y productos |
| **Estado** | En desarrollo |
| **Progreso** | 60% |
| **Version** | 1.2.0 |
| **Workspace** | `/home/isem/workspace-v1/projects/erp-core/` |
| **Fecha Migracion** | 2025-12-27 |

---

## VARIABLES PARA DIRECTIVAS GLOBALES

```yaml
# Identificacion del Proyecto
PROJECT:             erp-core
PROJECT_NAME:        ERP Core
PROJECT_LEVEL:       CORE-BASE

# Paths Principales (WORKSPACE-V1)
WORKSPACE_ROOT:      ~/workspace-v1
PROJECT_ROOT:        ~/workspace-v1/projects/erp-core
APPS_ROOT:           ~/workspace-v1/projects/erp-core
DOCS_ROOT:           ~/workspace-v1/projects/erp-core/docs
ORCHESTRATION:       ~/workspace-v1/projects/erp-core/orchestration

# Base Orchestration (Directivas y Perfiles)
DIRECTIVAS_PATH:     ~/workspace-v1/orchestration/directivas
PERFILES_PATH:       ~/workspace-v1/orchestration/agents/perfiles
CATALOG_PATH:        ~/workspace-v1/shared/catalog

# Base de Datos
DB_NAME:             erp_core
DB_DDL_PATH:         ~/workspace-v1/projects/erp-core/database/ddl
DB_SCRIPTS_PATH:     ~/workspace-v1/projects/erp-core/database

# Backend
BACKEND_ROOT:        ~/workspace-v1/projects/erp-core/backend
BACKEND_SRC:         ~/workspace-v1/projects/erp-core/backend/src

# Frontend
FRONTEND_ROOT:       ~/workspace-v1/projects/erp-core/frontend
FRONTEND_SRC:        ~/workspace-v1/projects/erp-core/frontend/src
```

---

## Descripcion

ERP Core es la base generica que proporciona el 60-70% del codigo compartido para todas las verticales. Incluye modulos fundamentales como autenticacion, usuarios, roles, catalogos maestros, y funcionalidades comunes.

**Proyectos que extienden este core (independientes):**
- `projects/erp-construccion/` - ERP Construccion INFONAVIT
- `projects/erp-vidrio-templado/` - ERP Vidrio Templado
- `projects/erp-mecanicas-diesel/` - ERP Talleres Mecanicos
- `projects/erp-retail/` - ERP Punto de Venta
- `projects/erp-clinicas/` - ERP Clinicas

**Productos derivados (en erp-suite):**
- `projects/erp-suite/apps/products/erp-basico/` - ERP Simplificado
- `projects/erp-suite/apps/products/pos-micro/` - POS Miniatura

---

## Stack Tecnológico

### Backend (`/backend`)
| Tecnología | Versión | Propósito |
|------------|---------|-----------|
| Node.js | 20+ | Runtime |
| Express.js | 4.x | Framework HTTP |
| TypeScript | 5.3+ | Lenguaje |
| TypeORM | 0.3.17 | ORM |
| JWT + bcryptjs | - | Autenticación |
| Zod, class-validator | - | Validación |
| Winston | - | Logger |
| Helmet, CORS | - | Seguridad HTTP |

### Frontend (`/frontend`)
| Tecnología | Versión | Propósito |
|------------|---------|-----------|
| React | 18 | Framework UI |
| Vite | 5.x | Build tool |
| TypeScript | 5.3+ | Lenguaje |
| Zustand | - | State management |
| Tailwind CSS | 4.x | Styling |

### Base de Datos (`/database`)
| Tecnología | Versión | Propósito |
|------------|---------|-----------|
| PostgreSQL | 15+ | Motor BD |
| RLS | - | Row-Level Security |
| uuid-ossp | - | Generación UUIDs |
| pg_trgm | - | Búsqueda fuzzy |

---

## Paths del Proyecto

```
/home/isem/workspace-v1/projects/erp-core/
├── backend/
│   ├── src/
│   │   ├── modules/           # Módulos de negocio (auth, users, etc.)
│   │   ├── shared/            # Código compartido (utils, types, constants)
│   │   ├── config/            # Configuración (database, jwt, cors)
│   │   └── middleware/        # Middlewares (auth, validation, error)
│   ├── package.json
│   ├── tsconfig.json
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── components/        # Componentes reutilizables
│   │   ├── pages/             # Páginas/Vistas
│   │   ├── stores/            # Estado global (Zustand)
│   │   ├── services/          # API clients
│   │   └── hooks/             # Custom hooks
│   ├── package.json
│   └── vite.config.ts
│
├── database/
│   ├── ddl/                   # CREATE TABLE statements
│   ├── migrations/            # Migraciones incrementales
│   ├── seeds/                 # Datos iniciales (idempotentes)
│   └── scripts/               # Scripts de utilidad
│
├── docs/                      # 517 archivos de documentación
│   ├── 00-vision-general/
│   ├── 00-analisis-referencias/
│   ├── 01-definicion-modulos/
│   ├── 02-modelado/
│   │   ├── database-design/
│   │   ├── domain-models/
│   │   └── especificaciones-tecnicas/
│   ├── 03-user-stories/       # 15 módulos MGN-*
│   ├── 90-transversal/
│   ├── 95-guias-desarrollo/
│   └── 97-adr/
│
└── orchestration/             # Sistema NEXUS
    ├── 00-guidelines/
    │   ├── CONTEXTO-PROYECTO.md      # Este archivo
    │   └── HERENCIA-DIRECTIVAS.md    # Mapeo de directivas
    ├── 01-analisis/           # Análisis de tareas
    ├── 02-planeacion/         # Planes detallados
    ├── 03-tareas/             # Descomposición de work
    ├── 04-ejecucion-logs/     # Logs de ejecución
    ├── 05-validaciones/       # Validaciones (pre/durante/post)
    │   ├── pre/
    │   ├── durante/
    │   └── post/
    ├── 06-subagentes/         # Gestión de subagentes
    ├── agentes/               # Ejecuciones por agente
    ├── directivas/            # Directivas específicas
    ├── estados/               # Estado actual de agentes
    ├── inventarios/           # Inventarios YAML
    ├── prompts/               # Prompts específicos
    ├── reportes/              # Reportes de ciclos
    ├── trazas/                # Historial de tareas
    ├── templates/             # Templates proyecto
    └── PROXIMA-ACCION.md      # Siguiente tarea
```

---

## Módulos Core (MGN-*)

Referencia: `/docs/03-user-stories/`

| Código | Módulo | Estado | Descripción |
|--------|--------|--------|-------------|
| MGN-001 | auth | En desarrollo | Autenticación JWT, OAuth, sessions |
| MGN-002 | users | En desarrollo | Gestión de usuarios CRUD |
| MGN-003 | roles | Planificado | Roles y permisos (RBAC) |
| MGN-004 | tenants | Planificado | Multi-tenancy, aislamiento |
| MGN-005 | catalogs | Planificado | Catálogos maestros genéricos |
| MGN-006 | settings | Planificado | Configuración del sistema |
| MGN-007 | audit | Planificado | Auditoría y logs |
| MGN-008 | notifications | Planificado | Sistema de notificaciones |
| MGN-009 | reports | Planificado | Reportes genéricos |
| MGN-010 | financial | Planificado | Contabilidad básica |
| MGN-011 | inventory | Planificado | Inventario básico |
| MGN-012 | purchasing | Planificado | Compras básicas |
| MGN-013 | crm | Planificado | CRM básico |
| MGN-014 | integration | Planificado | APIs de integración |

---

## Convenciones de Código

### Base de Datos (DDL)
```
Schemas:    core_{nombre}           (ej: core_auth, core_users)
Tablas:     {schema}.{nombre_plural} (ej: core_auth.users)
Columnas:   snake_case              (ej: created_at, user_id)
Índices:    idx_{tabla}_{columnas}  (ej: idx_users_email)
FK:         fk_{origen}_to_{destino} (ej: fk_users_to_tenants)
Triggers:   trg_{tabla}_{accion}    (ej: trg_users_audit)
```

**Columnas de auditoría (obligatorias):**
- `id` UUID PRIMARY KEY
- `tenant_id` UUID NOT NULL (multi-tenant)
- `created_at` TIMESTAMPTZ DEFAULT NOW()
- `updated_at` TIMESTAMPTZ DEFAULT NOW()
- `created_by` UUID REFERENCES users(id)
- `updated_by` UUID REFERENCES users(id)
- `is_active` BOOLEAN DEFAULT TRUE

### Backend (TypeScript)
```
Archivos:   kebab-case.tipo.ts      (ej: user-auth.service.ts)
Clases:     PascalCase + sufijo     (ej: UserAuthService, UserEntity)
Variables:  camelCase               (ej: userId, isActive)
Constantes: UPPER_SNAKE_CASE        (ej: MAX_LOGIN_ATTEMPTS)
Métodos:    camelCase + verbo       (ej: findById, createUser)
Interfaces: IPascalCase             (ej: IUserService)
Types:      TPascalCase             (ej: TUserRole)
```

**Estructura de módulo:**
```
modules/{nombre}/
├── {nombre}.module.ts
├── {nombre}.controller.ts
├── {nombre}.service.ts
├── {nombre}.entity.ts
├── dto/
│   ├── create-{nombre}.dto.ts
│   └── update-{nombre}.dto.ts
└── __tests__/
    └── {nombre}.service.spec.ts
```

### Frontend (React/TypeScript)
```
Componentes: PascalCase.tsx         (ej: UserProfile.tsx)
Páginas:     PascalCasePage.tsx     (ej: DashboardPage.tsx)
Hooks:       useCamelCase.ts        (ej: useAuth.ts)
Stores:      camelCase.store.ts     (ej: auth.store.ts)
Services:    camelCase.service.ts   (ej: api.service.ts)
Types:       camelCase.types.ts     (ej: user.types.ts)
```

---

## Herencia de Directivas

**Ver detalle completo en:** `HERENCIA-DIRECTIVAS.md`

### Orden de Precedencia
1. **Globales (CORE):** `/home/isem/workspace-v1/core/orchestration/directivas/`
2. **ERP-Suite:** `/home/isem/workspace-v1/projects/erp-suite/orchestration/directivas/`
3. **ERP-Core:** `./directivas/`

### Directivas Críticas
- `DIRECTIVA-FLUJO-5-FASES.md` - Flujo de trabajo obligatorio
- `DIRECTIVA-VALIDACION-DOCUMENTACION.md` - Validar contra /docs/
- `POLITICAS-USO-AGENTES.md` - Uso de agentes NEXUS
- `DIRECTIVA-DISENO-BASE-DATOS.md` - Diseño de BD

---

## Principios Core (Obligatorios)

1. **Independencia:** Todo módulo debe ser independiente y desacoplado
2. **Extensibilidad:** Las verticales EXTIENDEN, nunca modifican el core
3. **Multi-tenant:** TODA consulta debe filtrar por `tenant_id`
4. **Documentación:** Documentar ANTES de implementar
5. **Trazabilidad:** Registrar TODA tarea en `/orchestration/trazas/`
6. **Validación:** Usar flujo de 5 fases para toda tarea

---

## Flujo de 5 Fases (Obligatorio)

Toda tarea debe seguir:

| Fase | Carpeta | Entregable |
|------|---------|------------|
| 1. Análisis | `01-analisis/` | ANÁLISIS.md |
| 2. Planeación | `02-planeacion/` | PLAN.md |
| 3. Validación | `05-validaciones/pre/` | VALIDACIÓN.md |
| 4. Ejecución | `04-ejecucion-logs/` | LOGS.md |
| 5. Cierre | `05-validaciones/post/` | CIERRE.md |

---

## Referencias

| Recurso | Path |
|---------|------|
| Directivas globales | `/home/isem/workspace-v1/core/orchestration/directivas/` |
| Prompts base | `/home/isem/workspace-v1/core/orchestration/prompts/base/` |
| Patrones Odoo | `/home/isem/workspace-v1/knowledge-base/patterns/` |
| Catálogo central | `shared/catalog/` *(componentes reutilizables)* |
| Estándar docs | `/home/isem/workspace-v1/core/standards/ESTANDAR-ESTRUCTURA-DOCUMENTACION.md` |

---
*Última actualización: Diciembre 2025*