<?php

namespace App\Modules\Inventory\Contracts;

/**
 * 產品服務介面 — 供跨模組使用（如 Integration 模組）。
 */
interface ProductServiceInterface
{
    /**
     * 透過外部 POS ID 進行產品新增或更新（Upsert）。
     *
     * @param array $data
     * @return object
     */
    public function upsertFromPos(array $data);

    /**
     * 透過外部 POS ID 查找產品。
     *
     * @param string $externalPosId
     * @return object|null
     */
    public function findByExternalPosId(string $externalPosId);

    /**
     * 透過多個外部 POS ID 查找產品。
     *
     * @param array $externalPosIds
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function findByExternalPosIds(array $externalPosIds);

    /**
     * 透過多個 ERP 商品代碼查找產品（供販賣機 API 使用）。
     *
     * @param array $codes
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function findByCodes(array $codes);

    /**
     * 建立新商品。
     *
     * @param array $data
     * @return \App\Modules\Inventory\Models\Product
     */
    public function createProduct(array $data);

    /**
     * 更新現有商品。
     *
     * @param \App\Modules\Inventory\Models\Product $product
     * @param array $data
     * @return \App\Modules\Inventory\Models\Product
     */
    public function updateProduct(\App\Modules\Inventory\Models\Product $product, array $data);

    /**
     * 生成隨機 8 碼代號 (大寫英文+數字)。
     *
     * @return string
     */
    public function generateRandomCode();

    /**
     * 生成隨機 13 碼條碼 (純數字)。
     *
     * @return string
     */
    public function generateRandomBarcode();

    /**
     * 根據條碼或代號查找商品。
     *
     * @param string|null $barcode
     * @param string|null $code
     * @return \App\Modules\Inventory\Models\Product|null
     */
    public function findByBarcodeOrCode(?string $barcode, ?string $code);
}
