Files

권혁성 0ace50b006 docs: [종합정비] 구조 재편 — Phase 0+2+4 통합

- Phase 0: INDEX.md 전면 재작성, CLAUDE.md→INDEX.md 통합 삭제
- Phase 0: front/→guides/ 이관(5개 파일), changes/ D7 포맷 통일(3개)
- Phase 0: guides/ai-config-설정.md→ai-config-settings.md D3 통일
- Phase 2: architecture/+specs/→system/ 이관(6개 이동, 4개 폐기)
- Phase 2: 13개 파일 경로 참조 수정 (specs/→system/, architecture/→system/)
- Phase 4: 7개 파일 11개 교차참조 깨진 링크 수정

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-27 18:03:04 +09:00

10 KiB

Raw Blame History

품목기준관리(ItemMaster) API 가이드

품목 입력 화면을 구성하는 페이지-섹션-필드 구조 관리 시스템

1. 개요

1.1 핵심 개념

엔티티	테이블	설명
Page	`item_pages`	품목 유형별 화면 (FG, PT, SM, RM, CS)
Section	`item_sections`	페이지 내 논리적 영역
Field	`item_fields`	섹션 내 입력 항목
BomItem	`item_bom_items`	BOM 섹션 내 부품 항목
CustomTab	`custom_tabs`	커스텀 탭 설정
UnitOption	`unit_options`	단위 옵션

1.2 아키텍처

독립 엔티티 구조: 섹션, 필드, BOM은 독립적으로 존재하며 재사용 가능
링크 테이블: entity_relationships로 관계 관리
연결 잠금: 중요한 구조는 잠금으로 보호 가능

ItemPage (item_type: FG, PT, SM, RM, CS)
    │
    │ entity_relationships (is_locked)
    ▼
ItemSection (type: default, bom, custom)
    │
    ├─ entity_relationships → ItemField
    └─ entity_relationships → ItemBomItem

2. API 엔드포인트

2.1 초기화

Method	Endpoint	설명
GET	`/api/v1/item-master/init`	전체 데이터 로드

응답 구조:

{
  "pages": [],       // 페이지 + 연결된 섹션/필드
  "sections": [],    // 모든 독립 섹션
  "fields": [],      // 모든 독립 필드
  "customTabs": [],  // 커스텀 탭
  "unitOptions": []  // 단위 옵션
}

2.2 페이지

Method	Endpoint	설명
GET	`/api/v1/item-master/pages`	페이지 목록
POST	`/api/v1/item-master/pages`	페이지 생성
PUT	`/api/v1/item-master/pages/{id}`	페이지 수정
DELETE	`/api/v1/item-master/pages/{id}`	페이지 삭제

2.3 섹션

Method	Endpoint	설명
GET	`/api/v1/item-master/sections`	독립 섹션 목록
POST	`/api/v1/item-master/sections`	독립 섹션 생성
POST	`/api/v1/item-master/pages/{pageId}/sections`	섹션 생성 + 페이지 연결
PUT	`/api/v1/item-master/sections/{id}`	섹션 수정
DELETE	`/api/v1/item-master/sections/{id}`	섹션 삭제
POST	`/api/v1/item-master/sections/{id}/clone`	섹션 복제
GET	`/api/v1/item-master/sections/{id}/usage`	사용처 조회
PUT	`/api/v1/item-master/pages/{pageId}/sections/reorder`	섹션 순서 변경

2.4 필드

Method	Endpoint	설명
GET	`/api/v1/item-master/fields`	독립 필드 목록
POST	`/api/v1/item-master/fields`	독립 필드 생성
POST	`/api/v1/item-master/sections/{sectionId}/fields`	필드 생성 + 섹션 연결
PUT	`/api/v1/item-master/fields/{id}`	필드 수정
DELETE	`/api/v1/item-master/fields/{id}`	필드 삭제
POST	`/api/v1/item-master/fields/{id}/clone`	필드 복제
GET	`/api/v1/item-master/fields/{id}/usage`	사용처 조회
PUT	`/api/v1/item-master/sections/{sectionId}/fields/reorder`	필드 순서 변경

2.5 BOM

