# _MAP: MAI-004 - Compras e Inventarios

**Epica:** MAI-004
**Nombre:** Compras e Inventarios
**Fase:** 1 - Alcance Inicial
**Presupuesto:** $22,000 MXN
**Story Points:** 48 SP
**Estado:** Documentado
**Sprints:** Sprint 11-14 (Semanas 16.5-22)
**Prioridad:** P1 - Alta
**Ultima actualizacion:** 2025-12-06

---

## Proposito

Implementar sistema completo de gestion de compras e inventarios para construccion con:
- Catalogo de proveedores con calificacion automatica
- Cotizaciones (RFQ) multi-proveedor con comparativo
- Requisiciones y ordenes de compra con flujos de aprobacion
- Inventarios multi-almacen con valorizacion PEPS
- Kardex y analisis de consumo vs presupuesto
- **Integracion con app movil MOB-002 (Almacenista)**

**Justificacion:** Control eficiente de compras e inventarios es critico para optimizar costos, prevenir paros de obra y mantener exactitud en stock desde el inicio de cualquier proyecto.

**Reutilizacion Core:** 80% (concepto de gestion de inventarios adaptado)

---

## Contenido

### Requerimientos Funcionales (4)

| ID | Archivo | Titulo | Estado |
|----|---------|--------|--------|
| RF-PURCH-001 | [RF-PURCH-001-catalogo-proveedores.md](./requerimientos/RF-PURCH-001-catalogo-proveedores.md) | Catalogo de Proveedores y Cotizaciones | Documentado |
| RF-PURCH-002 | [RF-PURCH-002-requisiciones-ordenes-compra.md](./requerimientos/RF-PURCH-002-requisiciones-ordenes-compra.md) | Requisiciones y Ordenes de Compra | Documentado |
| RF-PURCH-003 | [RF-PURCH-003-almacenes-inventarios.md](./requerimientos/RF-PURCH-003-almacenes-inventarios.md) | Almacenes y Control de Inventarios | Documentado |
| RF-PURCH-004 | [RF-PURCH-004-kardex-alertas.md](./requerimientos/RF-PURCH-004-kardex-alertas.md) | Kardex y Alertas de Stock | Documentado |

### Especificaciones Tecnicas (4)

| ID | Archivo | Titulo | RF | Estado |
|----|---------|--------|-------|--------|
| ET-PURCH-001 | [ET-PURCH-001-implementacion-proveedores.md](./especificaciones/ET-PURCH-001-implementacion-proveedores.md) | Implementacion de Proveedores | RF-PURCH-001 | Documentado |
| ET-PURCH-002 | [ET-PURCH-002-implementacion-requisiciones-ordenes.md](./especificaciones/ET-PURCH-002-implementacion-requisiciones-ordenes.md) | Implementacion de Requisiciones y OCs | RF-PURCH-002 | Documentado |
| ET-PURCH-003 | [ET-PURCH-003-implementacion-almacenes.md](./especificaciones/ET-PURCH-003-implementacion-almacenes.md) | Implementacion de Almacenes | RF-PURCH-003 | Documentado |
| ET-PURCH-004 | [ET-PURCH-004-implementacion-kardex-alertas.md](./especificaciones/ET-PURCH-004-implementacion-kardex-alertas.md) | Implementacion de Kardex y Alertas | RF-PURCH-004 | Documentado |

### Historias de Usuario (8)

