feat(item-master): 잠금 기능 추가 및 FK 레거시 코드 정리

## 잠금 기능 (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 속성 추가 - 프론트엔드 가이드 문서 추가
2025-11-27 15:51:00 +09:00
parent 29fe1415e5
commit efa2a84d2c
35 changed files with 537 additions and 142 deletions
--- a/app/Services/Authz/AccessService.php
+++ b/app/Services/Authz/AccessService.php
@@ -51,21 +51,22 @@ protected static function hasUserOverride(
        $now = now();
        $guard = $guardName ?? config('auth.defaults.guard', 'api'); // ★

-        $q = DB::table('user_permission_overrides as uo')
-            ->join('permissions as p', 'p.id', '=', 'uo.permission_id')
-            ->whereNull('uo.deleted_at')
-            ->where('uo.user_id', $userId)
-            ->where('uo.tenant_id', $tenantId)
+        $q = DB::table('permission_overrides as po')
+            ->join('permissions as p', 'p.id', '=', 'po.permission_id')
+            ->whereNull('po.deleted_at')
+            ->where('po.model_type', 'App\\Models\\Members\\User')
+            ->where('po.model_id', $userId)
+            ->where('po.tenant_id', $tenantId)
            ->where('p.name', $permissionName)
            ->where('p.tenant_id', $tenantId)              // ★ 테넌트 일치
            ->where('p.guard_name', $guard)                // ★ 가드 일치
            ->where(function ($w) use ($now) {
-                $w->whereNull('uo.effective_from')->orWhere('uo.effective_from', '<=', $now);
+                $w->whereNull('po.effective_from')->orWhere('po.effective_from', '<=', $now);
            })
            ->where(function ($w) use ($now) {
-                $w->whereNull('uo.effective_to')->orWhere('uo.effective_to', '>=', $now);
+                $w->whereNull('po.effective_to')->orWhere('po.effective_to', '>=', $now);
            })
-            ->where('uo.is_allowed', $allow ? 1 : 0);
+            ->where('po.effect', $allow ? 1 : 0);

        return $q->exists();
    }
