SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf8036a64baf7a4df132e301355f4dda684f2bad
sam-api/docs/parameter-based-bom-endpoints.md
kent bf8036a64b feat: DB 연결 오버라이딩 및 대시보드 통계 위젯 추가 
- DB 연결: 로컬/Docker 환경 오버라이딩 설정 (.env)
- 테넌트 위젯: redirect 버그 수정 (TenantSelectorWidget)
- 통계 위젯: 사용자/제품/자재/주문 카드 추가 (StatsOverviewWidget)
- 리소스 한국어화: Product, Material 모델 레이블 추가
- 대시보드: 위젯 등록 및 캐시 최적화

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-30 23:31:14 +09:00

8.0 KiB
Raw Blame History

매개변수 기반 BOM 시스템 API 엔드포인트

엔드포인트 개요

이 문서는 SAM 프로젝트의 매개변수 기반 BOM 시스템을 위한 모든 RESTful API 엔드포인트를 요약합니다.

인증 및 권한

  • API Key: 모든 요청에 X-API-KEY 헤더 필요
  • Bearer Token: 사용자 컨텍스트가 필요한 요청에 Authorization: Bearer {token} 헤더 필요
  • 미들웨어: auth.apikey + auth:sanctum

매개변수 관리 API

모델 매개변수

메서드 엔드포인트 설명 권한
GET /v1/design/models/{modelId}/parameters 매개변수 목록 조회 READ
POST /v1/design/models/{modelId}/parameters 매개변수 생성 CREATE
PUT /v1/design/models/{modelId}/parameters/{parameterId} 매개변수 수정 UPDATE
DELETE /v1/design/models/{modelId}/parameters/{parameterId} 매개변수 삭제 DELETE

쿼리 파라미터 (GET):

  • page: 페이지 번호 (기본값: 1)
  • per_page: 페이지당 항목 수 (기본값: 20)
  • search: 매개변수명/라벨 검색
  • type: 매개변수 타입 필터 (INPUT, OUTPUT)

공식 관리 API

모델 공식

메서드 엔드포인트 설명 권한
GET /v1/design/models/{modelId}/formulas 공식 목록 조회 READ
POST /v1/design/models/{modelId}/formulas 공식 생성 CREATE
PUT /v1/design/models/{modelId}/formulas/{formulaId} 공식 수정 UPDATE
DELETE /v1/design/models/{modelId}/formulas/{formulaId} 공식 삭제 DELETE
POST /v1/design/models/{modelId}/formulas/{formulaId}/validate 공식 검증 READ

쿼리 파라미터 (GET):

  • page: 페이지 번호
  • per_page: 페이지당 항목 수
  • search: 공식명/대상 매개변수 검색
  • target_parameter: 대상 매개변수 필터

조건 규칙 관리 API

BOM 조건 규칙

메서드 엔드포인트 설명 권한
GET /v1/design/bom-templates/{bomTemplateId}/condition-rules 조건 규칙 목록 조회 READ
POST /v1/design/bom-templates/{bomTemplateId}/condition-rules 조건 규칙 생성 CREATE
PUT /v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId} 조건 규칙 수정 UPDATE
DELETE /v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId} 조건 규칙 삭제 DELETE
POST /v1/design/bom-templates/{bomTemplateId}/condition-rules/{ruleId}/toggle 규칙 활성/비활성 토글 UPDATE

쿼리 파라미터 (GET):

  • page: 페이지 번호
  • per_page: 페이지당 항목 수
  • search: 규칙명/대상 컴포넌트 검색
  • ref_type: 참조 타입 필터 (MATERIAL, PRODUCT)
  • is_active: 활성 상태 필터

핵심 BOM 해석 API

BOM 해석 및 제품 생성

메서드 엔드포인트 설명 권한
POST /v1/products/models/{modelId}/resolve-preview 실시간 BOM 미리보기 READ
POST /v1/products/create-from-model 제품 생성 + BOM 적용 CREATE
POST /v1/design/models/{modelId}/validate-parameters 매개변수 검증 READ

제품 조회 API

메서드 엔드포인트 설명 권한
GET /v1/products/{productId}/parameters 제품별 매개변수 조회 READ
GET /v1/products/{productId}/calculated-values 제품별 산출값 조회 READ

주요 요청/응답 스키마

실시간 BOM 미리보기 요청

{
  "input_parameters": {
    "W0": 1000,
    "H0": 800,
    "installation_type": "A",
    "power_source": "220V"
  },
  "include_calculated_values": true,
  "include_bom_items": true
}