| ID | Archivo | Titulo | SP | Sprint | Estado |
|----|---------|--------|----|--------|--------|
| US-PURCH-001 | [US-PURCH-001-registro-proveedor.md](./historias-usuario/US-PURCH-001-registro-proveedor.md) | Registro de Proveedor | 5 | 11 | Documentado |
| US-PURCH-002 | [US-PURCH-002-solicitud-cotizaciones.md](./historias-usuario/US-PURCH-002-solicitud-cotizaciones.md) | Solicitar Cotizaciones (RFQ) | 8 | 11 | Documentado |
| US-PURCH-003 | [US-PURCH-003-crear-requisicion-obra.md](./historias-usuario/US-PURCH-003-crear-requisicion-obra.md) | Crear Requisicion desde Obra | 5 | 12 | Documentado |
| US-PURCH-004 | [US-PURCH-004-aprobar-generar-orden-compra.md](./historias-usuario/US-PURCH-004-aprobar-generar-orden-compra.md) | Aprobar y Generar Orden de Compra | 8 | 12 | Documentado |
| US-PURCH-005 | [US-PURCH-005-recibir-material-almacen.md](./historias-usuario/US-PURCH-005-recibir-material-almacen.md) | Recibir Material en Almacen | 5 | 12 | Documentado |
| US-PURCH-006 | [US-PURCH-006-control-almacenes-movimientos.md](./historias-usuario/US-PURCH-006-control-almacenes-movimientos.md) | Control de Almacenes y Movimientos | 7 | 13 | Documentado |
| US-PURCH-007 | [US-PURCH-007-kardex-analisis-consumo.md](./historias-usuario/US-PURCH-007-kardex-analisis-consumo.md) | Kardex y Analisis de Consumo | 5 | 13 | Documentado |
| US-PURCH-008 | [US-PURCH-008-dashboard-inventarios-alertas.md](./historias-usuario/US-PURCH-008-dashboard-inventarios-alertas.md) | Dashboard de Inventarios y Alertas | 5 | 14 | Documentado |

**Total Story Points:** 48 SP

**Distribucion por Sprint:**
- Sprint 11 (13 SP): Proveedores + RFQ + Comparativo
- Sprint 12 (18 SP): Requisiciones + OC + Recepcion
- Sprint 13 (12 SP): Almacenes + Kardex
- Sprint 14 (5 SP): Dashboard + Alertas

### Implementacion

Inventarios de trazabilidad:
- [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) - Matriz completa de trazabilidad
- [DATABASE.yml](./implementacion/DATABASE.yml) - Objetos de base de datos
- [BACKEND.yml](./implementacion/BACKEND.yml) - Modulos backend
- [FRONTEND.yml](./implementacion/FRONTEND.yml) - Componentes frontend
- [MOBILE.yml](./implementacion/MOBILE.yml) - Especificaciones de app movil MOB-002

### Pruebas

Documentacion de testing:
- [TEST-PLAN.md](./pruebas/TEST-PLAN.md) - Plan de pruebas
- [TEST-CASES.md](./pruebas/TEST-CASES.md) - Casos de prueba
- [INTEGRATION-TESTS.md](./pruebas/INTEGRATION-TESTS.md) - Tests de integracion

---

## Referencias

- **README:** [README.md](./README.md) - Descripcion detallada de la epica
- **Resumen:** [RESUMEN-EPICA-MAI-004.md](./RESUMEN-EPICA-MAI-004.md) - Resumen ejecutivo completo
- **Fase 1:** [../README.md](../README.md) - Informacion de la fase completa
- **Roadmap:** [../ROADMAP-DETALLADO.md](../ROADMAP-DETALLADO.md) - Sprints 11-14

---

## Metricas

| Metrica | Valor |
|---------|-------|
| **Presupuesto estimado** | $22,000 MXN |
| **Presupuesto target** | $22,000 MXN ±5% |
| **Story Points estimados** | 48 SP |
| **Duracion estimada** | 4 sprints (8 semanas) |
| **Reutilizacion Core** | 80% |
| **Integraciones externas** | 0 (internas: 4) |
| **RF a implementar** | 4/4 |
| **ET a implementar** | 4/4 |
| **US a completar** | 8/8 |

---

## Modulos Afectados

### Base de Datos

**Schemas:** `purchasing_management`, `inventory_management`

**Tablas principales (19 tablas):**

purchasing_management:
- `suppliers` - Catalogo de proveedores
- `supplier_ratings` - Calificaciones de proveedores
- `rfqs` - Solicitudes de cotizacion
- `quotes` - Cotizaciones recibidas
- `requisitions` - Requisiciones de material
- `requisition_items` - Detalle de requisiciones
- `requisition_approvals` - Flujo de aprobaciones
- `purchase_orders` - Ordenes de compra
- `purchase_order_items` - Detalle de OCs
- `purchase_order_receipts` - Recepciones de material
- `invoices` - Facturas de proveedores

inventory_management:
- `warehouses` - Almacenes por obra
- `warehouse_locations` - Ubicaciones en almacen
- `inventory_stock` - Existencias actuales
- `inventory_lots` - Lotes para PEPS
- `inventory_movements` - Movimientos de inventario
- `stock_alerts` - Alertas de inventario
- `consumption_analysis` - Analisis de consumo
- `material_stock_config` - Configuracion de umbrales

