Files

hskwon 33ef01b2b4 docs: API 문서 및 테스트 시나리오 추가

- front/item-master-items-api.md - Items API 프론트엔드 연동 문서
- guides/menu-delete-verification-queries.md - 메뉴 삭제 검증 쿼리 가이드
- plans/flow-tests/item-delete-force-delete.json - 품목 삭제 테스트 시나리오

2025-12-12 08:51:54 +09:00

17 KiB

Raw Blame History

품목기준관리(ItemMaster) & 품목관리(Items) API 문서

프론트엔드 개발자를 위한 API 스펙 문서 작성일: 2025-12-10

개요

품목관리 (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 예시

GET /api/v1/items?type=FG,PT&search=모터&size=10&page=1

Response

{
  "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 예시

GET /api/v1/items/123?item_type=SM&include_price=true&client_id=5

Response

{
  "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 예시

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 예시

{
  "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

{
  "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 예시

{
  "item_type": "FG",
  "name": "수정된 완제품명",
  "safety_stock": 100
}

Response

{
  "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

{
  "success": true,
  "message": "품목이 삭제되었습니다.",
  "data": "success"
}

에러 Response (BOM 사용 중)

{
  "success": false,
  "message": "해당 품목은 3건의 BOM에서 구성품으로 사용 중입니다."
}

7. 품목 일괄 삭제

역할: 여러 품목 일괄 삭제

DELETE /api/v1/items/batch

Request Body

필드	타입	필수	설명
`item_type`	string	Y	품목 유형
`ids`	array	Y	삭제할 품목 ID 배열

Request 예시

{
  "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

{
  "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는 동일한 응답 구조를 따릅니다.

성공 응답

{
  "success": true,
  "message": "처리되었습니다.",
  "data": { ... }
}

페이지네이션 응답

{
  "success": true,
  "message": "조회되었습니다.",
  "data": {
    "data": [...],
    "current_page": 1,
    "per_page": 20,
    "total": 100,
    "last_page": 5,
    "from": 1,
    "to": 20
  }
}

에러 처리

에러 응답 형식

{
  "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는 다음 인증이 필요합니다:

API Key: X-API-KEY 헤더
Bearer Token: Authorization: Bearer {token} 헤더

GET /api/v1/items
X-API-KEY: your-api-key
Authorization: Bearer your-access-token

변경 이력

날짜	버전	변경 내용
2025-12-10	1.0	최초 작성

17 KiB Raw Blame History

품목기준관리(ItemMaster) & 품목관리(Items) API 문서

목차

개요

품목관리 (Items) vs 품목기준관리 (ItemMaster)

품목 유형 코드 (item_type / product_type)

품목관리 (Items) API

1. 통합 품목 목록 조회

Request Parameters (Query)

Request 예시

Response

Response 필드 설명

2. 단일 품목 조회 (ID 기반)

Path Parameters

Query Parameters

Request 예시

Response

3. 단일 품목 조회 (코드 기반)

Path Parameters

Query Parameters

Request 예시

4. 품목 생성

Request Body

Request 예시

Response

5. 품목 수정

Path Parameters

Request Body

Request 예시

Response

6. 품목 삭제 (Soft Delete)

Path Parameters

Query Parameters

Response

에러 Response (BOM 사용 중)

7. 품목 일괄 삭제

Request Body

Request 예시

품목기준관리 (ItemMaster) API

구조 개요

1. 초기화 데이터 로드

Response

Response 필드 설명

2. 페이지 API

페이지 목록 조회

페이지 생성

페이지 수정

페이지 삭제

3. 섹션 API

독립 섹션 목록 조회

독립 섹션 생성 (페이지 연결 없음)

페이지에 섹션 생성 (연결)

섹션 복제

섹션 사용처 조회

섹션 수정

섹션 삭제

섹션 순서 변경

4. 필드 API

독립 필드 목록 조회

독립 필드 생성 (섹션 연결 없음)

필드 타입 (field_type)

섹션에 필드 생성 (연결)

필드 복제

필드 사용처 조회

필드 수정

필드 삭제

공통 응답 형식

성공 응답

페이지네이션 응답

에러 처리

에러 응답 형식

주요 HTTP 상태 코드

주요 에러 케이스

인증

변경 이력

17 KiB

Raw Blame History