812 lines
32 KiB
Markdown
812 lines
32 KiB
Markdown
# _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
|