feat: TenantStatField API 구현

- TenantStatFieldService: CRUD + reorder + bulkUpsert 로직 구현 - TenantStatFieldController: 7개 엔드포인트 (SAM API Rules 준수) - FormRequest: Store/Update 검증 클래스 생성 - Swagger: 완전한 API 문서화 (6개 스키마, 7개 엔드포인트) - i18n: message.tenant_stat_field 키 추가 - Route: /tenant-stat-fields 7개 라우트 등록 유니크 제약 검증: tenant_id + target_table + field_key 집계 함수 필터링: avg, sum, min, max, count
2025-11-14 14:09:53 +09:00
parent d4e9f2a6e4
commit ffcc6c3742
7 changed files with 756 additions and 0 deletions
--- a/app/Http/Controllers/Api/V1/TenantStatFieldController.php
+++ b/app/Http/Controllers/Api/V1/TenantStatFieldController.php
@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\TenantStatField\TenantStatFieldStoreRequest;
+use App\Http\Requests\TenantStatField\TenantStatFieldUpdateRequest;
+use App\Services\TenantStatFieldService;
+use Illuminate\Http\Request;
+
+class TenantStatFieldController extends Controller
+{
+    public function __construct(private TenantStatFieldService $service) {}
+
+    // GET /tenant-stat-fields
+    public function index(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->index($request->all());
+        }, __('message.tenant_stat_field.fetched'));
+    }
+
+    // POST /tenant-stat-fields
+    public function store(TenantStatFieldStoreRequest $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->store($request->validated());
+        }, __('message.tenant_stat_field.created'));
+    }
+
+    // GET /tenant-stat-fields/{id}
+    public function show(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.tenant_stat_field.fetched'));
+    }
+
+    // PATCH /tenant-stat-fields/{id}
+    public function update(int $id, TenantStatFieldUpdateRequest $request)
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->update($id, $request->validated());
+        }, __('message.tenant_stat_field.updated'));
+    }
+
+    // DELETE /tenant-stat-fields/{id}
+    public function destroy(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $this->service->destroy($id);
+
+            return 'success';
+        }, __('message.tenant_stat_field.deleted'));
+    }
+
+    // POST /tenant-stat-fields/reorder
+    public function reorder(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $this->service->reorder($request->input());
+
+            return 'success';
+        }, __('message.tenant_stat_field.reordered'));
+    }
+
+    // PUT /tenant-stat-fields/bulk-upsert
+    public function bulkUpsert(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->bulkUpsert($request->input('items', []));
+        }, __('message.tenant_stat_field.bulk_upsert'));
+    }
+}
--- a/app/Http/Requests/TenantStatField/TenantStatFieldStoreRequest.php
+++ b/app/Http/Requests/TenantStatField/TenantStatFieldStoreRequest.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Http\Requests\TenantStatField;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class TenantStatFieldStoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'target_table' => 'required|string|max:50',
+            'field_key' => 'required|string|max:100',
+            'field_name' => 'required|string|max:100',
+            'field_type' => 'required|string|max:20',
+            'aggregation_types' => 'nullable|array',
+            'aggregation_types.*' => 'string|in:avg,sum,min,max,count',
+            'is_critical' => 'nullable|boolean',
+            'display_order' => 'nullable|integer|min:0',
+            'description' => 'nullable|string',
+        ];
+    }
+}
--- a/app/Http/Requests/TenantStatField/TenantStatFieldUpdateRequest.php
+++ b/app/Http/Requests/TenantStatField/TenantStatFieldUpdateRequest.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Http\Requests\TenantStatField;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class TenantStatFieldUpdateRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'target_table' => 'sometimes|string|max:50',
+            'field_key' => 'sometimes|string|max:100',
+            'field_name' => 'sometimes|string|max:100',
+            'field_type' => 'sometimes|string|max:20',
+            'aggregation_types' => 'nullable|array',
+            'aggregation_types.*' => 'string|in:avg,sum,min,max,count',
+            'is_critical' => 'sometimes|boolean',
+            'display_order' => 'sometimes|integer|min:0',
+            'description' => 'nullable|string',
+        ];
+    }
+}
--- a/app/Services/TenantStatFieldService.php
+++ b/app/Services/TenantStatFieldService.php
@@ -0,0 +1,237 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Tenants\TenantStatField;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+class TenantStatFieldService extends Service
+{
+    public function index(array $params)
+    {
+        $tenantId = $this->tenantId();
+
+        $size = (int) ($params['size'] ?? 20);
+        $targetTable = $params['target_table'] ?? null;
+        $isCritical = $params['is_critical'] ?? null;
+        $aggregationType = $params['aggregation_type'] ?? null;
+
+        $query = TenantStatField::query()
+            ->where('tenant_id', $tenantId);
+
+        // 필터: 대상 테이블
+        if ($targetTable) {
+            $query->forTable($targetTable);
+        }
+
+        // 필터: 중요 필드만
+        if ($isCritical !== null && $isCritical !== '') {
+            $query->critical();
+        }
+
+        // 필터: 특정 집계 함수 포함
+        if ($aggregationType) {
+            $query->withAggregation($aggregationType);
+        }
+
+        // 정렬: display_order, field_name
+        $query->ordered();
+
+        return $query->paginate($size);
+    }
+
+    public function store(array $data)
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        // FormRequest에서 이미 검증됨
+        $payload = $data;
+
+        // tenant_id + target_table + field_key 유니크 검증
+        $exists = TenantStatField::query()
+            ->where('tenant_id', $tenantId)
+            ->where('target_table', $payload['target_table'])
+            ->where('field_key', $payload['field_key'])
+            ->exists();
+        if ($exists) {
+            throw new BadRequestHttpException(__('error.duplicate_key'));
+        }
+
+        $payload['tenant_id'] = $tenantId;
+        $payload['is_critical'] = $payload['is_critical'] ?? false;
+        $payload['display_order'] = $payload['display_order'] ?? 0;
+        $payload['created_by'] = $userId;
+
+        return TenantStatField::create($payload);
+    }
+
+    public function show(int $id)
+    {
+        $tenantId = $this->tenantId();
+
+        $field = TenantStatField::query()
+            ->where('tenant_id', $tenantId)
+            ->find($id);
+
+        if (! $field) {
+            throw new BadRequestHttpException(__('error.not_found'));
+        }
+
+        return $field;
+    }
+
+    public function update(int $id, array $data)
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        $field = TenantStatField::query()
+            ->where('tenant_id', $tenantId)
+            ->find($id);
+
+        if (! $field) {
+            throw new BadRequestHttpException(__('error.not_found'));
+        }
+
+        // FormRequest에서 이미 검증됨
+        $payload = $data;
+
+        // target_table 또는 field_key 변경 시 유니크 검증
+        $targetTableChanged = isset($payload['target_table']) && $payload['target_table'] !== $field->target_table;
+        $fieldKeyChanged = isset($payload['field_key']) && $payload['field_key'] !== $field->field_key;
+
+        if ($targetTableChanged || $fieldKeyChanged) {
+            $newTargetTable = $payload['target_table'] ?? $field->target_table;
+            $newFieldKey = $payload['field_key'] ?? $field->field_key;
+
+            $dup = TenantStatField::query()
+                ->where('tenant_id', $tenantId)
+                ->where('target_table', $newTargetTable)
+                ->where('field_key', $newFieldKey)
+                ->where('id', '!=', $id)
+                ->exists();
+            if ($dup) {
+                throw new BadRequestHttpException(__('error.duplicate_key'));
+            }
+        }
+
+        $payload['updated_by'] = $userId;
+        $field->update($payload);
+
+        return $field->refresh();
+    }
+
+    public function destroy(int $id): void
+    {
+        $tenantId = $this->tenantId();
+
+        $field = TenantStatField::query()
+            ->where('tenant_id', $tenantId)
+            ->find($id);
+
+        if (! $field) {
+            throw new BadRequestHttpException(__('error.not_found'));
+        }
+
+        $field->delete();
+    }
+
+    public function reorder(array $items): void
+    {
+        $tenantId = $this->tenantId();
+
+        $rows = $items['items'] ?? $items;
+        if (! is_array($rows)) {
+            throw new BadRequestHttpException(__('error.invalid_payload'));
+        }
+
+        DB::transaction(function () use ($tenantId, $rows) {
+            foreach ($rows as $row) {
+                if (! isset($row['id'], $row['display_order'])) {
+                    continue;
+                }
+
+                TenantStatField::query()
+                    ->where('tenant_id', $tenantId)
+                    ->where('id', $row['id'])
+                    ->update(['display_order' => (int) $row['display_order']]);
+            }
+        });
+    }
+
+    public function bulkUpsert(array $items): array
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        if (! is_array($items) || empty($items)) {
+            throw new BadRequestHttpException(__('error.empty_items'));
+        }
+
+        $result = ['created' => 0, 'updated' => 0];
+
+        DB::transaction(function () use ($tenantId, $userId, $items, &$result) {
+            foreach ($items as $payload) {
+                // 기본 검증
+                if (! isset($payload['target_table'], $payload['field_key'], $payload['field_name'], $payload['field_type'])) {
+                    throw new BadRequestHttpException(__('error.invalid_payload'));
+                }
+
+                if (! empty($payload['id'])) {
+                    // 수정
+                    $model = TenantStatField::query()
+                        ->where('tenant_id', $tenantId)
+                        ->find($payload['id']);
+                    if (! $model) {
+                        throw new BadRequestHttpException(__('error.not_found'));
+                    }
+
+                    // target_table 또는 field_key 변경 시 유니크 검증
+                    $targetTableChanged = isset($payload['target_table']) && $payload['target_table'] !== $model->target_table;
+                    $fieldKeyChanged = isset($payload['field_key']) && $payload['field_key'] !== $model->field_key;
+
+                    if ($targetTableChanged || $fieldKeyChanged) {
+                        $newTargetTable = $payload['target_table'] ?? $model->target_table;
+                        $newFieldKey = $payload['field_key'] ?? $model->field_key;
+
+                        $dup = TenantStatField::query()
+                            ->where('tenant_id', $tenantId)
+                            ->where('target_table', $newTargetTable)
+                            ->where('field_key', $newFieldKey)
+                            ->where('id', '!=', $payload['id'])
+                            ->exists();
+                        if ($dup) {
+                            throw new BadRequestHttpException(__('error.duplicate_key'));
+                        }
+                    }
+
+                    $payload['updated_by'] = $userId;
+                    $model->update($payload);
+                    $result['updated']++;
+                } else {
+                    // 신규 생성
+                    $dup = TenantStatField::query()
+                        ->where('tenant_id', $tenantId)
+                        ->where('target_table', $payload['target_table'])
+                        ->where('field_key', $payload['field_key'])
+                        ->exists();
+                    if ($dup) {
+                        throw new BadRequestHttpException(__('error.duplicate_key'));
+                    }
+
+                    $payload['tenant_id'] = $tenantId;
+                    $payload['is_critical'] = $payload['is_critical'] ?? false;
+                    $payload['display_order'] = $payload['display_order'] ?? 0;
+                    $payload['created_by'] = $userId;
+
+                    TenantStatField::create($payload);
+                    $result['created']++;
+                }
+            }
+        });
+
+        return $result;
+    }
+}
--- a/app/Swagger/v1/TenantStatFieldApi.php
+++ b/app/Swagger/v1/TenantStatFieldApi.php
@@ -0,0 +1,368 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="TenantStatField", description="통계 필드 메타데이터 관리")
+ *
+ * @OA\Schema(
+ *   schema="TenantStatField",
+ *   type="object",
+ *   required={"id","tenant_id","target_table","field_key","field_name","field_type"},
+ *
+ *   @OA\Property(property="id", type="integer", example=1),
+ *   @OA\Property(property="tenant_id", type="integer", example=1),
+ *   @OA\Property(property="target_table", type="string", example="products"),
+ *   @OA\Property(property="field_key", type="string", example="margin_rate"),
+ *   @OA\Property(property="field_name", type="string", example="마진율(%)"),
+ *   @OA\Property(property="field_type", type="string", example="decimal"),
+ *   @OA\Property(
+ *     property="aggregation_types",
+ *     type="array",
+ *     nullable=true,
+ *     example={"avg","min","max"},
+ *
+ *     @OA\Items(type="string")
+ *   ),
+ *
+ *   @OA\Property(property="is_critical", type="boolean", example=true),
+ *   @OA\Property(property="display_order", type="integer", example=0),
+ *   @OA\Property(property="description", type="string", nullable=true, example="제품 마진율 통계"),
+ *   @OA\Property(property="created_by", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="created_at", type="string", example="2025-11-14 10:00:00"),
+ *   @OA\Property(property="updated_at", type="string", example="2025-11-14 10:10:00")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="TenantStatFieldPagination",
+ *   type="object",
+ *
+ *   @OA\Property(property="current_page", type="integer", example=1),
+ *   @OA\Property(
+ *     property="data",
+ *     type="array",
+ *
+ *     @OA\Items(ref="#/components/schemas/TenantStatField")
+ *   ),
+ *
+ *   @OA\Property(property="first_page_url", type="string", example="/api/v1/tenant-stat-fields?page=1"),
+ *   @OA\Property(property="from", type="integer", example=1),
+ *   @OA\Property(property="last_page", type="integer", example=2),
+ *   @OA\Property(property="last_page_url", type="string", example="/api/v1/tenant-stat-fields?page=2"),
+ *   @OA\Property(
+ *     property="links",
+ *     type="array",
+ *
+ *     @OA\Items(type="object",
+ *
+ *       @OA\Property(property="url", type="string", nullable=true, example=null),
+ *       @OA\Property(property="label", type="string", example="&laquo; Previous"),
+ *       @OA\Property(property="active", type="boolean", example=false)
+ *     )
+ *   ),
+ *   @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/tenant-stat-fields?page=2"),
+ *   @OA\Property(property="path", type="string", example="/api/v1/tenant-stat-fields"),
+ *   @OA\Property(property="per_page", type="integer", example=20),
+ *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
+ *   @OA\Property(property="to", type="integer", example=20),
+ *   @OA\Property(property="total", type="integer", example=9)
+ * )
+ *
+ * @OA\Schema(
+ *   schema="TenantStatFieldCreateRequest",
+ *   type="object",
+ *   required={"target_table","field_key","field_name","field_type"},
+ *
+ *   @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
+ *   @OA\Property(property="field_key", type="string", maxLength=100, example="processing_cost"),
+ *   @OA\Property(property="field_name", type="string", maxLength=100, example="가공비(원)"),
+ *   @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
+ *   @OA\Property(
+ *     property="aggregation_types",
+ *     type="array",
+ *     nullable=true,
+ *     example={"avg","sum"},
+ *
+ *     @OA\Items(type="string", enum={"avg","sum","min","max","count"})
+ *   ),
+ *
+ *   @OA\Property(property="is_critical", type="boolean", nullable=true, example=false),
+ *   @OA\Property(property="display_order", type="integer", nullable=true, example=0),
+ *   @OA\Property(property="description", type="string", nullable=true, example="제품별 가공비 통계")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="TenantStatFieldUpdateRequest",
+ *   type="object",
+ *
+ *   @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
+ *   @OA\Property(property="field_key", type="string", maxLength=100, example="processing_cost"),
+ *   @OA\Property(property="field_name", type="string", maxLength=100, example="가공비(원)"),
+ *   @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
+ *   @OA\Property(
+ *     property="aggregation_types",
+ *     type="array",
+ *     nullable=true,
+ *
+ *     @OA\Items(type="string", enum={"avg","sum","min","max","count"})
+ *   ),
+ *
+ *   @OA\Property(property="is_critical", type="boolean", nullable=true, example=true),
+ *   @OA\Property(property="display_order", type="integer", nullable=true, example=5),
+ *   @OA\Property(property="description", type="string", nullable=true, example="제품별 가공비 통계 (일일 집계)")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="TenantStatFieldReorderRequest",
+ *   type="object",
+ *   required={"items"},
+ *
+ *   @OA\Property(
+ *     property="items",
+ *     type="array",
+ *
+ *     @OA\Items(
+ *       type="object",
+ *
+ *       @OA\Property(property="id", type="integer", example=1),
+ *       @OA\Property(property="display_order", type="integer", example=10)
+ *     )
+ *   )
+ * )
+ *
+ * @OA\Schema(
+ *   schema="TenantStatFieldBulkUpsertRequest",
+ *   type="object",
+ *   required={"items"},
+ *
+ *   @OA\Property(
+ *     property="items",
+ *     type="array",
+ *
+ *     @OA\Items(
+ *       type="object",
+ *
+ *       @OA\Property(property="id", type="integer", nullable=true, example=null, description="수정 시 ID 필수, 신규 시 null"),
+ *       @OA\Property(property="target_table", type="string", maxLength=50, example="products"),
+ *       @OA\Property(property="field_key", type="string", maxLength=100, example="margin_rate"),
+ *       @OA\Property(property="field_name", type="string", maxLength=100, example="마진율(%)"),
+ *       @OA\Property(property="field_type", type="string", maxLength=20, example="decimal"),
+ *       @OA\Property(
+ *         property="aggregation_types",
+ *         type="array",
+ *         nullable=true,
+ *
+ *         @OA\Items(type="string")
+ *       ),
+ *
+ *       @OA\Property(property="is_critical", type="boolean", nullable=true, example=true),
+ *       @OA\Property(property="display_order", type="integer", nullable=true, example=0),
+ *       @OA\Property(property="description", type="string", nullable=true, example=null)
+ *     )
+ *   )
+ * )
+ */
+class TenantStatFieldApi
+{
+    /**
+     * @OA\Get(
+     *   path="/api/v1/tenant-stat-fields",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 목록 조회",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", default=20), example=20),
+     *   @OA\Parameter(name="target_table", in="query", @OA\Schema(type="string"), example="products"),
+     *   @OA\Parameter(name="is_critical", in="query", @OA\Schema(type="boolean"), example=true),
+     *   @OA\Parameter(name="aggregation_type", in="query", @OA\Schema(type="string", enum={"avg","sum","min","max","count"}), example="avg"),
+     *
+     *   @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", ref="#/components/schemas/TenantStatFieldPagination")
+     *     )
+     *   )
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/tenant-stat-fields",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 생성",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\RequestBody(
+     *     required=true,
+     *
+     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldCreateRequest")
+     *   ),
+     *
+     *   @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", ref="#/components/schemas/TenantStatField")
+     *     )
+     *   )
+     * )
+     */
+    public function store() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/tenant-stat-fields/{id}",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 단건 조회",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
+     *
+     *   @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", ref="#/components/schemas/TenantStatField")
+     *     )
+     *   )
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Patch(
+     *   path="/api/v1/tenant-stat-fields/{id}",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 수정",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
+     *
+     *   @OA\RequestBody(
+     *     required=true,
+     *
+     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldUpdateRequest")
+     *   ),
+     *
+     *   @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", ref="#/components/schemas/TenantStatField")
+     *     )
+     *   )
+     * )
+     */
+    public function update() {}
+
+    /**
+     * @OA\Delete(
+     *   path="/api/v1/tenant-stat-fields/{id}",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 삭제",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
+     *
+     *   @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="string", example="success")
+     *     )
+     *   )
+     * )
+     */
+    public function destroy() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/tenant-stat-fields/reorder",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 정렬순서 변경",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\RequestBody(
+     *     required=true,
+     *
+     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldReorderRequest")
+     *   ),
+     *
+     *   @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="string", example="success")
+     *     )
+     *   )
+     * )
+     */
+    public function reorder() {}
+
+    /**
+     * @OA\Put(
+     *   path="/api/v1/tenant-stat-fields/bulk-upsert",
+     *   tags={"TenantStatField"},
+     *   summary="통계 필드 일괄 생성/수정",
+     *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
+     *
+     *   @OA\RequestBody(
+     *     required=true,
+     *
+     *     @OA\JsonContent(ref="#/components/schemas/TenantStatFieldBulkUpsertRequest")
+     *   ),
+     *
+     *   @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="object",
+     *         @OA\Property(property="created", type="integer", example=3),
+     *         @OA\Property(property="updated", type="integer", example=2)
+     *       )
+     *     )
+     *   )
+     * )
+     */
+    public function bulkUpsert() {}
+}
--- a/lang/ko/message.php
+++ b/lang/ko/message.php
@@ -137,6 +137,15 @@
        'restored' => '테넌트가 복구되었습니다.',
    ],