**Funciones y Triggers:**
- Calculo de scoring de proveedores (0-100)
- Valorizacion PEPS automatica
- Actualizacion de stock en movimientos
- Generacion automatica de alertas
- Calculo de consumo vs presupuesto

**ENUMs:**
- `supplier_status` (active, suspended, blacklisted)
- `rfq_status` (draft, sent, closed)
- `requisition_status` (draft, sent, approved, rejected, converted)
- `purchase_order_status` (draft, sent, confirmed, received_partial, received_total, cancelled)
- `movement_type` (entry, exit, transfer, adjustment)
- `alert_type` (stock_min, reorder_point, overconsumption, no_movement, stock_max)

### Backend

**Modulo:** `purchases` + `inventory`
**Path:** `apps/backend/src/modules/`

**Services:**

purchases:
- `SupplierService` - CRUD y calificacion de proveedores
- `RFQService` - Gestion de cotizaciones
- `QuoteService` - Comparacion y scoring
- `RequisitionService` - Requisiciones con aprobaciones
- `PurchaseOrderService` - Ordenes de compra y recepciones
- `InvoiceService` - Registro de facturas

inventory:
- `WarehouseService` - Gestion de almacenes
- `InventoryService` - Control de stock
- `MovementService` - Entradas, salidas, traspasos
- `KardexService` - Trazabilidad de movimientos
- `AlertService` - Alertas inteligentes
- `AnalysisService` - Consumo vs presupuesto

**CRON Jobs:**
- Analisis diario de consumo
- Generacion de alertas automaticas
- Actualizacion de calificaciones de proveedores
- Deteccion de materiales sin movimiento

### Frontend Web

**Features:** `purchases`, `inventory`
**Path:** `apps/frontend/src/features/`

**Componentes principales:**

Proveedores y Cotizaciones:
- `SuppliersListView` - Lista de proveedores
- `SupplierFormModal` - Alta/edicion de proveedor
- `SupplierDetailView` - Detalle con historial
- `RFQFormModal` - Crear solicitud de cotizacion
- `QuoteComparisonView` - Comparativo visual de cotizaciones
- `SupplierRatingWidget` - Calificacion 0-100

Requisiciones y OCs:
- `RequisitionsListView` - Lista de requisiciones
- `RequisitionFormModal` - Crear requisicion
- `RequisitionApprovalPanel` - Panel de aprobaciones
- `PurchaseOrdersListView` - Lista de ordenes
- `PurchaseOrderFormModal` - Generar OC
- `PurchaseOrderPDFPreview` - Vista previa de PDF
- `ReceiptModal` - Registro de recepciones

Inventarios:
- `WarehousesListView` - Lista de almacenes
- `WarehouseDetailView` - Detalle con ubicaciones
- `InventoryStockTable` - Existencias actuales
- `MovementFormModal` - Registro de movimientos
- `KardexView` - Trazabilidad por material
- `StockAlertsPanel` - Panel de alertas
- `ConsumptionAnalysisView` - Analisis vs presupuesto
- `InventoryDashboard` - Dashboard ejecutivo

**Guards:** AuthGuard, RoleGuard (permisos especificos)

### App Movil (React Native)

**App:** MOB-002 - Almacenista
**Plataformas:** Android, iOS
**Framework:** React Native + Expo

**Features:** `warehouse-operations`
**Path:** `apps/mobile/almacen/src/features/`

**Pantallas principales:**

1. **Login**
   - Autenticacion con credenciales ERP
   - Modo offline con cache de credenciales

2. **Selector de Obra/Almacen**
   - Lista de obras asignadas al almacenista
   - Seleccion de almacen activo

3. **Dashboard de Almacen**
   - Resumen de existencias
   - Solicitudes de salida pendientes
   - Alertas de stock bajo
   - Recepciones programadas

4. **Recepcion de Material**
   - Busqueda de orden de compra
   - Escaneo de codigo de barras/QR
   - Registro de cantidad recibida
   - Captura de foto de evidencia
   - Asignacion de ubicacion
   - Firma digital del proveedor

