# 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