BOM 미리보기 응답

{
  "success": true,
  "message": "bom.preview_generated",
  "data": {
    "input_parameters": { ... },
    "calculated_values": {
      "W1": 1050,
      "H1": 850,
      "area": 892500,
      "weight": 27.31,
      "motor_power": 150
    },
    "bom_items": [
      {
        "ref_type": "MATERIAL",
        "ref_code": "BR-001",
        "ref_name": "표준 브라켓",
        "quantity": 3.0,
        "waste_rate": 0.05,
        "total_quantity": 3.15,
        "unit_cost": 5000.0,
        "total_cost": 15750.0,
        "applied_rule": "표준 브라켓 선택"
      }
    ],
    "summary": {
      "total_materials": 4,
      "total_cost": 110470.0,
      "estimated_weight": 27.31
    }
  }
}

제품 생성 요청

{
  "model_id": 1,
  "input_parameters": {
    "W0": 1000,
    "H0": 800,
    "installation_type": "A",
    "power_source": "220V"
  },
  "product_code": "KSS01-1000x800-A",
  "product_name": "KSS01 스크린 1000x800 A타입",
  "category_id": 1,
  "description": "매개변수 기반으로 생성된 맞춤형 스크린",
  "create_bom_items": true,
  "validate_bom": true
}

제품 생성 응답

{
  "success": true,
  "message": "product.created_from_model",
  "data": {
    "product": {
      "id": 123,
      "code": "KSS01-1000x800-A",
      "name": "KSS01 스크린 1000x800 A타입",
      "type": "PRODUCT"
    },
    "input_parameters": { ... },
    "calculated_values": { ... },
    "bom_items": [ ... ],
    "summary": {
      "total_bom_items": 4,
      "model_id": 1,
      "bom_template_id": 1
    }
  }
}

매개변수 데이터 타입

입력 매개변수 타입

타입 설명 예시
INTEGER 정수 1000
DECIMAL 소수 1000.5
STRING 문자열 "A"
BOOLEAN 불린 true

공식 표현식 예시

표현식 설명
W0 + 50 단순 산술 연산
W0 * H0 곱셈 연산
installation_type == "A" ? 50 : 30 조건부 연산
ceiling(W1 / 500) 수학 함수
W0 > 1000 && H0 > 800 논리 연산

BOM 조건 규칙 예시

조건 수량 공식 설명
installation_type == "A" ceiling(W1 / 500) A타입일 때 너비 기반 수량
motor_power >= 150 1 고출력 모터 조건
true ceiling(H1 / 1000) * 2 항상 적용되는 가이드 레일

에러 코드

일반 에러

코드 메시지 설명
400 Bad Request 잘못된 요청
401 Unauthorized 인증 실패
403 Forbidden 권한 없음
404 Not Found 리소스 없음
422 Validation Error 입력 검증 실패

비즈니스 로직 에러

코드 메시지 키 설명
400 error.model.not_found 모델을 찾을 수 없음
400 error.parameter.invalid_type 잘못된 매개변수 타입
400 error.formula.syntax_error 공식 구문 오류
400 error.bom.resolution_failed BOM 해석 실패
400 error.product.duplicate_code 제품 코드 중복

제한사항

Rate Limiting

  • 일반 요청: 테넌트당 1000 req/hour
  • BOM 해석: 테넌트당 100 req/hour
  • 제품 생성: 테넌트당 50 req/hour

데이터 제한

  • 매개변수: 모델당 최대 50개
  • 공식: 모델당 최대 100개
  • 조건 규칙: BOM 템플릿당 최대 200개
  • BOM 항목: 제품당 최대 500개

성능 고려사항

  • 복잡한 공식: 중첩 깊이 최대 10단계
  • 대용량 BOM: 1000개 이상 항목시 배치 처리 권장
  • 동시 생성: 동일 모델 기반 제품 동시 생성시 순차 처리

Swagger 문서

전체 API 스펙은 Swagger UI에서 확인할 수 있습니다:

  • Swagger UI: /api-docs/index.html
  • JSON Spec: /docs/api-docs.json

주요 태그

  • Model Parameters: 모델 매개변수 관리
  • Model Formulas: 모델 공식 관리
  • BOM Condition Rules: BOM 조건 규칙 관리
  • BOM Resolver: BOM 해석 및 제품 생성

각 엔드포인트는 상세한 요청/응답 스키마와 예시를 포함하고 있습니다.