# TRACEABILITY - MAI-004: Compras e Inventarios metadata: modulo: MAI-004 nombre: Compras e Inventarios version: 1.0.0 fecha: 2025-12-06 reutilizacion_core: 80% descripcion: Gestión integral de requisiciones de material, órdenes de compra, almacenes por obra y movimientos de inventario dependencias: - MGN-001 # Usuarios y Autenticación - MGN-002 # RBAC - MGN-003 # Multi-tenancy - MGN-005 # Catálogos - MAI-001 # Proyectos de Construcción - MAI-002 # Presupuestos apps_moviles: - MOB-002 # Almacenista requerimientos: - id: RF-COMP-001 titulo: Requisiciones de Material descripcion: Gestión de solicitudes de material para obras de construcción prioridad: alta especificaciones: - id: ESP-COMP-001-01 descripcion: Crear requisiciones de material vinculadas a obras y partidas presupuestales - id: ESP-COMP-001-02 descripcion: Definir cantidad solicitada, unidad de medida y fecha requerida - id: ESP-COMP-001-03 descripcion: Flujo de aprobación multinivel (Residente -> Superintendente -> Compras) - id: ESP-COMP-001-04 descripcion: Convertir requisiciones aprobadas en órdenes de compra - id: ESP-COMP-001-05 descripcion: Vincular requisiciones con partidas presupuestales específicas - id: ESP-COMP-001-06 descripcion: Control de estados (borrador, enviada, aprobada, rechazada, convertida) historias_usuario: - id: US-COMP-001-01 titulo: Como residente de obra necesito crear requisiciones de material criterios_aceptacion: - Seleccionar obra y partida presupuestal - Agregar materiales del catálogo con cantidades - Especificar fecha requerida de entrega - Guardar como borrador o enviar a aprobación - id: US-COMP-001-02 titulo: Como superintendente necesito aprobar/rechazar requisiciones criterios_aceptacion: - Ver lista de requisiciones pendientes de aprobación - Revisar detalle de materiales solicitados - Aprobar o rechazar con comentarios - Notificar al solicitante y departamento de compras - id: US-COMP-001-03 titulo: Como jefe de compras necesito convertir requisiciones en órdenes de compra criterios_aceptacion: - Ver requisiciones aprobadas pendientes - Agrupar requisiciones por proveedor/material - Generar orden de compra automáticamente - Marcar requisiciones como convertidas tablas: - purchasing_management.requisiciones - purchasing_management.requisiciones_detalle - purchasing_management.requisiciones_aprobaciones - purchasing_management.requisiciones_partidas endpoints: - POST /api/v1/requisiciones - GET /api/v1/requisiciones - GET /api/v1/requisiciones/:id - PUT /api/v1/requisiciones/:id - DELETE /api/v1/requisiciones/:id - POST /api/v1/requisiciones/:id/enviar - POST /api/v1/requisiciones/:id/aprobar - POST /api/v1/requisiciones/:id/rechazar - POST /api/v1/requisiciones/:id/convertir-oc - GET /api/v1/requisiciones/obra/:obra_id - GET /api/v1/requisiciones/pendientes-aprobacion componentes_ui: - RequisicionesListView - RequisicionFormModal - RequisicionDetailView - RequisicionApprovalPanel - RequisicionItemsTable - RequisicionWorkflowTimeline app_movil: MOB-002 integraciones: - modulo: MAI-001 descripcion: Vinculación con obras de construcción - modulo: MAI-002 descripcion: Vinculación con partidas presupuestales - modulo: MGN-005 descripcion: Catálogo de materiales y unidades de medida estado: pendiente - id: RF-COMP-002 titulo: Órdenes de Compra descripcion: Gestión completa de órdenes de compra a proveedores prioridad: alta especificaciones: - id: ESP-COMP-002-01 descripcion: Crear órdenes de compra manual o desde requisiciones - id: ESP-COMP-002-02 descripcion: Seleccionar proveedor y condiciones comerciales (precio, plazo, forma de pago) - id: ESP-COMP-002-03 descripcion: Generar documento PDF de orden de compra - id: ESP-COMP-002-04 descripcion: Control de estados (borrador, enviada, confirmada, recibida parcial, recibida total, cancelada) - id: ESP-COMP-002-05 descripcion: Registro de recepciones parciales y totales - id: ESP-COMP-002-06 descripcion: Comparación de precio cotizado vs precio de orden - id: ESP-COMP-002-07 descripcion: Control de presupuesto comprometido historias_usuario: - id: US-COMP-002-01 titulo: Como comprador necesito crear órdenes de compra criterios_aceptacion: - Seleccionar proveedor del catálogo - Agregar materiales con precio, cantidad y descuentos - Definir condiciones de pago y entrega - Calcular totales con impuestos - Generar PDF y enviar por email - id: US-COMP-002-02 titulo: Como almacenista necesito registrar recepciones de material criterios_aceptacion: - Ver órdenes pendientes de recepción - Registrar cantidad recibida (parcial o total) - Documentar diferencias o daños - Actualizar estado de orden - Generar entrada de almacén automáticamente - id: US-COMP-002-03 titulo: Como jefe de proyecto necesito consultar órdenes por obra criterios_aceptacion: - Filtrar órdenes por obra, proveedor, estado - Ver monto total comprometido - Consultar materiales pendientes de recibir - Generar reporte de órdenes tablas: - purchasing_management.ordenes_compra - purchasing_management.ordenes_compra_detalle - purchasing_management.ordenes_compra_recepciones - purchasing_management.ordenes_compra_documentos endpoints: - POST /api/v1/ordenes-compra - GET /api/v1/ordenes-compra - GET /api/v1/ordenes-compra/:id - PUT /api/v1/ordenes-compra/:id - DELETE /api/v1/ordenes-compra/:id - POST /api/v1/ordenes-compra/:id/enviar - POST /api/v1/ordenes-compra/:id/confirmar - POST /api/v1/ordenes-compra/:id/cancelar - POST /api/v1/ordenes-compra/:id/recepcion - GET /api/v1/ordenes-compra/:id/pdf - GET /api/v1/ordenes-compra/obra/:obra_id - GET /api/v1/ordenes-compra/proveedor/:proveedor_id componentes_ui: - OrdenesCompraListView - OrdenCompraFormModal - OrdenCompraDetailView - OrdenCompraItemsTable - OrdenCompraRecepcionModal - OrdenCompraPDFPreview - OrdenCompraStatusBadge app_movil: MOB-002 integraciones: - modulo: RF-COMP-001 descripcion: Generación desde requisiciones - modulo: MGN-005 descripcion: Catálogo de proveedores y materiales - modulo: MAI-001 descripcion: Vinculación con obras - modulo: MAI-002 descripcion: Control de presupuesto comprometido estado: pendiente - id: RF-COMP-003 titulo: Almacenes por Obra descripcion: Gestión de almacenes y ubicaciones de inventario en cada obra prioridad: alta especificaciones: - id: ESP-COMP-003-01 descripcion: Crear múltiples almacenes por obra de construcción - id: ESP-COMP-003-02 descripcion: Definir ubicaciones y áreas dentro de cada almacén - id: ESP-COMP-003-03 descripcion: Asignar responsable/almacenista a cada almacén - id: ESP-COMP-003-04 descripcion: Control de existencias por almacén y ubicación - id: ESP-COMP-003-05 descripcion: Establecer niveles mínimos y máximos de inventario - id: ESP-COMP-003-06 descripcion: Alertas de material con existencias bajas - id: ESP-COMP-003-07 descripcion: Inventario cíclico y físico por almacén historias_usuario: - id: US-COMP-003-01 titulo: Como jefe de obra necesito crear almacenes en la obra criterios_aceptacion: - Registrar almacén con nombre y ubicación física - Asignar almacenista responsable - Definir tipo de almacén (general, herramientas, materiales peligrosos) - Activar/desactivar almacenes - id: US-COMP-003-02 titulo: Como almacenista necesito organizar ubicaciones en el almacén criterios_aceptacion: - Crear zonas, pasillos y estantes - Asignar materiales a ubicaciones específicas - Consultar ubicación de materiales - Generar mapa de almacén - id: US-COMP-003-03 titulo: Como residente necesito consultar existencias por almacén criterios_aceptacion: - Ver inventario actual por almacén - Consultar disponibilidad de material - Ver materiales con existencias bajas - Generar reporte de inventario tablas: - inventory_management.almacenes - inventory_management.almacenes_ubicaciones - inventory_management.inventario_por_almacen - inventory_management.niveles_inventario endpoints: - POST /api/v1/almacenes - GET /api/v1/almacenes - GET /api/v1/almacenes/:id - PUT /api/v1/almacenes/:id - DELETE /api/v1/almacenes/:id - GET /api/v1/almacenes/obra/:obra_id - POST /api/v1/almacenes/:id/ubicaciones - GET /api/v1/almacenes/:id/inventario - GET /api/v1/almacenes/:id/existencias-bajas - POST /api/v1/almacenes/:id/inventario-fisico componentes_ui: - AlmacenesListView - AlmacenFormModal - AlmacenDetailView - UbicacionesTreeView - InventarioAlmacenTable - ExistenciasBajasAlert - AlmacenResponsableSelector app_movil: MOB-002 integraciones: - modulo: MAI-001 descripcion: Vinculación con obras de construcción - modulo: MGN-001 descripcion: Asignación de almacenistas - modulo: MGN-005 descripcion: Catálogo de materiales estado: pendiente - id: RF-COMP-004 titulo: Movimientos de Inventario descripcion: Registro y control de entradas, salidas y transferencias de inventario prioridad: alta especificaciones: - id: ESP-COMP-004-01 descripcion: Registrar entradas de material desde órdenes de compra - id: ESP-COMP-004-02 descripcion: Registrar salidas de material para consumo en obra - id: ESP-COMP-004-03 descripcion: Transferencias entre almacenes de diferentes obras - id: ESP-COMP-004-04 descripcion: Ajustes de inventario (mermas, devoluciones, correcciones) - id: ESP-COMP-004-05 descripcion: Trazabilidad completa de movimientos por material - id: ESP-COMP-004-06 descripcion: Vinculación de salidas con partidas presupuestales - id: ESP-COMP-004-07 descripcion: Cálculo automático de costos (PEPS, promedio ponderado) - id: ESP-COMP-004-08 descripcion: Validación de existencias disponibles antes de salidas historias_usuario: - id: US-COMP-004-01 titulo: Como almacenista necesito registrar entradas de material criterios_aceptacion: - Seleccionar orden de compra recibida - Registrar cantidad, lote, y ubicación - Capturar costo unitario - Generar comprobante de entrada - Actualizar inventario automáticamente - id: US-COMP-004-02 titulo: Como residente necesito solicitar salidas de material criterios_aceptacion: - Seleccionar materiales del inventario disponible - Especificar cantidad y destino (partida/frente de obra) - Enviar solicitud a almacenista - Recibir notificación de aprobación - id: US-COMP-004-03 titulo: Como almacenista necesito procesar salidas de material desde app móvil criterios_aceptacion: - Ver solicitudes pendientes en app móvil - Verificar existencias disponibles - Aprobar o rechazar solicitud - Registrar entrega con firma digital - Actualizar inventario en tiempo real - id: US-COMP-004-04 titulo: Como jefe de almacén necesito transferir material entre obras criterios_aceptacion: - Seleccionar almacén origen y destino - Especificar materiales y cantidades - Generar documento de transferencia - Registrar salida en origen y entrada en destino - Actualizar inventarios de ambas obras - id: US-COMP-004-05 titulo: Como contador necesito consultar valuación de inventario criterios_aceptacion: - Ver valor total de inventario por obra - Consultar costo promedio por material - Generar reporte de kardex - Exportar movimientos para contabilidad tablas: - inventory_management.movimientos_inventario - inventory_management.entradas_inventario - inventory_management.salidas_inventario - inventory_management.transferencias_inventario - inventory_management.ajustes_inventario - inventory_management.kardex endpoints: - POST /api/v1/inventario/entradas - POST /api/v1/inventario/salidas - POST /api/v1/inventario/transferencias - POST /api/v1/inventario/ajustes - GET /api/v1/inventario/movimientos - GET /api/v1/inventario/movimientos/:id - GET /api/v1/inventario/kardex/:material_id - GET /api/v1/inventario/existencias - GET /api/v1/inventario/valuacion - GET /api/v1/inventario/solicitudes-salida - POST /api/v1/inventario/solicitudes-salida/:id/aprobar - POST /api/v1/inventario/solicitudes-salida/:id/rechazar componentes_ui: - MovimientosInventarioListView - EntradaInventarioFormModal - SalidaInventarioFormModal - TransferenciaInventarioFormModal - AjusteInventarioFormModal - KardexMaterialView - SolicitudesSalidaPanel - ValuacionInventarioReport - MovimientoDetailView app_movil: MOB-002 funcionalidades_movil: - Consultar existencias en tiempo real - Registrar entradas desde órdenes de compra - Procesar solicitudes de salida - Escaneo de códigos de barras/QR - Captura de firma digital en entregas - Modo offline con sincronización - Inventario físico con conteo cíclico integraciones: - modulo: RF-COMP-002 descripcion: Entradas desde órdenes de compra - modulo: RF-COMP-003 descripcion: Actualización de existencias por almacén - modulo: MAI-002 descripcion: Vinculación de salidas con partidas presupuestales - modulo: MGN-005 descripcion: Catálogo de materiales y unidades - modulo: MAI-001 descripcion: Vinculación con obras estado: pendiente # Aplicación Móvil app_movil: id: MOB-002 nombre: Almacenista descripcion: Aplicación móvil para almacenistas en obra plataformas: - Android - iOS tecnologias: - React Native - Expo - SQLite (offline) - Axios (sync) funcionalidades: - login_offline: Autenticación con modo offline - consulta_inventario: Consulta de existencias en tiempo real - registro_entradas: Registro de entradas de material - procesamiento_salidas: Aprobación y entrega de salidas - escaneo_codigos: Escaneo de códigos de barras y QR - firma_digital: Captura de firma en entregas - inventario_fisico: Conteo físico e inventario cíclico - transferencias: Transferencias entre almacenes - fotografias: Captura de fotos de materiales - sincronizacion: Sincronización automática con servidor requerimientos_vinculados: - RF-COMP-001 # Consulta de requisiciones - RF-COMP-002 # Recepción de órdenes de compra - RF-COMP-003 # Gestión de almacenes - RF-COMP-004 # Movimientos de inventario estado: pendiente # Esquemas de Base de Datos esquemas: - nombre: purchasing_management descripcion: Esquema para gestión de compras tablas: - requisiciones - requisiciones_detalle - requisiciones_aprobaciones - requisiciones_partidas - ordenes_compra - ordenes_compra_detalle - ordenes_compra_recepciones - ordenes_compra_documentos - nombre: inventory_management descripcion: Esquema para gestión de inventarios tablas: - almacenes - almacenes_ubicaciones - inventario_por_almacen - niveles_inventario - movimientos_inventario - entradas_inventario - salidas_inventario - transferencias_inventario - ajustes_inventario - kardex # Políticas RLS rls_policies: archivo: ET-PURCH-rls-policies.sql descripcion: Políticas de seguridad a nivel de fila para multi-tenancy tablas_protegidas: - purchasing_management.requisiciones - purchasing_management.ordenes_compra - inventory_management.almacenes - inventory_management.movimientos_inventario # Reportes reportes: - id: REP-COMP-001 nombre: Requisiciones Pendientes descripcion: Listado de requisiciones en proceso de aprobación parametros: [fecha_inicio, fecha_fin, obra_id, estado] - id: REP-COMP-002 nombre: Órdenes de Compra por Proveedor descripcion: Detalle de órdenes emitidas por proveedor parametros: [fecha_inicio, fecha_fin, proveedor_id, estado] - id: REP-COMP-003 nombre: Inventario Valorizado descripcion: Valuación de inventario por almacén u obra parametros: [fecha_corte, obra_id, almacen_id] - id: REP-COMP-004 nombre: Kardex de Material descripcion: Movimientos detallados por material parametros: [material_id, fecha_inicio, fecha_fin, almacen_id] - id: REP-COMP-005 nombre: Consumo por Partida Presupuestal descripcion: Materiales consumidos por partida presupuestal parametros: [obra_id, partida_id, fecha_inicio, fecha_fin] - id: REP-COMP-006 nombre: Materiales por Recibir descripcion: Órdenes pendientes de recepción total o parcial parametros: [obra_id, proveedor_id, dias_atraso] # Notificaciones notificaciones: - evento: requisicion_enviada destinatarios: [aprobador_nivel_1, jefe_compras] canal: [email, app] - evento: requisicion_aprobada destinatarios: [solicitante, departamento_compras] canal: [email, app] - evento: requisicion_rechazada destinatarios: [solicitante] canal: [email, app] - evento: orden_compra_creada destinatarios: [proveedor, almacenista] canal: [email] - evento: material_recibido destinatarios: [residente_obra, solicitante] canal: [app] - evento: existencias_bajas destinatarios: [almacenista, residente_obra, compras] canal: [email, app] - evento: solicitud_salida_pendiente destinatarios: [almacenista] canal: [app, push_movil] - evento: transferencia_enviada destinatarios: [almacenista_destino] canal: [app, push_movil] # Métricas y KPIs metricas: - nombre: tiempo_aprobacion_requisiciones descripcion: Tiempo promedio de aprobación de requisiciones unidad: horas objetivo: "< 24 horas" - nombre: tasa_rechazo_requisiciones descripcion: Porcentaje de requisiciones rechazadas unidad: porcentaje objetivo: "< 10%" - nombre: cumplimiento_entregas descripcion: Porcentaje de órdenes entregadas a tiempo unidad: porcentaje objetivo: "> 90%" - nombre: exactitud_inventario descripcion: Diferencia entre inventario físico y sistema unidad: porcentaje objetivo: "> 95%" - nombre: rotacion_inventario descripcion: Veces que rota el inventario por período unidad: veces/mes objetivo: "> 2" - nombre: valor_inventario_inmovilizado descripcion: Valor de materiales sin movimiento > 90 días unidad: moneda objetivo: "< 5% del total" # Validaciones y Reglas de Negocio reglas_negocio: - codigo: RN-COMP-001 descripcion: No se puede crear una orden de compra sin requisición aprobada o autorización especial - codigo: RN-COMP-002 descripcion: Las salidas de inventario deben estar vinculadas a una partida presupuestal - codigo: RN-COMP-003 descripcion: No se permiten salidas de inventario si no hay existencias suficientes - codigo: RN-COMP-004 descripcion: Las transferencias deben ser aprobadas por los responsables de ambos almacenes - codigo: RN-COMP-005 descripcion: El costo de materiales debe actualizarse según método PEPS o promedio ponderado - codigo: RN-COMP-006 descripcion: Las requisiciones deben respetar el presupuesto aprobado de la obra - codigo: RN-COMP-007 descripcion: Los ajustes de inventario requieren justificación y aprobación # Seguridad seguridad: permisos: - compras.requisiciones.crear - compras.requisiciones.leer - compras.requisiciones.editar - compras.requisiciones.eliminar - compras.requisiciones.aprobar - compras.ordenes.crear - compras.ordenes.leer - compras.ordenes.editar - compras.ordenes.eliminar - compras.ordenes.enviar - inventario.almacenes.crear - inventario.almacenes.leer - inventario.almacenes.editar - inventario.movimientos.crear - inventario.movimientos.leer - inventario.entradas.registrar - inventario.salidas.registrar - inventario.salidas.aprobar - inventario.transferencias.crear - inventario.transferencias.aprobar - inventario.ajustes.crear - inventario.ajustes.aprobar - inventario.reportes.generar roles_sugeridos: - nombre: comprador permisos: [compras.requisiciones.*, compras.ordenes.*] - nombre: almacenista permisos: [inventario.movimientos.*, inventario.salidas.aprobar] - nombre: residente_obra permisos: [compras.requisiciones.crear, inventario.salidas.registrar] - nombre: jefe_almacen permisos: [inventario.*, compras.ordenes.leer] # Pruebas pruebas: unitarias: - calcular_costo_promedio_ponderado - validar_existencias_disponibles - aplicar_descuentos_orden_compra - calcular_totales_con_impuestos integracion: - flujo_completo_requisicion_a_orden - recepcion_material_y_actualizacion_inventario - transferencia_entre_almacenes - vinculacion_salida_con_presupuesto e2e: - proceso_completo_compra_material - ciclo_vida_inventario_entrada_salida - aprobacion_multinivel_requisiciones - sincronizacion_app_movil # Cronograma Estimado cronograma: - fase: Análisis y Diseño duracion: 2 semanas entregables: [modelos_datos, diagramas_flujo, especificaciones_api] - fase: Desarrollo Backend duracion: 4 semanas entregables: [api_requisiciones, api_ordenes, api_inventario, rls_policies] - fase: Desarrollo Frontend duracion: 4 semanas entregables: [ui_requisiciones, ui_ordenes, ui_almacenes, ui_movimientos] - fase: Desarrollo App Móvil duracion: 3 semanas entregables: [app_almacenista, modo_offline, sincronizacion] - fase: Pruebas duracion: 2 semanas entregables: [pruebas_unitarias, pruebas_integracion, pruebas_usuario] - fase: Documentación y Capacitación duracion: 1 semana entregables: [manual_usuario, manual_tecnico, videos_capacitacion] # Notas de Implementación notas: - Priorizar desarrollo de RF-COMP-001 y RF-COMP-002 (flujo de compras básico) - Integrar con módulo MAI-002 para control presupuestal desde el inicio - Desarrollar app móvil MOB-002 en paralelo con backend de inventario - Implementar sincronización offline-online robusta para app móvil - Considerar integración futura con proveedores vía EDI o API - Evaluar uso de códigos QR para trazabilidad de materiales - Planificar migración de datos de sistema legacy si aplica