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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Settings - Fields",
 *     description="테넌트 필드 설정 관리 API"
 * )
 *
 * @OA\Schema(
 *     schema="TenantFieldSetting",
 *
 *     @OA\Property(property="field_key", type="string", example="product_name_required"),
 *     @OA\Property(property="field_value", type="string", example="true"),
 *     @OA\Property(property="source", type="string", example="tenant", description="global 또는 tenant")
 * )
 *
 * @OA\Schema(
 *     schema="TenantFieldSettingBulkRequest",
 *
 *     @OA\Property(
 *         property="fields",
 *         type="array",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="field_key", type="string", example="product_name_required"),
 *             @OA\Property(property="field_value", type="string", example="true")
 *         )
 *     )
 * )
 */
class TenantFieldSettingApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/settings/fields",
     *     summary="테넌트 필드 설정 목록 조회",
     *     description="전역 + 테넌트별 병합된 필드 설정 효과값을 조회합니다.",
     *     tags={"Settings - Fields"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="필드 설정 목록 조회 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="조회 성공"),
     *             @OA\Property(
     *                 property="data",
     *                 type="array",
     *
     *                 @OA\Items(ref="#/components/schemas/TenantFieldSetting")
     *             )
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Put(
     *     path="/api/v1/settings/fields/bulk",
     *     summary="테넌트 필드 설정 대량 저장",
     *     description="여러 필드 설정을 트랜잭션으로 일괄 저장합니다.",
     *     tags={"Settings - Fields"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TenantFieldSettingBulkRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="대량 저장 성공",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
     *     ),
     *
     *     @OA\Response(
     *         response=400,
     *         description="유효하지 않은 필드 타입",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="유효하지 않은 필드 타입입니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=422,
     *         description="유효성 검사 실패",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
     *     )
     * )
     */
    public function bulkUpsert() {}

    /**
     * @OA\Patch(
     *     path="/api/v1/settings/fields/{key}",
     *     summary="테넌트 필드 설정 단건 수정",
     *     description="특정 필드 설정을 개별적으로 수정합니다.",
     *     tags={"Settings - Fields"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="key",
     *         in="path",
     *         required=true,
     *         description="필드 키",
     *
     *         @OA\Schema(type="string", example="product_name_required")
     *     ),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="field_value", type="string", example="false")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="필드 설정 수정 성공",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
     *     ),
     *
     *     @OA\Response(
     *         response=404,
     *         description="필드 설정을 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="해당 필드 설정을 찾을 수 없습니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=400,
     *         description="유효하지 않은 필드 타입",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="유효하지 않은 필드 타입입니다.")
     *         )
     *     )
     * )
     */
    public function updateOne() {}
}