feat: ClientGroup 및 Pricing API 완성 및 Swagger 문서 작성

- ClientGroupService 구현: 고객 그룹 관리 비즈니스 로직 (CRUD + toggle) - ClientGroupController 구현: 6개 REST API 엔드포인트 - PricingController 구현: 5개 가격 관리 API 엔드포인트 - routes/api.php에 client-groups, pricing 라우트 등록 - ClientGroupApi.php Swagger 문서 작성 (OpenAPI 3.0) - PricingApi.php Swagger 문서 작성 (OpenAPI 3.0) - l5-swagger 재생성 완료 추가된 파일: - app/Services/ClientGroupService.php - app/Http/Controllers/Api/V1/ClientGroupController.php - app/Http/Controllers/Api/V1/PricingController.php - app/Swagger/v1/ClientGroupApi.php - app/Swagger/v1/PricingApi.php 수정된 파일: - routes/api.php (라우트 11개 추가) - CURRENT_WORKS.md (작업 내용 문서화) API 엔드포인트: - GET/POST/PUT/DELETE /api/v1/client-groups - GET/POST /api/v1/pricing (show, bulk, upsert 포함)
2025-10-13 22:06:42 +09:00
parent a6b06be61d
commit b6f36cc967
7 changed files with 966 additions and 1 deletions
--- a/CURRENT_WORKS.md
+++ b/CURRENT_WORKS.md
@@ -1,5 +1,235 @@
 # SAM API 저장소 작업 현황

