docs:E-Sign TCPDF 폰트 정의 파일 오류 트러블슈팅 추가

- TCPDF font definition file 오류 원인/진단/해결 문서화
- 개발 vs 운영 환경 차이 (vendor 권한) 비교표 추가
- registerKoreanFont() 코드 수정 배경 설명
- 긴급 임시 조치 명령어 포함

deploys/ops-manual/08-troubleshooting.md

@@ -395,6 +395,7 @@ try {
 | 로그 유실로 에러 추적 불가 | `ls -la current/storage/logs` | `storage/logs` → shared 심링크 확인 |
 | 한글 폰트 미설치 | `ls /usr/share/fonts/truetype/nanum/` | `sudo apt install fonts-nanum` |
 | FPDI/TCPDF 미설치 | `composer show setasign/fpdi` | `composer install` |
+| TCPDF 폰트 정의 파일 오류 | 아래 "TCPDF 폰트 정의 파일 오류" 참고 | `registerKoreanFont()` 코드 수정 |
 
 **esign 디렉토리 권한 기준:**
 
@@ -414,6 +415,62 @@ sudo chmod -R 2775 /home/webservice/mng/shared/storage/app/private/esign/
 
 ---
 
+### TCPDF 폰트 정의 파일 오류 (font definition file)
+
+**증상:** 전자계약 서명 페이지에서 `TCPDF ERROR: Could not include font definition file: pretendard` (또는 `nanumgothic`) 오류.
+
+**근본 원인:**
+
+운영 환경에서 `vendor/tecnickcom/tcpdf/fonts/` 디렉토리가 배포 사용자(`hskwon`) 소유이므로 PHP-FPM(`www-data`)이 쓰기 불가.
+`TCPDF_FONTS::addTTFfont()`는 폰트 캐시 파일(.php, .z, .ctg.z)을 **생성만** 하고,
+`$pdf->SetFont('폰트명')`은 `K_PATH_FONTS`(vendor 경로)에서 **찾기만** 해서 경로 불일치 발생.
+
+개발서버는 `vendor/` 권한이 `2775 pro:develop`이라 PHP가 직접 쓸 수 있어 문제없음.
+
+**진단:**
+
+```bash
+# 폰트 캐시 존재 확인 (storage에 있으나 vendor에 없는 상태)
+ls -la /home/webservice/mng/shared/storage/app/private/fonts/
+ls /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/pretendard* 2>/dev/null
+
+# vendor fonts 소유자 확인
+stat -c "%U:%G %a" /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/
+
+# 에러 로그 확인
+grep -i "font definition\|Could not include" /home/webservice/mng/shared/storage/logs/laravel.log
+```
+
+**영구 해결 (코드 수정 - 2026-02-26 적용):**
+
+`PdfSignatureService.php`에서 `registerKoreanFont(Fpdi $pdf)` 메서드로 분리하여:
+1. 폰트 캐시를 `storage/app/private/fonts/`에 생성 (vendor 의존 제거)
+2. `$pdf->AddFont('pretendard', '', $fontDefFile)` — PDF 인스턴스에 **전체 경로로 등록**
+3. 이후 `SetFont('pretendard')`가 이미 등록된 폰트를 사용하므로 K_PATH_FONTS 미참조
+
+**긴급 임시 조치 (코드 수정 전):**
+
+```bash
+# vendor 폰트 디렉토리 권한 변경 (배포 시마다 초기화됨)
+sudo chown -R www-data:webservice /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/
+sudo chmod -R 775 /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/
+
+# 기존 캐시 삭제 (코드 수정 후 새 경로로 재생성)
+sudo rm -f /home/webservice/mng/shared/storage/app/private/fonts/pretendard.*
+sudo rm -f /home/webservice/mng/shared/storage/app/private/fonts/nanumgothic.*
+```
+
+**개발 vs 운영 환경 차이:**
+
+| 항목 | 개발 서버 | 운영 서버 |
+|------|----------|----------|
+| vendor/ 소유자 | `pro:develop` (2775) | `hskwon:hskwon` (배포 사용자) |
+| www-data vendor 쓰기 | ✅ 가능 | ❌ 불가 |
+| 폰트 캐시 위치 | vendor 내부 (기본) | storage/app/private/fonts/ |
+| `addTTFfont()` 결과 | vendor에 캐시 생성 → SetFont 성공 | storage에 캐시 생성 → SetFont 실패 (경로 불일치) |
+
+---
+
 ## 공통 장애
 
 ### 디스크 공간 부족