<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Position",
 *     description="직급/직책 통합 관리"
 * )
 *
 * @OA\Schema(
 *     schema="Position",
 *     type="object",
 *     required={"id", "tenant_id", "type", "name", "sort_order", "is_active"},
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="tenant_id", type="integer", example=287),
 *     @OA\Property(property="type", type="string", enum={"rank", "title"}, example="rank", description="유형: rank(직급), title(직책)"),
 *     @OA\Property(property="name", type="string", example="대리", description="명칭"),
 *     @OA\Property(property="sort_order", type="integer", example=2, description="정렬 순서"),
 *     @OA\Property(property="is_active", type="boolean", example=true, description="활성화 여부"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="PositionCreateRequest",
 *     type="object",
 *     required={"type", "name"},
 *
 *     @OA\Property(property="type", type="string", enum={"rank", "title"}, example="rank", description="유형: rank(직급), title(직책)"),
 *     @OA\Property(property="name", type="string", example="과장", description="명칭"),
 *     @OA\Property(property="sort_order", type="integer", example=3, description="정렬 순서 (생략시 자동)"),
 *     @OA\Property(property="is_active", type="boolean", example=true, description="활성화 여부")
 * )
 *
 * @OA\Schema(
 *     schema="PositionUpdateRequest",
 *     type="object",
 *
 *     @OA\Property(property="name", type="string", example="과장", description="명칭"),
 *     @OA\Property(property="sort_order", type="integer", example=3, description="정렬 순서"),
 *     @OA\Property(property="is_active", type="boolean", example=true, description="활성화 여부")
 * )
 *
 * @OA\Schema(
 *     schema="PositionReorderRequest",
 *     type="object",
 *     required={"items"},
 *
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *
 *         @OA\Items(
 *             type="object",
 *             required={"id", "sort_order"},
 *
 *             @OA\Property(property="id", type="integer", example=1),
 *             @OA\Property(property="sort_order", type="integer", example=1)
 *         )
 *     )
 * )
 */
class PositionApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/positions",
     *     tags={"Position"},
     *     summary="직급/직책 목록 조회",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="type", in="query", description="유형 필터 (rank: 직급, title: 직책)", @OA\Schema(type="string", enum={"rank", "title"})),
     *     @OA\Parameter(name="is_active", in="query", description="활성화 필터", @OA\Schema(type="boolean")),
     *     @OA\Parameter(name="q", in="query", description="검색어 (명칭)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="per_page", in="query", description="페이지당 개수 (생략시 전체)", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="page", in="query", description="페이지 번호", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Position"))
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/positions",
     *     tags={"Position"},
     *     summary="직급/직책 생성",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PositionCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/Position")
     *         )
     *     ),
     *
     *     @OA\Response(response=409, description="중복 오류")
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/positions/{id}",
     *     tags={"Position"},
     *     summary="직급/직책 단건 조회",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/Position")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="찾을 수 없음")
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/positions/{id}",
     *     tags={"Position"},
     *     summary="직급/직책 수정",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PositionUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/Position")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="찾을 수 없음"),
     *     @OA\Response(response=409, description="중복 오류")
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/positions/{id}",
     *     tags={"Position"},
     *     summary="직급/직책 삭제",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="id", type="integer"),
     *                 @OA\Property(property="deleted_at", type="string", format="date-time")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="찾을 수 없음")
     * )
     */
    public function destroy() {}

    /**
     * @OA\Put(
     *     path="/api/v1/positions/reorder",
     *     tags={"Position"},
     *     summary="직급/직책 순서 변경 (벌크)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PositionReorderRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="success", type="boolean"),
     *                 @OA\Property(property="updated", type="integer")
     *             )
     *         )
     *     )
     * )
     */
    public function reorder() {}
}
