workspace-v1/projects/erp-retail/orchestration/planes/PLAN-MAESTRO-MIGRACION-RETAIL.md

# PLAN MAESTRO: Migracion, Integracion y Adaptacion ERP-Core a Retail

**Version:** 1.0.0
**Fecha:** 2025-12-18
**Autor:** Requirements-Analyst (Perfil NEXUS)
**Proyecto Base:** erp-core
**Proyecto Destino:** erp-suite/verticales/retail

---

## RESUMEN EJECUTIVO

Este documento define el plan maestro para la migracion, integracion y adaptacion del proyecto base `erp-core` hacia la vertical especializada `retail`. El proceso se divide en 5 fases con subagentes especializados para garantizar completitud y trazabilidad.

### Metricas del Proyecto

| Concepto | Valor |
|----------|-------|
| Tablas heredadas de core | 144 |
| Schemas heredados | 12 |
| Modulos retail | 10 |
| Story Points estimados | 353 |
| % Reutilizacion promedio | 45% |

---

## FASE 1: PLANEACION - ANALISIS DETALLADO

### Objetivo
Realizar un analisis exhaustivo del estado actual de erp-core y los requerimientos especificos de retail para identificar todos los componentes a migrar, extender o crear.

### Entregables

1. **ANALISIS-ERP-CORE-INVENTARIO.md**
   - Inventario completo de modulos del core
   - Estado de implementacion de cada modulo
   - Especificaciones tecnicas existentes
   - DDL implementados

2. **ANALISIS-RETAIL-REQUERIMIENTOS.md**
   - Requerimientos funcionales especificos de retail
   - Requerimientos no funcionales (offline, performance)
   - Hardware e integraciones requeridas

3. **MATRIZ-MAPEO-CORE-RETAIL.md**
   - Mapeo modulo-a-modulo entre core y retail
   - Identificacion de herencia directa (100%)
   - Identificacion de extensiones necesarias
   - Identificacion de componentes nuevos

4. **GAP-ANALYSIS-RETAIL.md**
   - Gaps funcionales por modulo
   - Gaps de especificaciones
   - Gaps de implementacion

### Subagente Especializado

```yaml
agente: Explore-Agent
tipo: subagent_type=Explore
nivel_exploracion: very thorough
prompt: |
  Realizar analisis exhaustivo del proyecto erp-core:
  1. Explorar todos los modulos en backend/src/modules/
  2. Documentar estado de cada servicio (.service.ts)
  3. Revisar DDL en database/ddl/
  4. Catalogar especificaciones en docs/
  5. Verificar inventarios existentes

  Contexto: Se migrara a vertical retail (punto de venta)
  Entregar: Inventario completo con estado de implementacion  
```

### Archivos a Analizar

| Ruta | Proposito |
|------|-----------|
| `erp-core/backend/src/modules/` | Servicios backend |
| `erp-core/database/ddl/` | Esquemas DDL |
| `erp-core/docs/` | Documentacion y especificaciones |
| `retail/docs/` | Requerimientos retail |
| `retail/orchestration/inventarios/` | Inventarios actuales |

---

## FASE 2: EJECUCION DEL ANALISIS

### Objetivo
Ejecutar el analisis planificado modulo por modulo, generando documentacion detallada de cada componente.

### Entregables por Modulo

Para cada uno de los 10 modulos de retail (RT-001 a RT-010):

1. **ANALISIS-RT-{XXX}-{nombre}.md**
   - Componentes del core que hereda
   - Extensiones requeridas
   - Componentes nuevos a crear
   - Dependencias identificadas
   - Story points ajustados

### Matriz de Analisis

