diff --git a/dev/standards/pdf-font-policy.md b/dev/standards/pdf-font-policy.md index 097962f..f286ff4 100644 --- a/dev/standards/pdf-font-policy.md +++ b/dev/standards/pdf-font-policy.md @@ -27,7 +27,8 @@ Failed to open stream: Permission denied ❌ DomPDF의 isRemoteEnabled 옵션 사용 금지 ❌ font-family에 'Malgun Gothic' 등 시스템 전용 폰트 단독 사용 금지 (DomPDF가 인식 못함) ✅ NanumGothic을 DomPDF에 등록하여 사용 -✅ 폰트 등록은 storage/fonts/에 캐시 (vendor/ 아님) +✅ 폰트 원본은 resources/fonts/에 프로젝트와 함께 배포 (시스템 설치 의존 금지) +✅ 폰트 캐시는 storage/fonts/에 저장 (vendor/ 아님) ✅ 자동 등록 패턴(ensureKoreanFont) 적용 ✅ font-weight는 normal/bold만 사용 (800 이상 금지 — DomPDF 미매칭으로 한글 깨짐) ✅ 폰트 서브셋팅 활성화 (config/dompdf.php) @@ -100,12 +101,15 @@ DomPDF는 웹 브라우저가 아니다. 구글 폰트를 다운로드 → 파 ### 4.1 표준 한글 폰트: NanumGothic -SAM 프로젝트의 PDF 한글 폰트는 **NanumGothic**을 사용한다. 로컬(Docker)과 서버(Bare-metal) 모두 `fonts-nanum` 패키지가 설치되어 있다. +SAM 프로젝트의 PDF 한글 폰트는 **NanumGothic**을 사용한다. 폰트 파일은 프로젝트에 포함되어 Git으로 배포된다. 서버에 `fonts-nanum` 패키지를 별도 설치할 필요가 없다. -| 환경 | 폰트 경로 | 설치 방법 | -|------|----------|----------| -| 로컬 (Docker) | `/usr/share/fonts/truetype/nanum/` | Dockerfile에 포함 | -| 개발/운영 서버 | `/usr/share/fonts/truetype/nanum/` | `sudo apt install fonts-nanum` | +| 항목 | 경로 | 설명 | +|------|------|------| +| 폰트 원본 (Git 관리) | `resources/fonts/NanumGothic.ttf` | 프로젝트와 함께 배포 | +| 폰트 원본 (Git 관리) | `resources/fonts/NanumGothicBold.ttf` | 프로젝트와 함께 배포 | +| DomPDF 캐시 | `storage/fonts/` | 런타임에 자동 생성 (.gitignore) | + +> 이전에는 시스템 폰트(`/usr/share/fonts/truetype/nanum/`)에 의존했으나, 운영서버에 `fonts-nanum` 미설치 시 한글이 깨지는 문제가 발생하여 프로젝트 번들링 방식으로 전환했다. ### 4.2 Blade 뷰 font-family 지정 @@ -125,6 +129,9 @@ PDF를 생성하는 서비스에 다음 패턴을 적용한다. 최초 1회만 ```php /** * DomPDF에 한글(NanumGothic) 폰트 등록 (최초 1회만 실행) + * + * 폰트 원본은 resources/fonts/에 프로젝트와 함께 배포된다. + * 시스템 폰트(fonts-nanum) 설치 여부에 의존하지 않는다. */ private function ensureKoreanFont(): void { @@ -139,13 +146,13 @@ private function ensureKoreanFont(): void } } - // 시스템에 설치된 NanumGothic 찾기 - $fontPaths = [ - 'normal' => '/usr/share/fonts/truetype/nanum/NanumGothic.ttf', - 'bold' => '/usr/share/fonts/truetype/nanum/NanumGothicBold.ttf', + // 프로젝트에 포함된 폰트 (Git으로 배포됨) + $fontSources = [ + 'normal' => resource_path('fonts/NanumGothic.ttf'), + 'bold' => resource_path('fonts/NanumGothicBold.ttf'), ]; - if (! file_exists($fontPaths['normal'])) { + if (! file_exists($fontSources['normal'])) { return; } @@ -154,7 +161,7 @@ private function ensureKoreanFont(): void } // storage/fonts/에 복사 후 DomPDF에 등록 - foreach ($fontPaths as $weight => $src) { + foreach ($fontSources as $weight => $src) { $dst = $fontDir.'/'.basename($src); if (! file_exists($dst)) { copy($src, $dst); @@ -192,7 +199,7 @@ $pdfContent = $pdf->output(); ``` storage/fonts/ ├── installed-fonts.json ← DomPDF 폰트 레지스트리 -├── NanumGothic.ttf ← 시스템에서 복사된 원본 +├── NanumGothic.ttf ← resources/fonts/에서 복사된 원본 ├── NanumGothicBold.ttf ├── nanumgothic_normal_*.ufm ← DomPDF가 생성한 메트릭 캐시 ├── nanumgothic_normal_*.ttf ← DomPDF가 생성한 서브셋 @@ -317,11 +324,12 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/ - [ ] DomPDF 옵션에 `isRemoteEnabled` 없음 - [ ] 한글 PDF에 `ensureKoreanFont()` 호출 있음 -### 서버 환경 확인 +### 폰트 배포 확인 -- [ ] `fonts-nanum` 패키지 설치 확인 (`fc-list :lang=ko | grep Nanum`) +- [ ] `resources/fonts/NanumGothic.ttf` 존재 확인 (Git 관리) +- [ ] `resources/fonts/NanumGothicBold.ttf` 존재 확인 (Git 관리) - [ ] `storage/fonts/` 디렉토리 쓰기 권한 확인 -- [ ] 미설치 시: `sudo apt install fonts-nanum` +- [ ] 시스템 폰트(`fonts-nanum`)에 의존하지 않음 확인 --- @@ -330,6 +338,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/ - 서버 운영 매뉴얼: `dev/deploys/ops-manual/README.md` - DomPDF 패키지: `barryvdh/laravel-dompdf` v3.1 - DomPDF 설정: `mng/config/dompdf.php` — 서브셋팅, DPI 등 +- 폰트 원본: `mng/resources/fonts/` — NanumGothic TTF (Git 관리) - 구현 참조: `mng/app/Services/HR/PayrollService.php` — `ensureKoreanFont()` ---