13 KiB
13 KiB
RESUMEN EJECUTIVO - MAI-004: Compras e Inventarios
Épica: MAI-004 Versión: 1.0 Fecha: 2025-11-17 Estado: ✅ COMPLETO (100%)
1. Descripción General
Sistema completo de gestión de compras e inventarios para construcción, desde la solicitud de materiales en obra hasta el control detallado de stock con alertas inteligentes. Incluye:
- Gestión de Proveedores: Catálogo con calificación automática
- Cotizaciones (RFQ): Comparativo multi-proveedor con scoring
- Requisiciones y OCs: Flujos de aprobación configurables
- Inventarios Multi-almacén: Control PEPS con trazabilidad completa
- Kárdex y Análisis: Consumo vs presupuesto con proyecciones
- Alertas Inteligentes: 5 tipos de alertas automáticas
2. Objetivos de Negocio
Eficiencia en Compras
- Reducir tiempos: De requisición a OC en <48 horas
- Mejores precios: Comparación de 3+ proveedores
- Transparencia: Trazabilidad completa del proceso
Control de Inventarios
- Stock exacto: Inventario en tiempo real
- Reducir mermas: <2% del valor total
- Prevenir paros: Alertas anticipadas de faltantes
Optimización de Costos
- Stock justo: Ni exceso ni faltantes
- Detectar sobrecostos: Análisis vs presupuesto
- Calificar proveedores: Score 0-100 automático
3. Documentación Generada
3.1 Requerimientos Funcionales (4/4) ✅
| Código | Nombre | Tamaño | Estado |
|---|---|---|---|
| RF-PURCH-001 | Catálogo de Proveedores y Cotizaciones | ~30 KB | ✅ |
| RF-PURCH-002 | Requisiciones y Órdenes de Compra | ~22 KB | ✅ |
| RF-PURCH-003 | Almacenes y Control de Inventarios | ~25 KB | ✅ |
| RF-PURCH-004 | Kárdex y Alertas de Stock | ~28 KB | ✅ |
| TOTAL | 4 documentos | ~105 KB | 100% |
Contenido:
- Casos de uso detallados con wireframes
- Flujos de proceso (RFQ, aprobaciones, PEPS)
- Modelos de datos en TypeScript
- Criterios de aceptación
- Ejemplos visuales ASCII art
3.2 Especificaciones Técnicas (4/4) ✅
| Código | Nombre | Tamaño | Estado |
|---|---|---|---|
| ET-PURCH-001 | Implementación de Proveedores | ~18 KB | ✅ |
| ET-PURCH-002 | Implementación de Requisiciones y OCs | ~25 KB | ✅ |
| ET-PURCH-003 | Implementación de Almacenes | ~28 KB | ✅ |
| ET-PURCH-004 | Implementación de Kárdex y Alertas | ~22 KB | ✅ |
| TOTAL | 4 documentos | ~93 KB | 100% |
Contenido:
- Schemas SQL completos (purchases, inventory)
- TypeORM entities con relaciones
- Services con lógica de negocio
- Triggers para PEPS y alertas
- Funciones stored procedures
- React components principales
3.3 Historias de Usuario (8/8) ✅
| Sprint | Código | Nombre | SP | Estado |
|---|---|---|---|---|
| 11 | US-PURCH-001 | Registro de Proveedor | 5 | ✅ |
| 11 | US-PURCH-002 | Solicitar Cotizaciones (RFQ) | 8 | ✅ |
| 12 | US-PURCH-003 | Crear Requisición desde Obra | 5 | ✅ |
| 12 | US-PURCH-004 | Aprobar y Generar Orden de Compra | 8 | ✅ |
| 12 | US-PURCH-005 | Recibir Material en Almacén | 5 | ✅ |
| 13 | US-PURCH-006 | Control de Almacenes y Movimientos | 7 | ✅ |
| 13 | US-PURCH-007 | Kárdex y Análisis de Consumo | 5 | ✅ |
| 14 | US-PURCH-008 | Dashboard de Inventarios y Alertas | 5 | ✅ |
| TOTAL | 8 historias | 48 SP | 100% |
Distribución por Sprint:
- Sprint 11 (13 SP): Proveedores + RFQ + Comparativo
- Sprint 12 (18 SP): Requisiciones + OC + Recepción
- Sprint 13 (12 SP): Almacenes + Kárdex
- Sprint 14 (5 SP): Dashboard + Alertas
4. Stack Tecnológico
Backend
- NestJS 10+ con TypeScript
- PostgreSQL 15+ (schemas: purchases, inventory)
- TypeORM para ORM
- EventEmitter2 para eventos internos
- Cron para análisis diarios
- SendGrid/AWS SES para emails
Frontend
- React 18 con TypeScript
- Zustand para state management
- Chart.js para gráficas
- jsPDF para generación de PDFs
- React Query para cache
- WebSocket para notificaciones
Base de Datos
Schemas:
- purchases: suppliers, rfqs, quotes, purchase_orders, invoices
- inventory: warehouses, stock, movements, lots (PEPS), alerts
Features clave:
- Triggers para stock automático
- Stored procedures para PEPS
- Funciones para scoring de proveedores
- JSONB para items flexibles
- Full-text search en proveedores
5. Funcionalidades Clave
5.1 Gestión de Proveedores
- Catálogo con información fiscal y comercial
- Calificación automática 0-100 (5 criterios)
- Historial de órdenes y evaluaciones
- Certificación de proveedores
5.2 RFQ y Cotizaciones
- Envío simultáneo a múltiples proveedores
- Portal público para responder (token en URL)
- Comparativo visual con highlights
- Scoring automático:
score = precio(40%) + rating_proveedor(35%) + entrega(25%)
5.3 Requisiciones y OCs
- Flujos de aprobación por monto
- Validación vs presupuesto disponible
- Generación automática de OC desde cotización
- Numeración secuencial: REQ-YYYY-NNNNN, OC-YYYY-NNNNN
- PDFs automáticos enviados por email
5.4 Inventarios Multi-almacén
- Tipos: General, Por Proyecto, Temporal
- Movimientos: Entrada, Salida, Traspaso, Ajuste
- Valorización PEPS (First-In, First-Out)
- Ubicaciones por zona (A-01, B-03, etc.)
- Inventarios físicos con ajustes
5.5 Kárdex y Análisis
- Detalle por material/almacén/período
- Análisis consumo vs presupuesto
- Proyección de sobreconsumo (regresión lineal)
- Clasificación ABC automática
- Gráficas de tendencias
5.6 Alertas Inteligentes
- Stock Mínimo: Stock < umbral configurado
- Punto de Reorden: Momento de ordenar
- Sobreconsumo: Consumo > presupuesto +5%
- Sin Movimiento: 90 días sin uso
- Stock Máximo: Exceso de inventario
6. Modelo de Datos Principal
// Proveedores y Cotizaciones
suppliers (id, tax_id, legal_name, rating, certification_status)
→ supplier_ratings (evaluación mensual)
rfqs (id, code, project_id, items_jsonb, invited_suppliers[])
→ quotes (proveedor responde)
// Compras
requisitions (id, code, project_id, items_jsonb, approval_flow_jsonb)
→ purchase_orders (id, code, supplier_id, items_jsonb)
→ purchase_order_receipts (recepción parcial/total)
→ invoices (facturación)
// Inventarios
warehouses (id, code, type, project_id?)
→ inventory_stock (warehouse_id, material_id, quantity, average_cost)
→ inventory_lots (PEPS: entry_date, quantity, remaining, unit_cost)
→ inventory_movements (code, type, items_jsonb, source)
// Análisis y Alertas
consumption_analysis (project_id, material_id, variance_percentage)
stock_alerts (alert_type, severity, warehouse_id, material_id)
material_stock_config (umbrales por material/almacén)
7. Criterios de Aceptación Globales
Funcionales
- CRUD completo de proveedores con calificación
- RFQ multi-proveedor con comparativo
- Flujos de aprobación configurables
- Generación automática de OCs
- Multi-almacén con PEPS
- Kárdex detallado por material
- 5 tipos de alertas automáticas
- Dashboard ejecutivo en tiempo real
Técnicos
- Schemas SQL con triggers y funciones
- TypeORM entities con relaciones
- Services con lógica de negocio
- CRON jobs para análisis diarios
- Notificaciones email + in-app
- Generación de PDFs
- Tests unitarios >80%
UX/UI
- Wireframes ASCII en documentación
- Flujos completos de usuario
- Dashboards visuales con gráficas
- Exportación Excel/PDF
- Notificaciones en tiempo real
8. Estimación y Planificación
Story Points por Sprint
Sprint 11 (13 SP): Proveedores y RFQ
├─ US-PURCH-001: Registro de Proveedor (5 SP)
└─ US-PURCH-002: Solicitar Cotizaciones (8 SP)
Sprint 12 (18 SP): Requisiciones y OCs
├─ US-PURCH-003: Crear Requisición (5 SP)
├─ US-PURCH-004: Aprobar y Generar OC (8 SP)
└─ US-PURCH-005: Recibir Material (5 SP)
Sprint 13 (12 SP): Almacenes y Kárdex
├─ US-PURCH-006: Control de Almacenes (7 SP)
└─ US-PURCH-007: Kárdex y Análisis (5 SP)
Sprint 14 (5 SP): Dashboard y Alertas
└─ US-PURCH-008: Dashboard e Inventarios (5 SP)
Total: 48 Story Points
Estimación de Tiempo
- Sprints: 4 sprints
- Duración sprint: 2 semanas
- Tiempo total: 8 semanas (2 meses)
Equipo Sugerido
- 2 Backend developers (NestJS + PostgreSQL)
- 2 Frontend developers (React + TypeScript)
- 1 QA engineer
- 1 Product Owner (medio tiempo)
9. Riesgos e Impedimentos
Riesgos Técnicos
| Riesgo | Probabilidad | Impacto | Mitigación |
|---|---|---|---|
| Complejidad PEPS | Media | Alto | Triggers bien probados, stored procedures |
| Performance con miles de movimientos | Media | Medio | Índices apropiados, paginación |
| Sincronización de traspasos | Baja | Alto | Estados claros, validaciones |
Dependencias
- ✅ MAI-002 (Proyectos): Para vincular requisiciones
- ✅ MAI-003 (Presupuestos): Para validar disponibilidad
- ⬜ MAI-005 (Control de Obra): Para consumos en campo
10. Métricas de Éxito
KPIs del Sistema
-
Eficiencia de Compras
- Tiempo promedio requisición → OC: <48h
- % Requisiciones aprobadas en <24h: >80%
- % OCs con 3+ cotizaciones: >70%
-
Exactitud de Inventarios
- Diferencia inventario físico vs sistema: <2%
- % Alertas atendidas en <24h: >90%
- Rotación de inventario: 8-12 veces/año
-
Control de Costos
- % Materiales dentro de presupuesto: >85%
- Ahorro por comparación de cotizaciones: >5%
- % Proveedores con rating >80: >60%
11. Próximos Pasos
Implementación
- ✅ Documentación completa (HECHO)
- ⬜ Sprint Planning con equipo
- ⬜ Setup de infraestructura (BD, schemas)
- ⬜ Sprint 11: Proveedores y RFQ
- ⬜ Sprint 12: Requisiciones y OCs
- ⬜ Sprint 13: Almacenes y Kárdex
- ⬜ Sprint 14: Dashboard y Alertas
- ⬜ Testing integral y UAT
- ⬜ Capacitación a usuarios
- ⬜ Go-live escalonado
Integraciones Futuras
- Sistema de facturación electrónica (CFDI)
- Portal de proveedores completo
- App móvil para almacenistas
- BI avanzado con Power BI / Tableau
- Integración con ERP existente
12. Resumen de Entregables
Documentación (17 archivos, ~225 KB)
MAI-004-compras-inventarios/
├── requerimientos/
│ ├── RF-PURCH-001-catalogo-proveedores.md (~30 KB) ✅
│ ├── RF-PURCH-002-requisiciones-ordenes.md (~22 KB) ✅
│ ├── RF-PURCH-003-almacenes-inventarios.md (~25 KB) ✅
│ └── RF-PURCH-004-kardex-alertas.md (~28 KB) ✅
│
├── especificaciones/
│ ├── ET-PURCH-001-implementacion-proveedores.md (~18 KB) ✅
│ ├── ET-PURCH-002-implementacion-requisiciones.md (~25 KB) ✅
│ ├── ET-PURCH-003-implementacion-almacenes.md (~28 KB) ✅
│ └── ET-PURCH-004-implementacion-kardex-alertas.md (~22 KB) ✅
│
├── historias-usuario/
│ ├── US-PURCH-001-registro-proveedor.md (~5 KB) ✅
│ ├── US-PURCH-002-solicitud-cotizaciones.md (~6 KB) ✅
│ ├── US-PURCH-003-crear-requisicion-obra.md (~5 KB) ✅
│ ├── US-PURCH-004-aprobar-generar-orden-compra.md (~6 KB) ✅
│ ├── US-PURCH-005-recibir-material-almacen.md (~6 KB) ✅
│ ├── US-PURCH-006-control-almacenes-movimientos.md (~6 KB) ✅
│ ├── US-PURCH-007-kardex-analisis-consumo.md (~5 KB) ✅
│ └── US-PURCH-008-dashboard-inventarios-alertas.md (~6 KB) ✅
│
└── RESUMEN-EPICA-MAI-004.md (~12 KB) ✅
Total: 17 documentos, ~225 KB, 48 Story Points
13. Conclusión
La épica MAI-004: Compras e Inventarios está 100% documentada y lista para implementación.
Fortalezas del Diseño
✅ Sistema completo desde requisición hasta inventario ✅ Valorización PEPS con triggers automáticos ✅ Alertas inteligentes para prevenir paros de obra ✅ Comparación multi-proveedor con scoring ✅ Trazabilidad completa del flujo de materiales ✅ Análisis vs presupuesto en tiempo real
Valor de Negocio
- Reducción de costos: Comparación de proveedores, detección de sobreconsumos
- Eficiencia operativa: Automatización de flujos, alertas anticipadas
- Control financiero: Stock exacto, valorización PEPS, análisis detallados
- Transparencia: Trazabilidad completa, historial de decisiones
El equipo de desarrollo tiene toda la información necesaria para comenzar la implementación sin necesidad de aclaraciones adicionales.
Fecha de Finalización: 2025-11-17 Preparado por: Claude Code Estado: ✅ COMPLETO (100%)