| Modulo Retail | Modulos Core Relacionados | % Herencia | Analisis |
|---------------|---------------------------|------------|----------|
| RT-001 Fundamentos | MGN-001, MGN-002, MGN-003, MGN-004 | 100% | PENDIENTE |
| RT-002 POS | MGN-013 Sales | 20% | PENDIENTE |
| RT-003 Inventario | MGN-011 Inventory | 60% | PENDIENTE |
| RT-004 Compras | MGN-012 Purchase | 80% | PENDIENTE |
| RT-005 Clientes | MGN-014 CRM | 40% | PENDIENTE |
| RT-006 Precios | MGN-013 Sales (pricing) | 30% | PENDIENTE |
| RT-007 Caja | - | 10% | PENDIENTE |
| RT-008 Reportes | MGN-009 Reports | 70% | PENDIENTE |
| RT-009 E-commerce | MGN-013 Sales | 20% | PENDIENTE |
| RT-010 Facturacion | MGN-010 Financial | 60% | PENDIENTE |

### Subagentes Especializados

```yaml
# Para cada modulo ejecutar:
agente: Plan-Agent
tipo: subagent_type=Plan
prompt: |
  Analizar modulo RT-{XXX} {nombre}:

  1. HERENCIA DEL CORE:
     - Listar servicios de erp-core/{modulo_core} que aplican
     - Identificar tablas DDL que se reutilizan
     - Revisar specs transversales aplicables

  2. EXTENSIONES:
     - Campos adicionales requeridos
     - Logica de negocio adicional
     - Nuevos endpoints necesarios

  3. COMPONENTES NUEVOS:
     - Entidades especificas de retail
     - Servicios nuevos
     - Controladores nuevos

  4. DEPENDENCIAS:
     - Modulos core requeridos
     - Otros modulos retail requeridos
     - Servicios externos (PAC, hardware)

  Contexto: [Incluir documentacion del modulo retail]
  Entregar: Documento ANALISIS-RT-{XXX}.md  
```

---

## FASE 3: PLANEACION DE IMPLEMENTACIONES

### Objetivo
Crear planes de implementacion detallados para cada componente identificado en la Fase 2.

### Entregables

1. **PLAN-IMPL-DATABASE.md**
   - Orden de creacion de tablas
   - Migraciones de core requeridas
   - DDL especificos de retail
   - Indices y optimizaciones

2. **PLAN-IMPL-BACKEND.md**
   - Servicios a heredar (import directo)
   - Servicios a extender (class extends)
   - Servicios a crear (nuevos)
   - Controladores y rutas
   - Middlewares especificos

3. **PLAN-IMPL-FRONTEND.md**
   - Componentes reutilizables del core
   - Componentes especificos POS
   - PWA y modo offline
   - Integracion hardware

4. **ROADMAP-SPRINTS.md**
   - Sprints por prioridad (P0, P1, P2)
   - Dependencias entre sprints
   - Criterios de completitud

### Estructura del Plan por Capa

```yaml
database:
  sprint_1:
    - Crear schema retail
    - Crear tablas pos_sessions, pos_orders, pos_order_lines
    - Crear tablas cash_registers, cash_movements
    - Configurar RLS policies
  sprint_2:
    - Tablas branches, branch_stock
    - Tablas loyalty_cards, loyalty_transactions
    - Tablas promotions

backend:
  sprint_1:
    - Heredar AuthModule de @erp-core/auth
    - Heredar UsersModule de @erp-core/users
    - Crear POSModule
    - Crear CashModule
  sprint_2:
    - Extender InventoryModule
    - Crear LoyaltyModule
    - Crear PromotionsModule

frontend:
  sprint_1:
    - Dashboard principal
    - Pantalla POS
    - Gestion de caja
  sprint_2:
    - Inventario por sucursal
    - Clientes y fidelizacion
```

### Subagente Especializado

```yaml
agente: Plan-Agent
tipo: subagent_type=Plan
prompt: |
  Con base en los analisis de Fase 2, crear plan de implementacion:

  INPUT:
  - ANALISIS-RT-001 a RT-010
  - GAP-ANALYSIS-RETAIL
  - MATRIZ-MAPEO-CORE-RETAIL

  OUTPUT:
  - Plan de base de datos (orden DDL)
  - Plan de backend (herencia vs extension vs nuevo)
  - Plan de frontend (componentes)
  - Sprints priorizados

  Considerar:
  - Dependencias entre modulos
  - Prioridad P0 primero
  - Modo offline del POS
  - CFDI 4.0 en tiempo real  
```