5. **Salida de Material**
   - Lista de solicitudes pendientes
   - Verificacion de existencias
   - Registro de cantidad entregada
   - Firma digital del receptor
   - Vinculacion con partida presupuestal

6. **Consulta de Inventario**
   - Busqueda de materiales
   - Existencias en tiempo real
   - Ubicacion en almacen
   - Movimientos recientes

7. **Inventario Fisico**
   - Modo de conteo ciclico
   - Escaneo de materiales
   - Registro de cantidades contadas
   - Generacion de diferencias

8. **Transferencias**
   - Transferencias entre almacenes
   - Seleccion de destino
   - Registro de salida/entrada
   - Tracking de transferencias en transito

9. **Historial de Movimientos**
   - Listado de movimientos del dia
   - Filtros por tipo de movimiento
   - Estado de sincronizacion
   - Reenvio de movimientos fallidos

**Funcionalidades especiales:**

- **Modo Offline:** SQLite local con cola de sincronizacion
- **Escaner:** Codigos de barras y QR (react-native-camera)
- **Firma Digital:** Canvas para captura de firmas
- **Geolocalizacion:** GPS en movimientos
- **Fotos:** Captura de evidencia fotografica
- **Push Notifications:** Alertas de solicitudes pendientes
- **Sincronizacion:** Background sync automatica

**Tecnologias:**
- React Native 0.73+
- Expo 50
- WatermelonDB (offline storage)
- Zustand (state management)
- Axios (API sync)
- expo-camera (escaneo)
- expo-location (GPS)
- Firebase Cloud Messaging (push)

**Validaciones en App:**

| Validacion | Descripcion | Accion si falla |
|------------|-------------|-----------------|
| **Existencias** | Verificar stock disponible antes de salida | Bloquear salida, mostrar disponible |
| **Orden de compra** | Validar OC activa en recepciones | Advertencia, permitir recepcion manual |
| **Ubicacion** | Material debe tener ubicacion asignada | Solicitar ubicacion antes de guardar |
| **Cantidades** | No permitir cantidades negativas | Validacion en formulario |
| **Firma digital** | Requerir firma en entregas | Bloquear guardado sin firma |

**Modo Offline:**

Capacidades:
- Almacenar hasta 1000 movimientos en cola
- Cache de inventario actualizado diariamente
- Cache de ordenes de compra pendientes
- Indicador visual de movimientos pendientes de sincronizacion

Sincronizacion:
- Automatica al detectar conexion
- Manual por boton "Sincronizar ahora"
- Resolucion de conflictos (ultimo gana)
- Retry automatico con backoff exponencial

---

## Flujo de Documentacion RF → ET → US → Codigo

### Ejemplo: Requisiciones de Material

```
RF-PURCH-002: Requisiciones y Ordenes de Compra
    ↓
ET-PURCH-002: Implementacion de Requisiciones y OCs
    ├─ Schemas SQL (requisitions, requisition_items, requisition_approvals)
    ├─ TypeORM Entities (Requisition, RequisitionItem, RequisitionApproval)
    ├─ Services (RequisitionService con logica de aprobaciones)
    ├─ Controllers (RequisitionController con endpoints REST)
    └─ React Components (RequisitionFormModal, RequisitionApprovalPanel)
    ↓
US-PURCH-003: Crear Requisicion desde Obra (5 SP)
    ├─ Frontend: RequisitionFormModal con selector de materiales
    ├─ Backend: POST /api/v1/requisiciones
    ├─ Database: INSERT en requisitions + requisition_items
    └─ Notificacion: Email al aprobador nivel 1
    ↓
US-PURCH-004: Aprobar y Generar Orden de Compra (8 SP)
    ├─ Frontend: RequisitionApprovalPanel + PurchaseOrderFormModal
    ├─ Backend: POST /api/v1/requisiciones/:id/aprobar
    ├─ Backend: POST /api/v1/ordenes-compra (conversion automatica)
    ├─ Database: UPDATE requisition_status, INSERT purchase_orders
    └─ PDF: Generacion de OC para proveedor
    ↓
Codigo Implementado:
    ├─ apps/backend/src/modules/purchases/
    │   ├─ entities/requisition.entity.ts
    │   ├─ services/requisition.service.ts
    │   ├─ controllers/requisition.controller.ts
    │   └─ dto/create-requisition.dto.ts
    ├─ apps/frontend/src/features/purchases/
    │   ├─ components/RequisitionFormModal.tsx
    │   ├─ components/RequisitionApprovalPanel.tsx
    │   └─ hooks/useRequisitions.ts
    └─ apps/database/migrations/
        └─ 003_create_requisitions_schema.sql
```

