Analisis de Procura

Descripcion General

El Analisis de Procura es el proceso mediante el cual el equipo de contratacion evalua, cotiza y asigna proveedores a los materiales que no tienen stock en almacen. Se crea automaticamente cuando logistica enruta items desde una requisicion de material.

Flujo de Estados

stateDiagram-v2
    [*] --> OPEN: Creado desde requisicion

    OPEN --> IN_ANALYSIS: Contratacion actualiza items
    IN_ANALYSIS --> PENDING_COST_REVIEW: Enviar a revision (requiere adjuntos)

    PENDING_COST_REVIEW --> PENDING_DIRECTOR: Estimador completa revision
    PENDING_COST_REVIEW --> IN_ANALYSIS: Devolver

    PENDING_DIRECTOR --> APPROVED: Director aprueba
    PENDING_DIRECTOR --> IN_ANALYSIS: Devolver

    APPROVED --> [*]: Generar OC

---

Paso 1: Creacion Automatica (OPEN)

El analisis se crea automaticamente cuando logistica enruta items a procura:

• Titulo: "Analisis de Procura - {codigo_requisicion}"
• Codigo: Auto-generado (PA-YYYY-NNNN)
• Items: Copiados desde la requisicion de material con cantidades pendientes
• Vinculo: Cada item mantiene referencia al MaterialRequisitionItem original

No se puede crear un analisis manualmente; siempre se origina desde una requisicion de material.

Endpoint de origen: POST /api/material-requisitions/:id/route-procurement o POST /api/material-requisitions/:id/fulfill-and-procure

---

Paso 2: Analisis por Contratacion (IN_ANALYSIS)

El equipo de contratacion (permiso procurement:analyze) revisa los items y:

2.1 Registrar Items en Inventario

Si algun item no tiene vinculo al catalogo de inventario, contratacion puede registrarlo:

1. Haga clic en Registrar en Inventario junto al item
2. Elija: crear nuevo item o vincular a uno existente
3. Al crear nuevo: se genera codigo ITM-NNNNN automaticamente
4. El item queda vinculado tanto en el analisis como en la requisicion original

Endpoint: POST /api/procurement/analyses/:id/items/:itemId/register-inventory

2.2 Actualizar Notas

Contratacion puede agregar notas a cada item (especificaciones, alternativas, etc.):

Endpoint: PUT /api/procurement/analyses/:id/items

Transicion automatica

Al actualizar items por primera vez, el estado cambia automaticamente de OPEN a IN_ANALYSIS.

2.3 Adjuntar Cotizaciones

Antes de enviar a revision de costos, se debe adjuntar al menos un archivo (cotizacion, proforma, etc.):

1. Use la seccion de Archivos Adjuntos para subir documentos
2. El sistema valida que haya al menos 1 adjunto antes de permitir el envio

---

Paso 3: Revision de Costos (PENDING_COST_REVIEW)

Contratacion envia el analisis para revision de costos:

Requisitos:

• Estado actual: OPEN o IN_ANALYSIS
• Al menos 1 archivo adjunto

Endpoint: POST /api/procurement/analyses/:id/submit-cost-review

Rol: Estimador de Costos

Usuarios con permiso procurement:cost_review:

1. Revisan las cotizaciones adjuntas
2. Validan estimaciones de precios
3. Pueden agregar comentarios (disponibles para todos los roles)
4. Al terminar, hacen clic en Completar Revision

Endpoint: POST /api/procurement/analyses/:id/complete-cost-review

El analisis pasa a PENDING_DIRECTOR y se notifica al director.

---

Paso 4: Aprobacion del Director (PENDING_DIRECTOR)

4.1 Asignacion de Proveedores

El director (permiso procurement:approve_analysis) asigna proveedores a cada item:

1. Para cada item, seleccione uno o mas proveedores
2. Especifique la cantidad asignada a cada proveedor
3. Opcionalmente ingrese el precio unitario
4. La suma de cantidades asignadas debe ser igual a la cantidad requerida

{
  "allocations": [
    {
      "itemId": "uuid-del-item",
      "supplierId": "uuid-del-proveedor",
      "quantity": 50,
      "unitPrice": 25.00
    }
  ]
}

Validaciones:

• La suma de cantidades asignadas por item no puede exceder la cantidad requerida
• Un item puede tener multiples proveedores (ej: 30 unidades de proveedor A, 20 de proveedor B)

Endpoint: POST /api/procurement/analyses/:id/assign-suppliers

4.2 Aprobacion

Una vez asignados todos los proveedores:

1. El director hace clic en Aprobar
2. El sistema valida que todos los items tengan al menos una asignacion de proveedor
3. La suma de asignaciones de cada item debe ser exactamente igual a la cantidad requerida
4. Se registra approvedBy y approvedAt

Endpoint: POST /api/procurement/analyses/:id/approve

4.3 Devolucion

El director (o el estimador de costos desde PENDING_COST_REVIEW) puede devolver el analisis:

1. Haga clic en Devolver
2. Comentario obligatorio: explique que debe corregirse
3. El analisis regresa a IN_ANALYSIS
4. Se notifica al analista asignado

Endpoint: POST /api/procurement/analyses/:id/return

---

Sistema de Comentarios

Todos los roles pueden agregar comentarios al analisis en cualquier estado:

• Contratacion: Notas sobre cotizaciones, alternativas
• Estimador: Observaciones sobre precios
• Director: Instrucciones de asignacion

Los comentarios quedan registrados en el ActivityTimeline con el nombre y rol del usuario.

Permisos requeridos: procurement:analyze, procurement:cost_review o procurement:approve_analysis

Endpoint: POST /api/procurement/analyses/:id/comments

---

Linea de Tiempo (ActivityTimeline)

Cada analisis mantiene un historial completo de actividad:

Accion	Descripcion
CREATED	Analisis creado desde requisicion
STATUS_CHANGE	Cambio de estado (con oldStatus/newStatus)
COST_REVIEW_SUBMITTED	Enviado a revision de costos
COST_REVIEW_COMPLETED	Revision de costos completada
SUPPLIER_ASSIGNED	Proveedores asignados
APPROVED	Analisis aprobado
RETURNED	Devuelto con comentario
COMMENT	Comentario agregado
INVENTORY_ITEM_REGISTERED	Item registrado/vinculado en inventario
PURCHASE_ORDER_GENERATED	Ordenes de compra generadas

Endpoint: GET /api/procurement/analyses/:id/timeline

---

Generacion de PDF

Se puede exportar el analisis completo en formato PDF:

Endpoint: GET /api/procurement/analyses/:id/pdf

---

Tabla de Permisos

Accion	Permiso requerido
Ver analisis	procurement:read
Actualizar items / notas	procurement:analyze
Registrar item en inventario	procurement:analyze
Adjuntar archivos	procurement:analyze
Enviar a revision de costos	procurement:analyze
Completar revision de costos	procurement:cost_review
Asignar proveedores	procurement:approve_analysis
Aprobar analisis	procurement:approve_analysis
Devolver analisis	procurement:approve_analysis
Agregar comentarios	procurement:analyze o procurement:cost_review o procurement:approve_analysis
Generar ordenes de compra	procurement:create