반복 양식 문서 채우기용 document_core 연산 9종 — upstream 수용 의향을 여쭙습니다

[yuyu04]

HOP 기반으로 연구노트 docx/PDF → HWP 양식 일괄 변환 기능을 만들면서, 반복 양식 문서를 프로그램으로 채울 때 필요한 문서 정리 연산 몇 가지를 document_core에 직접 추가해 쓰고 있습니다. 지금은 제 포크에만 있는데, upstream에 둘 만한 내용인지 먼저 여쭙고 싶어 글을 올립니다.

배경

연구노트처럼 같은 표가 반복되는 양식을 12개월치 한 번에 채우는 파이프라인입니다. 표 구조를 LLM에 맡기면 원본 6×3 표가 6×2로 어긋나서, 앱이 기존 양식 표를 copyControl/pasteControl로 결정적 복제하고 내용만 채우는 방식으로 갑니다.

이 과정에서 rhwp 공개 API만으로는 해결이 안 되는 문제들이 있었습니다. 대부분 텍스트 조작 조합으로 흉내 내다 문단 인덱스가 밀리거나, 한컴에서 빈 페이지가 생기는 종류입니다.

추가한 연산

document_core + wasm_bindgen 바인딩으로 9종을 추가했습니다.

문단/페이지 정리

• removeOrphanParasBeforePageBreaks — 쪽나누기 앞 고아 빈 문단 제거. 강제 쪽나눔이 표 앞에 빈 문단을 남겨 항목 사이에 빈 페이지가 생기던 문제(92쪽 중 44쪽이 빈 페이지였습니다)
• trimTrailingParasAfterLastTable — 구역 끝 마지막 표 뒤 빈 문단 정리. 표 뒤에 보이는 내용이 있으면 보존
• compactLeadingParasBeforeTables — 표 위 선행 빈 문단 압축. 첫 항목이 한 페이지 밀리던 문제
• mergeSectionIntoPrevious

양식/목차

• removeSourceFormTable — 복제 원본 양식 표를 앵커 문단에 흡수시키며 제거(구역정의 등 다른 컨트롤 보존)
• rechunkTocTable, syncTocPageNumbers

셀 내부 삽입

• createTableInCell — 셀 안에 중첩 표. 표 문단의 line_height를 표 전체 높이로 잡아야 셀이 세로 공간을 예약합니다(이걸 안 하면 렌더에서 culling됩니다)
• insertPictureInCell — 셀 폭에 맞춰 비율 유지, 세로로 극단적인 이미지는 클램프
• fixPictureBorders

공개 범위 변경

• set_table_properties_native를 pub으로 — 쪽 경계에서 표가 흐르도록 호출 측에서 treatAsChar/pageBreak를 조정해야 합니다

작업 중 발견한 것 (별개로 참고가 되실 수 있어 공유)

1. set_table_properties의 treatAsChar가 저장에서 유실됩니다. serialize_table이 무손실 라운드트립을 위해 table.raw_ctrl_data(CommonObjAttr 원본 바이트)를 그대로 재사용하기 때문에, common.treat_as_char/common.attr만 바꾸면 저장 시 옛 바이트로 되돌아갑니다. 저희는 raw_ctrl_data[0..4] 비트0까지 3곳을 동기화하도록 고쳤습니다.

2. 다문단 셀 reflow 시 줄이 겹칩니다. reflow_line_segs는 문단 내부 줄 vpos만 누적하고 문단 시작 vpos는 원본(0)을 보존합니다. 셀 문단을 하나씩 reflow하면 모든 문단의 첫 line_seg가 vpos=0이 되어 셀 상단에 겹쳐 그려집니다. recalculate_section_vpos(&mut cell.paragraphs, 0)를 reflow 뒤에 부르는 것으로 해결했습니다.

3. delete_text_at가 char_shape ref를 중복 제거하지 않습니다. 셀 텍스트를 전체 삭제하면 여러 ref가 모두 위치 0으로 몰리고, 이후 삽입에서 보조 글자모양(예: 8pt)이 새 텍스트 일부를 덮습니다.

2·3번은 업스트림 버그로 보이는데, 원하시면 각각 회귀 테스트를 붙여 별도 이슈/PR로 정리하겠습니다.

현재 상태와 여쭙고 싶은 것

코드: https://github.com/yuyu04/rhwp/tree/feat/hop-agent-native-ops (f40c12f0)

