- CorsMiddleware: X-API-KEY 헤더를 Access-Control-Allow-Headers에 추가
- CorsMiddleware: OPTIONS 요청을 미들웨어 체인 진입 전에 즉시 처리하여 ApiKeyMiddleware 우회
- CorsMiddleware: PATCH 메서드 추가 및 Max-Age 86400초 설정
- ApiKeyMiddleware: 불필요한 OPTIONS 체크 로직 제거 (CorsMiddleware에서 이미 처리)
[근본 원인]
- React 프론트엔드에서 커스텀 헤더(X-API-KEY) 사용 시 브라우저가 자동으로 Preflight 요청(OPTIONS) 전송
- 기존 CorsMiddleware에서 X-API-KEY 헤더가 Allow-Headers 목록에 없어 CORS 정책 위반
- OPTIONS 요청이 ApiKeyMiddleware에서 401로 차단되어 Preflight 실패
[해결 방안]
- OPTIONS 요청은 CorsMiddleware에서 즉시 200 OK 응답 (인증 미들웨어 우회)
- X-API-KEY를 명시적으로 허용 헤더 목록에 추가
- 실제 GET/POST 요청은 기존대로 ApiKeyMiddleware에서 정상 검증
- Category CRUD 테스트 5개 추가
- 계층 구조 테스트 1개 추가
- 순서/이동 테스트 2개 추가
- 인증 테스트 1개 추가
- 2개 테스트 skip (API 라우트/인증 문제)
ItemMasterApiTest 패턴 재사용:
- 수동 User/Tenant 생성 방식
- DatabaseTransactions로 테스트 격리
- authenticatedRequest() 헬퍼 메서드
테스트 결과: 9 passed, 2 skipped, 44 assertions, 0.375s
- ItemPage CRUD 테스트 4개 추가
- ItemSection CRUD + Reorder 테스트 4개 추가
- ItemField CRUD + Reorder 테스트 4개 추가
- ItemBomItem CRUD 테스트 3개 추가
- SectionTemplate CRUD 테스트 4개 추가
- ItemMasterField CRUD 테스트 4개 추가
주요 수정:
- item_section_id → section_id 필드명 수정
- item_type enum 값 수정 (PRODUCT→FG, MATERIAL→RM)
- 모든 테스트 통과 (35 tests, 207 assertions)
주요 작업:
- ItemMaster API 통합 테스트 작성 (12개 테스트, 100% 통과)
- 로그인 → API 호출 실제 플로우 시뮬레이션
- CustomTab, UnitOption CRUD 및 Reorder 테스트
버그 수정:
- ApiKeyMiddleware: 로그인 엔드포인트 API Key 필수화
- ReorderRequest: validation 규칙 수정 (범용성 확보)
- 5개 Controller: ApiResponse namespace 수정
- routes/api.php: reorder 라우트 순서 수정
마이그레이션:
- section_templates, tab_columns 테이블 추가
테스트 결과: 12/12 통과 (82 assertions)
- Controller 2개, Service 2개, FormRequest 3개 생성
- Routes 등록 (커스텀 탭, 단위 옵션)
- Service-First, Multi-tenant, Soft Delete
- 라우트 테스트 및 Pint 검사 통과
- ItemMaster API 전체 32개 엔드포인트 구현 완료
9 files changed, 467 insertions(+)
- Controller 3개, Service 3개, FormRequest 6개 생성
- Routes 등록 (BOM 항목, 섹션 템플릿, 마스터 필드)
- Service-First, Multi-tenant, Soft Delete
- 라우트 테스트 및 Pint 검사 통과
13 files changed, 600+ insertions(+)
- Controller 4개 생성 (ItemMaster, ItemPage, ItemSection, ItemField)
- Service 4개 생성 (비즈니스 로직 및 Multi-tenant 지원)
- FormRequest 7개 생성 (Validation)
- Routes 등록 (/v1/item-master/*)
주요 API:
- GET /init - 전체 초기 데이터 로드
- 페이지 관리 (GET/POST/PUT/DELETE)
- 섹션 관리 (POST/PUT/DELETE/reorder)
- 필드 관리 (POST/PUT/DELETE/reorder)
기술적 특징:
- Service-First 패턴 (Controller는 DI + ApiResponse만)
- Multi-tenant 지원 (tenantId() 검증 + BelongsToTenant)
- Cascade Soft Delete (하위 엔티티 자동 처리)
- i18n 메시지 키 사용 (__('message.xxx'))
- order_no 자동 계산 및 reorder 지원
검증:
- 라우트 테스트: 13개 엔드포인트 정상 등록
- Pint 검사: 15 files PASS
SAM API Development Rules 준수
- 마이그레이션 9개 생성 (unit_options, section_templates, item_master_fields, item_pages, item_sections, item_fields, item_bom_items, custom_tabs, tab_columns)
- Eloquent 모델 9개 구현 (ItemMaster 네임스페이스)
- ItemMasterSeeder 작성 및 테스트 데이터 생성
주요 특징:
- Multi-tenant 지원 (BelongsToTenant trait)
- Soft Delete 적용 (deleted_at, deleted_by)
- 감사 로그 지원 (created_by, updated_by)
- JSON 필드로 동적 속성 지원 (display_condition, validation_rules, options, properties)
- FK 제약조건 및 Composite Index 설정
- 계층 구조 (ItemPage → ItemSection → ItemField/ItemBomItem)
SAM API Development Rules 준수
- is_active 컬럼 추가 마이그레이션 (default 1)
- Product 모델 fillable 및 casts 업데이트
- Material 모델 fillable 및 casts 업데이트
- Material 모델에 material_type fillable 추가
- ModelTrait의 scopeActive() 메서드 지원
- BP-MES_PHASE1_INTEGRATION_TEST.md 작성
- 17개 API 엔드포인트 검증 가이드
- 4개 통합 시나리오 (CRUD, BOM, File, 전체)
- 에러 처리 검증 케이스
- 성능 검증 기준
- Swagger UI 테스트 체크리스트
- CURRENT_WORKS.md 업데이트
- Items BOM API 구현 내용 (Day 6-9)
- Items File Upload API 구현 내용 (Day 10-12)
- 통합 테스트 완료 (Day 13-14)
- API 엔드포인트 요약 (총 17개)
- Phase 1 완료 및 Phase 2 제안
- Products 테이블에 9개 파일 관련 필드 추가
- bending_diagram, bending_details (JSON)
- specification_file, specification_file_name
- certification_file, certification_file_name
- certification_number, certification_start_date, certification_end_date
- ItemsFileController 구현 (Code-based API)
- POST /items/{code}/files - 파일 업로드
- DELETE /items/{code}/files/{type} - 파일 삭제
- 파일 타입: bending_diagram, specification, certification
- ItemsFileUploadRequest 검증
- 파일 타입별 MIME 검증 (이미지/문서)
- 파일 크기 제한 (10MB/20MB)
- 인증 정보 및 절곡 상세 정보 검증
- Swagger 문서 작성 (ItemsFileApi.php)
- 업로드/삭제 API 스펙
- 스키마: ItemFileUploadResponse, ItemFileDeleteResponse
- ItemsBomController 생성 (code 기반 BOM 관리)
- 기존 ProductBomService 100% 재사용 (Adapter 패턴)
- Code → ID 변환 후 기존 비즈니스 로직 활용
- 프론트엔드 요구사항 완벽 대응 (itemCode 기반 API)
- 10개 엔드포인트 추가:
* GET /items/{code}/bom - BOM 목록 (flat)
* GET /items/{code}/bom/tree - BOM 트리 (계층)
* POST /items/{code}/bom - BOM 추가 (bulk upsert)
* PUT /items/{code}/bom/{lineId} - BOM 수정
* DELETE /items/{code}/bom/{lineId} - BOM 삭제
* GET /items/{code}/bom/summary - BOM 요약
* GET /items/{code}/bom/validate - BOM 검증
* POST /items/{code}/bom/replace - BOM 전체 교체
* POST /items/{code}/bom/reorder - BOM 정렬
* GET /items/{code}/bom/categories - 카테고리 목록
- Swagger 문서 완성 (ItemsBomApi.php)
- i18n 메시지 키 추가 (message.bom.created/updated/deleted)
- Hybrid 구조 지원 (quantity_formula, condition, attributes)
- ItemsController 및 ItemsService CRUD 메서드 구현
- FormRequest 검증 클래스 추가 (ItemStoreRequest, ItemUpdateRequest)
- Swagger 문서 완성 (ItemsApi.php)
- 품목 생성/조회/수정/삭제 엔드포인트 추가
- i18n 메시지 키 추가 (message.item)
- Code 기반 라우팅 적용
- Hybrid 구조 지원 (고정 필드 + attributes JSON)
- TenantStatFieldService: CRUD + reorder + bulkUpsert 로직 구현
- TenantStatFieldController: 7개 엔드포인트 (SAM API Rules 준수)
- FormRequest: Store/Update 검증 클래스 생성
- Swagger: 완전한 API 문서화 (6개 스키마, 7개 엔드포인트)
- i18n: message.tenant_stat_field 키 추가
- Route: /tenant-stat-fields 7개 라우트 등록
유니크 제약 검증: tenant_id + target_table + field_key
집계 함수 필터링: avg, sum, min, max, count
- FormRequest 패턴 적용 (CategoryFieldStoreRequest, CategoryFieldUpdateRequest)
- Service에서 Validator::make() 제거
- Controller 메시지 i18n 키로 변경 (__('message.category_field.*'))
- is_required 타입을 'Y'/'N' → boolean으로 통일
- Swagger 스키마 is_required boolean 타입으로 업데이트
- Model scopeRequired() boolean 조건으로 변경
[추가된 파일]
- app/Models/Tenants/TenantStatField.php
- 테넌트별 통계 필드 설정 모델
- Scopes: forTable, critical, withAggregation, ordered
- 통계 시스템의 메타 정보 제공
- claudedocs/mes/HYBRID_STRUCTURE_GUIDE.md
- 하이브리드 구조 사용 가이드 문서
- 데이터베이스 구조 설명
- 코드 예제 (Product, ProductComponent 생성)
- 통계 쿼리 예제
- 성능 고려사항 및 주의사항
[모델 기능]
- BelongsToTenant, ModelTrait 적용
- aggregation_types JSON 자동 캐스팅
- tenant, target_table, field_key 조합으로 통계 필드 관리
[문서 내용]
- 고정 필드 vs 동적 필드 선택 기준
- attributes JSON 사용법
- 통계 쿼리 예제 (JSON_EXTRACT)
- CategoryField와 연동 방법
- 향후 Virtual Column 최적화 가이드
[변경 이유]
- 추후 별도 통계 시스템 구축 예정
- stat_snapshots는 캐싱용 스냅샷과 통계 시스템 역할이 겹침
- 역할 분리를 위해 제거
[변경 사항]
- stat_snapshots 테이블 rollback 및 마이그레이션 파일 삭제
- tenant_stat_fields 테이블은 유지 (통계 시스템의 메타 정보로 활용)
[유지되는 구조]
- tenant_stat_fields: 각 테넌트가 통계를 원하는 필드 선언
- 통계 시스템 구축 시 이 메타 정보를 기반으로 통계 생성
[향후 계획]
- 각 테넌트별 통계 데이터를 별도 통계 시스템에서 처리
- 리포트 기능에서 테넌트별 커스텀 통계 제공
[모델 업데이트]
- Product 모델: 하이브리드 구조 필드로 fillable/casts 간소화
- 고정 필드: safety_stock, lead_time, is_variable_size, product_category, part_type, attributes_archive
- 동적 필드: attributes JSON (category_fields로 관리)
- 제거: BP-MES 전용 33개 필드 (이제 attributes에 저장)
- ProductComponent 모델: BOM 계산 필드 + 동적 필드
- 고정 필드: quantity_formula, condition
- 동적 필드: attributes JSON
- 제거: is_bending, bending_diagram, bending_details (이제 attributes에 저장)
[Seeder 실행]
- BpMesCategoryFieldsSeeder: FG/PT/절곡품 카테고리 및 필드 생성
- BpMesTenantStatFieldsSeeder: 통계 필드 설정 (마진율, 가공비, 인건비, 설치비 등)
[검증 완료]
- Tinker 모델 테스트 통과
- Pint 코드 포맷팅 검사 통과
- products 테이블: 6개 고정 필드 + attributes JSON
- product_components 테이블: 수식/조건 + attributes JSON
- tenant_stat_fields 테이블: 테넌트별 통계 필드 설정
- stat_snapshots 테이블: 통계 캐싱
- BP-MES CategoryFields Seeder: 제품/부품/절곡품 카테고리 필드
- BP-MES TenantStatFields Seeder: 통계 필드 설정
[변경 사항]
삭제:
- 2025_11_13_120000_extend_products_table_for_bp_mes.php
- 2025_11_13_120001_extend_product_components_table_for_bp_mes.php
추가:
- 2025_11_14_000001_add_hybrid_fields_to_products_table.php
- 2025_11_14_000002_add_attributes_to_product_components_table.php
- 2025_11_14_000003_create_tenant_stat_fields_table.php
- 2025_11_14_000004_create_stat_snapshots_table.php
- BpMesCategoryFieldsSeeder.php
- BpMesTenantStatFieldsSeeder.php
[배경]
멀티테넌트 시스템의 유연성 확보를 위해 고정 필드를 최소화하고
동적 필드 시스템(category_fields + attributes JSON)으로 전환.
통계 성능을 위해 자주 조회하는 분류 필드(product_category, part_type)는
고정 컬럼으로 유지하고 인덱싱.
- GlobalMenuTemplateSeeder 추가: 60개 메뉴 템플릿 생성 (tenant_id=NULL)
- MenuBootstrapService.cloneGlobalMenusForTenant() 추가
- parent_id 매핑으로 계층 구조 유지
- DB 트랜잭션으로 원자성 보장
- RegisterService 업데이트: 신규 회원가입 시 메뉴 템플릿 복제
- 기존 225개 테넌트에 메뉴 일괄 복제 완료
- 테스트 완료: 회원가입 + 로그인 시 60개 메뉴 정상 반환
- 통합 품목 조회 API (materials + products UNION)
- ItemsService, ItemsController, Swagger 문서 생성
- 타입 필터링 (FG/PT/SM/RM/CS), 검색, 카테고리 지원
- Collection merge 방식으로 UNION 쿼리 안정화
- 품목-가격 통합 조회
- PricingService.getPriceByType() 추가 (SALE/PURCHASE 지원)
- 단일 품목 조회 시 판매가/매입가 선택적 포함
- 고객그룹 가격 우선순위 적용 및 시계열 조회
- 자재 타입 명시적 관리
- materials.material_type 컬럼 추가 (SM/RM/CS)
- 기존 데이터 344개 자동 변환 (RAW→RM, SUB→SM)
- 인덱스 추가로 조회 성능 최적화
- DB 데이터 정규화
- products.product_type: 760개 정규화 (PRODUCT→FG, PART/SUBASSEMBLY→PT)
- 타입 코드 표준화로 API 일관성 확보
최종 데이터: 제품 760개(FG 297, PT 463), 자재 344개(SM 215, RM 129)
- MemberService::getUserInfoForLogin(): 사용자 역할 조회 로직 추가
- ApiController::login(): 응답에 roles 포함
- AuthApi (Swagger): roles 응답 스키마 추가
- 로그인 시 해당 회원의 역할 목록 반환 (id, name, description)
fix: 회원가입 시 UserTenant 생성 누락으로 인한 로그인 실패 수정
근본 원인:
- RegisterService는 TenantUserProfile만 생성
- MemberService::getUserInfoForLogin()은 UserTenant 조회
- 회원가입 직후 로그인 시 테넌트 조회 실패 (userTenants->isEmpty() = true)
해결 방안:
- RegisterService에 UserTenant::create() 추가
- TenantUserProfile: 프로필 정보 (부서, 직급 등)
- UserTenant: 접근 권한 관리 (is_active, is_default, joined_at)
영향도:
- 신규 사용자: 로그인 가능하게 수정
- 기존 사용자: 영향 없음 (user_tenants 데이터 이미 존재)
fix: 로그인 시 테넌트 없는 경우 roles 누락 오류 수정
- MemberService::getUserInfoForLogin(): 테넌트가 없는 경우에도 roles 빈 배열 반환
- Undefined array key 'roles' 에러 해결
MemberService.php 권한 조회 로직 수정 - 역할 기반 권한 지원
[문제]
- 회원가입 후 로그인 시 메뉴 리스트가 표시되지 않음
- RegisterService에서 역할에 권한 할당(role_has_permissions)하고
사용자에게 역할 부여(model_has_roles)
- 하지만 MemberService는 model_has_permissions(직접 사용자 권한)만 조회
[원인]
- Spatie Permission 아키텍처 불일치
- 권한이 역할에 저장되었으나 직접 사용자 권한 테이블만 조회
[해결]
- model_has_roles → role_has_permissions → permissions 조인 쿼리로 변경
- UNION으로 직접 권한(model_has_permissions)도 지원하는 하이브리드 방식
- 역할 기반 권한과 직접 권한 모두 조회 가능
[변경 파일]
- app/Services/MemberService.php (getUserInfoForLogin 메서드, 239-259줄)
- enhance_files_table: 이중 파일명 시스템 (display_name/stored_name), 폴더 관리, 문서 연결 지원
- create_folders_table: 동적 폴더 관리 시스템 (tenant별 커스터마이징 가능)
- 5개 stub 마이그레이션 생성 (file_share_links, file_deletion_logs, storage_usage_history, add_storage_columns_to_tenants)
- FolderSeeder stub 생성
- CURRENT_WORKS.md에 Phase 1 진행상황 문서화
fix: 파일 공유 및 삭제 기능 버그 수정
- ShareLinkRequest: PATH 파라미터 {id}를 file_id로 자동 병합
- routes/api.php: 공유 링크 다운로드를 auth.apikey 그룹 밖으로 이동 (인증 불필요)
- FileShareLink: File, Tenant 클래스 import 추가
- File 모델: softDeleteFile()에서 SoftDeletes의 delete() 메서드 사용
- FileStorageService: getTrash(), restoreFile(), permanentDelete()에서 onlyTrashed() 사용
- File 모델: Tenant 네임스페이스 수정 (App\Models\Tenants\Tenant)
refactor: Swagger 문서 정리 - File 태그를 Files로 통합
- FileApi.php의 모든 태그를 Files로 변경
- 구 파일 시스템 라우트 삭제 (prefix 'file')
- 구 FileController.php 삭제
- 신규 파일 저장소 시스템으로 완전 통합
fix: 모든 legacy 파일 컬럼 nullable 일괄 처리
- 5개 legacy 컬럼을 한 번에 nullable로 변경
* original_name, file_name, file_name_old (string)
* fileable_id, fileable_type (polymorphic)
- foreach 루프로 반복 작업 자동화
- 신규/기존 시스템 간 완전한 하위 호환성 확보
fix: legacy 파일 컬럼 nullable 처리 완료
- file_name, file_name_old 컬럼도 nullable로 변경
- 기존 시스템과 신규 시스템 간 완전한 하위 호환성 확보
- Legacy: original_name, file_name, file_name_old (nullable)
- New: display_name, stored_name (required)
fix: original_name 컬럼 nullable 처리
- original_name을 nullable로 변경하여 하위 호환성 유지
- 새 시스템에서는 display_name 사용, 기존 시스템은 original_name 사용 가능
fix: 파일 업로드 DB 컬럼 누락 및 메시지 구조 개선
- files 테이블에 감사 컬럼 추가 (created_by, updated_by, uploaded_by)
- ApiResponse::handle() 메시지 로직 개선 (접미사 제거)
- 다국어 지원을 위한 완성된 문장 구조 유지
- FileUploadRequest 파일 검증 규칙 수정
fix: 파일 저장소 버그 수정 및 신규 테넌트 폴더 자동 생성
- FolderSeeder 네임스페이스 수정 (App\Models\Tenant → App\Models\Tenants\Tenant)
- FileStorageController use 문 구문 오류 수정 (/ → \)
- TenantObserver에 신규 테넌트 기본 폴더 자동 생성 로직 추가
- 5개 기본 폴더 (생산관리, 품질관리, 회계, 인사, 일반)
- 에러 처리 및 로깅
- 회원가입 시 자동 실행
- AuthService: 토큰 발급/갱신 통합 관리
- RefreshController: POST /api/v1/refresh 엔드포인트 추가
- 액세스 토큰 2시간, 리프레시 토큰 7일 (.env 설정)
- TOKEN_EXPIRED 에러 코드로 프론트엔드 자동 리프레시 지원
- 리프레시 토큰 일회성 사용 (보안 강화)
- Swagger 문서 Auth 태그로 통합
주요 변경사항:
- RegisterService.php: 생성된 메뉴 정보를 조회해서 응답에 포함
- RegisterApi.php: Swagger 문서에 menus 배열 스키마 추가
응답 구조:
{
user: {...},
tenant: {...},
menus: [
{id, parent_id, name, url, icon, sort_order, is_external, external_url}
]
}
기술 세부사항:
- 생성된 메뉴 ID 배열을 사용해 Menu::whereIn() 조회
- parent_id, sort_order 순서로 정렬
- 로그인 API와 동일한 메뉴 정보 구조 제공
주요 변경사항:
- MenusStep.php: 존재하지 않는 컬럼(code, route_name, depth, description) 제거
- MenusStep.php: 실제 DB 스키마 컬럼(hidden, is_external, external_url) 추가
- RecipeRegistry.php: MenusStep 비활성화 (하이브리드 메뉴 생성 방식 도입)
- Handler.php: ValidationException 처리 개선 (실제 에러 메시지 표시, 422 상태 코드)
기술 세부사항:
- 하이브리드 접근: TenantBootstrapper(데이터) + MenuBootstrapService(메뉴)
- HTTP 상태 코드 표준화: 422 Unprocessable Entity (validation 실패)
- 실제 검증 에러 메시지 반환: errors 객체에 필드별 에러 정보 포함
