# MNG 문서양식관리 (Document Template Management)

> **작성일**: 2026-03-06
> **상태**: 운영 중
> **라우트**: `/document-templates`
> **관련**: [README.md](README.md) | [MNG 문서관리](mng-document-system.md)

---

## 1. 개요

문서관리 시스템에서 사용하는 **서식(Template)**을 생성, 편집, 복제, 관리하는 기능. 검사 성적서, 작업지시서 등 다양한 문서 양식을 정의하며, 2가지 빌더 타입을 지원한다.

| 빌더 | builder_type | UI 명칭 | 설명 |
|------|-------------|---------|------|
| **Legacy Builder** | `legacy` 또는 null | 새 양식 | 탭 기반 폼 UI (순수 JavaScript) |
| **Block Builder** | `block` | 양식 디자이너 | WYSIWYG 캔버스 편집기 (Alpine.js + SortableJS) |

> **명칭 변경 이력**: Block Builder의 UI 표시 명칭이 '블록 빌더' → '양식 디자이너'로 변경됨 (2026-02-28)

**핵심 기능:**
- 결재선, 기본필드, 검사 기준서, 테이블 컬럼 정의
- EAV 데이터 구조의 서식 스키마 관리
- 양식 복제 (연결품목 제외)
- 프리셋 자동 제안 (카테고리별)
- 소프트 삭제 + 휴지통 관리 (슈퍼어드민)

---

## 2. 라우트

### 2.1 웹 라우트 (페이지)

```
GET  /document-templates              → index       (목록)
GET  /document-templates/create       → create      (Legacy 신규 생성)
GET  /document-templates/block-create → blockCreate (양식 디자이너 신규 생성)
GET  /document-templates/{id}/edit    → edit        (Legacy 편집)
GET  /document-templates/{id}/block-edit → blockEdit (양식 디자이너 편집)
```

### 2.2 API 라우트 (CRUD + 기능)

```
Prefix: /api/admin/document-templates (HQ 관리자 전용)

GET    /                              → index         (HTMX 테이블)
POST   /                              → store         (생성)
GET    /{id}                          → show          (상세 조회)
PUT    /{id}                          → update        (수정)
DELETE /{id}                          → destroy       (소프트 삭제)
DELETE /{id}/force                    → forceDestroy  (영구삭제, 슈퍼어드민)
POST   /{id}/restore                  → restore       (복원, 슈퍼어드민)
POST   /{id}/toggle-active            → toggleActive  (활성 토글)
POST   /{id}/duplicate                → duplicate     (복제)
POST   /upload-image                  → uploadImage   (이미지 업로드)
GET    /admin/common-codes/{group}    → getCommonCodes (공통코드 조회)
```

---

## 3. 모델 구조

### 3.1 모델 관계도

```
DocumentTemplate (서식 마스터)
├── 1:N  DocumentTemplateApprovalLine   (결재선)
├── 1:N  DocumentTemplateBasicField     (기본필드)
├── 1:N  DocumentTemplateSection        (섹션/기준서)
│         └── 1:N  DocumentTemplateSectionItem  (섹션 항목)
├── 1:N  DocumentTemplateSectionField   (섹션 필드)
├── 1:N  DocumentTemplateColumn         (테이블 컬럼)
└── 1:N  DocumentTemplateLink           (연결 설정)
           └── 1:N  DocumentTemplateLinkValue   (연결 값)
```

### 3.2 DocumentTemplate 핵심 필드

```php
// 기본 정보
builder_type    // 'legacy' | 'block'
name            // 양식명
category        // 분류명
title           // 문서 제목

// 회사 정보
company_name    // 회사명
company_address // 회사 주소
company_contact // 회사 연락처

// 하단 설정
footer_remark_label       // 비고 라벨
footer_judgement_label     // 판정 라벨
footer_judgement_options   // array - 판정 선택지

// Block Builder 전용
schema          // array - 블록 스키마 (JSON)
page_config     // array - 페이지 설정 (A4/A3, 여백 등)

// 연결 (레거시)
linked_item_ids     // array - 연결 품목 ID 목록
linked_process_id   // int - 연결 공정 ID

// 상태
is_active       // boolean - 활성 여부
deleted_at      // timestamp - 소프트 삭제
deleted_by      // int - 삭제자
```

