<?php

namespace App\Modules\Procurement\Contracts;

use Illuminate\Support\Collection;

interface ProcurementServiceInterface
{
    /**
     * Get purchase orders within a date range.
     * 
     * @param string $start
     * @param string $end
     * @param array $statuses
     * @return Collection
     */
    public function getPurchaseOrdersByDate(string $start, string $end, array $statuses = ['received', 'completed']): Collection;

    /**
     * Get purchase orders by multiple IDs.
     * 
     * @param array $ids
     * @param array $with
     * @return Collection
     */
    public function getPurchaseOrdersByIds(array $ids, array $with = []): Collection;

    /**
     * Get statistics for the dashboard.
     * 
     * @return array
     */
    public function getDashboardStats(): array;

    /**
     * Update received quantity for a PO item.
     * 
     * @param int $poItemId
     * @param float $quantity
     * @return void
     */
    public function updateReceivedQuantity(int $poItemId, float $quantity): void;

    /**
     * Search pending or partial purchase orders.
     * 
     * @param string $query
     * @return Collection
     */
    public function searchPendingPurchaseOrders(string $query): Collection;

    /**
     * Search vendors by name or code.
     * 
     * @param string $query
     * @return Collection
     */
    public function searchVendors(string $query): Collection;

    /**
     * 取得所有待進貨的採購單列表（不需搜尋條件）。
     * 用於進貨單頁面直接顯示可選擇的採購單。
     * 
     * @return Collection
     */
    public function getPendingPurchaseOrders(): Collection;

    /**
     * 取得所有廠商列表。
     * 
     * @return Collection
     */
    public function getAllVendors(): Collection;
    
    /**
     * Get vendors by multiple IDs.
     * 
     * @param array $ids
     * @return Collection
     */
    public function getVendorsByIds(array $ids): Collection;

    /**
     * 新增供貨商品關聯
     */
    public function attachProductToVendor(int $vendorId, int $productId, ?float $lastPrice): void;

    /**
     * 更新供貨商品價格
     */
    public function updateVendorProductPrice(int $vendorId, int $productId, ?float $lastPrice): void;

    /**
     * 檢查廠商是否已有該供貨商品
     */
    public function checkVendorHasProduct(int $vendorId, int $productId): bool;

    /**
     * 取得供貨商品的價格
     */
    public function getVendorProductPrice(int $vendorId, int $productId): ?float;

    /**
     * 移除供貨商品關聯
     */
    public function detachProductFromVendor(int $vendorId, int $productId): void;

    /**
     * 整批同步供貨商品
     * 
     * @param int $vendorId
     * @param array $productsData Format: [['product_id' => 1, 'last_price' => 100], ...]
     */
    public function syncVendorProducts(int $vendorId, array $productsData): void;
}