<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="Department",
 *   description="부서 관리(목록/조회/등록/수정/삭제) + 부서원 관리 + 부서 권한 매핑"
 * )
 */

/**
 * =========================
 *  Domain 스키마
 * =========================
 */

/**
 * @OA\Schema(
 *   schema="Department",
 *   type="object",
 *   description="부서 상세",
 *   required={"id","name"},
 *
 *   @OA\Property(property="id", type="integer", example=7),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="code", type="string", nullable=true, example="OPS"),
 *   @OA\Property(property="name", type="string", example="운영팀"),
 *   @OA\Property(property="description", type="string", nullable=true, example="서비스 운영 총괄"),
 *   @OA\Property(property="is_active", type="integer", example=1),
 *   @OA\Property(property="sort_order", type="integer", example=10),
 *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-16 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-16 10:00:00")
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentBrief",
 *   type="object",
 *   description="부서 요약",
 *   required={"id","name"},
 *
 *   @OA\Property(property="id", type="integer", example=7),
 *   @OA\Property(property="code", type="string", nullable=true, example="OPS"),
 *   @OA\Property(property="name", type="string", example="운영팀"),
 *   @OA\Property(property="is_active", type="integer", example=1),
 *   @OA\Property(property="sort_order", type="integer", example=10)
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentList",
 *   type="array",
 *
 *   @OA\Items(ref="#/components/schemas/DepartmentBrief")
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentCreateRequest",
 *   type="object",
 *   required={"name"},
 *
 *   @OA\Property(property="code", type="string", nullable=true, example="OPS"),
 *   @OA\Property(property="name", type="string", example="운영팀"),
 *   @OA\Property(property="description", type="string", nullable=true, example="서비스 운영 총괄"),
 *   @OA\Property(property="is_active", type="integer", enum={0,1}, example=1),
 *   @OA\Property(property="sort_order", type="integer", example=0)
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="code", type="string", nullable=true, example="OPS2"),
 *   @OA\Property(property="name", type="string", example="운영기획팀"),
 *   @OA\Property(property="description", type="string", nullable=true, example="운영 기획/성과 관리"),
 *   @OA\Property(property="is_active", type="integer", enum={0,1}, example=1),
 *   @OA\Property(property="sort_order", type="integer", example=5)
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentUserAttachRequest",
 *   type="object",
 *   required={"user_id"},
 *
 *   @OA\Property(property="user_id", type="integer", example=12),
 *   @OA\Property(property="is_primary", type="integer", enum={0,1}, nullable=true, example=0),
 *   @OA\Property(property="joined_at", type="string", format="date-time", nullable=true, example="2025-08-21 10:00:00")
 * )
 *
 * @OA\Schema(
 *    schema="UserBrief",
 *    type="object",
 *    description="부서원 요약",
 *    required={"id","name","email"},
 *
 *    @OA\Property(property="id", type="integer", example=12),
 *    @OA\Property(property="name", type="string", example="홍길동"),
 *    @OA\Property(property="email", type="string", format="email", example="hong@example.com"),
 *    @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678"),
 *    @OA\Property(property="is_active", type="integer", example=1)
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentPermissionUpsertSingle",
 *   type="object",
 *   required={"permission_id"},
 *
 *   @OA\Property(property="permission_id", type="integer", example=25),
 *   @OA\Property(property="is_allowed", type="integer", enum={0,1}, example=1, description="1=ALLOW, 0=DENY(차단)")
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentPermissionUpsertMany",
 *   type="object",
 *   required={"items"},
 *
 *   @OA\Property(
 *     property="items",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/DepartmentPermissionUpsertSingle")
 *   )
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentPermissionRevokeSingle",
 *   type="object",
 *   required={"permission_id"},
 *
 *   @OA\Property(property="permission_id", type="integer", example=25)
 * )
 *
 * @OA\Schema(
 *   schema="DepartmentPermissionRevokeMany",
 *   type="object",
 *   required={"items"},
 *
 *   @OA\Property(
 *     property="items",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/DepartmentPermissionRevokeSingle")
 *   )
 * )
 */
class DepartmentApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/departments",
     *   summary="부서 목록 조회",
     *   description="테넌트 범위 내 부서 목록을 페이징으로 반환합니다. (q로 이름/코드 검색)",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=10)),
     *   @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string", example="운영")),
     *   @OA\Parameter(name="is_active", in="query", required=false, @OA\Schema(type="integer", enum={0,1}, example=1)),
     *
     *   @OA\Response(response=200, description="부서 목록 조회 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 목록 조회 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="current_page", type="integer", example=1),
     *         @OA\Property(property="per_page", type="integer", example=10),
     *         @OA\Property(property="total", type="integer", example=2),
     *         @OA\Property(property="data", ref="#/components/schemas/DepartmentList")
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/departments/tree",
     *   summary="부서 트리 조회",
     *   description="부서를 계층 구조(트리)로 조회합니다. with_users=1 시 각 부서의 소속 사용자도 포함됩니다.",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="with_users", in="query", required=false, description="사용자 포함 여부", @OA\Schema(type="integer", enum={0,1}, example=0)),
     *
     *   @OA\Response(response=200, description="부서 트리 조회 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 트리 조회"),
     *       @OA\Property(property="data", type="array",
     *
     *         @OA\Items(
     *           type="object",
     *
     *           @OA\Property(property="id", type="integer", example=1),
     *           @OA\Property(property="name", type="string", example="본사"),
     *           @OA\Property(property="code", type="string", nullable=true, example="HQ"),
     *           @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
     *           @OA\Property(property="sort_order", type="integer", example=1),
     *           @OA\Property(property="is_active", type="integer", example=1),
     *           @OA\Property(property="children", type="array", @OA\Items(ref="#/components/schemas/DepartmentBrief")),
     *           @OA\Property(property="users", type="array", nullable=true, @OA\Items(ref="#/components/schemas/UserBrief"))
     *         )
     *       )
     *     )
     *   )
     * )
     */
    public function tree() {}

    /**
     * @OA\Get(
     *   path="/api/v1/departments/{id}",
     *   summary="부서 단건 조회",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *
     *   @OA\Response(response=200, description="부서 조회 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 조회 성공"),
     *       @OA\Property(property="data", ref="#/components/schemas/Department")
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *   path="/api/v1/departments",
     *   summary="부서 생성",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentCreateRequest")),
     *
     *   @OA\Response(response=200, description="부서 생성 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 생성 성공"),
     *       @OA\Property(property="data", ref="#/components/schemas/Department")
     *     )
     *   ),
     *
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/departments/{id}",
     *   summary="부서 수정",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentUpdateRequest")),
     *
     *   @OA\Response(response=200, description="부서 수정 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 수정 성공"),
     *       @OA\Property(property="data", ref="#/components/schemas/Department")
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/departments/{id}",
     *   summary="부서 삭제(소프트)",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *
     *   @OA\Response(response=200, description="부서 삭제 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 삭제 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="id", type="integer", example=7),
     *         @OA\Property(property="deleted_at", type="string", format="date-time", example="2025-08-21 11:00:00")
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Get(
     *   path="/api/v1/departments/{id}/users",
     *   summary="부서 사용자 목록",
     *   description="해당 부서에 속한 사용자 목록을 페이징으로 반환합니다.",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=20)),
     *
     *   @OA\Response(response=200, description="부서 사용자 목록 조회 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 사용자 목록 조회 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="current_page", type="integer", example=1),
     *         @OA\Property(property="per_page", type="integer", example=20),
     *         @OA\Property(property="total", type="integer", example=1),
     *         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/UserBrief"))
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function users() {}

    /**
     * @OA\Post(
     *   path="/api/v1/departments/{id}/users",
     *   summary="부서 사용자 배정(단건)",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentUserAttachRequest")),
     *
     *   @OA\Response(response=200, description="부서 사용자 배정 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 사용자 배정 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="department_id", type="integer", example=7),
     *         @OA\Property(property="user_id", type="integer", example=12)
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=409, description="이미 배정됨", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function attachUser() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/departments/{id}/users/{user}",
     *   summary="부서 사용자 해제(단건)",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *   @OA\Parameter(name="user", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *
     *   @OA\Response(response=200, description="부서 사용자 해제 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 사용자 해제 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="user_id", type="integer", example=12),
     *         @OA\Property(property="deleted_at", type="string", format="date-time", example="2025-08-21 11:00:00")
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function detachUser() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/departments/{id}/users/{user}/primary",
     *   summary="주부서 설정/해제",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *   @OA\Parameter(name="user", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="is_primary", type="integer", enum={0,1}, example=1)
     *     )
     *   ),
     *
     *   @OA\Response(response=200, description="주부서 설정 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="주부서 설정 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="user_id", type="integer", example=12),
     *         @OA\Property(property="department_id", type="integer", example=7),
     *         @OA\Property(property="is_primary", type="integer", example=1)
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function setPrimary() {}

    /**
     * @OA\Get(
     *   path="/api/v1/departments/{id}/permissions",
     *   summary="부서 권한 목록",
     *   description="부서에 설정된 ALLOW/DENY 목록을 조회합니다. (is_allowed=1|0, menu_id 필터 지원)",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *   @OA\Parameter(name="menu_id", in="query", required=false, @OA\Schema(type="integer", example=101)),
     *   @OA\Parameter(name="is_allowed", in="query", required=false, @OA\Schema(type="integer", enum={0,1}, example=1)),
     *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=20)),
     *
     *   @OA\Response(response=200, description="부서 권한 목록 조회 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 권한 목록 조회 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="current_page", type="integer", example=1),
     *         @OA\Property(property="per_page", type="integer", example=20),
     *         @OA\Property(property="total", type="integer", example=3),
     *         @OA\Property(property="data", type="array",
     *
     *           @OA\Items(type="object",
     *
     *             @OA\Property(property="permission_id", type="integer", example=25),
     *             @OA\Property(property="permission_code", type="string", example="menu.101.read"),
     *             @OA\Property(property="is_allowed", type="integer", example=1),
     *             @OA\Property(property="reason", type="string", nullable=true, example="보안 이슈"),
     *             @OA\Property(property="effective_from", type="string", format="date-time", nullable=true),
     *             @OA\Property(property="effective_to", type="string", format="date-time", nullable=true)
     *           )
     *         )
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function listPermissions() {}

    /**
     * @OA\Post(
     *   path="/api/v1/departments/{id}/permissions",
     *   summary="부서 권한 부여/차단(Upsert: 단건/배치)",
     *   description="permission_id 기준으로 ALLOW(1) 또는 DENY(0) 처리합니다. 단건 또는 items 배열을 모두 지원합니다.",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
     *
     *   @OA\RequestBody(
     *     required=true,
     *
     *     @OA\JsonContent(oneOf={
     *
     *       @OA\Schema(ref="#/components/schemas/DepartmentPermissionUpsertSingle"),
     *       @OA\Schema(ref="#/components/schemas/DepartmentPermissionUpsertMany")
     *     })
     *   ),
     *
     *   @OA\Response(response=200, description="부서 권한 적용 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 권한 적용 성공"),
     *       @OA\Property(property="data", type="object",
     *         @OA\Property(property="processed", type="integer", example=2),
     *         @OA\Property(property="succeeded", type="integer", example=2),
     *         @OA\Property(property="failed", type="array", @OA\Items(type="object"))
     *       )
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function upsertPermission() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/departments/{id}/permissions/{permission}",
     *   summary="부서 권한 해제",
     *   description="지정 권한을 부서 매핑에서 제거합니다.",
     *   tags={"Department"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, description="부서 ID", @OA\Schema(type="integer", example=7)),
     *   @OA\Parameter(name="permission", in="path", required=true, description="권한 ID", @OA\Schema(type="integer", example=15)),
     *
     *   @OA\Response(response=200, description="부서 권한 해제 성공",
     *
     *     @OA\JsonContent(
     *
     *       @OA\Property(property="success", type="boolean", example=true),
     *       @OA\Property(property="message", type="string", example="부서 권한 제거")
     *     )
     *   ),
     *
     *   @OA\Response(response=404, description="부서 또는 권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function revokePermission() {}
}
