764 lines
17 KiB
Markdown
764 lines
17 KiB
Markdown
|
# 품목기준관리(ItemMaster) & 품목관리(Items) API 문서
|
||
|
|
|
||
|
|
> 프론트엔드 개발자를 위한 API 스펙 문서
|
||
|
|
> 작성일: 2025-12-10
|
||
|
|
|
||
|
|
## 목차
|
||
|
|
1. [개요](#개요)
|
||
|
|
2. [품목관리 (Items) API](#품목관리-items-api)
|
||
|
|
3. [품목기준관리 (ItemMaster) API](#품목기준관리-itemmaster-api)
|
||
|
|
4. [공통 응답 형식](#공통-응답-형식)
|
||
|
|
5. [에러 처리](#에러-처리)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 개요
|
||
|
|
|
||
|
|
### 품목관리 (Items) vs 품목기준관리 (ItemMaster)
|
||
|
|
|
||
|
|
| 구분 | 품목관리 (Items) | 품목기준관리 (ItemMaster) |
|
||
|
|
|------|------------------|---------------------------|
|
||
|
|
| **역할** | 실제 품목 데이터 CRUD | 품목 입력 화면/폼 구성 관리 |
|
||
|
|
| **대상 데이터** | products, materials 테이블 | item_pages, item_sections, item_fields 테이블 |
|
||
|
|
| **사용자** | 품목 등록/수정하는 일반 사용자 | 화면 구성을 설정하는 관리자 |
|
||
|
|
| **비유** | 엑셀 데이터 | 엑셀 양식(템플릿) |
|
||
|
|
|
||
|
|
### 품목 유형 코드 (item_type / product_type)
|
||
|
|
|
||
|
|
| 코드 | 설명 | 저장 테이블 |
|
||
|
|
|------|------|-------------|
|
||
|
|
| `FG` | 완제품 (Finished Goods) | products |
|
||
|
|
| `PT` | 반제품/부품 (Part) | products |
|
||
|
|
| `SM` | 반자재 (Semi-Material) | materials |
|
||
|
|
| `RM` | 원자재 (Raw Material) | materials |
|
||
|
|
| `CS` | 소모품 (Consumables) | materials |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 품목관리 (Items) API
|
||
|
|
|
||
|
|
실제 품목 데이터를 조회/생성/수정/삭제하는 API입니다.
|
||
|
|
|
||
|
|
### 1. 통합 품목 목록 조회
|
||
|
|
|
||
|
|
**역할**: products와 materials를 통합하여 조회 (UNION 방식)
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/items
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Request Parameters (Query)
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `type` | string | N | 품목 유형 필터 (쉼표 구분). 기본값: `FG,PT,SM,RM,CS` |
|
||
|
|
| `search` 또는 `q` | string | N | 검색어 (코드, 이름, 태그) |
|
||
|
|
| `category_id` | integer | N | 카테고리 ID 필터 |
|
||
|
|
| `size` | integer | N | 페이지당 항목 수. 기본값: 20 |
|
||
|
|
| `page` | integer | N | 페이지 번호. 기본값: 1 |
|
||
|
|
| `include_deleted` | boolean | N | 삭제된 항목 포함 여부. 기본값: false |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```http
|
||
|
|
GET /api/v1/items?type=FG,PT&search=모터&size=10&page=1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "조회되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"data": [
|
||
|
|
{
|
||
|
|
"id": 1,
|
||
|
|
"item_type": "FG",
|
||
|
|
"code": "P-001",
|
||
|
|
"name": "완제품A",
|
||
|
|
"specification": null,
|
||
|
|
"unit": "EA",
|
||
|
|
"category_id": 5,
|
||
|
|
"type_code": "FG",
|
||
|
|
"created_at": "2025-01-01T00:00:00.000000Z",
|
||
|
|
"deleted_at": null,
|
||
|
|
"safety_stock": 100,
|
||
|
|
"lead_time": 7
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"current_page": 1,
|
||
|
|
"per_page": 20,
|
||
|
|
"total": 150,
|
||
|
|
"last_page": 8
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response 필드 설명
|
||
|
|
|
||
|
|
| 필드 | 설명 |
|
||
|
|
|------|------|
|
||
|
|
| `id` | 품목 고유 ID (테이블별 독립) |
|
||
|
|
| `item_type` | 품목 유형 코드 |
|
||
|
|
| `code` | 품목 코드 |
|
||
|
|
| `name` | 품목명 |
|
||
|
|
| `specification` | 규격 (materials만 해당) |
|
||
|
|
| `unit` | 단위 (EA, KG, M 등) |
|
||
|
|
| `category_id` | 카테고리 ID |
|
||
|
|
| `type_code` | 품목 유형 코드 (item_type과 동일) |
|
||
|
|
| `created_at` | 생성일시 |
|
||
|
|
| `deleted_at` | 삭제일시 (Soft Delete) |
|
||
|
|
| `safety_stock` | 안전재고 (attributes에서 플랫 전개) |
|
||
|
|
| `lead_time` | 리드타임 (attributes에서 플랫 전개) |
|
||
|
|
|
||
|
|
> **Note**: `attributes` JSON 필드는 자동으로 최상위로 플랫 전개되어 반환됩니다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 2. 단일 품목 조회 (ID 기반)
|
||
|
|
|
||
|
|
**역할**: 특정 ID의 품목 상세 정보 조회 (가격 정보 옵션)
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/items/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Path Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `id` | integer | Y | 품목 ID |
|
||
|
|
|
||
|
|
#### Query Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `item_type` | string | N | 품목 유형 코드. 기본값: `FG` |
|
||
|
|
| `include_price` | boolean | N | 가격 정보 포함 여부. 기본값: false |
|
||
|
|
| `client_id` | integer | N | 고객 ID (가격 조회 시) |
|
||
|
|
| `price_date` | string | N | 가격 기준일 (YYYY-MM-DD) |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```http
|
||
|
|
GET /api/v1/items/123?item_type=SM&include_price=true&client_id=5
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "조회되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"id": 123,
|
||
|
|
"item_type": "SM",
|
||
|
|
"code": "M-001",
|
||
|
|
"name": "반자재A",
|
||
|
|
"specification": "10mm x 20mm",
|
||
|
|
"unit": "EA",
|
||
|
|
"category_id": 10,
|
||
|
|
"category": {
|
||
|
|
"id": 10,
|
||
|
|
"name": "철강류"
|
||
|
|
},
|
||
|
|
"type_code": "SM",
|
||
|
|
"prices": {
|
||
|
|
"sale": {
|
||
|
|
"unit_price": 15000,
|
||
|
|
"currency": "KRW",
|
||
|
|
"effective_from": "2025-01-01"
|
||
|
|
},
|
||
|
|
"purchase": {
|
||
|
|
"unit_price": 10000,
|
||
|
|
"currency": "KRW",
|
||
|
|
"effective_from": "2025-01-01"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 3. 단일 품목 조회 (코드 기반)
|
||
|
|
|
||
|
|
**역할**: 품목 코드로 상세 정보 조회 (Product → Material 순서로 검색)
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/items/code/{code}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Path Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `code` | string | Y | 품목 코드 |
|
||
|
|
|
||
|
|
#### Query Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `include_bom` | boolean | N | BOM 정보 포함 여부. 기본값: false |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```http
|
||
|
|
GET /api/v1/items/code/P-001?include_bom=true
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 4. 품목 생성
|
||
|
|
|
||
|
|
**역할**: 새 품목 등록 (product_type에 따라 products 또는 materials에 저장)
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/items
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Request Body
|
||
|
|
|
||
|
|
| 필드 | 타입 | 필수 | 설명 |
|
||
|
|
|------|------|------|------|
|
||
|
|
| `code` | string | Y | 품목 코드 (최대 50자, 중복 시 자동 증가) |
|
||
|
|
| `name` | string | Y | 품목명 (최대 255자) |
|
||
|
|
| `product_type` | string | Y | 품목 유형: `FG`, `PT`, `SM`, `RM`, `CS` |
|
||
|
|
| `unit` | string | Y | 단위 (최대 20자) |
|
||
|
|
| `category_id` | integer | N | 카테고리 ID |
|
||
|
|
| `description` | string | N | 설명 |
|
||
|
|
| `is_sellable` | boolean | N | 판매 가능 여부. 기본값: true |
|
||
|
|
| `is_purchasable` | boolean | N | 구매 가능 여부. 기본값: false |
|
||
|
|
| `is_producible` | boolean | N | 생산 가능 여부. 기본값: false |
|
||
|
|
| `safety_stock` | integer | N | 안전재고 (0 이상) |
|
||
|
|
| `lead_time` | integer | N | 리드타임 (0 이상) |
|
||
|
|
| `is_variable_size` | boolean | N | 가변 사이즈 여부 |
|
||
|
|
| `product_category` | string | N | 제품 분류 (최대 20자) |
|
||
|
|
| `part_type` | string | N | 부품 유형 (최대 20자) |
|
||
|
|
| `attributes` | object | N | 동적 필드 (JSON) |
|
||
|
|
| `material_code` | string | N | 자재 코드 (Material 전용) |
|
||
|
|
| `item_name` | string | N | 품명 (Material 전용) |
|
||
|
|
| `specification` | string | N | 규격 (Material 전용) |
|
||
|
|
| `is_inspection` | string | N | 검수 여부: `Y`, `N` |
|
||
|
|
| `search_tag` | string | N | 검색 태그 |
|
||
|
|
| `remarks` | string | N | 비고 |
|
||
|
|
| `options` | object | N | 옵션 (JSON) |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"code": "P-NEW-001",
|
||
|
|
"name": "신규 완제품",
|
||
|
|
"product_type": "FG",
|
||
|
|
"unit": "EA",
|
||
|
|
"category_id": 5,
|
||
|
|
"is_sellable": true,
|
||
|
|
"safety_stock": 50,
|
||
|
|
"attributes": {
|
||
|
|
"color": "red",
|
||
|
|
"size": "L"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "품목이 생성되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"id": 999,
|
||
|
|
"code": "P-NEW-001",
|
||
|
|
"name": "신규 완제품",
|
||
|
|
"product_type": "FG",
|
||
|
|
"unit": "EA",
|
||
|
|
"category_id": 5,
|
||
|
|
"is_active": true,
|
||
|
|
"is_sellable": true,
|
||
|
|
"is_purchasable": false,
|
||
|
|
"is_producible": false,
|
||
|
|
"created_by": 1,
|
||
|
|
"created_at": "2025-12-10T10:00:00.000000Z"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
> **중복 코드 처리**: 코드가 이미 존재하면 자동으로 증가합니다.
|
||
|
|
> - `P-001` 중복 → `P-002`
|
||
|
|
> - `ABC` 중복 → `ABC-001`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 5. 품목 수정
|
||
|
|
|
||
|
|
**역할**: 기존 품목 정보 수정
|
||
|
|
|
||
|
|
```
|
||
|
|
PUT /api/v1/items/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Path Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `id` | integer | Y | 품목 ID |
|
||
|
|
|
||
|
|
#### Request Body
|
||
|
|
|
||
|
|
| 필드 | 타입 | 필수 | 설명 |
|
||
|
|
|------|------|------|------|
|
||
|
|
| `item_type` | string | Y | 품목 유형 (테이블 분기용) |
|
||
|
|
| `code` | string | N | 품목 코드 |
|
||
|
|
| `name` | string | N | 품목명 |
|
||
|
|
| ... | | | (생성과 동일한 필드, 모두 선택) |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"item_type": "FG",
|
||
|
|
"name": "수정된 완제품명",
|
||
|
|
"safety_stock": 100
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "품목이 수정되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"id": 999,
|
||
|
|
"code": "P-NEW-001",
|
||
|
|
"name": "수정된 완제품명",
|
||
|
|
"safety_stock": 100,
|
||
|
|
"updated_by": 1,
|
||
|
|
"updated_at": "2025-12-10T11:00:00.000000Z"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 6. 품목 삭제 (Soft Delete)
|
||
|
|
|
||
|
|
**역할**: 품목 삭제 (BOM 구성품으로 사용 중이면 삭제 불가)
|
||
|
|
|
||
|
|
```
|
||
|
|
DELETE /api/v1/items/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Path Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `id` | integer | Y | 품목 ID |
|
||
|
|
|
||
|
|
#### Query Parameters
|
||
|
|
|
||
|
|
| 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------|------|------|------|
|
||
|
|
| `item_type` | string | N | 품목 유형. 기본값: `FG` |
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "품목이 삭제되었습니다.",
|
||
|
|
"data": "success"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 에러 Response (BOM 사용 중)
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": false,
|
||
|
|
"message": "해당 품목은 3건의 BOM에서 구성품으로 사용 중입니다."
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 7. 품목 일괄 삭제
|
||
|
|
|
||
|
|
**역할**: 여러 품목 일괄 삭제
|
||
|
|
|
||
|
|
```
|
||
|
|
DELETE /api/v1/items/batch
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Request Body
|
||
|
|
|
||
|
|
| 필드 | 타입 | 필수 | 설명 |
|
||
|
|
|------|------|------|------|
|
||
|
|
| `item_type` | string | Y | 품목 유형 |
|
||
|
|
| `ids` | array | Y | 삭제할 품목 ID 배열 |
|
||
|
|
|
||
|
|
#### Request 예시
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"item_type": "FG",
|
||
|
|
"ids": [1, 2, 3, 4, 5]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 품목기준관리 (ItemMaster) API
|
||
|
|
|
||
|
|
품목 입력 화면의 구성(페이지, 섹션, 필드)을 관리하는 API입니다.
|
||
|
|
|
||
|
|
### 구조 개요
|
||
|
|
|
||
|
|
```
|
||
|
|
ItemMaster 계층 구조:
|
||
|
|
|
||
|
|
Page (페이지)
|
||
|
|
├── Section (섹션) - fields 타입
|
||
|
|
│ ├── Field (필드)
|
||
|
|
│ ├── Field (필드)
|
||
|
|
│ └── Field (필드)
|
||
|
|
└── Section (섹션) - bom 타입
|
||
|
|
├── BomItem (BOM 항목)
|
||
|
|
└── BomItem (BOM 항목)
|
||
|
|
```
|
||
|
|
|
||
|
|
- **Page**: 품목 유형별 입력 화면 (예: 완제품 등록 페이지)
|
||
|
|
- **Section**: 페이지 내 영역 구분 (예: 기본정보, BOM 구성)
|
||
|
|
- **Field**: 입력 필드 정의 (예: 품목코드, 품목명)
|
||
|
|
- **BomItem**: BOM 섹션의 구성품 정의
|
||
|
|
|
||
|
|
### 1. 초기화 데이터 로드
|
||
|
|
|
||
|
|
**역할**: 프론트엔드 앱 초기화 시 필요한 전체 ItemMaster 데이터 로드
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/init
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "조회되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"pages": [
|
||
|
|
{
|
||
|
|
"id": 1,
|
||
|
|
"tenant_id": 1,
|
||
|
|
"group_id": null,
|
||
|
|
"page_name": "완제품 등록",
|
||
|
|
"item_type": "FG",
|
||
|
|
"absolute_path": "/items/fg/create",
|
||
|
|
"is_active": true,
|
||
|
|
"sections": [
|
||
|
|
{
|
||
|
|
"id": 10,
|
||
|
|
"title": "기본정보",
|
||
|
|
"type": "fields",
|
||
|
|
"order_no": 1,
|
||
|
|
"is_locked": false,
|
||
|
|
"fields": [
|
||
|
|
{
|
||
|
|
"id": 100,
|
||
|
|
"field_name": "품목코드",
|
||
|
|
"field_key": "code",
|
||
|
|
"field_type": "textbox",
|
||
|
|
"is_required": true,
|
||
|
|
"order_no": 1,
|
||
|
|
"is_locked": true
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"sections": [...],
|
||
|
|
"fields": [...],
|
||
|
|
"customTabs": [...],
|
||
|
|
"unitOptions": [...]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Response 필드 설명
|
||
|
|
|
||
|
|
| 필드 | 설명 |
|
||
|
|
|------|------|
|
||
|
|
| `pages` | 페이지 목록 (섹션, 필드 중첩 포함) |
|
||
|
|
| `sections` | 모든 독립 섹션 목록 (재사용 가능) |
|
||
|
|
| `fields` | 모든 독립 필드 목록 (재사용 가능) |
|
||
|
|
| `customTabs` | 커스텀 탭 목록 (컬럼 설정 포함) |
|
||
|
|
| `unitOptions` | 단위 옵션 목록 |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 2. 페이지 API
|
||
|
|
|
||
|
|
#### 페이지 목록 조회
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/pages
|
||
|
|
```
|
||
|
|
|
||
|
|
| Query 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------------|------|------|------|
|
||
|
|
| `item_type` | string | N | 품목 유형 필터 |
|
||
|
|
|
||
|
|
#### 페이지 생성
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/pages
|
||
|
|
```
|
||
|
|
|
||
|
|
| Request Body | 타입 | 필수 | 설명 |
|
||
|
|
|--------------|------|------|------|
|
||
|
|
| `page_name` | string | Y | 페이지명 (최대 255자) |
|
||
|
|
| `item_type` | string | Y | 품목 유형: `FG`, `PT`, `SM`, `RM`, `CS` |
|
||
|
|
| `absolute_path` | string | N | 절대 경로 (최대 500자) |
|
||
|
|
|
||
|
|
#### 페이지 수정
|
||
|
|
|
||
|
|
```
|
||
|
|
PUT /api/v1/item-master/pages/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 페이지 삭제
|
||
|
|
|
||
|
|
```
|
||
|
|
DELETE /api/v1/item-master/pages/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 3. 섹션 API
|
||
|
|
|
||
|
|
#### 독립 섹션 목록 조회
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/sections
|
||
|
|
```
|
||
|
|
|
||
|
|
| Query 파라미터 | 타입 | 필수 | 설명 |
|
||
|
|
|----------------|------|------|------|
|
||
|
|
| `is_template` | boolean | N | 템플릿 섹션 필터 |
|
||
|
|
|
||
|
|
#### 독립 섹션 생성 (페이지 연결 없음)
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/sections
|
||
|
|
```
|
||
|
|
|
||
|
|
| Request Body | 타입 | 필수 | 설명 |
|
||
|
|
|--------------|------|------|------|
|
||
|
|
| `group_id` | integer | N | 계층 번호 |
|
||
|
|
| `title` | string | Y | 섹션 제목 (최대 255자) |
|
||
|
|
| `type` | string | Y | 섹션 타입: `fields`, `bom` |
|
||
|
|
|
||
|
|
#### 페이지에 섹션 생성 (연결)
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/pages/{pageId}/sections
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 섹션 복제
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/sections/{id}/clone
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 섹션 사용처 조회
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/sections/{id}/usage
|
||
|
|
```
|
||
|
|
|
||
|
|
**역할**: 해당 섹션이 어떤 페이지에서 사용되고 있는지 조회
|
||
|
|
|
||
|
|
#### 섹션 수정
|
||
|
|
|
||
|
|
```
|
||
|
|
PUT /api/v1/item-master/sections/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 섹션 삭제
|
||
|
|
|
||
|
|
```
|
||
|
|
DELETE /api/v1/item-master/sections/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 섹션 순서 변경
|
||
|
|
|
||
|
|
```
|
||
|
|
PUT /api/v1/item-master/pages/{pageId}/sections/reorder
|
||
|
|
```
|
||
|
|
|
||
|
|
| Request Body | 타입 | 필수 | 설명 |
|
||
|
|
|--------------|------|------|------|
|
||
|
|
| `items` | array | Y | `[{id: 1, order_no: 1}, {id: 2, order_no: 2}]` |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 4. 필드 API
|
||
|
|
|
||
|
|
#### 독립 필드 목록 조회
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/fields
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 독립 필드 생성 (섹션 연결 없음)
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/fields
|
||
|
|
```
|
||
|
|
|
||
|
|
| Request Body | 타입 | 필수 | 설명 |
|
||
|
|
|--------------|------|------|------|
|
||
|
|
| `group_id` | integer | N | 계층 번호 |
|
||
|
|
| `field_name` | string | Y | 필드 표시명 (최대 255자) |
|
||
|
|
| `field_key` | string | N | 필드 키 (최대 80자, 영문 시작) |
|
||
|
|
| `field_type` | string | Y | 필드 타입 (아래 참조) |
|
||
|
|
| `is_required` | boolean | N | 필수 입력 여부 |
|
||
|
|
| `default_value` | string | N | 기본값 |
|
||
|
|
| `placeholder` | string | N | 플레이스홀더 (최대 255자) |
|
||
|
|
| `display_condition` | object | N | 표시 조건 (JSON) |
|
||
|
|
| `validation_rules` | object | N | 검증 규칙 (JSON) |
|
||
|
|
| `options` | array | N | 드롭다운 옵션 등 (JSON) |
|
||
|
|
| `properties` | object | N | 추가 속성 (JSON) |
|
||
|
|
| `is_locked` | boolean | N | 잠금 여부 |
|
||
|
|
|
||
|
|
#### 필드 타입 (field_type)
|
||
|
|
|
||
|
|
| 타입 | 설명 |
|
||
|
|
|------|------|
|
||
|
|
| `textbox` | 한 줄 텍스트 입력 |
|
||
|
|
| `number` | 숫자 입력 |
|
||
|
|
| `dropdown` | 드롭다운 선택 |
|
||
|
|
| `checkbox` | 체크박스 |
|
||
|
|
| `date` | 날짜 선택 |
|
||
|
|
| `textarea` | 여러 줄 텍스트 입력 |
|
||
|
|
|
||
|
|
#### 섹션에 필드 생성 (연결)
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/sections/{sectionId}/fields
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 필드 복제
|
||
|
|
|
||
|
|
```
|
||
|
|
POST /api/v1/item-master/fields/{id}/clone
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 필드 사용처 조회
|
||
|
|
|
||
|
|
```
|
||
|
|
GET /api/v1/item-master/fields/{id}/usage
|
||
|
|
```
|
||
|
|
|
||
|
|
**역할**: 해당 필드가 어떤 섹션에서 사용되고 있는지 조회
|
||
|
|
|
||
|
|
#### 필드 수정
|
||
|
|
|
||
|
|
```
|
||
|
|
PUT /api/v1/item-master/fields/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 필드 삭제
|
||
|
|
|
||
|
|
```
|
||
|
|
DELETE /api/v1/item-master/fields/{id}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 공통 응답 형식
|
||
|
|
|
||
|
|
모든 API는 동일한 응답 구조를 따릅니다.
|
||
|
|
|
||
|
|
### 성공 응답
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "처리되었습니다.",
|
||
|
|
"data": { ... }
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 페이지네이션 응답
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": true,
|
||
|
|
"message": "조회되었습니다.",
|
||
|
|
"data": {
|
||
|
|
"data": [...],
|
||
|
|
"current_page": 1,
|
||
|
|
"per_page": 20,
|
||
|
|
"total": 100,
|
||
|
|
"last_page": 5,
|
||
|
|
"from": 1,
|
||
|
|
"to": 20
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 에러 처리
|
||
|
|
|
||
|
|
### 에러 응답 형식
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"success": false,
|
||
|
|
"message": "에러 메시지",
|
||
|
|
"errors": {
|
||
|
|
"field_name": ["검증 오류 메시지"]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 주요 HTTP 상태 코드
|
||
|
|
|
||
|
|
| 코드 | 설명 |
|
||
|
|
|------|------|
|
||
|
|
| `200` | 성공 |
|
||
|
|
| `201` | 생성 성공 |
|
||
|
|
| `400` | 잘못된 요청 (검증 실패, 중복 코드 등) |
|
||
|
|
| `401` | 인증 필요 |
|
||
|
|
| `403` | 권한 없음 |
|
||
|
|
| `404` | 리소스 없음 |
|
||
|
|
| `422` | 검증 실패 (Validation Error) |
|
||
|
|
| `500` | 서버 오류 |
|
||
|
|
|
||
|
|
### 주요 에러 케이스
|
||
|
|
|
||
|
|
| 상황 | 메시지 예시 |
|
||
|
|
|------|-------------|
|
||
|
|
| 품목 없음 | "해당 품목을 찾을 수 없습니다." |
|
||
|
|
| 코드 중복 | "이미 사용 중인 품목코드입니다." |
|
||
|
|
| BOM 사용 중 | "해당 품목은 N건의 BOM에서 구성품으로 사용 중입니다." |
|
||
|
|
| 필수 필드 누락 | "품목코드는 필수입니다." |
|
||
|
|
| 잘못된 품목 유형 | "품목 유형은 FG, PT, SM, RM, CS 중 하나여야 합니다." |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 인증
|
||
|
|
|
||
|
|
모든 API는 다음 인증이 필요합니다:
|
||
|
|
|
||
|
|
1. **API Key**: `X-API-KEY` 헤더
|
||
|
|
2. **Bearer Token**: `Authorization: Bearer {token}` 헤더
|
||
|
|
|
||
|
|
```http
|
||
|
|
GET /api/v1/items
|
||
|
|
X-API-KEY: your-api-key
|
||
|
|
Authorization: Bearer your-access-token
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 변경 이력
|
||
|
|
|
||
|
|
| 날짜 | 버전 | 변경 내용 |
|
||
|
|
|------|------|----------|
|
||
|
|
| 2025-12-10 | 1.0 | 최초 작성 |
|