📑 Compras

---

1. 🧩 Descripción General

El módulo de Compras permite gestionar la adquisición de productos y servicios desde proveedores. Controla solicitudes, órdenes de compra, recepción de mercancía y conexión con inventarios y finanzas. Su propósito es asegurar el abastecimiento oportuno, con trazabilidad y control financiero.

---

2. 🧱 Modelos del Módulo

a. PurchaseRequest

• id: integer (PK)
• created_by: FK → User
• status: enum (pendiente, autorizada, rechazada)
• observations: text
• requested_at: datetime

b. PurchaseRequestItem

• id: integer (PK)
• purchase_request_id: FK → PurchaseRequest
• product_id: FK → Product
• quantity: decimal
• unit: string

c. PurchaseOrder

• id: integer (PK)
• provider_id: FK → Provider
• requested_by: FK → User
• status: enum (pendiente, enviada, parcial, completa, cancelada)
• order_date: datetime
• expected_date: datetime
• subtotal, tax, total: decimal

d. PurchaseOrderItem

• id: integer (PK)
• purchase_order_id: FK → PurchaseOrder
• product_id: FK → Product
• quantity_ordered: decimal
• quantity_received: decimal
• unit_price: decimal

e. PurchaseReceipt

• id: integer (PK)
• purchase_order_id: FK → PurchaseOrder
• received_by: FK → User
• received_at: datetime
• document: string (path o número de remisión)

f. PurchaseReceiptItem

• id: integer (PK)
• purchase_receipt_id: FK → PurchaseReceipt
• purchase_order_item_id: FK → PurchaseOrderItem
• quantity_received: decimal
• batch_number: string
• expiry_date: date

---

3. 🔁 Funciones del Controlador

• index(): Listado de órdenes de compra.
• store(): Crear orden desde solicitud o directa.
• show($id): Detalle de una orden.
• update($id): Editar orden (si no enviada).
• destroy($id): Cancelar orden (si no completada).
• receive(): Registrar recepción parcial o completa.
• history(): Obtener historial de compras por proveedor/producto.
• authorizeRequest(): Aprobar solicitud interna.

---

4. 🌐 Endpoints detallados y justificados

Método	Ruta	Descripción	Justificación
GET	/api/purchase-orders	Lista de órdenes	Control de compras
POST	/api/purchase-orders	Crear orden	Registrar nuevas adquisiciones
GET	/api/purchase-orders/{id}	Ver detalle	Revisión completa del pedido
PUT	/api/purchase-orders/{id}	Editar	Ajustes antes de enviar
DELETE	/api/purchase-orders/{id}	Cancelar	Anulación de orden no utilizada
POST	/api/purchase-orders/{id}/receive	Registrar recepción	Entrada a inventario + control de entrega
GET	/api/purchase-orders/history/product/{product_id}	Historial por producto	Trazabilidad
GET	/api/purchase-orders/history/provider/{provider_id}	Historial por proveedor	Análisis de desempeño

---

5. 🖥️ Diseño UX sugerido (flujo de usuario)

Página principal: "Órdenes de Compra"

• Filtros: estado, proveedor, fechas
• Tabla con órdenes recientes
• Acciones:
  • Crear nueva orden
  • Ver detalle
  • Recibir productos

Página: "Nueva Orden"

• Formulario:
  • Selección de proveedor
  • Fecha estimada
  • Productos y cantidades
• Botón: Enviar/Guardar

Página: "Recepción"

• Mostrar productos pendientes
• Campos:
  • Cantidad recibida
  • Lote
  • Fecha de caducidad
• Botón: Confirmar recepción

---

6. 📄 Vistas sugeridas (tipo wireframe)

Vista	Campos sugeridos	Acciones
Órdenes	#, proveedor, estado, fecha, total	Ver, Recibir, Cancelar
Formulario orden	Proveedor, productos, cantidades, precios	Guardar, Enviar
Recepción	Producto, cantidad pedida, recibida, lote	Confirmar, Editar

---

7. 🔗 Conexión Frontend ↔ API JSON:API

Acción en Frontend	Método/API	Resultado esperado
Cargar órdenes	GET /api/purchase-orders	Mostrar listado
Crear orden	POST /api/purchase-orders	Alta y redirección
Ver orden	GET /api/purchase-orders/{id}	Detalles de productos
Editar orden	PUT /api/purchase-orders/{id}	Actualizar info
Cancelar	DELETE /api/purchase-orders/{id}	Estado = cancelada
Registrar recepción	POST /api/purchase-orders/{id}/receive	Actualiza existencias
Ver historial	GET /api/purchase-orders/history/product/{id}	Mostrar compras previas

---

🧩 Esta documentación conecta el backend de compras con el inventario, finanzas y proveedores. Su diseño permite operar eficientemente el flujo de adquisición y trazabilidad de insumos dentro del ERP.