### Ejemplo: Movimientos de Inventario (App Movil)

```
RF-PURCH-003: Almacenes y Control de Inventarios
    +
RF-PURCH-004: Kardex y Alertas de Stock
    ↓
ET-PURCH-003: Implementacion de Almacenes
    +
ET-PURCH-004: Implementacion de Kardex y Alertas
    ├─ Schemas SQL (warehouses, inventory_stock, inventory_movements, inventory_lots)
    ├─ TypeORM Entities (Warehouse, InventoryStock, InventoryMovement)
    ├─ Services (InventoryService, MovementService, AlertService)
    ├─ Triggers (actualizacion automatica de stock con PEPS)
    └─ API Endpoints para app movil
    ↓
US-PURCH-005: Recibir Material en Almacen (5 SP)
    ├─ App Movil: ReceptionScreen con escaneo QR
    ├─ Backend: POST /api/v1/inventario/entradas
    ├─ Database: INSERT inventory_movements + UPDATE inventory_stock
    ├─ PEPS: Creacion de nuevo lote (inventory_lots)
    └─ Notificacion: Push al residente de obra
    ↓
US-PURCH-006: Control de Almacenes y Movimientos (7 SP)
    ├─ App Movil: MovementsScreen con tipos (entrada/salida/traspaso)
    ├─ Frontend Web: InventoryStockTable + MovementFormModal
    ├─ Backend: API completa de movimientos
    ├─ Database: Triggers para stock automatico
    └─ Alertas: Generacion de stock_alerts si < umbral
    ↓
Codigo Implementado:
    ├─ apps/backend/src/modules/inventory/
    │   ├─ entities/warehouse.entity.ts
    │   ├─ entities/inventory-movement.entity.ts
    │   ├─ services/inventory.service.ts
    │   ├─ services/movement.service.ts
    │   └─ services/alert.service.ts
    ├─ apps/frontend/src/features/inventory/
    │   ├─ components/InventoryStockTable.tsx
    │   ├─ components/MovementFormModal.tsx
    │   └─ components/StockAlertsPanel.tsx
    └─ apps/mobile/almacen/src/features/warehouse/
        ├─ screens/ReceptionScreen.tsx
        ├─ screens/MovementsScreen.tsx
        ├─ screens/InventoryScreen.tsx
        └─ services/offline-sync.service.ts
```

---

## Integracion con App Movil MOB-002 (Almacenista)

### Arquitectura de Integracion

```
┌──────────────────────────────────────────────────────────────┐
│                     Backend (NestJS)                         │
│                                                              │
│  ┌────────────────────┐      ┌─────────────────────┐        │
│  │ PurchaseController │      │ InventoryController │        │
│  └────────┬───────────┘      └──────────┬──────────┘        │
│           │                             │                    │
│  ┌────────▼───────────┐      ┌─────────▼──────────┐         │
│  │ PurchaseOrderService│      │ InventoryService   │         │
│  └────────┬───────────┘      └──────────┬─────────┘         │
│           │                             │                    │
│  ┌────────▼──────────────────────────────▼─────────┐        │
│  │          PostgreSQL Database                    │        │
│  │  - purchasing_management schema                 │        │
│  │  - inventory_management schema                  │        │
│  └─────────────────────────────────────────────────┘        │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           │ REST API
                           │ WebSocket (notificaciones)
                           │
┌──────────────────────────▼───────────────────────────────────┐
│              App Movil MOB-002 (React Native)                │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Reception    │  │ Exit         │  │ Inventory    │      │
│  │ Screen       │  │ Screen       │  │ Screen       │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                 │                │
│  ┌──────▼─────────────────▼─────────────────▼───────┐       │
│  │         Movement Service (React Native)          │       │
│  │  - API calls con retry                           │       │
│  │  - Offline queue management                      │       │
│  └──────────────────────┬───────────────────────────┘       │
│                         │                                    │
│  ┌──────────────────────▼───────────────────────────┐       │
│  │      WatermelonDB (SQLite - Offline Storage)     │       │
│  │  - movements_queue (pendientes sincronizacion)   │       │
│  │  - inventory_cache (datos offline)               │       │
│  │  - purchase_orders_cache                         │       │
│  └──────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────┘
```