솔직히 말씀드리면 이 브랜치는 v0.7.13(b3e16ef2) 기준이라 지금 devel보다 4,600커밋 이상 뒤처져 있습니다. object_ops.rs가 모듈 디렉터리로 분해되는 등 구조도 많이 바뀌어서, 그대로 PR을 내면 CI가 통과할 수 없습니다. 테스트 6개는 붙어 있습니다(셀 그림 크기 정상/클램프, 원본 표 흡수, 표 뒤 내용 보존).

여쭙고 싶은 것:

1. 이런 양식 문서 후처리 계열 연산이 rhwp의 범위에 맞나요? 아니면 애플리케이션 레이어에 두는 게 맞다고 보시나요?
2. 맞다면 어떤 형태를 선호하실까요 — 개별 native 함수들로? 아니면 하나의 "form fill 후처리" 모듈로 묶어서?
3. 받아주실 의향이 있으면 최신 devel 기준으로 이식해서 기능별로 쪼갠 PR로 다시 올리겠습니다. 한 번에 다 내는 것보다 (a) 문단/페이지 정리 (b) 셀 내부 삽입 (c) 목차 순으로 나누는 게 리뷰하기 나을까요?

범위에 맞지 않는다고 하셔도 괜찮습니다 — 포크로 계속 쓰면 되고, 위 2·3번 버그 리포트만 따로 정리해 올리겠습니다.

감사합니다.

[edwardkim]

@yuyu04 님, 제안 감사합니다. 결론부터 — 방향이 rhwp 범위에 맞고, 환영합니다.

왜 맞는가 — 프로젝트 계보

rhwp 의 초기 설계 목표 중 하나가 공공기관 웹 기안 워크플로의 오픈소스 대안이었습니다. 반복 양식 문서를 프로그램으로 정확히 채우는 축은 그 계보의 직계이고, 최근의 일반기안문·간이기안문 표준 서식 자산(#3372), CLI edit fill-fields/set-cell/replace-text 연작, 54쪽 실물 정부 서식 편집 실증이 모두 같은 줄기입니다. "표 구조를 LLM 에 맡기지 않고 결정적 복제로 간다"는 접근도 이 프로젝트의 결정론 지향과 정확히 일치합니다.

질문별 답

1. 범위 — document_core 가 맞는 층입니다. 다만 TOC 2종(rechunkTocTable·syncTocPageNumbers)은 문서 엔진 vs 앱 층 경계 논의가 필요하니 그 조각에서 따로 다루시죠.

2. 형태 — 개별 native 함수를 선호합니다. 기존 edit 계열 규약을 따라 주세요: 연산별 계약 테스트, HWP5/HWPX 저장 왕복 확인, 가능하면 한컴 편집기 열람 확인.

3. 분할 — 제안하신 (a) 문단/페이지 정리 (b) 셀 내부 삽입 (c) 목차 순서에 동의합니다. 각 조각 착수 전에 이슈로 연산 스펙(이름·인자·경계 동작)을 합의하고 가시죠. 4,600커밋 이식은 조각 단위면 충분히 리뷰 가능합니다.

발견 사항 3건 — 먼저 이것부터 부탁드립니다

세 건 모두 값진 리포트입니다. 특히 1번(treatAsChar 저장 유실)은 현행 devel 에서도 실버그로 확인했습니다 — set_table_properties_native 가 attr/common 만 바꾸고, serializer 는 raw_ctrl_data 가 있으면 재사용합니다. 확인 결과를 바탕으로 이슈로 등록해 두겠습니다. upstream 수정 방향은 3곳 동기화보다 raw_ctrl_data 무효화를 권합니다 — #1916 이 raw 부재 시 IR 에서 CommonObjAttr 를 재합성하는 폴백을 이미 갖춰 놨고, 수식이 같은 패턴(clear())을 씁니다. 2·3번도 회귀 테스트와 함께 별도 이슈/PR 로 주시면 감사하겠습니다. 연산 9종보다 이 세 건이 먼저 들어오는 게 모두에게 이익입니다.

[edwardkim]

포크 구현: yuyu04/rhwp f40c12f0 (v0.7.13 기준) 을 참고하여 #3587 이슈를 착수하겠습니다. 현재 rhwp 버전 0.8.6 을 기준으로 구현하신 내용을 참고하여 기초 설계에 반영할 예정입니다.