+## 2025-10-13 (일) - ClientGroup 및 Pricing API 완성 (오후)
+
+### 주요 작업
+- **ClientGroup API 전체 구현**: 고객 그룹 관리를 위한 완전한 REST API 구축
+- **Pricing API 전체 구현**: 가격 이력 관리 및 가격 조회 API 구축
+- **Swagger 문서 작성**: ClientGroup, Pricing API의 완전한 OpenAPI 3.0 문서 생성
+- **l5-swagger 재생성**: 모든 API 문서를 Swagger UI에서 확인 가능하도록 재생성
+
+### 추가된 파일:
+- `app/Services/ClientGroupService.php` - 고객 그룹 관리 서비스 (CRUD + toggle)
+- `app/Http/Controllers/Api/V1/ClientGroupController.php` - 고객 그룹 컨트롤러
+- `app/Http/Controllers/Api/V1/PricingController.php` - 가격 이력 컨트롤러
+- `app/Swagger/v1/ClientGroupApi.php` - ClientGroup Swagger 문서
+- `app/Swagger/v1/PricingApi.php` - Pricing Swagger 문서
+
+### 수정된 파일:
+- `routes/api.php` - ClientGroup 및 Pricing 라우트 등록
+
+### 작업 내용:
+
+#### 1. ClientGroupService 구현
+**핵심 기능:**
+- `index()` - 페이지네이션 목록 조회 (검색, 활성 여부 필터링)
+- `show($id)` - 단건 조회
+- `store($params)` - 생성 (group_code 중복 검사)
+- `update($id, $params)` - 수정 (중복 검사)
+- `destroy($id)` - Soft Delete
+- `toggle($id)` - 활성/비활성 상태 토글
+
+**검증 규칙:**
+```php
+- group_code: required|string|max:30
+- group_name: required|string|max:100
+- price_rate: required|numeric|min:0|max:99.9999
+- is_active: nullable|boolean
+```
+
+**에러 처리:**
+- 중복 코드: `__('error.duplicate_code')`
+- 데이터 없음: `NotFoundHttpException`
+- 검증 실패: `BadRequestHttpException`
+
+#### 2. ClientGroupController 구현
+**표준 RESTful 패턴:**
+```php
+- GET /api/v1/client-groups → index()
+- POST /api/v1/client-groups → store()
+- GET /api/v1/client-groups/{id} → show()
+- PUT /api/v1/client-groups/{id} → update()
+- DELETE /api/v1/client-groups/{id} → destroy()
+- PATCH /api/v1/client-groups/{id}/toggle → toggle()
+```
+
+**공통 특징:**
+- ApiResponse::handle() 래퍼 사용
+- i18n 메시지 키 사용 (__('message.xxx'))
+- Service DI를 통한 비즈니스 로직 분리
+
+#### 3. PricingController 구현
+**특화된 엔드포인트:**
+```php
+- GET /api/v1/pricing → index() (가격 이력 목록)
+- GET /api/v1/pricing/show → show() (단일 항목 가격 조회)
+- POST /api/v1/pricing/bulk → bulk() (여러 항목 일괄 조회)
+- POST /api/v1/pricing/upsert → upsert() (등록/수정)
+- DELETE /api/v1/pricing/{id} → destroy() (삭제)
+```
+
+**가격 조회 파라미터:**
+- `item_type`: PRODUCT | MATERIAL (필수)
+- `item_id`: 항목 ID (필수)
+- `client_id`: 고객 ID (선택, 그룹별 가격 조회)
+- `date`: 기준일 (선택, 미지정 시 오늘)
+
+**일괄 조회 요청:**
+```json
+{
+  "items": [
+    {"item_type": "PRODUCT", "item_id": 1},
+    {"item_type": "MATERIAL", "item_id": 5}
+  ],
+  "client_id": 10,
+  "date": "2025-10-13"
+}
+```
+
+#### 4. ClientGroupApi.php Swagger 문서
+**스키마 구성:**
+- `ClientGroup` - 모델 스키마 (전체 필드)
+- `ClientGroupPagination` - 페이지네이션 응답
+- `ClientGroupCreateRequest` - 생성 요청 (required 필드)
+- `ClientGroupUpdateRequest` - 수정 요청 (optional 필드)
+
+**엔드포인트 문서:**
+- 각 엔드포인트별 파라미터, 요청/응답 예시
+- 에러 응답 (401, 404, 400) 정의
+- Security: ApiKeyAuth + BearerAuth
+
+#### 5. PricingApi.php Swagger 문서
+**스키마 구성:**
+- `PriceHistory` - 가격 이력 모델
+- `PriceHistoryPagination` - 목록 응답
+- `PriceUpsertRequest` - 등록/수정 요청
+- `PriceQueryResult` - 단일 조회 결과 (price, price_history_id, client_group_id, warning)
+- `BulkPriceQueryRequest` - 일괄 조회 요청
+- `BulkPriceQueryResult` - 일괄 조회 결과 (prices[], warnings[])
+
+**특수 스키마:**
+```php
+// 단일 항목 가격 조회 결과
+PriceQueryResult {
+  price: 50000.00,
+  price_history_id: 1,
+  client_group_id: 1,
+  warning: "가격을 찾을 수 없습니다" // nullable
+}
+
+// 일괄 조회 결과
+BulkPriceQueryResult {
+  prices: [
+    {item_type: "PRODUCT", item_id: 1, price: 50000, ...},
+    {item_type: "MATERIAL", item_id: 5, price: null, ...}
+  ],
+  warnings: ["MATERIAL(5): 가격을 찾을 수 없습니다"]
+}
+```
+
+#### 6. Routes 등록
+**ClientGroups 라우트:**
+```php
+Route::prefix('client-groups')->group(function () {
+    Route::get   ('',             [ClientGroupController::class, 'index']);
+    Route::post  ('',             [ClientGroupController::class, 'store']);
+    Route::get   ('/{id}',        [ClientGroupController::class, 'show'])->whereNumber('id');
+    Route::put   ('/{id}',        [ClientGroupController::class, 'update'])->whereNumber('id');
+    Route::delete('/{id}',        [ClientGroupController::class, 'destroy'])->whereNumber('id');
+    Route::patch ('/{id}/toggle', [ClientGroupController::class, 'toggle'])->whereNumber('id');
+});
+```
+
+**Pricing 라우트:**
+```php
+Route::prefix('pricing')->group(function () {
+    Route::get   ('',         [PricingController::class, 'index']);
+    Route::get   ('/show',    [PricingController::class, 'show']);
+    Route::post  ('/bulk',    [PricingController::class, 'bulk']);
+    Route::post  ('/upsert',  [PricingController::class, 'upsert']);
+    Route::delete('/{id}',    [PricingController::class, 'destroy'])->whereNumber('id');
+});
+```
+
+#### 7. Swagger 재생성 및 검증
+```bash
+# Swagger JSON 재생성
+php artisan l5-swagger:generate
+
+# 검증 결과
+✅ ClientGroup 태그 확인됨
+✅ Pricing 태그 확인됨
+✅ 11개 엔드포인트 모두 포함:
+   - /api/v1/client-groups (6개)
+   - /api/v1/pricing (5개)
+```
+
+### 사용한 도구:
+- **기본 Claude 도구**: Read, Write, Edit, Bash, TodoWrite
+- **MCP 서버**: 사용하지 않음 (표준 CRUD 구현)
+- **SuperClaude 페르소나**: 사용하지 않음 (기존 패턴 따름)
+
+### 아키텍처 준수 사항:
+✅ **SAM API Development Rules 준수:**
+- Service-First 아키텍처 (비즈니스 로직은 Service에)
+- Controller는 DI + ApiResponse::handle()만 사용
+- i18n 메시지 키 사용 (__('message.xxx'))
+- Validator 사용 (Service 내에서)
+- BelongsToTenant 멀티테넌트 스코프
+- SoftDeletes 적용
+- 감사 컬럼 (created_by, updated_by) 포함
+
+✅ **Swagger 문서 표준:**
+- Controller와 분리된 별도 파일
+- 파일 위치: `app/Swagger/v1/`
+- 파일명: `{Resource}Api.php`
+- 빈 메서드에 @OA 어노테이션
+- ApiResponse, ErrorResponse 재사용
+
+### API 엔드포인트 요약:
+
+#### ClientGroup API (6개)
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | /api/v1/client-groups | 목록 조회 (페이지네이션, 검색) |
+| POST | /api/v1/client-groups | 고객 그룹 생성 |
+| GET | /api/v1/client-groups/{id} | 단건 조회 |
+| PUT | /api/v1/client-groups/{id} | 수정 |
+| DELETE | /api/v1/client-groups/{id} | 삭제 (soft) |
+| PATCH | /api/v1/client-groups/{id}/toggle | 활성/비활성 토글 |
+
+#### Pricing API (5개)
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | /api/v1/pricing | 가격 이력 목록 (필터링) |
+| GET | /api/v1/pricing/show | 단일 항목 가격 조회 |
+| POST | /api/v1/pricing/bulk | 여러 항목 일괄 조회 |
+| POST | /api/v1/pricing/upsert | 가격 등록/수정 |
+| DELETE | /api/v1/pricing/{id} | 가격 이력 삭제 |
+
+### Swagger UI 접근:
+- URL: `http://localhost:8000/api-docs/index.html`
+- ClientGroup 섹션: 6개 엔드포인트
+- Pricing 섹션: 5개 엔드포인트
+- Try it out 기능으로 즉시 테스트 가능
+
+### 완료된 향후 작업 (오전 작업 기준):
+- [x] 가격 관리 API 엔드포인트 추가 (CRUD) ✅
+- [x] Swagger 문서 작성 (가격 관련 API) ✅
+- [x] 고객 그룹 관리 API 엔드포인트 추가 ✅
+
+### 신규 향후 작업:
+- [ ] API 엔드포인트 실제 테스트 (Postman/Swagger UI)
+- [ ] Frontend 가격 관리 화면 구현
+- [ ] Frontend 고객 그룹 관리 화면 구현
+- [ ] 가격 일괄 업로드 기능 추가
+- [ ] 단위 테스트 작성
+
+### Git 커밋 준비:
+- 다음 커밋 예정: `feat: ClientGroup 및 Pricing API 완성 및 Swagger 문서 작성`
+
+---
+
 ## 2025-10-13 (일) - 고객그룹별 차등 가격 시스템 구축

 ### 주요 작업
