diff --git a/dev/standards/pdf-font-policy.md b/dev/standards/pdf-font-policy.md index e3b5182..097962f 100644 --- a/dev/standards/pdf-font-policy.md +++ b/dev/standards/pdf-font-policy.md @@ -29,6 +29,8 @@ Failed to open stream: Permission denied ✅ NanumGothic을 DomPDF에 등록하여 사용 ✅ 폰트 등록은 storage/fonts/에 캐시 (vendor/ 아님) ✅ 자동 등록 패턴(ensureKoreanFont) 적용 +✅ font-weight는 normal/bold만 사용 (800 이상 금지 — DomPDF 미매칭으로 한글 깨짐) +✅ 폰트 서브셋팅 활성화 (config/dompdf.php) ``` --- @@ -51,7 +53,19 @@ $pdf = Pdf::loadView('view', $data) ->setOptions(['isRemoteEnabled' => true]); ``` -### 2.3 DomPDF 미등록 폰트 사용 금지 +### 2.3 font-weight 800 이상 사용 금지 + +NanumGothic은 `normal`(400)과 `bold`(700) 두 가지 weight만 존재한다. `font-weight: 800` 이상을 지정하면 DomPDF가 매칭되는 폰트를 찾지 못해 해당 텍스트의 한글이 `?`로 깨진다. + +```css +/* ❌ DomPDF에서 한글 깨짐 — 800 weight에 매칭되는 폰트 없음 */ +h1 { font-weight: 800; } + +/* ✅ bold(700)까지만 사용 */ +h1 { font-weight: bold; } +``` + +### 2.4 DomPDF 미등록 폰트 사용 금지 DomPDF는 시스템 폰트를 자동으로 인식하지 않는다. `Malgun Gothic`, `Apple SD Gothic Neo` 등을 `font-family`에 지정해도 DomPDF가 찾지 못해 한글이 `???`로 깨진다. @@ -189,7 +203,42 @@ storage/fonts/ --- -## 5. 기존 코드 수정 가이드 +## 5. PDF 경량화 설정 + +### 5.1 배경 — 텍스트 PDF가 5MB + +급여명세서 PDF(텍스트만, 1페이지)가 약 5MB로 생성되는 문제가 발생. 원인은 DomPDF가 NanumGothic 폰트 파일 전체(수천 개 한글 글리프 포함)를 PDF에 임베딩하기 때문이다. + +### 5.2 폰트 서브셋팅 (필수) + +`config/dompdf.php`에서 `enable_font_subsetting`을 `true`로 설정한다. PDF에 실제 사용된 문자의 글리프만 포함하여 용량을 대폭 줄인다. + +```php +// config/dompdf.php +'options' => [ + 'enable_font_subsetting' => true, // ✅ 필수 — 사용 글자만 임베딩 + 'enable_javascript' => false, // ✅ 권장 — PDF 내 JS 불필요 + // ... +], +``` + +| 설정 | 변경 전 | 변경 후 | 효과 | +|------|---------|---------|------| +| `enable_font_subsetting` | `false` | `true` | 폰트 전체(~4-5MB) → 사용 글자만(수십KB) | +| `enable_javascript` | `true` | `false` | PDF 내 JS 코드 제거 | + +> 한글 폰트는 11,172개의 완성형 글자를 포함하지만, 급여명세서에 사용되는 글자는 100~200자 수준이다. 서브셋팅으로 99% 이상의 불필요한 글리프를 제거한다. + +### 5.3 경량화 체크리스트 + +- [ ] `config/dompdf.php`의 `enable_font_subsetting` → `true` +- [ ] `enable_javascript` → `false` (PDF 내 JS 미사용 시) +- [ ] Blade 뷰에 불필요한 이미지/외부 리소스 미포함 +- [ ] `font-weight`는 `normal`/`bold`만 사용 (미등록 weight가 fallback 폰트를 트리거하면 용량 증가) + +--- + +## 6. 기존 코드 수정 가이드 구글 폰트를 사용하는 기존 PDF 뷰를 발견하면 다음 절차로 수정한다. @@ -231,7 +280,7 @@ $pdf = Pdf::loadView('emails.payslip', ['payslipData' => $payslipData]) --- -## 6. 긴급 복구 — 운영서버 권한 오류 발생 시 +## 7. 긴급 복구 — 운영서버 권한 오류 발생 시 이미 구글 폰트를 사용하는 코드가 배포되어 권한 오류가 발생한 경우의 즉시 조치이다. 근본 수정(구글 폰트 제거 + ensureKoreanFont 적용)을 반드시 병행한다. @@ -246,7 +295,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/ --- -## 7. 체크리스트 +## 8. 체크리스트 ### PDF 뷰 작성 시 @@ -254,6 +303,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/ - [ ] `` 미포함 - [ ] `font-family`에 `NanumGothic` 포함 (DomPDF 한글 지원) - [ ] `font-family` fallback에 `Malgun Gothic`, `sans-serif` 포함 (브라우저용) +- [ ] `font-weight`는 `normal`/`bold`만 사용 (800 이상 금지) ### PDF 생성 코드 작성 시 @@ -279,6 +329,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/app/Services/HR/PayrollService.php` — `ensureKoreanFont()` ---