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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Auth", description="로그인/로그아웃/회원가입")
 */

/**
 * 회원가입 요청/응답 스키마
 * -----------------------------------------------------------------------------
 * 필요 시 공용 components 영역으로 이동해도 됩니다.
 */

/**
 * @OA\Schema(
 *     schema="SignupRequest",
 *     type="object",
 *     required={"user_id","name","email","password"},
 *
 *     @OA\Property(property="user_id", type="string", maxLength=255, example="userId", description="로그인 ID (고유)"),
 *     @OA\Property(property="name", type="string", maxLength=255, example="Kent"),
 *     @OA\Property(property="email", type="string", maxLength=100, example="codebridge@gmail.com"),
 *     @OA\Property(property="phone", type="string", maxLength=30, nullable=true, example="010-4820-9104"),
 *     @OA\Property(property="password", type="string", minLength=8, maxLength=64, example="StrongPass!1234")
 * )
 *
 * @OA\Schema(
 *     schema="SignupResponseData",
 *     type="object",
 *
 *     @OA\Property(
 *         property="user",
 *         ref="#/components/schemas/Member"
 *     )
 * )
 *
 * @OA\Schema(
 *    schema="MemberBrief",
 *    type="object",
 *    description="회원 요약 정보(회원가입 응답용)",
 *    required={"id","user_id","name","email","phone"},
 *
 *    @OA\Property(property="id", type="integer", example=6),
 *    @OA\Property(property="user_id", type="string", example="userId"),
 *    @OA\Property(property="name", type="string", example="Kent"),
 *    @OA\Property(property="email", type="string", example="codebridge1@gmail.com"),
 *    @OA\Property(property="phone", type="string", example="010-4820-9104")
 *  )
 */
class AuthApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/debug-apikey",
     *     tags={"Auth"},
     *     summary="API Key 인증 확인",
     *     description="API Key가 유효한지 확인합니다. Bearer 토큰은 선택사항입니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="API Key 인증 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="message", type="string", example="API Key 인증 성공")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function debugApiKey() {}

    /**
     * @OA\Post(
     *     path="/api/v1/login",
     *     tags={"Auth"},
     *     summary="로그인 (토큰 + 사용자 정보 + 테넌트 + 메뉴 + 역할)",
     *     description="로그인 성공 시 인증 토큰과 함께 사용자 정보, 활성 테넌트 정보, 접근 가능한 메뉴 목록, 역할 목록을 반환합니다.",
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"user_id","user_pwd"},
     *
     *             @OA\Property(property="user_id", type="string", example="hamss"),
     *             @OA\Property(property="user_pwd", type="string", example="StrongPass!1234")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="로그인 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="message", type="string", example="로그인 성공"),
     *             @OA\Property(property="access_token", type="string", example="1|abc123xyz456", description="액세스 토큰 (API 호출에 사용)"),
     *             @OA\Property(property="refresh_token", type="string", example="2|def456uvw789", description="리프레시 토큰 (액세스 토큰 갱신에 사용)"),
     *             @OA\Property(property="token_type", type="string", example="Bearer", description="토큰 타입"),
     *             @OA\Property(property="expires_in", type="integer", nullable=true, example=7200, description="액세스 토큰 만료 시간 (초 단위, null이면 무제한)"),
     *             @OA\Property(property="expires_at", type="string", nullable=true, example="2025-11-10 16:00:00", description="액세스 토큰 만료 시각 (null이면 무제한)"),
     *             @OA\Property(
     *                 property="user",
     *                 type="object",
     *                 description="사용자 기본 정보",
     *                 @OA\Property(property="id", type="integer", example=1),
     *                 @OA\Property(property="user_id", type="string", example="hamss"),
     *                 @OA\Property(property="name", type="string", example="홍길동"),
     *                 @OA\Property(property="email", type="string", example="hamss@example.com"),
     *                 @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678")
     *             ),
     *             @OA\Property(
     *                 property="tenant",
     *                 type="object",
     *                 nullable=true,
     *                 description="활성 테넌트 정보 (is_default=1 우선, 없으면 is_active=1 중 첫 번째, 없으면 null)",
     *                 @OA\Property(property="id", type="integer", example=1),
     *                 @OA\Property(property="company_name", type="string", example="주식회사 코드브리지"),
     *                 @OA\Property(property="business_num", type="string", nullable=true, example="123-45-67890"),
     *                 @OA\Property(property="tenant_st_code", type="string", nullable=true, example="ACTIVE"),
     *                 @OA\Property(
     *                     property="other_tenants",
     *                     type="array",
     *                     description="사용자가 소속된 다른 활성 테넌트 목록",
     *
     *                     @OA\Items(
     *                         type="object",
     *
     *                         @OA\Property(property="tenant_id", type="integer", example=2),
     *                         @OA\Property(property="company_name", type="string", example="주식회사 샘플"),
     *                         @OA\Property(property="business_num", type="string", nullable=true, example="987-65-43210"),
     *                         @OA\Property(property="tenant_st_code", type="string", nullable=true, example="ACTIVE")
     *                     )
     *                 )
     *             ),
     *             @OA\Property(
     *                 property="menus",
     *                 type="array",
     *                 description="사용자가 접근 가능한 메뉴 목록 (menu:{menu_id}.view 권한 체크, override deny/allow 적용)",
     *
     *                 @OA\Items(
     *                     type="object",
     *
     *                     @OA\Property(property="id", type="integer", example=1),
     *                     @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
     *                     @OA\Property(property="name", type="string", example="대시보드"),
     *                     @OA\Property(property="url", type="string", nullable=true, example="/dashboard"),
     *                     @OA\Property(property="icon", type="string", nullable=true, example="dashboard"),
     *                     @OA\Property(property="sort_order", type="integer", example=1),
     *                     @OA\Property(property="is_external", type="boolean", example=false, description="외부 링크 여부"),
     *                     @OA\Property(property="external_url", type="string", nullable=true, example="https://example.com", description="외부 링크 URL")
     *                 )
     *             ),
     *             @OA\Property(
     *                 property="roles",
     *                 type="array",
     *                 description="사용자가 가진 역할 목록",
     *
     *                 @OA\Items(
     *                     type="object",
     *
     *                     @OA\Property(property="id", type="integer", example=1, description="역할 ID"),
     *                     @OA\Property(property="name", type="string", example="system_manager", description="역할명"),
     *                     @OA\Property(property="description", type="string", example="시스템 관리자", description="역할 설명")
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response="200 (테넌트 없음)",
     *         description="로그인 성공 - 활성 테넌트 없는 경우",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="message", type="string", example="로그인 성공"),
     *             @OA\Property(property="access_token", type="string", example="1|abc123xyz456", description="액세스 토큰 (API 호출에 사용)"),
     *             @OA\Property(property="refresh_token", type="string", example="2|def456uvw789", description="리프레시 토큰 (액세스 토큰 갱신에 사용)"),
     *             @OA\Property(property="token_type", type="string", example="Bearer", description="토큰 타입"),
     *             @OA\Property(property="expires_in", type="integer", nullable=true, example=7200, description="액세스 토큰 만료 시간 (초 단위, null이면 무제한)"),
     *             @OA\Property(property="expires_at", type="string", nullable=true, example="2025-11-10 16:00:00", description="액세스 토큰 만료 시각 (null이면 무제한)"),
     *             @OA\Property(
     *                 property="user",
     *                 type="object",
     *                 @OA\Property(property="id", type="integer", example=1),
     *                 @OA\Property(property="user_id", type="string", example="hamss"),
     *                 @OA\Property(property="name", type="string", example="홍길동"),
     *                 @OA\Property(property="email", type="string", example="hamss@example.com"),
     *                 @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678")
     *             ),
     *             @OA\Property(property="tenant", type="null", example=null),
     *             @OA\Property(property="menus", type="array", @OA\Items())
     *         )
     *     ),
     *
     *     @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"))
     * )
     */
    public function login() {}

    /**
     * @OA\Post(
     *     path="/api/v1/logout",
     *     tags={"Auth"},
     *     summary="로그아웃 (Access 및 Token 무효화)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="로그아웃 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="message", type="string", example="로그아웃 완료")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function logout() {}

    /**
     * @OA\Post(
     *     path="/api/v1/signup",
     *     tags={"Auth"},
     *     summary="회원가입",
     *     description="신규 회원을 생성합니다. (API Key 필요)",
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/SignupRequest")),
     *
     *     @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="user", ref="#/components/schemas/MemberBrief")
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패(API Key 누락/오류)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function signup() {}
}