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

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

작성일: 2026-03-09 상태: 조사 완료 관련: README.md | API 명세

---

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 추가 필요:

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

$casts 추가 필요:

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

6.3 ApprovalStep.php 수정 상세

$fillable 추가 필요:

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

6.4 ApprovalForm.php 수정 상세

$fillable 추가 필요:

'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

---

관련 문서

• 결재관리 시스템 개요 — 아키텍처, 상태 관리, 권한
• API 명세 — 20개 엔드포인트 상세
• 워크플로우 상세 — 승인/반려/회수/보류/전결 흐름
• 기획서 원본 — Phase 1~4 전체 기획

---

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