# task-1348.1 완료 보고서: 한글 폰트 대량 설치 + 배너 에디터 폰트 선택 기능

## SCQA

**S**: 배너 에디터 서버에 한글 폰트가 4개(Noto Sans CJK KR, Do Hyeon, 나눔명조, Pretendard)만 설치되어 있으며, 배너 에디터 UI에서 폰트 변경 기능이 없다.

**C**: 다양한 배너 디자인이 필요하지만 폰트 선택지가 극히 제한적이어서 디자인 다양성이 떨어진다. 사용자가 배너 에디터 내에서 폰트를 변경할 방법이 없다.

**Q**: 한글 폰트를 대량 설치하고 배너 에디터에서 폰트를 선택할 수 있도록 할 수 있는가?

**A**: 47개 한글 폰트 패밀리를 설치하고, `GET /api/banner-editor/fonts` API + 프론트엔드 폰트 드롭다운을 구현하여 배너 에디터에서 실시간 폰트 변경이 가능하도록 했다. 총 폰트 파일 130+개 설치, API 테스트 47개 패밀리 정상 반환 확인.

## 작업 내용

### 작업 1: 한글 폰트 대량 설치

**설치 경로**: `~/.local/share/fonts/`

**설치 전**: 4개 패밀리 (Noto Sans CJK KR, Do Hyeon, NanumMyeongjo, Pretendard)
**설치 후**: 47개 패밀리 (fc-list charset=AC00 기준)

**신규 설치된 폰트 (카테고리별)**:

산세리프 (고딕):
- SUIT (9 weights), Wanted Sans (4 weights), Spoqa Han Sans Neo (5 weights)
- IBM Plex Sans KR (7 weights), NanumGothic (3 weights), NanumGothicCoding
- Gothic A1 (9 weights), Gowun Dodum, Hahmlet (9 weights)
- Pretendard JP (9 weights + Variable), NanumBarunGothic (3 weights)

세리프 (명조):
- Noto Serif KR (7 weights), Gowun Batang (2 weights)
- KoPub Batang Pro (3 weights), NanumMyeongjo 추가 weights

디스플레이/특수:
- Black Han Sans, Jua (기존), Gugi, Song Myung, Poor Story
- East Sea Dokdo, Sunflower (3 weights), Yeon Sung, Gaegu (3 weights)
- Hi Melody, Dokdo, Stylish, Cute Font, Kirang Haerang, Gamja Flower

코딩/모노:
- D2Coding (3 variants), Source Code Pro

나눔 패밀리 (추가):
- NanumSquare, NanumSquareRound, NanumSquare_ac, NanumBarunpen
- Nanum Brush Script, Nanum Pen Script, NanumMyeongjo/NanumGothic Eco

### 작업 2: 배너 에디터 폰트 선택 기능

**server.py** — `GET /api/banner-editor/fonts` API 추가:
- `fc-list :charset=AC00 --format=%{family}\n` 실행
- 각 라인의 첫 번째(주) 패밀리명만 추출, 중복 제거, 정렬
- 에러 시 빈 배열 graceful 반환

**BannerEditorView.js** — 폰트 드롭다운 UI 추가:
- `availableFonts` state + API fetch useEffect (mode=editor일 때)
- `fontFamily` 속성을 selectedProps에 추가
- 요소 선택 시 computed fontFamily 자동 읽기
- 텍스트 속성 패널에 폰트 선택 `<select>` 추가 (폰트 크기 위)
- 선택 시 `updateSelectedStyle('fontFamily', v)`로 즉시 반영

## 생성/수정 파일

**수정 파일**:
- `/home/jay/workspace/dashboard/server.py` (lines 3619-3635: 폰트 목록 API 추가)
- `/home/jay/workspace/dashboard/components/BannerEditorView.js` (5곳 수정: state, useEffect, readElementProps, selectedProps 초기값, JSX 드롭다운)

**추가 파일** (폰트):
- `~/.local/share/fonts/` — 91개 루트 폰트 파일 (.ttf/.otf)
- `~/.local/share/fonts/Pretendard/` — 10개 파일 (기존)
- `~/.local/share/fonts/PretendardJP/` — 10개 파일 (신규)
- `~/.local/share/fonts/Nanum/` — 33개 파일 (신규)

## 테스트 결과

- API 테스트: `curl http://localhost:8000/api/banner-editor/fonts` → 47개 폰트 패밀리 정상 반환
- `fc-list :lang=ko` → 79개 항목 (full Korean support)
- `fc-list :charset=AC00` → 119개 항목 (Korean 문자 포함)
- 기존 폰트 삭제 없음 확인

## 발견 이슈 및 해결

### 자체 해결 (3건)

1. **fc-list :lang=ko 필터가 Pretendard, SUIT 등 누락** — `:charset=AC00` (한글 음절 U+AC00 포함 여부)으로 변경하여 47개 → 모든 설치된 한글 폰트 캡처
   - 수정: `server.py:3622` `:lang=ko` → `:charset=AC00`

2. **font family 가중치 변형이 별도 항목으로 표시** — comma-separated 라인에서 첫 번째 이름만 추출하여 중복 방지 (예: "Gothic A1,고딕 A1,Gothic A1 Black" → "Gothic A1"만 추출)
   - 수정: `server.py:3628` `line.split(",")[0].strip()` 패턴 적용

3. **Source Code Pro가 charset=AC00 필터에서 제외** — Latin-only 폰트이므로 한국어 문자 미포함은 정상. 코딩용 폰트로 fc-list 전체에서는 확인 가능하나 배너 에디터 한글 폰트 목록에서는 의도적 미표시.

## QC 검증 결과

- overall: WARN (style_check만 WARN, 나머지 PASS/SKIP)
- test_runner: PASS (pytest 7 passed in 0.27s)
- pyright_check: PASS (0 errors, 0 warnings)
- file_check: PASS (server.py 223232 bytes, BannerEditorView.js 87765 bytes)
- data_integrity: PASS
- TRUST 5: 전 차원 passed (T/R/U/S/T 모두 true)

참고: 본 작업은 코드 개발(폰트 설치 + API/UI 구현) 작업이나, 태스크 파일에 "배너" 키워드가 포함되어 디자인 QC 트리거가 발생함. 실제 디자인 산출물(이미지/배너 생성)은 없으므로 로키(opus) 코드 리뷰는 대상 외.

## 모델 사용 기록

- 팀원: 토르(백엔드) / 작업: server.py API 엔드포인트 추가 / 모델: sonnet
- 팀원: 프레이야(프론트엔드) / 작업: BannerEditorView.js 폰트 드롭다운 / 모델: sonnet
- 팀원: (시스템작업) / 작업: 한글 폰트 대량 다운로드 및 설치 / 모델: sonnet