### API Endpoints para App Movil

**Autenticacion:**
```
POST /api/v1/auth/login
POST /api/v1/auth/refresh-token
```

**Recepciones de Material:**
```
GET  /api/v1/ordenes-compra/pendientes-recepcion
GET  /api/v1/ordenes-compra/:id
POST /api/v1/inventario/entradas
POST /api/v1/inventario/entradas/:id/upload-photo
```

**Salidas de Material:**
```
GET  /api/v1/inventario/solicitudes-salida
POST /api/v1/inventario/salidas
POST /api/v1/inventario/solicitudes-salida/:id/aprobar
POST /api/v1/inventario/solicitudes-salida/:id/rechazar
```

**Consulta de Inventario:**
```
GET  /api/v1/inventario/existencias?almacen_id=:id
GET  /api/v1/inventario/buscar?q=:query
GET  /api/v1/inventario/ubicacion/:material_id
```

**Transferencias:**
```
POST /api/v1/inventario/transferencias
GET  /api/v1/inventario/transferencias/pendientes
POST /api/v1/inventario/transferencias/:id/confirmar-recepcion
```

**Inventario Fisico:**
```
POST /api/v1/inventario/conteo-fisico
POST /api/v1/inventario/conteo-fisico/:id/ajustar
GET  /api/v1/inventario/diferencias
```

**Sincronizacion:**
```
POST /api/v1/sync/movements/batch
GET  /api/v1/sync/inventory/delta?last_sync=:timestamp
```

### Flujo de Sincronizacion Offline

```mermaid
sequenceDiagram
    participant App as App Movil
    participant Queue as Cola Local
    participant API as Backend API
    participant DB as PostgreSQL

    Note over App: Sin conexion a internet

    App->>Queue: Guardar movimiento localmente
    Queue-->>App: Confirmacion local

    Note over App: Conexion restaurada

    App->>App: Detectar conexion
    App->>Queue: Obtener movimientos pendientes
    Queue-->>App: Lista de movimientos

    loop Por cada movimiento
        App->>API: POST /api/v1/sync/movements/batch
        API->>DB: Guardar movimiento
        DB-->>API: Confirmacion
        API-->>App: Success (movement_id)
        App->>Queue: Marcar como sincronizado
    end

    App->>API: GET /api/v1/sync/inventory/delta
    API->>DB: Obtener cambios desde last_sync
    DB-->>API: Delta de inventario
    API-->>App: Inventario actualizado
    App->>App: Actualizar cache local
```

### Resolucion de Conflictos

| Escenario | Estrategia | Accion |
|-----------|-----------|--------|
| **Mismo movimiento duplicado** | Detectar por UUID generado en app | Rechazar duplicado, notificar en app |
| **Stock insuficiente en salida** | Validar en servidor | Rechazar movimiento, actualizar cache |
| **Material eliminado** | Validar existencia en servidor | Rechazar movimiento, sincronizar catalogo |
| **Orden de compra cancelada** | Validar estado en servidor | Rechazar recepcion, notificar en app |
| **Cambios concurrentes de stock** | Ultimo movimiento gana | Aplicar movimiento, recalcular stock |

---

## Alertas Inteligentes

### Tipos de Alertas

1. **Stock Minimo** (alert_type: `stock_min`)
   - Trigger: `stock_actual < umbral_minimo`
   - Severidad: Alta
   - Accion: Notificar a almacenista + compras

2. **Punto de Reorden** (alert_type: `reorder_point`)
   - Trigger: `stock_actual <= punto_reorden`
   - Severidad: Media
   - Accion: Sugerir crear requisicion

3. **Sobreconsumo** (alert_type: `overconsumption`)
   - Trigger: `consumo_real > presupuesto * 1.05`
   - Severidad: Alta
   - Accion: Notificar a residente + jefe de proyecto

4. **Sin Movimiento** (alert_type: `no_movement`)
   - Trigger: Materiales sin movimiento en 90 dias
   - Severidad: Baja
   - Accion: Sugerir transferencia o venta