@@ -76,19 +77,27 @@ protected static function departmentAllows(
        int $tenantId,
        ?string $guardName = null
    ): bool {
+        $now = now();
        $guard = $guardName ?? config('auth.defaults.guard', 'api'); // ★

        $q = DB::table('department_user as du')
-            ->join('department_permissions as dp', function ($j) {
-                $j->on('dp.department_id', '=', 'du.department_id')
-                    ->whereNull('dp.deleted_at')
-                    ->where('dp.is_allowed', 1);
+            ->join('permission_overrides as po', function ($j) use ($now) {
+                $j->on('po.model_id', '=', 'du.department_id')
+                    ->where('po.model_type', 'App\\Models\\Tenants\\Department')
+                    ->whereNull('po.deleted_at')
+                    ->where('po.effect', 1)
+                    ->where(function ($w) use ($now) {
+                        $w->whereNull('po.effective_from')->orWhere('po.effective_from', '<=', $now);
+                    })
+                    ->where(function ($w) use ($now) {
+                        $w->whereNull('po.effective_to')->orWhere('po.effective_to', '>=', $now);
+                    });
            })
-            ->join('permissions as p', 'p.id', '=', 'dp.permission_id')
+            ->join('permissions as p', 'p.id', '=', 'po.permission_id')
            ->whereNull('du.deleted_at')
            ->where('du.user_id', $userId)
            ->where('du.tenant_id', $tenantId)
-            ->where('dp.tenant_id', $tenantId)
+            ->where('po.tenant_id', $tenantId)
            ->where('p.tenant_id', $tenantId)              // ★ 테넌트 일치
            ->where('p.guard_name', $guard)                // ★ 가드 일치
            ->where('p.name', $permissionName);
--- a/app/Services/ItemMaster/ItemBomItemService.php
+++ b/app/Services/ItemMaster/ItemBomItemService.php
@@ -6,11 +6,14 @@
 use App\Models\ItemMaster\ItemBomItem;
 use App\Models\ItemMaster\ItemSection;
 use App\Services\Service;
+use App\Traits\LockCheckTrait;
 use Illuminate\Database\Eloquent\Collection;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

 class ItemBomItemService extends Service
 {
+    use LockCheckTrait;
+
    /**
     * 독립 BOM 목록 조회
     *
@@ -147,10 +150,15 @@ public function destroy(int $id): void
            throw new NotFoundHttpException(__('error.not_found'));
        }

+        // 잠금 체크: 이 BOM이 잠금된 연결로 보호되고 있는지 확인
+        $this->checkCanDelete(EntityRelationship::TYPE_BOM, $id);
+
        // 1. entity_relationships에서 이 BOM의 모든 부모 관계 해제
        //    (section→bom 관계에서 이 BOM 제거)
+        //    주의: 잠금된 연결이 있으면 위에서 예외 발생
        EntityRelationship::where('child_type', EntityRelationship::TYPE_BOM)
            ->where('child_id', $id)
+            ->where('is_locked', false)
            ->delete();

        // 2. BOM Soft Delete
--- a/app/Services/ItemMaster/ItemFieldService.php
+++ b/app/Services/ItemMaster/ItemFieldService.php
@@ -5,11 +5,14 @@
 use App\Models\ItemMaster\EntityRelationship;
 use App\Models\ItemMaster\ItemField;
 use App\Services\Service;
+use App\Traits\LockCheckTrait;
 use Illuminate\Database\Eloquent\Collection;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

 class ItemFieldService extends Service
 {
+    use LockCheckTrait;
+
    /**
     * 모든 필드 목록 조회
     *
@@ -223,10 +226,15 @@ public function destroy(int $id): void
            throw new NotFoundHttpException(__('error.not_found'));
        }

+        // 잠금 체크: 이 필드가 잠금된 연결로 보호되고 있는지 확인
+        $this->checkCanDelete(EntityRelationship::TYPE_FIELD, $id);
+
        // 1. entity_relationships에서 이 필드의 모든 부모 관계 해제
        //    (section→field, page→field 관계에서 이 필드 제거)
+        //    주의: 잠금된 연결이 있으면 위에서 예외 발생
        EntityRelationship::where('child_type', EntityRelationship::TYPE_FIELD)
            ->where('child_id', $id)
+            ->where('is_locked', false)
            ->delete();

        // 2. 필드 Soft Delete
--- a/app/Services/ItemMaster/ItemMasterService.php
+++ b/app/Services/ItemMaster/ItemMasterService.php
@@ -4,8 +4,8 @@

 use App\Models\ItemMaster\CustomTab;
 use App\Models\ItemMaster\EntityRelationship;
+use App\Models\ItemMaster\ItemBomItem;
 use App\Models\ItemMaster\ItemField;
-use App\Models\ItemMaster\ItemMasterField;
 use App\Models\ItemMaster\ItemPage;
 use App\Models\ItemMaster\ItemSection;
 use App\Models\ItemMaster\UnitOption;
@@ -18,7 +18,6 @@ class ItemMasterService extends Service
     *
     * - pages (linkedSections 기반 중첩)
     * - sections (모든 독립 섹션)
-     * - masterFields
     * - customTabs (columnSetting 포함)
     * - unitOptions
     */
@@ -57,22 +56,18 @@ public function init(): array
            ->orderBy('created_at', 'desc')
            ->get();

-        // 4. 마스터 필드
-        $masterFields = ItemMasterField::where('tenant_id', $tenantId)->get();
-
-        // 5. 커스텀 탭 (컬럼 설정 포함)
+        // 4. 커스텀 탭 (컬럼 설정 포함)
        $customTabs = CustomTab::with('columnSetting')
            ->where('tenant_id', $tenantId)
            ->orderBy('order_no')
            ->get();

-        // 6. 단위 옵션
+        // 5. 단위 옵션
        $unitOptions = UnitOption::where('tenant_id', $tenantId)->get();

        return [
            'pages' => $pagesWithSections,
            'sections' => $sections,
-            'masterFields' => $masterFields,
            'customTabs' => $customTabs,
            'unitOptions' => $unitOptions,
        ];
@@ -99,15 +94,24 @@ private function getLinkedSections(int $tenantId, int $pageId): array
            if ($section) {
                // 섹션에 연결된 필드 (entity_relationships 기반)
                $linkedFields = $this->getLinkedFields($tenantId, $section->id);
+                // 섹션에 연결된 BOM 항목 (entity_relationships 기반)
+                $linkedBomItems = $this->getLinkedBomItems($tenantId, $section->id);

                $sectionData = $section->toArray();
                $sectionData['order_no'] = $rel->order_no;
+                // 연결 잠금 상태 (이 페이지-섹션 관계의 잠금)
+                $sectionData['is_locked'] = (bool) $rel->is_locked;

                // FK 기반 필드 + 링크 기반 필드 병합
                if (! empty($linkedFields)) {
                    $sectionData['fields'] = $linkedFields;
                }

+                // FK 기반 BOM + 링크 기반 BOM 병합
+                if (! empty($linkedBomItems)) {
+                    $sectionData['bom_items'] = $linkedBomItems;
+                }
+
                $sections[] = $sectionData;
            }
        }
@@ -133,10 +137,39 @@ private function getLinkedFields(int $tenantId, int $sectionId): array
            if ($field) {
                $fieldData = $field->toArray();
                $fieldData['order_no'] = $rel->order_no;
+                // 연결 잠금 상태 (이 섹션-필드 관계의 잠금)
+                $fieldData['is_locked'] = (bool) $rel->is_locked;
                $fields[] = $fieldData;
            }
        }

        return $fields;
    }
+
+    /**
+     * 섹션에 연결된 BOM 항목 조회 (entity_relationships 기반)
+     */
+    private function getLinkedBomItems(int $tenantId, int $sectionId): array
+    {
+        $relationships = EntityRelationship::where('tenant_id', $tenantId)
+            ->where('parent_type', EntityRelationship::TYPE_SECTION)
+            ->where('parent_id', $sectionId)
+            ->where('child_type', EntityRelationship::TYPE_BOM)
+            ->orderBy('order_no')
+            ->get();
+
+        $bomItems = [];
+        foreach ($relationships as $rel) {
+            $bomItem = ItemBomItem::find($rel->child_id);
+            if ($bomItem) {
+                $bomData = $bomItem->toArray();
+                $bomData['order_no'] = $rel->order_no;
+                // 연결 잠금 상태 (이 섹션-BOM 관계의 잠금)
+                $bomData['is_locked'] = (bool) $rel->is_locked;
+                $bomItems[] = $bomData;
+            }
+        }
+
+        return $bomItems;
+    }
 }
