sam-api/CURRENT_WORKS.md

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) - 활성/비활성 상태 토글

검증 규칙:

- 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 패턴:

- 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 구현

특화된 엔드포인트:

- 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: 기준일 (선택, 미지정 시 오늘)

일괄 조회 요청:

{
  "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[])

특수 스키마:

// 단일 항목 가격 조회 결과
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 라우트:

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 라우트:

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 재생성 및 검증

# 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 기능으로 즉시 테스트 가능

완료된 향후 작업 (오전 작업 기준):

• 가격 관리 API 엔드포인트 추가 (CRUD) ✅
• Swagger 문서 작성 (가격 관련 API) ✅
• 고객 그룹 관리 API 엔드포인트 추가 ✅

신규 향후 작업:

• API 엔드포인트 실제 테스트 (Postman/Swagger UI)
• Frontend 가격 관리 화면 구현
• Frontend 고객 그룹 관리 화면 구현
• 가격 일괄 업로드 기능 추가
• 단위 테스트 작성

Git 커밋 준비:

• 다음 커밋 예정: feat: ClientGroup 및 Pricing API 완성 및 Swagger 문서 작성

---

2025-10-13 (일) - 고객그룹별 차등 가격 시스템 구축

주요 작업

• 고객 그룹 관리 시스템 구축: 고객별 차등 가격 관리를 위한 client_groups 테이블 및 모델 구현
• 가격 이력 시스템 확장: price_histories 테이블에 고객그룹별 가격 지원 추가
• PricingService 신규 구축: 우선순위 기반 가격 조회 로직 구현
• EstimateService 통합: 견적 생성 시 자동 가격 계산 기능 추가

추가된 파일:

• database/migrations/2025_10_13_213549_create_client_groups_table.php - 고객 그룹 테이블 생성
• database/migrations/2025_10_13_213556_add_client_group_id_to_clients_table.php - clients 테이블에 그룹 ID 추가
• database/migrations/2025_10_13_213602_add_client_group_id_to_price_histories_table.php - price_histories 테이블에 그룹 ID 추가
• app/Models/Orders/ClientGroup.php - 고객 그룹 모델
• app/Services/Pricing/PricingService.php - 가격 조회/관리 서비스

수정된 파일:

• app/Models/Orders/Client.php - ClientGroup 관계 추가
• app/Models/Products/PriceHistory.php - ClientGroup 관계 추가, 다양한 스코프 메서드 추가
• app/Services/Estimate/EstimateService.php - PricingService 의존성 주입 및 가격 계산 로직 통합
• lang/ko/error.php - price_not_found 에러 메시지 추가

작업 내용:

1. 데이터베이스 스키마 설계

client_groups 테이블:

- id, tenant_id
- group_code (그룹 코드)
- group_name (그룹명)
- price_rate (가격 배율: 1.0 = 기준가, 0.9 = 90%, 1.1 = 110%)
- is_active (활성 여부)
- created_by, updated_by, deleted_by (감사 컬럼)
- created_at, updated_at, deleted_at
- UNIQUE(tenant_id, group_code)

clients 테이블 확장:

• client_group_id 컬럼 추가 (NULL 허용 = 기본 그룹)

price_histories 테이블 확장:

• client_group_id 컬럼 추가 (NULL = 기본 가격, 값 있으면 그룹별 차등 가격)
• 인덱스 재구성: (tenant_id, item_type_code, item_id, client_group_id, started_at)

2. 모델 관계 설정

ClientGroup 모델:

• clients() → hasMany 관계
• scopeActive() → 활성 그룹만 조회
• scopeCode() → 코드로 검색

Client 모델:

• clientGroup() → belongsTo 관계

PriceHistory 모델:

• clientGroup() → belongsTo 관계
• item() → Polymorphic 관계 (Product/Material)
• 다양한 스코프 메서드:
  • scopeForItem() → 특정 항목 필터링
  • scopeForClientGroup() → 고객 그룹 필터링
  • scopeValidAt() → 기준일 기준 유효한 가격
  • scopeSalePrice() → 매출단가만
  • scopePurchasePrice() → 매입단가만

3. PricingService 핵심 로직

가격 조회 우선순위:

1순위: 고객 그룹별 매출단가 (client_group_id 있음)
2순위: 기본 매출단가 (client_group_id = NULL)
3순위: NULL (경고 발생)

// ❌ 제거: 매입단가는 견적에서 사용하지 않음 (순수 참고용)

주요 메서드:

• getItemPrice() → 단일 항목 가격 조회
• getBulkItemPrices() → 여러 항목 일괄 조회
• upsertPrice() → 가격 등록/수정
• listPrices() → 가격 이력 조회 (페이지네이션)
• deletePrice() → 가격 삭제 (Soft Delete)

4. EstimateService 통합

견적 생성 프로세스:

1. BOM 계산 (수량만)
2. 각 BOM 항목의 가격 조회 (PricingService)
3. unit_price × quantity = total_price 계산
4. 전체 항목의 total_price 합산 = total_amount
5. 가격 없는 항목 경고 로그 기록

수정된 메서드:

• createEstimate() → client_id 전달, total_amount 재계산
• updateEstimate() → 파라미터 변경 시 가격 재계산
• createEstimateItems() → 가격 조회 로직 추가, float 반환

5. 에러 처리 및 로깅

가격 없는 항목 처리:

• 경고 메시지 반환: __('error.price_not_found', [...])
• Laravel Log에 경고 기록
• 견적 생성은 계속 진행 (unit_price = 0)
• 프론트엔드에서 경고 표시 가능

비즈니스 규칙 정리:

매입단가 vs 매출단가

• 매입단가 (PURCHASE): 순수 참고용, 견적 계산에 미사용
• 매출단가 (SALE): 실제 견적 계산에 사용
• STANDARD 가격: 경동 비즈니스에서는 불필요 (사용하지 않음)

고객 그룹별 차등 가격

예시 데이터:
- 기본 가격: 100,000원 (client_group_id = NULL)
- A그룹 가격: 90,000원 (client_group_id = 1, price_rate = 0.9)
- B그룹 가격: 110,000원 (client_group_id = 2, price_rate = 1.1)

조회 로직:
- A그룹 고객 → 90,000원 (1순위)
- B그룹 고객 → 110,000원 (1순위)
- 일반 고객 → 100,000원 (2순위)
- 가격 없음 → NULL + 경고 (3순위)

마이그레이션 실행 결과:

✅ 2025_10_13_213549_create_client_groups_table (46.85ms)
✅ 2025_10_13_213556_add_client_group_id_to_clients_table (38.75ms)
✅ 2025_10_13_213602_add_client_group_id_to_price_histories_table (38.46ms)

코드 품질:

• Laravel Pint 포맷팅 완료 (5 files, 4 style issues fixed)
• SAM API Development Rules 준수
• Service-First 아키텍처 유지
• BelongsToTenant 멀티테넌트 스코프 적용
• SoftDeletes 적용
• 감사 컬럼 (created_by, updated_by, deleted_by) 포함

예상 효과:

1. 유연한 가격 관리: 고객 그룹별 차등 가격 설정 가능
2. 자동 가격 계산: 견적 생성 시 수동 입력 불필요
3. 이력 관리: 기간별 가격 변동 이력 추적
4. 확장성: 향후 복잡한 가격 정책 적용 가능
5. 투명성: 가격 출처 추적 가능 (price_history_id, client_group_id)

향후 작업:

• PricingService 구현
• EstimateService 통합
• 가격 관리 API 엔드포인트 추가 (CRUD)
• Swagger 문서 작성 (가격 관련 API)
• 고객 그룹 관리 API 엔드포인트 추가
• Frontend 가격 관리 화면 구현
• 가격 일괄 업로드 기능 추가

Git 커밋 준비:

• 다음 커밋 예정: feat: 고객그룹별 차등 가격 시스템 구축

---

2025-10-01 (화) - Client API 및 Swagger 문서 구조 개선

주요 작업

• Client API Swagger 문서 생성: Controller에서 분리된 Swagger 파일 생성
• Swagger 구조 표준화: Controller는 비즈니스 로직만, Swagger는 별도 파일로 관리
• CLAUDE.md 업데이트: Swagger 문서 작성 규칙 명확화

추가된 파일:

• app/Swagger/v1/ClientApi.php - Client API Swagger 문서 (Tag, Schemas, Endpoints)

수정된 파일:

• app/Http/Controllers/Api/V1/ClientController.php - Swagger 어노테이션 제거 (비즈니스 로직만 유지)
• CLAUDE.md - Swagger 문서 작성 규칙 섹션 업데이트

작업 내용:

1. Swagger 문서 구조 표준화

기존 방식 (잘못된 방식):

• Controller에 Swagger 어노테이션 직접 작성
• 비즈니스 로직과 API 문서가 혼재
• Controller 가독성 저하

새로운 방식 (표준 방식):

• app/Swagger/v1/{Resource}Api.php 별도 파일로 관리
• Controller는 순수 비즈니스 로직만 포함
• Swagger 문서는 독립적으로 관리

2. ClientApi.php 구조

namespace App\Swagger\v1;

/**
 * @OA\Tag - 리소스 태그 정의
 * @OA\Schema(schema="Client") - 모델 스키마
 * @OA\Schema(schema="ClientPagination") - 페이지네이션
 * @OA\Schema(schema="ClientCreateRequest") - 생성 요청
 * @OA\Schema(schema="ClientUpdateRequest") - 수정 요청
 */
class ClientApi {
    public function index() {}  // GET /api/v1/clients
    public function show() {}   // GET /api/v1/clients/{id}
    public function store() {}  // POST /api/v1/clients
    public function update() {} // PUT /api/v1/clients/{id}
    public function destroy() {} // DELETE /api/v1/clients/{id}
    public function toggle() {} // PATCH /api/v1/clients/{id}/toggle
}

3. CLAUDE.md 규칙 업데이트

추가된 내용:

• Swagger 파일 위치: app/Swagger/v1/
• 파일 네이밍: {Resource}Api.php
• Controller 정책: Swagger 어노테이션 금지
• Schemas 구성: Model, Pagination, CreateRequest, UpdateRequest
• 재생성 명령어: php artisan l5-swagger:generate

4. Client API 엔드포인트 구성

• GET /api/v1/clients - 거래처 목록 (페이지네이션)
• GET /api/v1/clients/{id} - 거래처 상세
• POST /api/v1/clients - 거래처 생성
• PUT /api/v1/clients/{id} - 거래처 수정
• DELETE /api/v1/clients/{id} - 거래처 삭제 (soft)
• PATCH /api/v1/clients/{id}/toggle - 활성/비활성 토글

시스템 개선 효과:

1. 코드 가독성 향상: Controller가 순수 비즈니스 로직만 포함
2. 문서 관리 효율성: Swagger 문서를 독립적으로 관리 가능
3. 표준화: 모든 API가 동일한 구조로 문서화
4. 유지보수성: Swagger 변경 시 Controller 영향 없음

Swagger 재생성:

php artisan l5-swagger:generate

• Client API가 Swagger UI에 "Client" 태그로 표시됨
• /api-docs/index.html에서 확인 가능

향후 작업:

• 다른 Controller에도 동일한 패턴 적용
• Swagger 문서 품질 검증
• API 엔드포인트 테스트

---

2025-09-24 (화) - FK 제약조건 최적화 및 데이터베이스 성능 개선

주요 작업

• 데이터베이스 FK 제약조건 분석 및 최적화
• 성능과 관리 편의성을 위한 비중요 FK 제거
• 3단계 점진적 FK 제거 마이그레이션 구현

추가된 파일:

• database/migrations/2025_09_24_214146_remove_non_critical_foreign_keys_phase1.php - 1차 FK 제거 (Classifications, Departments)
• database/migrations/2025_09_24_214200_remove_estimate_foreign_keys_phase2.php - 2차 FK 제거 (견적 시스템)
• database/migrations/2025_09_24_214300_remove_material_foreign_key_phase3.php - 3차 FK 제거 (제품-자재 관계)
• CURRENT_WORKS.md - 저장소별 작업 현황 추적

수정된 파일:

• CLAUDE.md - CURRENT_WORKS.md 파일 위치 규칙 명확화
• database/migrations/2025_09_24_000002_create_dynamic_estimate_fields.php - level 컬럼 제거로 마이그레이션 오류 해결

작업 내용:

1. FK 제약조건 현황 분석

• 현재 8개 마이그레이션에서 FK 제약조건 사용 확인
• 권한 관리, 제품/자재 관리, 견적 시스템, 기타 시스템별 분류
• 총 15+개의 FK 제약조건 식별

2. 중요도별 테이블 분류

🔴 핵심 테이블 (FK 유지 필수):

• 인증/권한 시스템: users, roles, permissions 관계
• 제품/BOM 관리 핵심: products.category_id, product_components 내부 관계
• 멀티테넌트 핵심: 모든 tenant_id 참조

🟡 중요 테이블 (FK 선택적 유지):

• 견적 시스템: estimates, estimate_items 관계
• 자재 관리: product_components.material_id

🟢 일반 테이블 (FK 제거 권장):

• 분류/코드 관리: classifications.tenant_id
• 부서 관리: departments.parent_id (자기참조)
• 감사 로그: 모든 audit 관련 FK

3. 코드 영향도 분석 결과

✅ 중요 결론: 모델/컨트롤러/서비스 코드 수정 불필요!

• Laravel Eloquent 관계가 FK 제약조건과 독립적으로 작동
• 현재 코드가 CASCADE 동작에 의존하지 않음
• BelongsToTenant 트레잇과 소프트 딜리트로 무결성 관리
• 비즈니스 로직이 애플리케이션 레벨에서 처리됨

4. 3단계 점진적 FK 제거 전략

Phase 1 (즉시 적용 가능):

• classifications.tenant_id → tenants
• departments.parent_id → departments (자기참조)
• 영향도: 낮음, 관리 편의성 증가

Phase 2 (견적 시스템):

• estimates.model_set_id → categories
• estimate_items.estimate_id → estimates
• 영향도: 중간, 성능 향상 효과
• 멀티테넌트 보안 FK는 유지

Phase 3 (신중한 검토 필요):

• product_components.material_id → materials
• 영향도: 중간, 자재 관리 유연성 증가
• 핵심 제품 관계 FK는 유지

5. 마이그레이션 특징

• 동적 FK 이름 탐지로 안전한 제거
• 성능을 위한 인덱스 유지/추가
• 상세한 진행 상황 로깅
• 완전한 롤백 기능
• 각 단계별 영향도와 주의사항 문서화

데이터베이스 마이그레이션 상태:

• 기존 마이그레이션 오류 해결 완료 (level 컬럼 이슈)
• 새로운 FK 제거 마이그레이션 3개 생성
• 롤백 가능한 안전한 구조로 설계

예상 효과:

1. 성능 향상: 견적 시스템과 분류 관리에서 FK 검증 오버헤드 제거
2. 관리 편의성: 부서 구조 변경, 자재 관리 시 유연성 증가
3. 개발 생산성: 데이터 변경 시 FK 제약 에러 감소
4. 확장성: 향후 시스템 확장 시 유연한 스키마 변경 가능

향후 작업:

1. Phase 1 마이그레이션 개발 서버 테스트
2. 각 단계별 성능 영향 모니터링
3. Service 레벨에서 데이터 무결성 검증 로직 보강 검토
4. 프로덕션 적용 전 백업 및 롤백 계획 수립

논리적 관계 자동화 시스템 구축:

• 자동화 도구 4개 생성: 관계 문서 생성/업데이트/모델생성 명령어
• Provider 시스템: 마이그레이션 후 자동 문서 업데이트
• 간소화 문서: 즉시 사용 가능한 관계 문서 생성 (LOGICAL_RELATIONSHIPS_SIMPLE.md)

새로운 명령어:

• php artisan db:update-relationships - 모델에서 관계 자동 추출
• php artisan db:generate-simple-relationships - 기본 관계 문서 생성
• php artisan make:model-with-docs - 모델 생성 후 관계 문서 자동 업데이트

ERD 생성 시스템:

• ERD 생성 도구: beyondcode/laravel-er-diagram-generator 활용
• GraphViz 설치: brew install graphviz로 dot 명령어 지원
• 모델 오류 해결: BelongsToTenantTrait → BelongsToTenant 수정
• 생성 결과: 60개 모델의 완전한 관계도 생성 (graph.png, 4.1MB)
• 명령어: php artisan generate:erd --format=png

예상 효과 (업데이트):

1. 시각화 개선: 복잡한 다중 테넌트 구조의 시각적 이해 향상
2. 개발 생산성: ERD를 통한 빠른 스키마 파악 및 설계 검증
3. 문서화 자동화: 스키마 변경 시 ERD 자동 업데이트 가능
4. 기존 효과 유지: 성능 향상, 관리 편의성, 확장성은 FK 제거로 달성

Git 커밋:

• cfd4c25 - fix: categories 테이블 level 컬럼 제거로 마이그레이션 오류 해결
• 7dafab3 - docs: CURRENT_WORKS.md 파일 위치 규칙 명확화
• c63e676 - feat: 데이터베이스 FK 제약조건 최적화 및 3단계 마이그레이션 구현