@nameofSEOKWONHONG 님, rhwp 프로젝트 첫 기여를 환영합니다! 🎉

구조적 사고가 돋보이는 좋은 PR입니다. 기능·검증 모두 통과해서 곧 merge 진행 가능한 수준입니다. 아래에 (A) 이번 PR 에서 반영 권장, (B) 후속 커밋으로 보완 권장, (C) 향후 기여 시 참고할 프로젝트 규칙 순으로 정리드립니다.

👍 잘하신 점 (먼저)

• 계층 분리가 깔끔함 — DocumentCore::extract_*_native 가 순수 데이터 추출, src/main.rs 는 I/O orchestration 만. rhwp의 기존 분리 원칙과 일치.
• 이미지 2단계 폴백 — 컨트롤 참조 실패 시 bin_data_id 로 복구하는 get_bin_data_image_{data,mime}_native. 실제 현장 HWP 파일 품질을 고려한 방어적 설계.
• 기존 API 재사용 — detect_clipboard_image_mime, build_page_tree, paginate() 등 프로젝트 자원을 잘 활용.
• docstring 품질 — 각 pub 함수에 의도(TextLine 순회, 표 내부 중복 추출 방지)를 명확히 기록.
• Known Issue 정직 공개 — page_count == 0 underflow, MIME 매핑 한계를 명시하고 후속 패치로 분리. 업스트림에 가장 환영받는 스타일.
• CI + cargo clippy + test 모두 통과.

🔧 (A) 이번 PR 범위 내 — 작은 수정 요청

A1. 최종 보고서 내부 링크 깨짐

mydocs/report/task_m100_237_report.md 하단의 링크:

- 계획: [feature_text_markdown_export_plan.md](../plans/feature_text_markdown_export_plan.md)
- 단계: [feature_text_markdown_export_stage1.md](../working/feature_text_markdown_export_stage1.md)

실제 파일명은 task_m100_237.md / task_m100_237_stage1.md 로 갱신됐습니다. 링크를 실제 파일명에 맞게 수정 부탁드립니다.

A2. page_count == 0 가드

src/main.rs 의 export_text / export_markdown 에 이미 감지 후 return 은 있지만, 범위 오류 메시지 (페이지 번호가 범위를 벗어났습니다 (0~{page_count - 1}))가 page_count == 0 이전에 평가되면 underflow 합니다. 가드 위치 앞으로 이동하거나 page_count.saturating_sub(1) 사용 권장.

if p >= page_count {
    eprintln!("오류: 페이지 번호가 범위를 벗어났습니다 (0~{})", page_count.saturating_sub(1));
    return;
}

📋 (B) 후속 커밋(또는 후속 PR)으로 보완 권장

B1. 구현계획서 누락

rhwp의 하이퍼-워터폴 규칙상 mydocs/plans/task_m100_237_impl.md (구현계획서)가 필요합니다. 수행계획서와 구분되는 목적:

• 수행계획서 (task_m100_237.md): WHY, WHAT, 범위, 리스크
• 구현계획서 (task_m100_237_impl.md): HOW, 단계 분할, 파일별 diff 의도

CLAUDE.md 의 "문서 파일명 규칙" 섹션을 참고해 주세요.

B2. orders 갱신 누락

mydocs/orders/20260424.md 에 Task #237 섹션을 추가 부탁드립니다. 형식은 기존 섹션(예: ## 1. Task #265 — HWP 3.0 파일 감지 + 친절한 에러 메시지)을 참고.

B3. export-text / export-markdown 자동화 테스트

Known Issue에 본인도 기록하셨는데, 현재 수동 CLI 실행만 검증됐습니다. 최소 수준으로:

• 텍스트 추출: 작은 샘플 로드 → 특정 문자열 포함 확인
• 마크다운 추출: 이미지 토큰 치환 + assets 디렉터리 생성 확인
• 통합 테스트 파일 (tests/export_text_markdown.rs) 신설 권장

B4. MIME 확장자 매핑 확장

image/tiff → tif, image/svg+xml → svg 등 누락된 매핑을 보강해 주세요. 단순하므로 후속 커밋 1건으로 충분.

B5. 이슈 #237 본문 정리

이슈 #237 본문이 PR 템플릿 구조(변경요약/테스트/스크린샷)로 작성되어 있는데, 이는 PR용 템플릿입니다. 이슈는 증상/재현/기대 동작/제안 형식이 더 적합합니다. 이번 PR 이슈는 이미 CLOSED 상태이지만, 앞으로 이슈 작성 시 참고 부탁드립니다.

📖 (C) 향후 기여 시 참고할 프로젝트 규칙

rhwp는 하이퍼-워터폴 방법론을 채택하고 있어 일반적인 오픈소스보다 문서화가 엄격합니다. 다음 순서를 지켜주시면 리뷰가 빠르게 진행됩니다:

1. 이슈 생성 (증상/재현/제안)
2. 브랜치 생성 — 브랜치명은 local/task{번호} 형식 권장 (외부 기여자는 이번처럼 feature/* 도 허용)
3. 수행계획서 (mydocs/plans/task_m100_{번호}.md) 작성 + 승인 요청
4. 구현계획서 (task_m100_{번호}_impl.md) 작성 + 승인 요청
5. 단계별 구현 + 단계 보고서 (mydocs/working/task_m100_{번호}_stage{N}.md) — 범위가 크면 분리
6. 최종 보고서 (mydocs/report/task_m100_{번호}_report.md) + orders/ 갱신
7. PR 생성 (위 문서들을 함께 커밋)

상세는 CLAUDE.md 참조. 이번 PR은 이미 상당 부분을 갖추셨으니 작은 보완만 하시면 됩니다.

다음 단계

위 A1, A2 만 이번 PR 에 반영 후 push 해주시면 merge 진행하겠습니다. B 항목은 별도 후속 PR 이나 추가 커밋으로 처리 가능합니다.

감사합니다! 앞으로도 많은 기여 부탁드립니다.