본문으로 건너뛰기

2026-04-22

2026-04-24 — ADR 0018 에 의해 재정의

"docx-first" 는 편집 전략 으로서는 폐기. 편집은 플랫폼 내 Tiptap 에디터 에서 수행하고, docx/PDF 는 최종 제출용 export 포맷 으로만 유지. ADR 0018 참조.

ADR 0012 — 한글 서식 export 2단 배포

결정문​

Phase 1 S1 (47M) 에서 docx-templates 기반 구현 을 선행하고, S1 말S2 초 (6~8M) 에 한글 네이티브 경로 를 후속 추가하는 2단 배포. Minority Report (P1 한글 병행 릴리스 요구) 는 파일럿 실측 4가지 조건 충족 시 S2 앞당김으로 완화.

배경​

  • ADR 0011 Phase 1 S1 pre-req (Pack 1 완제품화).
  • P5 기술 분석: docx-templates 7축 비교 전 영역 우세 (2.5 eng-day · 활성 OSS · CF pure JS).
  • P1 실무 반박: docx-only 는 표·세로쓰기 파손 · 파일럿 이탈 위험.

대안 검토​

A — docx-templates 단일 (P5 R1)​

기술 최적이나 한글 변환 서식 파손. 이탈 위험.

B — hwp-js 단일 (기각)​

OSS 정체 3년 · DOM 의존 · CF 불가 · 1.2MB · 6~8 eng-day.

C — pdfmake 단일 (기각)​

편집 불가 → 변호사 재작업 강제. 폰트 700KB+.

D — docx + hwp 병행 릴리스 (P1 요구, 부분 채택)​

이상적이나 S1 내 9+ eng-day × 2 = 18+ eng-day 부담. 2단 배포로 분할.

결정 + 근거​

2단 배포 구조​

S1 초 (4~5M) — docx-templates 선행

  • Cloud Function renderDocxTemplate (Node pure JS, 150ms/문서)
  • Server Action generate-docx.ts · weight 1 (docGeneration 킬 스위치 재사용)
  • UI DocTemplatePicker + DocxPreviewDialog
  • 사전 고지: UI 에 "한글 서식 S2 예정" 명시
  • 파일럿 실측 수집: 3명 × 한 달 × 생성 리포트

S1 말S2 초 (68M) — 한글 네이티브 후속

  • 별도 tier=B 회의 (파일럿 데이터 기반)
  • 재조사 대상: libhwp / officejs-hwp / hwp-js fork / LibreOffice headless / 상용 API

핵심 근거​

  1. docx 인프라 완성이 hwp 의 공통 pre-req: 템플릿 엔진·Server Action·UI·PII 마스킹·킬 스위치는 어떤 포맷이든 동일. docx 먼저 완성하면 hwp 는 렌더 레이어만 교체.
  2. 파일럿 데이터 없이 hwp 대안 선택 불가: libhwp/fork/상용 API 비교는 서식 깨짐 실측이 있어야 비용·복잡도 트레이드오프 판단 가능.
  3. P1 이탈 위험 완화 조건 4종 (아래 성공 지표) 을 S1 1개월 내 모니터링해 S2 앞당김 조항.

성공 지표 · S2 앞당김 트리거​

  • 파일럿 3명 × 한 달 생성 리포트 ≥ 30건
  • 서식 깨짐 리포트 2건+ 발생 시 S2 한글 네이티브 scope 확대
  • 파일럿 이탈 실제 1건+ = S2 앞당김 (Phase 1 S3 축소로 예산 이전)
  • S2 hwp 도착 시점 서식 깨짐 월 0건

Minority Report​

P1 변호사 (중대 반대)​

"S1 docx-only 배포는 파일럿 이탈 리스크. 한글 네이티브를 S1 에 병행 릴리스해야 안전." 처리: 4가지 완화 조건 (사전 고지 · 1개월 데이터 · 2건 트리거 · 이탈 시 앞당김) 을 Accept 조항으로 명시. 서식 깨짐 발생 시 즉시 S2 확대.

P5 개발자 (부분 반대)​

"hwp-js fork 는 S2 회의 전 maintained fork 여부 재조사 필요." 처리: S2 회의 안건 첫 3분에 자동 포함.

구현 PR 계획 (S1 착수)​

PR제목범위eng-day
1feat(docgen): docx-templates 기반 모듈 + 테스트functions/src/docgen/ + 단위 테스트 3종1.0
2feat(docgen): Server Action + PII 마스킹 + 킬 스위치generate-docx.ts · executeAiAction 래핑 · weight 11.5
3feat(docgen): DocTemplatePicker + DocxPreviewDialog UIshadcn/ui 시맨틱 · "hwp S2 예정" 문구1.0
4 (opt)feat(docgen): 관리자 템플릿 업로드tenant 소유권 게이팅 · Storage1.0
합계4.5 (PR 4 포함 시)

후속 (파생 안건)​

  • tier=B S2 한글 네이티브 경로 (파일럿 데이터 기반, S1 말~S2 초)
  • tier=C DocxPreviewDialog "S2 예정" 카피 확정
  • 텔레메트리 스키마: tenants/{tid}/docxGenerationStats/{YYYY-MM} — 생성 건수 · 서식 이슈 리포트 · 파일럿 플래그