<?php

declare(strict_types=1);

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

namespace App\Tools\Support;

/**
 * 列表类 Tool 共用的分页 / 排序 JSON Schema 片段。
 */
final class ToolListSchema
{
    /**
     * @param  list<string>  $sortFields
     * @return array<string, mixed>
     */
    public static function paginationInputProperties(array $sortFields, string $defaultSort, string $defaultDir = 'desc'): array
    {
        return [
            'page' => [
                'type' => 'integer',
                'minimum' => 1,
                'maximum' => 10000,
                'default' => 1,
                'description' => '1-based page index. Large result sets must be traversed page by page.',
            ],
            'per_page' => [
                'type' => 'integer',
                'minimum' => 1,
                'maximum' => 100,
                'default' => 20,
                'description' => 'Page size. Maximum 100; Core bounds this and does not stream unbounded lists.',
            ],
            'sort_by' => [
                'type' => 'string',
                'enum' => $sortFields,
                'default' => $defaultSort,
                'description' => 'Whitelist sort field.',
            ],
            'sort_dir' => [
                'type' => 'string',
                'enum' => ['asc', 'desc'],
                'default' => $defaultDir,
                'description' => 'Sort direction.',
            ],
        ];
    }

    /**
     * @param  array<string, mixed>  $itemSchema
     * @return array<string, mixed>
     */
    public static function paginatedOutputSchema(array $itemSchema): array
    {
        return [
            'type' => 'object',
            'required' => ['items', 'page', 'per_page', 'total', 'has_more'],
            'additionalProperties' => false,
            'properties' => [
                'items' => [
                    'type' => 'array',
                    'items' => $itemSchema,
                ],
                'page' => ['type' => 'integer'],
                'per_page' => ['type' => 'integer'],
                'total' => ['type' => 'integer'],
                'has_more' => ['type' => 'boolean'],
            ],
        ];
    }

    /**
     * @param  array<string, mixed>  $itemSchema
     * @return array<string, mixed>
     */
    public static function paginatedOutputSchemaWithCurrency(array $itemSchema): array
    {
        $schema = self::paginatedOutputSchema($itemSchema);
        $schema['required'][] = 'currency';
        $schema['properties']['currency'] = ToolCurrency::outputSchema();

        return $schema;
    }
}