--- a/app/Http/Controllers/Api/V1/ClientGroupController.php
+++ b/app/Http/Controllers/Api/V1/ClientGroupController.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Services\ClientGroupService;
+use Illuminate\Http\Request;
+
+class ClientGroupController extends Controller
+{
+    protected ClientGroupService $service;
+
+    public function __construct(ClientGroupService $service)
+    {
+        $this->service = $service;
+    }
+
+    public function index(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $data = $this->service->index($request->all());
+
+            return ['data' => $data, 'message' => __('message.fetched')];
+        });
+    }
+
+    public function show(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $data = $this->service->show($id);
+
+            return ['data' => $data, 'message' => __('message.fetched')];
+        });
+    }
+
+    public function store(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $data = $this->service->store($request->all());
+
+            return ['data' => $data, 'message' => __('message.created')];
+        });
+    }
+
+    public function update(Request $request, int $id)
+    {
+        return ApiResponse::handle(function () use ($request, $id) {
+            $data = $this->service->update($id, $request->all());
+
+            return ['data' => $data, 'message' => __('message.updated')];
+        });
+    }
+
+    public function destroy(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $this->service->destroy($id);
+
+            return ['data' => null, 'message' => __('message.deleted')];
+        });
+    }
+
+    public function toggle(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $data = $this->service->toggle($id);
+
+            return ['data' => $data, 'message' => __('message.updated')];
+        });
+    }
+}
--- a/app/Http/Controllers/Api/V1/PricingController.php
+++ b/app/Http/Controllers/Api/V1/PricingController.php
@@ -0,0 +1,96 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Pricing\PricingService;
+use Illuminate\Http\Request;
+
+class PricingController extends Controller
+{
+    protected PricingService $service;
+
+    public function __construct(PricingService $service)
+    {
+        $this->service = $service;
+    }
+
+    /**
+     * 가격 이력 목록 조회
+     */
+    public function index(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $filters = $request->only([
+                'item_type_code',
+                'item_id',
+                'price_type_code',
+                'client_group_id',
+                'date',
+            ]);
+            $perPage = (int) ($request->input('size') ?? 15);
+
+            $data = $this->service->listPrices($filters, $perPage);
+
+            return ['data' => $data, 'message' => __('message.fetched')];
+        });
+    }
+
+    /**
+     * 단일 항목 가격 조회
+     */
+    public function show(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $itemType = $request->input('item_type'); // PRODUCT | MATERIAL
+            $itemId = (int) $request->input('item_id');
+            $clientId = $request->input('client_id') ? (int) $request->input('client_id') : null;
+            $date = $request->input('date') ?? null;
+
+            $result = $this->service->getItemPrice($itemType, $itemId, $clientId, $date);
+
+            return ['data' => $result, 'message' => __('message.fetched')];
+        });
+    }
+
+    /**
+     * 여러 항목 일괄 가격 조회
+     */
+    public function bulk(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $items = $request->input('items'); // [['item_type' => 'PRODUCT', 'item_id' => 1], ...]
+            $clientId = $request->input('client_id') ? (int) $request->input('client_id') : null;
+            $date = $request->input('date') ?? null;
+
+            $result = $this->service->getBulkItemPrices($items, $clientId, $date);
+
+            return ['data' => $result, 'message' => __('message.fetched')];
+        });
+    }
+
+    /**
+     * 가격 등록/수정
+     */
+    public function upsert(Request $request)
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $data = $this->service->upsertPrice($request->all());
+
+            return ['data' => $data, 'message' => __('message.created')];
+        });
+    }
+
+    /**
+     * 가격 삭제
+     */
+    public function destroy(int $id)
+    {
+        return ApiResponse::handle(function () use ($id) {
+            $this->service->deletePrice($id);
+
+            return ['data' => null, 'message' => __('message.deleted')];
+        });
+    }
+}
--- a/app/Services/ClientGroupService.php
+++ b/app/Services/ClientGroupService.php
@@ -0,0 +1,167 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Orders\ClientGroup;
+use Illuminate\Support\Facades\Validator;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class ClientGroupService extends Service
+{
+    /** 목록(검색/페이징) */
+    public function index(array $params)
+    {
+        $tenantId = $this->tenantId();
+
+        $page = (int) ($params['page'] ?? 1);
+        $size = (int) ($params['size'] ?? 20);
+        $q = trim((string) ($params['q'] ?? ''));
+        $onlyActive = $params['only_active'] ?? null;
+
+        $query = ClientGroup::query()->where('tenant_id', $tenantId);
+
+        if ($q !== '') {
+            $query->where(function ($qq) use ($q) {
+                $qq->where('group_name', 'like', "%{$q}%")
+                    ->orWhere('group_code', 'like', "%{$q}%");
+            });
+        }
+
+        if ($onlyActive !== null) {
+            $query->where('is_active', $onlyActive ? 1 : 0);
+        }
+
+        $query->orderBy('group_code')->orderBy('id');
+
+        return $query->paginate($size, ['*'], 'page', $page);
+    }
+
+    /** 단건 */
+    public function show(int $id)
+    {
+        $tenantId = $this->tenantId();
+        $group = ClientGroup::where('tenant_id', $tenantId)->find($id);
+        if (! $group) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        return $group;
+    }
+
+    /** 생성 */
+    public function store(array $params)
+    {
+        $tenantId = $this->tenantId();
+        $uid = $this->apiUserId();
+
+        $v = Validator::make($params, [
+            'group_code' => 'required|string|max:30',
+            'group_name' => 'required|string|max:100',
+            'price_rate' => 'required|numeric|min:0|max:99.9999',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        if ($v->fails()) {
+            throw new BadRequestHttpException($v->errors()->first());
+        }
+
+        $data = $v->validated();
+
+        // group_code 중복 검사
+        $exists = ClientGroup::where('tenant_id', $tenantId)
+            ->where('group_code', $data['group_code'])
+            ->exists();
+        if ($exists) {
+            throw new BadRequestHttpException(__('error.duplicate_code'));
+        }
+
+        $data['tenant_id'] = $tenantId;
+        $data['is_active'] = $data['is_active'] ?? 1;
+        $data['created_by'] = $uid;
+
+        return ClientGroup::create($data);
+    }
+
+    /** 수정 */
+    public function update(int $id, array $params)
+    {
+        $tenantId = $this->tenantId();
+        $uid = $this->apiUserId();
+
+        $group = ClientGroup::where('tenant_id', $tenantId)->find($id);
+        if (! $group) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        $v = Validator::make($params, [
+            'group_code' => 'sometimes|required|string|max:30',
+            'group_name' => 'sometimes|required|string|max:100',
+            'price_rate' => 'sometimes|required|numeric|min:0|max:99.9999',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        if ($v->fails()) {
+            throw new BadRequestHttpException($v->errors()->first());
+        }
+
+        $payload = $v->validated();
+
+        // group_code 변경 시 중복 검사
+        if (isset($payload['group_code']) && $payload['group_code'] !== $group->group_code) {
+            $exists = ClientGroup::where('tenant_id', $tenantId)
+                ->where('group_code', $payload['group_code'])
+                ->exists();
+            if ($exists) {
+                throw new BadRequestHttpException(__('error.duplicate_code'));
+            }
+        }
+
+        $payload['updated_by'] = $uid;
+
+        $group->update($payload);
+
+        return $group->refresh();
+    }
+
+    /** 삭제 */
+    public function destroy(int $id)
+    {
+        $tenantId = $this->tenantId();
+        $uid = $this->apiUserId();
+
+        $group = ClientGroup::where('tenant_id', $tenantId)->find($id);
+        if (! $group) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        // 해당 그룹에 속한 고객이 있는지 검사
+        if ($group->clients()->exists()) {
+            throw new BadRequestHttpException(__('error.has_clients'));
+        }
+
+        $group->deleted_by = $uid;
+        $group->save();
+        $group->delete();
+
+        return 'success';
+    }
+
+    /** 활성/비활성 토글 */
+    public function toggle(int $id)
+    {
+        $tenantId = $this->tenantId();
+        $uid = $this->apiUserId();
+
+        $group = ClientGroup::where('tenant_id', $tenantId)->find($id);
+        if (! $group) {
+            throw new NotFoundHttpException(__('error.not_found'));
+        }
+
+        $group->is_active = $group->is_active ? 0 : 1;
+        $group->updated_by = $uid;
+        $group->save();
+
+        return $group->refresh();
+    }
+}
--- a/app/Swagger/v1/ClientGroupApi.php
+++ b/app/Swagger/v1/ClientGroupApi.php
@@ -0,0 +1,176 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="ClientGroup", description="고객 그룹 관리")
+ *
+ * @OA\Schema(
+ *   schema="ClientGroup",
+ *   type="object",
+ *   required={"id","group_code","group_name","price_rate"},
+ *   @OA\Property(property="id", type="integer", example=1),
+ *   @OA\Property(property="tenant_id", type="integer", example=1),
+ *   @OA\Property(property="group_code", type="string", example="VIP"),
+ *   @OA\Property(property="group_name", type="string", example="VIP 고객"),
+ *   @OA\Property(property="price_rate", type="number", format="decimal", example=0.9, description="가격 배율 (1.0=기준가, 0.9=90%, 1.1=110%)"),
+ *   @OA\Property(property="is_active", type="boolean", example=true),
+ *   @OA\Property(property="created_at", type="string", example="2025-10-01 12:00:00"),
+ *   @OA\Property(property="updated_at", type="string", example="2025-10-01 12:00:00")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ClientGroupPagination",
+ *   type="object",
+ *   @OA\Property(property="current_page", type="integer", example=1),
+ *   @OA\Property(
+ *     property="data",
+ *     type="array",
+ *     @OA\Items(ref="#/components/schemas/ClientGroup")
+ *   ),
+ *   @OA\Property(property="first_page_url", type="string", example="/api/v1/client-groups?page=1"),
+ *   @OA\Property(property="from", type="integer", example=1),
+ *   @OA\Property(property="last_page", type="integer", example=3),
+ *   @OA\Property(property="last_page_url", type="string", example="/api/v1/client-groups?page=3"),
+ *   @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/client-groups?page=2"),
+ *   @OA\Property(property="path", type="string", example="/api/v1/client-groups"),
+ *   @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=50)
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ClientGroupCreateRequest",
+ *   type="object",
+ *   required={"group_code","group_name","price_rate"},
+ *   @OA\Property(property="group_code", type="string", maxLength=30, example="VIP", description="그룹 코드"),
+ *   @OA\Property(property="group_name", type="string", maxLength=100, example="VIP 고객", description="그룹명"),
+ *   @OA\Property(property="price_rate", type="number", format="decimal", example=0.9, description="가격 배율 (1.0=기준가)"),
+ *   @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="ClientGroupUpdateRequest",
+ *   type="object",
+ *   @OA\Property(property="group_code", type="string", maxLength=30),
+ *   @OA\Property(property="group_name", type="string", maxLength=100),
+ *   @OA\Property(property="price_rate", type="number", format="decimal"),
+ *   @OA\Property(property="is_active", type="boolean")
+ * )
+ */
+class ClientGroupApi
+{
+    /**
+     * @OA\Get(
+     *   path="/api/v1/client-groups",
+     *   tags={"ClientGroup"},
+     *   summary="고객 그룹 목록",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
+     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", example=20)),
+     *   @OA\Parameter(name="q", in="query", description="그룹 코드/이름 검색", @OA\Schema(type="string")),
+     *   @OA\Parameter(name="only_active", in="query", @OA\Schema(type="boolean")),
+     *   @OA\Response(response=200, description="조회 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientGroupPagination"))
+     *     })
+     *   ),
+     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/client-groups/{id}",
+     *   tags={"ClientGroup"},
+     *   summary="고객 그룹 단건 조회",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *   @OA\Response(response=200, description="조회 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientGroup"))
+     *     })
+     *   ),
+     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/client-groups",
+     *   tags={"ClientGroup"},
+     *   summary="고객 그룹 생성",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClientGroupCreateRequest")),
+     *   @OA\Response(response=200, description="생성 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientGroup"))
+     *     })
+     *   ),
+     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function store() {}
+
+    /**
+     * @OA\Put(
+     *   path="/api/v1/client-groups/{id}",
+     *   tags={"ClientGroup"},
+     *   summary="고객 그룹 수정",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClientGroupUpdateRequest")),
+     *   @OA\Response(response=200, description="수정 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientGroup"))
+     *     })
+     *   )
+     * )
+     */
+    public function update() {}
+
+    /**
+     * @OA\Delete(
+     *   path="/api/v1/client-groups/{id}",
+     *   tags={"ClientGroup"},
+     *   summary="고객 그룹 삭제(soft)",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
+     * )
+     */
+    public function destroy() {}
+
+    /**
+     * @OA\Patch(
+     *   path="/api/v1/client-groups/{id}/toggle",
+     *   tags={"ClientGroup"},
+     *   summary="활성/비활성 토글",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *   @OA\Response(response=200, description="변경 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientGroup"))
+     *     })
+     *   )
+     * )
+     */
+    public function toggle() {}
+}
--- a/app/Swagger/v1/PricingApi.php
+++ b/app/Swagger/v1/PricingApi.php
@@ -0,0 +1,204 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Pricing", description="가격 이력 관리")
+ *
+ * @OA\Schema(
+ *   schema="PriceHistory",
+ *   type="object",
+ *   required={"id","item_type_code","item_id","price_type_code","price","started_at"},
+ *   @OA\Property(property="id", type="integer", example=1),
+ *   @OA\Property(property="tenant_id", type="integer", example=1),
+ *   @OA\Property(property="item_type_code", type="string", enum={"PRODUCT","MATERIAL"}, example="PRODUCT", description="항목 유형"),
+ *   @OA\Property(property="item_id", type="integer", example=10, description="제품/자재 ID"),
+ *   @OA\Property(property="price_type_code", type="string", enum={"SALE","PURCHASE"}, example="SALE", description="가격 유형"),
+ *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1, description="고객 그룹 ID (NULL=기본 가격)"),
+ *   @OA\Property(property="price", type="number", format="decimal", example=50000.00),
+ *   @OA\Property(property="started_at", type="string", format="date", example="2025-01-01"),
+ *   @OA\Property(property="ended_at", type="string", format="date", nullable=true, example="2025-12-31"),
+ *   @OA\Property(property="created_at", type="string", example="2025-10-01 12:00:00"),
+ *   @OA\Property(property="updated_at", type="string", example="2025-10-01 12:00:00")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="PriceHistoryPagination",
+ *   type="object",
+ *   @OA\Property(property="current_page", type="integer", example=1),
+ *   @OA\Property(
+ *     property="data",
+ *     type="array",
+ *     @OA\Items(ref="#/components/schemas/PriceHistory")
+ *   ),
+ *   @OA\Property(property="first_page_url", type="string", example="/api/v1/pricing?page=1"),
+ *   @OA\Property(property="from", type="integer", example=1),
+ *   @OA\Property(property="last_page", type="integer", example=3),
+ *   @OA\Property(property="last_page_url", type="string", example="/api/v1/pricing?page=3"),
+ *   @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/pricing?page=2"),
+ *   @OA\Property(property="path", type="string", example="/api/v1/pricing"),
+ *   @OA\Property(property="per_page", type="integer", example=15),
+ *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
+ *   @OA\Property(property="to", type="integer", example=15),
+ *   @OA\Property(property="total", type="integer", example=50)
+ * )
+ *
+ * @OA\Schema(
+ *   schema="PriceUpsertRequest",
+ *   type="object",
+ *   required={"item_type_code","item_id","price_type_code","price","started_at"},
+ *   @OA\Property(property="item_type_code", type="string", enum={"PRODUCT","MATERIAL"}, example="PRODUCT"),
+ *   @OA\Property(property="item_id", type="integer", example=10),
+ *   @OA\Property(property="price_type_code", type="string", enum={"SALE","PURCHASE"}, example="SALE"),
+ *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1, description="NULL=기본 가격"),
+ *   @OA\Property(property="price", type="number", format="decimal", example=50000.00),
+ *   @OA\Property(property="started_at", type="string", format="date", example="2025-01-01"),
+ *   @OA\Property(property="ended_at", type="string", format="date", nullable=true, example="2025-12-31")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="PriceQueryResult",
+ *   type="object",
+ *   @OA\Property(property="price", type="number", format="decimal", nullable=true, example=50000.00),
+ *   @OA\Property(property="price_history_id", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1),
+ *   @OA\Property(property="warning", type="string", nullable=true, example="가격을 찾을 수 없습니다")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="BulkPriceQueryRequest",
+ *   type="object",
+ *   required={"items"},
+ *   @OA\Property(
+ *     property="items",
+ *     type="array",
+ *     @OA\Items(type="object",
+ *       @OA\Property(property="item_type", type="string", enum={"PRODUCT","MATERIAL"}, example="PRODUCT"),
+ *       @OA\Property(property="item_id", type="integer", example=10)
+ *     )
+ *   ),
+ *   @OA\Property(property="client_id", type="integer", nullable=true, example=5),
+ *   @OA\Property(property="date", type="string", format="date", nullable=true, example="2025-10-13")
+ * )
+ *
+ * @OA\Schema(
+ *   schema="BulkPriceQueryResult",
+ *   type="object",
+ *   @OA\Property(
+ *     property="prices",
+ *     type="array",
+ *     @OA\Items(type="object",
+ *       @OA\Property(property="item_type", type="string", example="PRODUCT"),
+ *       @OA\Property(property="item_id", type="integer", example=10),
+ *       @OA\Property(property="price", type="number", nullable=true, example=50000.00),
+ *       @OA\Property(property="price_history_id", type="integer", nullable=true, example=1),
+ *       @OA\Property(property="client_group_id", type="integer", nullable=true, example=1)
+ *     )
+ *   ),
+ *   @OA\Property(property="warnings", type="array", @OA\Items(type="string"))
+ * )
+ */
+class PricingApi
+{
+    /**
+     * @OA\Get(
+     *   path="/api/v1/pricing",
+     *   tags={"Pricing"},
+     *   summary="가격 이력 목록",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="item_type_code", in="query", @OA\Schema(type="string", enum={"PRODUCT","MATERIAL"})),
+     *   @OA\Parameter(name="item_id", in="query", @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="price_type_code", in="query", @OA\Schema(type="string", enum={"SALE","PURCHASE"})),
+     *   @OA\Parameter(name="client_group_id", in="query", @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="date", in="query", description="특정 날짜 기준 유효한 가격", @OA\Schema(type="string", format="date")),
+     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", example=15)),
+     *   @OA\Response(response=200, description="조회 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PriceHistoryPagination"))
+     *     })
+     *   ),
+     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Get(
+     *   path="/api/v1/pricing/show",
+     *   tags={"Pricing"},
+     *   summary="단일 항목 가격 조회",
+     *   description="특정 제품/자재의 현재 유효한 가격 조회",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="item_type", in="query", required=true, @OA\Schema(type="string", enum={"PRODUCT","MATERIAL"})),
+     *   @OA\Parameter(name="item_id", in="query", required=true, @OA\Schema(type="integer")),
+     *   @OA\Parameter(name="client_id", in="query", @OA\Schema(type="integer"), description="고객 ID (고객 그룹별 가격 적용)"),
+     *   @OA\Parameter(name="date", in="query", @OA\Schema(type="string", format="date"), description="기준일 (미지정시 오늘)"),
+     *   @OA\Response(response=200, description="조회 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PriceQueryResult"))
+     *     })
+     *   )
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/pricing/bulk",
+     *   tags={"Pricing"},
+     *   summary="여러 항목 일괄 가격 조회",
+     *   description="여러 제품/자재의 가격을 한 번에 조회",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BulkPriceQueryRequest")),
+     *   @OA\Response(response=200, description="조회 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/BulkPriceQueryResult"))
+     *     })
+     *   )
+     * )
+     */
+    public function bulk() {}
+
+    /**
+     * @OA\Post(
+     *   path="/api/v1/pricing/upsert",
+     *   tags={"Pricing"},
+     *   summary="가격 등록/수정",
+     *   description="가격 이력 등록 (동일 조건 존재 시 업데이트)",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/PriceUpsertRequest")),
+     *   @OA\Response(response=200, description="저장 성공",
+     *     @OA\JsonContent(allOf={
+     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PriceHistory"))
+     *     })
+     *   ),
+     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function upsert() {}
+
+    /**
+     * @OA\Delete(
+     *   path="/api/v1/pricing/{id}",
+     *   tags={"Pricing"},
+     *   summary="가격 이력 삭제(soft)",
+     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
+     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
+     * )
+     */
+    public function destroy() {}
+}
--- a/routes/api.php
+++ b/routes/api.php
@@ -27,7 +27,8 @@
 use App\Http\Controllers\Api\V1\CategoryTemplateController;
 use App\Http\Controllers\Api\V1\ClassificationController;
 use App\Http\Controllers\Api\V1\ClientController;
