From 593644922ad092c81d16f1425faf52079e08d34e Mon Sep 17 00:00:00 2001 From: byeongcheolryu Date: Tue, 25 Nov 2025 21:07:10 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20API=20=ED=94=84=EB=A1=9D=EC=8B=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=20=EB=B0=8F=20=ED=92=88=EB=AA=A9=EA=B8=B0?= =?UTF-8?q?=EC=A4=80=EA=B4=80=EB=A6=AC=20=EA=B8=B0=EB=8A=A5=20=EA=B0=9C?= =?UTF-8?q?=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - HttpOnly 쿠키 기반 API 프록시 라우트 추가 (/api/proxy/[...path]) - 품목기준관리 컴포넌트 개선 (섹션, 필드, 다이얼로그) - ItemMasterContext API 연동 강화 - mock-data 제거 및 실제 API 연동 - 문서 명명규칙 정리 ([TYPE-DATE] 형식) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...ANALYSIS-2025-11-21] item-master-notes.md} | 0 ...11-24] item-management-dynamic-api-spec.md | 1595 +++++++++++++++++ ...item-master-data-management-api-request.md | 971 ++++++++++ ...2025-11-25] section-template-fields-api.md | 588 ++++++ ...25] httponly-cookie-security-validation.md | 370 ++++ ...11-24] item-management-dynamic-frontend.md | 1128 ++++++++++++ ...=> [IMPL-2025-11-18] ssr-hydration-fix.md} | 0 ... => [PLAN-2025-11-18] refactoring-plan.md} | 0 ...[PLAN-2025-11-21] component-separation.md} | 0 ...md => [REF-2025-11-18] cleanup-summary.md} | 0 ...> [REF-2025-11-18] unused-files-report.md} | 0 claudedocs/_API_DESIGN_ITEM_MASTER_CONFIG.md | 958 ---------- claudedocs/_ITEM_MASTER_API_STRUCTURE.md | 1388 -------------- src/app/api/proxy/[...path]/route.ts | 244 +++ src/components/auth/LoginPage.tsx | 4 +- src/components/items/BOMManagementSection.tsx | 15 +- src/components/items/ItemDetailClient.tsx | 2 +- .../items/ItemMasterDataManagement.tsx | 375 ++-- .../components/ConditionalDisplayUI.tsx | 110 +- .../components/DraggableField.tsx | 22 +- .../components/DraggableSection.tsx | 13 +- .../dialogs/FieldDialog.tsx | 48 +- .../dialogs/PageDialog.tsx | 9 +- .../dialogs/SectionDialog.tsx | 279 ++- .../dialogs/TemplateFieldDialog.tsx | 165 +- .../tabs/HierarchyTab/index.tsx | 5 +- .../tabs/MasterFieldTab/index.tsx | 18 +- .../tabs/SectionsTab.tsx | 10 +- src/contexts/ItemMasterContext.tsx | 326 ++-- src/hooks/useCurrentTime.ts | 12 +- src/lib/api/auth-headers.ts | 32 +- src/lib/api/error-handler.ts | 14 +- src/lib/api/item-master.ts | 5 +- src/lib/api/items.ts | 6 +- src/lib/api/mock-data.ts | 449 ----- src/types/item-master-api.ts | 1 + tsconfig.tsbuildinfo | 2 +- 37 files changed, 5897 insertions(+), 3267 deletions(-) rename claudedocs/{itemmaster.txt => [ANALYSIS-2025-11-21] item-master-notes.md} (100%) create mode 100644 claudedocs/[API-2025-11-24] item-management-dynamic-api-spec.md create mode 100644 claudedocs/[API-2025-11-25] item-master-data-management-api-request.md create mode 100644 claudedocs/[API-REQUEST-2025-11-25] section-template-fields-api.md create mode 100644 claudedocs/[CASE-2025-11-25] httponly-cookie-security-validation.md create mode 100644 claudedocs/[DESIGN-2025-11-24] item-management-dynamic-frontend.md rename claudedocs/{SSR_HYDRATION_FIX.md => [IMPL-2025-11-18] ssr-hydration-fix.md} (100%) rename claudedocs/{REFACTORING_PLAN.md => [PLAN-2025-11-18] refactoring-plan.md} (100%) rename claudedocs/{COMPONENT_SEPARATION_PLAN.md => [PLAN-2025-11-21] component-separation.md} (100%) rename claudedocs/{CLEANUP_SUMMARY.md => [REF-2025-11-18] cleanup-summary.md} (100%) rename claudedocs/{UNUSED_FILES_REPORT.md => [REF-2025-11-18] unused-files-report.md} (100%) delete mode 100644 claudedocs/_API_DESIGN_ITEM_MASTER_CONFIG.md delete mode 100644 claudedocs/_ITEM_MASTER_API_STRUCTURE.md create mode 100644 src/app/api/proxy/[...path]/route.ts delete mode 100644 src/lib/api/mock-data.ts diff --git a/claudedocs/itemmaster.txt b/claudedocs/[ANALYSIS-2025-11-21] item-master-notes.md similarity index 100% rename from claudedocs/itemmaster.txt rename to claudedocs/[ANALYSIS-2025-11-21] item-master-notes.md diff --git a/claudedocs/[API-2025-11-24] item-management-dynamic-api-spec.md b/claudedocs/[API-2025-11-24] item-management-dynamic-api-spec.md new file mode 100644 index 00000000..a68d6600 --- /dev/null +++ b/claudedocs/[API-2025-11-24] item-management-dynamic-api-spec.md @@ -0,0 +1,1595 @@ +ㅓ# 품목관리 동적 화면 생성 API 명세서 + +**작성일**: 2025-11-24 +**프로젝트**: SAM MES System +**기준 문서**: api_rules.md, architecture.md, swagger_guide.md + +--- + +## 목차 + +1. [개요](#개요) +2. [아키텍처 설계](#아키텍처-설계) +3. [API 엔드포인트 명세](#api-엔드포인트-명세) +4. [데이터 구조](#데이터-구조) +5. [구현 가이드](#구현-가이드) +6. [Swagger 문서화](#swagger-문서화) + +--- + +## 개요 + +### 목적 +품목기준관리에서 정의한 메타데이터를 기반으로 품목관리 화면을 동적으로 생성하기 위한 API 시스템 구축 + +### 핵심 요구사항 +1. 품목기준관리 메타데이터 조회 API +2. 동적 필드 구조 기반 품목 CRUD API +3. Multi-tenant 데이터 격리 +4. 필드 타입별 유효성 검증 +5. 검색/필터/정렬 동적 지원 + +### 데이터 흐름 +``` +품목기준관리 (메타데이터 정의) + ↓ 저장 +Laravel DB (pages, sections, fields) + ↓ API 조회 +Next.js 프론트엔드 + ↓ 동적 렌더링 +품목관리 화면 (폼/테이블 자동 생성) +``` + +--- + +## 아키텍처 설계 + +### Service-First 패턴 적용 + +**ItemMetadataService**: +- 메타데이터 조회 로직 +- 캐싱 전략 +- 테넌트별 격리 + +**ItemService**: +- 동적 필드 기반 CRUD +- 유효성 검증 (메타데이터 기반) +- 검색/필터/정렬 + +### Multi-Tenancy + +**테넌트 격리 방식**: +- JWT 토큰에서 `tenant_id` 자동 추출 +- `BelongsToTenant` Trait 적용 +- Global Scope 자동 필터링 + +```php +// ✅ Service에서 컨텍스트 강제 +public function getMetadata(): array { + $this->tenantId(); // 테넌트 ID 필수 확인 + $this->apiUserId(); // API 사용자 ID 확인 + + // 메타데이터 조회 로직... +} +``` + +### 데이터베이스 스키마 + +#### 1. item_master_pages (페이지/탭) +```sql +CREATE TABLE item_master_pages ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + page_name VARCHAR(100) NOT NULL COMMENT '페이지명 (예: 기본정보, 추가정보)', + display_order INT NOT NULL DEFAULT 0 COMMENT '표시 순서', + is_active BOOLEAN NOT NULL DEFAULT TRUE COMMENT '활성화 여부', + created_by BIGINT UNSIGNED COMMENT '생성자 ID', + updated_by BIGINT UNSIGNED COMMENT '수정자 ID', + deleted_by BIGINT UNSIGNED COMMENT '삭제자 ID', + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + UNIQUE KEY uk_tenant_page (tenant_id, page_name, deleted_at), + INDEX idx_tenant_order (tenant_id, display_order), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +) COMMENT='품목 마스터 페이지 (탭) 정의'; +``` + +#### 2. item_master_sections (섹션) +```sql +CREATE TABLE item_master_sections ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + page_id BIGINT UNSIGNED NOT NULL COMMENT '페이지 ID', + section_name VARCHAR(100) NOT NULL COMMENT '섹션명', + display_order INT NOT NULL DEFAULT 0 COMMENT '표시 순서', + is_active BOOLEAN NOT NULL DEFAULT TRUE COMMENT '활성화 여부', + created_by BIGINT UNSIGNED COMMENT '생성자 ID', + updated_by BIGINT UNSIGNED COMMENT '수정자 ID', + deleted_by BIGINT UNSIGNED COMMENT '삭제자 ID', + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_page (tenant_id, page_id), + INDEX idx_display_order (page_id, display_order), + FOREIGN KEY (tenant_id) REFERENCES tenants(id), + FOREIGN KEY (page_id) REFERENCES item_master_pages(id) ON DELETE CASCADE +) COMMENT='품목 마스터 섹션 정의'; +``` + +#### 3. item_master_fields (필드) +```sql +CREATE TABLE item_master_fields ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + section_id BIGINT UNSIGNED NOT NULL COMMENT '섹션 ID', + field_name VARCHAR(100) NOT NULL COMMENT '필드명', + field_label VARCHAR(100) NOT NULL COMMENT '필드 레이블', + field_type ENUM('text', 'number', 'date', 'select', 'textarea', 'checkbox', 'file') NOT NULL COMMENT '필드 타입', + is_required BOOLEAN NOT NULL DEFAULT FALSE COMMENT '필수 입력 여부', + is_searchable BOOLEAN NOT NULL DEFAULT TRUE COMMENT '검색 가능 여부', + is_filterable BOOLEAN NOT NULL DEFAULT TRUE COMMENT '필터 가능 여부', + is_sortable BOOLEAN NOT NULL DEFAULT TRUE COMMENT '정렬 가능 여부', + show_in_list BOOLEAN NOT NULL DEFAULT TRUE COMMENT '목록에 표시 여부', + list_order INT NULL COMMENT '목록 표시 순서', + column_width VARCHAR(20) NULL COMMENT '컬럼 너비 (예: 150px)', + display_order INT NOT NULL DEFAULT 0 COMMENT '표시 순서', + validation_rules JSON NULL COMMENT '유효성 검증 규칙 (JSON)', + default_value VARCHAR(255) NULL COMMENT '기본값', + options JSON NULL COMMENT 'select 옵션 (JSON)', + data_source JSON NULL COMMENT '동적 데이터 소스 (JSON)', + help_text VARCHAR(500) NULL COMMENT '도움말 텍스트', + placeholder VARCHAR(100) NULL COMMENT 'placeholder', + is_active BOOLEAN NOT NULL DEFAULT TRUE COMMENT '활성화 여부', + created_by BIGINT UNSIGNED COMMENT '생성자 ID', + updated_by BIGINT UNSIGNED COMMENT '수정자 ID', + deleted_by BIGINT UNSIGNED COMMENT '삭제자 ID', + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_section (tenant_id, section_id), + INDEX idx_display_order (section_id, display_order), + INDEX idx_searchable (tenant_id, is_searchable), + INDEX idx_list_display (tenant_id, show_in_list, list_order), + FOREIGN KEY (tenant_id) REFERENCES tenants(id), + FOREIGN KEY (section_id) REFERENCES item_master_sections(id) ON DELETE CASCADE +) COMMENT='품목 마스터 필드 정의'; +``` + +#### 4. items (품목 데이터) +```sql +CREATE TABLE items ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + item_code VARCHAR(50) NOT NULL COMMENT '품목코드', + item_name VARCHAR(200) NOT NULL COMMENT '품목명', + dynamic_fields JSON NULL COMMENT '동적 필드 데이터 (JSON)', + is_active BOOLEAN NOT NULL DEFAULT TRUE COMMENT '활성화 여부', + created_by BIGINT UNSIGNED COMMENT '생성자 ID', + updated_by BIGINT UNSIGNED COMMENT '수정자 ID', + deleted_by BIGINT UNSIGNED COMMENT '삭제자 ID', + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + UNIQUE KEY uk_tenant_code (tenant_id, item_code, deleted_at), + INDEX idx_tenant_name (tenant_id, item_name), + INDEX idx_tenant_active (tenant_id, is_active), + FULLTEXT KEY ft_search (item_code, item_name), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +) COMMENT='품목 마스터 데이터' ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; +``` + +### validation_rules JSON 구조 예시 + +```json +{ + "min_length": 5, + "max_length": 20, + "pattern": "^[A-Z0-9-]+$", + "error_message": "영문 대문자, 숫자, 하이픈만 가능", + "min": 0, + "max": 999999, + "decimal_places": 2, + "min_date": "today", + "max_date": "2025-12-31", + "max_size": 5242880, + "allowed_extensions": ["jpg", "png", "pdf"] +} +``` + +### data_source JSON 구조 예시 + +```json +{ + "type": "api", + "endpoint": "/api/v1/master/units", + "value_field": "unit_code", + "label_field": "unit_name" +} +``` + +또는 + +```json +{ + "type": "master_table", + "table": "suppliers", + "value_field": "id", + "label_field": "company_name" +} +``` + +--- + +## API 엔드포인트 명세 + +### 1. 메타데이터 조회 + +#### GET /api/v1/item-master/config + +**목적**: 품목기준관리에서 정의한 화면 구조 메타데이터 조회 + +**인증**: `auth.apikey + auth:sanctum` + +**Request**: +- 없음 (JWT에서 tenant_id 자동 추출) + +**Response** (200 OK): +```json +{ + "success": true, + "message": "message.fetched", + "data": { + "pages": [ + { + "id": 1, + "page_name": "기본정보", + "display_order": 1, + "is_active": true, + "sections": [ + { + "id": 1, + "section_name": "품목코드 정보", + "display_order": 1, + "is_active": true, + "fields": [ + { + "id": 1, + "field_name": "item_code", + "field_label": "품목코드", + "field_type": "text", + "is_required": true, + "is_searchable": true, + "is_filterable": true, + "is_sortable": true, + "show_in_list": true, + "list_order": 1, + "column_width": "150px", + "display_order": 1, + "validation_rules": { + "min_length": 5, + "max_length": 20, + "pattern": "^[A-Z0-9-]+$" + }, + "default_value": null, + "options": null, + "data_source": null, + "help_text": "영문 대문자, 숫자, 하이픈 조합", + "placeholder": "예: ITEM-001" + }, + { + "id": 2, + "field_name": "item_name", + "field_label": "품목명", + "field_type": "text", + "is_required": true, + "show_in_list": true, + "list_order": 2, + "display_order": 2 + }, + { + "id": 3, + "field_name": "unit", + "field_label": "단위", + "field_type": "select", + "is_required": true, + "options": ["EA", "BOX", "KG", "M"], + "default_value": "EA", + "show_in_list": true, + "list_order": 3, + "display_order": 3 + } + ] + } + ] + }, + { + "id": 2, + "page_name": "추가정보", + "display_order": 2, + "is_active": true, + "sections": [...] + } + ], + "bom": { + "enabled": true, + "structure": "single_level" + } + } +} +``` + +**Error Responses**: +- `401 Unauthorized`: 인증 실패 +- `403 Forbidden`: 권한 없음 +- `404 Not Found`: 설정된 메타데이터 없음 + +--- + +### 2. 품목 목록 조회 + +#### GET /api/v1/items + +**목적**: 동적 필드 포함 품목 목록 조회 (페이지네이션) + +**인증**: `auth.apikey + auth:sanctum` + +**Query Parameters**: +```typescript +{ + page?: number; // 페이지 번호 (default: 1) + per_page?: number; // 페이지당 항목 수 (default: 20) + sort_by?: string; // 정렬 필드명 (예: item_code, created_at) + sort_order?: 'asc'|'desc'; // 정렬 순서 (default: desc) + search?: string; // 검색어 (item_code, item_name 검색) + is_active?: boolean; // 활성 상태 필터 + // 동적 필드 필터 (메타데이터 기반) + [field_name]?: string; // 예: unit=EA, category=전자부품 +} +``` + +**Request Example**: +``` +GET /api/v1/items?page=1&per_page=20&sort_by=created_at&sort_order=desc&search=ITEM&unit=EA +``` + +**Response** (200 OK): +```json +{ + "success": true, + "message": "message.fetched", + "data": { + "data": [ + { + "id": 1, + "item_code": "ITEM-001", + "item_name": "제품A", + "is_active": true, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z", + // 동적 필드들 (메타데이터에서 정의된 필드만) + "unit": "EA", + "category": "전자부품", + "spec": "100x100", + "material": "ABS" + } + ], + "pagination": { + "total": 100, + "per_page": 20, + "current_page": 1, + "last_page": 5, + "from": 1, + "to": 20 + } + } +} +``` + +--- + +### 3. 품목 상세 조회 + +#### GET /api/v1/items/{id} + +**목적**: 특정 품목의 모든 필드 데이터 조회 + +**인증**: `auth.apikey + auth:sanctum` + +**Path Parameters**: +- `id` (required): 품목 ID + +**Response** (200 OK): +```json +{ + "success": true, + "message": "message.fetched", + "data": { + "id": 1, + "item_code": "ITEM-001", + "item_name": "제품A", + "is_active": true, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T00:00:00Z", + "created_by": { + "id": 1, + "name": "홍길동" + }, + "updated_by": { + "id": 1, + "name": "홍길동" + }, + // 동적 필드들 (모든 페이지의 모든 필드) + "unit": "EA", + "category": "전자부품", + "spec": "100x100", + "material": "ABS", + "color": "검정", + "weight": 150, + "price": 10000, + // BOM 데이터 (활성화된 경우) + "bom": [ + { + "id": 1, + "child_item_code": "ITEM-002", + "child_item_name": "부품A", + "quantity": 2, + "unit": "EA" + } + ] + } +} +``` + +**Error Responses**: +- `404 Not Found`: 품목이 존재하지 않음 +- `403 Forbidden`: 다른 테넌트의 품목 접근 시도 + +--- + +### 4. 품목 생성 + +#### POST /api/v1/items + +**목적**: 새 품목 생성 (동적 필드 포함) + +**인증**: `auth.apikey + auth:sanctum` + +**Request Body**: +```json +{ + "item_code": "ITEM-001", + "item_name": "제품A", + // 동적 필드들 (메타데이터에 정의된 필드만 허용) + "unit": "EA", + "category": "전자부품", + "spec": "100x100", + "material": "ABS", + "color": "검정", + "weight": 150, + "price": 10000 +} +``` + +**Validation**: +- 메타데이터 기반 자동 검증 +- `is_required=true` 필드 필수 체크 +- `validation_rules`에 따른 검증 (pattern, min, max 등) +- 존재하지 않는 필드는 무시 + +**Response** (201 Created): +```json +{ + "success": true, + "message": "message.created", + "data": { + "id": 1, + "item_code": "ITEM-001", + "item_name": "제품A", + "unit": "EA", + // ... 모든 필드 + "created_at": "2025-01-01T00:00:00Z" + } +} +``` + +**Error Responses**: +- `422 Unprocessable Entity`: 유효성 검증 실패 + ```json + { + "success": false, + "message": "error.validation_failed", + "errors": { + "item_code": ["품목코드는 5자 이상 20자 이하여야 합니다."], + "unit": ["단위는 필수 항목입니다."] + } + } + ``` + +--- + +### 5. 품목 수정 + +#### PUT /api/v1/items/{id} + +**목적**: 기존 품목 수정 (동적 필드 포함) + +**인증**: `auth.apikey + auth:sanctum` + +**Path Parameters**: +- `id` (required): 품목 ID + +**Request Body**: +```json +{ + "item_name": "제품A (수정됨)", + "spec": "120x120", + "price": 12000 +} +``` + +**Validation**: +- 메타데이터 기반 자동 검증 +- 제공된 필드만 업데이트 (부분 업데이트 지원) + +**Response** (200 OK): +```json +{ + "success": true, + "message": "message.updated", + "data": { + "id": 1, + "item_code": "ITEM-001", + "item_name": "제품A (수정됨)", + "spec": "120x120", + "price": 12000, + // ... 모든 필드 + "updated_at": "2025-01-02T00:00:00Z" + } +} +``` + +**Error Responses**: +- `404 Not Found`: 품목이 존재하지 않음 +- `422 Unprocessable Entity`: 유효성 검증 실패 +- `403 Forbidden`: 수정 권한 없음 + +--- + +### 6. 품목 삭제 + +#### DELETE /api/v1/items/{id} + +**목적**: 품목 삭제 (Soft Delete) + +**인증**: `auth.apikey + auth:sanctum` + +**Path Parameters**: +- `id` (required): 품목 ID + +**Response** (200 OK): +```json +{ + "success": true, + "message": "message.deleted", + "data": null +} +``` + +**Error Responses**: +- `404 Not Found`: 품목이 존재하지 않음 +- `403 Forbidden`: 삭제 권한 없음 + +--- + +## 데이터 구조 + +### 메타데이터 캐싱 전략 + +**Redis 캐시 키 패턴**: +``` +item_metadata:{tenant_id} +``` + +**캐시 만료 시간**: 1시간 + +**캐시 무효화 시점**: +- 품목기준관리에서 메타데이터 변경 시 +- 수동 캐시 클리어 API 호출 시 + +```php +// ItemMetadataService.php +public function getMetadata(): array { + $tenantId = $this->tenantId(); + $cacheKey = "item_metadata:{$tenantId}"; + + return Cache::remember($cacheKey, 3600, function() use ($tenantId) { + // DB에서 메타데이터 조회 + return $this->buildMetadataStructure($tenantId); + }); +} +``` + +### 동적 필드 저장 방식 + +**Option 1: JSON 컬럼 (권장)** +```sql +-- items 테이블 +dynamic_fields JSON NULL COMMENT '동적 필드 데이터' + +-- 저장 예시 +{ + "unit": "EA", + "category": "전자부품", + "spec": "100x100", + "material": "ABS", + "color": "검정", + "weight": 150, + "price": 10000 +} +``` + +**장점**: +- 스키마 변경 불필요 +- 메타데이터 변경에 유연 대응 +- JSON 쿼리 지원 (MySQL 5.7+) + +**단점**: +- 인덱스 제한적 +- 복잡한 검색 쿼리 성능 저하 가능 + +**Option 2: EAV 모델 (확장 가능)** +```sql +CREATE TABLE item_field_values ( + id BIGINT UNSIGNED PRIMARY KEY, + tenant_id BIGINT UNSIGNED, + item_id BIGINT UNSIGNED, + field_id BIGINT UNSIGNED, + value TEXT, + FOREIGN KEY (item_id) REFERENCES items(id), + FOREIGN KEY (field_id) REFERENCES item_master_fields(id) +); +``` + +**장점**: +- 정규화된 구조 +- 필드별 인덱스 가능 + +**단점**: +- 복잡한 조인 쿼리 +- 성능 오버헤드 + +**권장**: **Option 1 (JSON 컬럼)** 사용 (Laravel Eloquent JSON Cast 지원) + +--- + +## 구현 가이드 + +### Controller 구현 + +**ItemController.php**: +```php + + $service->getList($request->validated()) + ); + } + + /** + * 품목 상세 조회 + */ + public function show(int $id, ItemService $service) + { + return ApiResponse::handle(fn() => + $service->getById($id) + ); + } + + /** + * 품목 생성 + */ + public function store(StoreItemRequest $request, ItemService $service) + { + return ApiResponse::handle(fn() => + $service->create($request->validated()), + 201 + ); + } + + /** + * 품목 수정 + */ + public function update(int $id, UpdateItemRequest $request, ItemService $service) + { + return ApiResponse::handle(fn() => + $service->update($id, $request->validated()) + ); + } + + /** + * 품목 삭제 + */ + public function destroy(int $id, ItemService $service) + { + return ApiResponse::handle(fn() => + $service->delete($id) + ); + } +} +``` + +### Service 구현 + +**ItemMetadataService.php**: +```php +tenantId(); + $cacheKey = "item_metadata:{$tenantId}"; + + return Cache::remember($cacheKey, 3600, function() { + $pages = ItemMasterPage::with([ + 'sections' => function($query) { + $query->where('is_active', true) + ->orderBy('display_order'); + }, + 'sections.fields' => function($query) { + $query->where('is_active', true) + ->orderBy('display_order'); + } + ]) + ->where('is_active', true) + ->orderBy('display_order') + ->get(); + + return [ + 'pages' => $pages->toArray(), + 'bom' => $this->getBomConfig() + ]; + }); + } + + /** + * 캐시 무효화 + */ + public function clearCache(): void + { + $tenantId = $this->tenantId(); + Cache::forget("item_metadata:{$tenantId}"); + } + + /** + * BOM 설정 조회 + */ + protected function getBomConfig(): array + { + // BOM 설정 조회 로직 + return [ + 'enabled' => true, + 'structure' => 'single_level' + ]; + } +} +``` + +**ItemService.php**: +```php +metadataService = $metadataService; + } + + /** + * 품목 목록 조회 + */ + public function getList(array $params): LengthAwarePaginator + { + $this->tenantId(); + + $query = Item::query(); + + // 검색 + if (!empty($params['search'])) { + $search = $params['search']; + $query->where(function($q) use ($search) { + $q->where('item_code', 'like', "%{$search}%") + ->orWhere('item_name', 'like', "%{$search}%"); + }); + } + + // 활성 상태 필터 + if (isset($params['is_active'])) { + $query->where('is_active', $params['is_active']); + } + + // 동적 필드 필터 (JSON 쿼리) + $metadata = $this->metadataService->getMetadata(); + $filterableFields = $this->getFilterableFields($metadata); + + foreach ($filterableFields as $fieldName) { + if (isset($params[$fieldName])) { + $query->whereJsonContains("dynamic_fields->{$fieldName}", $params[$fieldName]); + } + } + + // 정렬 + $sortBy = $params['sort_by'] ?? 'created_at'; + $sortOrder = $params['sort_order'] ?? 'desc'; + + if (in_array($sortBy, ['item_code', 'item_name', 'created_at', 'updated_at'])) { + $query->orderBy($sortBy, $sortOrder); + } else { + // 동적 필드 정렬 (JSON 경로) + $query->orderBy("dynamic_fields->{$sortBy}", $sortOrder); + } + + $perPage = $params['per_page'] ?? 20; + + return $query->paginate($perPage); + } + + /** + * 품목 상세 조회 + */ + public function getById(int $id): Item + { + $this->tenantId(); + + $item = Item::with(['creator', 'updater'])->findOrFail($id); + + // 동적 필드 병합 + $item->setAttribute('dynamic_fields_decoded', $item->dynamic_fields); + + return $item; + } + + /** + * 품목 생성 + */ + public function create(array $data): Item + { + $tenantId = $this->tenantId(); + $userId = $this->apiUserId(); + + // 메타데이터 기반 유효성 검증 + $this->validateDynamicFields($data); + + // 고정 필드와 동적 필드 분리 + $fixedFields = [ + 'tenant_id' => $tenantId, + 'item_code' => $data['item_code'], + 'item_name' => $data['item_name'], + 'created_by' => $userId, + ]; + + $dynamicFields = $this->extractDynamicFields($data); + + $item = Item::create([ + ...$fixedFields, + 'dynamic_fields' => $dynamicFields + ]); + + return $item; + } + + /** + * 품목 수정 + */ + public function update(int $id, array $data): Item + { + $this->tenantId(); + $userId = $this->apiUserId(); + + $item = Item::findOrFail($id); + + // 메타데이터 기반 유효성 검증 + $this->validateDynamicFields($data); + + // 고정 필드 업데이트 + if (isset($data['item_code'])) { + $item->item_code = $data['item_code']; + } + if (isset($data['item_name'])) { + $item->item_name = $data['item_name']; + } + + // 동적 필드 업데이트 (병합) + $currentDynamicFields = $item->dynamic_fields ?? []; + $newDynamicFields = $this->extractDynamicFields($data); + + $item->dynamic_fields = array_merge($currentDynamicFields, $newDynamicFields); + $item->updated_by = $userId; + $item->save(); + + return $item; + } + + /** + * 품목 삭제 + */ + public function delete(int $id): bool + { + $this->tenantId(); + $userId = $this->apiUserId(); + + $item = Item::findOrFail($id); + $item->deleted_by = $userId; + $item->save(); + + return $item->delete(); + } + + /** + * 동적 필드 유효성 검증 + */ + protected function validateDynamicFields(array $data): void + { + $metadata = $this->metadataService->getMetadata(); + $fields = $this->getAllFields($metadata); + + foreach ($fields as $field) { + $fieldName = $field['field_name']; + $value = $data[$fieldName] ?? null; + + // 필수 필드 체크 + if ($field['is_required'] && empty($value)) { + throw new \Illuminate\Validation\ValidationException( + validator([], []), + response()->json([ + 'errors' => [ + $fieldName => [__("validation.required", ['attribute' => $field['field_label']])] + ] + ], 422) + ); + } + + // 타입별 검증 + if (!empty($value)) { + $this->validateFieldByType($field, $value); + } + } + } + + /** + * 필드 타입별 검증 + */ + protected function validateFieldByType(array $field, $value): void + { + $rules = $field['validation_rules'] ?? []; + + switch ($field['field_type']) { + case 'text': + case 'textarea': + if (isset($rules['min_length']) && strlen($value) < $rules['min_length']) { + throw new \InvalidArgumentException( + "{$field['field_label']}은(는) 최소 {$rules['min_length']}자 이상이어야 합니다." + ); + } + if (isset($rules['max_length']) && strlen($value) > $rules['max_length']) { + throw new \InvalidArgumentException( + "{$field['field_label']}은(는) 최대 {$rules['max_length']}자 이하여야 합니다." + ); + } + if (isset($rules['pattern']) && !preg_match("/{$rules['pattern']}/", $value)) { + $errorMsg = $rules['error_message'] ?? "형식이 올바르지 않습니다."; + throw new \InvalidArgumentException("{$field['field_label']}: {$errorMsg}"); + } + break; + + case 'number': + if (!is_numeric($value)) { + throw new \InvalidArgumentException("{$field['field_label']}은(는) 숫자여야 합니다."); + } + if (isset($rules['min']) && $value < $rules['min']) { + throw new \InvalidArgumentException( + "{$field['field_label']}은(는) {$rules['min']} 이상이어야 합니다." + ); + } + if (isset($rules['max']) && $value > $rules['max']) { + throw new \InvalidArgumentException( + "{$field['field_label']}은(는) {$rules['max']} 이하여야 합니다." + ); + } + break; + + case 'select': + $options = $field['options'] ?? []; + if (!empty($options) && !in_array($value, $options)) { + throw new \InvalidArgumentException( + "{$field['field_label']}의 값이 올바르지 않습니다." + ); + } + break; + } + } + + /** + * 동적 필드 추출 + */ + protected function extractDynamicFields(array $data): array + { + $metadata = $this->metadataService->getMetadata(); + $fields = $this->getAllFields($metadata); + + $dynamicFields = []; + foreach ($fields as $field) { + $fieldName = $field['field_name']; + if (isset($data[$fieldName])) { + $dynamicFields[$fieldName] = $data[$fieldName]; + } + } + + return $dynamicFields; + } + + /** + * 모든 필드 목록 추출 + */ + protected function getAllFields(array $metadata): array + { + $fields = []; + foreach ($metadata['pages'] as $page) { + foreach ($page['sections'] as $section) { + foreach ($section['fields'] as $field) { + $fields[] = $field; + } + } + } + return $fields; + } + + /** + * 필터 가능한 필드 추출 + */ + protected function getFilterableFields(array $metadata): array + { + $fields = $this->getAllFields($metadata); + return array_column( + array_filter($fields, fn($f) => $f['is_filterable']), + 'field_name' + ); + } +} +``` + +### Model 구현 + +**Item.php**: +```php + 'array', + 'is_active' => 'boolean', + ]; + + /** + * 생성자 관계 + */ + public function creator() + { + return $this->belongsTo(User::class, 'created_by'); + } + + /** + * 수정자 관계 + */ + public function updater() + { + return $this->belongsTo(User::class, 'updated_by'); + } +} +``` + +**ItemMasterPage.php**: +```php + 'boolean', + ]; + + /** + * 섹션 관계 + */ + public function sections() + { + return $this->hasMany(ItemMasterSection::class, 'page_id'); + } +} +``` + +**ItemMasterSection.php**, **ItemMasterField.php** 유사하게 구현 + +### FormRequest 구현 + +**IndexItemRequest.php**: +```php + 'integer|min:1', + 'per_page' => 'integer|min:1|max:100', + 'sort_by' => 'string|max:100', + 'sort_order' => 'in:asc,desc', + 'search' => 'string|max:200', + 'is_active' => 'boolean', + ]; + } +} +``` + +**StoreItemRequest.php**: +```php + 'required|string|max:50', + 'item_name' => 'required|string|max:200', + // 동적 필드는 Service에서 검증 + ]; + } +} +``` + +--- + +## Swagger 문서화 + +### ItemApi.php + +```php +; // 탭별 컬럼 설정 + unitOptions: UnitOptionResponse[]; // 단위 옵션 목록 + materialOptions: MaterialOptionResponse[]; // 재질 옵션 목록 + surfaceOptions: SurfaceOptionResponse[]; // 표면처리 옵션 목록 +} +``` + +**중요**: `pages` 응답 시 `sections`와 `fields`를 Nested로 포함해야 함 + +**예시 응답**: +```json +{ + "success": true, + "message": "message.fetched", + "data": { + "pages": [ + { + "id": 1, + "page_name": "기본정보", + "item_type": "FG", + "is_active": true, + "sections": [ + { + "id": 1, + "title": "품목코드 정보", + "type": "fields", + "order_no": 1, + "fields": [ + { + "id": 1, + "field_name": "품목코드", + "field_type": "textbox", + "is_required": true, + "master_field_id": null, + "order_no": 1 + } + ] + } + ] + } + ], + "sectionTemplates": [...], + "masterFields": [...], + "customTabs": [...], + "tabColumns": {...}, + "unitOptions": [...] + } +} +``` + +--- + +### 2.2 페이지 관리 API + +#### `POST /api/v1/item-master/pages` +**목적**: 새 페이지 생성 + +**Request Body**: +```typescript +interface ItemPageRequest { + page_name: string; // 페이지명 (필수) + item_type: 'FG' | 'PT' | 'SM' | 'RM' | 'CS'; // 품목유형 (필수) + absolute_path?: string; // 절대경로 (선택) + is_active?: boolean; // 활성화 여부 (기본: true) +} +``` + +**Response**: `ItemPageResponse` + +--- + +#### `PUT /api/v1/item-master/pages/{id}` +**목적**: 페이지 수정 + +**Path Parameter**: `id` - 페이지 ID + +**Request Body**: `Partial` + +**Response**: `ItemPageResponse` + +--- + +#### `DELETE /api/v1/item-master/pages/{id}` +**목적**: 페이지 삭제 (Soft Delete) + +**Path Parameter**: `id` - 페이지 ID + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.3 섹션 관리 API + +#### `POST /api/v1/item-master/pages/{pageId}/sections` +**목적**: 페이지에 새 섹션 추가 + +**Path Parameter**: `pageId` - 페이지 ID + +**Request Body**: +```typescript +interface ItemSectionRequest { + title: string; // 섹션명 (필수) + type: 'fields' | 'bom'; // 섹션 타입 (필수) + template_id?: number; // 템플릿 ID (선택) - 템플릿에서 생성 시 +} +``` + +**중요 - 템플릿 적용 로직**: +- `template_id`가 전달되면 해당 템플릿의 필드들을 복사하여 새 섹션에 추가 +- 템플릿의 필드들은 `master_field_id` 연결 관계도 복사 + +**Response**: `ItemSectionResponse` (생성된 섹션 + 필드 포함) + +--- + +#### `PUT /api/v1/item-master/sections/{id}` +**목적**: 섹션 수정 (제목 변경 등) + +**Path Parameter**: `id` - 섹션 ID + +**Request Body**: `Partial` + +**Response**: `ItemSectionResponse` + +--- + +#### `DELETE /api/v1/item-master/sections/{id}` +**목적**: 섹션 삭제 + +**Path Parameter**: `id` - 섹션 ID + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +#### `PUT /api/v1/item-master/pages/{pageId}/sections/reorder` +**목적**: 섹션 순서 변경 (드래그앤드롭) + +**Path Parameter**: `pageId` - 페이지 ID + +**Request Body**: +```typescript +interface SectionReorderRequest { + section_orders: Array<{ + id: number; // 섹션 ID + order_no: number; // 새 순서 + }>; +} +``` + +**Response**: `ItemSectionResponse[]` + +--- + +### 2.4 필드 관리 API + +#### `POST /api/v1/item-master/sections/{sectionId}/fields` +**목적**: 섹션에 새 필드 추가 + +**Path Parameter**: `sectionId` - 섹션 ID + +**Request Body**: +```typescript +interface ItemFieldRequest { + field_name: string; // 필드명 (필수) + field_type: 'textbox' | 'number' | 'dropdown' | 'checkbox' | 'date' | 'textarea'; // 필드 타입 (필수) + + // 마스터 필드 연결 (핵심 기능) + master_field_id?: number; // 마스터 필드 ID (마스터에서 선택한 경우) + + // 선택 속성 + is_required?: boolean; + placeholder?: string; + default_value?: string; + options?: Array<{ label: string; value: string }>; // dropdown 옵션 + validation_rules?: Record; + properties?: Record; + + // 조건부 표시 설정 (신규 기능) + display_condition?: { + field_key: string; // 조건 필드 키 + expected_value: string; // 예상 값 + target_field_ids?: string[]; // 표시할 필드 ID 목록 + target_section_ids?: string[]; // 표시할 섹션 ID 목록 + }[]; +} +``` + +**중요 - master_field_id 처리**: +- 프론트엔드에서 "마스터 항목 선택" 모드로 필드 추가 시 `master_field_id` 전달 +- 백엔드에서 해당 마스터 필드의 속성을 참조하여 기본값 설정 +- 마스터 필드가 수정되면 연결된 필드도 동기화 필요 (옵션) + +**Response**: `ItemFieldResponse` + +--- + +#### `PUT /api/v1/item-master/fields/{id}` +**목적**: 필드 수정 + +**Path Parameter**: `id` - 필드 ID + +**Request Body**: `Partial` + +**Response**: `ItemFieldResponse` + +--- + +#### `DELETE /api/v1/item-master/fields/{id}` +**목적**: 필드 삭제 + +**Path Parameter**: `id` - 필드 ID + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +#### `PUT /api/v1/item-master/sections/{sectionId}/fields/reorder` +**목적**: 필드 순서 변경 (드래그앤드롭) + +**Path Parameter**: `sectionId` - 섹션 ID + +**Request Body**: +```typescript +interface FieldReorderRequest { + field_orders: Array<{ + id: number; // 필드 ID + order_no: number; // 새 순서 + }>; +} +``` + +**Response**: `ItemFieldResponse[]` + +--- + +### 2.5 섹션 템플릿 API + +#### `GET /api/v1/item-master/section-templates` +**목적**: 섹션 템플릿 목록 조회 + +**Response**: `SectionTemplateResponse[]` + +--- + +#### `POST /api/v1/item-master/section-templates` +**목적**: 새 섹션 템플릿 생성 + +**Request Body**: +```typescript +interface SectionTemplateRequest { + title: string; // 템플릿명 (필수) + type: 'fields' | 'bom'; // 타입 (필수) + description?: string; // 설명 (선택) + is_default?: boolean; // 기본 템플릿 여부 (선택) + + // 템플릿에 포함될 필드들 + fields?: Array<{ + field_name: string; + field_type: string; + master_field_id?: number; + is_required?: boolean; + options?: Array<{ label: string; value: string }>; + properties?: Record; + }>; +} +``` + +**Response**: `SectionTemplateResponse` + +--- + +#### `PUT /api/v1/item-master/section-templates/{id}` +**목적**: 섹션 템플릿 수정 + +**Response**: `SectionTemplateResponse` + +--- + +#### `DELETE /api/v1/item-master/section-templates/{id}` +**목적**: 섹션 템플릿 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.6 마스터 필드 API + +#### `GET /api/v1/item-master/master-fields` +**목적**: 마스터 필드 목록 조회 + +**Response**: `MasterFieldResponse[]` + +--- + +#### `POST /api/v1/item-master/master-fields` +**목적**: 새 마스터 필드 생성 + +**Request Body**: +```typescript +interface MasterFieldRequest { + field_name: string; // 필드명 (필수) + field_type: 'textbox' | 'number' | 'dropdown' | 'checkbox' | 'date' | 'textarea'; // 필드 타입 (필수) + category?: string; // 카테고리 (선택) - 예: "기본정보", "스펙정보" + description?: string; // 설명 (선택) + is_common?: boolean; // 공통 항목 여부 (선택) + default_value?: string; + options?: Array<{ label: string; value: string }>; + validation_rules?: Record; + properties?: Record; +} +``` + +**Response**: `MasterFieldResponse` + +--- + +#### `PUT /api/v1/item-master/master-fields/{id}` +**목적**: 마스터 필드 수정 + +**Response**: `MasterFieldResponse` + +--- + +#### `DELETE /api/v1/item-master/master-fields/{id}` +**목적**: 마스터 필드 삭제 + +**주의**: 해당 마스터 필드를 참조하는 필드(`master_field_id`)가 있을 경우 처리 방안 필요 +- 옵션 1: 삭제 불가 (참조 무결성) +- 옵션 2: 참조 해제 후 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.7 BOM 관리 API + +#### `POST /api/v1/item-master/sections/{sectionId}/bom-items` +**목적**: BOM 항목 추가 + +**Request Body**: +```typescript +interface BomItemRequest { + item_code?: string; + item_name: string; // 필수 + quantity: number; // 필수 + unit?: string; + unit_price?: number; + total_price?: number; + spec?: string; + note?: string; +} +``` + +**Response**: `BomItemResponse` + +--- + +#### `PUT /api/v1/item-master/bom-items/{id}` +**목적**: BOM 항목 수정 + +**Response**: `BomItemResponse` + +--- + +#### `DELETE /api/v1/item-master/bom-items/{id}` +**목적**: BOM 항목 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.8 커스텀 탭 API + +#### `GET /api/v1/item-master/custom-tabs` +**목적**: 커스텀 탭 목록 조회 + +**Response**: `CustomTabResponse[]` + +--- + +#### `POST /api/v1/item-master/custom-tabs` +**목적**: 새 커스텀 탭 생성 + +**Request Body**: +```typescript +interface CustomTabRequest { + label: string; // 탭 레이블 (필수) + icon?: string; // 아이콘 (선택) + is_default?: boolean; // 기본 탭 여부 (선택) +} +``` + +**Response**: `CustomTabResponse` + +--- + +#### `PUT /api/v1/item-master/custom-tabs/{id}` +**목적**: 커스텀 탭 수정 + +**Response**: `CustomTabResponse` + +--- + +#### `DELETE /api/v1/item-master/custom-tabs/{id}` +**목적**: 커스텀 탭 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +#### `PUT /api/v1/item-master/custom-tabs/reorder` +**목적**: 탭 순서 변경 + +**Request Body**: +```typescript +interface TabReorderRequest { + tab_orders: Array<{ + id: number; + order_no: number; + }>; +} +``` + +**Response**: `{ success: true }` + +--- + +#### `PUT /api/v1/item-master/custom-tabs/{id}/columns` +**목적**: 탭별 컬럼 설정 업데이트 + +**Request Body**: +```typescript +interface TabColumnUpdateRequest { + columns: Array<{ + key: string; + label: string; + visible: boolean; + order: number; + }>; +} +``` + +**Response**: `TabColumnResponse[]` + +--- + +### 2.9 단위 옵션 API + +#### `GET /api/v1/item-master/unit-options` +**목적**: 단위 옵션 목록 조회 + +**Response**: `UnitOptionResponse[]` + +--- + +#### `POST /api/v1/item-master/unit-options` +**목적**: 새 단위 옵션 추가 + +**Request Body**: +```typescript +interface UnitOptionRequest { + label: string; // 표시명 (예: "개") + value: string; // 값 (예: "EA") +} +``` + +**Response**: `UnitOptionResponse` + +--- + +#### `DELETE /api/v1/item-master/unit-options/{id}` +**목적**: 단위 옵션 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.10 재질 옵션 API + +#### `GET /api/v1/item-master/material-options` +**목적**: 재질 옵션 목록 조회 + +**Response**: `MaterialOptionResponse[]` + +```typescript +interface MaterialOptionResponse { + id: number; + tenant_id: number; + label: string; // 표시명 (예: "스테인리스") + value: string; // 값 (예: "SUS") + properties?: { // 추가 속성 (선택) + columns?: Array<{ // 멀티 컬럼 설정 + key: string; + name: string; + value: string; + }>; + }; + created_by: number | null; + created_at: string; + updated_at: string; +} +``` + +--- + +#### `POST /api/v1/item-master/material-options` +**목적**: 새 재질 옵션 추가 + +**Request Body**: +```typescript +interface MaterialOptionRequest { + label: string; // 표시명 (필수) + value: string; // 값 (필수) + properties?: { // 추가 속성 (선택) + columns?: Array<{ + key: string; + name: string; + value: string; + }>; + }; +} +``` + +**Response**: `MaterialOptionResponse` + +--- + +#### `PUT /api/v1/item-master/material-options/{id}` +**목적**: 재질 옵션 수정 + +**Response**: `MaterialOptionResponse` + +--- + +#### `DELETE /api/v1/item-master/material-options/{id}` +**목적**: 재질 옵션 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +### 2.11 표면처리 옵션 API + +#### `GET /api/v1/item-master/surface-options` +**목적**: 표면처리 옵션 목록 조회 + +**Response**: `SurfaceOptionResponse[]` + +```typescript +interface SurfaceOptionResponse { + id: number; + tenant_id: number; + label: string; // 표시명 (예: "아노다이징") + value: string; // 값 (예: "ANODIZING") + properties?: { // 추가 속성 (선택) + columns?: Array<{ + key: string; + name: string; + value: string; + }>; + }; + created_by: number | null; + created_at: string; + updated_at: string; +} +``` + +--- + +#### `POST /api/v1/item-master/surface-options` +**목적**: 새 표면처리 옵션 추가 + +**Request Body**: +```typescript +interface SurfaceOptionRequest { + label: string; // 표시명 (필수) + value: string; // 값 (필수) + properties?: { // 추가 속성 (선택) + columns?: Array<{ + key: string; + name: string; + value: string; + }>; + }; +} +``` + +**Response**: `SurfaceOptionResponse` + +--- + +#### `PUT /api/v1/item-master/surface-options/{id}` +**목적**: 표면처리 옵션 수정 + +**Response**: `SurfaceOptionResponse` + +--- + +#### `DELETE /api/v1/item-master/surface-options/{id}` +**목적**: 표면처리 옵션 삭제 + +**Response**: `{ success: true, message: "message.deleted" }` + +--- + +## 3. 데이터베이스 스키마 제안 + +### 3.1 item_master_pages +```sql +CREATE TABLE item_master_pages ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + page_name VARCHAR(100) NOT NULL, + item_type ENUM('FG', 'PT', 'SM', 'RM', 'CS') NOT NULL, + absolute_path VARCHAR(500) NULL, + order_no INT NOT NULL DEFAULT 0, + is_active BOOLEAN NOT NULL DEFAULT TRUE, + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant (tenant_id), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +); +``` + +### 3.2 item_master_sections +```sql +CREATE TABLE item_master_sections ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + page_id BIGINT UNSIGNED NOT NULL, + title VARCHAR(100) NOT NULL, + type ENUM('fields', 'bom') NOT NULL DEFAULT 'fields', + order_no INT NOT NULL DEFAULT 0, + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_page (tenant_id, page_id), + FOREIGN KEY (tenant_id) REFERENCES tenants(id), + FOREIGN KEY (page_id) REFERENCES item_master_pages(id) ON DELETE CASCADE +); +``` + +### 3.3 item_master_fields +```sql +CREATE TABLE item_master_fields ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + section_id BIGINT UNSIGNED NOT NULL, + master_field_id BIGINT UNSIGNED NULL, -- 마스터 필드 참조 + field_name VARCHAR(100) NOT NULL, + field_type ENUM('textbox', 'number', 'dropdown', 'checkbox', 'date', 'textarea') NOT NULL, + order_no INT NOT NULL DEFAULT 0, + is_required BOOLEAN NOT NULL DEFAULT FALSE, + placeholder VARCHAR(200) NULL, + default_value VARCHAR(500) NULL, + display_condition JSON NULL, -- 조건부 표시 설정 + validation_rules JSON NULL, + options JSON NULL, -- dropdown 옵션 + properties JSON NULL, -- 추가 속성 (컬럼 설정 등) + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_section (tenant_id, section_id), + INDEX idx_master_field (master_field_id), + FOREIGN KEY (tenant_id) REFERENCES tenants(id), + FOREIGN KEY (section_id) REFERENCES item_master_sections(id) ON DELETE CASCADE, + FOREIGN KEY (master_field_id) REFERENCES item_master_master_fields(id) ON DELETE SET NULL +); +``` + +### 3.4 item_master_master_fields (마스터 필드) +```sql +CREATE TABLE item_master_master_fields ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + field_name VARCHAR(100) NOT NULL, + field_type ENUM('textbox', 'number', 'dropdown', 'checkbox', 'date', 'textarea') NOT NULL, + category VARCHAR(50) NULL, + description TEXT NULL, + is_common BOOLEAN NOT NULL DEFAULT FALSE, + default_value VARCHAR(500) NULL, + options JSON NULL, + validation_rules JSON NULL, + properties JSON NULL, + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant (tenant_id), + INDEX idx_category (tenant_id, category), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +); +``` + +### 3.5 item_master_section_templates (섹션 템플릿) +```sql +CREATE TABLE item_master_section_templates ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + title VARCHAR(100) NOT NULL, + type ENUM('fields', 'bom') NOT NULL DEFAULT 'fields', + description TEXT NULL, + is_default BOOLEAN NOT NULL DEFAULT FALSE, + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant (tenant_id), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +); +``` + +### 3.6 item_master_template_fields (템플릿 필드) +```sql +CREATE TABLE item_master_template_fields ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + template_id BIGINT UNSIGNED NOT NULL, + master_field_id BIGINT UNSIGNED NULL, + field_name VARCHAR(100) NOT NULL, + field_type ENUM('textbox', 'number', 'dropdown', 'checkbox', 'date', 'textarea') NOT NULL, + order_no INT NOT NULL DEFAULT 0, + is_required BOOLEAN NOT NULL DEFAULT FALSE, + placeholder VARCHAR(200) NULL, + default_value VARCHAR(500) NULL, + options JSON NULL, + properties JSON NULL, + created_at TIMESTAMP NULL, + updated_at TIMESTAMP NULL, + + INDEX idx_template (template_id), + FOREIGN KEY (tenant_id) REFERENCES tenants(id), + FOREIGN KEY (template_id) REFERENCES item_master_section_templates(id) ON DELETE CASCADE, + FOREIGN KEY (master_field_id) REFERENCES item_master_master_fields(id) ON DELETE SET NULL +); +``` + +--- + +## 4. 핵심 비즈니스 로직 + +### 4.1 마스터 필드 연결 (`master_field_id`) + +**시나리오**: 사용자가 필드 추가 시 "마스터 항목 선택" 모드로 추가 + +**프론트엔드 동작**: +1. 마스터 필드 목록에서 선택 +2. 선택된 마스터 필드의 속성을 폼에 자동 채움 +3. 저장 시 `master_field_id` 포함하여 전송 + +**백엔드 처리**: +```php +// ItemFieldService.php +public function create(int $sectionId, array $data): ItemField +{ + // master_field_id가 있으면 마스터 필드에서 기본값 가져오기 + if (!empty($data['master_field_id'])) { + $masterField = MasterField::findOrFail($data['master_field_id']); + + // 마스터 필드의 속성을 기본값으로 사용 (명시적 값이 없는 경우) + $data = array_merge([ + 'field_type' => $masterField->field_type, + 'options' => $masterField->options, + 'validation_rules' => $masterField->validation_rules, + 'properties' => $masterField->properties, + ], $data); + } + + return ItemField::create($data); +} +``` + +### 4.2 섹션 템플릿 적용 + +**시나리오**: 사용자가 섹션 추가 시 "템플릿에서 선택" 모드로 추가 + +**프론트엔드 동작**: +1. 템플릿 목록에서 선택 +2. 선택된 템플릿 정보로 섹션 생성 요청 +3. `template_id` 포함하여 전송 + +**백엔드 처리**: +```php +// ItemSectionService.php +public function create(int $pageId, array $data): ItemSection +{ + $section = ItemSection::create([ + 'page_id' => $pageId, + 'title' => $data['title'], + 'type' => $data['type'], + ]); + + // template_id가 있으면 템플릿의 필드들을 복사 + if (!empty($data['template_id'])) { + $templateFields = TemplateField::where('template_id', $data['template_id']) + ->orderBy('order_no') + ->get(); + + foreach ($templateFields as $index => $tf) { + ItemField::create([ + 'section_id' => $section->id, + 'master_field_id' => $tf->master_field_id, // 마스터 연결 유지 + 'field_name' => $tf->field_name, + 'field_type' => $tf->field_type, + 'order_no' => $index, + 'is_required' => $tf->is_required, + 'options' => $tf->options, + 'properties' => $tf->properties, + ]); + } + } + + return $section->load('fields'); +} +``` + +### 4.3 조건부 표시 설정 + +**JSON 구조**: +```json +{ + "display_condition": [ + { + "field_key": "item_type", + "expected_value": "FG", + "target_field_ids": ["5", "6", "7"] + }, + { + "field_key": "item_type", + "expected_value": "PT", + "target_section_ids": ["3"] + } + ] +} +``` + +**활용**: 프론트엔드에서 품목 데이터 입력 시 해당 조건에 따라 필드/섹션을 동적으로 표시/숨김 + +--- + +## 5. 우선순위 + +### Phase 1 (필수 - 즉시) +1. `GET /api/v1/item-master/init` - 초기화 API +2. 페이지 CRUD API +3. 섹션 CRUD API (순서변경 포함) +4. 필드 CRUD API (순서변경 포함, `master_field_id` 지원) + +### Phase 2 (중요 - 1주 내) +5. 마스터 필드 CRUD API +6. 섹션 템플릿 CRUD API +7. 템플릿 필드 관리 + +### Phase 3 (선택 - 2주 내) +8. BOM 항목 관리 API +9. 커스텀 탭 API +10. 단위 옵션 API + +--- + +## 6. 참고 사항 + +### 6.1 프론트엔드 코드 위치 +- API 클라이언트: `src/lib/api/item-master.ts` +- 타입 정의: `src/types/item-master-api.ts` +- 메인 컴포넌트: `src/components/items/ItemMasterDataManagement.tsx` + +### 6.2 기존 API 문서 +- `claudedocs/[API-2025-11-24] item-management-dynamic-api-spec.md` - 품목관리 동적 화면 API + +### 6.3 Multi-Tenancy +- 모든 테이블에 `tenant_id` 컬럼 필수 +- JWT에서 tenant_id 자동 추출 +- `BelongsToTenant` Trait 적용 필요 + +### 6.4 에러 응답 형식 +```json +{ + "success": false, + "message": "error.validation_failed", + "errors": { + "field_name": ["필드명은 필수입니다."], + "field_type": ["유효하지 않은 필드 타입입니다."] + } +} +``` + +--- + +## 7. 연락처 + +질문이나 협의 사항이 있으면 언제든 연락 바랍니다. + +**프론트엔드 담당**: [담당자명] +**작성일**: 2025-11-25 \ No newline at end of file diff --git a/claudedocs/[API-REQUEST-2025-11-25] section-template-fields-api.md b/claudedocs/[API-REQUEST-2025-11-25] section-template-fields-api.md new file mode 100644 index 00000000..493dd79e --- /dev/null +++ b/claudedocs/[API-REQUEST-2025-11-25] section-template-fields-api.md @@ -0,0 +1,588 @@ +# 품목기준관리 API 추가 요청 - 섹션 템플릿 하위 데이터 + +**요청일**: 2025-11-25 +**버전**: v1.1 +**작성자**: 프론트엔드 개발팀 +**수신**: 백엔드 개발팀 +**긴급도**: 🔴 높음 + +--- + +## 📋 목차 + +1. [요청 배경](#1-요청-배경) +2. [데이터베이스 테이블 추가](#2-데이터베이스-테이블-추가) +3. [API 엔드포인트 추가](#3-api-엔드포인트-추가) +4. [init API 응답 수정](#4-init-api-응답-수정) +5. [구현 우선순위](#5-구현-우선순위) + +--- + +## 1. 요청 배경 + +### 1.1 문제 상황 +- 섹션탭 > 일반 섹션에 항목(필드) 추가 후 **새로고침 시 데이터 사라짐** +- 섹션탭 > 모듈 섹션(BOM)에 BOM 품목 추가 후 **새로고침 시 데이터 사라짐** +- 원인: 섹션 템플릿 하위 데이터를 저장/조회하는 API 없음 + +### 1.2 현재 상태 비교 + +| 구분 | 계층구조 (정상) | 섹션 템플릿 (문제) | +|------|----------------|-------------------| +| 섹션/템플릿 CRUD | ✅ 있음 | ✅ 있음 | +| 필드 CRUD | ✅ `/sections/{id}/fields` | ❌ **없음** | +| BOM 품목 CRUD | ✅ `/sections/{id}/bom-items` | ❌ **없음** | +| init 응답에 중첩 포함 | ✅ `fields`, `bomItems` 포함 | ❌ **미포함** | + +### 1.3 요청 내용 +1. 섹션 템플릿 필드 테이블 및 CRUD API 추가 +2. 섹션 템플릿 BOM 품목 테이블 및 CRUD API 추가 +3. init API 응답에 섹션 템플릿 하위 데이터 중첩 포함 +4. **🔴 [추가] 계층구조 섹션 ↔ 섹션 템플릿 데이터 동기화** + +--- + +## 2. 데이터베이스 테이블 추가 + +### 2.0 section_templates 테이블 수정 (데이터 동기화용) + +**요구사항**: 계층구조에서 생성한 섹션과 섹션탭의 템플릿이 **동일한 데이터**로 연동되어야 함 + +**현재 문제**: +``` +계층구조 섹션 생성 시: +├── item_sections 테이블에 저장 (id: 1) +└── section_templates 테이블에 저장 (id: 1) + → 두 개의 별도 데이터! 연결 없음! +``` + +**해결 방안**: `section_templates`에 `section_id` 컬럼 추가 + +```sql +ALTER TABLE section_templates +ADD COLUMN section_id BIGINT UNSIGNED NULL COMMENT '연결된 계층구조 섹션 ID (동기화용)' AFTER tenant_id, +ADD INDEX idx_section_id (section_id), +ADD FOREIGN KEY (section_id) REFERENCES item_sections(id) ON DELETE SET NULL; +``` + +**동기화 동작**: +| 액션 | 동작 | +|------|------| +| 계층구조에서 섹션 생성 | `item_sections` + `section_templates` 생성, `section_id`로 연결 | +| 계층구조에서 섹션 수정 | `item_sections` 수정 → 연결된 `section_templates`도 수정 | +| 계층구조에서 섹션 삭제 | `item_sections` 삭제 → 연결된 `section_templates`의 `section_id` = NULL | +| 섹션탭에서 템플릿 수정 | `section_templates` 수정 → 연결된 `item_sections`도 수정 | +| 섹션탭에서 템플릿 삭제 | `section_templates` 삭제 → 연결된 `item_sections`는 유지 | + +**init API 응답 수정** (section_id 포함): +```json +{ + "sectionTemplates": [ + { + "id": 1, + "section_id": 5, // 연결된 계층구조 섹션 ID (없으면 null) + "title": "일반 섹션", + "type": "fields", + ... + } + ] +} +``` + +--- + +### 2.1 section_template_fields (섹션 템플릿 필드) + +**참고**: 기존 `item_fields` 테이블 구조와 유사하게 설계 + +```sql +CREATE TABLE section_template_fields ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + template_id BIGINT UNSIGNED NOT NULL COMMENT '섹션 템플릿 ID', + field_name VARCHAR(255) NOT NULL COMMENT '필드명', + field_key VARCHAR(100) NOT NULL COMMENT '필드 키 (영문)', + field_type ENUM('textbox', 'number', 'dropdown', 'checkbox', 'date', 'textarea') NOT NULL COMMENT '필드 타입', + order_no INT NOT NULL DEFAULT 0 COMMENT '정렬 순서', + is_required TINYINT(1) DEFAULT 0 COMMENT '필수 여부', + options JSON NULL COMMENT '드롭다운 옵션 ["옵션1", "옵션2"]', + multi_column TINYINT(1) DEFAULT 0 COMMENT '다중 컬럼 여부', + column_count INT NULL COMMENT '컬럼 수', + column_names JSON NULL COMMENT '컬럼명 목록 ["컬럼1", "컬럼2"]', + description TEXT NULL COMMENT '설명', + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_template (tenant_id, template_id), + INDEX idx_order (template_id, order_no), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE, + FOREIGN KEY (template_id) REFERENCES section_templates(id) ON DELETE CASCADE +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='섹션 템플릿 필드'; +``` + +### 2.2 section_template_bom_items (섹션 템플릿 BOM 품목) + +**참고**: 기존 `item_bom_items` 테이블 구조와 유사하게 설계 + +```sql +CREATE TABLE section_template_bom_items ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL COMMENT '테넌트 ID', + template_id BIGINT UNSIGNED NOT NULL COMMENT '섹션 템플릿 ID', + item_code VARCHAR(100) NULL COMMENT '품목 코드', + item_name VARCHAR(255) NOT NULL COMMENT '품목명', + quantity DECIMAL(15, 4) NOT NULL DEFAULT 0 COMMENT '수량', + unit VARCHAR(50) NULL COMMENT '단위', + unit_price DECIMAL(15, 2) NULL COMMENT '단가', + total_price DECIMAL(15, 2) NULL COMMENT '총액', + spec TEXT NULL COMMENT '규격/사양', + note TEXT NULL COMMENT '비고', + order_no INT NOT NULL DEFAULT 0 COMMENT '정렬 순서', + created_by BIGINT UNSIGNED NULL, + updated_by BIGINT UNSIGNED NULL, + deleted_by BIGINT UNSIGNED NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + deleted_at TIMESTAMP NULL, + + INDEX idx_tenant_template (tenant_id, template_id), + INDEX idx_order (template_id, order_no), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE, + FOREIGN KEY (template_id) REFERENCES section_templates(id) ON DELETE CASCADE +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='섹션 템플릿 BOM 품목'; +``` + +--- + +## 3. API 엔드포인트 추가 + +### 3.1 섹션 템플릿 필드 관리 (우선순위 1) + +#### `POST /v1/item-master/section-templates/{templateId}/fields` +**목적**: 템플릿 필드 생성 + +**Request Body**: +```json +{ + "field_name": "품목코드", + "field_key": "item_code", + "field_type": "textbox", + "is_required": true, + "options": null, + "multi_column": false, + "column_count": null, + "column_names": null, + "description": "품목 고유 코드" +} +``` + +**Validation**: +- `field_name`: required, string, max:255 +- `field_key`: required, string, max:100, alpha_dash +- `field_type`: required, in:textbox,number,dropdown,checkbox,date,textarea +- `is_required`: boolean +- `options`: nullable, array (dropdown 타입일 경우) +- `multi_column`: boolean +- `column_count`: nullable, integer, min:2, max:10 +- `column_names`: nullable, array +- `description`: nullable, string + +**Response**: +```json +{ + "success": true, + "message": "message.created", + "data": { + "id": 1, + "template_id": 1, + "field_name": "품목코드", + "field_key": "item_code", + "field_type": "textbox", + "order_no": 0, + "is_required": true, + "options": null, + "multi_column": false, + "column_count": null, + "column_names": null, + "description": "품목 고유 코드", + "created_at": "2025-11-25T10:00:00.000000Z", + "updated_at": "2025-11-25T10:00:00.000000Z" + } +} +``` + +**참고**: +- `order_no`는 자동 계산 (해당 템플릿의 마지막 필드 order + 1) + +--- + +#### `PUT /v1/item-master/section-templates/{templateId}/fields/{fieldId}` +**목적**: 템플릿 필드 수정 + +**Request Body**: +```json +{ + "field_name": "품목코드 (수정)", + "field_type": "dropdown", + "options": ["옵션1", "옵션2"], + "is_required": false +} +``` + +**Validation**: POST와 동일 (모든 필드 optional) + +**Response**: 수정된 필드 정보 반환 + +--- + +#### `DELETE /v1/item-master/section-templates/{templateId}/fields/{fieldId}` +**목적**: 템플릿 필드 삭제 (Soft Delete) + +**Request**: 없음 + +**Response**: +```json +{ + "success": true, + "message": "message.deleted" +} +``` + +--- + +#### `PUT /v1/item-master/section-templates/{templateId}/fields/reorder` +**목적**: 템플릿 필드 순서 변경 + +**Request Body**: +```json +{ + "field_orders": [ + { "id": 3, "order_no": 0 }, + { "id": 1, "order_no": 1 }, + { "id": 2, "order_no": 2 } + ] +} +``` + +**Validation**: +- `field_orders`: required, array +- `field_orders.*.id`: required, exists:section_template_fields,id +- `field_orders.*.order_no`: required, integer, min:0 + +**Response**: +```json +{ + "success": true, + "message": "message.updated", + "data": [ + { "id": 3, "order_no": 0 }, + { "id": 1, "order_no": 1 }, + { "id": 2, "order_no": 2 } + ] +} +``` + +--- + +### 3.2 섹션 템플릿 BOM 품목 관리 (우선순위 2) + +#### `POST /v1/item-master/section-templates/{templateId}/bom-items` +**목적**: 템플릿 BOM 품목 생성 + +**Request Body**: +```json +{ + "item_code": "PART-001", + "item_name": "부품 A", + "quantity": 2, + "unit": "EA", + "unit_price": 15000, + "spec": "100x50x20", + "note": "필수 부품" +} +``` + +**Validation**: +- `item_code`: nullable, string, max:100 +- `item_name`: required, string, max:255 +- `quantity`: required, numeric, min:0 +- `unit`: nullable, string, max:50 +- `unit_price`: nullable, numeric, min:0 +- `spec`: nullable, string +- `note`: nullable, string + +**Response**: +```json +{ + "success": true, + "message": "message.created", + "data": { + "id": 1, + "template_id": 2, + "item_code": "PART-001", + "item_name": "부품 A", + "quantity": 2, + "unit": "EA", + "unit_price": 15000, + "total_price": 30000, + "spec": "100x50x20", + "note": "필수 부품", + "order_no": 0, + "created_at": "2025-11-25T10:00:00.000000Z", + "updated_at": "2025-11-25T10:00:00.000000Z" + } +} +``` + +**참고**: +- `total_price`는 서버에서 자동 계산 (`quantity * unit_price`) +- `order_no`는 자동 계산 (해당 템플릿의 마지막 BOM 품목 order + 1) + +--- + +#### `PUT /v1/item-master/section-templates/{templateId}/bom-items/{itemId}` +**목적**: 템플릿 BOM 품목 수정 + +**Request Body**: +```json +{ + "item_name": "부품 A (수정)", + "quantity": 3, + "unit_price": 12000 +} +``` + +**Validation**: POST와 동일 (모든 필드 optional) + +**Response**: 수정된 BOM 품목 정보 반환 + +--- + +#### `DELETE /v1/item-master/section-templates/{templateId}/bom-items/{itemId}` +**목적**: 템플릿 BOM 품목 삭제 (Soft Delete) + +**Request**: 없음 + +**Response**: +```json +{ + "success": true, + "message": "message.deleted" +} +``` + +--- + +#### `PUT /v1/item-master/section-templates/{templateId}/bom-items/reorder` +**목적**: 템플릿 BOM 품목 순서 변경 + +**Request Body**: +```json +{ + "item_orders": [ + { "id": 3, "order_no": 0 }, + { "id": 1, "order_no": 1 }, + { "id": 2, "order_no": 2 } + ] +} +``` + +**Validation**: +- `item_orders`: required, array +- `item_orders.*.id`: required, exists:section_template_bom_items,id +- `item_orders.*.order_no`: required, integer, min:0 + +**Response**: +```json +{ + "success": true, + "message": "message.updated", + "data": [...] +} +``` + +--- + +## 4. init API 응답 수정 + +### 4.1 현재 응답 (문제) + +```json +{ + "success": true, + "data": { + "sectionTemplates": [ + { + "id": 1, + "title": "일반 섹션", + "type": "fields", + "description": null, + "is_default": false + }, + { + "id": 2, + "title": "BOM 섹션", + "type": "bom", + "description": null, + "is_default": false + } + ] + } +} +``` + +### 4.2 수정 요청 + +`sectionTemplates`에 하위 데이터 중첩 포함: + +```json +{ + "success": true, + "data": { + "sectionTemplates": [ + { + "id": 1, + "title": "일반 섹션", + "type": "fields", + "description": null, + "is_default": false, + "fields": [ + { + "id": 1, + "field_name": "품목코드", + "field_key": "item_code", + "field_type": "textbox", + "order_no": 0, + "is_required": true, + "options": null, + "multi_column": false, + "column_count": null, + "column_names": null, + "description": "품목 고유 코드" + } + ] + }, + { + "id": 2, + "title": "BOM 섹션", + "type": "bom", + "description": null, + "is_default": false, + "bomItems": [ + { + "id": 1, + "item_code": "PART-001", + "item_name": "부품 A", + "quantity": 2, + "unit": "EA", + "unit_price": 15000, + "total_price": 30000, + "spec": "100x50x20", + "note": "필수 부품", + "order_no": 0 + } + ] + } + ] + } +} +``` + +**참고**: +- `type: "fields"` 템플릿: `fields` 배열 포함 +- `type: "bom"` 템플릿: `bomItems` 배열 포함 +- 기존 `pages` 응답의 중첩 구조와 동일한 패턴 + +--- + +## 5. 구현 우선순위 + +| 우선순위 | 작업 내용 | 예상 공수 | +|---------|----------|----------| +| 🔴 0 | `section_templates`에 `section_id` 컬럼 추가 (동기화용) | 0.5일 | +| 🔴 0 | 계층구조 섹션 생성 시 `section_templates` 자동 생성 로직 | 0.5일 | +| 🔴 1 | `section_template_fields` 테이블 생성 | 0.5일 | +| 🔴 1 | 섹션 템플릿 필드 CRUD API (5개) | 1일 | +| 🔴 1 | init API 응답에 `fields` 중첩 포함 | 0.5일 | +| 🟡 2 | `section_template_bom_items` 테이블 생성 | 0.5일 | +| 🟡 2 | 섹션 템플릿 BOM 품목 CRUD API (5개) | 1일 | +| 🟡 2 | init API 응답에 `bomItems` 중첩 포함 | 0.5일 | +| 🟢 3 | 양방향 동기화 로직 (섹션↔템플릿 수정 시 상호 반영) | 1일 | +| 🟢 3 | Swagger 문서 업데이트 | 0.5일 | + +**총 예상 공수**: 백엔드 6.5일 + +--- + +## 6. 프론트엔드 연동 계획 + +### 6.1 API 완료 후 프론트엔드 작업 + +| 작업 | 설명 | 의존성 | +|------|------|--------| +| 타입 정의 수정 | `SectionTemplateResponse`에 `fields`, `bomItems`, `section_id` 추가 | init API 수정 후 | +| Context 수정 | 섹션 템플릿 필드/BOM API 호출 로직 추가 | CRUD API 완료 후 | +| 로컬 상태 제거 | `default_fields` 로컬 관리 로직 → API 연동으로 교체 | CRUD API 완료 후 | +| 동기화 UI | 계층구조↔섹션탭 간 데이터 자동 반영 | section_id 추가 후 | + +### 6.2 타입 수정 예시 + +**현재** (`src/types/item-master-api.ts`): +```typescript +export interface SectionTemplateResponse { + id: number; + title: string; + type: 'fields' | 'bom'; + description?: string; + is_default: boolean; +} +``` + +**수정 후**: +```typescript +export interface SectionTemplateResponse { + id: number; + section_id?: number | null; // 연결된 계층구조 섹션 ID + title: string; + type: 'fields' | 'bom'; + description?: string; + is_default: boolean; + fields?: SectionTemplateFieldResponse[]; // type='fields'일 때 + bomItems?: SectionTemplateBomItemResponse[]; // type='bom'일 때 +} +``` + +### 6.3 동기화 시나리오 정리 + +``` +[시나리오 1] 계층구조에서 섹션 생성 + └─ 백엔드: item_sections + section_templates 동시 생성 (section_id로 연결) + └─ 프론트: init 재조회 → 양쪽 탭에 데이터 표시 + +[시나리오 2] 계층구조에서 필드 추가/수정 + └─ 백엔드: item_fields 저장 → 연결된 section_template_fields도 동기화 + └─ 프론트: init 재조회 → 섹션탭에 필드 반영 + +[시나리오 3] 섹션탭에서 필드 추가/수정 + └─ 백엔드: section_template_fields 저장 → 연결된 item_fields도 동기화 + └─ 프론트: init 재조회 → 계층구조탭에 필드 반영 + +[시나리오 4] 섹션탭에서 독립 템플릿 생성 (section_id = null) + └─ 백엔드: section_templates만 생성 (계층구조와 무관) + └─ 프론트: 섹션탭에서만 사용 가능한 템플릿 +``` + +--- + +## 📞 문의 + +질문 있으시면 프론트엔드 팀으로 연락 주세요. + +--- + +**작성일**: 2025-11-25 +**기준 문서**: `[API-2025-11-20] item-master-specification.md` diff --git a/claudedocs/[CASE-2025-11-25] httponly-cookie-security-validation.md b/claudedocs/[CASE-2025-11-25] httponly-cookie-security-validation.md new file mode 100644 index 00000000..1770b2ee --- /dev/null +++ b/claudedocs/[CASE-2025-11-25] httponly-cookie-security-validation.md @@ -0,0 +1,370 @@ +# [CASE STUDY] HttpOnly 쿠키 보안 검증 사례 + +**날짜**: 2025-11-25 +**카테고리**: 보안 검증, 인증 아키텍처, HttpOnly 쿠키 +**결과**: ✅ 보안 설계가 완벽하게 작동함을 검증 + +--- + +## 📋 요약 + +HttpOnly 쿠키를 사용한 인증 시스템에서 **"토큰값이 null로 전달된다"** 는 문제가 발생했으나, 실제로는 **보안이 철저하게 작동하고 있었음**을 확인한 사례. + +**핵심 교훈**: +> **JavaScript로 HttpOnly 쿠키를 절대 읽을 수 없다 = 보안이 제대로 작동하고 있다는 증거!** + +--- + +## 🔴 문제 상황 + +### 증상 +``` +❌ GET https://api.codebridge-x.com/api/v1/item-master/init 401 (Unauthorized) +❌ 백엔드 로그: Authorization 헤더 값이 null +❌ 로그인은 성공했는데 이후 API 호출 시 인증 실패 +``` + +### 초기 의심 지점 +1. API URL 경로 문제? → ❌ 경로는 정상 +2. 헤더 전송 문제? → ❌ 헤더는 전송되고 있음 +3. 쿠키 저장 문제? → ❌ 쿠키는 저장되어 있음 +4. **토큰 추출 문제?** → ✅ **여기가 진짜 원인!** + +--- + +## 🔍 발견 과정 + +### 1단계: 혼란 +```typescript +// auth-headers.ts에서 토큰 추출 시도 +const token = document.cookie + .split('; ') + .find(row => row.startsWith('access_token=')) + ?.split('=')[1]; + +console.log(token); // undefined ← 왜??? +``` + +**의문점**: +- 분명 로그인 성공했는데? +- Application 탭에서 쿠키 보이는데? +- Swagger에서는 같은 토큰으로 잘 되는데? + +### 2단계: 결정적 질문 +> **"어 근데 로그아웃 할 때는 토큰 잘 던지는데 어떤차이야???"** + +### 3단계: 깨달음 +로그아웃 API 코드를 확인해보니... + +```typescript +// /api/auth/logout/route.ts (Next.js API Route - 서버사이드!) +export async function POST(request: NextRequest) { + // ✅ 서버에서는 HttpOnly 쿠키를 읽을 수 있다! + const accessToken = request.cookies.get('access_token')?.value; + + // 토큰이 정상적으로 추출됨! + console.log(accessToken); // "eyJ0eXAiOiJKV1QiLCJh..." +} +``` + +**발견**: 로그아웃은 **Next.js API Route (서버사이드)** 에서 처리하고 있었다! + +--- + +## 💡 근본 원인 + +### HttpOnly 쿠키의 작동 원리 + +``` +┌─────────────────────────────────────────────────────────┐ +│ HttpOnly 쿠키 = JavaScript 접근 차단 (XSS 방지) │ +└─────────────────────────────────────────────────────────┘ + +❌ 클라이언트 JavaScript (브라우저) + ↓ + document.cookie → "" (빈 문자열, 읽기 불가) + ↓ + HttpOnly 쿠키는 보이지 않음! + + +✅ 서버사이드 (Node.js, Next.js API Route) + ↓ + request.cookies.get('access_token') → "토큰값" (읽기 가능!) + ↓ + HttpOnly 쿠키 정상 접근! +``` + +### 우리가 겪은 상황 + +```typescript +// ❌ WRONG: 클라이언트에서 직접 백엔드 호출 +fetch('https://api.codebridge-x.com/api/v1/item-master/init', { + headers: { + 'Authorization': `Bearer ${document.cookie에서_추출}` // null! + // ↑ HttpOnly 쿠키는 JavaScript로 읽을 수 없음! + } +}) +``` + +**결론**: 우리가 막아둔 보안(HttpOnly)이 **완벽하게 작동하고 있었다!** 🎉 + +--- + +## ✅ 해결 방법: Next.js API Proxy Pattern + +### 아키텍처 + +``` +[브라우저] + ↓ fetch('/api/proxy/item-master/init') + ↓ Cookie: access_token=xxx (자동 전송, HttpOnly) + ↓ Headers: { X-API-KEY, Accept } + ↓ ⚠️ Authorization 헤더 없음 (JS로 못 읽으니까!) + +[Next.js 프록시] ← 서버사이드! + ↓ request.cookies.get('access_token') ✅ 읽기 성공! + ↓ fetch('https://backend.com/api/v1/item-master/init') + ↓ Headers: { + ↓ Authorization: 'Bearer {토큰}', ← 프록시가 추가! + ↓ X-API-KEY: '...' + ↓ } + +[PHP 백엔드] + ↓ Authorization 헤더 확인 ✅ + ↓ 인증 성공! 데이터 반환 + +[브라우저] + ↓ 데이터 수신 완료! +``` + +### 구현 + +#### 1. Catch-all 프록시 라우트 생성 +```typescript +// /src/app/api/proxy/[...path]/route.ts +async function proxyRequest( + request: NextRequest, + params: { path: string[] }, + method: string +) { + // 1. 서버에서 HttpOnly 쿠키 읽기 (가능!) + const token = request.cookies.get('access_token')?.value; + + // 2. 백엔드로 프록시 + const backendResponse = await fetch( + `${process.env.NEXT_PUBLIC_API_URL}/api/v1/${params.path.join('/')}`, + { + method, + headers: { + 'Authorization': token ? `Bearer ${token}` : '', + 'X-API-KEY': process.env.NEXT_PUBLIC_API_KEY || '', + }, + } + ); + + return backendResponse; +} + +export async function GET(request, { params }) { + return proxyRequest(request, params, 'GET'); +} + +export async function POST(request, { params }) { + return proxyRequest(request, params, 'POST'); +} + +// PUT, DELETE도 동일... +``` + +#### 2. API 클라이언트 수정 +```typescript +// /src/lib/api/item-master.ts + +// ❌ BEFORE: 직접 백엔드 호출 +const BASE_URL = 'https://api.codebridge-x.com/api/v1'; + +// ✅ AFTER: 프록시 사용 +const BASE_URL = '/api/proxy'; + +// 이제 모든 API 호출이 프록시를 통함 +export async function getItemMasterInit() { + const response = await fetch(`${BASE_URL}/item-master/init`, { + headers: getAuthHeaders(), + }); + return response; +} +``` + +#### 3. 헤더 유틸리티 간소화 +```typescript +// /src/lib/api/auth-headers.ts + +// ✅ AFTER: Authorization 헤더 제거 (프록시가 처리) +export const getAuthHeaders = (): HeadersInit => { + return { + 'Content-Type': 'application/json', + 'Accept': 'application/json', + 'X-API-KEY': process.env.NEXT_PUBLIC_API_KEY || '', + // Authorization 헤더 없음! 프록시가 추가함 + }; +}; +``` + +--- + +## 🎓 교훈 + +### 1. HttpOnly 쿠키는 정말로 JavaScript 접근을 막는다 +```javascript +// 이것은 실패하도록 설계되었다! +document.cookie // HttpOnly 쿠키는 보이지 않음 + +// 이것이 보안의 핵심! +// XSS 공격으로 스크립트가 실행되어도 토큰을 훔칠 수 없다! +``` + +### 2. "작동 안 함" ≠ "버그" +- 처음엔 "토큰이 null이라서 문제"라고 생각 +- 실제로는 "보안이 제대로 작동하는 것" +- **예상대로 작동하지 않는 것이 설계 의도일 수 있다!** + +### 3. 기존 코드에서 배우기 +- 로그아웃이 작동하는 이유를 분석 +- "왜 이것만 되지?"라는 질문이 해결의 열쇠 +- **작동하는 코드 = 참조 구현** + +### 4. 서버사이드 프록시 패턴의 가치 +``` +보안 (HttpOnly) + 기능 (API 호출) = 프록시 패턴 + ↓ ↓ ↓ +XSS 방지 인증된 API 호출 Best of Both +``` + +--- + +## 🔐 보안 검증 결과 + +### ✅ 검증된 사항 + +1. **JavaScript로 HttpOnly 쿠키를 절대 읽을 수 없음** + - `document.cookie`에서 완전히 숨겨짐 + - 브라우저 콘솔에서도 접근 불가 + - **XSS 공격으로부터 안전!** + +2. **서버사이드에서만 접근 가능** + - Next.js API Route에서 `request.cookies.get()` 성공 + - 토큰이 서버 메모리에만 존재 + - 클라이언트 JavaScript에 노출되지 않음 + +3. **자동 쿠키 전송** + - 브라우저가 same-origin 요청 시 자동 전송 + - HTTPS로 암호화되어 전송 + - Secure, HttpOnly, SameSite 속성으로 보호 + +### 🛡️ 보안 강도 + +| 공격 유형 | 방어 가능 여부 | 이유 | +|----------|----------------|------| +| XSS (Cross-Site Scripting) | ✅ 방어 | JavaScript가 쿠키를 읽을 수 없음 | +| Session Hijacking | ✅ 방어 | HttpOnly + Secure 조합 | +| CSRF | ⚠️ 추가 방어 필요 | SameSite 속성으로 일부 방어 | +| Man-in-the-Middle | ✅ 방어 | HTTPS + Secure 속성 | + +--- + +## 📝 RULES.md 반영 + +이번 사례를 바탕으로 `RULES.md`에 추가된 규칙: + +```markdown +## API Communication with HttpOnly Cookies +**Priority**: 🔴 **Triggers**: Backend API calls requiring authentication + +### Mandatory Proxy Pattern +- ALL authenticated API calls MUST use Next.js API route proxies +- NEVER try to read HttpOnly cookies with JavaScript +- Reference implementation: /api/auth/logout/route.ts +``` + +--- + +## 🎯 적용 범위 + +### 현재 적용됨 +- ✅ 로그인 API (`/api/auth/login`) +- ✅ 로그아웃 API (`/api/auth/logout`) +- ✅ 품목기준관리 API (`/api/proxy/item-master/*`) + +### 향후 적용 필요 +- 품목관리 API (개발 예정) +- 기타 인증 필요 API들 + +### 프록시 사용법 +```typescript +// ❌ WRONG +fetch('https://backend.com/api/v1/some-api') + +// ✅ RIGHT +fetch('/api/proxy/some-api') +``` + +--- + +## 📊 성능 영향 + +### 레이턴시 +- **프록시 추가 레이턴시**: ~5-15ms (Next.js 서버 처리) +- **보안 향상**: 무한대 +- **결론**: 트레이드오프 가치 있음 + +### 서버 부하 +- Next.js 서버가 모든 API 요청을 중계 +- 필요 시 캐싱 전략 추가 가능 +- 현재 규모에서는 문제 없음 + +--- + +## 🔗 관련 파일 + +### 구현 파일 +- `/src/app/api/proxy/[...path]/route.ts` - Catch-all 프록시 +- `/src/lib/api/item-master.ts` - API 클라이언트 +- `/src/lib/api/auth-headers.ts` - 헤더 유틸리티 + +### 참조 파일 +- `/src/app/api/auth/logout/route.ts` - 참조 구현 +- `/Users/byeongcheolryu/.claude/RULES.md` - 규칙 문서 + +--- + +## 💬 팀 피드백 + +> "흐흑 ㅠㅠ 우리가 막아두고 계속 스크립트로 요청했구나" +> +> "보안 검증이 철저하게 됐군 스크립트로 절대 못 뽑아온다는걸 말야 ㅋㅋ" + +**→ 보안이 제대로 작동하고 있었다는 것을 확인한 순간!** + +--- + +## 🎉 결론 + +이번 사례는 **"버그인 줄 알았는데 실은 기능(feature)이었다"** 는 완벽한 예시입니다. + +### Key Takeaways +1. ✅ HttpOnly 쿠키 보안이 완벽하게 작동함을 검증 +2. ✅ 서버사이드 프록시 패턴으로 보안과 기능 모두 확보 +3. ✅ 기존 코드(로그아웃)에서 해결책을 찾음 +4. ✅ 향후 모든 인증 API에 적용할 패턴 확립 + +### 최종 평가 +**🏆 보안 설계: A+** +**🔧 구현 방법: A+** +**📚 문서화: A+** + +--- + +**작성일**: 2025-11-25 +**작성자**: Claude Code +**검증자**: 개발팀 +**상태**: ✅ 완료 및 프로덕션 적용 \ No newline at end of file diff --git a/claudedocs/[DESIGN-2025-11-24] item-management-dynamic-frontend.md b/claudedocs/[DESIGN-2025-11-24] item-management-dynamic-frontend.md new file mode 100644 index 00000000..ed3402c4 --- /dev/null +++ b/claudedocs/[DESIGN-2025-11-24] item-management-dynamic-frontend.md @@ -0,0 +1,1128 @@ +# 품목관리 동적 화면 생성 프론트엔드 설계 + +**작성일**: 2025-11-24 +**프로젝트**: SAM MES System - Next.js 15 Frontend +**관련 API 문서**: [API-2025-11-24] item-management-dynamic-api-spec.md + +--- + +## 목차 + +1. [개요](#개요) +2. [아키텍처 설계](#아키텍처-설계) +3. [컴포넌트 구조](#컴포넌트-구조) +4. [동적 렌더링 엔진](#동적-렌더링-엔진) +5. [상태 관리](#상태-관리) +6. [구현 가이드](#구현-가이드) +7. [사용자 시나리오](#사용자-시나리오) + +--- + +## 개요 + +### 목적 +품목기준관리에서 정의한 메타데이터를 기반으로 품목관리 화면을 동적으로 생성 + +### 핵심 요구사항 +1. 메타데이터 기반 동적 폼 생성 +2. 메타데이터 기반 동적 테이블 생성 +3. 필드 타입별 적절한 입력 컴포넌트 +4. 페이지(탭) 구조 지원 +5. 섹션별 그룹핑 +6. 실시간 유효성 검증 + +### 기존 품목기준관리 구조 참고 + +**ItemMasterContext**: +```typescript +// 메타데이터 구조 +interface ItemPage { + id: string; + page_name: string; + display_order: number; + sections: ItemSection[]; +} + +interface ItemSection { + id: string; + section_name: string; + display_order: number; + fields: ItemField[]; +} + +interface ItemField { + id: string; + field_name: string; + field_label: string; + field_type: 'text' | 'number' | 'date' | 'select' | 'textarea' | 'checkbox' | 'file'; + is_required: boolean; + validation_rules?: Record; + default_value?: string; + options?: string[]; + help_text?: string; + placeholder?: string; +} +``` + +--- + +## 아키텍처 설계 + +### 전체 흐름 + +``` +사용자가 품목관리 페이지 접속 + ↓ +1. API 호출: GET /api/item-master/config + → 메타데이터 조회 + ↓ +2. ItemMetadataContext에 저장 + → 전역 상태 관리 + ↓ +3. 메타데이터 파싱 + - 페이지(탭) 구조 분석 + - 섹션 구조 분석 + - 필드 구조 분석 + ↓ +4. 동적 컴포넌트 생성 + - DynamicTable (목록) + - DynamicForm (생성/수정) + - DynamicFilter (필터) + ↓ +5. 사용자 CRUD 작업 + → API 호출 +``` + +### 디렉토리 구조 + +``` +src/ +├── components/ +│ └── items/ +│ ├── ItemManagement.tsx # 메인 페이지 컴포넌트 +│ └── ItemManagement/ +│ ├── DynamicTable.tsx # 동적 테이블 +│ ├── DynamicForm.tsx # 동적 폼 +│ ├── DynamicFilter.tsx # 동적 필터 +│ ├── fields/ +│ │ ├── DynamicFieldRenderer.tsx # 필드 타입별 렌더러 +│ │ ├── TextField.tsx # 텍스트 입력 +│ │ ├── NumberField.tsx # 숫자 입력 +│ │ ├── DateField.tsx # 날짜 선택 +│ │ ├── SelectField.tsx # 드롭다운 +│ │ ├── TextareaField.tsx # 텍스트 영역 +│ │ ├── CheckboxField.tsx # 체크박스 +│ │ └── FileField.tsx # 파일 업로드 +│ ├── ItemDialog.tsx # 생성/수정 다이얼로그 +│ └── ItemTableRow.tsx # 테이블 행 컴포넌트 +├── contexts/ +│ └── ItemMetadataContext.tsx # 메타데이터 전역 상태 +├── lib/ +│ ├── api/ +│ │ └── items.ts # 품목 API 클라이언트 +│ └── utils/ +│ ├── fieldValidation.ts # 필드 검증 유틸 +│ └── fieldFormatters.ts # 필드 포맷터 +└── types/ + └── item.ts # 품목 관련 타입 정의 +``` + +--- + +## 컴포넌트 구조 + +### 1. ItemMetadataContext + +**목적**: 메타데이터를 전역에서 관리하고 캐싱 + +```typescript +// src/contexts/ItemMetadataContext.tsx +'use client'; + +import { createContext, useContext, useState, useEffect, ReactNode } from 'react'; +import { itemsApi } from '@/lib/api/items'; +import type { ItemMetadata, ItemPage } from '@/types/item'; + +interface ItemMetadataContextType { + metadata: ItemMetadata | null; + isLoading: boolean; + error: string | null; + refresh: () => Promise; +} + +const ItemMetadataContext = createContext(undefined); + +export function ItemMetadataProvider({ children }: { children: ReactNode }) { + const [metadata, setMetadata] = useState(null); + const [isLoading, setIsLoading] = useState(true); + const [error, setError] = useState(null); + + const loadMetadata = async () => { + try { + setIsLoading(true); + setError(null); + const data = await itemsApi.getMetadata(); + setMetadata(data); + } catch (err) { + setError(err instanceof Error ? err.message : 'Failed to load metadata'); + } finally { + setIsLoading(false); + } + }; + + useEffect(() => { + loadMetadata(); + }, []); + + return ( + + {children} + + ); +} + +export function useItemMetadata() { + const context = useContext(ItemMetadataContext); + if (!context) { + throw new Error('useItemMetadata must be used within ItemMetadataProvider'); + } + return context; +} +``` + +### 2. ItemManagement (메인 페이지) + +```typescript +// src/components/items/ItemManagement.tsx +'use client'; + +import { useState } from 'react'; +import { PageLayout } from '@/components/organisms/PageLayout'; +import { PageHeader } from '@/components/organisms/PageHeader'; +import { Button } from '@/components/ui/button'; +import { Plus } from 'lucide-react'; +import { useItemMetadata } from '@/contexts/ItemMetadataContext'; +import { DynamicTable } from './ItemManagement/DynamicTable'; +import { DynamicFilter } from './ItemManagement/DynamicFilter'; +import { ItemDialog } from './ItemManagement/ItemDialog'; +import { LoadingSpinner } from '@/components/ui/loading-spinner'; +import { ErrorMessage } from '@/components/ui/error-message'; + +export function ItemManagement() { + const { metadata, isLoading, error } = useItemMetadata(); + const [isDialogOpen, setIsDialogOpen] = useState(false); + const [editingItem, setEditingItem] = useState(null); + const [filters, setFilters] = useState>({}); + + if (isLoading) { + return ; + } + + if (error || !metadata) { + return ; + } + + const handleCreate = () => { + setEditingItem(null); + setIsDialogOpen(true); + }; + + const handleEdit = (item: any) => { + setEditingItem(item); + setIsDialogOpen(true); + }; + + return ( + + + + 품목 추가 + + } + /> + +
+ {/* 동적 필터 */} + + + {/* 동적 테이블 */} + +
+ + {/* 생성/수정 다이얼로그 */} + setIsDialogOpen(false)} + metadata={metadata} + item={editingItem} + /> + + ); +} +``` + +### 3. DynamicTable (동적 테이블) + +```typescript +// src/components/items/ItemManagement/DynamicTable.tsx +'use client'; + +import { useState, useEffect } from 'react'; +import { itemsApi } from '@/lib/api/items'; +import type { ItemMetadata, Item } from '@/types/item'; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from '@/components/ui/table'; +import { Button } from '@/components/ui/button'; +import { Edit, Trash2 } from 'lucide-react'; +import { Pagination } from '@/components/ui/pagination'; + +interface DynamicTableProps { + metadata: ItemMetadata; + filters: Record; + onEdit: (item: Item) => void; +} + +export function DynamicTable({ metadata, filters, onEdit }: DynamicTableProps) { + const [items, setItems] = useState([]); + const [pagination, setPagination] = useState({ + total: 0, + current_page: 1, + per_page: 20, + last_page: 1, + }); + const [isLoading, setIsLoading] = useState(false); + + // 목록에 표시할 컬럼 추출 (show_in_list=true) + const columns = metadata.pages + .flatMap(page => page.sections) + .flatMap(section => section.fields) + .filter(field => field.show_in_list) + .sort((a, b) => (a.list_order ?? 999) - (b.list_order ?? 999)); + + useEffect(() => { + loadItems(); + }, [filters, pagination.current_page]); + + const loadItems = async () => { + try { + setIsLoading(true); + const response = await itemsApi.getList({ + page: pagination.current_page, + per_page: pagination.per_page, + ...filters, + }); + setItems(response.data); + setPagination(response.pagination); + } catch (error) { + console.error('Failed to load items:', error); + } finally { + setIsLoading(false); + } + }; + + const handleDelete = async (id: number) => { + if (!confirm('정말 삭제하시겠습니까?')) return; + + try { + await itemsApi.delete(id); + loadItems(); + } catch (error) { + console.error('Failed to delete item:', error); + alert('삭제에 실패했습니다.'); + } + }; + + return ( +
+ + + + {columns.map(column => ( + + {column.field_label} + + ))} + 작업 + + + + {isLoading ? ( + + + 로딩 중... + + + ) : items.length === 0 ? ( + + + 데이터가 없습니다. + + + ) : ( + items.map(item => ( + + {columns.map(column => ( + + {formatCellValue(item[column.field_name], column)} + + ))} + +
+ + +
+ + + )) + )} + +
+ + setPagination(prev => ({ ...prev, current_page: page }))} + /> +
+ ); +} + +function formatCellValue(value: any, column: any): string { + if (value === null || value === undefined) return '-'; + + switch (column.field_type) { + case 'number': + return typeof value === 'number' ? value.toLocaleString() : value; + case 'date': + return value ? new Date(value).toLocaleDateString('ko-KR') : '-'; + case 'checkbox': + return value ? '예' : '아니오'; + default: + return String(value); + } +} +``` + +### 4. DynamicForm (동적 폼) + +```typescript +// src/components/items/ItemManagement/DynamicForm.tsx +'use client'; + +import { useState, useEffect } from 'react'; +import type { ItemMetadata, Item, ItemField } from '@/types/item'; +import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'; +import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'; +import { DynamicFieldRenderer } from './fields/DynamicFieldRenderer'; +import { validateField } from '@/lib/utils/fieldValidation'; + +interface DynamicFormProps { + metadata: ItemMetadata; + initialValues?: Partial; + onSubmit: (values: Record) => void; +} + +export function DynamicForm({ metadata, initialValues, onSubmit }: DynamicFormProps) { + const [values, setValues] = useState>({}); + const [errors, setErrors] = useState>({}); + + // 초기값 설정 + useEffect(() => { + const defaultValues: Record = {}; + + // 메타데이터에서 기본값 추출 + metadata.pages.forEach(page => { + page.sections.forEach(section => { + section.fields.forEach(field => { + if (field.default_value) { + defaultValues[field.field_name] = field.default_value; + } + }); + }); + }); + + // 초기값 병합 + setValues({ ...defaultValues, ...initialValues }); + }, [metadata, initialValues]); + + const handleFieldChange = (fieldName: string, value: any, field: ItemField) => { + setValues(prev => ({ ...prev, [fieldName]: value })); + + // 실시간 유효성 검증 + const error = validateField(value, field); + setErrors(prev => { + const newErrors = { ...prev }; + if (error) { + newErrors[fieldName] = error; + } else { + delete newErrors[fieldName]; + } + return newErrors; + }); + }; + + const handleSubmit = () => { + // 전체 유효성 검증 + const newErrors: Record = {}; + + metadata.pages.forEach(page => { + page.sections.forEach(section => { + section.fields.forEach(field => { + const value = values[field.field_name]; + const error = validateField(value, field); + if (error) { + newErrors[field.field_name] = error; + } + }); + }); + }); + + if (Object.keys(newErrors).length > 0) { + setErrors(newErrors); + return; + } + + onSubmit(values); + }; + + return ( +
+ + + {metadata.pages.map(page => ( + + {page.page_name} + + ))} + + + {metadata.pages.map(page => ( + + {page.sections.map(section => ( + + + {section.section_name} + + + {section.fields.map(field => ( + handleFieldChange(field.field_name, value, field)} + /> + ))} + + + ))} + + ))} + + +
+ + +
+
+ ); +} +``` + +### 5. DynamicFieldRenderer (필드 렌더러) + +```typescript +// src/components/items/ItemManagement/fields/DynamicFieldRenderer.tsx +'use client'; + +import type { ItemField } from '@/types/item'; +import { TextField } from './TextField'; +import { NumberField } from './NumberField'; +import { DateField } from './DateField'; +import { SelectField } from './SelectField'; +import { TextareaField } from './TextareaField'; +import { CheckboxField } from './CheckboxField'; +import { FileField } from './FileField'; + +interface DynamicFieldRendererProps { + field: ItemField; + value: any; + error?: string; + onChange: (value: any) => void; +} + +export function DynamicFieldRenderer({ field, value, error, onChange }: DynamicFieldRendererProps) { + const commonProps = { + label: field.field_label, + value, + error, + onChange, + required: field.is_required, + helpText: field.help_text, + placeholder: field.placeholder, + }; + + switch (field.field_type) { + case 'text': + return ; + + case 'number': + return ; + + case 'date': + return ; + + case 'select': + return ; + + case 'textarea': + return ; + + case 'checkbox': + return ; + + case 'file': + return ; + + default: + console.warn(`Unknown field type: ${field.field_type}`); + return null; + } +} +``` + +### 6. TextField 예시 + +```typescript +// src/components/items/ItemManagement/fields/TextField.tsx +'use client'; + +import { Input } from '@/components/ui/input'; +import { Label } from '@/components/ui/label'; + +interface TextFieldProps { + label: string; + value: string; + error?: string; + onChange: (value: string) => void; + required?: boolean; + helpText?: string; + placeholder?: string; + validation?: Record; +} + +export function TextField({ + label, + value, + error, + onChange, + required, + helpText, + placeholder, + validation, +}: TextFieldProps) { + return ( +
+ + onChange(e.target.value)} + placeholder={placeholder} + maxLength={validation?.max_length} + className={error ? 'border-red-500' : ''} + /> + {helpText && ( +

{helpText}

+ )} + {error && ( +

{error}

+ )} +
+ ); +} +``` + +--- + +## 동적 렌더링 엔진 + +### 필드 검증 유틸리티 + +```typescript +// src/lib/utils/fieldValidation.ts +import type { ItemField } from '@/types/item'; + +export function validateField(value: any, field: ItemField): string | null { + // 필수 필드 체크 + if (field.is_required && !value) { + return `${field.field_label}은(는) 필수 입력 항목입니다.`; + } + + if (!value) return null; + + const rules = field.validation_rules || {}; + + switch (field.field_type) { + case 'text': + case 'textarea': + if (rules.min_length && value.length < rules.min_length) { + return `${field.field_label}은(는) 최소 ${rules.min_length}자 이상이어야 합니다.`; + } + if (rules.max_length && value.length > rules.max_length) { + return `${field.field_label}은(는) 최대 ${rules.max_length}자 이하여야 합니다.`; + } + if (rules.pattern && !new RegExp(rules.pattern).test(value)) { + return rules.error_message || `${field.field_label}의 형식이 올바르지 않습니다.`; + } + break; + + case 'number': + const numValue = Number(value); + if (isNaN(numValue)) { + return `${field.field_label}은(는) 숫자여야 합니다.`; + } + if (rules.min !== undefined && numValue < rules.min) { + return `${field.field_label}은(는) ${rules.min} 이상이어야 합니다.`; + } + if (rules.max !== undefined && numValue > rules.max) { + return `${field.field_label}은(는) ${rules.max} 이하여야 합니다.`; + } + break; + + case 'date': + const dateValue = new Date(value); + if (isNaN(dateValue.getTime())) { + return `${field.field_label}의 날짜 형식이 올바르지 않습니다.`; + } + if (rules.min_date) { + const minDate = rules.min_date === 'today' ? new Date() : new Date(rules.min_date); + if (dateValue < minDate) { + return `${field.field_label}은(는) ${minDate.toLocaleDateString()} 이후여야 합니다.`; + } + } + if (rules.max_date) { + const maxDate = new Date(rules.max_date); + if (dateValue > maxDate) { + return `${field.field_label}은(는) ${maxDate.toLocaleDateString()} 이전이어야 합니다.`; + } + } + break; + } + + return null; +} +``` + +### API 클라이언트 + +```typescript +// src/lib/api/items.ts +import { getAuthHeaders } from './auth-headers'; +import type { ItemMetadata, Item } from '@/types/item'; + +const BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'https://api.codebridge-x.com'; + +export const itemsApi = { + /** + * 메타데이터 조회 + */ + async getMetadata(): Promise { + const headers = getAuthHeaders(); + const response = await fetch(`${BASE_URL}/item-master/config`, { + method: 'GET', + headers, + }); + + if (!response.ok) { + throw new Error('Failed to fetch metadata'); + } + + const data = await response.json(); + return data.data; + }, + + /** + * 품목 목록 조회 + */ + async getList(params: { + page?: number; + per_page?: number; + sort_by?: string; + sort_order?: 'asc' | 'desc'; + search?: string; + [key: string]: any; + }): Promise<{ + data: Item[]; + pagination: { + total: number; + current_page: number; + per_page: number; + last_page: number; + }; + }> { + const headers = getAuthHeaders(); + const queryString = new URLSearchParams(params as any).toString(); + const response = await fetch(`${BASE_URL}/items?${queryString}`, { + method: 'GET', + headers, + }); + + if (!response.ok) { + throw new Error('Failed to fetch items'); + } + + const data = await response.json(); + return data.data; + }, + + /** + * 품목 상세 조회 + */ + async getById(id: number): Promise { + const headers = getAuthHeaders(); + const response = await fetch(`${BASE_URL}/items/${id}`, { + method: 'GET', + headers, + }); + + if (!response.ok) { + throw new Error('Failed to fetch item'); + } + + const data = await response.json(); + return data.data; + }, + + /** + * 품목 생성 + */ + async create(item: Record): Promise { + const headers = getAuthHeaders(); + const response = await fetch(`${BASE_URL}/items`, { + method: 'POST', + headers, + body: JSON.stringify(item), + }); + + if (!response.ok) { + const error = await response.json(); + throw new Error(error.message || 'Failed to create item'); + } + + const data = await response.json(); + return data.data; + }, + + /** + * 품목 수정 + */ + async update(id: number, item: Record): Promise { + const headers = getAuthHeaders(); + const response = await fetch(`${BASE_URL}/items/${id}`, { + method: 'PUT', + headers, + body: JSON.stringify(item), + }); + + if (!response.ok) { + const error = await response.json(); + throw new Error(error.message || 'Failed to update item'); + } + + const data = await response.json(); + return data.data; + }, + + /** + * 품목 삭제 + */ + async delete(id: number): Promise { + const headers = getAuthHeaders(); + const response = await fetch(`${BASE_URL}/items/${id}`, { + method: 'DELETE', + headers, + }); + + if (!response.ok) { + throw new Error('Failed to delete item'); + } + }, +}; +``` + +--- + +## 상태 관리 + +### Context vs Zustand + +**권장**: ItemMetadataContext (React Context API 사용) + +**이유**: +- 메타데이터는 자주 변경되지 않음 +- 전체 앱에서 공유 필요 +- 간단한 구조로 충분 + +**선택사항**: Zustand (복잡한 상태 관리 필요 시) + +```typescript +// src/stores/itemMetadataStore.ts (선택사항) +import { create } from 'zustand'; +import { itemsApi } from '@/lib/api/items'; +import type { ItemMetadata } from '@/types/item'; + +interface ItemMetadataState { + metadata: ItemMetadata | null; + isLoading: boolean; + error: string | null; + loadMetadata: () => Promise; +} + +export const useItemMetadataStore = create((set) => ({ + metadata: null, + isLoading: false, + error: null, + loadMetadata: async () => { + set({ isLoading: true, error: null }); + try { + const data = await itemsApi.getMetadata(); + set({ metadata: data }); + } catch (error) { + set({ error: error instanceof Error ? error.message : 'Failed to load' }); + } finally { + set({ isLoading: false }); + } + }, +})); +``` + +--- + +## 구현 가이드 + +### Step 1: Context 및 Provider 설정 + +1. `ItemMetadataContext.tsx` 생성 +2. `app/[locale]/(protected)/layout.tsx`에 Provider 추가: + +```typescript +import { ItemMetadataProvider } from '@/contexts/ItemMetadataContext'; + +export default function ProtectedLayout({ children }) { + return ( + + {children} + + ); +} +``` + +### Step 2: 기존 품목관리 페이지 대체 + +1. 기존 `/src/app/[locale]/(protected)/items/page.tsx` 백업 +2. 새 ItemManagement 컴포넌트로 교체: + +```typescript +// src/app/[locale]/(protected)/items/page.tsx +import { ItemManagement } from '@/components/items/ItemManagement'; +import type { Metadata } from 'next'; + +export const metadata: Metadata = { + title: '품목 관리', + description: '품목 정보를 관리합니다', +}; + +export default function ItemsPage() { + return ; +} +``` + +### Step 3: 동적 컴포넌트 구현 + +1. `DynamicTable.tsx` +2. `DynamicForm.tsx` +3. `DynamicFilter.tsx` +4. `DynamicFieldRenderer.tsx` +5. 각 필드 타입별 컴포넌트 (TextField, NumberField 등) + +### Step 4: API 클라이언트 구현 + +1. `src/lib/api/items.ts` 생성 +2. CRUD 메서드 구현 +3. 에러 핸들링 추가 + +### Step 5: 유효성 검증 로직 + +1. `src/lib/utils/fieldValidation.ts` 생성 +2. 필드 타입별 검증 로직 구현 + +### Step 6: 테스트 + +1. 메타데이터 조회 동작 확인 +2. 테이블 렌더링 확인 +3. 필터 동작 확인 +4. CRUD 동작 확인 +5. 유효성 검증 확인 + +--- + +## 사용자 시나리오 + +### 시나리오 1: 신규 품목 등록 + +``` +사용자 → "품목 추가" 버튼 클릭 + ↓ +ItemDialog 열림 + ↓ +DynamicForm 렌더링 (메타데이터 기반) + - 페이지 1: 기본정보 (품목코드, 품목명, 단위 등) + - 페이지 2: 추가정보 (규격, 재질, 색상 등) + ↓ +사용자 → 필드 입력 + ↓ +실시간 유효성 검증 + - 품목코드: 5-20자, 패턴 검증 + - 단위: 필수 선택 + ↓ +"저장" 버튼 클릭 + ↓ +전체 유효성 검증 + ↓ +API 호출: POST /api/v1/items + ↓ +성공 → 테이블 새로고침 + 토스트 메시지 +``` + +### 시나리오 2: 품목 검색 및 필터링 + +``` +사용자 → 검색어 입력 ("ITEM-") + ↓ +DynamicFilter에서 입력 감지 + ↓ +debounce 후 API 호출 + → GET /api/v1/items?search=ITEM- + ↓ +테이블 업데이트 + ↓ +사용자 → 필터 적용 (단위: EA) + ↓ +API 호출: GET /api/v1/items?search=ITEM-&unit=EA + ↓ +테이블 업데이트 +``` + +### 시나리오 3: 품목기준관리 변경 반영 + +``` +관리자 → 품목기준관리에서 필드 추가 + 예: "중량" 필드 추가 (number, 필수) + ↓ +백엔드 → 메타데이터 업데이트 + ↓ +백엔드 → 캐시 클리어 + ↓ +사용자 → 품목관리 페이지 새로고침 + ↓ +메타데이터 재조회 + ↓ +DynamicForm에 "중량" 필드 자동 추가 + ↓ +DynamicTable에 "중량" 컬럼 자동 추가 + ↓ +기존 품목 → 중량 필드 없음 (NULL) +신규 품목 → 중량 필드 필수 입력 +``` + +--- + +## 체크리스트 + +### 프론트엔드 구현 + +``` +✓ ItemMetadataContext 및 Provider 설정 +✓ ItemManagement 메인 컴포넌트 +✓ DynamicTable 구현 +✓ DynamicForm 구현 +✓ DynamicFilter 구현 +✓ DynamicFieldRenderer 구현 +✓ 필드 타입별 컴포넌트 (7개) +✓ API 클라이언트 구현 +✓ 유효성 검증 유틸리티 +✓ 에러 핸들링 +✓ 로딩 상태 관리 +✓ 반응형 디자인 +``` + +### 기능 구현 + +``` +✓ 메타데이터 조회 및 캐싱 +✓ 페이지(탭) 구조 렌더링 +✓ 섹션별 그룹핑 +✓ 동적 필드 렌더링 +✓ 필수 필드 검증 +✓ 필드 타입별 검증 (패턴, min/max 등) +✓ 테이블 목록 표시 +✓ 검색 기능 +✓ 필터 기능 +✓ 정렬 기능 +✓ 페이지네이션 +✓ 생성/수정/삭제 기능 +``` + +--- + +## 관련 문서 + +- [백엔드 API 명세서](./[API-2025-11-24]%20item-management-dynamic-api-spec.md) +- [품목기준관리 컴포넌트](/src/components/items/ItemMasterDataManagement.tsx) +- [품목기준관리 Context](/src/contexts/ItemMasterContext.tsx) + +--- + +**최종 업데이트**: 2025-11-24 \ No newline at end of file diff --git a/claudedocs/SSR_HYDRATION_FIX.md b/claudedocs/[IMPL-2025-11-18] ssr-hydration-fix.md similarity index 100% rename from claudedocs/SSR_HYDRATION_FIX.md rename to claudedocs/[IMPL-2025-11-18] ssr-hydration-fix.md diff --git a/claudedocs/REFACTORING_PLAN.md b/claudedocs/[PLAN-2025-11-18] refactoring-plan.md similarity index 100% rename from claudedocs/REFACTORING_PLAN.md rename to claudedocs/[PLAN-2025-11-18] refactoring-plan.md diff --git a/claudedocs/COMPONENT_SEPARATION_PLAN.md b/claudedocs/[PLAN-2025-11-21] component-separation.md similarity index 100% rename from claudedocs/COMPONENT_SEPARATION_PLAN.md rename to claudedocs/[PLAN-2025-11-21] component-separation.md diff --git a/claudedocs/CLEANUP_SUMMARY.md b/claudedocs/[REF-2025-11-18] cleanup-summary.md similarity index 100% rename from claudedocs/CLEANUP_SUMMARY.md rename to claudedocs/[REF-2025-11-18] cleanup-summary.md diff --git a/claudedocs/UNUSED_FILES_REPORT.md b/claudedocs/[REF-2025-11-18] unused-files-report.md similarity index 100% rename from claudedocs/UNUSED_FILES_REPORT.md rename to claudedocs/[REF-2025-11-18] unused-files-report.md diff --git a/claudedocs/_API_DESIGN_ITEM_MASTER_CONFIG.md b/claudedocs/_API_DESIGN_ITEM_MASTER_CONFIG.md deleted file mode 100644 index 9aae32e8..00000000 --- a/claudedocs/_API_DESIGN_ITEM_MASTER_CONFIG.md +++ /dev/null @@ -1,958 +0,0 @@ -# 품목기준관리 API 설계 문서 - -**작성일**: 2025-11-18 -**목적**: 품목기준관리 페이지의 설정 데이터를 서버와 동기화하기 위한 API 구조 설계 - ---- - -## 📋 목차 - -1. [개요](#개요) -2. [데이터 구조 분석](#데이터-구조-분석) -3. [API 엔드포인트 설계](#api-엔드포인트-설계) -4. [데이터 모델](#데이터-모델) -5. [저장/불러오기 시나리오](#저장불러오기-시나리오) -6. [버전 관리 전략](#버전-관리-전략) -7. [에러 처리](#에러-처리) - ---- - -## 개요 - -### 테넌트 정보 구조 - -본 시스템은 로그인 시 받는 실제 테넌트 정보 구조를 기반으로 설계되었습니다. - -```typescript -// 로그인 성공 시 받는 실제 사용자 정보 -{ - userId: "TestUser3", - name: "드미트리", - tenant: { - id: 282, // ✅ 테넌트 고유 ID (number 타입) - company_name: "(주)테크컴퍼니", // 테넌트 회사명 - business_num: "123-45-67890", // 사업자 번호 - tenant_st_code: "trial" // 테넌트 상태 코드 - } -} -``` - -**중요**: API 엔드포인트의 `{tenantId}`는 위 구조의 `tenant.id` 값(number 타입, 예: 282)을 의미합니다. - -### 시스템 흐름 - -``` -┌──────────────────────────────┐ -│ 로그인 (Login) │ -│ tenant.id: 282 (number) │ -└────────┬─────────────────────┘ - │ - ▼ -┌──────────────────────────────┐ -│ 테넌트 (Tenant) │ -│ 고유 필드 구성 │ -│ tenant.id 기반 격리 │ -└────────┬─────────────────────┘ - │ - ▼ -┌────────────────────────────────┐ -│ 품목기준관리 페이지 │ -│ (Item Master Config Page) │ -│ │ -│ - 페이지 구조 설정 │ -│ - 섹션 구성 │ -│ - 필드 정의 │ -│ - 마스터 데이터 관리 │ -│ - 버전 관리 │ -└────────┬───────────────────────┘ - │ Save (with tenant.id) - ▼ -┌────────────────────────────────┐ -│ API Server │ -│ (Backend) │ -│ │ -│ - 테넌트별 데이터 저장 │ -│ - tenant.id 검증 │ -│ - 버전 관리 │ -│ - 유효성 검증 │ -└────────┬───────────────────────┘ - │ Load (filtered by tenant.id) - ▼ -┌────────────────────────────────┐ -│ 품목관리 페이지 │ -│ (Item Management Page) │ -│ │ -│ - 설정 기반 동적 폼 생성 │ -│ - 실제 품목 데이터 입력 │ -└────────────────────────────────┘ -``` - -### 핵심 요구사항 - -1. **테넌트 격리**: 각 테넌트별로 독립적인 설정 (`tenant.id` 기반 완전 격리) -2. **계층 구조**: Page → Section → Field 3단계 계층 -3. **버전 관리**: 설정 변경 이력 추적 -4. **재사용성**: 템플릿 기반 섹션/필드 재사용 -5. **동적 생성**: 설정 기반 품목관리 페이지 동적 렌더링 -6. **서버 검증**: JWT의 tenant.id와 API 요청의 tenantId 일치 검증 - ---- - -## 데이터 구조 분석 - -### 1. 계층 구조 (Hierarchical Structure) - -``` -ItemMasterConfig (전체 설정) -│ -├─ ItemPage[] (페이지 배열) -│ ├─ id -│ ├─ pageName -│ ├─ itemType (FG/PT/SM/RM/CS) -│ └─ sections[] -│ │ -│ ├─ ItemSection (섹션) -│ │ ├─ id -│ │ ├─ title -│ │ ├─ type ('fields' | 'bom') -│ │ ├─ order -│ │ └─ fields[] -│ │ │ -│ │ └─ ItemField (필드) -│ │ ├─ id -│ │ ├─ name -│ │ ├─ fieldKey -│ │ ├─ property (ItemFieldProperty) -│ │ └─ displayCondition -│ -├─ SectionTemplate[] (재사용 섹션 템플릿) -│ -├─ ItemMasterField[] (재사용 필드 템플릿) -│ -└─ MasterData (마스터 데이터들) - ├─ SpecificationMaster[] - ├─ MaterialItemName[] - ├─ ItemCategory[] - ├─ ItemUnit[] - ├─ ItemMaterial[] - ├─ SurfaceTreatment[] - ├─ PartTypeOption[] - ├─ PartUsageOption[] - └─ GuideRailOption[] -``` - -### 2. 저장해야 할 데이터 범위 - -#### ✅ 저장 필수 데이터 -1. **페이지 구조** (`itemPages`) -2. **섹션 템플릿** (`sectionTemplates`) -3. **항목 마스터** (`itemMasterFields`) -4. **마스터 데이터** (9가지): - - 규격 마스터 (`specificationMasters`) - - 품목명 마스터 (`materialItemNames`) - - 품목 분류 (`itemCategories`) - - 단위 (`itemUnits`) - - 재질 (`itemMaterials`) - - 표면처리 (`surfaceTreatments`) - - 부품 유형 옵션 (`partTypeOptions`) - - 부품 용도 옵션 (`partUsageOptions`) - - 가이드레일 옵션 (`guideRailOptions`) - -#### ❌ 저장 불필요 데이터 -- **실제 품목 데이터** (`itemMasters`) - 별도 API로 관리 - ---- - -## API 엔드포인트 설계 - -### Base URL -``` -/api/tenants/{tenantId}/item-master-config -``` - -**참고**: `{tenantId}`는 로그인 응답의 `tenant.id` 값(number 타입)입니다. 예: `/api/tenants/282/item-master-config` - -### 서버 검증 (Server-side Validation) - -모든 API 요청에서 다음 검증을 수행해야 합니다: - -```typescript -// Middleware 예시 -async function validateTenantAccess(req, res, next) { - // 1. JWT에서 사용자의 tenant.id 추출 - const userTenantId = req.user.tenant.id; // number (예: 282) - - // 2. URL 파라미터의 tenantId 추출 및 타입 변환 - const requestedTenantId = parseInt(req.params.tenantId, 10); - - // 3. 일치 검증 - if (userTenantId !== requestedTenantId) { - return res.status(403).json({ - success: false, - error: { - code: "FORBIDDEN", - message: "접근 권한이 없습니다.", - details: { - userTenantId, - requestedTenantId, - reason: "테넌트 ID 불일치" - } - } - }); - } - - next(); -} -``` - -### 1. 전체 설정 조회 (GET) - -#### 엔드포인트 -``` -GET /api/tenants/{tenantId}/item-master-config -``` - -**예시**: `GET /api/tenants/282/item-master-config` - -#### Query Parameters -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| version | string | No | 버전 (기본값: latest) | -| includeInactive | boolean | No | 비활성 항목 포함 여부 (기본값: false) | - -#### Response -```typescript -{ - "success": true, - "data": { - "tenantId": 282, // ✅ number 타입 - "version": "1.0", - "lastUpdated": "2025-11-18T10:30:00Z", - "updatedBy": "TestUser3", - "config": { - // 페이지 구조 - "pages": ItemPage[], - - // 재사용 템플릿 - "sectionTemplates": SectionTemplate[], - "itemMasterFields": ItemMasterField[], - - // 마스터 데이터 - "masters": { - "specifications": SpecificationMaster[], - "materialNames": MaterialItemName[], - "categories": ItemCategory[], - "units": ItemUnit[], - "materials": ItemMaterial[], - "surfaceTreatments": SurfaceTreatment[], - "partTypes": PartTypeOption[], - "partUsages": PartUsageOption[], - "guideRailOptions": GuideRailOption[] - } - } - } -} -``` - ---- - -### 2. 전체 설정 저장 (POST/PUT) - -#### 엔드포인트 -``` -POST /api/tenants/{tenantId}/item-master-config -PUT /api/tenants/{tenantId}/item-master-config/{version} -``` - -#### Request Body -```typescript -{ - "version": "1.0", // 버전 명시 (PUT의 경우 URL의 version과 일치해야 함) - "comment": "초기 설정 저장", // 변경 사유 (선택) - "config": { - "pages": ItemPage[], - "sectionTemplates": SectionTemplate[], - "itemMasterFields": ItemMasterField[], - "masters": { - "specifications": SpecificationMaster[], - "materialNames": MaterialItemName[], - "categories": ItemCategory[], - "units": ItemUnit[], - "materials": ItemMaterial[], - "surfaceTreatments": SurfaceTreatment[], - "partTypes": PartTypeOption[], - "partUsages": PartUsageOption[], - "guideRailOptions": GuideRailOption[] - } - } -} -``` - -#### Response -```typescript -{ - "success": true, - "data": { - "tenantId": 282, // ✅ number 타입 - "version": "1.0", - "savedAt": "2025-11-18T10:30:00Z", - "savedBy": "TestUser3" - }, - "message": "설정이 성공적으로 저장되었습니다." -} -``` - ---- - -### 3. 특정 페이지 조회 (GET) - -#### 엔드포인트 -``` -GET /api/tenants/{tenantId}/item-master-config/pages/{pageId} -``` - -**예시**: `GET /api/tenants/282/item-master-config/pages/PAGE-001` - -#### Response -```typescript -{ - "success": true, - "data": { - "page": ItemPage, - "metadata": { - "tenantId": 282, // ✅ number 타입 - "version": "1.0", - "lastUpdated": "2025-11-18T10:30:00Z" - } - } -} -``` - ---- - -### 4. 특정 페이지 업데이트 (PUT) - -#### 엔드포인트 -``` -PUT /api/tenants/{tenantId}/item-master-config/pages/{pageId} -``` - -#### Request Body -```typescript -{ - "page": ItemPage, - "comment": "페이지 구조 변경" -} -``` - ---- - -### 5. 페이지 추가 (POST) - -#### 엔드포인트 -``` -POST /api/tenants/{tenantId}/item-master-config/pages -``` - -#### Request Body -```typescript -{ - "page": { - "id": "PAGE-001", - "pageName": "제품 등록", - "itemType": "FG", - "sections": [], - "isActive": true, - "createdAt": "2025-11-18T10:30:00Z" - } -} -``` - ---- - -### 6. 섹션 템플릿 관리 - -#### 엔드포인트 -``` -GET /api/tenants/{tenantId}/item-master-config/section-templates -POST /api/tenants/{tenantId}/item-master-config/section-templates -PUT /api/tenants/{tenantId}/item-master-config/section-templates/{templateId} -DELETE /api/tenants/{tenantId}/item-master-config/section-templates/{templateId} -``` - ---- - -### 7. 항목 마스터 관리 - -#### 엔드포인트 -``` -GET /api/tenants/{tenantId}/item-master-config/item-master-fields -POST /api/tenants/{tenantId}/item-master-config/item-master-fields -PUT /api/tenants/{tenantId}/item-master-config/item-master-fields/{fieldId} -DELETE /api/tenants/{tenantId}/item-master-config/item-master-fields/{fieldId} -``` - ---- - -### 8. 마스터 데이터 관리 - -각 마스터 데이터별 CRUD API - -``` -# 규격 마스터 -GET /api/tenants/{tenantId}/item-master-config/masters/specifications -POST /api/tenants/{tenantId}/item-master-config/masters/specifications -PUT /api/tenants/{tenantId}/item-master-config/masters/specifications/{id} -DELETE /api/tenants/{tenantId}/item-master-config/masters/specifications/{id} - -# 품목명 마스터 -GET /api/tenants/{tenantId}/item-master-config/masters/material-names -POST /api/tenants/{tenantId}/item-master-config/masters/material-names -PUT /api/tenants/{tenantId}/item-master-config/masters/material-names/{id} -DELETE /api/tenants/{tenantId}/item-master-config/masters/material-names/{id} - -# ... (나머지 마스터 데이터도 동일 패턴) -``` - ---- - -## 데이터 모델 - -### 1. ItemMasterConfig (전체 설정) - -```typescript -interface ItemMasterConfig { - tenantId: number; // ✅ 테넌트 ID (number 타입, 예: 282) - version: string; // 버전 (1.0, 1.1, 2.0...) - lastUpdated: string; // 마지막 업데이트 시간 (ISO 8601) - updatedBy: string; // 업데이트한 사용자 ID - comment?: string; // 변경 사유 - config: { - pages: ItemPage[]; - sectionTemplates: SectionTemplate[]; - itemMasterFields: ItemMasterField[]; - masters: { - specifications: SpecificationMaster[]; - materialNames: MaterialItemName[]; - categories: ItemCategory[]; - units: ItemUnit[]; - materials: ItemMaterial[]; - surfaceTreatments: SurfaceTreatment[]; - partTypes: PartTypeOption[]; - partUsages: PartUsageOption[]; - guideRailOptions: GuideRailOption[]; - }; - }; -} -``` - -### 2. API Response 공통 형식 - -#### 성공 응답 -```typescript -interface ApiSuccessResponse { - success: true; - data: T; - message?: string; - metadata?: { - total?: number; - page?: number; - pageSize?: number; - }; -} -``` - -#### 에러 응답 -```typescript -interface ApiErrorResponse { - success: false; - error: { - code: string; // 에러 코드 (VALIDATION_ERROR, NOT_FOUND 등) - message: string; // 사용자용 에러 메시지 - details?: any; // 상세 에러 정보 - timestamp: string; // 에러 발생 시간 - }; -} -``` - ---- - -## 저장/불러오기 시나리오 - -### 시나리오 1: 초기 설정 저장 - -**상황**: 품목기준관리 페이지에서 처음으로 설정을 저장 - -```typescript -// 1. 사용자가 Save 버튼 클릭 -// 2. Frontend에서 전체 설정 데이터 준비 -const configData = { - version: "1.0", - comment: "초기 설정", - config: { - pages: itemPages, - sectionTemplates: sectionTemplates, - itemMasterFields: itemMasterFields, - masters: { - specifications: specificationMasters, - materialNames: materialItemNames, - // ... 나머지 마스터 데이터 - } - } -}; - -// 3. API 호출 -const response = await fetch(`/api/tenants/${tenantId}/item-master-config`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(configData) -}); - -// 4. 성공 시 localStorage 업데이트 -if (response.ok) { - localStorage.setItem('mes-itemMasterConfig-version', '1.0'); - localStorage.setItem('mes-itemMasterConfig-lastSync', new Date().toISOString()); -} -``` - ---- - -### 시나리오 2: 설정 불러오기 (페이지 로드) - -**상황**: 품목기준관리 페이지 접속 시 - -```typescript -// 1. 컴포넌트 마운트 시 useEffect -useEffect(() => { - const loadConfig = async () => { - try { - // 2. 서버에서 최신 설정 조회 - const response = await fetch( - `/api/tenants/${tenantId}/item-master-config?version=latest` - ); - - const { data } = await response.json(); - - // 3. Context 상태 업데이트 - setItemPages(data.config.pages); - setSectionTemplates(data.config.sectionTemplates); - setItemMasterFields(data.config.itemMasterFields); - setSpecificationMasters(data.config.masters.specifications); - // ... 나머지 데이터 설정 - - // 4. localStorage에 캐시 - localStorage.setItem('mes-itemMasterConfig', JSON.stringify(data)); - localStorage.setItem('mes-itemMasterConfig-version', data.version); - localStorage.setItem('mes-itemMasterConfig-lastSync', new Date().toISOString()); - - } catch (error) { - // 5. 에러 시 localStorage 폴백 - const cachedConfig = localStorage.getItem('mes-itemMasterConfig'); - if (cachedConfig) { - const data = JSON.parse(cachedConfig); - // ... 캐시된 데이터로 설정 - } - } - }; - - loadConfig(); -}, [tenantId]); -``` - ---- - -### 시나리오 3: 특정 항목만 업데이트 - -**상황**: 규격 마스터 1개만 추가 - -```typescript -// 1. 새 규격 마스터 추가 -const newSpec = { - id: "SPEC-NEW-001", - specificationCode: "2.0T x 1219 x 2438", - itemType: "RM", - // ... 나머지 필드 -}; - -// 2. 부분 업데이트 API 호출 -const response = await fetch( - `/api/tenants/${tenantId}/item-master-config/masters/specifications`, - { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(newSpec) - } -); - -// 3. Context 상태 업데이트 -if (response.ok) { - addSpecificationMaster(newSpec); -} -``` - ---- - -### 시나리오 4: 버전 업그레이드 - -**상황**: 기존 설정을 기반으로 새 버전 생성 - -```typescript -// 1. 현재 버전 조회 -const currentConfig = await fetch( - `/api/tenants/${tenantId}/item-master-config?version=1.0` -).then(res => res.json()); - -// 2. 수정사항 반영 -const updatedConfig = { - ...currentConfig.data.config, - pages: [...currentConfig.data.config.pages, newPage] -}; - -// 3. 새 버전으로 저장 -const response = await fetch( - `/api/tenants/${tenantId}/item-master-config`, - { - method: 'POST', - body: JSON.stringify({ - version: "1.1", - comment: "신규 페이지 추가", - config: updatedConfig - }) - } -); -``` - ---- - -## 버전 관리 전략 - -### 1. 버전 네이밍 규칙 - -``` -{MAJOR}.{MINOR} - -MAJOR: 구조적 변경 (페이지 추가/삭제, 필드 타입 변경) -MINOR: 데이터 추가 (마스터 데이터 추가, 섹션 추가) - -예시: -1.0 - 초기 버전 -1.1 - 마스터 데이터 추가 -1.2 - 섹션 추가 -2.0 - 페이지 구조 변경 -``` - -### 2. 버전 관리 테이블 구조 - -```sql -CREATE TABLE item_master_config_versions ( - id VARCHAR(50) PRIMARY KEY, - tenant_id BIGINT NOT NULL, -- ✅ number 타입 (tenant.id와 일치) - version VARCHAR(10) NOT NULL, - config JSON NOT NULL, - comment TEXT, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - created_by VARCHAR(50), - is_active BOOLEAN DEFAULT TRUE, - - UNIQUE KEY unique_tenant_version (tenant_id, version), - INDEX idx_tenant_active (tenant_id, is_active), - FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE -); -``` - -**참고**: `tenant_id`는 BIGINT 타입으로 정의하여 로그인 응답의 `tenant.id`(number) 값과 정확히 일치하도록 합니다. - -### 3. 버전 조회 전략 - -```typescript -// Latest 버전 조회 -GET /api/tenants/{tenantId}/item-master-config?version=latest - -// 특정 버전 조회 -GET /api/tenants/{tenantId}/item-master-config?version=1.0 - -// 버전 목록 조회 -GET /api/tenants/{tenantId}/item-master-config/versions -// Response: -{ - "versions": [ - { "version": "1.0", "createdAt": "2025-11-01", "comment": "초기 버전" }, - { "version": "1.1", "createdAt": "2025-11-10", "comment": "마스터 데이터 추가" }, - { "version": "2.0", "createdAt": "2025-11-18", "comment": "페이지 구조 변경" } - ], - "current": "2.0" -} -``` - ---- - -## 에러 처리 - -### 1. 에러 코드 정의 - -| Code | HTTP Status | Description | -|------|-------------|-------------| -| `VALIDATION_ERROR` | 400 | 데이터 유효성 검증 실패 | -| `UNAUTHORIZED` | 401 | 인증 실패 | -| `FORBIDDEN` | 403 | 권한 없음 (테넌트 접근 권한 없음) | -| `NOT_FOUND` | 404 | 설정 또는 버전을 찾을 수 없음 | -| `CONFLICT` | 409 | 버전 충돌 (이미 존재하는 버전) | -| `VERSION_MISMATCH` | 409 | 버전 불일치 (동시 수정 충돌) | -| `SERVER_ERROR` | 500 | 서버 내부 오류 | - -### 2. 에러 응답 예시 - -#### Validation Error -```typescript -{ - "success": false, - "error": { - "code": "VALIDATION_ERROR", - "message": "입력 데이터가 올바르지 않습니다.", - "details": { - "field": "config.pages[0].sections[0].fields[0].property.inputType", - "message": "inputType은 필수입니다.", - "value": null - }, - "timestamp": "2025-11-18T10:30:00Z" - } -} -``` - -#### Version Conflict -```typescript -{ - "success": false, - "error": { - "code": "CONFLICT", - "message": "버전 1.0이 이미 존재합니다.", - "details": { - "existingVersion": "1.0", - "suggestedVersion": "1.1" - }, - "timestamp": "2025-11-18T10:30:00Z" - } -} -``` - ---- - -## 프론트엔드 구현 가이드 - -### 1. API 클라이언트 생성 - -```typescript -// src/lib/api/itemMasterConfigApi.ts - -export const ItemMasterConfigAPI = { - // 전체 설정 조회 - async getConfig(tenantId: number, version = 'latest') { // ✅ number 타입 - const response = await fetch( - `/api/tenants/${tenantId}/item-master-config?version=${version}` - ); - if (!response.ok) throw new Error('설정 조회 실패'); - return response.json(); - }, - - // 전체 설정 저장 - async saveConfig(tenantId: number, config: ItemMasterConfig) { // ✅ number 타입 - const response = await fetch( - `/api/tenants/${tenantId}/item-master-config`, - { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(config) - } - ); - if (!response.ok) throw new Error('설정 저장 실패'); - return response.json(); - }, - - // 페이지 조회 - async getPage(tenantId: number, pageId: string) { // ✅ number 타입 - const response = await fetch( - `/api/tenants/${tenantId}/item-master-config/pages/${pageId}` - ); - if (!response.ok) throw new Error('페이지 조회 실패'); - return response.json(); - }, - - // 규격 마스터 추가 - async addSpecification(tenantId: number, spec: SpecificationMaster) { // ✅ number 타입 - const response = await fetch( - `/api/tenants/${tenantId}/item-master-config/masters/specifications`, - { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify(spec) - } - ); - if (!response.ok) throw new Error('규격 추가 실패'); - return response.json(); - } -}; -``` - -**사용 예시**: -```typescript -// AuthContext에서 tenant.id를 추출하여 사용 -const { user } = useAuth(); -const tenantId = user.tenant.id; // number 타입 (예: 282) - -// API 호출 -const config = await ItemMasterConfigAPI.getConfig(tenantId); -``` - -### 2. Context 통합 - -```typescript -// ItemMasterContext.tsx - -// 서버 동기화 함수 추가 -const syncWithServer = async () => { - try { - const { data } = await ItemMasterConfigAPI.getConfig(tenantId); - - // 모든 상태 업데이트 - setItemPages(data.config.pages); - setSectionTemplates(data.config.sectionTemplates); - // ... 나머지 데이터 - - // localStorage 캐시 - localStorage.setItem('mes-itemMasterConfig', JSON.stringify(data)); - localStorage.setItem('mes-itemMasterConfig-lastSync', new Date().toISOString()); - - } catch (error) { - console.error('서버 동기화 실패:', error); - // localStorage 폴백 - } -}; - -// 저장 함수 추가 -const saveToServer = async () => { - try { - const configData = { - version: currentVersion, - comment: saveComment, - config: { - pages: itemPages, - sectionTemplates: sectionTemplates, - itemMasterFields: itemMasterFields, - masters: { - specifications: specificationMasters, - materialNames: materialItemNames, - // ... 나머지 - } - } - }; - - await ItemMasterConfigAPI.saveConfig(tenantId, configData); - - } catch (error) { - console.error('저장 실패:', error); - throw error; - } -}; -``` - ---- - -## 다음 단계 - -### Phase 1: API 모킹 (현재) -1. ✅ API 구조 설계 완료 -2. ⏳ Mock API 서버 구현 (MSW 또는 json-server) -3. ⏳ 프론트엔드 API 클라이언트 구현 -4. ⏳ Context와 API 통합 - -### Phase 2: 백엔드 구현 -1. ⏳ 데이터베이스 스키마 설계 -2. ⏳ API 엔드포인트 구현 -3. ⏳ 인증/권한 처리 -4. ⏳ 버전 관리 로직 구현 - -### Phase 3: 품목관리 페이지 동적 생성 -1. ⏳ 설정 기반 폼 렌더러 구현 -2. ⏳ 조건부 표시 로직 구현 -3. ⏳ 유효성 검증 구현 -4. ⏳ 실제 품목 데이터 저장 API 연동 - ---- - -## 부록 - -### A. localStorage 키 규칙 - -**❌ 기존 (tenant.id 없음 - 데이터 오염 위험)**: -```typescript -// 테넌트 ID가 없어서 테넌트 전환 시 데이터 오염 발생! -'mes-itemMasterConfig' -'mes-specificationMasters' -``` - -**✅ 권장 (tenant.id 포함 - 완전한 격리)**: -```typescript -// 설정 데이터 (tenant.id 포함) -`mes-${tenantId}-itemMasterConfig` // 예: 'mes-282-itemMasterConfig' -`mes-${tenantId}-itemMasterConfig-version` -`mes-${tenantId}-itemMasterConfig-lastSync` - -// 개별 마스터 데이터 (tenant.id + 버전 포함) -`mes-${tenantId}-specificationMasters` // 예: 'mes-282-specificationMasters' -`mes-${tenantId}-specificationMasters-version` -`mes-${tenantId}-materialItemNames` -`mes-${tenantId}-materialItemNames-version` -`mes-${tenantId}-itemCategories` -`mes-${tenantId}-itemUnits` -`mes-${tenantId}-itemMaterials` -`mes-${tenantId}-surfaceTreatments` -`mes-${tenantId}-partTypeOptions` -`mes-${tenantId}-partUsageOptions` -`mes-${tenantId}-guideRailOptions` -``` - -**구현 예시**: -```typescript -// TenantAwareCache 클래스 사용 (권장) -// 자세한 구현은 [REF-2025-11-19] multi-tenancy-implementation.md 참조 -const cache = new TenantAwareCache(user.tenant.id); -cache.set('itemMasterConfig', configData); - -// 또는 직접 구현 -const key = `mes-${user.tenant.id}-itemMasterConfig`; // 'mes-282-itemMasterConfig' -localStorage.setItem(key, JSON.stringify(configData)); -``` - -**테넌트 전환 시 캐시 삭제**: -```typescript -// 로그아웃 또는 테넌트 전환 시 -function clearTenantCache(tenantId: number) { - const keys = Object.keys(localStorage); - const prefix = `mes-${tenantId}-`; - keys.forEach(key => { - if (key.startsWith(prefix)) { - localStorage.removeItem(key); - } - }); -} -``` - -### B. 타입 정의 파일 위치 - -``` -src/ -├─ types/ -│ ├─ itemMaster.ts # 품목 관련 타입 -│ ├─ itemMasterConfig.ts # 설정 관련 타입 -│ └─ api.ts # API 응답 타입 -├─ lib/ -│ └─ api/ -│ └─ itemMasterConfigApi.ts # API 클라이언트 -└─ contexts/ - └─ ItemMasterContext.tsx # Context (기존) -``` - ---- - -**문서 버전**: 1.0 -**마지막 업데이트**: 2025-11-18 \ No newline at end of file diff --git a/claudedocs/_ITEM_MASTER_API_STRUCTURE.md b/claudedocs/_ITEM_MASTER_API_STRUCTURE.md deleted file mode 100644 index 49861c33..00000000 --- a/claudedocs/_ITEM_MASTER_API_STRUCTURE.md +++ /dev/null @@ -1,1388 +0,0 @@ -# 품목기준관리 API 구조 - -## 목차 -1. [최초 화면 접근 시 필요한 API](#최초-화면-접근-시-필요한-api) -2. [각 항목별 저장 API](#각-항목별-저장-api) -3. [API 응답 구조](#api-응답-구조) -4. [에러 처리](#에러-처리) - ---- - -## 최초 화면 접근 시 필요한 API - -페이지 로드 시 `tenant.id` 기준으로 모든 기준정보를 조회합니다. - -### 1. 전체 설정 조회 (통합 API) - -**엔드포인트**: `GET /api/tenants/{tenantId}/item-master-config` - -**목적**: 모든 기준정보를 한 번에 조회 (성능 최적화) - -**Next.js 프록시**: `/api/tenants/[tenantId]/item-master-config/route.ts` - -**요청 예시**: -```http -GET /api/tenants/282/item-master-config HTTP/1.1 -Authorization: Bearer {access_token} -X-API-KEY: {api_key} -``` - -**PHP 백엔드 엔드포인트**: -``` -GET /api/v1/tenants/282/item-master-config -``` - -**응답 구조**: -```json -{ - "success": true, - "data": { - "tenantId": 282, - "itemMasters": [], - "specificationMasters": [...], - "materialItemNames": [...], - "itemCategories": [...], - "itemUnits": [...], - "itemMaterials": [...], - "surfaceTreatments": [...], - "partTypeOptions": [...], - "partUsageOptions": [...], - "guideRailOptions": [...], - "itemMasterFields": [...], - "itemPages": [...] - } -} -``` - -### 2. 개별 조회 API (선택적 사용) - -필요 시 개별 항목만 조회할 수 있습니다. - -#### 2.1 규격 마스터 -```http -GET /api/tenants/{tenantId}/item-master-config/specification-masters -``` - -#### 2.2 자재 품목명 -```http -GET /api/tenants/{tenantId}/item-master-config/material-item-names -``` - -#### 2.3 품목 카테고리 -```http -GET /api/tenants/{tenantId}/item-master-config/item-categories -``` - -#### 2.4 품목 단위 -```http -GET /api/tenants/{tenantId}/item-master-config/item-units -``` - -#### 2.5 품목 재질 -```http -GET /api/tenants/{tenantId}/item-master-config/item-materials -``` - -#### 2.6 표면처리 -```http -GET /api/tenants/{tenantId}/item-master-config/surface-treatments -``` - -#### 2.7 부품 타입 옵션 -```http -GET /api/tenants/{tenantId}/item-master-config/part-type-options -``` - -#### 2.8 부품 용도 옵션 -```http -GET /api/tenants/{tenantId}/item-master-config/part-usage-options -``` - -#### 2.9 가이드레일 옵션 -```http -GET /api/tenants/{tenantId}/item-master-config/guide-rail-options -``` - -#### 2.10 품목 마스터 필드 -```http -GET /api/tenants/{tenantId}/item-master-config/item-master-fields -``` - -#### 2.11 품목 페이지 -```http -GET /api/tenants/{tenantId}/item-master-config/item-pages -``` - ---- - -## 각 항목별 저장 API - -각 섹션의 저장 버튼 클릭 시 호출되는 API입니다. - -### 1. 규격 마스터 (Specification Master) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/specification-masters -Content-Type: application/json - -{ - "specificationCode": "1219*1200", - "itemType": "RM", - "itemName": "SPHC-SD", - "fieldCount": "1", - "thickness": "1.6", - "widthA": "1219", - "length": "1200", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/specification-masters/{specId} -Content-Type: application/json - -{ - "specificationCode": "1219*1200", - "thickness": "1.8", - "isActive": true -} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/specification-masters/{specId} -``` - -#### 일괄 저장 (추천) -```http -POST /api/tenants/{tenantId}/item-master-config/specification-masters/bulk -Content-Type: application/json - -{ - "items": [ - { "specificationCode": "1219*1200", ... }, - { "specificationCode": "1219*2438", ... } - ] -} -``` - -### 2. 자재 품목명 (Material Item Name) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/material-item-names -Content-Type: application/json - -{ - "itemType": "RM", - "itemName": "SPHC-SD", - "category": "냉연강판", - "description": "일반냉연강판", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/material-item-names/{materialId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/material-item-names/{materialId} -``` - -#### 일괄 저장 -```http -POST /api/tenants/{tenantId}/item-master-config/material-item-names/bulk -``` - -### 3. 품목 카테고리 (Item Category) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/item-categories -Content-Type: application/json - -{ - "categoryType": "PRODUCT", - "category1": "스크린", - "code": "SC", - "description": "스크린 셔터", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/item-categories/{categoryId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/item-categories/{categoryId} -``` - -### 4. 품목 단위 (Item Unit) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/item-units -Content-Type: application/json - -{ - "unitCode": "EA", - "unitName": "EA (개)", - "description": "낱개 단위", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/item-units/{unitId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/item-units/{unitId} -``` - -### 5. 품목 재질 (Item Material) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/item-materials -Content-Type: application/json - -{ - "materialCode": "EGI-1.2T", - "materialName": "EGI 1.2T", - "materialType": "STEEL", - "thickness": "1.2T", - "description": "전기아연도금강판", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/item-materials/{materialId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/item-materials/{materialId} -``` - -### 6. 표면처리 (Surface Treatment) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/surface-treatments -Content-Type: application/json - -{ - "treatmentCode": "POWDER", - "treatmentName": "파우더도장", - "treatmentType": "PAINTING", - "description": "분체도장", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/surface-treatments/{treatmentId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/surface-treatments/{treatmentId} -``` - -### 7. 부품 타입 옵션 (Part Type Option) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/part-type-options -Content-Type: application/json - -{ - "partType": "ASSEMBLY", - "optionCode": "ASSY", - "optionName": "조립품", - "description": "여러 부품을 조립하는 부품", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/part-type-options/{optionId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/part-type-options/{optionId} -``` - -### 8. 부품 용도 옵션 (Part Usage Option) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/part-usage-options -Content-Type: application/json - -{ - "usageCode": "GUIDE_RAIL", - "usageName": "가이드레일", - "description": "가이드레일용 부품", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/part-usage-options/{optionId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/part-usage-options/{optionId} -``` - -### 9. 가이드레일 옵션 (Guide Rail Option) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/guide-rail-options -Content-Type: application/json - -{ - "optionType": "MODEL_TYPE", - "optionCode": "SCREEN", - "optionName": "스크린용", - "description": "스크린 셔터용 가이드레일", - "parentOption": null, - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/guide-rail-options/{optionId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/guide-rail-options/{optionId} -``` - -### 10. 품목 마스터 필드 (Item Master Field) - -#### 등록 -```http -POST /api/tenants/{tenantId}/item-master-config/item-master-fields -Content-Type: application/json - -{ - "name": "품목코드", - "fieldKey": "itemCode", - "property": { - "inputType": "textbox", - "required": true, - "row": 1, - "col": 1 - }, - "category": "공통", - "description": "품목의 고유 코드", - "isActive": true -} -``` - -#### 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/item-master-fields/{fieldId} -``` - -#### 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/item-master-fields/{fieldId} -``` - -### 11. 품목 페이지 (Item Page) - -#### 페이지 조회 -```http -GET /api/tenants/{tenantId}/item-master-config/pages/{pageId} -``` - -**Next.js 프록시**: `/api/tenants/[tenantId]/item-master-config/pages/[pageId]/route.ts` - -#### 페이지 생성 -```http -POST /api/tenants/{tenantId}/item-master-config/pages -Content-Type: application/json - -{ - "pageName": "품목 등록", - "itemType": "FG", - "isActive": true, - "sections": [ - { - "title": "기본정보", - "order": 1, - "isCollapsible": true, - "isCollapsed": false, - "fields": [ - { - "name": "품목코드", - "fieldKey": "itemCode", - "property": { "inputType": "textbox", "required": true, "row": 1, "col": 1 } - } - ] - } - ] -} -``` - -#### 페이지 수정 -```http -PUT /api/tenants/{tenantId}/item-master-config/pages/{pageId} -Content-Type: application/json - -{ - "pageName": "품목 등록 (수정)", - "isActive": true, - "sections": [...] -} -``` - -**Next.js 프록시**: `/api/tenants/[tenantId]/item-master-config/pages/[pageId]/route.ts` - -#### 페이지 삭제 -```http -DELETE /api/tenants/{tenantId}/item-master-config/pages/{pageId} -``` - -**Next.js 프록시**: `/api/tenants/[tenantId]/item-master-config/pages/[pageId]/route.ts` - ---- - -## API 응답 샘플 데이터 - -아래 샘플 데이터는 프론트엔드에서 주석 처리한 Mock 데이터이며, **백엔드 API 응답의 실제 구조 및 데이터 예시**입니다. - -### 1. 규격 마스터 (Specification Masters) - -**샘플 데이터** (27개 중 일부): - -```json -[ - { - "id": "spec-001", - "specificationCode": "1219*1200", - "itemType": "RM", - "itemName": "SPHC-SD", - "fieldCount": "1", - "thickness": "1.6", - "widthA": "1219", - "length": "1200", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "spec-002", - "specificationCode": "1219*2438", - "itemType": "RM", - "itemName": "SPHC-SD", - "fieldCount": "1", - "thickness": "1.6", - "widthA": "1219", - "length": "2438", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "spec-022", - "specificationCode": "1219*1200", - "itemType": "RM", - "itemName": "STS304", - "fieldCount": "1", - "thickness": "1.5", - "widthA": "1219", - "length": "1200", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - } -] -``` - -**데이터 설명**: -- 총 27개 규격: SPHC-SD, SPCC-SD, SECC, SGCC, SPHD, SS330, SS400, STS304, STS430 -- 각 자재별로 3가지 길이 (1200, 2438, 3000mm) 규격 존재 - -### 2. 자재 품목명 (Material Item Names) - -**샘플 데이터** (139개 중 일부): - -```json -[ - { - "id": "mat-001", - "itemType": "RM", - "itemName": "SPHC-SD", - "category": "냉연강판", - "description": "일반냉연강판", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "mat-008", - "itemType": "RM", - "itemName": "STS304", - "category": "스테인리스", - "description": "스테인리스강판 304", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "mat-101", - "itemType": "SM", - "itemName": "육각볼트", - "category": "체결부품", - "description": "육각머리볼트", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "mat-201", - "itemType": "SM", - "itemName": "용접봉", - "category": "용접재료", - "description": "용접봉", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - }, - { - "id": "mat-301", - "itemType": "SM", - "itemName": "도료(백색)", - "category": "도장재료", - "description": "백색도료", - "isActive": true, - "createdAt": "2025-01-19T10:00:00Z" - } -] -``` - -**데이터 분류**: -- **원자재 (RM)**: 21개 (냉연강판, 스테인리스, 알루미늄, 파이프류, 형강류, 비철금속) -- **부자재 (SM)**: 118개 - - 체결부품 (mat-101~111): 볼트, 너트, 와셔, 나사 등 - - 용접/접착 (mat-201~207): 용접봉, 실리콘, 에폭시 등 - - 도장/표면처리 (mat-301~306): 도료, 프라이머 등 - - 연마/연삭 (mat-401~404): 연마지, 절단석 등 - - 기타 부자재 (mat-501~539): 패킹, 베어링, 모터, 샤프트 등 - -### 3. 품목 카테고리 (Item Categories) - -**샘플 데이터** (14개): - -```json -[ - { - "id": "CAT-001", - "categoryType": "PRODUCT", - "category1": "스크린", - "code": "SC", - "description": "스크린 셔터", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "CAT-101", - "categoryType": "PART", - "category1": "가이드레일", - "code": "GR", - "description": "가이드레일 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "CAT-201", - "categoryType": "MATERIAL", - "category1": "강판", - "code": "SP", - "description": "강판 원자재", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "CAT-301", - "categoryType": "SUB_MATERIAL", - "category1": "볼트너트", - "code": "BN", - "description": "볼트/너트", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -**카테고리 타입 분류**: -- **PRODUCT**: 완제품 (스크린, 철재문, 블라인드) -- **PART**: 부품 (가이드레일, 하단마감재, 케이스, 도어, 브라켓) -- **MATERIAL**: 원자재 (강판, 알루미늄, 플라스틱) -- **SUB_MATERIAL**: 부자재 (볼트너트, 나사, 페인트) - -### 4. 품목 단위 (Item Units) - -**샘플 데이터** (7개): - -```json -[ - { - "id": "UNIT-001", - "unitCode": "EA", - "unitName": "EA (개)", - "description": "낱개 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "UNIT-002", - "unitCode": "SET", - "unitName": "SET (세트)", - "description": "세트 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "UNIT-003", - "unitCode": "M", - "unitName": "M (미터)", - "description": "길이 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "UNIT-004", - "unitCode": "KG", - "unitName": "KG (킬로그램)", - "description": "무게 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "UNIT-006", - "unitCode": "M2", - "unitName": "㎡ (제곱미터)", - "description": "면적 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "UNIT-007", - "unitCode": "BOX", - "unitName": "BOX (박스)", - "description": "박스 단위", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -### 5. 품목 재질 (Item Materials) - -**샘플 데이터** (7개): - -```json -[ - { - "id": "MAT-001", - "materialCode": "EGI-1.2T", - "materialName": "EGI 1.2T", - "materialType": "STEEL", - "thickness": "1.2T", - "description": "전기아연도금강판", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MAT-002", - "materialCode": "EGI-1.55T", - "materialName": "EGI 1.55T", - "materialType": "STEEL", - "thickness": "1.55T", - "description": "전기아연도금강판", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MAT-004", - "materialCode": "SUS-1.2T", - "materialName": "SUS 1.2T", - "materialType": "STEEL", - "thickness": "1.2T", - "description": "스테인리스 강판", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MAT-006", - "materialCode": "AL-6063", - "materialName": "알루미늄 6063", - "materialType": "ALUMINUM", - "description": "알루미늄 압출재", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -**재질 타입**: -- **STEEL**: EGI (전기아연도금강판), SUS (스테인리스) -- **ALUMINUM**: AL-6063, AL-6061 - -### 6. 표면처리 (Surface Treatments) - -**샘플 데이터** (5개): - -```json -[ - { - "id": "TREAT-001", - "treatmentCode": "NONE", - "treatmentName": "무도장", - "treatmentType": "NONE", - "description": "표면처리 없음", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "TREAT-002", - "treatmentCode": "POWDER", - "treatmentName": "파우더도장", - "treatmentType": "PAINTING", - "description": "분체도장", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "TREAT-003", - "treatmentCode": "ANODIZING", - "treatmentName": "아노다이징", - "treatmentType": "COATING", - "description": "알루미늄 양극산화처리", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "TREAT-004", - "treatmentCode": "ZINC", - "treatmentName": "아연도금", - "treatmentType": "PLATING", - "description": "아연 도금처리", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -**처리 타입**: -- **NONE**: 무도장 -- **PAINTING**: 도장 (파우더도장) -- **COATING**: 코팅 (아노다이징) -- **PLATING**: 도금 (아연도금, 크롬도금) - -### 7. 부품 타입 옵션 (Part Type Options) - -**샘플 데이터** (3개): - -```json -[ - { - "id": "PTYPE-001", - "partType": "ASSEMBLY", - "optionCode": "ASSY", - "optionName": "조립품", - "description": "여러 부품을 조립하는 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "PTYPE-002", - "partType": "BENDING", - "optionCode": "BEND", - "optionName": "절곡품", - "description": "절곡 가공 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "PTYPE-003", - "partType": "PURCHASED", - "optionCode": "PURCH", - "optionName": "구매품", - "description": "외부에서 구매하는 부품", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -### 8. 부품 용도 옵션 (Part Usage Options) - -**샘플 데이터** (6개): - -```json -[ - { - "id": "USAGE-001", - "usageCode": "GUIDE_RAIL", - "usageName": "가이드레일", - "description": "가이드레일용 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "USAGE-002", - "usageCode": "BOTTOM_FINISH", - "usageName": "하단마감재", - "description": "하단마감재용 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "USAGE-003", - "usageCode": "CASE", - "usageName": "케이스", - "description": "케이스용 부품", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "USAGE-004", - "usageCode": "DOOR", - "usageName": "도어", - "description": "도어용 부품", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -### 9. 가이드레일 옵션 (Guide Rail Options) - -**샘플 데이터** (13개 중 일부): - -```json -[ - { - "id": "GR-001", - "optionType": "MODEL_TYPE", - "optionCode": "SCREEN", - "optionName": "스크린용", - "description": "스크린 셔터용 가이드레일", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "GR-011", - "optionType": "MODEL", - "optionCode": "T40", - "optionName": "T40", - "parentOption": "SCREEN", - "description": "T40 모델", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "GR-021", - "optionType": "CERTIFICATION", - "optionCode": "KFI", - "optionName": "KFI인증", - "description": "KFI 인증", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "GR-031", - "optionType": "SHAPE", - "optionCode": "ROUND", - "optionName": "R형", - "description": "라운드형", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "GR-041", - "optionType": "FINISH", - "optionCode": "POWDER", - "optionName": "파우더도장", - "description": "파우더 도장 마감", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "GR-051", - "optionType": "LENGTH", - "optionCode": "3000", - "optionName": "3000mm", - "description": "3미터", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -**옵션 타입 분류**: -- **MODEL_TYPE**: 제품 유형 (스크린용, 철재용) -- **MODEL**: 모델명 (T40, T60, 프리미엄) - `parentOption` 참조 -- **CERTIFICATION**: 인증 (KFI인증, 미인증) -- **SHAPE**: 형상 (R형, ㄱ형) -- **FINISH**: 마감 (파우더도장, 아노다이징) -- **LENGTH**: 길이 (3000mm, 4000mm, 5000mm) - -### 10. 품목 마스터 필드 (Item Master Fields) - -**샘플 데이터** (5개): - -```json -[ - { - "id": "MASTER-001", - "name": "품목코드", - "fieldKey": "itemCode", - "property": { - "inputType": "textbox", - "required": true, - "row": 1, - "col": 1 - }, - "category": "공통", - "description": "품목의 고유 코드", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MASTER-002", - "name": "품목명", - "fieldKey": "itemName", - "property": { - "inputType": "textbox", - "required": true, - "row": 1, - "col": 1 - }, - "category": "공통", - "description": "품목의 이름", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MASTER-003", - "name": "단위", - "fieldKey": "unit", - "property": { - "inputType": "dropdown", - "required": true, - "row": 1, - "col": 1, - "options": ["EA", "SET", "KG", "M", "BOX"] - }, - "category": "공통", - "description": "품목의 단위", - "isActive": true, - "createdAt": "2025-01-01" - }, - { - "id": "MASTER-004", - "name": "재질", - "fieldKey": "material", - "property": { - "inputType": "dropdown", - "required": false, - "row": 1, - "col": 1, - "options": ["EGI 1.2T", "SUS 1.2T", "AL 1.5T"] - }, - "category": "부품", - "description": "부품의 재질", - "isActive": true, - "createdAt": "2025-01-01" - } -] -``` - -**inputType 종류**: -- `textbox`: 텍스트 입력 -- `dropdown`: 드롭다운 선택 (options 필수) - -### 11. 품목 페이지 (Item Pages) - -**샘플 구조** (실제 Mock 데이터는 빈 배열): - -```json -[ - { - "id": "PAGE-001", - "pageName": "제품 등록", - "itemType": "FG", - "isActive": true, - "createdAt": "2025-01-01", - "sections": [ - { - "id": "SECTION-001", - "title": "기본정보", - "order": 1, - "isCollapsible": true, - "isCollapsed": false, - "fields": [ - { - "name": "품목코드", - "fieldKey": "itemCode", - "property": { - "inputType": "textbox", - "required": true, - "row": 1, - "col": 1 - } - }, - { - "name": "품목명", - "fieldKey": "itemName", - "property": { - "inputType": "textbox", - "required": true, - "row": 1, - "col": 2 - } - } - ] - } - ] - } -] -``` - -### 전체 설정 조회 API 응답 예시 - -`GET /api/tenants/282/item-master-config` 응답: - -```json -{ - "success": true, - "data": { - "tenantId": 282, - "itemMasters": [], - "specificationMasters": [ - /* 위의 27개 규격 마스터 데이터 */ - ], - "materialItemNames": [ - /* 위의 139개 자재 품목명 데이터 */ - ], - "itemCategories": [ - /* 위의 14개 품목 카테고리 데이터 */ - ], - "itemUnits": [ - /* 위의 7개 품목 단위 데이터 */ - ], - "itemMaterials": [ - /* 위의 7개 품목 재질 데이터 */ - ], - "surfaceTreatments": [ - /* 위의 5개 표면처리 데이터 */ - ], - "partTypeOptions": [ - /* 위의 3개 부품 타입 옵션 데이터 */ - ], - "partUsageOptions": [ - /* 위의 6개 부품 용도 옵션 데이터 */ - ], - "guideRailOptions": [ - /* 위의 13개 가이드레일 옵션 데이터 */ - ], - "itemMasterFields": [ - /* 위의 5개 품목 마스터 필드 데이터 */ - ], - "itemPages": [] - } -} -``` - -**주의사항**: -- `id` 필드는 백엔드에서 자동 생성 (UUID 또는 Auto Increment) -- `createdAt`, `updatedAt` 필드는 백엔드에서 자동 관리 -- Mock 데이터의 날짜는 예시용이며, 실제로는 백엔드에서 생성된 timestamp 사용 - ---- - -## API 응답 구조 - -### 성공 응답 -```json -{ - "success": true, - "data": { - "id": "spec-001", - "specificationCode": "1219*1200", - "itemType": "RM", - "itemName": "SPHC-SD", - "createdAt": "2025-01-19T10:00:00Z", - "updatedAt": "2025-01-19T10:00:00Z" - } -} -``` - -### 에러 응답 -```json -{ - "success": false, - "error": { - "code": "VALIDATION_ERROR", - "message": "필수 필드가 누락되었습니다.", - "details": { - "field": "itemName", - "reason": "required" - } - } -} -``` - -### 일괄 저장 응답 -```json -{ - "success": true, - "data": { - "total": 10, - "created": 8, - "updated": 2, - "failed": 0, - "items": [...] - } -} -``` - ---- - -## 에러 처리 - -### HTTP 상태 코드 - -| 코드 | 의미 | 설명 | -|------|------|------| -| 200 | OK | 성공 | -| 201 | Created | 생성 성공 | -| 400 | Bad Request | 잘못된 요청 | -| 401 | Unauthorized | 인증 실패 | -| 403 | Forbidden | 권한 없음 (테넌트 불일치) | -| 404 | Not Found | 리소스 없음 | -| 409 | Conflict | 중복 데이터 | -| 500 | Internal Server Error | 서버 오류 | - -### 에러 코드 - -| 에러 코드 | 설명 | -|----------|------| -| `VALIDATION_ERROR` | 유효성 검사 실패 | -| `UNAUTHORIZED` | 인증 필요 | -| `FORBIDDEN` | 권한 없음 | -| `NOT_FOUND` | 리소스 없음 | -| `DUPLICATE` | 중복 데이터 | -| `SERVER_ERROR` | 서버 오류 | - ---- - -## Next.js API Routes 구조 - -### 기존 구현 완료 -1. ✅ `/api/tenants/[tenantId]/item-master-config/route.ts` - - GET: 전체 설정 조회 - - POST: 전체 설정 생성 - - PUT: 전체 설정 수정 - -2. ✅ `/api/tenants/[tenantId]/item-master-config/pages/[pageId]/route.ts` - - GET: 특정 페이지 조회 - - PUT: 특정 페이지 수정 - - DELETE: 특정 페이지 삭제 - -### 추가 필요 (선택사항) -개별 항목 CRUD가 필요한 경우 추가 라우트 생성: -``` -/api/tenants/[tenantId]/item-master-config/ - ├── specification-masters/ - ├── material-item-names/ - ├── item-categories/ - ├── item-units/ - ├── item-materials/ - ├── surface-treatments/ - ├── part-type-options/ - ├── part-usage-options/ - ├── guide-rail-options/ - ├── item-master-fields/ - └── pages/ - └── [pageId]/ -``` - ---- - -## 캐싱 전략 - -### TenantAwareCache 사용 -```typescript -// ItemMasterContext.tsx에서 구현됨 -cache.set('itemMasters', data, 3600000); // 1시간 TTL -cache.set('specificationMasters', data, 3600000); -// ... 기타 항목들 -``` - -### 캐시 키 구조 -``` -mes-{tenantId}-itemMasters -mes-{tenantId}-specificationMasters -mes-{tenantId}-materialItemNames -mes-{tenantId}-itemCategories -mes-{tenantId}-itemUnits -mes-{tenantId}-itemMaterials -mes-{tenantId}-surfaceTreatments -mes-{tenantId}-partTypeOptions -mes-{tenantId}-partUsageOptions -mes-{tenantId}-guideRailOptions -mes-{tenantId}-itemMasterFields -mes-{tenantId}-itemPages -``` - -### 캐시 무효화 -- 테넌트 전환 시: 이전 테넌트 캐시 자동 삭제 -- 로그아웃 시: 현재 테넌트 캐시 삭제 -- 데이터 저장 시: 해당 항목 캐시 무효화 - ---- - -## 프론트엔드 구현 체크리스트 - -### ItemMasterContext.tsx -- [ ] Mock 데이터 주석 처리 -- [ ] API 호출 함수 구현 -- [ ] TenantAwareCache 연동 -- [ ] 에러 처리 추가 -- [ ] 로딩 상태 관리 - -### ItemMasterDataManagement.tsx -- [ ] 각 섹션별 저장 버튼 이벤트 -- [ ] API 호출 로직 -- [ ] 성공/실패 토스트 메시지 -- [ ] 낙관적 업데이트 (Optimistic UI) -- [ ] 에러 핸들링 - -### 백엔드 요구사항 - -#### 필수 구현 -- [ ] PHP `/api/v1/tenants/{tenantId}/item-master-config` 엔드포인트 구현 -- [ ] 테넌트 검증 로직 (인증된 사용자의 tenant.id와 URL의 tenantId 일치 확인) -- [ ] 데이터베이스 테이블 생성 -- [ ] 트랜잭션 처리 -- [ ] 에러 응답 표준화 - -#### DB 초기 데이터 등록 (Seeding) - -**중요**: 모든 데이터는 API로 제공되므로, DB에 초기 데이터 등록이 필수입니다. - -**시스템 기본값** (모든 테넌트 공통 또는 테넌트 생성 시 자동 복사): - -1. **품목 단위** (7개) - - EA, SET, M, KG, L, M2, BOX - - 우선순위: 🔴 높음 (필수) - -2. **품목 재질** (7개) - - EGI-1.2T, EGI-1.55T, EGI-2.0T, SUS-1.2T, SUS-1.5T, AL-6063, AL-6061 - - 우선순위: 🔴 높음 (필수) - -3. **표면처리** (5개) - - 무도장, 파우더도장, 아노다이징, 아연도금, 크롬도금 - - 우선순위: 🔴 높음 (필수) - -4. **품목 카테고리** (14개) - - PRODUCT, PART, MATERIAL, SUB_MATERIAL 타입별 카테고리 - - 우선순위: 🟡 중간 - -5. **부품 타입 옵션** (3개) - - 조립품, 절곡품, 구매품 - - 우선순위: 🟡 중간 - -6. **부품 용도 옵션** (6개) - - 가이드레일, 하단마감재, 케이스, 도어, 브라켓, 일반 - - 우선순위: 🟡 중간 - -7. **품목 마스터 필드** (5개) - - 품목코드, 품목명, 단위, 재질, 표면처리 - - 우선순위: 🟡 중간 - -**테넌트별 데이터** (선택적, 빈 배열로 시작 가능): - -8. **규격 마스터** (27개 샘플) - - 우선순위: 🟢 낮음 (테스트/샘플 데이터) - -9. **자재 품목명** (139개 샘플) - - 우선순위: 🟢 낮음 (테스트/샘플 데이터) - -10. **가이드레일 옵션** (13개 샘플) - - 우선순위: 🟢 낮음 (테스트/샘플 데이트) - -**초기 데이터 등록 방법**: -```sql --- 예시: 품목 단위 초기 데이터 -INSERT INTO item_units (tenant_id, unitCode, unitName, description, isActive) VALUES - (NULL, 'EA', 'EA (개)', '낱개 단위', true), -- tenant_id NULL = 전체 공통 - (NULL, 'SET', 'SET (세트)', '세트 단위', true), - (NULL, 'M', 'M (미터)', '길이 단위', true), - (NULL, 'KG', 'KG (킬로그램)', '무게 단위', true), - (NULL, 'L', 'L (리터)', '부피 단위', true), - (NULL, 'M2', '㎡ (제곱미터)', '면적 단위', true), - (NULL, 'BOX', 'BOX (박스)', '박스 단위', true); - --- 또는 테넌트 생성 시 자동 복사 -CREATE TRIGGER copy_default_data_on_tenant_create -AFTER INSERT ON tenants -FOR EACH ROW -BEGIN - -- 기본값 자동 복사 로직 -END; -``` - -**API 응답 예시**: -```json -{ - "success": true, - "data": { - "tenantId": 282, - "itemUnits": [ - { - "id": "UNIT-001", - "unitCode": "EA", - "unitName": "EA (개)", - "description": "낱개 단위", - "isActive": true - } - // ... 6개 더 - ], - "itemMaterials": [/* 7개 기본 재질 */], - "surfaceTreatments": [/* 5개 기본 표면처리 */], - "itemCategories": [/* 14개 */], - "partTypeOptions": [/* 3개 */], - "partUsageOptions": [/* 6개 */], - "itemMasterFields": [/* 5개 */], - "specificationMasters": [], // 빈 배열 (테넌트별 데이터) - "materialItemNames": [], - "guideRailOptions": [], - "itemPages": [] - } -} -``` - -**참고**: 위의 "API 응답 샘플 데이터" 섹션에 모든 초기 데이터의 상세 구조가 포함되어 있습니다. \ No newline at end of file diff --git a/src/app/api/proxy/[...path]/route.ts b/src/app/api/proxy/[...path]/route.ts new file mode 100644 index 00000000..a38e8a49 --- /dev/null +++ b/src/app/api/proxy/[...path]/route.ts @@ -0,0 +1,244 @@ +import { NextRequest, NextResponse } from 'next/server'; + +/** + * 🔵 Catch-All API Proxy (HttpOnly Cookie Pattern) + * + * ⚡ 설계 목적: + * - HttpOnly 쿠키 보안 유지: JavaScript 접근 차단 + * - 모든 백엔드 API를 단일 프록시로 처리 + * - 서버에서 쿠키 읽어 Authorization 헤더 자동 추가 + * + * 🔄 동작 흐름: + * 1. 클라이언트 → Next.js /api/proxy/* (토큰 없이) + * 2. Next.js: HttpOnly 쿠키에서 access_token 읽기 (서버에서만 가능) + * 3. Next.js → PHP Backend /api/v1/* (Authorization 헤더 포함) + * 4. PHP Backend → Next.js (응답) + * 5. Next.js → 클라이언트 (응답 전달) + * + * 🔐 보안 특징: + * - HttpOnly 쿠키: JavaScript 접근 불가 (XSS 방지) + * - 서버 사이드 토큰 처리: 브라우저에 토큰 노출 안됨 + * - 자동 인증 헤더 추가: 클라이언트는 신경 쓸 필요 없음 + * + * 📍 사용 예시: + * - Frontend: fetch('/api/proxy/item-master/init') + * - Backend: GET https://api.codebridge-x.com/api/v1/item-master/init + * + * ⚠️ 주의: + * - 로그아웃 API(/api/auth/logout)와 동일한 패턴 + * - 모든 HTTP 메서드 지원 (GET, POST, PUT, DELETE) + * - 쿼리 파라미터와 요청 바디 모두 전달 + */ + +/** + * 토큰 갱신 함수 (access_token 만료 시 refresh_token으로 갱신) + */ +async function refreshAccessToken(refreshToken: string): Promise<{ + success: boolean; + accessToken?: string; + refreshToken?: string; + expiresIn?: number; +}> { + try { + const response = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/v1/refresh`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Accept': 'application/json', + 'X-API-KEY': process.env.NEXT_PUBLIC_API_KEY || '', + }, + body: JSON.stringify({ + refresh_token: refreshToken, + }), + }); + + if (!response.ok) { + console.warn('🔴 [PROXY] Token refresh failed'); + return { success: false }; + } + + const data = await response.json(); + console.log('✅ [PROXY] Token refreshed successfully'); + + return { + success: true, + accessToken: data.access_token, + refreshToken: data.refresh_token, + expiresIn: data.expires_in, + }; + } catch (error) { + console.error('🔴 [PROXY] Token refresh error:', error); + return { success: false }; + } +} + +/** + * Catch-all proxy handler for all HTTP methods + */ +async function proxyRequest( + request: NextRequest, + params: { path: string[] }, + method: string +) { + try { + // 1. HttpOnly 쿠키에서 토큰 읽기 (서버에서만 가능!) + let token = request.cookies.get('access_token')?.value; + const refreshToken = request.cookies.get('refresh_token')?.value; + + // 1-1. access_token이 없고 refresh_token이 있으면 자동 갱신 + let newTokens: { accessToken?: string; refreshToken?: string; expiresIn?: number } | null = null; + if (!token && refreshToken) { + console.log('🔄 [PROXY] No access_token, attempting refresh...'); + const refreshResult = await refreshAccessToken(refreshToken); + if (refreshResult.success && refreshResult.accessToken) { + token = refreshResult.accessToken; + newTokens = refreshResult; + } + } + + // 2. 백엔드 URL 구성 + const backendUrl = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/${params.path.join('/')}`; + + // 쿼리 파라미터 추가 + const url = new URL(backendUrl); + request.nextUrl.searchParams.forEach((value, key) => { + url.searchParams.append(key, value); + }); + + // 3. 요청 바디 읽기 (POST, PUT, DELETE) + let body: string | undefined; + if (['POST', 'PUT', 'DELETE'].includes(method)) { + // Content-Type에 따라 바디 처리 + const contentType = request.headers.get('content-type') || ''; + + if (contentType.includes('application/json')) { + body = await request.text(); + + // 🔍 디버깅: 전송 데이터 로그 + console.log('🔵 [PROXY DEBUG] Request Details:'); + console.log(' Method:', method); + console.log(' URL:', url.toString()); + console.log(' Body:', body); + console.log(' Token:', token ? `${token.substring(0, 20)}...` : 'null'); + } else if (contentType.includes('multipart/form-data')) { + // FormData는 그대로 전달 + const formData = await request.formData(); + // FormData를 백엔드로 전달하기 위해 다시 변환 + body = await request.text(); + } + } + + // 4. 백엔드로 프록시 요청 + const backendResponse = await fetch(url.toString(), { + method, + headers: { + 'Content-Type': request.headers.get('content-type') || 'application/json', + 'Accept': 'application/json', + 'X-API-KEY': process.env.NEXT_PUBLIC_API_KEY || '', + 'Authorization': token ? `Bearer ${token}` : '', + }, + body, + }); + + // 5. 응답 데이터 읽기 + const responseData = await backendResponse.text(); + + // 🔍 디버깅: 백엔드 응답 로그 + console.log('🔵 [PROXY DEBUG] Backend Response:'); + console.log(' Status:', backendResponse.status); + console.log(' Response:', responseData.substring(0, 500)); // 처음 500자만 + + // 6. 클라이언트로 응답 전달 + const clientResponse = new NextResponse(responseData, { + status: backendResponse.status, + headers: { + 'Content-Type': backendResponse.headers.get('content-type') || 'application/json', + }, + }); + + // 6-1. 토큰이 갱신되었으면 새 쿠키 설정 + if (newTokens && newTokens.accessToken) { + const accessTokenCookie = [ + `access_token=${newTokens.accessToken}`, + 'HttpOnly', + 'Secure', + 'SameSite=Strict', + 'Path=/', + `Max-Age=${newTokens.expiresIn || 7200}`, + ].join('; '); + + clientResponse.headers.append('Set-Cookie', accessTokenCookie); + + if (newTokens.refreshToken) { + const refreshTokenCookie = [ + `refresh_token=${newTokens.refreshToken}`, + 'HttpOnly', + 'Secure', + 'SameSite=Strict', + 'Path=/', + 'Max-Age=604800', // 7 days + ].join('; '); + clientResponse.headers.append('Set-Cookie', refreshTokenCookie); + } + + console.log('🍪 [PROXY] New tokens set in cookies'); + } + + return clientResponse; + + } catch (error) { + console.error('Proxy request error:', error); + return NextResponse.json( + { error: 'Proxy server error' }, + { status: 500 } + ); + } +} + +/** + * GET 요청 프록시 + * Next.js 15: params는 Promise이므로 await 필요 + */ +export async function GET( + request: NextRequest, + { params }: { params: Promise<{ path: string[] }> } +) { + const resolvedParams = await params; + return proxyRequest(request, resolvedParams, 'GET'); +} + +/** + * POST 요청 프록시 + * Next.js 15: params는 Promise이므로 await 필요 + */ +export async function POST( + request: NextRequest, + { params }: { params: Promise<{ path: string[] }> } +) { + const resolvedParams = await params; + return proxyRequest(request, resolvedParams, 'POST'); +} + +/** + * PUT 요청 프록시 + * Next.js 15: params는 Promise이므로 await 필요 + */ +export async function PUT( + request: NextRequest, + { params }: { params: Promise<{ path: string[] }> } +) { + const resolvedParams = await params; + return proxyRequest(request, resolvedParams, 'PUT'); +} + +/** + * DELETE 요청 프록시 + * Next.js 15: params는 Promise이므로 await 필요 + */ +export async function DELETE( + request: NextRequest, + { params }: { params: Promise<{ path: string[] }> } +) { + const resolvedParams = await params; + return proxyRequest(request, resolvedParams, 'DELETE'); +} diff --git a/src/components/auth/LoginPage.tsx b/src/components/auth/LoginPage.tsx index 18604814..e5e18a7f 100644 --- a/src/components/auth/LoginPage.tsx +++ b/src/components/auth/LoginPage.tsx @@ -131,8 +131,8 @@ export function LoginPage() { } else { setError(error.message || t('invalidCredentials')); } - } finally { - setIsLoggingIn(false); // ✅ 로그인 종료 (성공/실패 상관없이) + + setIsLoggingIn(false); // ✅ 실패 시에만 버튼 재활성화 (성공 시 페이지 전환까지 비활성화 유지) } }; diff --git a/src/components/items/BOMManagementSection.tsx b/src/components/items/BOMManagementSection.tsx index 4408a9ec..c2ae94ac 100644 --- a/src/components/items/BOMManagementSection.tsx +++ b/src/components/items/BOMManagementSection.tsx @@ -16,7 +16,7 @@ interface BOMManagementSectionProps { title?: string; description?: string; bomItems: BOMItem[]; - onAddItem: (item: Omit) => void; + onAddItem: (item: Omit) => void; onUpdateItem: (id: number, item: Partial) => void; onDeleteItem: (id: number) => void; itemTypeOptions?: { value: string; label: string }[]; @@ -30,17 +30,8 @@ export function BOMManagementSection({ onAddItem, onUpdateItem, onDeleteItem, - itemTypeOptions = [ - { value: 'product', label: '제품' }, - { value: 'part', label: '부품' }, - { value: 'material', label: '원자재' }, - ], - unitOptions = [ - { value: 'EA', label: 'EA' }, - { value: 'KG', label: 'KG' }, - { value: 'M', label: 'M' }, - { value: 'L', label: 'L' }, - ], + itemTypeOptions = [], + unitOptions = [], }: BOMManagementSectionProps) { const [isDialogOpen, setIsDialogOpen] = useState(false); const [editingId, setEditingId] = useState(null); diff --git a/src/components/items/ItemDetailClient.tsx b/src/components/items/ItemDetailClient.tsx index 043daf31..61ac6e58 100644 --- a/src/components/items/ItemDetailClient.tsx +++ b/src/components/items/ItemDetailClient.tsx @@ -8,7 +8,7 @@ import { useRouter } from 'next/navigation'; import type { ItemMaster } from '@/types/item'; -import { ITEM_TYPE_LABELS, _PART_TYPE_LABELS, _PART_USAGE_LABELS, PRODUCT_CATEGORY_LABELS } from '@/types/item'; +import { ITEM_TYPE_LABELS, PART_TYPE_LABELS, PART_USAGE_LABELS, PRODUCT_CATEGORY_LABELS } from '@/types/item'; import { Button } from '@/components/ui/button'; import { Badge } from '@/components/ui/badge'; import { Label } from '@/components/ui/label'; diff --git a/src/components/items/ItemMasterDataManagement.tsx b/src/components/items/ItemMasterDataManagement.tsx index c70ea7a6..65611b2a 100644 --- a/src/components/items/ItemMasterDataManagement.tsx +++ b/src/components/items/ItemMasterDataManagement.tsx @@ -4,7 +4,7 @@ import { useState, useEffect } from 'react'; import { PageLayout } from '@/components/organisms/PageLayout'; import { PageHeader } from '@/components/organisms/PageHeader'; import { useItemMaster } from '@/contexts/ItemMasterContext'; -import type { ItemPage, ItemSection, ItemField, FieldDisplayCondition, ItemMasterField, ItemFieldProperty, SectionTemplate, BOMItem } from '@/contexts/ItemMasterContext'; +import type { ItemPage, ItemSection, ItemField, FieldDisplayCondition, ItemMasterField, ItemFieldProperty, SectionTemplate, BOMItem, TemplateField } from '@/contexts/ItemMasterContext'; import { MasterFieldTab, HierarchyTab, SectionsTab } from './ItemMasterDataManagement/tabs'; import { FieldDialog } from './ItemMasterDataManagement/dialogs/FieldDialog'; import { type ConditionalFieldConfig } from './ItemMasterDataManagement/components/ConditionalDisplayUI'; @@ -82,6 +82,7 @@ const INPUT_TYPE_OPTIONS = [ export function ItemMasterDataManagement() { const { itemPages, + loadItemPages, addItemPage, updateItemPage, deleteItemPage, @@ -93,14 +94,17 @@ export function ItemMasterDataManagement() { deleteField, reorderFields, itemMasterFields, + loadItemMasterFields, addItemMasterField, updateItemMasterField, deleteItemMasterField, sectionTemplates, + loadSectionTemplates, addSectionTemplate, updateSectionTemplate, deleteSectionTemplate, - resetAllData + resetAllData, + tenantId } = useItemMaster(); console.log('ItemMasterDataManagement: Current sectionTemplates', sectionTemplates); @@ -134,23 +138,17 @@ export function ItemMasterDataManagement() { const data = await itemMasterApi.init(); - // 페이지 데이터 로드 (context의 addItemPage 사용) - data.pages.forEach(page => { - const transformed = transformPagesResponse([page])[0]; - addItemPage(transformed); - }); + // 페이지 데이터 로드 (이미 존재하는 데이터를 state에 로드 - API 호출 없음) + const transformedPages = transformPagesResponse(data.pages); + loadItemPages(transformedPages); - // 섹션 템플릿 로드 - data.sectionTemplates.forEach(template => { - const transformed = transformSectionTemplatesResponse([template])[0]; - addSectionTemplate(transformed); - }); + // 섹션 템플릿 로드 (덮어쓰기 - API 호출 없음!) + const transformedTemplates = transformSectionTemplatesResponse(data.sectionTemplates); + loadSectionTemplates(transformedTemplates); - // 마스터 필드 로드 - data.masterFields.forEach(field => { - const transformed = transformMasterFieldsResponse([field])[0]; - addItemMasterField(transformed); - }); + // 마스터 필드 로드 (덮어쓰기 - API 호출 없음!) + const transformedFields = transformMasterFieldsResponse(data.masterFields); + loadItemMasterFields(transformedFields); // 커스텀 탭 로드 (local state) if (data.customTabs && data.customTabs.length > 0) { @@ -207,12 +205,8 @@ export function ItemMasterDataManagement() { const [activeTab, setActiveTab] = useState('hierarchy'); - // 속성 하위 탭 관리 - const [attributeSubTabs, setAttributeSubTabs] = useState>([ - { id: 'units', label: '단위', key: 'units', isDefault: true, order: 0 }, - { id: 'materials', label: '재질', key: 'materials', isDefault: true, order: 1 }, - { id: 'surface', label: '표면처리', key: 'surface', isDefault: true, order: 2 } - ]); + // 속성 하위 탭 관리 (API에서 로드) + const [attributeSubTabs, setAttributeSubTabs] = useState>([]); // 마스터 항목이 추가/수정될 때 속성 탭 자동 생성 useEffect(() => { @@ -344,7 +338,9 @@ export function ItemMasterDataManagement() { const [newSectionTitle, setNewSectionTitle] = useState(''); const [newSectionDescription, setNewSectionDescription] = useState(''); const [newSectionType, setNewSectionType] = useState<'fields' | 'bom'>('fields'); - + const [sectionInputMode, setSectionInputMode] = useState<'custom' | 'template'>('custom'); + const [selectedSectionTemplateId, setSelectedSectionTemplateId] = useState(null); + // 모바일 체크 const [isMobile, setIsMobile] = useState(false); useEffect(() => { @@ -426,6 +422,10 @@ export function ItemMasterDataManagement() { const [templateFieldMultiColumn, setTemplateFieldMultiColumn] = useState(false); const [templateFieldColumnCount, setTemplateFieldColumnCount] = useState(2); const [templateFieldColumnNames, setTemplateFieldColumnNames] = useState(['컬럼1', '컬럼2']); + // 템플릿 필드 마스터 항목 관련 상태 + const [templateFieldInputMode, setTemplateFieldInputMode] = useState<'custom' | 'master'>('custom'); + const [templateFieldShowMasterFieldList, setTemplateFieldShowMasterFieldList] = useState(false); + const [templateFieldSelectedMasterFieldId, setTemplateFieldSelectedMasterFieldId] = useState(''); // BOM 관리 상태 const [_bomItems, setBomItems] = useState([]); @@ -433,6 +433,8 @@ export function ItemMasterDataManagement() { // 속성 변경 시 연동된 마스터 항목의 옵션 자동 업데이트 useEffect(() => { itemMasterFields.forEach(field => { + // default_properties가 null/undefined인 경우 스킵 + if (!field.default_properties) return; const attributeType = (field.default_properties as any).attributeType; if (attributeType && attributeType !== 'custom' && field.default_properties?.inputType === 'dropdown') { let newOptions: string[] = []; @@ -548,20 +550,19 @@ export function ItemMasterDataManagement() { setIsLoading(true); const absolutePath = generateAbsolutePath(newPageItemType, newPageName); - // API 호출 - const response = await itemMasterApi.pages.create({ + // Context의 addItemPage 사용 (API 호출 + state 업데이트) + // ⚠️ 이전 코드는 여기서 API 호출 후 addItemPage도 호출해서 API가 2번 호출되는 버그가 있었음 + const newPage = await addItemPage({ page_name: newPageName, item_type: newPageItemType, absolute_path: absolutePath, is_active: true, + sections: [], + order_no: 0, }); - // 응답 변환 및 context에 추가 - const transformedPage = transformPageResponse(response); - addItemPage(transformedPage); - // 새로 생성된 페이지를 선택 - setSelectedPageId(transformedPage.id); + setSelectedPageId(newPage.id); // 폼 초기화 setNewPageName(''); @@ -586,43 +587,39 @@ export function ItemMasterDataManagement() { } }; - const handleDuplicatePage = (pageId: number) => { + const handleDuplicatePage = async (pageId: number) => { const originalPage = itemPages.find(p => p.id === pageId); if (!originalPage) return toast.error('페이지를 찾을 수 없습니다'); - // 섹션 인스턴스 깊은 복사 (새로운 ID 부여) - const duplicatedSections = originalPage.sections.map(section => ({ - ...section, - id: Date.now(), - fields: section.fields?.map(field => ({ - ...field, - id: Date.now() - })) || [], - bomItems: section.bomItems?.map(item => ({ - ...item, - id: Date.now() - })) - })); + try { + setIsLoading(true); - // 페이지 복제 - const duplicatedPageName = `${originalPage.page_name} (복제)`; - const absolutePath = generateAbsolutePath(originalPage.item_type, duplicatedPageName); - const newPage: ItemPage = { - id: Date.now(), - page_name: duplicatedPageName, - item_type: originalPage.item_type, - sections: duplicatedSections, - is_active: true, - absolute_path: absolutePath, - order_no: 0, - created_at: new Date().toISOString(), - updated_at: new Date().toISOString() - }; + // 페이지 복제 + const duplicatedPageName = `${originalPage.page_name} (복제)`; + const absolutePath = generateAbsolutePath(originalPage.item_type, duplicatedPageName); - // 페이지 추가 - addItemPage(newPage); - setSelectedPageId(newPage.id); - toast.success('페이지가 복제되었습니다 (저장 필요)'); + // Context의 addItemPage 사용 (API 호출 + state 업데이트) + const newPage = await addItemPage({ + page_name: duplicatedPageName, + item_type: originalPage.item_type, + sections: [], // 섹션은 별도 API로 복제해야 함 + is_active: true, + absolute_path: absolutePath, + order_no: 0, + }); + + // 서버에서 반환된 ID로 선택 + setSelectedPageId(newPage.id); + toast.success('페이지가 복제되었습니다'); + + // TODO: 원본 페이지의 섹션들도 복제 필요 (별도 API 호출) + } catch (err) { + const errorMessage = getErrorMessage(err); + toast.error(errorMessage); + console.error('❌ Failed to duplicate page:', err); + } finally { + setIsLoading(false); + } }; const handleAddSection = () => { @@ -657,20 +654,21 @@ export function ItemMasterDataManagement() { // 섹션은 페이지의 일부이므로 sections로 별도 추적하지 않음 // 2. 섹션관리 탭에도 템플릿으로 자동 추가 (계층구조 섹션 = 섹션 탭 섹션) - const newTemplate: SectionTemplate = { - id: Date.now(), + // 프론트엔드 형식: template_name, section_type ('BASIC' | 'BOM' | 'CUSTOM') + const newTemplateData = { + tenant_id: tenantId ?? 0, template_name: newSection.section_name, - section_type: newSection.section_type, - description: newSection.description, + section_type: newSection.section_type as 'BASIC' | 'BOM' | 'CUSTOM', + description: newSection.description ?? null, default_fields: null, - created_at: new Date().toISOString(), - updated_at: new Date().toISOString() + created_by: null, + updated_by: null, }; - addSectionTemplate(newTemplate); + addSectionTemplate(newTemplateData); console.log('Section added to both page and template:', { sectionId: newSection.id, - templateId: newTemplate.id + templateTitle: newTemplateData.title }); setNewSectionTitle(''); @@ -680,6 +678,67 @@ export function ItemMasterDataManagement() { toast.success(`${newSectionType === 'bom' ? 'BOM' : '일반'} 섹션이 페이지에 추가되고 템플릿으로도 등록되었습니다!`); }; + // 섹션 템플릿을 페이지에 연결 (SectionDialog에서 사용) + const handleLinkTemplate = (template: SectionTemplate) => { + if (!selectedPage) { + toast.error('페이지를 먼저 선택해주세요'); + return; + } + + // 템플릿을 섹션으로 변환하여 페이지에 추가 + const newSection: Omit = { + page_id: selectedPage.id, + section_name: template.template_name, + section_type: template.section_type, + description: template.description || undefined, + order_no: selectedPage.sections.length + 1, + is_collapsible: true, + is_default_open: true, + fields: template.fields ? template.fields.map((field, idx) => ({ + id: Date.now() + idx, + section_id: 0, // 추후 업데이트됨 + field_name: field.name, + field_type: field.property.inputType, + order_no: idx + 1, + is_required: field.property.required, + placeholder: field.description || null, + default_value: null, + display_condition: null, + validation_rules: null, + options: field.property.options + ? field.property.options.map(opt => ({ label: opt, value: opt })) + : null, + properties: field.property.multiColumn ? { + multiColumn: true, + columnCount: field.property.columnCount, + columnNames: field.property.columnNames + } : null, + created_at: new Date().toISOString(), + updated_at: new Date().toISOString() + })) : [], + bomItems: template.section_type === 'BOM' ? (template.bomItems || []) : undefined + }; + + console.log('Linking template to page:', { + templateId: template.id, + templateName: template.template_name, + pageId: selectedPage.id, + newSection + }); + + addSectionToPage(selectedPage.id, newSection); + + // 다이얼로그 상태 초기화 + setSectionInputMode('custom'); + setSelectedSectionTemplateId(null); + setNewSectionTitle(''); + setNewSectionDescription(''); + setNewSectionType('fields'); + setIsSectionDialogOpen(false); + + toast.success(`"${template.template_name}" 템플릿이 페이지에 연결되었습니다!`); + }; + const handleEditSectionTitle = (sectionId: string, currentTitle: string) => { setEditingSectionId(sectionId); setEditingSectionTitle(currentTitle); @@ -758,9 +817,15 @@ export function ItemMasterDataManagement() { // 텍스트박스 컬럼 설정 const hasColumns = newFieldInputType === 'textbox' && textboxColumns.length > 0; + // 마스터 항목에서 가져온 경우 master_field_id 설정 + const masterFieldId = fieldInputMode === 'master' && selectedMasterFieldId + ? Number(selectedMasterFieldId) + : null; + const newField: ItemField = { id: editingFieldId ? Number(editingFieldId) : Date.now(), section_id: Number(selectedSectionForField), + master_field_id: masterFieldId, // 마스터 항목 연결 정보 field_name: newFieldName, field_type: newFieldInputType, order_no: 0, @@ -805,17 +870,16 @@ export function ItemMasterDataManagement() { // 1. 섹션에 항목 추가 addFieldToSection(Number(selectedSectionForField), newField); - // 2. 항목관리 탭에도 마스터 항목으로 자동 추가 (중복 체크) + // 2. 마스터 항목 선택이 아닌 경우에만 새 마스터 항목 자동 생성 + // (마스터 항목 선택 시에는 이미 master_field_id로 연결되어 있음) + const isFromMasterField = masterFieldId !== null; const existingMasterField = itemMasterFields.find(mf => mf.id.toString() === newField.field_name); - if (!existingMasterField) { + if (!isFromMasterField && !existingMasterField) { + // API 스펙: field_type은 소문자만 허용 (textbox, number, dropdown, checkbox, date, textarea) const newMasterField: ItemMasterField = { id: Date.now(), field_name: newField.field_name, - field_type: newField.field_type === 'textbox' ? 'TEXT' : - newField.field_type === 'number' ? 'NUMBER' : - newField.field_type === 'date' ? 'DATE' : - newField.field_type === 'textarea' ? 'TEXTAREA' : - newField.field_type === 'checkbox' ? 'CHECKBOX' : 'SELECT', + field_type: newField.field_type, // API 스펙에 맞게 소문자 그대로 전달 description: newField.placeholder, default_properties: newField.properties, category: selectedPage.item_type, // 현재 페이지의 품목유형을 카테고리로 설정 @@ -975,14 +1039,11 @@ export function ItemMasterDataManagement() { })); } + // API 스펙: field_type은 소문자만 허용 (textbox, number, dropdown, checkbox, date, textarea) const newMasterField: ItemMasterField = { id: Date.now(), field_name: newMasterFieldName, - field_type: newMasterFieldInputType === 'textbox' ? 'TEXT' : - newMasterFieldInputType === 'number' ? 'NUMBER' : - newMasterFieldInputType === 'date' ? 'DATE' : - newMasterFieldInputType === 'textarea' ? 'TEXTAREA' : - newMasterFieldInputType === 'checkbox' ? 'CHECKBOX' : 'SELECT', + field_type: newMasterFieldInputType, category: newMasterFieldCategory || null, description: newMasterFieldDescription || null, default_validation: null, @@ -1214,21 +1275,24 @@ export function ItemMasterDataManagement() { // 섹션 템플릿 핸들러 const handleAddSectionTemplate = () => { - if (!newSectionTemplateTitle.trim()) + if (!newSectionTemplateTitle.trim()) return toast.error('섹션 제목을 입력해주세요'); - const newTemplate: SectionTemplate = { - id: Date.now(), + // Context의 addSectionTemplate이 기대하는 SectionTemplate 형식 사용 + // template_name, section_type ('BASIC' | 'BOM' | 'CUSTOM') + const newTemplateData = { + tenant_id: tenantId ?? 0, template_name: newSectionTemplateTitle, - section_type: newSectionTemplateType === 'bom' ? 'BOM' : 'BASIC', - description: newSectionTemplateDescription || undefined, + section_type: (newSectionTemplateType === 'bom' ? 'BOM' : 'BASIC') as 'BASIC' | 'BOM' | 'CUSTOM', + description: newSectionTemplateDescription || null, default_fields: null, - created_at: new Date().toISOString(), - updated_at: new Date().toISOString() + category: newSectionTemplateCategory, + created_by: null, + updated_by: null, }; - console.log('Adding section template:', newTemplate); - addSectionTemplate(newTemplate); + console.log('Adding section template:', newTemplateData); + addSectionTemplate(newTemplateData); setNewSectionTemplateTitle(''); setNewSectionTemplateDescription(''); @@ -1240,9 +1304,10 @@ export function ItemMasterDataManagement() { const handleEditSectionTemplate = (template: SectionTemplate) => { setEditingSectionTemplateId(template.id); + // SectionTemplate 타입에 맞게 template_name, section_type 사용 setNewSectionTemplateTitle(template.template_name); setNewSectionTemplateDescription(template.description || ''); - setNewSectionTemplateCategory([]); + setNewSectionTemplateCategory(template.category || []); setNewSectionTemplateType(template.section_type === 'BOM' ? 'bom' : 'fields'); setIsSectionTemplateDialogOpen(true); }; @@ -1251,13 +1316,16 @@ export function ItemMasterDataManagement() { if (!editingSectionTemplateId || !newSectionTemplateTitle.trim()) return toast.error('섹션 제목을 입력해주세요'); + // Context의 updateSectionTemplate이 기대하는 SectionTemplate 형식 사용 + // template_name, section_type ('BASIC' | 'BOM' | 'CUSTOM') const updateData = { - title: newSectionTemplateTitle, + template_name: newSectionTemplateTitle, description: newSectionTemplateDescription || undefined, category: newSectionTemplateCategory.length > 0 ? newSectionTemplateCategory : undefined, - type: newSectionTemplateType + section_type: (newSectionTemplateType === 'bom' ? 'BOM' : 'BASIC') as 'BASIC' | 'BOM' | 'CUSTOM' }; + console.log('Updating section template:', { id: editingSectionTemplateId, updateData }); updateSectionTemplate(editingSectionTemplateId, updateData); setEditingSectionTemplateId(null); @@ -1290,19 +1358,20 @@ export function ItemMasterDataManagement() { } // 템플릿을 복사해서 섹션으로 추가 + // API 스펙: SectionTemplate은 title, type ('fields' | 'bom') 사용 const newSection: Omit = { page_id: selectedPage.id, - section_name: template.template_name, - section_type: template.section_type, + section_name: template.title, + section_type: template.type === 'bom' ? 'BOM' : 'BASIC', description: template.description || undefined, order_no: selectedPage.sections.length + 1, is_collapsible: true, is_default_open: true, fields: [], - bomItems: template.section_type === 'BOM' ? [] : undefined + bomItems: template.type === 'bom' ? [] : undefined }; - console.log('Loading template to section:', template.template_name, 'type:', template.section_type, 'newSection:', newSection); + console.log('Loading template to section:', template.title, 'type:', template.type, 'newSection:', newSection); addSectionToPage(selectedPage.id, newSection); setSelectedTemplateId(null); setIsLoadTemplateDialogOpen(false); @@ -1321,15 +1390,11 @@ export function ItemMasterDataManagement() { // 항목 탭에 해당 항목이 없으면 자동으로 추가 const existingMasterField = itemMasterFields.find(f => f.id.toString() === templateFieldKey); if (!existingMasterField && !editingTemplateFieldId) { + // API 스펙: field_type은 소문자만 허용 (textbox, number, dropdown, checkbox, date, textarea) const newMasterField: ItemMasterField = { id: Date.now(), field_name: templateFieldName, - field_type: templateFieldInputType === 'textbox' ? 'TEXT' : - templateFieldInputType === 'number' ? 'NUMBER' : - templateFieldInputType === 'date' ? 'DATE' : - templateFieldInputType === 'dropdown' ? 'SELECT' : - templateFieldInputType === 'textarea' ? 'TEXTAREA' : - templateFieldInputType === 'checkbox' ? 'CHECKBOX' : 'TEXT', + field_type: templateFieldInputType, default_properties: { inputType: templateFieldInputType, required: templateFieldRequired, @@ -1380,38 +1445,30 @@ export function ItemMasterDataManagement() { } } - const newField: ItemField = { - id: editingTemplateFieldId || Date.now(), - section_id: 0, // Placeholder for template - field_name: templateFieldName, - field_type: templateFieldInputType, - order_no: 0, - is_required: templateFieldRequired, - placeholder: templateFieldDescription || null, - default_value: null, - display_condition: null, - validation_rules: null, - options: templateFieldInputType === 'dropdown' && templateFieldOptions.trim() - ? templateFieldOptions.split(',').map(o => ({ label: o.trim(), value: o.trim() })) - : null, - properties: { + // TemplateField 형식으로 생성 (UI가 기대하는 형식) + const newField: TemplateField = { + id: String(editingTemplateFieldId || Date.now()), + name: templateFieldName, + fieldKey: templateFieldKey, + property: { inputType: templateFieldInputType, required: templateFieldRequired, - row: 1, - col: 1, + options: templateFieldInputType === 'dropdown' && templateFieldOptions.trim() + ? templateFieldOptions.split(',').map(o => o.trim()) + : undefined, multiColumn: (templateFieldInputType === 'textbox' || templateFieldInputType === 'textarea') ? templateFieldMultiColumn : undefined, columnCount: (templateFieldInputType === 'textbox' || templateFieldInputType === 'textarea') && templateFieldMultiColumn ? templateFieldColumnCount : undefined, columnNames: (templateFieldInputType === 'textbox' || templateFieldInputType === 'textarea') && templateFieldMultiColumn ? templateFieldColumnNames : undefined }, - created_at: new Date().toISOString(), - updated_at: new Date().toISOString() + description: templateFieldDescription || undefined }; let updatedFields; const currentFields = template.default_fields ? (typeof template.default_fields === 'string' ? JSON.parse(template.default_fields) : template.default_fields) : []; if (editingTemplateFieldId) { - updatedFields = Array.isArray(currentFields) ? currentFields.map((f: any) => f.id === editingTemplateFieldId ? newField : f) : []; + // f.id는 string, editingTemplateFieldId는 number이므로 String으로 변환하여 비교 + updatedFields = Array.isArray(currentFields) ? currentFields.map((f: any) => String(f.id) === String(editingTemplateFieldId) ? newField : f) : []; toast.success('항목이 수정되었습니다'); } else { updatedFields = Array.isArray(currentFields) ? [...currentFields, newField] : [newField]; @@ -1434,18 +1491,19 @@ export function ItemMasterDataManagement() { setIsTemplateFieldDialogOpen(false); }; - const handleEditTemplateField = (templateId: number, field: ItemField) => { + // TemplateField 형식으로 수정 (UI가 전달하는 형식) + const handleEditTemplateField = (templateId: number, field: TemplateField) => { setCurrentTemplateId(templateId); - setEditingTemplateFieldId(field.id); - setTemplateFieldName(field.field_name); - setTemplateFieldKey(field.id.toString()); - setTemplateFieldInputType(field.properties?.inputType); - setTemplateFieldRequired(field.is_required); - setTemplateFieldOptions(field.options?.map(o => o.value).join(', ') || ''); - setTemplateFieldDescription(field.placeholder || ''); - setTemplateFieldMultiColumn(field.properties?.multiColumn || false); - setTemplateFieldColumnCount(field.properties?.columnCount || 2); - setTemplateFieldColumnNames(field.properties?.columnNames || ['컬럼1', '컬럼2']); + setEditingTemplateFieldId(Number(field.id)); // TemplateField.id는 string + setTemplateFieldName(field.name); + setTemplateFieldKey(field.fieldKey); + setTemplateFieldInputType(field.property.inputType); + setTemplateFieldRequired(field.property.required); + setTemplateFieldOptions(field.property.options?.join(', ') || ''); + setTemplateFieldDescription(field.description || ''); + setTemplateFieldMultiColumn(field.property.multiColumn || false); + setTemplateFieldColumnCount(field.property.columnCount || 2); + setTemplateFieldColumnNames(field.property.columnNames || ['컬럼1', '컬럼2']); setIsTemplateFieldDialogOpen(true); }; @@ -1456,7 +1514,8 @@ export function ItemMasterDataManagement() { if (!template) return; const currentFields = template.default_fields ? (typeof template.default_fields === 'string' ? JSON.parse(template.default_fields) : template.default_fields) : []; - const updatedFields = Array.isArray(currentFields) ? currentFields.filter((f: any) => f.id !== fieldId) : []; + // f.id는 number 또는 string일 수 있으므로 String으로 변환하여 비교 + const updatedFields = Array.isArray(currentFields) ? currentFields.filter((f: any) => String(f.id) !== String(fieldId)) : []; updateSectionTemplate(templateId, { default_fields: updatedFields }); toast.success('항목이 삭제되었습니다'); }; @@ -1468,7 +1527,7 @@ export function ItemMasterDataManagement() { id: Date.now(), created_at: new Date().toISOString(), updated_at: new Date().toISOString(), - tenant_id: 1, + tenant_id: tenantId ?? 0, section_id: 0 }; setBomItems(prev => [...prev, newItem]); @@ -1489,7 +1548,7 @@ export function ItemMasterDataManagement() { id: Date.now(), created_at: new Date().toISOString(), updated_at: new Date().toISOString(), - tenant_id: 1, + tenant_id: tenantId ?? 0, section_id: 0 }; @@ -1770,11 +1829,7 @@ export function ItemMasterDataManagement() { { id: 'attributes', label: '속성', icon: 'Settings', isDefault: true, order: 4 } ]); - setAttributeSubTabs([ - { id: 'units', label: '단위', key: 'units', isDefault: true, order: 0 }, - { id: 'materials', label: '재질', key: 'materials', isDefault: true, order: 1 }, - { id: 'surface', label: '표면처리', key: 'surface', isDefault: true, order: 2 } - ]); + setAttributeSubTabs([]); console.log('🗑️ 모든 품목기준관리 데이터가 초기화되었습니다'); toast.success('✅ 모든 데이터가 초기화되었습니다!\n계층구조, 섹션, 항목, 속성이 모두 삭제되었습니다.'); @@ -1831,14 +1886,14 @@ export function ItemMasterDataManagement() { ); })} - + {/* setIsManageTabsDialogOpen(true)}*/} + {/*>*/} + {/* */} + {/* 탭 관리*/} + {/**/} {/* 전체 초기화 버튼 숨김 처리 - 디자인에 없는 기능 */} {/* @@ -2622,6 +2677,12 @@ export function ItemMasterDataManagement() { newSectionDescription={newSectionDescription} setNewSectionDescription={setNewSectionDescription} handleAddSection={handleAddSection} + sectionInputMode={sectionInputMode} + setSectionInputMode={setSectionInputMode} + sectionTemplates={sectionTemplates} + selectedTemplateId={selectedSectionTemplateId} + setSelectedTemplateId={setSelectedSectionTemplateId} + handleLinkTemplate={handleLinkTemplate} /> {/* 항목 추가/수정 다이얼로그 - 데스크톱 */} @@ -2809,6 +2870,14 @@ export function ItemMasterDataManagement() { templateFieldColumnNames={templateFieldColumnNames} setTemplateFieldColumnNames={setTemplateFieldColumnNames} handleAddTemplateField={handleAddTemplateField} + // 마스터 항목 관련 props + itemMasterFields={itemMasterFields} + templateFieldInputMode={templateFieldInputMode} + setTemplateFieldInputMode={setTemplateFieldInputMode} + showMasterFieldList={templateFieldShowMasterFieldList} + setShowMasterFieldList={setTemplateFieldShowMasterFieldList} + selectedMasterFieldId={templateFieldSelectedMasterFieldId} + setSelectedMasterFieldId={setTemplateFieldSelectedMasterFieldId} /> ; @@ -92,8 +92,10 @@ export function ConditionalDisplayUI({ }; // selectedSectionForField는 이미 ItemSection 객체이므로 바로 사용 + // 신규 ItemField 타입: id는 number const availableFields = selectedSectionForField?.fields?.filter(f => f.id !== editingFieldId) || []; - const availableSections = selectedPage?.sections.filter(s => s.type !== 'bom') || []; + // 신규 ItemSection 타입: section_type은 'BASIC' | 'BOM' | 'CUSTOM' + const availableSections = selectedPage?.sections.filter(s => s.section_type !== 'BOM') || []; return (
@@ -175,32 +177,35 @@ export function ConditionalDisplayUI({ 이 값일 때 표시할 항목들 ({condition.targetFieldIds?.length || 0}개 선택됨):
- {availableFields.map(field => ( - - ))} + {availableFields.map(field => { + const fieldIdStr = String(field.id); + return ( + + ); + })}
) : ( @@ -278,29 +283,32 @@ export function ConditionalDisplayUI({ 이 값일 때 표시할 섹션들 ({condition.targetSectionIds?.length || 0}개 선택됨):
- {availableSections.map(section => ( - - ))} + {availableSections.map(section => { + const sectionIdStr = String(section.id); + return ( + + ); + })}
diff --git a/src/components/items/ItemMasterDataManagement/components/DraggableField.tsx b/src/components/items/ItemMasterDataManagement/components/DraggableField.tsx index 17924305..c7ec8560 100644 --- a/src/components/items/ItemMasterDataManagement/components/DraggableField.tsx +++ b/src/components/items/ItemMasterDataManagement/components/DraggableField.tsx @@ -71,29 +71,29 @@ export function DraggableField({ field, index, moveField, onDelete, onEdit }: Dr
- {field.name} + {field.field_name} - {INPUT_TYPE_OPTIONS.find(t => t.value === field.property.inputType)?.label} + {INPUT_TYPE_OPTIONS.find(t => t.value === field.field_type)?.label || field.field_type} - {field.property.required && ( + {field.is_required && ( 필수 )} - {field.displayCondition && ( + {field.display_condition && ( 조건부 )} - {field.order !== undefined && ( - 순서: {field.order + 1} + {field.order_no !== undefined && ( + 순서: {field.order_no + 1} )}
- 필드키: {field.fieldKey} - {field.displayCondition && ( + 필드ID: {field.id} + {field.display_condition && ( - (조건: {field.displayCondition.fieldKey} = {field.displayCondition.expectedValue}) + (조건부 표시 설정됨) )} - {field.description && ( - • {field.description} + {field.placeholder && ( + • {field.placeholder} )}
diff --git a/src/components/items/ItemMasterDataManagement/components/DraggableSection.tsx b/src/components/items/ItemMasterDataManagement/components/DraggableSection.tsx index 14063025..79f7a706 100644 --- a/src/components/items/ItemMasterDataManagement/components/DraggableSection.tsx +++ b/src/components/items/ItemMasterDataManagement/components/DraggableSection.tsx @@ -16,11 +16,11 @@ interface DraggableSectionProps { index: number; moveSection: (dragIndex: number, hoverIndex: number) => void; onDelete: () => void; - onEditTitle: (id: string, title: string) => void; - editingSectionId: string | null; + onEditTitle: (id: number, title: string) => void; + editingSectionId: number | null; editingSectionTitle: string; setEditingSectionTitle: (title: string) => void; - setEditingSectionId: (id: string | null) => void; + setEditingSectionId: (id: number | null) => void; handleSaveSectionTitle: () => void; children: React.ReactNode; } @@ -106,9 +106,9 @@ export function DraggableSection({ ) : (
onEditTitle(section.id, section.title)} + onClick={() => onEditTitle(section.id, section.section_name)} > - {section.title} + {section.section_name}
)} @@ -118,8 +118,9 @@ export function DraggableSection({ size="sm" variant="ghost" onClick={onDelete} + title="페이지에서 연결 해제" > - + diff --git a/src/components/items/ItemMasterDataManagement/dialogs/FieldDialog.tsx b/src/components/items/ItemMasterDataManagement/dialogs/FieldDialog.tsx index 0228b3fc..2baa1928 100644 --- a/src/components/items/ItemMasterDataManagement/dialogs/FieldDialog.tsx +++ b/src/components/items/ItemMasterDataManagement/dialogs/FieldDialog.tsx @@ -13,6 +13,9 @@ import { toast } from 'sonner'; import type { ItemPage, ItemSection, ItemMasterField } from '@/contexts/ItemMasterContext'; import { ConditionalDisplayUI, type ConditionalFieldConfig } from '../components/ConditionalDisplayUI'; +// 입력 타입 정의 +export type InputType = 'textbox' | 'dropdown' | 'checkbox' | 'number' | 'date' | 'textarea'; + // 텍스트박스 칼럼 타입 (단순 구조) interface OptionColumn { id: string; @@ -20,7 +23,7 @@ interface OptionColumn { key: string; } -const INPUT_TYPE_OPTIONS = [ +const INPUT_TYPE_OPTIONS: Array<{ value: InputType; label: string }> = [ { value: 'textbox', label: '텍스트박스' }, { value: 'dropdown', label: '드롭다운' }, { value: 'checkbox', label: '체크박스' }, @@ -56,8 +59,8 @@ interface FieldDialogProps { setNewFieldName: (name: string) => void; newFieldKey: string; setNewFieldKey: (key: string) => void; - newFieldInputType: 'textbox' | 'dropdown' | 'checkbox' | 'number' | 'date' | 'textarea' | 'section'; - setNewFieldInputType: (type: any) => void; + newFieldInputType: InputType; + setNewFieldInputType: (type: InputType) => void; newFieldRequired: boolean; setNewFieldRequired: (required: boolean) => void; newFieldDescription: string; @@ -198,21 +201,22 @@ export function FieldDialog({
{ - setSelectedMasterFieldId(field.id); - setNewFieldName(field.name); - setNewFieldKey(field.fieldKey); - setNewFieldInputType(field.property.inputType); - setNewFieldRequired(field.property.required); + setSelectedMasterFieldId(String(field.id)); + setNewFieldName(field.field_name); + setNewFieldKey(field.id.toString()); + setNewFieldInputType(field.field_type); + setNewFieldRequired(field.properties?.required || false); setNewFieldDescription(field.description || ''); - setNewFieldOptions(field.property.options?.join(', ') || ''); - if (field.property.multiColumn && field.property.columnNames) { + // options는 {label, value}[] 배열이므로 label만 추출 + setNewFieldOptions(field.options?.map(opt => opt.label).join(', ') || ''); + if (field.properties?.multiColumn && field.properties?.columnNames) { setTextboxColumns( - field.property.columnNames.map((name, idx) => ({ + field.properties.columnNames.map((name: string, idx: number) => ({ id: `col-${idx}`, name, key: `column${idx + 1}` @@ -224,28 +228,26 @@ export function FieldDialog({
- {field.name} + {field.field_name} - {INPUT_TYPE_OPTIONS.find(o => o.value === field.property.inputType)?.label} + {INPUT_TYPE_OPTIONS.find(o => o.value === field.field_type)?.label || field.field_type} - {field.property.required && ( + {field.properties?.required && ( 필수 )}
{field.description && (

{field.description}

)} - {Array.isArray(field.category) && field.category.length > 0 && ( + {field.category && (
- {field.category.map((cat, idx) => ( - - {cat} - - ))} + + {field.category} +
)}
- {selectedMasterFieldId === field.id && ( + {selectedMasterFieldId === String(field.id) && ( )}
@@ -280,7 +282,7 @@ export function FieldDialog({
- setNewFieldInputType(v as InputType)}> diff --git a/src/components/items/ItemMasterDataManagement/dialogs/PageDialog.tsx b/src/components/items/ItemMasterDataManagement/dialogs/PageDialog.tsx index b603c0ad..74cde3a6 100644 --- a/src/components/items/ItemMasterDataManagement/dialogs/PageDialog.tsx +++ b/src/components/items/ItemMasterDataManagement/dialogs/PageDialog.tsx @@ -7,10 +7,11 @@ import { Input } from '@/components/ui/input'; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'; const ITEM_TYPE_OPTIONS = [ - { value: 'product', label: '제품' }, - { value: 'part', label: '부품' }, - { value: 'material', label: '자재' }, - { value: 'assembly', label: '조립품' }, + { value: 'FG', label: '제품 (FG)' }, + { value: 'PT', label: '부품 (PT)' }, + { value: 'SM', label: '반제품 (SM)' }, + { value: 'RM', label: '원자재 (RM)' }, + { value: 'CS', label: '소모품 (CS)' }, ]; interface PageDialogProps { diff --git a/src/components/items/ItemMasterDataManagement/dialogs/SectionDialog.tsx b/src/components/items/ItemMasterDataManagement/dialogs/SectionDialog.tsx index 877de56c..89dfc454 100644 --- a/src/components/items/ItemMasterDataManagement/dialogs/SectionDialog.tsx +++ b/src/components/items/ItemMasterDataManagement/dialogs/SectionDialog.tsx @@ -5,6 +5,9 @@ import { Button } from '@/components/ui/button'; import { Label } from '@/components/ui/label'; import { Input } from '@/components/ui/input'; import { Textarea } from '@/components/ui/textarea'; +import { Badge } from '@/components/ui/badge'; +import { FileText, Package, Check, X } from 'lucide-react'; +import type { SectionTemplate } from '@/contexts/ItemMasterContext'; interface SectionDialogProps { isSectionDialogOpen: boolean; @@ -16,6 +19,13 @@ interface SectionDialogProps { newSectionDescription: string; setNewSectionDescription: (description: string) => void; handleAddSection: () => void; + // 템플릿 선택 관련 props + sectionInputMode: 'custom' | 'template'; + setSectionInputMode: (mode: 'custom' | 'template') => void; + sectionTemplates: SectionTemplate[]; + selectedTemplateId: number | null; + setSelectedTemplateId: (id: number | null) => void; + handleLinkTemplate: (template: SectionTemplate) => void; } export function SectionDialog({ @@ -28,59 +38,246 @@ export function SectionDialog({ newSectionDescription, setNewSectionDescription, handleAddSection, + sectionInputMode, + setSectionInputMode, + sectionTemplates, + selectedTemplateId, + setSelectedTemplateId, + handleLinkTemplate, }: SectionDialogProps) { + const handleClose = () => { + setIsSectionDialogOpen(false); + setNewSectionType('fields'); + setNewSectionTitle(''); + setNewSectionDescription(''); + setSectionInputMode('custom'); + setSelectedTemplateId(null); + }; + + // 템플릿 선택 시 폼에 값 채우기 + const handleSelectTemplate = (template: SectionTemplate) => { + setSelectedTemplateId(template.id); + setNewSectionTitle(template.template_name); + setNewSectionDescription(template.description || ''); + setNewSectionType(template.section_type === 'BOM' ? 'bom' : 'fields'); + }; + return ( { - setIsSectionDialogOpen(open); - if (!open) { - setNewSectionType('fields'); - setNewSectionTitle(''); - setNewSectionDescription(''); - } + if (!open) handleClose(); + else setIsSectionDialogOpen(open); }}> - - - {newSectionType === 'bom' ? 'BOM 섹션' : '일반 섹션'} 추가 + + + 섹션 추가 - {newSectionType === 'bom' - ? '새로운 BOM(자재명세서) 섹션을 추가합니다' - : '새로운 일반 섹션을 추가합니다'} + 새로운 섹션을 추가하거나 기존 템플릿을 연결합니다. -
-
- - setNewSectionTitle(e.target.value)} - placeholder={newSectionType === 'bom' ? '예: BOM 구성' : '예: 기본 정보'} - /> + +
+ {/* 입력 모드 선택 */} +
+ +
-
- -