# 레이아웃 JSON - 상속 (Extends, Partial, 병합)

> **메인 문서**: [layout-json.md](layout-json.md)
> **관련 문서**: [layout-json-features.md](layout-json-features.md) | [layout-json-components.md](layout-json-components.md)

---

## TL;DR (5초 요약)

```text
1. extends: 베이스 레이아웃 상속 (type: "slot" 위치에 삽입)
2. slots: 상속 시 슬롯별 컴포넌트 배열 정의
3. partials: 파일 분할 (컴포넌트 내용만 치환)
4. 병합 규칙: extends 상속 시 data_sources, modals, init_actions, computed, globalHeaders 자동 병합
5. globalHeaders 병합: pattern 기준으로 병합, 동일 pattern은 headers 병합 (자식 우선)
6. Partial은 컴포넌트 치환만! computed/data_sources 등은 부모 레이아웃에 정의!
7. 독립 레이아웃(extends 없음)은 Toast/Modal 등 글로벌 호스트 컴포넌트를 직접 마운트해야 함 (engine-v1.47.1 명문화)
```

## 독립 레이아웃의 글로벌 호스트 컴포넌트 (CRITICAL)

`extends` 가 없는 독립 레이아웃(예: `admin_login.json`)은 베이스의 `Toast`, `ModalRoot` 등 글로벌 호스트 컴포넌트를 자동으로 마운트하지 않는다. `toast` / `openModal` 같은 핸들러는 `_global.toasts` / `_global.modal` 에 데이터를 push 만 하고 화면 렌더는 호스트 컴포넌트의 책임이므로, 호스트 미마운트 상태에서 핸들러를 호출하면 `success` 로 기록되지만 사용자에게 보이지 않는 silent failure 가 발생한다.

```text
❌ 독립 레이아웃에서 init_actions 의 toast / openModal 발화 + 호스트 컴포넌트 누락
   → 핸들러 success / 화면 미노출 → 회귀 (시각적으로 무동작)

✅ 독립 레이아웃 components 최상단에 호스트 컴포넌트 직접 추가
   - Toast: { id, type: "composite", name: "Toast",
              props: { toasts: "{{_global.toasts}}", position, duration } }
   - 베이스 레이아웃의 호스트 컴포넌트 정의를 그대로 복사하는 것을 권장
```

### 베이스 레이아웃의 호스트 컴포넌트 위치

| 템플릿 | 베이스 레이아웃 | Toast 컴포넌트 위치 |
|--------|----------------|--------------------|
| sirsoft-admin_basic | `layouts/_admin_base.json` | `components[0]` (id: `global_toast`) |
| sirsoft-basic | `layouts/_user_base.json` | components 내 `Toast` 항목 |

독립 레이아웃을 작성할 때는 위 베이스의 `global_toast` (또는 동등 항목) 블록을 그대로 복사한다. 사용자 정의 변형 없이 정의를 통일하면 회귀가 발생하지 않는다.

---

## Partial 처리 방식

```text
필수: Partial 처리는 "단순 컴포넌트 치환"입니다!

Partial 처리 시 {"partial": "path"} 객체가 해당 파일의 컴포넌트 내용으로 치환됩니다.
최상위 속성(computed, data_sources, modals, init_actions 등)은 병합되지 않습니다!

✅ Partial에서 사용 가능:
   - 컴포넌트 정의 (type, name, children, props 등)
   - 데이터 바인딩 표현식 ({{...}})
   - $computed 참조 (부모 레이아웃에 정의된 computed 사용)
   - 조건부 렌더링 (if), 반복 (iteration) 등

❌ Partial에서 정의해도 무시되는 속성 (전체 목록):
   - computed: 부모 레이아웃과 병합되지 않음
   - data_sources: 부모 레이아웃과 병합되지 않음
   - modals: 부모 레이아웃과 병합되지 않음
   - init_actions: 부모 레이아웃과 병합되지 않음
   - state: 부모 레이아웃과 병합되지 않음
   - version: 부모 레이아웃 버전이 사용됨
   - layout_name: 부모 레이아웃 이름이 사용됨
   - extends: partial에서 extends 사용 불가
   - slots: partial은 슬롯 정의 불가
   - classMap: 부모 레이아웃과 병합되지 않음
   - errorHandling: 부모 레이아웃과 병합되지 않음
   - scripts: 부모 레이아웃과 병합되지 않음

최상위 속성은 반드시 부모 레이아웃(메인 레이아웃)에 정의해야 합니다!

💡 기술적 이유: Partial 처리는 {"partial": "path"} 객체를 파일 내용으로 치환합니다.
   치환된 내용은 컴포넌트 배열 내에 삽입되므로, 레이아웃 최상위 속성은 의미가 없습니다.
   extends 상속과 달리 partial은 mergeComputed(), mergeDataSources() 등을 호출하지 않습니다.
```