**Helper 메서드:**

```php
isBlockBuilder(): bool   // builder_type === 'block'
isLegacyBuilder(): bool  // builder_type !== 'block'
```

### 3.3 DocumentTemplateApprovalLine (결재선)

| 필드 | 타입 | 설명 |
|------|------|------|
| `template_id` | FK | 서식 ID |
| `name` | string | 결재자 이름/직책 |
| `department` | string | 부서 |
| `role` | string | 역할 (작성/검토/승인) |
| `sort_order` | int | 순서 |

### 3.4 DocumentTemplateBasicField (기본필드)

| 필드 | 타입 | 설명 |
|------|------|------|
| `template_id` | FK | 서식 ID |
| `field_key` | string | 필드 키 (bf_ 접두사) |
| `label` | string | 라벨 |
| `field_type` | string | text, date, select 등 |
| `default_value` | string | 기본값 |
| `is_required` | boolean | 필수 여부 |
| `sort_order` | int | 순서 |
| `options` | array | 선택지 (select 타입) |

### 3.5 DocumentTemplateSection (섹션/검사 기준서)

| 필드 | 타입 | 설명 |
|------|------|------|
| `template_id` | FK | 서식 ID |
| `title` | string | 섹션 제목 |
| `image_path` | string | 섹션 이미지 경로 |
| `sort_order` | int | 순서 |

**하위 관계:**

```
Section 1:N SectionItem
    ├── category        // 카테고리 (그룹핑)
    ├── name            // 항목명
    ├── standard        // 기준
    ├── tolerance_type  // 공차 유형 (symmetric/asymmetric/range/limit)
    ├── tolerance_plus  // +공차
    ├── tolerance_minus // -공차
    ├── reference_value // 기준값
    ├── method          // 검사방법
    ├── measurement_type // 측정유형
    └── frequency       // 검사주기
```

### 3.6 DocumentTemplateColumn (테이블 컬럼)

| 필드 | 타입 | 설명 |
|------|------|------|
| `template_id` | FK | 서식 ID |
| `label` | string | 컬럼 라벨 |
| `group_name` | string | 그룹명 (다단계 "/" 구분) |
| `width` | int | 컬럼 너비 |
| `column_type` | string | text, check, complex, select, measurement |
| `sub_labels` | array | complex 타입 하위 라벨 |
| `sort_order` | int | 순서 |

### 3.7 DocumentTemplateLink (연결 설정)

| 필드 | 타입 | 설명 |
|------|------|------|
| `template_id` | FK | 서식 ID |
| `link_key` | string | 연결 키 |
| `label` | string | 라벨 |
| `link_type` | string | `single` / `multiple` |
| `source_table` | string | `items` / `processes` / `users` |
| `search_params` | array | 검색 파라미터 |
| `display_fields` | array | 표시 필드 |
| `is_required` | boolean | 필수 여부 |
| `sort_order` | int | 순서 |

**하위 관계:**

```
Link 1:N LinkValue
    ├── link_id        // FK → Link
    ├── linkable_id    // 연결 엔티티 ID
    └── (source_table에 따라 items/processes/users 참조)
```

**레거시 호환 처리:**

```php
// 신규 links가 있으면 사용
if ($template->links->isNotEmpty()) {
    // template_links + link_values 사용
}

// 레거시만 있으면 가상 엔트리 생성
if (!empty($template->linked_item_ids)) {
    return [['link_key' => 'items', 'values' => [...]]]
}
```

---

## 4. 컨트롤러 상세

### 4.1 DocumentTemplateController (웹)

| 메서드 | 동작 |
|--------|------|
| `index()` | HTMX 요청 → HX-Redirect 반환 (전체 페이지 로드 강제) |
| `create()` | Legacy 신규 생성 폼 렌더링 |
| `edit($id)` | Legacy 편집. 양식 디자이너 타입이면 `blockEdit`으로 자동 리다이렉트 |
| `blockCreate()` | 양식 디자이너 신규 생성 (빈 캔버스) |
| `blockEdit($id)` | 양식 디자이너 편집 (스키마 로드) |

