HWPX 원본 문서를 업로드하면 AI가 내용을 분석하고, 기존 문서의 스타일·구조를 유지한 채 새 문서를 생성하는 로컬 데모 서비스입니다.
현재 저장소는 v2 / v3 / v4 가 공존합니다.
권장 실행 버전은 v4이며, 각 버전의 차이는 아래를 참고하세요.
| 버전 | 폴터 | 권장 여부 | 핵심 특징 |
|---|---|---|---|
| v4 | v4/ |
✅ 권장 | 샘플 문서 체험, Toast 알림, HWPX 검증, 다크모드, Vitest/CI, Docker |
| v3 | v3/ |
유지보수 모드 | v2의 preview≠download 해결, 자립형 구조, @rhwp/core exact pin |
| v2 | v2/ |
레거시 | 초기 모듈 분리 버전 (Google OAuth, 드래그앤드롭, WASM 파싱) |
| v1 | app.js, index.html |
아카이브 | PHP 기반 단일 페이지 데모 |
v4 실행 가이드는
v4/README.md에 상세히 기술되어 있습니다.
cd v4
npm install # workspace 설치 (client + server)
cp server/.env.example server/.env # API 키 채우기
npm run dev # client(5192) + server(8792) 동시 실행- 클라이언트: http://127.0.0.1:5192
- 서버 API : http://127.0.0.1:8792
- 자동 로그인 모드:
npm run dev:auto(client 5193 + server 8793)
cd v3
npm install
cp server/.env.example server/.env
npm run dev # client(5190) + server(8790)- 클라이언트: http://127.0.0.1:5190
- 자동 로그인 모드:
npm run dev:auto(client 5191 + server 8791)
cd v2
npm install
npm run dev # client(5188) + server(8788)- 클라이언트: http://127.0.0.1:5188
- 자동 로그인 모드:
npm run dev:auto(client 5189 + server 8789)
| 기능 | 설명 |
|---|---|
| 샘플 문서 체험 | 업로드 없이 공문서 기본 양식 샘플로 즉시 체험 가능 (EmptyState 컴포넌트 + GET /api/samples) |
| Toast 알림 | 성공/오류/경고 토스트 메시지 (useToast.js) |
| HWPX 검증 패널 | 생성된 문서의 규칙/구조/컨테이너/스키마 검증 결과 시각화 (ValidationPanel) |
| AI 비용 투명성 | 생성마다 소요 시간·토큰 추정·예상 비용(USD) 표시 |
| ErrorBoundary | 런타임 크래시 시 흰 화면 대신 복구 UI (App.jsx 래핑) |
| 다크 모드 | prefers-color-scheme 기반 자동 테마 |
| 테스트 인프라 | Vitest 도입 + GitHub Actions CI(.github/workflows/v4-checks.yml) |
| Docker 지원 | v4/Dockerfile 컨테이너 실행 |
@rhwp/core |
ADR-0001 준수 exact pin (재현성 보장) |
setup-rhwp-symlink.sh |
postinstall로 @rhwp/core WASM 파일 자동 연결 |
| 기능 | 설명 |
|---|---|
| AI 미커버 body 자동 비우기 | AI가 N섹션만 생성하면 나머지 템플릿 섹션 body를 모두 비움 |
| AI 프롬프트 강화 | 섹션 5개 이상, body 3~5문장, 중복/빈 body 금지 |
fix_namespaces 후처리 |
ns0:/ns1: → 한컴 표준 hh/hc/hp/hs 교체 |
clone_form.py CLI |
ZIP-level 문자열 치환으로 표/이미지/병합셀 100% 보존 |
| 자립형 구조 | scripts/, templates/ 낸부화 — 외부 경로 의존 0 |
| Google OAuth + Mock 폭백 | client_id 미설정 시 개발용 Mock 로그인 제공 |
| 버전 A/B 실행 | dev (수동 로그인) + dev:auto (자동 오버레이) 동시 지원 |
- React + Vite 클라이언트 / Express 서버 / Python HWPX 빌더 분리
@rhwp/coreWASM 브라우저 파싱- 멀티 AI 프로바이더 (Anthropic / OpenAI / Kimi / xAI)
- 드래그앤드롭 업로드 + 파일 해제
- SVG 다이어그램 자동 생성 + HWPX 내 PNG 삽입
현재 main에 반영된 변경과 별도 브랜치의 후속 작업을 구분한 시간순 요약입니다 (최신순).
브랜치 상태: 아래 2026-09 항목은 최신 통합본
codex/hwp-quality-safety-2026-09-27에 적용됐습니다. 이 저장소의main및 기존v4/코드에는 아직 병합되지 않았습니다. 따라서main에서 실행한 v4의@rhwp/core버전을 0.8.6으로 해석하면 안 됩니다.
- 골든 HWPX 검사에 날짜·금액 보존, 중복 문장, 원본 안내문 누출 사례를 추가하고 격리 실행을 CI에 연결했습니다. 실제 실행 사례가 0건이면 실패하며 평가용 AI API 호출은 추가하지 않습니다.
- 테스트 출력과 설정 파일 경로를 분리하고, 테스트 중 실제
server/.env쓰기와 개발 서버 시작 시 생성 파일 자동 정리를 차단했습니다. 업로드 문서의 지시문은 작성 자료로만 다루도록 프롬프트 경계와 회귀 테스트도 추가했습니다. - 통합본의 로컬 검증은 골든 4/4, 서버 125/125, 클라이언트 91/91, Python 49/49 및 빌드 통과입니다. HWP 변환 사례 1건은 변환기 부재로 스킵했고 원격 CI와 실제 AI 모델의 지시문 대응은 확인하지 않았습니다.
- 독립 통합본의
@rhwp/core를0.7.17에서0.8.6으로 올리고 정확한 버전으로 고정했습니다. 브라우저의 HWP/HWPX 파싱·미리보기·생성·다운로드를 로컬에서 검증했습니다.main/v4의 의존성은 아직0.7.17이며, 한컴오피스에서 열기와 유료 AI 호출은 검증하지 않았습니다.
- 문서 소유권 검사, 설정 변경 권한, 인증·컨테이너 바인딩, 업로드·워커 자원 상한을 보강했습니다. 다중 XML 구역과 필수 검증 실패를 명확히 거절하고, 초안 수정 후 이전 결과 다운로드와 AI 스트림 장애 후 자동 유료 재생성을 차단했습니다.
- v4를 독립 환경에서 시니어 개발자·디자이너·PO 3개 관점으로 전수 검토 후 4단계(Phase 0~3)에 걸쳐 발견 항목을 전부 수정. 코드 변경은 PR #2에서 확인·머지 가능 (CI 통과 완료).
- 데이터 무결성: 본문에
&/<포함 시 다이어그램이 조용히 누락되던 버그, macOS(NFD)에서 AI 본문이 빈 섹션으로 나오던 버그, 생성 실패 시 손상 파일이 다운로드되던 문제, 에러 시 서버 내부 정보 노출 — 4건 모두 수정. - 보안: 외부/팀 배포용
AUTH_MODE=protected신설(로그인 게이트·rate limit·helmet·XSS 방어·zip/XXE 방어·산출물 익명화). 로컬 기본 동작은 무변경. - 제품 기능: AI 초안을 섹션 단위로 검토·수정·재생성할 수 있는 편집 루프 추가, 원문 전체 컨텍스트 반영, AI 모델 선택 + 실사용 비용 표시, 최근 생성 문서 히스토리, 문서 유형별 맞춤 입력 필드.
- 품질 인프라: 자동 테스트 41개 신규(서버 16 · 클라이언트 9 · Python 16) + CI 편입, 구조화 로깅 및
/api/metrics, 다크모드 대비 WCAG AA 통과.
@rhwp/core0.7.2 → 0.7.17 범프 (v2 / v3 / v4 client) — 업스트림 rhwp 누적 수정(수식·표·차트·HWPX 렌더 정합)을 반영. ADR-0001에 따라 exact pin 유지.npm install+vite build통과 검증(WASM 번들 정상). 단, 브라우저 런타임(HWPX 파싱/렌더) 동작은 별도 확인 권장.- 변경 이력(Changelog) 섹션 신규 — v1(2026-04-10)부터 v4(2026-04-26)까지 날짜·버전별 시간순 요약 정리.
- v4 기능 표 보강 — 실재하나 README에 누락돼 있던 항목 추가:
ErrorBoundary, AI 비용/토큰 표시, 다크 모드(prefers-color-scheme), Vitest + GitHub Actions CI(v4-checks.yml),v4/Dockerfile, 샘플 API(GET /api/samples).
- v4 신규: 검증 UI(
ValidationPanel) · 샘플 문서 체험(EmptyState+GET /api/samples) · Toast 알림 · AI 비용/토큰 표시 · GitHub Actions CI(v4-checks.yml). - 코드 품질:
ErrorBoundary도입(런타임 크래시 복구),useDraftAbortController(fetch 경쟁 조건 해결),LoginOverlay접근성(focus trap·Escape·role=dialog), 다크 모드(prefers-color-scheme), Vitest 테스트 인프라,v4/Dockerfile. - 버전 식별자 정정: v4 문서/코드에 남아 있던 v2·v3 잔재 정리,
@rhwp/coreexact pin(0.7.2) 복원(ADR-0001 준수). - 다이어그램 HWPX 삽입 수정: Homebrew Python venv 우선 적용으로
cairosvg/libcairo로딩 문제 해결,render_diagram()이steps/items/rows키 인식,cairosvg를requirements.txt에 추가. - 문서: 루트 README에 v2/v3/v4 통합 가이드 반영, 폭포수 문서를 v3/v4로 분리.
- 검증 레이어 + 골든 테스트 + polaris_dvc 연동 + docType별 스펙 프레임워크.
- preview≠download 바이트 불일치 해결, P0~P2 개선(미커버 body 자동 비우기, 프롬프트 강화, 네임스페이스 정정,
clone_form.py),scripts/·templates/내부화.
- Google OAuth 로그인/로그아웃, client_id 미설정 시 Mock 폴백, 별도 포트 자동 로그인 오버레이,
/auth프록시·팝업 폴백. 폭포수 문서 v1.2/v1.3 갱신.
- v2를 client/server/shared 모듈 구조로 리팩터링 + self-learning 인프라(lessons-learned, skills, hooks). Anthropic 기본 모델
claude-opus-4-7업그레이드. v2 AI 문서 스튜디오 + 다이어그램 렌더링.
- 자립형 AI HWPX 데모 공개, HWPX 패키지 구조 문서화, 한국어 서비스 소개 랜딩.
버전별 기능 비교는 위 버전별 주요 변경사항을, 상세 변경은
docs/v2-update.md와 각 버전의CLAUDE.md(실수 이력)를 참고하세요.
.
├── v4/ # ✅ 최신 권장 버전
│ ├── client/ # React 18 + Vite
│ ├── server/ # Express + Node.js ESM
│ ├── shared/ # client+server 공용 코드
│ ├── scripts/ # Python HWPX 빌더
│ ├── templates/ # HWPX 템플릿 + 샘플
│ ├── docs/adr/ # Architecture Decision Records
│ ├── skills/ # 재사용 워크플로우
│ ├── hooks/ # 자동화 가드레일 (shell)
│ ├── tools/ # 검증 스크립트
│ └── README.md # v4 상세 가이드
│
├── v3/ # 자립형 안정 버전
│ ├── client/ # React + Vite
│ ├── server/ # Express
│ ├── shared/
│ ├── docs/
│ ├── skills/
│ ├── hooks/
│ ├── tools/
│ └── README.md # v3 상세 가이드
│
├── v2/ # 초기 모듈 분리 버전
│ ├── client/
│ ├── server/
│ ├── shared/
│ └── ...
│
├── docs/ # 프로젝트 전체 문서
│ ├── waterfall-hwpx-demo/ # 폭포수 문서 (v2 기준 v1.3)
│ ├── v2-update.md # v2 변경 내역
│ └── HWPX_FORMAT.md # HWPX 포맷 참조
│
├── scripts/ # 루트 레벨 Python 스크립트 (v1/v2 유산)
├── templates/ # 루트 레벨 템플릿 (v1/v2 유산)
├── app.js # v1 레거시 (PHP 대체 Node.js)
├── index.html # v1 레거시
└── README.md # 이 파일
| 목적 | 명령 |
|---|---|
| 완료 선언 전 필수 검증 | bash v4/hooks/pre-completion-checklist.sh |
| 단독 E2E 스모크 테스트 | bash v4/tools/smoke-test.sh |
| HWPX 마커 검증 | python3 v4/tools/verify-hwpx-markers.py <hwpx_path> MARKER1 ... |
| 클라이언트 프로덕션 빌드 | cd v4/client && npm run build |
v3 검증 명령은
v4/→v3/로 경로만 변경하면 동일합니다.
v4/server/.env (또는 v3/server/.env, v2/server/.env) 파일 생성:
PORT=8792
CLIENT_ORIGIN=http://127.0.0.1:5192
OAUTH_REDIRECT_BASE=http://127.0.0.1:8792
# AI Provider API Keys (최소 1개 필요)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
KIMI_API_KEY=...
XAI_API_KEY=...
# Google OAuth (선택 — 미설정 시 Mock 로그인 폭백)
GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxbrew install cairo # macOS
pip3 install cairosvg| 문서 | 위치 | 설명 |
|---|---|---|
| v4 상세 가이드 | v4/README.md |
v4 실행, 구조, Self-Learning Protocol |
| v3 상세 가이드 | v3/README.md |
v3 실행, 구조, 자립형 기능 |
| v2 업데이트 상세 | docs/v2-update.md |
v2 변경 내역, 버그 수정, UI 개선 |
| 폭포수 문서 (v4 기준) | v4/docs/waterfall-hwpx-demo/ |
기획→검토 8단계 전체 산출물 |
| 폭포수 문서 (v3 기준) | v3/docs/waterfall-hwpx-demo/ |
기획→검토 8단계 전체 산출물 |
| HWPX 포맷 참조 | docs/HWPX_FORMAT.md |
한글 문서 구조 기술 참조 |
AI HWPX Demo generates a new HWPX document while preserving the original document's style and structure. This repository contains three active versions: v4 (latest, recommended), v3 (stable), and v2 (legacy).
cd v4 && npm install && cp server/.env.example server/.env
npm run dev
# Open http://127.0.0.1:5192- Browser-side WASM parsing via
@rhwp/core - Sample document quick-start (no upload required)
- Toast notifications + HWPX validation panel
- Multi-provider AI: Anthropic Claude, OpenAI, Kimi, xAI
- SVG diagrams (flowchart / timeline / comparison) in preview and HWPX