**병합 흐름**:

```text
[메인 레이아웃]
    ↓
[{"partial": "path"} 객체 탐색]
    ↓
[해당 파일 로드 후 컴포넌트 내용으로 치환]
    ↓
[DB에 병합된 단일 JSON 저장]
    ↓
[프론트엔드는 병합된 JSON만 수신]
```

### Partial 경로 해석 (cross-namespace 지원)

Partial 경로는 다음 순서로 해석된다 — 다른 레이아웃의 partials 디렉토리도 자유롭게 참조 가능 (모달뿐 아니라 모든 레이아웃 컴포넌트에 적용):

1. **호출 레이아웃 기준 상대 경로**: `<layout-dir>/<partial-path>`
2. **Layouts 루트 기준 fallback**: `<layouts-root>/<partial-path>` — `partials/` 로 시작하는 경로일 때만

따라서 `admin_template_list.json` 에서 `"partial": "partials/admin_settings/_modal_core_update_guide.json"` 처럼 **다른 layout namespace 의 partial 을 참조해도 정상 해석된다** (코어 공유 모달 등 재사용 케이스).

```json
// ✅ 동일 namespace
{ "partial": "partials/admin_template_list/_modal_update.json" }

// ✅ 다른 namespace (cross-namespace) — 코어 공유 모달/컴포넌트 재사용
{ "partial": "partials/admin_settings/_modal_core_update_guide.json" }

// ❌ layouts 디렉토리 외부 — 보안상 LayoutIncludeException
{ "partial": "../../some-other-template/partials/x.json" }
```

**보안**: 해석된 절대 경로가 layouts 루트 디렉토리 밖이면 `LayoutIncludeException` 으로 차단 (path traversal 방지).

**구현**: `app/Extension/Traits/ValidatesLayoutFiles.php::resolvePartialPath()` 가 위 두 단계 해석을 수행. 같은 로직을 `PluginManager` 도 공유.

**올바른 computed 정의 방법**:

```json
// ✅ admin_product_list.json (부모 레이아웃) - computed 정의
{
  "layout_name": "admin_product_list",
  "computed": {
    "filterPriceType": "{{_local.filter.priceType ?? query.price_type ?? 'selling_price'}}",
    "filterDateType": "{{_local.filter.dateType ?? query.date_type ?? 'created_at'}}"
  },
  "slots": {
    "content": [
      { "partial": "partials/_filter_section.json" }
    ]
  }
}

// ✅ _filter_section.json (partial 파일) - $computed 참조만 가능
{
  "meta": { "is_partial": true },
  "type": "basic",
  "name": "Div",
  "children": [
    {
      "type": "basic",
      "name": "Span",
      "text": "가격 유형: {{$computed.filterPriceType}}"
    }
  ]
}
```

**잘못된 예시 (partial에서 computed 정의)**:

```json
// ❌ _filter_section.json (partial 파일) - computed 정의해도 무시됨!
{
  "meta": { "is_partial": true },
  "computed": {
    "filterPriceType": "..."  // 이 computed는 병합되지 않음!
  },
  "type": "basic",
  "name": "Div"
}
```

위 partial의 `computed`는 **부모 레이아웃과 병합되지 않습니다**. `$computed.filterPriceType`은 `undefined`로 평가됩니다.

---

## 목차