Method	Endpoint	설명
GET	`/api/v1/item-master/bom-items`	독립 BOM 목록
POST	`/api/v1/item-master/bom-items`	독립 BOM 생성
POST	`/api/v1/item-master/sections/{sectionId}/bom-items`	BOM 생성 + 섹션 연결
PUT	`/api/v1/item-master/bom-items/{id}`	BOM 수정
DELETE	`/api/v1/item-master/bom-items/{id}`	BOM 삭제

2.6 섹션 템플릿

Method	Endpoint	설명
GET	`/api/v1/item-master/section-templates`	템플릿 목록
POST	`/api/v1/item-master/section-templates`	템플릿 생성
PUT	`/api/v1/item-master/section-templates/{id}`	템플릿 수정
DELETE	`/api/v1/item-master/section-templates/{id}`	템플릿 삭제

2.7 커스텀 탭

Method	Endpoint	설명
GET	`/api/v1/item-master/custom-tabs`	탭 목록
POST	`/api/v1/item-master/custom-tabs`	탭 생성
PUT	`/api/v1/item-master/custom-tabs/{id}`	탭 수정
DELETE	`/api/v1/item-master/custom-tabs/{id}`	탭 삭제
PUT	`/api/v1/item-master/custom-tabs/reorder`	탭 순서 변경

2.8 단위 옵션

Method	Endpoint	설명
GET	`/api/v1/item-master/unit-options`	단위 목록
POST	`/api/v1/item-master/unit-options`	단위 생성
DELETE	`/api/v1/item-master/unit-options/{id}`	단위 삭제

2.9 엔티티 관계 (Link/Unlink)

페이지-섹션 연결:

Method	Endpoint	설명
POST	`/api/v1/item-master/pages/{pageId}/link-section`	섹션 연결
DELETE	`/api/v1/item-master/pages/{pageId}/unlink-section/{sectionId}`	섹션 연결 해제

페이지-필드 연결:

Method	Endpoint	설명
POST	`/api/v1/item-master/pages/{pageId}/link-field`	필드 연결
DELETE	`/api/v1/item-master/pages/{pageId}/unlink-field/{fieldId}`	필드 연결 해제

섹션-필드 연결:

Method	Endpoint	설명
POST	`/api/v1/item-master/sections/{sectionId}/link-field`	필드 연결
DELETE	`/api/v1/item-master/sections/{sectionId}/unlink-field/{fieldId}`	필드 연결 해제

섹션-BOM 연결:

Method	Endpoint	설명
POST	`/api/v1/item-master/sections/{sectionId}/link-bom`	BOM 연결
DELETE	`/api/v1/item-master/sections/{sectionId}/unlink-bom/{bomId}`	BOM 연결 해제

관계 조회/정렬:

Method	Endpoint	설명
GET	`/api/v1/item-master/pages/{pageId}/relationships`	페이지 관계 조회
GET	`/api/v1/item-master/pages/{pageId}/structure`	페이지 구조 조회
GET	`/api/v1/item-master/sections/{sectionId}/relationships`	섹션 관계 조회
POST	`/api/v1/item-master/relationships/reorder`	관계 순서 변경

3. 데이터 구조

3.1 ItemPage

interface ItemPage {
  id: number;
  tenant_id: number;
  group_id: number;
  page_name: string;
  item_type: 'FG' | 'PT' | 'SM' | 'RM' | 'CS';
  source_table: 'products' | 'materials';
  absolute_path?: string;
  is_active: boolean;
  sections: ItemSection[];  // init 응답에 포함
}

3.2 ItemSection

interface ItemSection {
  id: number;
  tenant_id: number;
  group_id: number;
  title: string;
  type: string;
  order_no: number;
  is_template: boolean;
  is_default: boolean;
  is_locked?: boolean;    // 연결 잠금 상태
  description?: string;
  fields?: ItemField[];
  bom_items?: ItemBomItem[];
}

3.3 ItemField