---

## FASE 4: VALIDACION DE PLANEACION

### Objetivo
Validar que el plan de implementacion cubre todos los componentes identificados y que no faltan dependencias.

### Entregables

1. **VALIDACION-COMPLETITUD.md**
   - Checklist de todos los objetos a implementar
   - Verificacion de dependencias cruzadas
   - Objetos faltantes identificados

2. **DEPENDENCY-GRAPH-VALIDADO.yml**
   - Grafo de dependencias actualizado
   - Orden de implementacion validado
   - Ciclos detectados (si existen)

3. **IMPACTO-CAMBIOS.md**
   - Componentes impactados por cada cambio
   - Propagacion de cambios en cascada
   - Riesgos identificados

### Checklist de Validacion

```yaml
validacion_database:
  - [ ] Todas las tablas de ANALISIS tienen DDL en PLAN-IMPL
  - [ ] FK apuntan a tablas existentes o en plan
  - [ ] RLS policies definidas para todas las tablas
  - [ ] Indices de rendimiento para POS (<100ms)

validacion_backend:
  - [ ] Cada servicio tiene su controlador
  - [ ] Cada endpoint tiene ruta definida
  - [ ] Imports de core son resolubles
  - [ ] No hay dependencias circulares

validacion_frontend:
  - [ ] Cada pantalla tiene componentes definidos
  - [ ] PWA manifest configurado
  - [ ] Service workers para offline
  - [ ] Integracion hardware documentada

validacion_herencia:
  - [ ] Modulos 100% herencia no duplican codigo
  - [ ] Extensiones usan 'extends' correctamente
  - [ ] Specs transversales aplicadas
```

### Subagente Especializado

```yaml
agente: General-Purpose-Agent
tipo: subagent_type=general-purpose
prompt: |
  Validar completitud del plan de implementacion:

  1. VERIFICAR OBJETOS:
     - Leer ANALISIS-RT-* (todos los modulos)
     - Leer PLAN-IMPL-* (todos los planes)
     - Cruzar: cada objeto analizado tiene plan

  2. VERIFICAR DEPENDENCIAS:
     - Construir grafo de dependencias
     - Detectar objetos huerfanos
     - Detectar ciclos

  3. VERIFICAR IMPACTO:
     - Para cada cambio en core, que retail impacta
     - Para cada nuevo en retail, que core requiere

  4. GENERAR REPORTE:
     - Lista de gaps encontrados
     - Recomendaciones de ajuste
     - Plan de correccion

  Entregar: VALIDACION-COMPLETITUD.md  
```

---

## FASE 5: EJECUCION DE IMPLEMENTACIONES

### Objetivo
Ejecutar las implementaciones segun el plan validado, usando subagentes especializados por capa.

### Subagentes por Dominio

#### Database-Agent

```yaml
agente: Database-Agent
prompt: |
  Implementar DDL para retail segun PLAN-IMPL-DATABASE:

  CONTEXTO:
  - Schema: retail
  - Herencia: schemas auth, core, inventory, sales de erp-core
  - Variable RLS: app.current_tenant_id

  ARCHIVOS A CREAR/MODIFICAR:
  - database/init/03-retail-tables.sql (completar)
  - database/init/04-retail-functions.sql
  - database/init/05-retail-triggers.sql

  VALIDAR:
  - FK validas a tablas de core
  - RLS en todas las tablas
  - Indices para performance POS  
```

#### Backend-Agent

```yaml
agente: Backend-Agent
prompt: |
  Implementar backend segun PLAN-IMPL-BACKEND:

  MODULOS A CREAR:
  - src/modules/pos/
  - src/modules/cash/
  - src/modules/loyalty/
  - src/modules/promotions/

  MODULOS A HEREDAR:
  - Importar @erp-core/auth
  - Importar @erp-core/users
  - Importar @erp-core/inventory (extender)

  PATRON:
  - NestJS con TypeORM
  - Controllers + Services + Entities
  - DTOs para validacion  
```