--- a/app/Services/ItemMaster/ItemPageService.php
+++ b/app/Services/ItemMaster/ItemPageService.php
@@ -2,14 +2,18 @@

 namespace App\Services\ItemMaster;

+use App\Exceptions\BusinessException;
 use App\Models\ItemMaster\EntityRelationship;
 use App\Models\ItemMaster\ItemPage;
 use App\Services\Service;
+use App\Traits\LockCheckTrait;
 use Illuminate\Support\Collection;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

 class ItemPageService extends Service
 {
+    use LockCheckTrait;
+
    /**
     * 페이지 목록 조회 (섹션/필드 중첩)
     */
@@ -104,10 +108,22 @@ public function destroy(int $id): void
            throw new NotFoundHttpException(__('error.not_found'));
        }

+        // 잠금 체크: 이 페이지의 자식 관계 중 잠금된 것이 있는지 확인
+        $hasLockedChildren = EntityRelationship::where('parent_type', EntityRelationship::TYPE_PAGE)
+            ->where('parent_id', $id)
+            ->where('is_locked', true)
+            ->exists();
+
+        if ($hasLockedChildren) {
+            throw new BusinessException(__('error.page_has_locked_children'));
+        }
+
        // 1. entity_relationships에서 이 페이지의 모든 자식 관계 해제
        //    (page→section, page→field 관계 삭제)
+        //    주의: 잠금된 연결이 없는 상태에서만 진입
        EntityRelationship::where('parent_type', EntityRelationship::TYPE_PAGE)
            ->where('parent_id', $id)
+            ->where('is_locked', false)
            ->delete();

        // 2. 페이지만 Soft Delete (섹션/필드는 독립 엔티티로 유지)
--- a/app/Services/ItemMaster/ItemSectionService.php
+++ b/app/Services/ItemMaster/ItemSectionService.php
@@ -7,11 +7,14 @@
 use App\Models\ItemMaster\ItemField;
 use App\Models\ItemMaster\ItemSection;
 use App\Services\Service;