interface ItemField {
  id: number;
  tenant_id: number;
  group_id: number;
  field_name: string;
  field_key: string;           // 저장 시 사용할 키
  field_type: FieldType;
  order_no: number;
  is_required: boolean;
  is_common: boolean;
  is_active: boolean;
  is_locked: boolean;
  default_value?: string;
  placeholder?: string;
  display_condition?: object;  // 조건부 표시
  validation_rules?: object;   // 유효성 검사 규칙
  options?: object;            // dropdown 옵션 등
  properties?: object;         // 추가 설정
  category?: string;
  description?: string;
}

type FieldType = 'textbox' | 'number' | 'dropdown' | 'checkbox' | 'date' | 'textarea';

3.4 EntityRelationship

interface EntityRelationship {
  id: number;
  tenant_id: number;
  group_id: number;
  parent_type: 'page' | 'section';
  parent_id: number;
  child_type: 'section' | 'field' | 'bom';
  child_id: number;
  order_no: number;
  is_locked: boolean;
  locked_by?: number;
  locked_at?: string;
  metadata?: object;
}

4. 잠금(Lock) 기능

4.1 잠금의 의미

연결이 잠기면:

해당 연결(관계)를 해제할 수 없음
연결된 자식 엔티티를 삭제할 수 없음
이름 변경, 속성 추가 등 비구조적 수정은 허용

예시: page→section 연결이 잠김
├─ ❌ 섹션을 페이지에서 분리할 수 없음
├─ ❌ 해당 섹션을 삭제할 수 없음
├─ ✅ 섹션 제목 변경 가능
└─ ✅ 섹션에 새 필드 추가 가능

4.2 잠금 상태 확인

init API 응답에 is_locked 필드가 포함됩니다.

{
  "pages": [{
    "id": 1,
    "sections": [{
      "id": 10,
      "is_locked": true,
      "fields": [{
        "id": 100,
        "is_locked": false
      }]
    }]
  }]
}

4.3 잠금 관련 에러

{
  "success": false,
  "message": "잠금된 연결은 해제할 수 없습니다.",
  "error": "entity_protected_by_locked_relationship"
}

5. 필드 타입

field_type	설명	렌더링 컴포넌트
`textbox`	텍스트 입력	`<Input type="text" />`
`number`	숫자 입력	`<Input type="number" />`
`dropdown`	드롭다운 선택	`<Select />`
`checkbox`	체크박스	`<Checkbox />`
`date`	날짜 선택	`<DatePicker />`
`textarea`	장문 텍스트	`<Textarea />`

6. 주의사항

6.1 삭제 시 동작

페이지 삭제: 연결된 섹션/필드는 삭제되지 않고 관계만 해제
섹션 삭제: 연결된 필드/BOM은 삭제되지 않고 관계만 해제
잠금된 연결이 있으면: 삭제/해제 불가

6.2 복제(Clone) 시 동작

섹션 복제: 섹션 + 필드 + BOM 모두 복제
필드 복제: 필드만 복제
복제된 항목은 독립 엔티티로 생성됨

6.3 순서 변경

Drag & Drop 후 reorder API 호출 필요
items 배열에 {id, order_no} 형태로 전달

7. 변경 이력

날짜	변경 내용
2025-12-09	시스템 기반 문서 전면 재작성
2025-11-27	잠금(Lock) 기능 추가
2025-11-26	독립 엔티티 아키텍처 적용
2025-11-20	entity_relationships 링크 테이블 도입

10 KiB Raw Blame History

품목기준관리(ItemMaster) API 가이드

1. 개요

1.1 핵심 개념

1.2 아키텍처

2. API 엔드포인트

2.1 초기화

2.2 페이지

2.3 섹션

2.4 필드

2.5 BOM

2.6 섹션 템플릿

2.7 커스텀 탭

2.8 단위 옵션

2.9 엔티티 관계 (Link/Unlink)

3. 데이터 구조

3.1 ItemPage

3.2 ItemSection

3.3 ItemField

3.4 EntityRelationship

4. 잠금(Lock) 기능

4.1 잠금의 의미

4.2 잠금 상태 확인

4.3 잠금 관련 에러

5. 필드 타입

6. 주의사항

6.1 삭제 시 동작

6.2 복제(Clone) 시 동작

6.3 순서 변경

7. 변경 이력

10 KiB

Raw Blame History