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/Http/Controllers/Api/V1/ItemMaster/CustomTabController.php
+++ b/app/Http/Controllers/Api/V1/ItemMaster/CustomTabController.php
@@ -2,11 +2,11 @@

 namespace App\Http\Controllers\Api\V1\ItemMaster;

+use App\Helpers\ApiResponse;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\ItemMaster\CustomTabStoreRequest;
 use App\Http\Requests\ItemMaster\CustomTabUpdateRequest;
 use App\Http\Requests\ItemMaster\ReorderRequest;
-use App\Helpers\ApiResponse;
 use App\Services\ItemMaster\CustomTabService;

 class CustomTabController extends Controller
--- a/app/Http/Controllers/Api/V1/ItemMaster/SectionTemplateController.php
+++ b/app/Http/Controllers/Api/V1/ItemMaster/SectionTemplateController.php
@@ -2,10 +2,10 @@

 namespace App\Http\Controllers\Api\V1\ItemMaster;

+use App\Helpers\ApiResponse;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\ItemMaster\SectionTemplateStoreRequest;
 use App\Http\Requests\ItemMaster\SectionTemplateUpdateRequest;
-use App\Helpers\ApiResponse;
 use App\Services\ItemMaster\SectionTemplateService;

 class SectionTemplateController extends Controller
--- a/app/Http/Controllers/Api/V1/ItemMaster/UnitOptionController.php
+++ b/app/Http/Controllers/Api/V1/ItemMaster/UnitOptionController.php
@@ -2,9 +2,9 @@

 namespace App\Http\Controllers\Api\V1\ItemMaster;

+use App\Helpers\ApiResponse;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\ItemMaster\UnitOptionStoreRequest;
-use App\Helpers\ApiResponse;
 use App\Services\ItemMaster\UnitOptionService;

 class UnitOptionController extends Controller
--- a/app/Models/ItemMaster/EntityRelationship.php
+++ b/app/Models/ItemMaster/EntityRelationship.php
@@ -28,6 +28,9 @@ class EntityRelationship extends Model
        'child_id',
        'order_no',
        'metadata',
+        'is_locked',
+        'locked_by',
+        'locked_at',
        'created_by',
        'updated_by',
    ];
@@ -38,6 +41,8 @@ class EntityRelationship extends Model
        'child_id' => 'integer',
        'order_no' => 'integer',
        'metadata' => 'array',
+        'is_locked' => 'boolean',
+        'locked_at' => 'datetime',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];
@@ -146,6 +151,8 @@ public static function link(

    /**
     * 관계 해제
+     *
+     * @throws \App\Exceptions\BusinessException 잠금된 연결인 경우
     */
    public static function unlink(
        int $tenantId,
@@ -155,18 +162,31 @@ public static function unlink(
        int $childId,
        int $groupId = self::GROUP_ITEM_MASTER
    ): bool {
-        return self::where([
+        $relationship = self::where([
            'tenant_id' => $tenantId,
            'group_id' => $groupId,
            'parent_type' => $parentType,
            'parent_id' => $parentId,
            'child_type' => $childType,
            'child_id' => $childId,
-        ])->delete() > 0;
+        ])->first();
+
+        if (! $relationship) {
+            return false;
+        }
+
+        // 잠금 체크
+        if ($relationship->is_locked) {
+            throw new \App\Exceptions\BusinessException(__('error.relationship_locked'));
+        }
+
+        return $relationship->delete();
    }

    /**
-     * 특정 부모의 모든 자식 관계 해제
+     * 특정 부모의 모든 자식 관계 해제 (잠금되지 않은 것만)
+     *
+     * @throws \App\Exceptions\BusinessException 잠금된 연결이 있는 경우
     */
    public static function unlinkAllChildren(
        int $tenantId,
@@ -186,6 +206,43 @@ public static function unlinkAllChildren(
            $query->where('child_type', $childType);
        }

+        // 잠금된 연결이 있는지 확인
+        if ($query->clone()->where('is_locked', true)->exists()) {
+            throw new \App\Exceptions\BusinessException(__('error.has_locked_relationships'));
+        }
+
        return $query->delete();
    }
+
+    /**
+     * 특정 자식 엔티티가 잠금된 연결을 가지고 있는지 확인
+     */
+    public static function hasLockedParentRelationship(string $childType, int $childId): bool
+    {
+        return self::where('child_type', $childType)
+            ->where('child_id', $childId)
+            ->where('is_locked', true)
+            ->exists();
+    }
+
+    /**
+     * 특정 자식 엔티티의 잠금 상태 조회 (computed)
+     * 연결이 잠겨있으면 엔티티도 잠금 상태로 간주
+     */
+    public static function getChildLockStatus(string $childType, int $childId): array
+    {
+        $lockedRelationships = self::where('child_type', $childType)
+            ->where('child_id', $childId)
+            ->where('is_locked', true)
+            ->get(['id', 'parent_type', 'parent_id']);
+
+        return [
+            'is_locked' => $lockedRelationships->isNotEmpty(),
+            'locked_by_relationships' => $lockedRelationships->map(fn ($rel) => [
+                'relationship_id' => $rel->id,
+                'parent_type' => $rel->parent_type,
+                'parent_id' => $rel->parent_id,
+            ])->toArray(),
+        ];
+    }
 }
--- a/app/Models/ItemMaster/ItemPage.php
+++ b/app/Models/ItemMaster/ItemPage.php
@@ -36,14 +36,6 @@ class ItemPage extends Model
        'deleted_at',
    ];