**공통 데이터 준비:**

```php
// 현재 테넌트 조회
$tenantId = getCurrentTenant();  // 세션의 selected_tenant_id

// 카테고리 목록 = common_codes + 기존 템플릿 카테고리
$categories = getCategories();

// 기본필드 키 옵션
$basicFieldKeys = getBasicFieldKeys();  // common_codes 'doc_template_basic_field'
```

### 4.2 DocumentTemplateApiController (API)

#### `index()` — HTMX 테이블 조회

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `search` | string | 양식명/분류 검색 |
| `category` | string | 분류 필터 |
| `is_active` | string | `1` / `0` / `TRASHED` (휴지통) |

```php
// 휴지통 모드 (슈퍼어드민 전용)
if ($isActive === 'TRASHED') {
    $query->onlyTrashed();
}
```

#### `store()` / `update()` — 생성/수정

```
요청 데이터
    ↓
검증 (직접 validate, FormRequest 미사용)
    ↓
연결품목 중복 검증 (checkLinkedItemDuplicates)
    ↓
DB::transaction 시작
    ↓
Template 생성/수정
    ↓
saveRelations() — 관계 데이터 upsert
    ↓
DB::transaction 완료
    ↓
JSON 응답
```

#### `duplicate()` — 양식 복제

```php
$source = DocumentTemplate::with([...all relationships...]);

$newTemplate = DocumentTemplate::create([
    ...원본 데이터,
    'name' => request('name', '원본 (복사)'),
    'is_active' => false,           // 비활성으로 생성
    'linked_item_ids' => null,       // 연결품목 제외
    'linked_process_id' => null,     // 연결공정 제외
]);

// 각 관계 데이터 복사 (approvalLines, basicFields, sections, columns...)
// linkValues는 복사 안 함 (동일 분류 내 중복 방지)
```

#### `forceDestroy()` — 영구삭제

```php
// 사전 검사: 참조하는 문서 존재 여부
$documentCount = Document::withTrashed()
    ->where('template_id', $id)
    ->count();

if ($documentCount > 0) {
    return 422; // "이 양식을 사용한 문서 {count}건이 있어 삭제 불가"
}
```

#### `uploadImage()` — 이미지 업로드

```
요청 (multipart)
    ↓
ApiTokenService::exchangeToken($userId, $tenantId)
    ↓
API /files/upload 호출 (Bearer 토큰)
    ↓
응답: file_path (1/temp/2026/02/xxx.jpg)
    ↓
최종 URL: http://api.sam.kr/storage/tenants/{file_path}
```

---

## 5. 저장 메커니즘 (saveRelations)

### 5.1 upsert 전략

| 관계 | 방식 | 이유 |
|------|------|------|
| approvalLines | 전체 삭제 → 재생성 | ID 참조 없음 |
| basicFields | 전체 삭제 → 재생성 | ID 참조 없음 |
| **sections** | **ID 보존 upsert** | document_data가 section_id 참조 |
| **sectionItems** | **ID 보존 upsert** | section 하위 항목 |
| **columns** | **ID 보존 upsert** | document_data가 column_id 참조 |
| sectionFields | 전체 삭제 → 재생성 | ID 참조 없음 |
| links + linkValues | 전체 삭제 → 재생성 | ID 참조 없음 |

### 5.2 ID 보존 upsert 로직

```php
// 1. 요청 ID 수집
$incomingIds = collect($data['sections'])->pluck('id')->filter();

// 2. 요청에 없는 항목 삭제
$template->sections()
    ->whereNotIn('id', $incomingIds)
    ->each(function($s) {
        $s->items()->delete();
        $s->delete();
    });

// 3. 각 항목 upsert
foreach ($data['sections'] as $section) {
    if (!empty($section['id']) && $existing = $template->sections()->find($section['id'])) {
        $existing->update($sectionData);  // 기존: update
    } else {
        DocumentTemplateSection::create([...]); // 신규: create
    }
}
```

