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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="TenantSettings",
 *     description="테넌트 설정 관리 API"
 * )
 *
 * @OA\Schema(
 *     schema="TenantSetting",
 *     type="object",
 *     required={"id", "tenant_id", "setting_group", "setting_key"},
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="tenant_id", type="integer", example=287),
 *     @OA\Property(property="setting_group", type="string", example="stock"),
 *     @OA\Property(property="setting_key", type="string", example="stock_item_types"),
 *     @OA\Property(property="setting_value", type="object", example={"RM", "SM", "CS", "PT", "SF"}),
 *     @OA\Property(property="description", type="string", nullable=true, example="재고관리 대상 품목유형"),
 *     @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="TenantSettingStoreRequest",
 *     type="object",
 *     required={"group", "key", "value"},
 *
 *     @OA\Property(property="group", type="string", maxLength=50, example="stock", description="설정 그룹"),
 *     @OA\Property(property="key", type="string", maxLength=100, example="stock_item_types", description="설정 키"),
 *     @OA\Property(property="value", type="object", example={"RM", "SM", "CS", "PT", "SF"}, description="설정 값 (JSON)"),
 *     @OA\Property(property="description", type="string", nullable=true, maxLength=255, example="재고관리 대상 품목유형", description="설정 설명")
 * )
 *
 * @OA\Schema(
 *     schema="TenantSettingBulkRequest",
 *     type="object",
 *     required={"group", "settings"},
 *
 *     @OA\Property(property="group", type="string", maxLength=50, example="stock", description="설정 그룹"),
 *     @OA\Property(
 *         property="settings",
 *         type="array",
 *
 *         @OA\Items(
 *             type="object",
 *             required={"key", "value"},
 *
 *             @OA\Property(property="key", type="string", example="stock_item_types"),
 *             @OA\Property(property="value", type="object", example={"RM", "SM", "CS"}),
 *             @OA\Property(property="description", type="string", nullable=true)
 *         )
 *     )
 * )
 */
class TenantSettingApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/tenant-settings",
     *     tags={"TenantSettings"},
     *     summary="테넌트 설정 목록 조회",
     *     description="현재 테넌트의 모든 설정을 그룹별로 조회합니다.",
     *     security={{"ApiKeyAuth":{}}, {"BearerAuth":{}}},
     *
     *     @OA\Parameter(
     *         name="group",
     *         in="query",
     *         required=false,
     *         description="특정 그룹만 조회",
     *
     *         @OA\Schema(type="string", example="stock")
     *     ),
     *
     *     @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="stock",
     *                     type="object",
     *                     @OA\Property(
     *                         property="stock_item_types",
     *                         type="object",
     *                         @OA\Property(property="value", type="array", @OA\Items(type="string")),
     *                         @OA\Property(property="description", type="string"),
     *                         @OA\Property(property="updated_at", type="string")
     *                     )
     *                 )
     *             )
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/tenant-settings/{group}/{key}",
     *     tags={"TenantSettings"},
     *     summary="단일 설정 조회",
     *     description="그룹과 키로 특정 설정값을 조회합니다.",
     *     security={{"ApiKeyAuth":{}}, {"BearerAuth":{}}},
     *
     *     @OA\Parameter(
     *         name="group",
     *         in="path",
     *         required=true,
     *         description="설정 그룹",
     *
     *         @OA\Schema(type="string", example="stock")
     *     ),
     *
     *     @OA\Parameter(
     *         name="key",
     *         in="path",
     *         required=true,
     *         description="설정 키",
     *
     *         @OA\Schema(type="string", example="stock_item_types")
     *     ),
     *
     *     @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="group", type="string", example="stock"),
     *                 @OA\Property(property="key", type="string", example="stock_item_types"),
     *                 @OA\Property(property="value", type="array", @OA\Items(type="string"), example={"RM", "SM", "CS", "PT", "SF"})
     *             )
     *         )
     *     )
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *     path="/api/v1/tenant-settings",
     *     tags={"TenantSettings"},
     *     summary="설정 저장/업데이트",
     *     description="설정을 저장하거나 업데이트합니다. 이미 존재하는 경우 업데이트됩니다.",
     *     security={{"ApiKeyAuth":{}}, {"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TenantSettingStoreRequest")
     *     ),
     *
     *     @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/TenantSetting")
     *         )
     *     )
     * )
     */
    public function store() {}

    /**
     * @OA\Put(
     *     path="/api/v1/tenant-settings/bulk",
     *     tags={"TenantSettings"},
     *     summary="설정 일괄 저장",
     *     description="같은 그룹의 여러 설정을 일괄 저장합니다.",
     *     security={{"ApiKeyAuth":{}}, {"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TenantSettingBulkRequest")
     *     ),
     *
     *     @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="updated", type="integer", example=3)
     *             )
     *         )
     *     )
     * )
     */
    public function bulkUpdate() {}

    /**
     * @OA\Post(
     *     path="/api/v1/tenant-settings/initialize",
     *     tags={"TenantSettings"},
     *     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",
     *                 type="object",
     *                 @OA\Property(property="initialized", type="integer", example=3)
     *             )
     *         )
     *     )
     * )
     */
    public function initialize() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/tenant-settings/{group}/{key}",
     *     tags={"TenantSettings"},
     *     summary="설정 삭제",
     *     description="특정 설정을 삭제합니다.",
     *     security={{"ApiKeyAuth":{}}, {"BearerAuth":{}}},
     *
     *     @OA\Parameter(
     *         name="group",
     *         in="path",
     *         required=true,
     *         description="설정 그룹",
     *
     *         @OA\Schema(type="string", example="stock")
     *     ),
     *
     *     @OA\Parameter(
     *         name="key",
     *         in="path",
     *         required=true,
     *         description="설정 키",
     *
     *         @OA\Schema(type="string", example="stock_item_types")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="삭제 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="삭제되었습니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=404,
     *         description="설정을 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="해당 데이터를 찾을 수 없습니다.")
     *         )
     *     )
     * )
     */
    public function destroy() {}
}