1. [레이아웃 상속 (Extends & Slots)](#레이아웃-상속-extends--slots)
2. [레이아웃 Partial (파일 분할)](#레이아웃-partial-파일-분할)
3. [병합 결과 구조](#병합-결과-구조)
4. [상속 체인 검증 규칙](#레이아웃-상속-체인-검증-규칙)

---

## 레이아웃 상속 (Extends & Slots)

**목적**: 레이아웃 재사용 및 확장성 향상

### Base 레이아웃 예시

```json
{
  "version": "1.0.0",
  "layout_name": "base_admin",
  "components": [
    {
      "id": "header",
      "type": "composite",
      "name": "AdminHeader"
    },
    {
      "id": "main-content",
      "type": "slot",
      "name": "content",
      "default": []
    },
    {
      "id": "footer",
      "type": "composite",
      "name": "AdminFooter"
    }
  ]
}
```

### 상속 레이아웃 예시

```json
{
  "version": "1.0.0",
  "layout_name": "dashboard",
  "extends": "base_admin",
  "meta": {
    "title": "$t:dashboard.title",
    "description": "$t:dashboard.description"
  },
  "data_sources": [],
  "slots": {
    "content": [
      {
        "id": "dashboard-content",
        "type": "composite",
        "name": "DashboardStats"
      }
    ]
  }
}
```

---

## 레이아웃 Partial (파일 분할)

**목적**: 거대한 레이아웃 JSON 파일을 작은 파일들로 분할하여 가독성 및 유지보수성 향상

**처리 시점**: 템플릿/모듈 활성화 시점 (DB 저장 전)

### 기본 문법

```json
{
  "partial": "경로"
}
```

**핵심 원칙**:
- ✅ `partial` 키워드 사용 ($ 접두사 없음)
- ✅ 상대 경로만 허용
- ✅ 어디든 사용 가능 (객체, 배열 항목 등)
- ✅ 무제한 중첩 깊이 (최대 10단계)
- ✅ data_sources 전파 (partial 파일에서도 접근 가능)

### 사용 예시

#### 1. 기본 예시 (템플릿)

**디렉토리 구조**:
```
templates/sirsoft-admin_basic/layouts/
├── template_partial_test.json          # 메인 레이아웃
└── partials/                           # Partial 파일 폴더
    └── template_partial_test/          # 메인 레이아웃명으로 그룹핑
        ├── _content_section.json      # Level 1 partial
        └── _info_card.json            # Level 2 partial
```

**메인 레이아웃**:
```json
{
  "version": "1.0.0",
  "layout_name": "template_partial_test",
  "extends": "_admin_base",
  "slots": {
    "content": [
      {
        "type": "basic",
        "name": "Div",
        "children": [
          {
            "partial": "partials/template_partial_test/_content_section.json"
          }
        ]
      }
    ]
  }
}
```

**Partial 파일** (_content_section.json):
```json
{
  "meta": {
    "is_partial": true,
    "description": "컨텐츠 섹션"
  },
  "type": "basic",
  "name": "Div",
  "children": [
    {
      "partial": "_info_card.json"
    }
  ]
}
```

**중첩 Partial 파일** (_info_card.json):
```json
{
  "meta": {
    "is_partial": true,
    "description": "정보 카드"
  },
  "type": "composite",
  "name": "Card",
  "props": {
    "title": "Partial 테스트",
    "content": "이 Card는 partial로 포함되었습니다.\n\n특징:\n• 무제한 중첩 깊이\n• data_sources 전파"
  }
}
```

### is_partial 메타데이터

Partial 전용 파일임을 표시하는 메타데이터 (선택사항):

```json
{
  "meta": {
    "is_partial": true,
    "description": "Partial 전용 파일 설명"
  }
}
```

**용도**:
- Partial 전용 파일임을 명시적으로 표시
- DB 저장 방지 (활성화 시 자동 스킵)
- 문서화 및 가독성 향상

### 경로 해석 규칙

**기본 경로**: 현재 레이아웃 파일이 있는 디렉토리

| 경로 형식 | 설명 | 예시 |
|----------|------|------|
| `folder/file.json` | 하위 디렉토리의 파일 | `partials/template_partial_test/_content_section.json` |
| `file.json` | 같은 디렉토리의 파일 | `_section_header.json` |
| `../file.json` | 상위 디렉토리 | `../common/header.json` |

**보안 제약**:
- ✅ 상대 경로만 허용
- 절대 경로 사용 금지
- ❌ 크로스 템플릿/모듈 참조 금지
- ✅ `resources/layouts/{category}/` 디렉토리 내부로 제한

### data_sources 전파

**핵심 기능**: 메인 레이아웃의 `data_sources`가 partial 파일에서도 접근 가능

```json
// 메인 레이아웃
{
  "data_sources": [
    {"id": "items", "endpoint": "/api/admin/sample/test-data"}
  ],
  "slots": {
    "content": [
      {"partial": "partials/sample_content/_tab_content.json"}
    ]
  }
}

// _tab_content.json (partial 파일)
{
  "type": "composite",
  "name": "Card",
  "props": {
    "content": "Items 총 개수: {{items.data.pagination.total}}"
  }
}
```

### 제약사항

- **최대 깊이**: 10단계 (`config('template.layout.max_inheritance_depth')`)
- **순환 참조**: 자동 감지 및 로그 기록 (에러 컴포넌트 반환)
- **보안**: layouts 디렉토리 외부 참조 금지
- **에러 처리**: 파일 없음, JSON 파싱 실패 시 로그 기록 + 에러 컴포넌트 반환 (개발 환경에서만)

### 에러 처리

**개발 환경** (`APP_DEBUG=true`):
- 에러 메시지를 화면에 빨간색 박스로 표시
- 로그에 상세 정보 기록

**프로덕션 환경** (`APP_DEBUG=false`):
- 에러 컴포넌트를 빈 배열로 반환 (아무것도 렌더링 안 함)
- 로그에만 기록

#### 2. 하이브리드 폴더 구조 예시 (권장)

**디렉토리 구조**:
```
modules/sirsoft-board/resources/layouts/admin/
├── admin_board_form.json               # 메인 레이아웃
└── partials/
    ├── admin_board_form/               # 레이아웃 전용 Partial 파일
    │   ├── _tab_basic.json
    │   ├── _tab_permissions.json
    │   ├── _tab_list.json
    │   ├── _tab_post.json
    │   └── _tab_notification.json
    └── common/                         # 재사용 가능한 공통 Partial (향후)
        └── _common_section.json
```

**메인 레이아웃** (admin_board_form.json):
```json
{
  "version": "1.0.0",
  "layout_name": "admin_board_form",
  "extends": "_admin_base",
  "slots": {
    "content": [
      {
        "id": "board_form",
        "type": "basic",
        "name": "Form",
        "children": [
          {
            "partial": "partials/admin_board_form/_tab_basic.json"
          },
          {
            "partial": "partials/admin_board_form/_tab_permissions.json"
          }
        ]
      }
    ]
  }
}
```

**Partial 파일** (partials/admin_board_form/_tab_basic.json):
```json
{
  "meta": {
    "is_partial": true,
    "description": "Board Form - Basic Tab Content"
  },
  "id": "tab_content_basic",
  "type": "basic",
  "name": "Div",
  "condition": "{{(_local.activeTab ?? 'basic') === 'basic'}}",
  "props": {
    "className": "space-y-6 max-w-2xl pt-6"
  },
  "children": [
    {
      "id": "board_id_field",
      "type": "basic",
      "name": "Input",
      "props": {
        "type": "text",
        "name": "board_id",
        "placeholder": "$t:sirsoft-board.admin.form.board_id_placeholder"
      }
    }
  ]
}
```

**하이브리드 구조의 장점**:
- ✅ **레이아웃별 격리**: `admin_board_form/` 폴더로 해당 레이아웃 전용 파일 관리
- ✅ **확장성**: `common/` 폴더에 향후 재사용 가능한 컴포넌트 추가 가능
- ✅ **명확한 구조**: 파일 경로만 봐도 용도를 알 수 있음
- ✅ **유지보수성**: 특정 레이아웃 수정 시 해당 폴더만 작업

### Partial 내부 데이터 바인딩 규칙

```
Partial은 PHP의 include와 동일하게 "단순 문자열 삽입"입니다.
병합 후 하나의 완전한 레이아웃이 되므로, 프론트엔드는 partial 여부를 알 수 없습니다.

주의: partial 내부에서 {{props.xxx}} 사용 불가
   - props는 partial 호출 시 전달되는 것이 아님
   - 병합 후 프론트엔드에서 props 컨텍스트가 없어 평가 불가

✅ 필수: partial 내부에서 직접 data_sources ID로 참조
   - {{stats?.data?.users ?? 0}} (O)
   - {{props.value}} (X)
```

**잘못된 예시 ({{props.xxx}} 사용)**:

```json
// ❌ _stat_card.json (partial 파일)
{
  "meta": { "is_partial": true },
  "type": "basic",
  "name": "Div",
  "children": [
    { "type": "basic", "name": "Span", "text": "{{props.value}}" },
    { "type": "basic", "name": "P", "text": "{{props.label}}" }
  ]
}

// ❌ home.json (메인 레이아웃) - props 전달 시도
{
  "partial": "partials/home/_stat_card.json",
  "props": { "value": "{{stats?.data?.users ?? 0}}", "label": "회원수" }
}
```

**올바른 예시 (data_sources 직접 참조)**:

```json
// ✅ _stat_card.json (partial 파일) - data_sources ID 직접 참조
{
  "meta": { "is_partial": true },
  "type": "basic",
  "name": "Div",
  "children": [
    { "type": "basic", "name": "Span", "text": "{{stats?.data?.users ?? 0}}" },
    { "type": "basic", "name": "P", "text": "$t:home.stats.members" }
  ]
}

// ✅ home.json (메인 레이아웃) - partial만 참조
{
  "partial": "partials/home/_stat_card.json"
}
```

**왜 {{props.xxx}}가 작동하지 않는가?**

1. Partial 처리는 **활성화 시점**에 수행되어 DB에 병합된 결과가 저장됨
2. 프론트엔드는 병합된 하나의 레이아웃만 받아서 렌더링
3. 프론트엔드 입장에서 "partial이었던 부분"과 "원래 메인 레이아웃 부분"의 구분이 불가능
4. `props` 컨텍스트는 컴포넌트 내부에서만 유효하며, partial 호출 시 전달되는 것이 아님
5. 따라서 `{{props.xxx}}`는 평가 시점에 `undefined`로 해석됨

**체크리스트**:

```
□ partial 파일 내부에서 {{props.xxx}} 패턴 사용하지 않았는가?
□ data_sources ID를 직접 참조하고 있는가? (예: {{stats?.data?.xxx}})
□ 메인 레이아웃의 data_sources가 partial에서 접근하는 ID를 포함하는가?
□ Optional chaining (?.) 과 nullish coalescing (??) 을 사용하여 안전하게 접근하는가?
```

---

### 베스트 프랙티스

**분할 기준**:
- ✅ 반복되는 큰 구조 (탭, 섹션)
- ✅ 재사용 가능한 컴포넌트 조합
- ✅ 독립적으로 관리하고 싶은 부분
- ❌ meta, state (짧고 맥락 필요)
- ❌ data_sources (관계 파악 필요)

**폴더 구조 규칙**:
- ✅ **하이브리드 구조 (권장)**: `partials/{레이아웃명}/` + `partials/common/`
- ✅ **레이아웃 전용**: `partials/{레이아웃명}/` (특정 레이아웃에만 사용)
- ✅ **공통 폴더**: `partials/common/` (여러 레이아웃에서 재사용)
- ❌ **단일 폴더**: `partials/` (파일이 많아질 경우 관리 어려움)

**네이밍 규칙**:
- 파일: `_{파일명}.json` (언더스코어 접두사 권장)
- is_partial 메타데이터 추가 권장

**경로 표기**:
```json
// ✅ 권장 (하이브리드 구조)
{"partial": "partials/admin_board_form/_tab_basic.json"}
{"partial": "partials/common/_section_header.json"}

// ✅ 허용 (같은 디렉토리)
{"partial": "_section_header.json"}

// ❌ 금지 (절대 경로, 크로스 참조)
{"partial": "/modules/sirsoft-sample/resources/layouts/..."}
{"partial": "./partials/_tab_content.json"}
```

### extends와의 차이

| 항목 | extends | partial |
|------|---------|---------|
| 목적 | 레이아웃 상속 | 파일 분할 |
| 구조 | 선형 체인 | 트리 |
| 개수 | 1개만 | 제한 없음 |
| 깊이 | 10단계 | 10단계 |
| 병합 | 슬롯 교체 | 직접 치환 |
| 처리 시점 | Runtime | 활성화 시점 |
| data_sources | 상속됨 | 전파됨 |

### 처리 흐름

```
[템플릿/모듈 활성화]
    ↓
[syncLayouts() 실행]
    ↓
[레이아웃 JSON 파일 읽기]
    ↓
[resolveAllPartials() 실행] ← Partial 처리
  - partial 키 탐색 (DFS)
  - 파일 로드 및 JSON 파싱
  - data_sources 전파
  - 순환 참조 감지
  - 치환된 데이터로 교체
    ↓
[partial이 모두 병합된 JSON]
    ↓
[DB 저장 (template_layouts 테이블)]
```

**중요**: Partial 처리는 **활성화 시점에 한 번만** 실행되며, DB에는 병합된 결과가 저장됩니다. Runtime에서는 DB에서 병합된 JSON을 직접 사용합니다.

---

## 병합 결과 구조

레이아웃 병합 시 `LayoutService::mergeLayouts()`가 반환하는 결과 구조:

```json
{
  "version": "1.0.0",
  "layout_name": "dashboard",
  "meta": { ... },
  "data_sources": [ ... ],
  "components": [ ... ],
  "modals": [ ... ],
  "init_actions": [ ... ]
}
```

### 필수 필드

| 필드 | 설명 | 병합 우선순위 |
|------|------|--------------|
| `version` | 레이아웃 스키마 버전 | 자식 → 부모 → "1.0.0" |
| `layout_name` | 레이아웃 식별자 | 자식 → 부모 → "" |
| `meta` | 메타 정보 | 자식이 부모를 덮어씀 |
| `data_sources` | 데이터 소스 | 부모 + 자식 (ID 중복 불가) |
| `components` | 컴포넌트 트리 | 슬롯 교체 병합 |
| `modals` | 모달 컴포넌트 | ID 기반 병합 (자식 우선) |
| `initActions` / `init_actions` | 초기화 액션 | 부모 먼저 + 자식 나중에 (실행 순서 보장) |
| `initLocal` / `state` | 로컬 상태 초기값 | 얕은 병합 (자식이 동일 키 덮어씀) |
| `initGlobal` | 전역 상태 초기값 | 얕은 병합 (자식이 동일 키 덮어씀) |
| `initIsolated` | 격리 상태 초기값 | 얕은 병합 (자식이 동일 키 덮어씀) |
| `scripts` | 외부 스크립트 | ID 기반 병합 (자식 우선) |

### 상태 초기화 속성 병합 규칙 (engine-v1.11.0+)

> **얕은 병합 (Shallow Merge)**: 부모와 자식의 최상위 키만 병합, 동일 키는 자식이 덮어씀

```text
// 부모 레이아웃
"initLocal": { "activeTab": "basic", "isLoading": false }

// 자식 레이아웃
"initLocal": { "activeTab": "advanced", "filter": {} }

// 병합 결과 (자식이 동일 키 덮어씀)
"initLocal": { "activeTab": "advanced", "isLoading": false, "filter": {} }
```

| 속성 | 병합 방식 | 하위 호환 |
|------|----------|----------|
| `initLocal` | 얕은 병합 (array_merge) | `state` 속성도 동일 처리. 데이터소스 `initLocal`은 `_merge` 옵션으로 병합 방식 지정 가능 |
| `initGlobal` | 얕은 병합 (array_merge) | - |
| `initIsolated` | 얕은 병합 (array_merge) | - |
| `initActions` | 배열 연결 (부모 + 자식 순서) | `init_actions` 속성도 동일 처리 |
| `scripts` | ID 기반 병합 (자식 우선) | - |
| `globalHeaders` | pattern 기준 병합 (자식 우선) | 동일 pattern은 headers 병합 (engine-v1.16.0+) |

### meta.seo 병합 규칙

부모의 meta.seo 기본값을 자식이 부분적으로 오버라이드 가능:

| 키 유형 | 병합 전략 |
|---------|----------|
| 스칼라 (enabled, priority 등) | 자식 우선 오버라이드 |
| 연관 배열 (og, vars, structured_data) | deep merge (array_replace_recursive) |
| data_sources (숫자 배열) | 합집합 + 중복 제거 (permissions와 동일) |

- 부모: `{ enabled: true, priority: 0.5 }`
- 자식: `{ priority: 0.8, og: {...} }`
- 결과: `{ enabled: true, priority: 0.8, og: {...} }` ← 부모 enabled 보존

자식이 `enabled: false` 지정 시 → SEO 비활성화 (자식 우선)

> 상세: [seo-system.md](../backend/seo-system.md)

#### 데이터소스 initLocal의 `_merge` 옵션 (engine-v1.18.0+)

데이터소스의 `initLocal`에서 `_merge` 옵션을 사용하면 API 응답을 `_local`에 매핑할 때 병합 방식을 지정할 수 있습니다.

| `_merge` 값 | 동작 |
|-------------|------|
| `"deep"` (기본값) | 깊은 병합 — 기존 `_local` 값 보존, 매핑 결과만 덮어쓰기 |
| `"shallow"` | 얕은 병합 — 최상위 키만 병합 |
| `"replace"` | 완전 교체 — 기존 `_local` 무시, 매핑 결과만 남음 |

> **상세 문서**: [data-sources-advanced.md](data-sources-advanced.md#3-병합-전략-옵션-_merge)

### 병합 시 제거되는 필드

- `extends`: 상속 관계 정보
- `slots`: 슬롯 정의
- `slot`: 컴포넌트의 슬롯 속성

### 프론트엔드 검증

- `LayoutLoader.ts`에서 `version`, `layout_name` 필드 필수 검증
- 필드 누락 시 `VALIDATION_FAILED` 오류 발생

### 검증 규칙

- `extends` 필드가 있으면 `components` 또는 `slots` 중 하나 필수
- `extends`가 없으면 `components` 필드 필수 (base 레이아웃)
- 순환 참조 방지 (A → B → A)
- 최대 상속 깊이: 10단계

### 슬롯 병합 규칙

- 부모 레이아웃의 슬롯을 자식 레이아웃의 컴포넌트로 대체
- 슬롯 이름이 일치하지 않으면 부모 레이아웃의 `default` 컴포넌트 사용
- 상속 체인은 재귀적으로 병합 (최대 10단계)

### globalHeaders 병합

> **버전**: engine-v1.16.0+

부모와 자식 레이아웃의 globalHeaders는 **pattern 기준**으로 병합됩니다.

#### 병합 규칙

1. **배열 합치기**: 부모 + 자식 배열을 순서대로 합침
2. **동일 pattern**: 같은 pattern이 있으면 headers를 병합 (자식이 동일 키 덮어씀)
3. **다른 pattern**: 별도로 유지

#### 예시

**부모 레이아웃** (`_user_base.json`):

```json
{
  "globalHeaders": [
    { "pattern": "*", "headers": { "X-Template": "basic" } },
    { "pattern": "/api/modules/sirsoft-ecommerce/*", "headers": { "X-Cart-Key": "{{_global.cartKey}}" } }
  ]
}
```

**자식 레이아웃** (`shop/cart.json`):

```json
{
  "extends": "_user_base",
  "globalHeaders": [
    { "pattern": "*", "headers": { "X-Page": "cart" } }
  ]
}
```

**병합 결과**:

```json
{
  "globalHeaders": [
    { "pattern": "*", "headers": { "X-Template": "basic", "X-Page": "cart" } },
    { "pattern": "/api/modules/sirsoft-ecommerce/*", "headers": { "X-Cart-Key": "{{_global.cartKey}}" } }
  ]
}
```

- 동일 pattern `*`: headers가 병합됨 (자식의 `X-Page` 추가)
- 부모에만 있는 pattern `/api/modules/sirsoft-ecommerce/*`: 그대로 유지

#### 병합 순서

```text
부모 레이아웃 (_base.json)
    ↓ 병합
자식 레이아웃 (shop/cart.json)
    ↓ 병합 (있을 경우)
Partial은 병합되지 않음 (컴포넌트 치환만)
```

---

## 레이아웃 상속 체인 검증 규칙

```
중요: 레이아웃 상속 시 순환 참조 및 깊이 제한 검증 필수
✅ 필수: LayoutService에서 validateInheritanceChain() 구현
```

### 핵심 원칙

- **최대 상속 깊이**: 10단계 (MAX_DEPTH 상수)
- **순환 참조 방지**: A → B → A 패턴 감지
- **검증 시점**: 레이아웃 생성/수정 시 (FormRequest)
- **예외 처리**: CircularReferenceException, MaxDepthExceededException

### 검증 구현

```php
<?php

namespace App\Services\Template;

use App\Exceptions\Template\CircularReferenceException;
use App\Exceptions\Template\MaxDepthExceededException;
use App\Models\TemplateLayout;

class LayoutService
{
    private const MAX_DEPTH = 10;

    /**
     * 레이아웃 상속 체인 검증
     *
     * @param string $layoutName 검증할 레이아웃명
     * @param array $stack 상속 체인 스택 (재귀 추적용)
     * @param int $depth 현재 깊이
     * @throws CircularReferenceException 순환 참조 발생 시
     * @throws MaxDepthExceededException 깊이 초과 시
     */
    public function validateInheritanceChain(
        string $layoutName,
        array $stack = [],
        int $depth = 0
    ): void {
        // 1. 순환 참조 검사
        if (in_array($layoutName, $stack)) {
            throw new CircularReferenceException($stack, $layoutName);
        }

        // 2. 깊이 검사
        if ($depth > self::MAX_DEPTH) {
            throw new MaxDepthExceededException($depth, self::MAX_DEPTH);
        }

        // 3. 레이아웃 조회
        $layout = TemplateLayout::where('name', $layoutName)->first();

        if (!$layout) {
            return; // 레이아웃이 없으면 더 이상 검증 불필요
        }

        // 4. extends가 있으면 재귀적으로 검증
        if ($layout->extends) {
            $this->validateInheritanceChain(
                $layout->extends,
                array_merge($stack, [$layoutName]),
                $depth + 1
            );
        }
    }

    /**
     * 레이아웃 생성 전 검증
     */
    public function createLayout(array $data): TemplateLayout
    {
        // extends가 있으면 상속 체인 검증
        if (isset($data['extends'])) {
            $this->validateInheritanceChain($data['extends']);
        }

        $layout = TemplateLayout::create($data);

        // 캐시 무효화
        $this->cacheService->invalidateLayout($layout->name);

        return $layout;
    }

    /**
     * 레이아웃 수정 전 검증
     */
    public function updateLayout(int $id, array $data): TemplateLayout
    {
        $layout = TemplateLayout::findOrFail($id);
        $oldExtends = $layout->extends;

        // extends 변경 시 새로운 상속 체인 검증
        if (isset($data['extends']) && $data['extends'] !== $oldExtends) {
            // 자기 자신을 extends하는지 검사
            if ($data['extends'] === $layout->name) {
                throw new CircularReferenceException([], $layout->name);
            }

            // 새 상속 체인 검증
            $this->validateInheritanceChain($data['extends'], [$layout->name]);
        }

        $layout->update($data);

        // 캐시 무효화 (상속 체인 전체)
        $this->cacheService->invalidateLayoutChain($layout->name);

        return $layout->fresh();
    }
}
```

### Custom Exception 예시

```php
<?php

namespace App\Exceptions\Template;

use Exception;

/**
 * 레이아웃 순환 참조 예외
 */
class CircularReferenceException extends Exception
{
    private array $stack;

    public function __construct(array $stack, string $currentLayout)
    {
        $this->stack = $stack;

        $stackTrace = implode(' → ', $stack) . " → {$currentLayout}";
        $message = __('exceptions.template.circular_reference', ['trace' => $stackTrace]);

        parent::__construct($message);
    }

    public function getStack(): array
    {
        return $this->stack;
    }
}

/**
 * 레이아웃 최대 깊이 초과 예외
 */
class MaxDepthExceededException extends Exception
{
    public function __construct(int $currentDepth, int $maxDepth = 10)
    {
        $message = __('exceptions.template.max_depth_exceeded', [
            'current' => $currentDepth,
            'max' => $maxDepth
        ]);

        parent::__construct($message);
    }
}
```

### 검증 시점

```php
// StoreLayoutRequest.php - 레이아웃 생성 시
public function rules(): array
{
    return [
        'extends' => ['nullable', 'string', new ValidLayoutInheritance],
        // ... 기타 필드
    ];
}

// ValidLayoutInheritance Custom Rule
class ValidLayoutInheritance implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (empty($value)) {
            return;
        }

        try {
            $layoutService = app(LayoutService::class);
            $layoutService->validateInheritanceChain($value);
        } catch (CircularReferenceException $e) {
            $fail(__('validation.layout.circular_reference', ['trace' => $e->getMessage()]));
        } catch (MaxDepthExceededException $e) {
            $fail(__('validation.layout.max_depth_exceeded'));
        }
    }
}
```