erp-retail/orchestration/planes/fase-1-analisis/ANALISIS-RETAIL-REQUERIMIENTOS.md

# ANALISIS RETAIL - REQUERIMIENTOS COMPLETOS

**Fecha:** 2025-12-18
**Fase:** 1 - Planeacion
**Objetivo:** Documentar todos los requerimientos especificos de la vertical retail

---

## RESUMEN EJECUTIVO

| Metrica | Valor |
|---------|-------|
| **Modulos** | 10 |
| **Story Points Totales** | 353 SP |
| **Tablas Heredadas (Core)** | ~144 tablas |
| **Tablas Especificas Retail** | ~26 tablas |
| **Herencia Promedio** | 45% |
| **Performance Requerido** | < 100ms por transaccion |
| **Disponibilidad** | 99.9% |

---

## 1. MODULOS RETAIL (RT-001 a RT-010)

### 1.1 Resumen de Modulos

| Codigo | Nombre | Herencia | SP | Prioridad | Estado |
|--------|--------|----------|----:|-----------|--------|
| RT-001 | Fundamentos | 100% | 0 | P0 | PLANIFICADO |
| RT-002 | POS | 20% | 55 | P0 | PLANIFICADO |
| RT-003 | Inventario | 60% | 42 | P0 | PLANIFICADO |
| RT-004 | Compras | 80% | 38 | P0 | PLANIFICADO |
| RT-005 | Clientes | 40% | 34 | P1 | PLANIFICADO |
| RT-006 | Precios | 30% | 36 | P0 | PLANIFICADO |
| RT-007 | Caja | 10% | 28 | P0 | PLANIFICADO |
| RT-008 | Reportes | 70% | 30 | P1 | PLANIFICADO |
| RT-009 | E-commerce | 20% | 55 | P2 | PLANIFICADO |
| RT-010 | Facturacion | 60% | 35 | P0 | PLANIFICADO |

---

## 2. DETALLE POR MODULO

### RT-001: Fundamentos (0 SP)

**Descripcion:** Autenticacion y usuarios por sucursal
**Herencia:** 100% del core

**Funcionalidades:**
- Autenticacion JWT multi-tenancy
- Usuarios segregados por sucursal
- Roles: Cajero, Supervisor, Gerente, Admin
- RBAC completo

**Dependencias Core:** MGN-001 Auth, MGN-002 Users, MGN-003 Roles

---

### RT-002: Punto de Venta - POS (55 SP)

**Descripcion:** Terminal de venta con operacion offline
**Herencia:** 20%

**Funcionalidades Criticas:**

1. **Venta Rapida**
   - Escaneo codigo de barras (< 500ms)
   - Busqueda producto por nombre/SKU
   - Carrito en tiempo real
   - Calculo totales < 10ms

2. **Formas de Pago**
   - Efectivo con calculo de cambio
   - Tarjeta credito/debito
   - Pagos mixtos
   - Transferencia
   - Credito interno

3. **Modo Offline (PWA)**
   - Funcionamiento 24+ horas sin conexion
   - Cache local IndexedDB
   - Sincronizacion automatica al reconectar
   - Cola de transacciones

4. **Hardware**
   - Lector codigo barras (USB HID)
   - Impresora termica (ESC/POS)
   - Terminal bancaria
   - Cajon de dinero

5. **Descuentos**
   - Porcentuales y monto fijo
   - Promociones automaticas
   - Autorizacion supervisor

**Performance Requerido:**
| Operacion | Objetivo |
|-----------|----------|
| Busqueda producto | < 50ms |
| Calculo totales | < 10ms |
| Registro venta | < 100ms |
| Cierre venta | < 3s |

---

### RT-003: Inventario Multi-Sucursal (42 SP)

**Descripcion:** Control de stock distribuido
**Herencia:** 60%

**Funcionalidades:**

1. **Consulta Stock**
   - Stock por sucursal en tiempo real
   - Stock disponible vs reservado

2. **Transferencias**
   - Solicitud desde tienda
   - Estados: draft → pending → in_transit → received
   - Confirmacion de recepcion

3. **Recepcion Mercancia**
   - Validacion contra OC
   - Registro faltantes/sobrantes

