sam-api/app/Http/Controllers/Api/V1/TenantFieldSettingController.php

<?php

namespace App\Http\Controllers\Api\V1;

use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Services\TenantFieldSettingService;
use Illuminate\Http\Request;

/**
 * @OA\Tag(
 *     name="Settings - Fields",
 *     description="테넌트 필드 설정 관리 API"
 * )
 */
class TenantFieldSettingController extends Controller
{
    /**
     * @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(
     *                     type="object",
     *
     *                     @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")
     *                 )
     *             )
     *         )
     *     )
     * )
     */
    public function index(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return TenantFieldSettingService::index($request->all());
        }, '테넌트 필드 효과값 목록 조회');
    }

    /**
     * @OA\Put(
     *     path="/api/v1/settings/fields/bulk",
     *     summary="테넌트 필드 설정 대량 저장",
     *     description="여러 필드 설정을 트랜잭션으로 일괄 저장합니다.",
     *     tags={"Settings - Fields"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @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")
     *                 )
     *             )
     *         )
     *     ),
     *
     *     @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(Request $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return TenantFieldSettingService::bulkUpsert($request->all());
        }, '테넌트 필드 설정 대량 저장');
    }

    /**
     * @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(Request $request, string $key)
    {
        return ApiResponse::handle(function () use ($request, $key) {
            return TenantFieldSettingService::updateOne($key, $request->all());
        }, '테넌트 필드 설정 단건 수정');
    }
}