- ItemField 모델: 소스 매핑 컬럼 추가 (source_table, source_column 등)
- ItemPage 모델: source_table 컬럼 추가
- ItemDataService: 동적 데이터 조회 서비스
- ItemMasterApi Swagger 업데이트
- ItemTypeSeeder: 품목 유형 시더
- 스펙 문서: ITEM_MASTER_FIELD_INTEGRATION_PLAN.md
- Price, PriceRevision 모델 추가 (PriceHistory 대체)
- PricingService: CRUD, 원가 조회, 확정 기능
- PricingController: statusCode 파라미터로 201 반환 지원
- NotFoundHttpException(404) 적용 (존재하지 않는 리소스)
- FormRequest 분리 (Store, Update, Index, Cost, ByItems)
- Swagger 문서 업데이트
- ApiResponse::handle()에 statusCode 옵션 추가
- prices/price_revisions 마이그레이션 및 데이터 이관
- 마이그레이션: is_active 컬럼 추가 (기본값 true)
- ItemField 모델: fillable, casts에 is_active 추가
- ItemFieldService: store, storeIndependent, clone, update 메서드에 is_active 처리
- FormRequest: is_active 유효성 검사 규칙 추가
- API Flow 테스트 시나리오 추가 (docs/api-flows/)
- docs/INDEX.md에 api-flows 섹션 추가
ModelTrait::scopeActive() 메서드 사용을 위한 필수 컬럼
- 거래처 유형(client_type), 연락처(mobile, fax), 담당자 정보 필드 추가
- 발주처 설정(account_id/password, payment_day) 필드 추가
- 약정 세금(tax_agreement, tax_amount, tax_start/end_date) 필드 추가
- 악성채권(bad_debt 관련 5개 필드) 정보 필드 추가
- Model, Service, FormRequest, Swagger 문서 업데이트
- 견적 API 계획에 문서 발송 API(email/fax/kakao) 요구사항 추가
- 삭제 전 product_components 테이블에서 사용 여부 확인
- BOM 구성품으로 사용 중인 품목 삭제 차단 (400 에러)
- 일괄 삭제에도 동일한 참조 체크 적용
- 품목 관련 에러 메시지 추가 (error.item.*)
- 품목 삭제 API 테스트 플로우 JSON 추가
- global_menus 테이블 분리를 위한 menus 컬럼 추가 (global_menu_id, is_customized)
- GlobalMenuController: 글로벌 메뉴 CRUD API
- GlobalMenuService: 글로벌 메뉴 비즈니스 로직
- MenuSyncService: 테넌트 메뉴 동기화 서비스
- MenuBootstrapService: 테넌트 초기 메뉴 생성 로직 개선
- MenuController: 메뉴 재동기화 엔드포인트 추가
- 중복 코드 자동 증가 기능 추가 (P-001 → P-002, ABC → ABC-001)
- soft delete 항목 조회 파라미터 추가 (include_deleted)
- ValidationException 응답 포맷 수정 (공통 에러 형식)
- batch delete 라우트 순서 수정 (/{id} 보다 /batch 먼저)
- is_active 기본값 true 설정
- BoardController, PostController 추가
- Board, BoardSetting 모델 수정
- BoardService 추가
- FormRequest 클래스 추가
- Swagger 문서 추가 (BoardApi, PostApi)
- 게시판 시스템 필드 마이그레이션 추가
- field_key: {ID}_{key} 형식으로 고유키 생성
- is_locked, locked_by, locked_at 잠금 컬럼 추가
- ItemFieldService: store/update/clone 로직 수정
- FormRequest: field_key 검증 규칙 추가
- Swagger 스키마 업데이트
- 섹션 복제 시 필드를 새로 CREATE하던 로직 제거
- 섹션 복제 시 BOM을 새로 CREATE하던 로직 제거
- 기존 필드/BOM ID로 EntityRelationship 링크만 생성
- 독립 엔티티 아키텍처 원칙 준수 (복제 = 자신만 복제 + 관계 링크만 복제)
- 불필요한 use 문 제거 (ItemField, ItemBomItem)
- EntityRelationship::link() 호출 파라미터 순서 수정 (3개 파일)
- ItemSectionService: tenantId를 첫 번째 파라미터로 변경
- ItemBomItemService: tenantId를 첫 번째 파라미터로 변경
- ItemFieldService: tenantId를 첫 번째 파라미터로 변경
- ItemSection 모델의 fields()/bomItems() 관계 메서드 문제 해결
- 쿼리빌더 반환으로 인한 addEagerConstraints() 에러 수정
- loadRelatedEntities() 메서드 신규 추가
- with()/load() 대신 setRelation()으로 데이터 설정
- 영향받은 서비스 파일 전체 수정
- ItemSectionService, SectionTemplateService, ItemMasterService
## 잠금 기능 (Lock Feature)
- entity_relationships 테이블에 is_locked, locked_by, locked_at 컬럼 추가
- EntityRelationship 모델에 잠금 관련 헬퍼 메서드 추가
- LockCheckTrait 생성 (destroy 시 잠금 체크 공통 로직)
- 각 Service의 destroy() 메서드에 잠금 체크 적용
- API 응답에 is_locked 필드 포함
- 한국어 에러 메시지 추가
## FK 레거시 코드 정리
- ItemMasterSeeder: entity_relationships 기반으로 전환
- ItemPage 모델: FK 기반 sections() 관계 제거
- ItemSectionService: clone() 메서드 FK 제거
- SectionTemplateService: page_id 컬럼 참조 제거
- EntityRelationship::link() 파라미터 순서 통일
## 기타
- Swagger 스키마에 is_locked 속성 추가
- 프론트엔드 가이드 문서 추가
- FK 컬럼 제거: item_sections.page_id, item_fields.section_id, item_bom_items.section_id
- entity_relationships 테이블로 전환하여 독립 엔티티 구조 확립
- ItemMasterField 관련 파일 삭제 (Controller, Service, Model, Requests)
- destroy 메서드 독립 엔티티 아키텍처 적용 (관계 링크만 삭제)
- Swagger 스키마에서 FK 참조 제거
- FormRequest 및 Swagger에 group_id(계층번호) 필드 추가
- SectionTemplateService: 독립 섹션 생성, page_id 있으면 링크 연결
- ItemMasterService: init API가 linkedSections 기반으로 조회
- SectionTemplateStoreRequest: page_id nullable로 변경
- Swagger: 스키마 업데이트 (sectionTemplates → sections)
- CASCADE FK → 독립 엔티티 + entity_relationships 링크 테이블
- 독립 API 10개 추가 (섹션/필드/BOM CRUD, clone, usage)
- SectionTemplate 모델 제거 → ItemSection.is_template 통합
- 페이지-섹션, 섹션-필드, 섹션-BOM 링크/언링크 API 14개 추가
- Swagger 문서 업데이트
- 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 준수
- 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
- 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 조건으로 변경
- 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 객체에 필드별 에러 정보 포함
- MenuBootstrapService 생성: 새 테넌트를 위한 기본 메뉴 9개 자동 생성
- 대시보드
- 기초정보관리 (제품/거래처/BOM 관리)
- 시스템 관리 (사용자/권한/부서 관리)
- RegisterService 수정: 메뉴 생성 후 권한 자동 설정
- 생성된 메뉴에 대한 권한(menu.{id}) 자동 생성
- system_manager 역할에 모든 메뉴 권한 할당
- 기존 테이블 구조에 맞게 구현 (code, route_name, depth, description 컬럼 미사용)
- message.registered 수정: '회원가입 처리'로 변경 (에러 메시지 개선)
- RecipeRegistry 호출 제거 (클래스 존재하지 않음)
- 메뉴 기반 권한 생성 로직 제거
- system_manager 역할만 생성하고 사용자에게 부여
- 메뉴 테이블 컬럼 불일치 오류 해결
현재는 기본 회원가입 기능만 제공:
- 테넌트 생성 (코드 자동 생성)
- 사용자 생성
- 테넌트-사용자 프로필 연결
- system_manager 역할 부여
향후 메뉴 시스템이 완성되면 RecipeRegistry를 다시 활성화할 예정
- TenantCodeGenerator 헬퍼 클래스 생성
- 한글 초성 추출 및 영문 변환
- Base-36 순번 생성 (최대 1,679,616 코드)
- 순환형 코드 생성 (초성+순번 조합)
- RegisterService에서 테넌트 생성 시 코드 자동 생성
- 회원가입 시 'code' 필드 누락 오류 해결
- MemberService::getUserInfoForLogin() 메서드 추가
- 사용자 기본 정보 (id, user_id, name, email, phone)
- 활성 테넌트 정보 (is_default 우선 → is_active 차순)
- 테넌트 없는 경우 null 반환
- 추가 테넌트 목록 (other_tenants 배열)
- 권한 기반 메뉴 필터링 (menu:{id}.view)
- 권한 체크 3단계
- 기본 Role 권한 (model_has_permissions)
- Override 권한 (permission_overrides, 시간 제약)
- 우선순위: deny(-1) > allow(1) > base permission
- ApiController::login() 응답 구조 변경
- 기존: {message, user_token}
- 개선: {message, user_token, user, tenant, menus}
- Swagger 문서 업데이트 (AuthApi.php)
- 테넌트 있는 경우 응답 스키마
- 테넌트 없는 경우 응답 스키마 (null)
- 에러 케이스 추가 (400, 401, 404)