+use App\Traits\LockCheckTrait;
 use Illuminate\Database\Eloquent\Collection;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

 class ItemSectionService extends Service
 {
+    use LockCheckTrait;
+
    /**
     * 모든 섹션 목록 조회
     *
@@ -89,12 +92,11 @@ public function clone(int $id): ItemSection
            'created_by' => $userId,
        ]);

-        // 필드 복제
-        foreach ($original->fields as $field) {
-            ItemField::create([
+        // 필드 복제 (entity_relationships 기반)
+        foreach ($original->fields as $orderNo => $field) {
+            $clonedField = ItemField::create([
                'tenant_id' => $tenantId,
                'group_id' => $field->group_id,
-                'section_id' => $cloned->id,
                'field_name' => $field->field_name,
                'field_type' => $field->field_type,
                'order_no' => $field->order_no,
@@ -107,14 +109,25 @@ public function clone(int $id): ItemSection
                'properties' => $field->properties,
                'created_by' => $userId,
            ]);
+
+            // 섹션-필드 관계 생성
+            EntityRelationship::link(
+                $tenantId,
+                EntityRelationship::TYPE_SECTION,
+                $cloned->id,
+                EntityRelationship::TYPE_FIELD,
+                $clonedField->id,
+                $field->order_no,
+                null,
+                $field->group_id
+            );
        }

-        // BOM 항목 복제
-        foreach ($original->bomItems as $bom) {
-            ItemBomItem::create([
+        // BOM 항목 복제 (entity_relationships 기반)
+        foreach ($original->bomItems as $orderNo => $bom) {
+            $clonedBom = ItemBomItem::create([
                'tenant_id' => $tenantId,
                'group_id' => $bom->group_id,
-                'section_id' => $cloned->id,
                'item_code' => $bom->item_code,
                'item_name' => $bom->item_name,
                'quantity' => $bom->quantity,
@@ -125,6 +138,18 @@ public function clone(int $id): ItemSection
                'note' => $bom->note,
                'created_by' => $userId,
            ]);
+
+            // 섹션-BOM 관계 생성
+            EntityRelationship::link(
+                $tenantId,
+                EntityRelationship::TYPE_SECTION,
+                $cloned->id,
+                EntityRelationship::TYPE_BOM,
+                $clonedBom->id,
+                $orderNo,
+                null,
+                $bom->group_id
+            );
        }

        return $cloned->load(['fields', 'bomItems']);
@@ -227,6 +252,8 @@ public function update(int $id, array $data): ItemSection
     * 섹션 삭제 (Soft Delete)
     *
     * 독립 엔티티 아키텍처: 섹션만 삭제하고 연결된 필드/BOM은 unlink만 수행
+     *
+     * @throws \App\Exceptions\BusinessException 잠금된 연결이 있는 경우
     */
    public function destroy(int $id): void
    {
@@ -241,17 +268,25 @@ public function destroy(int $id): void
            throw new NotFoundHttpException(__('error.not_found'));
        }

+        // 잠금 체크: 이 섹션이 잠금된 연결로 보호되고 있는지 확인
+        $this->checkCanDelete(EntityRelationship::TYPE_SECTION, $id);
+
        // 1. entity_relationships에서 이 섹션의 모든 부모 관계 해제
        //    (page→section 관계에서 이 섹션 제거)
+        //    주의: 잠금된 연결이 있으면 예외 발생
        EntityRelationship::where('child_type', EntityRelationship::TYPE_SECTION)
            ->where('child_id', $id)
+            ->where('is_locked', false)
            ->delete();

        // 2. entity_relationships에서 이 섹션의 모든 자식 관계 해제
        //    (section→field, section→bom 관계 삭제)
-        EntityRelationship::where('parent_type', EntityRelationship::TYPE_SECTION)
-            ->where('parent_id', $id)
-            ->delete();
+        //    주의: 잠금된 연결이 있으면 예외 발생 (unlinkAllChildren에서 처리)
+        EntityRelationship::unlinkAllChildren(
+            $tenantId,
+            EntityRelationship::TYPE_SECTION,
+            $id
+        );

        // 3. 섹션만 Soft Delete (필드/BOM은 독립 엔티티로 유지)
        $section->update(['deleted_by' => $userId]);
--- a/app/Services/ItemMaster/SectionTemplateService.php
+++ b/app/Services/ItemMaster/SectionTemplateService.php
@@ -50,11 +50,10 @@ public function store(array $data): ItemSection
            }
        }

-        // 1. 독립 섹션 생성 (page_id=null)
+        // 1. 독립 섹션 생성
        $section = ItemSection::create([
            'tenant_id' => $tenantId,
            'group_id' => 1,
-            'page_id' => null,
            'title' => $data['title'],
            'type' => $data['type'],
            'order_no' => 0,