5. **Stock Maximo** (alert_type: `stock_max`)
   - Trigger: `stock_actual > umbral_maximo`
   - Severidad: Media
   - Accion: Alertar de exceso de inventario

### Configuracion de Umbrales

Por defecto:
- Stock minimo: 10% del presupuestado
- Punto de reorden: 20% del presupuestado
- Stock maximo: 150% del presupuestado

Configurable por:
- Material especifico
- Almacen
- Obra

---

## Testing

### Unit Tests (Backend)

```typescript
describe('InventoryService', () => {
  it('should calculate PEPS cost correctly')
  it('should prevent negative stock exits')
  it('should generate stock alerts when below threshold')
  it('should update stock automatically on movements')
})

describe('RequisitionService', () => {
  it('should validate budget availability')
  it('should handle approval workflow correctly')
  it('should convert requisition to purchase order')
})

describe('PurchaseOrderService', () => {
  it('should calculate totals with taxes')
  it('should generate PDF correctly')
  it('should track partial receptions')
})
```

### E2E Tests (App Movil)

```typescript
describe('Warehouse Operations E2E', () => {
  it('should complete material reception flow')
  it('should process material exit request')
  it('should handle offline mode correctly')
  it('should sync pending movements when online')
  it('should scan QR code and fetch material')
})
```

### Integration Tests

```typescript
describe('Purchase to Inventory Integration', () => {
  it('should create inventory entry from PO reception')
  it('should update stock with PEPS valuation')
  it('should link exit to budget item')
  it('should generate alerts on low stock')
})
```

---

## Riesgos Especificos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|-------------|---------|------------|
| **Complejidad de PEPS** | Media | Alto | Triggers bien probados, stored procedures |
| **Performance con miles de movimientos** | Media | Medio | Indices apropiados, paginacion, archivado |
| **Sincronizacion offline falla** | Media | Alto | Cola persistente, retry automatico, logs detallados |
| **Conflictos de stock concurrente** | Alta | Medio | Validaciones en servidor, locks transaccionales |
| **Adopcion de app movil por almacenistas** | Media | Alto | UI simple, capacitacion, modo offline robusto |

---

## Checklist de Implementacion

### Backend
- [ ] Schemas SQL completos (purchasing_management, inventory_management)
- [ ] TypeORM entities con relaciones
- [ ] Services con logica de negocio
- [ ] Triggers para PEPS y stock automatico
- [ ] API REST completa
- [ ] Generacion de PDFs (ordenes de compra)
- [ ] Sistema de notificaciones (email + in-app)
- [ ] CRON jobs para analisis y alertas
- [ ] Tests unitarios >80% coverage

### Frontend Web
- [ ] Gestion de proveedores y calificaciones
- [ ] RFQ y comparativo de cotizaciones
- [ ] Requisiciones con flujo de aprobacion
- [ ] Ordenes de compra con PDFs
- [ ] Gestion de almacenes y ubicaciones
- [ ] Control de movimientos de inventario
- [ ] Kardex detallado por material
- [ ] Dashboard de inventarios con graficas
- [ ] Panel de alertas
- [ ] Analisis de consumo vs presupuesto

### App Movil MOB-002
- [ ] Login y autenticacion
- [ ] Selector de obra/almacen
- [ ] Recepcion de material con escaneo QR
- [ ] Procesamiento de solicitudes de salida
- [ ] Consulta de inventario en tiempo real
- [ ] Inventario fisico/conteo ciclico
- [ ] Transferencias entre almacenes
- [ ] Captura de firma digital
- [ ] Modo offline con WatermelonDB
- [ ] Cola de sincronizacion automatica
- [ ] Push notifications
- [ ] UI optimizada para campo

### Database
- [ ] Schemas y tablas creadas
- [ ] Funciones de scoring y PEPS
- [ ] Triggers de stock automatico
- [ ] Triggers de alertas
- [ ] Indices optimizados
- [ ] Politicas RLS para multi-tenancy

### Testing
- [ ] Unit tests backend >80%
- [ ] E2E tests de app movil
- [ ] Integration tests flujo completo
- [ ] Tests de sincronizacion offline
- [ ] Tests de PEPS con multiples lotes
- [ ] Performance tests con volumen alto