4. **Alertas Reorden**
   - Stock minimo automatico
   - Por sucursal

5. **Conteos Ciclicos**
   - Conteo ciego
   - Clasificacion ABC
   - Registro diferencias

6. **Kardex**
   - Historial completo (2 anos)
   - Trazabilidad por usuario

---

### RT-004: Compras y Reabastecimiento (38 SP)

**Descripcion:** Gestion centralizada de compras
**Herencia:** 80%

**Funcionalidades:**

1. **Sugerencias Automaticas**
   - Basadas en stock minimo
   - Calculo punto de reorden

2. **Ordenes de Compra**
   - Estados: borrador → confirmada → recibida
   - Envio automatico por email

3. **Recepcion**
   - Validacion contra OC
   - Actualizacion de stock

4. **Gestion Proveedores**
   - Catalogo con lead times
   - Historico de compras

---

### RT-005: Clientes y Programa de Lealtad (34 SP)

**Descripcion:** CRM y fidelizacion
**Herencia:** 40%

**Funcionalidades:**

1. **Registro Cliente**
   - Datos minimos en POS
   - Busqueda por telefono/email

2. **Programa de Puntos**
   - Acumulacion: 1 punto por $10
   - Canje: 100 puntos = $10
   - Puntos extra promocionales

3. **Niveles Membresia**
   - BRONCE: 0-999 pts/ano (1x)
   - PLATA: 1000-4999 pts/ano (1.5x)
   - ORO: 5000+ pts/ano (2x)

4. **Historial Compras**
   - 3 anos minimo
   - Accesible en backoffice

---

### RT-006: Precios y Promociones (36 SP)

**Descripcion:** Motor de reglas de precios
**Herencia:** 30%

**Funcionalidades:**

1. **Listas de Precios**
   - Por canal (tienda, online)
   - Por sucursal
   - Por cliente

2. **Tipos de Promociones**
   - Descuento porcentual
   - Descuento monto fijo
   - NxM (3x2)
   - Por volumen
   - Cupones

3. **Motor de Reglas**
   - Evaluacion por prioridad
   - No acumulables
   - Calculo < 100ms

---

### RT-007: Caja - Arqueos y Cortes (28 SP)

**Descripcion:** Control de efectivo
**Herencia:** 10% (casi nuevo)

**Funcionalidades:**

1. **Sesiones de Caja**
   - Apertura con fondo inicial
   - Estados: opening → open → closing → closed

2. **Movimientos Efectivo**
   - Retiros (deposito banca)
   - Ingresos (cambio)
   - Motivo documentado

3. **Arqueos Parciales**
   - Sin cerrar caja
   - Validar diferencias

4. **Corte de Caja**
   - Conteo fisico
   - Declaracion por denominacion
   - Calculo diferencias

5. **Auditoria**
   - Historial 1 ano minimo
   - Responsabilidad por cajero

---

### RT-008: Reportes y Dashboard (30 SP)

**Descripcion:** Analytics y dashboards
**Herencia:** 70%

**Funcionalidades:**

1. **Dashboard Principal**
   - Ventas del dia
   - Transacciones
   - Ticket promedio
   - Ventas por hora

2. **Reportes Ventas**
   - Por sucursal
   - Por categoria
   - Por cajero
   - Comparativo periodos

3. **Analisis Productos**
   - Top 5 mas vendidos
   - Stock muerto
   - Clasificacion ABC

4. **Exportacion**
   - Excel, PDF

---

### RT-009: E-commerce (55 SP)

**Descripcion:** Tienda online integrada
**Herencia:** 20%

**Funcionalidades:**

1. **Catalogo Online**
   - Navegacion con filtros
   - Stock en tiempo real

2. **Carrito y Checkout**
   - Carrito persistente
   - Validacion disponibilidad

3. **Formas de Pago**
   - Stripe/Conekta
   - Paypal/MercadoPago
   - Puntos de lealtad

4. **Entrega**
   - Envio a domicilio
   - Pickup en tienda

5. **Gestion Pedidos**
   - Estados: pendiente → pagado → enviado → entregado

---

### RT-010: Facturacion CFDI 4.0 (35 SP)

**Descripcion:** Comprobantes fiscales
**Herencia:** 60%

**Funcionalidades:**

