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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Account",
 *     description="계정 관리 (탈퇴, 사용중지, 약관동의)"
 * )
 *
 * @OA\Schema(
 *     schema="AgreementItem",
 *     type="object",
 *
 *     @OA\Property(property="type", type="string", example="marketing"),
 *     @OA\Property(property="label", type="string", example="마케팅 정보 수신"),
 *     @OA\Property(property="required", type="boolean", example=false),
 *     @OA\Property(property="agreed", type="boolean", example=true),
 *     @OA\Property(property="agreed_at", type="string", format="date-time", nullable=true, example="2025-12-19T10:00:00+09:00")
 * )
 *
 * @OA\Schema(
 *     schema="AgreementsResponse",
 *     type="object",
 *
 *     @OA\Property(
 *         property="agreements",
 *         type="object",
 *         additionalProperties={"$ref": "#/components/schemas/AgreementItem"}
 *     ),
 *     @OA\Property(
 *         property="types",
 *         type="object",
 *         description="약관 유형 레이블",
 *         example={"terms": "이용약관", "privacy": "개인정보 처리방침", "marketing": "마케팅 정보 수신"}
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="WithdrawRequest",
 *     type="object",
 *     required={"password"},
 *
 *     @OA\Property(property="password", type="string", example="currentPassword123", description="현재 비밀번호 (확인용)"),
 *     @OA\Property(property="reason", type="string", enum={"not_using", "difficult", "alternative", "privacy", "other"}, example="not_using", description="탈퇴 사유"),
 *     @OA\Property(property="detail", type="string", nullable=true, maxLength=500, example="더 이상 필요하지 않습니다.", description="상세 사유")
 * )
 *
 * @OA\Schema(
 *     schema="WithdrawResponse",
 *     type="object",
 *
 *     @OA\Property(property="withdrawn_at", type="string", format="date-time", example="2025-12-19T10:00:00+09:00")
 * )
 *
 * @OA\Schema(
 *     schema="SuspendResponse",
 *     type="object",
 *
 *     @OA\Property(property="suspended", type="boolean", example=true),
 *     @OA\Property(property="new_default_tenant_id", type="integer", nullable=true, example=2, description="새 기본 테넌트 ID (없으면 null)")
 * )
 *
 * @OA\Schema(
 *     schema="UpdateAgreementsRequest",
 *     type="object",
 *     required={"agreements"},
 *
 *     @OA\Property(
 *         property="agreements",
 *         type="array",
 *
 *         @OA\Items(
 *             type="object",
 *             required={"type", "agreed"},
 *
 *             @OA\Property(property="type", type="string", enum={"terms", "privacy", "marketing", "push", "email", "sms"}, example="marketing"),
 *             @OA\Property(property="agreed", type="boolean", example=true)
 *         )
 *     )
 * )
 */
class AccountApi
{
    /**
     * @OA\Post(
     *     path="/api/v1/account/withdraw",
     *     operationId="withdrawAccount",
     *     tags={"Account"},
     *     summary="회원 탈퇴",
     *     description="SAM 회원 탈퇴 (모든 테넌트에서 탈퇴, 계정 삭제)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/WithdrawRequest")
     *     ),
     *
     *     @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/WithdrawResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="비밀번호 불일치"),
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=404, description="사용자를 찾을 수 없음")
     * )
     */
    public function withdraw() {}

    /**
     * @OA\Post(
     *     path="/api/v1/account/suspend",
     *     operationId="suspendAccount",
     *     tags={"Account"},
     *     summary="사용 중지",
     *     description="현재 테넌트에서만 탈퇴 (다른 테넌트 멤버십 유지)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/SuspendResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=404, description="테넌트 멤버십을 찾을 수 없음")
     * )
     */
    public function suspend() {}

    /**
     * @OA\Get(
     *     path="/api/v1/account/agreements",
     *     operationId="getAgreements",
     *     tags={"Account"},
     *     summary="약관 동의 정보 조회",
     *     description="현재 사용자의 약관 동의 정보를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/AgreementsResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=404, description="사용자를 찾을 수 없음")
     * )
     */
    public function getAgreements() {}

    /**
     * @OA\Put(
     *     path="/api/v1/account/agreements",
     *     operationId="updateAgreements",
     *     tags={"Account"},
     *     summary="약관 동의 정보 수정",
     *     description="약관 동의 정보를 수정합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/UpdateAgreementsRequest")
     *     ),
     *
     *     @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="agreements",
     *                     type="object",
     *                     additionalProperties={"$ref": "#/components/schemas/AgreementItem"}
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=404, description="사용자를 찾을 수 없음"),
     *     @OA\Response(response=422, description="유효성 검증 실패")
     * )
     */
    public function updateAgreements() {}
}