<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="TenantStatField", description="통계 필드 메타데이터 관리")
 *
 * @OA\Schema(
 *   schema="TenantStatField",
 *   type="object",
 *   required={"id","tenant_id","target_table","field_key","field_name","field_type"},
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="target_table", type="string", example="products"),
 *   @OA\Property(property="field_key", type="string", example="margin_rate"),
 *   @OA\Property(property="field_name", type="string", example="마진율(%)"),
 *   @OA\Property(property="field_type", type="string", example="decimal"),
 *   @OA\Property(
 *     property="aggregation_types",
 *     type="array",
 *     nullable=true,
 *     example={"avg","min","max"},
 *
 *     @OA\Items(type="string")
 *   ),
 *
 *   @OA\Property(property="is_critical", type="boolean", example=true),
 *   @OA\Property(property="display_order", type="integer", example=0),
 *   @OA\Property(property="description", type="string", nullable=true, example="제품 마진율 통계"),
 *   @OA\Property(property="created_by", type="integer", nullable=true, example=1),
 *   @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
 *   @OA\Property(property="created_at", type="string", example="2025-11-14 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-11-14 10:10:00")
 * )
 *
 * @OA\Schema(
 *   schema="TenantStatFieldPagination",
 *   type="object",
 *
 *   @OA\Property(property="current_page", type="integer", example=1),
 *   @OA\Property(
 *     property="data",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/TenantStatField")
 *   ),
 *
 *   @OA\Property(property="first_page_url", type="string", example="/api/v1/tenant-stat-fields?page=1"),
 *   @OA\Property(property="from", type="integer", example=1),
 *   @OA\Property(property="last_page", type="integer", example=2),
 *   @OA\Property(property="last_page_url", type="string", example="/api/v1/tenant-stat-fields?page=2"),
 *   @OA\Property(
 *     property="links",
 *     type="array",
 *
 *     @OA\Items(type="object",
 *
 *       @OA\Property(property="url", type="string", nullable=true, example=null),
 *       @OA\Property(property="label", type="string", example="&laquo; Previous"),
 *       @OA\Property(property="active", type="boolean", example=false)
 *     )
 *   ),
 *   @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/tenant-stat-fields?page=2"),
 *   @OA\Property(property="path", type="string", example="/api/v1/tenant-stat-fields"),
 *   @OA\Property(property="per_page", type="integer", example=20),
 *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="to", type="integer", example=20),
 *   @OA\Property(property="total", type="integer", example=9)
 * )
 *
 * @OA\Schema(
 *   schema="TenantStatFieldCreateRequest",
 *   type="object",
 *   required={"target_table","field_key","field_name","field_type"},
 *
 *   @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
 *   @OA\Property(property="field_key", type="string", maxLength=100, example="processing_cost"),
 *   @OA\Property(property="field_name", type="string", maxLength=100, example="가공비(원)"),
 *   @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
 *   @OA\Property(
 *     property="aggregation_types",
 *     type="array",
 *     nullable=true,
 *     example={"avg","sum"},
 *
 *     @OA\Items(type="string", enum={"avg","sum","min","max","count"})
 *   ),
 *
 *   @OA\Property(property="is_critical", type="boolean", nullable=true, example=false),
 *   @OA\Property(property="display_order", type="integer", nullable=true, example=0),
 *   @OA\Property(property="description", type="string", nullable=true, example="제품별 가공비 통계")
 * )
 *
 * @OA\Schema(
 *   schema="TenantStatFieldUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
 *   @OA\Property(property="field_key", type="string", maxLength=100, example="processing_cost"),
 *   @OA\Property(property="field_name", type="string", maxLength=100, example="가공비(원)"),
 *   @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
 *   @OA\Property(
 *     property="aggregation_types",
 *     type="array",
 *     nullable=true,
 *
 *     @OA\Items(type="string", enum={"avg","sum","min","max","count"})
 *   ),
 *
 *   @OA\Property(property="is_critical", type="boolean", nullable=true, example=true),
 *   @OA\Property(property="display_order", type="integer", nullable=true, example=5),
 *   @OA\Property(property="description", type="string", nullable=true, example="제품별 가공비 통계 (일일 집계)")
 * )
 *
 * @OA\Schema(
 *   schema="TenantStatFieldReorderRequest",
 *   type="object",
 *   required={"items"},
 *
 *   @OA\Property(
 *     property="items",
 *     type="array",
 *
 *     @OA\Items(
 *       type="object",
 *
 *       @OA\Property(property="id", type="integer", example=1),
 *       @OA\Property(property="display_order", type="integer", example=10)
 *     )
 *   )
 * )
 *
 * @OA\Schema(
 *   schema="TenantStatFieldBulkUpsertRequest",
 *   type="object",
 *   required={"items"},
 *
 *   @OA\Property(
 *     property="items",
 *     type="array",
 *
 *     @OA\Items(
 *       type="object",
 *
 *       @OA\Property(property="id", type="integer", nullable=true, example=null, description="수정 시 ID 필수, 신규 시 null"),
 *       @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
 *       @OA\Property(property="field_key", type="string", maxLength=100, example="margin_rate"),
 *       @OA\Property(property="field_name", type="string", maxLength=100, example="마진율(%)"),
 *       @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
 *       @OA\Property(
 *         property="aggregation_types",
 *         type="array",
 *         nullable=true,
 *
 *         @OA\Items(type="string")
 *       ),
 *
 *       @OA\Property(property="is_critical", type="boolean", nullable=true, example=true),
 *       @OA\Property(property="display_order", type="integer", nullable=true, example=0),
 *       @OA\Property(property="description", type="string", nullable=true, example=null)
 *     )
 *   )
 * )
 */
class TenantStatFieldApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/tenant-stat-fields",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 목록 조회",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", default=20), example=20),
     *   @OA\Parameter(name="target_table", in="query", @OA\Schema(type="string"), example="products"),
     *   @OA\Parameter(name="is_critical", in="query", @OA\Schema(type="boolean"), example=true),
     *   @OA\Parameter(name="aggregation_type", in="query", @OA\Schema(type="string", enum={"avg","sum","min","max","count"}), example="avg"),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드를 조회했습니다."),
     *       @OA\Property(property="data", ref="#/components/schemas/TenantStatFieldPagination")
     *     )
     *   )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *   path="/api/v1/tenant-stat-fields",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 생성",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldCreateRequest")
     *   ),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드가 생성되었습니다."),
     *       @OA\Property(property="data", ref="#/components/schemas/TenantStatField")
     *     )
     *   )
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *   path="/api/v1/tenant-stat-fields/{id}",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 단건 조회",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드를 조회했습니다."),
     *       @OA\Property(property="data", ref="#/components/schemas/TenantStatField")
     *     )
     *   )
     * )
     */
    public function show() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/tenant-stat-fields/{id}",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 수정",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldUpdateRequest")
     *   ),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드가 수정되었습니다."),
     *       @OA\Property(property="data", ref="#/components/schemas/TenantStatField")
     *     )
     *   )
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/tenant-stat-fields/{id}",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 삭제",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드가 삭제되었습니다."),
     *       @OA\Property(property="data", type="string", example="success")
     *     )
     *   )
     * )
     */
    public function destroy() {}

    /**
     * @OA\Post(
     *   path="/api/v1/tenant-stat-fields/reorder",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 정렬순서 변경",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldReorderRequest")
     *   ),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드 정렬이 변경되었습니다."),
     *       @OA\Property(property="data", type="string", example="success")
     *     )
     *   )
     * )
     */
    public function reorder() {}

    /**
     * @OA\Put(
     *   path="/api/v1/tenant-stat-fields/bulk-upsert",
     *   tags={"TenantStatField"},
     *   summary="통계 필드 일괄 생성/수정",
     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldBulkUpsertRequest")
     *   ),
     *
     *   @OA\Response(
     *     response=200,
     *     description="성공",
     *
     *     @OA\JsonContent(
     *       type="object",
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="통계 필드가 일괄 저장되었습니다."),
     *       @OA\Property(
     *         property="data",
     *         type="object",
     *         @OA\Property(property="created", type="integer", example=3),
     *         @OA\Property(property="updated", type="integer", example=2)
     *       )
     *     )
     *   )
     * )
     */
    public function bulkUpsert() {}
}
