workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-004-compras-inventarios/RESUMEN-EPICA-MAI-004.md

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

1. Stock Mínimo: Stock < umbral configurado
2. Punto de Reorden: Momento de ordenar
3. Sobreconsumo: Consumo > presupuesto +5%
4. Sin Movimiento: 90 días sin uso
5. 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

1. Eficiencia de Compras

   • Tiempo promedio requisición → OC: <48h
   • % Requisiciones aprobadas en <24h: >80%
   • % OCs con 3+ cotizaciones: >70%

2. Exactitud de Inventarios

   • Diferencia inventario físico vs sistema: <2%
   • % Alertas atendidas en <24h: >90%
   • Rotación de inventario: 8-12 veces/año

3. 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

1. ✅ Documentación completa (HECHO)
2. ⬜ Sprint Planning con equipo
3. ⬜ Setup de infraestructura (BD, schemas)
4. ⬜ Sprint 11: Proveedores y RFQ
5. ⬜ Sprint 12: Requisiciones y OCs
6. ⬜ Sprint 13: Almacenes y Kárdex
7. ⬜ Sprint 14: Dashboard y Alertas
8. ⬜ Testing integral y UAT
9. ⬜ Capacitación a usuarios
10. ⬜ 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%)