1. **Facturacion POS**
   - Generacion al cerrar venta
   - Timbrado < 5 segundos
   - PDF + XML

2. **Factura Publico General**
   - RFC generico XAXX010101000

3. **Portal Autofactura**
   - Cliente ingresa folio
   - Timbrado automatico

4. **Notas de Credito**
   - Por devolucion
   - Reversion IVA

5. **Cancelacion**
   - Dentro de plazo legal
   - Con motivo

---

## 3. REQUERIMIENTOS ESPECIALES

### 3.1 Modo Offline

| Aspecto | Requerimiento |
|---------|---------------|
| Duracion | 24+ horas sin conexion |
| Almacenamiento | IndexedDB (> 50MB) |
| Sincronizacion | < 5 minutos al reconectar |
| Transacciones | No perder nunca |
| Cache | Productos, precios, clientes frecuentes |

### 3.2 Integracion Hardware

| Dispositivo | Protocolo | Conexion |
|------------|-----------|----------|
| Impresora tickets | ESC/POS | USB/Red |
| Lector codigo barras | USB HID | USB |
| Terminal bancaria | ISO 8583 | USB/Red |
| Cajon dinero | Pulso via impresora | RJ-11 |

### 3.3 Performance

| Operacion | Objetivo | Alerta |
|-----------|----------|--------|
| Busqueda producto | < 50ms | > 100ms |
| Calculo totales | < 10ms | > 20ms |
| Registro venta | < 100ms | > 200ms |
| Venta completa | < 30s | > 60s |
| Dashboard carga | < 3s | > 5s |

### 3.4 CFDI 4.0

| Aspecto | Requerimiento |
|---------|---------------|
| Timbrado | < 5 segundos |
| PAC respaldo | Configurado |
| Almacenamiento | 5 anos minimo |
| Cancelacion | Dentro de 30 dias |

---

## 4. DDL EXISTENTE

### 4.1 Archivo: 03-retail-tables.sql (723 lineas)

**ENUMs:**
- pos_session_status
- pos_order_status
- payment_method
- cash_movement_type
- transfer_status
- promotion_type

**Tablas (26):**
- branches
- cash_registers
- pos_sessions
- pos_orders
- pos_order_lines
- pos_payments
- cash_movements
- branch_stock
- stock_transfers
- stock_transfer_lines
- product_barcodes
- promotions
- promotion_products
- loyalty_programs
- loyalty_cards
- loyalty_transactions

---

## 5. DEPENDENCIAS ENTRE MODULOS

```
RT-001 (Fundamentos) ◄─── Base de todo
    │
    ├─► RT-002 (POS)
    │   └─ Requiere: RT-006 precios, RT-003 inventario
    │
    ├─► RT-003 (Inventario) ◄─► RT-004 (Compras)
    │
    ├─► RT-005 (Clientes)
    │   └─ Integra con: RT-002 POS
    │
    ├─► RT-006 (Precios)
    │   └─ Base para: RT-002, RT-009
    │
    ├─► RT-007 (Caja)
    │   └─ Requiere: RT-002 POS
    │
    ├─► RT-008 (Reportes)
    │   └─ Requiere: Todos los anteriores
    │
    ├─► RT-009 (E-commerce)
    │   └─ Requiere: RT-003, RT-005, RT-006
    │
    └─► RT-010 (Facturacion)
        └─ Requiere: RT-002, RT-009
```

---

## 6. SPRINTS SUGERIDOS

| Sprint | Modulos | Semanas |
|--------|---------|---------|
| 1-2 | RT-001 (setup) | 1-2 |
| 3-4 | RT-006 (precios) | 3-4 |
| 5-8 | RT-002 (POS) + RT-003 (inventario) | 5-8 |
| 9-10 | RT-004 (compras) | 9-10 |
| 11-12 | RT-007 (caja) | 11-12 |
| 13-14 | RT-005 (clientes) + RT-008 (reportes) | 13-14 |
| 15-18 | RT-009 (e-commerce) | 15-18 |
| 19-20 | RT-010 (facturacion) | 19-20 |

---

**Documento generado:** 2025-12-18
**Fase:** 1 - Planeacion - Analisis Detallado
**Estado:** COMPLETO