> **ID 보존이 필수인 이유**: `document_data` 테이블이 `section_id`, `column_id`를 FK로 참조한다. 양식 수정 시 ID가 변경되면 기존 문서 데이터와의 매핑이 깨진다.

---

## 6. 화면 구성

### 6.1 목록 화면 (`index.blade.php`)

```
┌─────────────────────────────────────────────────┐
│ 문서양식관리                                      │
│ [+ 새 양식]  [+ 양식 디자이너]                      │
├─────────────────────────────────────────────────┤
│ 필터: [검색어] [분류 ▼] [활성/비활성/휴지통 ▼]      │
├─────────────────────────────────────────────────┤
│ # │ 양식명 │ 분류 │ 활성 │ 수정일 │ 액션          │
│ 1 │ FQC... │ 검사 │ ✅   │ 03-06 │ 편집 복제 삭제 │
│ 2 │ 수입... │ 검사 │ ✅   │ 03-05 │ 편집 복제 삭제 │
│ ...│        │      │      │       │               │
└─────────────────────────────────────────────────┘
```

**HTMX 테이블 로드:**

```html
<div id="template-table"
     hx-get="/api/admin/document-templates"
     hx-trigger="load, filterSubmit from:body"
     hx-swap="innerHTML">
</div>
```

**액션 버튼:**
- **편집**: 새 양식 → `/document-templates/{id}/edit`, 양식 디자이너 → `/document-templates/{id}/block-edit`
- **복제**: `duplicateTemplate(id)` — 이름 입력 모달 후 POST
- **삭제**: `confirmDelete(id)` — 확인 후 DELETE
- **미리보기**: `previewTemplate(id)` — 모달 표시
- **활성 토글**: `toggleActive(id)` — POST toggle-active
- **복원/영구삭제**: 휴지통 모드에서만 표시 (슈퍼어드민)

### 6.2 Legacy Builder 편집 화면 (`edit.blade.php`)

**4개 탭 구조:**

```
┌─────────────────────────────────────────────────────┐
│ [기본정보] [기본필드] [검사 기준서] [테이블 컬럼]       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  (각 탭 콘텐츠)                                      │
│                                                     │
├─────────────────────────────────────────────────────┤
│                        [미리보기]  [저장]  [취소]     │
└─────────────────────────────────────────────────────┘
```

#### 탭 1: 기본정보

| 필드 | 설명 |
|------|------|
| 양식명 | 서식 이름 (필수) |
| 제목 | 문서 제목 |
| 분류 | 카테고리 (common_codes + 기존값) |
| 회사명 | 문서 헤더 회사명 |
| 회사 주소/연락처 | 문서 헤더 |
| 활성 | 체크박스 |
| 결재선 | 동적 행 추가/삭제 (이름, 부서, 역할) |

#### 탭 2: 기본필드

| 항목 | 설명 |
|------|------|
| 필드 키 | `bf_` 접두사 (common_codes에서 선택) |
| 라벨 | 표시 라벨 |
| 필드 타입 | text, date, select 등 |
| 기본값 | 문서 생성 시 자동 입력 |
| 필수 여부 | 체크박스 |

#### 탭 3: 검사 기준서

```
┌──────────────────────────────────────────────────┐
│ 섹션 1: [제목 입력]  [이미지 업로드]  [+ 항목 추가] │
│ ┌──────────────────────────────────────────────┐ │
│ │ 카테고리 │ 항목 │ 기준 │ 공차 │ 기준값 │ ...   │ │
│ │ 외관     │ 색상 │ 기준 │ ±0.5 │ 5.0  │ ...   │ │
│ │ 외관     │ 흠집 │ 무   │      │      │ ...   │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ 섹션 2: [제목 입력]  [이미지 업로드]  [+ 항목 추가] │
│ ...                                              │
│                                  [+ 섹션 추가]    │
└──────────────────────────────────────────────────┘
```

**공차 유형:**

| 유형 | 입력 | 표시 예 |
|------|------|--------|
| `symmetric` | ± 값 | ±0.5 |
| `asymmetric` | +값, -값 | +0.3 / -0.2 |
| `range` | 최소~최대 | 4.5 ~ 5.5 |
| `limit` | 상한 또는 하한 | ≤ 10 |

