sam-api/app/Swagger/v1/ApprovalApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Approvals", description="전자결재 문서 관리")
 *
 * @OA\Schema(
 *     schema="Approval",
 *     type="object",
 *     description="결재 문서 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="문서 ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="form_id", type="integer", example=1, description="양식 ID"),
 *     @OA\Property(property="drafter_id", type="integer", example=10, description="기안자 ID"),
 *     @OA\Property(property="doc_number", type="string", example="APR-2024-0001", nullable=true, description="문서번호"),
 *     @OA\Property(property="title", type="string", example="휴가 신청", description="제목"),
 *     @OA\Property(property="content", type="object", description="문서 내용 JSON"),
 *     @OA\Property(property="status", type="string", enum={"draft","pending","approved","rejected","cancelled"}, example="pending", description="상태"),
 *     @OA\Property(property="current_step", type="integer", example=1, nullable=true, description="현재 결재 단계"),
 *     @OA\Property(property="submitted_at", type="string", format="date-time", nullable=true, description="상신일시"),
 *     @OA\Property(property="completed_at", type="string", format="date-time", nullable=true, description="완료일시"),
 *     @OA\Property(property="form", type="object", nullable=true, description="결재 양식 정보",
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="name", type="string", example="품의서"),
 *         @OA\Property(property="code", type="string", example="REQUEST_01")
 *     ),
 *     @OA\Property(property="drafter", type="object", nullable=true, description="기안자 정보",
 *         @OA\Property(property="id", type="integer", example=10),
 *         @OA\Property(property="name", type="string", example="홍길동")
 *     ),
 *     @OA\Property(property="steps", type="array", description="결재 단계", @OA\Items(ref="#/components/schemas/ApprovalStepDetail")),
 *     @OA\Property(property="created_at", type="string", format="date-time", example="2024-01-01T09:00:00Z"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", example="2024-01-01T09:00:00Z")
 * )
 *
 * @OA\Schema(
 *     schema="ApprovalStepDetail",
 *     type="object",
 *     description="결재 단계 상세 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="step_order", type="integer", example=1, description="단계 순서"),
 *     @OA\Property(property="type", type="string", enum={"approval","agreement","reference"}, example="approval", description="단계 유형"),
 *     @OA\Property(property="user_id", type="integer", example=20, description="결재자 ID"),
 *     @OA\Property(property="status", type="string", enum={"pending","approved","rejected","skipped"}, example="pending", description="단계 상태"),
 *     @OA\Property(property="comment", type="string", nullable=true, description="결재 의견"),
 *     @OA\Property(property="acted_at", type="string", format="date-time", nullable=true, description="결재일시"),
 *     @OA\Property(property="is_read", type="boolean", example=false, description="열람 여부 (참조)"),
 *     @OA\Property(property="read_at", type="string", format="date-time", nullable=true, description="열람일시"),
 *     @OA\Property(property="user", type="object", nullable=true, description="결재자 정보",
 *         @OA\Property(property="id", type="integer", example=20),
 *         @OA\Property(property="name", type="string", example="김부장")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ApprovalStoreRequest",
 *     type="object",
 *     required={"form_id", "title"},
 *     description="결재 문서 생성/임시저장 요청",
 *
 *     @OA\Property(property="form_id", type="integer", example=1, description="양식 ID"),
 *     @OA\Property(property="title", type="string", example="휴가 신청", description="제목"),
 *     @OA\Property(property="content", type="object", description="문서 내용 JSON"),
 *     @OA\Property(property="steps", type="array", description="결재 단계 (임시저장 시 선택)", @OA\Items(type="object",
 *         @OA\Property(property="type", type="string", enum={"approval","agreement","reference"}, example="approval"),
 *         @OA\Property(property="user_id", type="integer", example=20)
 *     ))
 * )
 *
 * @OA\Schema(
 *     schema="ApprovalUpdateRequest",
 *     type="object",
 *     description="결재 문서 수정 요청 (임시저장 상태만 가능)",
 *
 *     @OA\Property(property="title", type="string", example="휴가 신청 (수정)", description="제목"),
 *     @OA\Property(property="content", type="object", description="문서 내용 JSON"),
 *     @OA\Property(property="steps", type="array", description="결재 단계", @OA\Items(type="object"))
 * )
 *
 * @OA\Schema(
 *     schema="ApprovalSubmitRequest",
 *     type="object",
 *     required={"steps"},
 *     description="결재 상신 요청",
 *
 *     @OA\Property(property="steps", type="array", description="결재 단계 (필수)", @OA\Items(type="object",
 *         @OA\Property(property="type", type="string", enum={"approval","agreement","reference"}, example="approval"),
 *         @OA\Property(property="user_id", type="integer", example=20)
 *     ))
 * )
 *
 * @OA\Schema(
 *     schema="ApprovalSummary",
 *     type="object",
 *     description="결재 현황 요약",
 *
 *     @OA\Property(property="draft", type="integer", example=3, description="임시저장"),
 *     @OA\Property(property="pending", type="integer", example=5, description="진행중"),
 *     @OA\Property(property="approved", type="integer", example=10, description="승인완료"),
 *     @OA\Property(property="rejected", type="integer", example=2, description="반려")
 * )
 *
 * @OA\Schema(
 *     schema="InboxSummary",
 *     type="object",
 *     description="결재함 현황 요약",
 *
 *     @OA\Property(property="requested", type="integer", example=3, description="결재 요청"),
 *     @OA\Property(property="scheduled", type="integer", example=2, description="결재 예정"),
 *     @OA\Property(property="completed", type="integer", example=15, description="결재 완료"),
 *     @OA\Property(property="rejected", type="integer", example=1, description="반려")
 * )
 */
class ApprovalApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/approvals/drafts",
     *     tags={"Approvals"},
     *     summary="기안함 - 내가 작성한 문서 목록",
     *     description="로그인 사용자가 기안한 결재 문서 목록을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"draft","pending","approved","rejected","cancelled"})),
     *     @OA\Parameter(name="search", in="query", description="검색어 (제목, 문서번호)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"created_at","submitted_at","completed_at","title"}, default="created_at")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
     *     @OA\Parameter(ref="#/components/parameters/Page"),
     *     @OA\Parameter(ref="#/components/parameters/Size"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="current_page", type="integer", example=1),
     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Approval")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=15)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function drafts() {}

    /**
     * @OA\Get(
     *     path="/api/v1/approvals/drafts/summary",
     *     tags={"Approvals"},
     *     summary="기안함 현황 카드",
     *     description="기안 문서의 상태별 건수를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ApprovalSummary"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function draftsSummary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/approvals/inbox",
     *     tags={"Approvals"},
     *     summary="결재함 - 내가 결재할/결재한 문서",
     *     description="로그인 사용자에게 결재 요청된 문서 목록을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="filter", in="query", description="필터 (requested: 결재요청, scheduled: 결재예정, completed: 결재완료, rejected: 반려)", @OA\Schema(type="string", enum={"requested","scheduled","completed","rejected"})),
     *     @OA\Parameter(name="search", in="query", description="검색어 (제목, 문서번호, 기안자)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"created_at","submitted_at","title"}, default="submitted_at")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
     *     @OA\Parameter(ref="#/components/parameters/Page"),
     *     @OA\Parameter(ref="#/components/parameters/Size"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="current_page", type="integer", example=1),
     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Approval")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=10)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function inbox() {}

    /**
     * @OA\Get(
     *     path="/api/v1/approvals/inbox/summary",
     *     tags={"Approvals"},
     *     summary="결재함 현황 카드",
     *     description="결재함의 상태별 건수를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/InboxSummary"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function inboxSummary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/approvals/reference",
     *     tags={"Approvals"},
     *     summary="참조함 - 참조로 받은 문서",
     *     description="로그인 사용자가 참조자로 지정된 문서 목록을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="is_read", in="query", description="열람 여부 필터", @OA\Schema(type="boolean")),
     *     @OA\Parameter(name="search", in="query", description="검색어 (제목, 문서번호, 기안자)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"created_at","submitted_at","title"}, default="submitted_at")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
     *     @OA\Parameter(ref="#/components/parameters/Page"),
     *     @OA\Parameter(ref="#/components/parameters/Size"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="current_page", type="integer", example=1),
     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Approval")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=8)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function reference() {}

    /**
     * @OA\Get(
     *     path="/api/v1/approvals/{id}",
     *     tags={"Approvals"},
     *     summary="결재 문서 상세 조회",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals",
     *     tags={"Approvals"},
     *     summary="결재 문서 생성 (임시저장)",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/ApprovalStoreRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="생성 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="양식을 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Patch(
     *     path="/api/v1/approvals/{id}",
     *     tags={"Approvals"},
     *     summary="결재 문서 수정",
     *     description="임시저장 상태의 문서만 수정할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/ApprovalUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="잘못된 요청 또는 수정 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/approvals/{id}",
     *     tags={"Approvals"},
     *     summary="결재 문서 삭제",
     *     description="임시저장 상태의 문서만 삭제할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @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", example="삭제 완료"),
     *             @OA\Property(property="data", type="boolean", example=true)
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="삭제 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/submit",
     *     tags={"Approvals"},
     *     summary="결재 상신",
     *     description="임시저장 문서를 결재선에 상신합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/ApprovalSubmitRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="상신 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="상신 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function submit() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/approve",
     *     tags={"Approvals"},
     *     summary="결재 승인",
     *     description="현재 순서의 결재자가 문서를 승인합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=false,
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="comment", type="string", example="승인합니다.", description="결재 의견 (선택)")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="승인 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="결재 불가 상태 또는 결재 순서 아님", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function approve() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/reject",
     *     tags={"Approvals"},
     *     summary="결재 반려",
     *     description="현재 순서의 결재자가 문서를 반려합니다. 반려 사유는 필수입니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"comment"},
     *
     *             @OA\Property(property="comment", type="string", example="서류가 미비합니다. 재작성 바랍니다.", description="반려 사유 (필수)")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="반려 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="결재 불가 상태 또는 결재 순서 아님", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, 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")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function reject() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/cancel",
     *     tags={"Approvals"},
     *     summary="결재 회수",
     *     description="기안자가 진행중인 문서를 회수합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="회수 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="회수 불가 상태 또는 기안자가 아님", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function cancel() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/read",
     *     tags={"Approvals"},
     *     summary="열람 처리",
     *     description="참조자가 문서를 열람 처리합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="열람 처리 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="참조자가 아님", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function markRead() {}

    /**
     * @OA\Post(
     *     path="/api/v1/approvals/{id}/unread",
     *     tags={"Approvals"},
     *     summary="미열람 처리",
     *     description="참조자가 문서를 미열람 처리합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="미열람 처리 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Approval"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="참조자가 아님", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function markUnread() {}
}