sam-docs/sam/docs/features/approvals/db-changes-and-model-sync.md

# 결재관리 DB 변경사항 및 API 모델 동기화 현황

> **작성일**: 2026-03-09
> **상태**: 조사 완료
> **관련**: [README.md](README.md) | [API 명세](api-reference.md)

---

## 1. 개요

### 1.1 목적

2026-02-27 ~ 2026-03-05 기간에 결재관리 테이블에 대규모 컬럼 추가가 이루어졌다. 이 문서는 변경된 DB 스키마와 API/MNG 프로젝트 간 모델 동기화 상태를 기록한다.

### 1.2 핵심 발견

- 마이그레이션 **15개** 실행 (API 프로젝트에서 관리)
- MNG 모델: ✅ 모든 신규 컬럼 반영 완료
- API 모델: ❌ **`$fillable`/`$casts` 미반영** — 오류 원인 가능성

---

## 2. 마이그레이션 변경 타임라인

### 2.1 Phase 2 확장 (2026-02-27)

| 마이그레이션 파일 | 대상 테이블 | 작업 |
|------------------|-----------|------|
| `add_columns_to_approvals_table` | `approvals` | `line_id`, `body`, `is_urgent`, `department_id` 추가 |
| `add_columns_to_approval_steps_table` | `approval_steps` | `approver_name`, `approver_department`, `approver_position` 추가 |
| `add_phase2_columns_to_approval_steps_table` | `approval_steps` | `parallel_group`, `acted_by`, `approval_type` 추가 |
| `add_phase2_columns_to_approvals_table` | `approvals` | `recall_reason`, `parent_doc_id` 추가 |
| `create_approval_delegations_table` | `approval_delegations` | 위임 테이블 신규 생성 |
| `add_linkable_to_approvals_table` | `approvals` | `linkable_type`, `linkable_id` 추가 (다형성) |

### 2.2 도메인 연동 (2026-02-28)

| 마이그레이션 파일 | 대상 테이블 | 작업 |
|------------------|-----------|------|
| `add_approval_id_to_leaves_table` | `leaves` | `approval_id` FK 추가 |
| `insert_leave_approval_form` | `approval_forms` | 휴가신청 양식 데이터 등록 |

### 2.3 양식 확장 (2026-03-03 ~ 03-04)

| 마이그레이션 파일 | 대상 테이블 | 작업 |
|------------------|-----------|------|
| `insert_attendance_approval_forms` | `approval_forms` | 근태신청, 사유서 양식 등록 |
| `add_body_template_to_approval_forms` | `approval_forms` | `body_template` 컬럼 추가 |
| `insert_expense_approval_form` | `approval_forms` | 지출결의서 양식 + body_template 등록 |
| `update_expense_approval_form_body_template` | `approval_forms` | 지출결의서 body_template 고도화 |

### 2.4 추적 기능 (2026-03-05)

| 마이그레이션 파일 | 대상 테이블 | 작업 |
|------------------|-----------|------|
| `add_drafter_read_at_to_approvals_table` | `approvals` | `drafter_read_at` 추가 |
| `add_resubmit_count_to_approvals_table` | `approvals` | `resubmit_count` 추가 |
| `add_rejection_history_to_approvals_table` | `approvals` | `rejection_history` 추가 |

---

## 3. 추가된 컬럼 상세

### 3.1 `approvals` 테이블 (11개 컬럼 추가)

| 컬럼 | 타입 | 기본값 | 추가일 | 용도 |
|------|------|--------|--------|------|
| `line_id` | BIGINT FK NULL | NULL | 02-27 | 결재선 템플릿 참조 |
| `body` | LONGTEXT NULL | NULL | 02-27 | 문서 본문 HTML |
| `is_urgent` | BOOLEAN | false | 02-27 | 긴급 여부 |
| `department_id` | BIGINT NULL | NULL | 02-27 | 기안 부서 |
| `recall_reason` | TEXT NULL | NULL | 02-27 | 회수 사유 |
| `parent_doc_id` | BIGINT FK NULL | NULL | 02-27 | 재기안 원본 문서 |
| `linkable_type` | VARCHAR NULL | NULL | 02-27 | 다형성 모델 타입 |
| `linkable_id` | BIGINT NULL | NULL | 02-27 | 다형성 모델 ID |
| `drafter_read_at` | TIMESTAMP NULL | NULL | 03-05 | 기안자 열람 시각 |
| `resubmit_count` | TINYINT UNSIGNED | 0 | 03-05 | 재상신 횟수 |
| `rejection_history` | JSON NULL | NULL | 03-05 | 반려 이력 배열 |