#### 탭 4: 테이블 컬럼

| 항목 | 설명 |
|------|------|
| 라벨 | 컬럼 헤더 |
| 그룹명 | 다단계 그룹 ("/" 구분) |
| 너비 | 컬럼 너비 (px 또는 %) |
| 컬럼 타입 | text, check, complex, select, measurement |
| 하위 라벨 | complex 타입 시 sub_labels |

**자동 컬럼 생성:**

```
[기준서에서 자동 생성] 버튼 클릭
    ↓
검사 기준서 섹션의 항목들을 분석
    ↓
카테고리 그룹별 컬럼 자동 생성
    ↓
measurement_type에 따라 컬럼 타입 결정
```

### 6.3 양식 디자이너 편집 화면 (`block-editor.blade.php`)

**3패널 레이아웃:**

```
┌──────────┬──────────────────────────┬───────────┐
│ 팔레트    │ 캔버스                    │ 속성 패널  │
│ (220px)  │ (flex: 1)               │ (300px)   │
│          │                          │           │
│ 기본:     │ ┌──────────────────────┐ │ 선택 블록: │
│ □ 제목    │ │ [제목 블록]           │ │           │
│ □ 문단    │ │ [문단 블록]           │ │ 제목: ... │
│ □ 테이블  │ │ [테이블 블록]         │ │ 크기: ... │
│ □ 컬럼    │ │ [입력 필드 블록]      │ │ 정렬: ... │
│ □ 구분선  │ │                      │ │           │
│ □ 여백    │ └──────────────────────┘ │           │
│          │                          │           │
│ 폼:      │                          │           │
│ □ 텍스트  │                          │           │
│ □ 숫자    │                          │           │
│ □ 날짜    │                          │           │
│ □ 선택    │                          │           │
│ □ 체크    │                          │           │
│ □ 텍스트영역│                        │           │
│ □ 서명    │                          │           │
└──────────┴──────────────────────────┴───────────┘
```

**블록 타입 (15개):**

| 분류 | 타입 | 설명 |
|------|------|------|
| 기본 | `heading` | 제목 (h1~h6) |
| 기본 | `paragraph` | 문단 텍스트 |
| 기본 | `table` | 테이블 (행/열 편집) |
| 기본 | `columns` | 다단 컬럼 레이아웃 |
| 기본 | `divider` | 구분선 |
| 기본 | `spacer` | 여백 |
| 폼 | `text_field` | 텍스트 입력 |
| 폼 | `number_field` | 숫자 입력 |
| 폼 | `date_field` | 날짜 입력 |
| 폼 | `select_field` | 선택 드롭다운 |
| 폼 | `checkbox_field` | 체크박스 |
| 폼 | `textarea_field` | 긴 텍스트 입력 |
| 폼 | `signature_field` | 서명 영역 |

**Alpine.js 상태 관리:**

```javascript
blockEditor(initialSchema, templateId) {
    blocks: [],            // 블록 배열
    selectedBlockId: null, // 현재 선택 블록
    history: [],           // Undo/Redo 스택 (최대 50)
    historyIndex: -1,
    pageConfig: {          // 페이지 설정
        size: 'A4',        // A4 / A3
        orientation: 'portrait',  // portrait / landscape
        margins: { top, right, bottom, left }
    },
    templateName: '',
    category: ''
}
```

**키보드 단축키:**

| 단축키 | 기능 |
|--------|------|
| `Ctrl+Z` / `Cmd+Z` | Undo |
| `Ctrl+Shift+Z` / `Cmd+Shift+Z` | Redo |
| `Ctrl+S` / `Cmd+S` | 저장 |

**SortableJS:**
- 캔버스 내 블록 드래그-앤-드롭 정렬
- 팔레트에서 캔버스로 블록 추가

---

## 7. 미리보기 시스템

### 7.1 Legacy Builder 미리보기

