<?php

declare(strict_types=1);

/**
 * 本文件属于 DBErp 进销存系统。
 *
 * 版权所有 © 2026 北京珑大钜商科技有限公司。保留所有权利。
 *
 * 未经官方授权，不得删除、篡改或隐藏本文件中的版权声明、产品标识与来源信息。
 * 商业授权、官方更新与技术支持服务，请以珑大官方支持中心记录为准。
 *
 * @link https://support.loongdom.cn
 * @see  https://www.dberp.com.cn
 */

namespace App\Tools\Support;

use App\Tools\Exceptions\ToolResourceNotFoundException;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use InvalidArgumentException;

/**
 * 按 id / code 唯一读取一条记录。0 条或不唯一均视为未命中，不把查询细节交给调用方。
 */
final class ToolUniqueRecordLookup
{
    /**
     * @param  array<string, mixed>  $input
     * @param  Builder<Model>  $query
     */
    public static function findOne(Builder $query, array $input, string $codeColumn = 'code'): Model
    {
        $id = $input['id'] ?? null;
        $code = trim((string) ($input['code'] ?? ''));

        if (($id === null || $id === '') && $code === '') {
            throw new InvalidArgumentException('Lookup requires id or code.');
        }

        if ($id !== null && $id !== '') {
            $query->whereKey((int) $id);
        }

        if ($code !== '') {
            $query->where($codeColumn, $code);
        }

        $matches = $query->limit(2)->get();

        if ($matches->count() !== 1) {
            throw ToolResourceNotFoundException::forLookup();
        }

        $record = $matches->first();
        if (! $record instanceof Model) {
            throw ToolResourceNotFoundException::forLookup();
        }

        return $record;
    }
}