#### Frontend-Agent

```yaml
agente: Frontend-Agent
prompt: |
  Implementar frontend segun PLAN-IMPL-FRONTEND:

  STACK:
  - React 18 + TypeScript
  - Vite + PWA plugin
  - Tailwind CSS
  - Zustand para estado

  PANTALLAS PRIORITARIAS:
  1. POS (punto de venta) - offline-first
  2. Dashboard de ventas
  3. Gestion de caja
  4. Inventario por sucursal

  CONSIDERACIONES:
  - Service workers para offline
  - IndexedDB para cache local
  - Sincronizacion con backend  
```

### Control de Progreso

| Sprint | Modulos | Estado | % |
|--------|---------|--------|---|
| Sprint 1 | RT-001, RT-002, RT-007 | PENDIENTE | 0% |
| Sprint 2 | RT-003, RT-004, RT-010 | PENDIENTE | 0% |
| Sprint 3 | RT-005, RT-006 | PENDIENTE | 0% |
| Sprint 4 | RT-008, RT-009 | PENDIENTE | 0% |

---

## CRONOGRAMA DE FASES

| Fase | Descripcion | Estado | Dependencias |
|------|-------------|--------|--------------|
| F1 | Planeacion - Analisis Detallado | **SIGUIENTE** | - |
| F2 | Ejecucion del Analisis | PENDIENTE | F1 |
| F3 | Plan de Implementaciones | PENDIENTE | F2 |
| F4 | Validacion de Plan | PENDIENTE | F3 |
| F5 | Ejecucion de Implementaciones | PENDIENTE | F4 |

---

## ARCHIVOS DE SOPORTE

### Estructura de Carpetas para Entregables

```
retail/orchestration/planes/
├── PLAN-MAESTRO-MIGRACION-RETAIL.md  (este documento)
├── fase-1-analisis/
│   ├── ANALISIS-ERP-CORE-INVENTARIO.md
│   ├── ANALISIS-RETAIL-REQUERIMIENTOS.md
│   ├── MATRIZ-MAPEO-CORE-RETAIL.md
│   └── GAP-ANALYSIS-RETAIL.md
├── fase-2-analisis-modulos/
│   ├── ANALISIS-RT-001-fundamentos.md
│   ├── ANALISIS-RT-002-pos.md
│   ├── ANALISIS-RT-003-inventario.md
│   ├── ANALISIS-RT-004-compras.md
│   ├── ANALISIS-RT-005-clientes.md
│   ├── ANALISIS-RT-006-precios.md
│   ├── ANALISIS-RT-007-caja.md
│   ├── ANALISIS-RT-008-reportes.md
│   ├── ANALISIS-RT-009-ecommerce.md
│   └── ANALISIS-RT-010-facturacion.md
├── fase-3-implementacion/
│   ├── PLAN-IMPL-DATABASE.md
│   ├── PLAN-IMPL-BACKEND.md
│   ├── PLAN-IMPL-FRONTEND.md
│   └── ROADMAP-SPRINTS.md
├── fase-4-validacion/
│   ├── VALIDACION-COMPLETITUD.md
│   ├── DEPENDENCY-GRAPH-VALIDADO.yml
│   └── IMPACTO-CAMBIOS.md
└── fase-5-ejecucion/
    └── TRAZA-EJECUCION.md
```

---

## PROXIMA ACCION

**Fase Actual:** FASE 1 - Planeacion
**Accion Inmediata:** Ejecutar analisis exhaustivo de erp-core con Explore-Agent

```bash
# Comando para iniciar Fase 1:
# Usar subagente Explore con nivel "very thorough"
# Target: /projects/erp-suite/apps/erp-core/
```

---

**Documento creado:** 2025-12-18
**Sistema:** NEXUS + SIMCO v2.2.0
**Perfil:** Requirements-Analyst