```javascript
buildDocumentPreviewHtml(data)
├── 결재란 테이블 (역할별 칸)
├── 기본필드 (2열 15:35:15:35 비율)
├── 섹션별 이미지 (title + image 또는 placeholder)
├── 검사 데이터 테이블
│   ├── 다단계 그룹 헤더 (group_name "/" 구분)
│   ├── sub_labels (complex 컬럼)
│   ├── 항목 행 (카테고리 그룹핑)
│   └── 측정치 셀 (measurement_type별 렌더)
└── 비고/종합판정 섹션
```

### 7.2 양식 디자이너 미리보기

```javascript
buildBlockPreviewHtml(data)
├── 블록 타입별 HTML 렌더링
├── 폼 필드 placeholder 표시
└── A4/A3 레이아웃 시뮬레이션
```

### 7.3 이미지 URL 처리

```javascript
_previewImageUrl(imagePath)
├── http(s):// 시작 → 그대로 사용
├── /^\d+\// 패턴 → API tenant storage URL 생성
│   → http://api.sam.kr/storage/tenants/{imagePath}
└── 기타 → MNG local storage (/storage/{imagePath})
```

---

## 8. 분류(Category) 관리

### 8.1 소스 (우선순위)

1. **common_codes** (code_group = `document_category`, is_active = true)
   - tenant_id가 있는 것 우선 (테넌트 전용)
   - tenant_id가 null인 것도 포함 (공통)
   - code 기준 중복 제거 (테넌트 우선)
2. **기존 템플릿의 category** (common_codes에 없는 값)
   - 기존 이름 그대로 추가

### 8.2 연동 공통코드 그룹

| 그룹 | 용도 |
|------|------|
| `document_category` | 문서 분류 |
| `doc_template_basic_field` | 기본필드 키 옵션 |
| `doc_inspection_method` | 검사방법 |
| `doc_measurement_type` | 측정유형 |

---

## 9. 프리셋 시스템

### 9.1 테이블

```
document_template_field_presets
├── name               // 프리셋 이름
├── category           // 대상 카테고리
├── description        // 설명
└── field_definitions  // array - 필드 정의 목록
    [{ field_key, label, field_type, options, ... }]
```

### 9.2 동작

```
분류(Category) 변경
    ↓
매칭 프리셋 검색
    ↓
기존 section_fields가 비어있으면
    ↓
"'{category}' 카테고리에 맞는 프리셋을 적용할까요?" 확인
    ↓
승인 시 field_definitions 자동 적용
```

> **주의**: 초기 로드 시에는 제안하지 않음. 분류 변경 시에만 제안.

---

## 10. 연결품목 중복 검증

### 10.1 규칙

같은 category 내 서로 다른 템플릿이 동일한 items를 연결할 수 없다.

### 10.2 검증 로직

```php
checkLinkedItemDuplicates($templateId, $category, $itemIds)

// 1. 같은 category의 다른 템플릿 조회
$otherTemplates = DocumentTemplate::where('category', $category)
    ->where('id', '!=', $templateId)
    ->get();

// 2. 각 템플릿의 연결품목 수집
foreach ($otherTemplates as $other) {
    // 레거시: linked_item_ids (JSON 배열)
    // 신규: template_links → linkValues (source_table = 'items')
    $existingItemIds = ...;
}

// 3. 교집합 검사
$duplicates = array_intersect($itemIds, $existingItemIds);
if (!empty($duplicates)) {
    return 422; // 중복 항목 목록과 함께 오류 반환
}
```

---

## 11. JavaScript 상태 관리 (Legacy Builder)

### 11.1 templateState 객체

```javascript
const templateState = {
    // 기본정보
    id, name, category, title,
    company_name, company_address, company_contact,
    footer_remark_label, footer_judgement_label,
    footer_judgement_options,
    is_active,

    // 관계 데이터
    approval_lines: [],      // 결재선
    basic_fields: [],        // 기본필드
    sections: [],            // 섹션 + items
    columns: [],             // 테이블 컬럼
    section_fields: [],      // 섹션 필드
    template_links: [],      // 연결 설정 + values
};
```

### 11.2 저장 흐름