-
+use App\Http\Controllers\Api\V1\ClientGroupController;
+use App\Http\Controllers\Api\V1\PricingController;

 // 설계 전용 (디자인 네임스페이스)
 use App\Http\Controllers\Api\V1\Design\DesignModelController as DesignModelController;
@@ -292,6 +293,25 @@
            Route::patch ('/{id}/toggle', [ClientController::class, 'toggle'])->whereNumber('id')->name('v1.clients.toggle');  // 활성/비활성
        });

+        // Client Groups (고객 그룹 관리)
+        Route::prefix('client-groups')->group(function () {
+            Route::get   ('',             [ClientGroupController::class, 'index'])->name('v1.client-groups.index');     // 목록
+            Route::post  ('',             [ClientGroupController::class, 'store'])->name('v1.client-groups.store');     // 생성
+            Route::get   ('/{id}',        [ClientGroupController::class, 'show'])->whereNumber('id')->name('v1.client-groups.show');    // 단건
+            Route::put   ('/{id}',        [ClientGroupController::class, 'update'])->whereNumber('id')->name('v1.client-groups.update');  // 수정
+            Route::delete('/{id}',        [ClientGroupController::class, 'destroy'])->whereNumber('id')->name('v1.client-groups.destroy'); // 삭제
+            Route::patch ('/{id}/toggle', [ClientGroupController::class, 'toggle'])->whereNumber('id')->name('v1.client-groups.toggle');  // 활성/비활성
+        });
+
+        // Pricing (가격 이력 관리)
+        Route::prefix('pricing')->group(function () {
+            Route::get   ('',         [PricingController::class, 'index'])->name('v1.pricing.index');     // 목록
+            Route::get   ('/show',    [PricingController::class, 'show'])->name('v1.pricing.show');       // 단일 항목 가격 조회
+            Route::post  ('/bulk',    [PricingController::class, 'bulk'])->name('v1.pricing.bulk');       // 여러 항목 일괄 조회
+            Route::post  ('/upsert',  [PricingController::class, 'upsert'])->name('v1.pricing.upsert');   // 가격 등록/수정
+            Route::delete('/{id}',    [PricingController::class, 'destroy'])->whereNumber('id')->name('v1.pricing.destroy'); // 삭제
+        });
+
        // Products & Materials (제품/자재 통합 관리)
        Route::prefix('products')->group(function (){