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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="BarobillSettings", description="바로빌 설정 관리")
 *
 * @OA\Schema(
 *     schema="BarobillSetting",
 *     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="corp_num", type="string", example="1234567890", description="사업자번호 (10자리)"),
 *     @OA\Property(property="barobill_id", type="string", example="testuser", description="바로빌 아이디"),
 *     @OA\Property(property="corp_name", type="string", example="(주)테스트회사", description="회사명"),
 *     @OA\Property(property="ceo_name", type="string", example="홍길동", description="대표자명"),
 *     @OA\Property(property="addr", type="string", example="서울시 강남구 테헤란로 123", nullable=true, description="주소"),
 *     @OA\Property(property="biz_type", type="string", example="서비스", nullable=true, description="업태"),
 *     @OA\Property(property="biz_class", type="string", example="소프트웨어개발", nullable=true, description="종목"),
 *     @OA\Property(property="contact_id", type="string", example="manager@test.com", nullable=true, description="담당자 이메일"),
 *     @OA\Property(property="contact_name", type="string", example="김담당", nullable=true, description="담당자명"),
 *     @OA\Property(property="contact_tel", type="string", example="02-1234-5678", nullable=true, description="담당자 연락처"),
 *     @OA\Property(property="is_active", type="boolean", example=true, description="활성화 여부"),
 *     @OA\Property(property="auto_issue", type="boolean", example=false, description="자동발행 여부"),
 *     @OA\Property(property="verified_at", type="string", format="date-time", nullable=true, description="검증 완료 일시"),
 *     @OA\Property(property="formatted_corp_num", type="string", example="123-45-67890", description="포맷팅된 사업자번호"),
 *     @OA\Property(property="created_by", type="integer", example=1, nullable=true, description="생성자 ID"),
 *     @OA\Property(property="updated_by", type="integer", example=1, nullable=true, description="수정자 ID"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="BarobillSettingSaveRequest",
 *     type="object",
 *     required={"corp_num","cert_key","barobill_id","corp_name","ceo_name"},
 *     description="바로빌 설정 저장 요청",
 *
 *     @OA\Property(property="corp_num", type="string", example="1234567890", minLength=10, maxLength=10, description="사업자번호 (10자리, 하이픈 제외)"),
 *     @OA\Property(property="cert_key", type="string", example="xxxxxx", description="공인인증서 키 (암호화되어 저장)"),
 *     @OA\Property(property="barobill_id", type="string", example="testuser", maxLength=50, description="바로빌 아이디"),
 *     @OA\Property(property="corp_name", type="string", example="(주)테스트회사", maxLength=200, description="회사명"),
 *     @OA\Property(property="ceo_name", type="string", example="홍길동", maxLength=100, description="대표자명"),
 *     @OA\Property(property="addr", type="string", example="서울시 강남구 테헤란로 123", maxLength=500, nullable=true, description="주소"),
 *     @OA\Property(property="biz_type", type="string", example="서비스", maxLength=100, nullable=true, description="업태"),
 *     @OA\Property(property="biz_class", type="string", example="소프트웨어개발", maxLength=100, nullable=true, description="종목"),
 *     @OA\Property(property="contact_id", type="string", example="manager@test.com", maxLength=100, nullable=true, description="담당자 이메일"),
 *     @OA\Property(property="contact_name", type="string", example="김담당", maxLength=100, nullable=true, description="담당자명"),
 *     @OA\Property(property="contact_tel", type="string", example="02-1234-5678", maxLength=50, nullable=true, description="담당자 연락처"),
 *     @OA\Property(property="is_active", type="boolean", example=true, description="활성화 여부 (기본값: true)"),
 *     @OA\Property(property="auto_issue", type="boolean", example=false, description="자동발행 여부 (기본값: false)")
 * )
 *
 * @OA\Schema(
 *     schema="BarobillConnectionTestResult",
 *     type="object",
 *     description="바로빌 연동 테스트 결과",
 *
 *     @OA\Property(property="success", type="boolean", example=true, description="연동 성공 여부"),
 *     @OA\Property(property="remaining_point", type="integer", example=10000, description="잔여 포인트"),
 *     @OA\Property(property="tested_at", type="string", format="date-time", description="테스트 일시")
 * )
 */
class BarobillSettingApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/barobill-settings",
     *     tags={"BarobillSettings"},
     *     summary="바로빌 설정 조회",
     *     description="현재 테넌트의 바로빌 설정을 조회합니다. 설정이 없는 경우 null을 반환합니다.",
     *     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/BarobillSetting", nullable=true)
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/barobill-settings",
     *     tags={"BarobillSettings"},
     *     summary="바로빌 설정 저장",
     *     description="바로빌 설정을 저장합니다. 기존 설정이 있으면 수정하고, 없으면 새로 생성합니다. cert_key는 암호화되어 저장됩니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/BarobillSettingSaveRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="저장 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/BarobillSetting")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function save() {}

    /**
     * @OA\Post(
     *     path="/api/v1/barobill-settings/test-connection",
     *     tags={"BarobillSettings"},
     *     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/BarobillConnectionTestResult")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function testConnection() {}
}