### 3.2 `approval_steps` 테이블 (6개 컬럼 추가)

| 컬럼 | 타입 | 기본값 | 추가일 | 용도 |
|------|------|--------|--------|------|
| `approver_name` | VARCHAR(50) NULL | NULL | 02-27 | 결재자명 스냅샷 |
| `approver_department` | VARCHAR(100) NULL | NULL | 02-27 | 결재자 부서 스냅샷 |
| `approver_position` | VARCHAR(50) NULL | NULL | 02-27 | 결재자 직급 스냅샷 |
| `parallel_group` | INT NULL | NULL | 02-27 | 병렬 결재 그룹 (Phase 3) |
| `acted_by` | BIGINT FK NULL | NULL | 02-27 | 실제 처리자 (대결) |
| `approval_type` | VARCHAR(20) | 'normal' | 02-27 | normal/pre_decided/delegated |

### 3.3 `approval_forms` 테이블 (1개 컬럼 추가)

| 컬럼 | 타입 | 기본값 | 추가일 | 용도 |
|------|------|--------|--------|------|
| `body_template` | TEXT NULL | NULL | 03-04 | HTML 양식 렌더링 템플릿 |

### 3.4 `approval_delegations` 테이블 (신규 생성)

| 컬럼 | 타입 | 설명 |
|------|------|------|
| `tenant_id` | BIGINT FK | 테넌트 격리 |
| `delegator_id` | BIGINT FK | 위임자 |
| `delegate_id` | BIGINT FK | 대리인 |
| `start_date` | DATE | 위임 시작일 |
| `end_date` | DATE | 위임 종료일 |
| `form_ids` | JSON NULL | 대상 양식 (NULL=전체) |
| `notify_delegator` | BOOLEAN | 대결 시 보고 여부 |
| `is_active` | BOOLEAN | 활성 여부 |
| `reason` | VARCHAR(200) | 위임 사유 |

---

## 4. API/MNG 모델 동기화 현황

### 4.1 Approval 모델 비교

| 항목 | MNG (`mng/app/Models/Approvals/Approval.php`) | API (`api/app/Models/Tenants/Approval.php`) |
|------|:---:|:---:|
| `line_id` in $fillable | ✅ | ❌ |
| `body` in $fillable | ✅ | ❌ |
| `is_urgent` in $fillable/$casts | ✅ boolean | ❌ |
| `department_id` in $fillable | ✅ | ❌ |
| `recall_reason` in $fillable | ✅ | ❌ |
| `parent_doc_id` in $fillable | ✅ | ❌ |
| `linkable_type/id` in $fillable | ✅ | ✅ |
| `drafter_read_at` in $fillable/$casts | ✅ datetime | ❌ |
| `resubmit_count` in $fillable/$casts | ✅ integer | ❌ |
| `rejection_history` in $fillable/$casts | ✅ array | ❌ |

### 4.2 ApprovalStep 모델 비교

| 항목 | MNG | API |
|------|:---:|:---:|
| `approver_name` in $fillable | ✅ | ❌ |
| `approver_department` in $fillable | ✅ | ❌ |
| `approver_position` in $fillable | ✅ | ❌ |
| `parallel_group` in $fillable | ✅ | ❌ |
| `acted_by` in $fillable | ✅ | ❌ |
| `approval_type` in $fillable | ✅ | ❌ |

### 4.3 ApprovalForm 모델 비교

| 항목 | MNG | API |
|------|:---:|:---:|
| `body_template` in $fillable | ✅ | ❌ |

### 4.4 ApprovalDelegation 모델

| 항목 | MNG | API |
|------|:---:|:---:|
| 모델 파일 존재 | ✅ | ❌ 미생성 |

---

## 5. 오류 영향 분석

### 5.1 API 모델 미반영으로 인한 잠재적 오류

API 프로젝트의 모델 `$fillable`에 신규 컬럼이 누락되어, API 엔드포인트를 통한 결재 문서 처리 시 다음 오류가 발생할 수 있다:

| 증상 | 원인 | 영향 범위 |
|------|------|----------|
| `create()`/`update()` 시 신규 필드 저장 안 됨 | `$fillable` 미포함 → mass assignment 차단 | API v1 결재 CRUD |
| JSON 필드(`rejection_history`) 문자열로 반환 | `$casts` 미정의 → 타입 변환 안 됨 | API 응답 파싱 오류 |
| `drafter_read_at` 날짜 비교 실패 | `$casts` datetime 미정의 → Carbon 미변환 | 열람 추적 기능 |
| `is_urgent` 비교 오류 | `$casts` boolean 미정의 → 문자열 비교 | 긴급 필터링 |
| 위임(delegation) 기능 완전 불가 | 모델 자체 미생성 | Phase 3 기능 전체 |

### 5.2 MNG는 정상

MNG 프로젝트의 모델은 모든 신규 컬럼이 `$fillable`, `$casts`, `$attributes`에 반영되어 있으며, `ApprovalService`에서 정상 사용 중이다.

```
MNG 정상 동작 확인 기능:
✅ 반려 이력 저장 (rejection_history)
✅ 재상신 횟수 추적 (resubmit_count)
✅ 기안자 열람 추적 (drafter_read_at)
✅ 결재자 스냅샷 저장 (approver_name/department/position)
✅ 전결 처리 (approval_type = pre_decided)
✅ 회수 사유 기록 (recall_reason)
```

---

## 6. 수정 필요 파일 목록

### 6.1 API 모델 업데이트 필요

| 파일 | 수정 내용 |
|------|----------|
| `api/app/Models/Tenants/Approval.php` | `$fillable`에 9개 필드, `$casts`에 4개 필드 추가 |
| `api/app/Models/Tenants/ApprovalStep.php` | `$fillable`에 6개 필드 추가 |
| `api/app/Models/Tenants/ApprovalForm.php` | `$fillable`에 `body_template` 추가 |
| `api/app/Models/Tenants/ApprovalDelegation.php` | 모델 파일 신규 생성 |

### 6.2 Approval.php 수정 상세

**`$fillable` 추가 필요:**

```php
'line_id',
'body',
'is_urgent',
'department_id',
'recall_reason',
'parent_doc_id',
'drafter_read_at',
'resubmit_count',
'rejection_history',
```

**`$casts` 추가 필요:**

```php
'drafter_read_at' => 'datetime',
'resubmit_count' => 'integer',
'rejection_history' => 'array',
'is_urgent' => 'boolean',
```

### 6.3 ApprovalStep.php 수정 상세

**`$fillable` 추가 필요:**

```php
'approver_name',
'approver_department',
'approver_position',
'parallel_group',
'acted_by',
'approval_type',
```

### 6.4 ApprovalForm.php 수정 상세

**`$fillable` 추가 필요:**

```php
'body_template',
```

---

## 7. 연관 테이블 참조 변경

결재 시스템과 연동된 다른 테이블의 변경사항:

| 테이블 | 추가 컬럼 | 추가일 | 용도 |
|--------|----------|--------|------|
| `leaves` | `approval_id` (BIGINT FK) | 02-28 | 휴가 ↔ 결재 연동 |
| `purchases` | `approval_id` (BIGINT FK) | (기존) | 구매 ↔ 결재 연동 |

---

## 8. 등록된 결재 양식 (13종)

2026-02-28 ~ 03-07 기간에 마이그레이션으로 등록된 양식:

| 코드 | 양식명 | 카테고리 | 등록일 |
|------|--------|---------|--------|
| `leave` | 휴가신청서 | request | 02-28 |
| `attendance_request` | 근태신청서 | request | 03-03 |
| `reason_report` | 사유서 | request | 03-03 |
| `expense` | 지출결의서 | expense | 03-04 |
| `employment_cert` | 재직증명서 | request | 03-05 |
| `career_cert` | 경력증명서 | request | 03-05 |
| `appointment_cert` | 위촉증명서 | request | 03-05 |
| `resignation` | 사직서 | request | 03-06 |
| `seal_usage` | 사용인감계 | request | 03-06 |
| `delegation` | 위임장 | request | 03-06 |
| `board_minutes` | 이사회의사록 | request | 03-06 |
| `quotation` | 견적서 | request | 03-06 |
| `official_letter` | 공문서 | request | 03-07 |

---

## 관련 문서

- [결재관리 시스템 개요](README.md) — 아키텍처, 상태 관리, 권한
- [API 명세](api-reference.md) — 20개 엔드포인트 상세
- [워크플로우 상세](workflows.md) — 승인/반려/회수/보류/전결 흐름
- [기획서 원본](../../plans/approval-management-system-plan.md) — Phase 1~4 전체 기획

---

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