### Despliegue
- [ ] Variables de entorno configuradas
- [ ] Deploy de app a stores (TestFlight, Play Store)
- [ ] Configuracion de push notifications
- [ ] Monitoreo de sincronizacion
- [ ] Logs de errores (Sentry)
- [ ] Documentacion de API
- [ ] Manual de usuario de app movil

---

## Quick Links

### Documentacion Tecnica
- Matriz de trazabilidad: [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)
- Modelo de datos: [DATABASE.yml](./implementacion/DATABASE.yml)
- Especificaciones backend: [BACKEND.yml](./implementacion/BACKEND.yml)
- Especificaciones app movil: [MOBILE.yml](./implementacion/MOBILE.yml)

### Historias de Usuario por Funcionalidad

**Proveedores y Cotizaciones:**
- [US-PURCH-001](./historias-usuario/US-PURCH-001-registro-proveedor.md) - Registro de Proveedor
- [US-PURCH-002](./historias-usuario/US-PURCH-002-solicitud-cotizaciones.md) - Solicitar Cotizaciones (RFQ)

**Requisiciones y Ordenes de Compra:**
- [US-PURCH-003](./historias-usuario/US-PURCH-003-crear-requisicion-obra.md) - Crear Requisicion desde Obra
- [US-PURCH-004](./historias-usuario/US-PURCH-004-aprobar-generar-orden-compra.md) - Aprobar y Generar Orden de Compra
- [US-PURCH-005](./historias-usuario/US-PURCH-005-recibir-material-almacen.md) - Recibir Material en Almacen

**Almacenes e Inventarios:**
- [US-PURCH-006](./historias-usuario/US-PURCH-006-control-almacenes-movimientos.md) - Control de Almacenes y Movimientos
- [US-PURCH-007](./historias-usuario/US-PURCH-007-kardex-analisis-consumo.md) - Kardex y Analisis de Consumo
- [US-PURCH-008](./historias-usuario/US-PURCH-008-dashboard-inventarios-alertas.md) - Dashboard de Inventarios y Alertas

### Requerimientos Funcionales por Subsistema

**Compras:**
- [RF-PURCH-001](./requerimientos/RF-PURCH-001-catalogo-proveedores.md) - Catalogo de Proveedores y Cotizaciones
- [RF-PURCH-002](./requerimientos/RF-PURCH-002-requisiciones-ordenes-compra.md) - Requisiciones y Ordenes de Compra

**Inventarios:**
- [RF-PURCH-003](./requerimientos/RF-PURCH-003-almacenes-inventarios.md) - Almacenes y Control de Inventarios
- [RF-PURCH-004](./requerimientos/RF-PURCH-004-kardex-alertas.md) - Kardex y Alertas de Stock

### Especificaciones Tecnicas

- [ET-PURCH-001](./especificaciones/ET-PURCH-001-implementacion-proveedores.md) - Implementacion de Proveedores
- [ET-PURCH-002](./especificaciones/ET-PURCH-002-implementacion-requisiciones-ordenes.md) - Implementacion de Requisiciones y OCs
- [ET-PURCH-003](./especificaciones/ET-PURCH-003-implementacion-almacenes.md) - Implementacion de Almacenes
- [ET-PURCH-004](./especificaciones/ET-PURCH-004-implementacion-kardex-alertas.md) - Implementacion de Kardex y Alertas

---

## Lessons Learned (a documentar post-implementacion)

1. **PEPS requiere triggers robustos:** La valorizacion automatica es compleja, requiere testing exhaustivo
2. **Modo offline es critico:** Obras no siempre tienen conexion, cola de sincronizacion debe ser solida
3. **UX simple en app movil:** Almacenistas necesitan flujos rapidos y directos
4. **Alertas deben ser accionables:** No solo notificar, sino sugerir acciones concretas
5. **Integracion con presupuestos clave:** Vinculacion temprana con MAI-002 evita retrabajo

---

## Siguiente Paso

Iniciar implementacion comenzando por:
1. Setup de schemas de base de datos
2. Backend de proveedores y cotizaciones (Sprint 11)
3. Frontend de requisiciones y ordenes de compra (Sprint 12)
4. App movil MOB-002 en paralelo con inventarios (Sprint 13-14)

---

**Generado:** 2025-12-06
**Mantenedores:** @tech-lead @backend-team @mobile-team @inventory-team
**Estado:** Documentado
**Prioridad:** P1 - Alta para control de costos y prevencion de paros