docs: [standards] PDF 경량화 설정 및 font-weight 주의사항 추가

- 폰트 서브셋팅(enable_font_subsetting) 필수 설정 추가
- font-weight 800 이상 사용 금지 규칙 추가
- 섹션 번호 정리 (5.경량화, 6.수정가이드, 7.긴급복구, 8.체크리스트)
This commit is contained in:
김보곤
2026-03-11 10:50:06 +09:00
parent f0d7a29be9
commit 95bf896536

View File

@@ -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/
- [ ] `<link href="https://fonts.googleapis.com/...">` 미포함
- [ ] `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()`
---