```
사용자 입력 (Blade 폼)
    ↓
templateState 객체 갱신
    ↓
saveTemplate() 호출
    ↓
fetch POST/PUT /api/admin/document-templates
    ↓
DocumentTemplateApiController::store/update()
    ↓
검증 → 중복 검사 → DB 트랜잭션 → saveRelations()
    ↓
JSON 응답
    ↓
showToast() 메시지
    ↓
htmx.trigger('#template-table', 'filterSubmit') → 테이블 새로고침
```

---

## 12. 양식 디자이너(Block Builder) vs 새 양식(Legacy Builder) 비교

| 항목 | 양식 디자이너 | 새 양식 |
|------|:------------:|:-------------:|
| builder_type | `block` | `legacy` 또는 null |
| 편집 UI | WYSIWYG 캔버스 (Alpine.js) | 탭 폼 (순수 JavaScript) |
| 데이터 저장 | `schema` JSON 컬럼 | 관계 테이블 (7개) |
| Undo/Redo | 히스토리 스택 (최대 50) | 불가 |
| 블록 타입 | 15개 (기본 6 + 폼 7 + 기타 2) | N/A |
| 드래그-앤-드롭 | SortableJS | 불가 |
| 페이지 설정 | A4/A3, 여백, 방향 | 없음 |
| 복제 | 스키마 JSON 복사 | 각 관계 데이터 개별 복사 |
| 미리보기 함수 | `buildBlockPreviewHtml()` | `buildDocumentPreviewHtml()` |
| 적합 용도 | 자유 레이아웃 문서 | 정형화된 검사 성적서 |

---

## 13. 권한 및 보안

### 13.1 미들웨어

- **웹 라우트**: 일반 인증 (auth)
- **API 라우트**: HQ 관리자 미들웨어 (`admin` prefix)

### 13.2 슈퍼어드민 전용 기능

| 기능 | 엔드포인트 |
|------|-----------|
| 영구삭제 | `DELETE /{id}/force` |
| 복원 | `POST /{id}/restore` |
| 휴지통 조회 | `GET /?is_active=TRASHED` |

### 13.3 삭제 보호

- 소프트 삭제: `deleted_at` + `deleted_by` 기록
- 영구삭제 전 참조 문서 검사 (Document 테이블)
- 참조 문서가 있으면 영구삭제 불가 (422 응답)

---

## 14. API 프로젝트 연동

### 14.1 API 서비스

```php
// DocumentTemplateService (API)
list(array $params): LengthAwarePaginator
    // 필터: is_active, category, search

show(int $id): DocumentTemplate
    // 전체 관계 로드 (approvalLines, basicFields, sections, columns...)
```

### 14.2 API 엔드포인트

```
GET  /v1/document-templates      → index (목록)
GET  /v1/document-templates/{id} → show  (상세)
```

> API는 **읽기 전용**. 서식 생성/수정은 MNG에서만 수행.

---

## 15. 주요 파일 경로

| 기능 | 경로 |
|------|------|
| 웹 컨트롤러 | `mng/app/Http/Controllers/DocumentTemplateController.php` |
| API 컨트롤러 | `mng/app/Http/Controllers/Api/Admin/DocumentTemplateApiController.php` |
| 모델 (8개) | `mng/app/Models/DocumentTemplate*.php` |
| 뷰 - 목록 | `mng/resources/views/document-templates/index.blade.php` |
| 뷰 - Legacy 편집 | `mng/resources/views/document-templates/edit.blade.php` |
| 뷰 - 양식 디자이너 | `mng/resources/views/document-templates/block-editor.blade.php` |
| 뷰 - 테이블 | `mng/resources/views/document-templates/partials/table.blade.php` |
| 뷰 - 미리보기 | `mng/resources/views/document-templates/partials/preview-modal.blade.php` |
| API 서비스 | `api/app/Services/DocumentTemplateService.php` |
| API 모델 | `api/app/Models/Documents/DocumentTemplate*.php` |

---

## 관련 문서

- [README.md](README.md) — 문서관리 시스템 개요 (API 중심)
- [MNG 문서관리](mng-document-system.md) — 문서 생성/편집/결재 (서식을 사용하는 측)
- [DB 스키마 — 문서](../../system/database/documents.md)

---

**최종 업데이트**: 2026-03-06