From 95bf8965364a0e7a67a88d9af5319c3fdce95d1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 11 Mar 2026 10:50:06 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[standards]=20PDF=20=EA=B2=BD=EB=9F=89?= =?UTF-8?q?=ED=99=94=20=EC=84=A4=EC=A0=95=20=EB=B0=8F=20font-weight=20?= =?UTF-8?q?=EC=A3=BC=EC=9D=98=EC=82=AC=ED=95=AD=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 폰트 서브셋팅(enable_font_subsetting) 필수 설정 추가 - font-weight 800 이상 사용 금지 규칙 추가 - 섹션 번호 정리 (5.경량화, 6.수정가이드, 7.긴급복구, 8.체크리스트) --- dev/standards/pdf-font-policy.md | 59 +++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 4 deletions(-) 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()` ---