-    /**
-     * 페이지의 섹션 목록 (기존 FK 기반 - 하위 호환성)
-     */
-    public function sections()
-    {
-        return $this->hasMany(ItemSection::class, 'page_id')->orderBy('order_no');
-    }
-
    /**
     * 페이지와 연결된 섹션 관계 목록 (링크 테이블 기반)
     */
--- a/app/Models/ItemMaster/UnitOption.php
+++ b/app/Models/ItemMaster/UnitOption.php
@@ -30,4 +30,4 @@ class UnitOption extends Model
        'deleted_by',
        'deleted_at',
    ];
-}
+}
--- 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,
--- a/app/Swagger/v1/ItemMasterApi.php
+++ b/app/Swagger/v1/ItemMasterApi.php
@@ -42,6 +42,7 @@
 *   @OA\Property(property="order_no", type="integer", example=0),
 *   @OA\Property(property="is_template", type="boolean", example=false, description="템플릿 여부"),
 *   @OA\Property(property="is_default", type="boolean", example=false, description="기본 템플릿 여부"),
+ *   @OA\Property(property="is_locked", type="boolean", example=false, description="연결 잠금 여부 (init API 응답 시 포함)"),
 *   @OA\Property(property="description", type="string", nullable=true, example="섹션 설명"),
 *   @OA\Property(property="created_at", type="string", example="2025-11-20 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-11-20 10:00:00"),
@@ -53,7 +54,7 @@
 *   ),
 *
 *   @OA\Property(
- *     property="bomItems",
+ *     property="bom_items",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/ItemBomItem")
@@ -72,6 +73,7 @@
 *   @OA\Property(property="field_type", type="string", enum={"textbox","number","dropdown","checkbox","date","textarea"}, example="textbox"),
 *   @OA\Property(property="order_no", type="integer", example=0),
 *   @OA\Property(property="is_required", type="boolean", example=true),
+ *   @OA\Property(property="is_locked", type="boolean", example=false, description="연결 잠금 여부 (init API 응답 시 포함)"),
 *   @OA\Property(property="default_value", type="string", nullable=true, example=null),
 *   @OA\Property(property="placeholder", type="string", nullable=true, example="제품명을 입력하세요"),
 *   @OA\Property(property="display_condition", type="object", nullable=true, example=null),
@@ -101,6 +103,7 @@
 *   @OA\Property(property="total_price", type="number", format="float", nullable=true, example=15000),
 *   @OA\Property(property="spec", type="string", nullable=true, example="규격 정보"),
 *   @OA\Property(property="note", type="string", nullable=true, example="비고"),
+ *   @OA\Property(property="is_locked", type="boolean", example=false, description="연결 잠금 여부 (init API 응답 시 포함)"),
 *   @OA\Property(property="created_at", type="string", example="2025-11-20 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-11-20 10:00:00")
 * )
--- a/app/Swagger/v1/ItemsFileApi.php
+++ b/app/Swagger/v1/ItemsFileApi.php
@@ -78,15 +78,16 @@ class ItemsFileApi
     *                     property="bending_details",
     *                     type="array",
     *                     description="절곡 상세 정보 (bending_diagram 타입일 때만)",
+     *
     *                     @OA\Items(
     *                         type="object",
     *                         required={"angle", "length", "type"},
+     *
     *                         @OA\Property(property="angle", type="number", format="float", example=90, description="절곡 각도"),
     *                         @OA\Property(property="length", type="number", format="float", example=100.5, description="절곡 길이"),
     *                         @OA\Property(property="type", type="string", example="V형", description="절곡 타입")
     *                     )
     *                 ),
-     *
     *                 @OA\Property(
     *                     property="certification_number",
     *                     type="string",
--- a/app/Traits/LockCheckTrait.php
+++ b/app/Traits/LockCheckTrait.php
@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Traits;
+
+use App\Exceptions\BusinessException;
+use App\Models\ItemMaster\EntityRelationship;
+
+/**
+ * LockCheckTrait - 엔티티 잠금 체크 공통 로직
+ *
+ * 연결(entity_relationships)의 is_locked가 true인 경우:
+ * - 해당 연결 해제 불가
+ * - 연결된 자식 엔티티 삭제 불가 (연결을 통한 보호)
+ */
+trait LockCheckTrait
+{
+    /**
+     * 엔티티 삭제 가능 여부 체크
+     * 잠금된 연결이 있으면 삭제 불가
+     *
+     * @throws BusinessException 잠금된 연결이 있는 경우
+     */
+    protected function checkCanDelete(string $entityType, int $entityId): void
+    {
+        if (EntityRelationship::hasLockedParentRelationship($entityType, $entityId)) {
+            throw new BusinessException(__('error.entity_protected_by_locked_relationship'));
+        }
+    }
+
+    /**
+     * 엔티티의 잠금 상태 조회 (API Response용)
+     */
+    protected function getEntityLockStatus(string $entityType, int $entityId): array
+    {
+        return EntityRelationship::getChildLockStatus($entityType, $entityId);
+    }
+
+    /**
+     * 엔티티가 잠금 상태인지 확인 (연결을 통한 잠금 포함)
+     */
+    protected function isEntityLocked(string $entityType, int $entityId): bool
+    {
+        return EntityRelationship::hasLockedParentRelationship($entityType, $entityId);
+    }
+}