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

264 lines
8.0 KiB
Markdown
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 미리보기 요청
```json
{
"input_parameters": {
"W0": 1000,
"H0": 800,
"installation_type": "A",
"power_source": "220V"
},
"include_calculated_values": true,
"include_bom_items": true
}
```
### BOM 미리보기 응답
```json
{
"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
}
}
}
```
### 제품 생성 요청
```json
{
"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
}
```
### 제품 생성 응답
```json
{
"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 해석 및 제품 생성
각 엔드포인트는 상세한 요청/응답 스키마와 예시를 포함하고 있습니다.
Reference in New Issue View Git Blame Copy Permalink