<?php

namespace App\Modules\Inventory\Contracts;

interface InventoryServiceInterface
{
    /**
     * Check if a product has sufficient stock in a specific warehouse.
     *
     * @param int $productId
     * @param int $warehouseId
     * @param float $quantity
     * @return bool
     */
    public function checkStock(int $productId, int $warehouseId, float $quantity): bool;

    /**
     * @param int $productId
     * @param int $warehouseId
     * @param float $quantity
     * @param string|null $reason
     * @param bool $force
     * @param string|null $slot
     * @return void
     */
    public function decreaseStock(int $productId, int $warehouseId, float $quantity, ?string $reason = null, bool $force = false, ?string $slot = null): void;

    /**
     * Get all active warehouses.
     * 
     * @return \Illuminate\Support\Collection
     */
    public function getAllWarehouses();

    /**
     * Get multiple products by their IDs.
     * 
     * @param array $ids
     * @return \Illuminate\Support\Collection
     */
    public function getProductsByIds(array $ids);

    /**
     * Search products by name.
     * 
     * @param string $name
     * @return \Illuminate\Support\Collection
     */
    public function getProductsByName(string $name);

    /**
     * Get a specific product by ID.
     * 
     * @param int $id
     * @return object|null
     */
    public function getProduct(int $id);

    /**
     * Get a specific warehouse by ID.
     * 
     * @param int $id
     * @return object|null
     */
    public function getWarehouse(int $id);

    /**
     * Get all available inventories in a specific warehouse.
     * 
     * @param int $warehouseId
     * @return \Illuminate\Support\Collection
     */
    public function getInventoriesByWarehouse(int $warehouseId);

    /**
     * Get all products.
     * 
     * @return \Illuminate\Support\Collection
     */
    public function getAllProducts();

    /**
     * Get all units.
     * 
     * @return \Illuminate\Support\Collection
     */
    public function getUnits();

    /**
     * Create a new inventory record (e.g., for finished goods).
     * 
     * @param array $data
     * @return object
     */
    public function createInventoryRecord(array $data);

    /**
     * Decrease quantity of a specific inventory record.
     * 
     * @param int $inventoryId
     * @param float $quantity
     * @param string|null $reason
     * @param string|null $referenceType
     * @param int|string|null $referenceId
     * @return void
     */
    public function decreaseInventoryQuantity(int $inventoryId, float $quantity, ?string $reason = null, ?string $referenceType = null, $referenceId = null);

    /**
     * Find a specific inventory record by warehouse, product and batch.
     * 
     * @param int $warehouseId
     * @param int $productId
     * @param string|null $batchNumber
     * @return object|null
     */
    public function findInventoryByBatch(int $warehouseId, int $productId, ?string $batchNumber);

    /**
     * 取得即時庫存查詢資料（含統計卡片 + 分頁明細）。
     *
     * @param array $filters 篩選條件
     * @param int $perPage 每頁筆數
     * @return array
     */
    public function getStockQueryData(array $filters = [], int $perPage = 10): array;

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