+    'tenant_stat_field' => [
+        'fetched' => '통계 필드를 조회했습니다.',
+        'created' => '통계 필드가 생성되었습니다.',
+        'updated' => '통계 필드가 수정되었습니다.',
+        'deleted' => '통계 필드가 삭제되었습니다.',
+        'reordered' => '통계 필드 정렬이 변경되었습니다.',
+        'bulk_upsert' => '통계 필드가 일괄 저장되었습니다.',
+    ],
+
    // 파일 관리
    'file' => [
        'uploaded' => '파일이 업로드되었습니다.',
--- a/routes/api.php
+++ b/routes/api.php
@@ -105,6 +105,17 @@
            Route::put('/restore/{tenant_id}', [TenantController::class, 'restore'])->name('v1.tenant.restore');     // 테넌트 복구
        });

+        // Tenant Statistics Field API
+        Route::prefix('tenant-stat-fields')->group(function () {
+            Route::get('/', [TenantStatFieldController::class, 'index'])->name('v1.tenant-stat-fields.index');   // 목록 조회
+            Route::post('/', [TenantStatFieldController::class, 'store'])->name('v1.tenant-stat-fields.store');   // 생성
+            Route::get('/{id}', [TenantStatFieldController::class, 'show'])->name('v1.tenant-stat-fields.show');     // 단건 조회
+            Route::patch('/{id}', [TenantStatFieldController::class, 'update'])->name('v1.tenant-stat-fields.update'); // 수정
+            Route::delete('/{id}', [TenantStatFieldController::class, 'destroy'])->name('v1.tenant-stat-fields.destroy'); // 삭제
+            Route::post('/reorder', [TenantStatFieldController::class, 'reorder'])->name('v1.tenant-stat-fields.reorder'); // 정렬 변경
+            Route::put('/bulk-upsert', [TenantStatFieldController::class, 'bulkUpsert'])->name('v1.tenant-stat-fields.bulk-upsert'); // 일괄 저장
+        });
+
        // Menu API
        Route::middleware(['perm.map', 'permission'])->prefix('menus')->group(function () {
            Route::get('/', [MenuController::class, 'index'])->name('v1.menus.index');