star-erp/app/Modules/Procurement/Contracts/ProcurementServiceInterface.php

<?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;
}