Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락

[planet6897]

요약

• 표 페이지 분할 알고리즘이 rowspan>1 셀의 시각적 점유 영역을 분할 단위에 반영하도록 개선
• MeasuredTable 에 rowspan 묶음 블록 캐시(row_block_start/end) 와 헬퍼(row_block_for, snap_to_block_boundary) 추가
• pagination/engine.rs::split_table_rows 와 typeset.rs::paginate_table (실제 SVG 내보내기 경로) 양쪽에 블록 단위 분할 정책 적용

closes #398

배경

samples/2025년 기부·답례품 실적 지자체 보고서_양식.hwpx 1쪽 하단에 다음 표(pi=22, 3×3, 제목 "<2025년 기부·답례품 실적 분석보고서 요약>") 의 첫 행이 잘려 들어가고 rowspan=2 제목 셀의 텍스트가 본문 영역 끝에 겹쳐서 그려짐. PDF 원본은 표 전체를 2쪽으로 미룸.

근본 원인

분할 단위를 개별 행으로 산정하면서 rowspan>1 셀의 시각적 점유 영역을 누락.

• mt.row_heights[r] 산출 시 cell.row_span == 1 셀만 집계 (height_measurer.rs:466)
• split_table_rows 의 first_row_h = mt.row_heights[0] 가 17.27px (rs=1 셀만), 실제 첫 분할 단위는 행 0+1 묶음(rowspan=2 셀 점유) = 35.4px
• 페이지 1 잔여 19px ≥ 17.27px → 행 0 배치 결정 → 35.4px 셀이 시각적으로 잘림

해결책

분할 가능 단위를 "행" → "rowspan 묶음 블록"으로 확장.

데이터 구조

MeasuredTable 에 사전 계산된 블록 경계 캐시:

• row_block_start[r]: r 행을 포함하는 모든 rowspan 셀의 최소 시작 행
• row_block_end[r]: r 행을 포함하는 모든 rowspan 셀의 최대 종료 행 (exclusive)

compute_row_blocks(table, row_count) 헬퍼가 모든 셀의 (row, row_span) 을 검사하여 전이 폐포로 통합. mt.cells (page_break == CellBreak 일 때만 채움) 가 아닌 모델의 table.cells 에서 직접 계산하여 모든 page_break 모드에 일관 적용.

신규 메서드:

• MeasuredTable::row_block_for(row) -> (start, end_exclusive, height)
• MeasuredTable::snap_to_block_boundary(end_row) -> usize

분할 호출부 변경

Pre-loop 분할 판정: first_row_h = mt.row_heights[0] → first_block_h = mt.row_block_for(0).2.

Loop body:

• find_break_row 결과에 snap_to_block_boundary 적용 → rowspan 묶음 중간 분할 차단
• 인트라-로우 분할 / 강제 split 모두 단일 행 블록(block_end == block_start + 1) 에서만 시도
• 다중 행 블록이 들어가지 않으면 end_row = cur_b_end (블록 전체 한 단위로 배치)

동일 패턴을 pagination/engine.rs 와 typeset.rs 양쪽에 적용 (분할 로직 중복 — 향후 통합 고려, 별도 타스크).

검증

본 샘플 회귀 (Task #398)

항목	수정 전	수정 후
페이지 1 마지막 항목	PartialTable pi=22 ci=0 rows=0..1 cont=false 3x3	pi=21 (빈) (표 사라짐)
페이지 2 첫 항목	PartialTable pi=22 ci=0 rows=1..3 cont=true	Table pi=22 ci=0 3x3 635.0x924.5px (표 전체)
페이지 1 SVG 제목 글자 (분/석/답/례)	본문 영역 끝에 겹쳐 그려짐	페이지 1 부재, 페이지 2 정상

테스트

스위트	결과
cargo test --lib	1023 passed; 0 failed
cargo test --test svg_snapshot (골든 6건)	6 passed
cargo test --tests (전체 통합)	1073 passed; 0 failed
cargo build --release	성공
samples/table-vpos-01.hwpx 회귀	5쪽 정상
samples/표-텍스트.hwpx 회귀	1쪽 정상

신규 단위 테스트 (7건)

height_measurer.rs::tests:

• test_compute_row_blocks_all_single — rowspan 모두 1
• test_compute_row_blocks_rs2_at_row0 — 행 0에 rs=2 셀
• test_compute_row_blocks_overlapping — 겹치는 rowspan 통합
• test_compute_row_blocks_disjoint — 비인접 rowspan 별개 블록
• test_row_block_for_basic — 같은 블록 내 모든 행이 동일 (start, end, height)
• test_row_block_for_empty_metadata — 빈 vec → 단일 행 폴백
• test_snap_to_block_boundary — 블록 중간 → 시작으로 후퇴

의도된 동작 변경

다른 문서에서 rowspan>1 셀이 페이지 경계에 걸리는 경우, 표가 통째로 다음 페이지로 밀려나면서 빈 공간이 더 커질 수 있다. 이는 한글 호환 동작이며 의도된 변경.

변경 파일

파일	변경
src/renderer/height_measurer.rs	MeasuredTable.row_block_start/end + compute_row_blocks + row_block_for/snap_to_block_boundary + 단위 테스트 7건
src/renderer/pagination/engine.rs::split_table_rows	pre-loop first_block_h, snap, 단일성 가드
src/renderer/typeset.rs::paginate_table	동일 패턴 적용 (실제 내보내기 경로)
samples/2025년 기부·답례품 실적 지자체 보고서_양식.{hwpx,pdf}	신규 (회귀 검증 자료)
mydocs/plans/task_m100_398{,_impl}.md, mydocs/working/task_m100_398_stage{1,2}.md, mydocs/report/task_m100_398_report.md, mydocs/orders/20260428.md	작업 문서

Test plan

• cargo test --lib 통과 (1023)
• cargo test --tests 통과 (1073)
• cargo build --release 성공
• 본 샘플 1쪽에서 표 분할 사라지고 2쪽에 표 전체 시작
• 페이지 1 SVG에 제목 텍스트(분/석/답/례) 부재
• 다른 표 샘플(table-vpos-01, 표-텍스트) 회귀 없음

## 메타

- **Base 브랜치**: `devel`
- **Head 브랜치**: `local/task398` (로컬) 또는 push 시 `devel`로 직접 merge
- **연결 이슈**: closes #398
- **커밋 (3개)**:
  - `4454573` Stage 1: MeasuredTable rowspan 묶음 메타데이터 추가
  - `d570ab7` Stage 2: 분할 호출부에 rowspan 블록 정책 적용
  - `50f4164` Stage 3: 회귀 검증 통과 + 최종 보고서

[edwardkim]

PR 검토 결과 안내드립니다. 본 PR 의 결함 분석 (rowspan>1 셀의 시각적 점유 영역이 분할 단위 산정에서 누락) + 정정 방향 (rowspan 묶음 단위 분할) 자체는 합리적입니다. CLAUDE.md 절차 준수 (수행/구현 계획서 + Stage 보고서 + 최종 보고서) 도 양호합니다. CI 통과 + cherry-pick 후 cargo test --lib 1038 passed 검증도 통과했습니다.

다만 메인테이너 환경의 회귀 검증 샘플에서 회귀가 발견되어 재정정이 필요합니다.

회귀 발견 — `samples/synam-001.hwp` 5 페이지

본 PR cherry-pick 후 시각 비교 결과:

항목	devel (PR 미적용)	PR #401 적용 후
전체 페이지 수	35	37 (+2 증가)
페이지 5 의 PartialTable pi=69	rows=0..5 (5 행 배치)	rows=0..2 (2 행만)
페이지 5 SVG 크기	333 KB (정상)	101 KB (대폭 축소)

회귀 원인

`pi=69` 표 (8행×3열) 의 셀[4]:

```
셀[4] r=2,c=0 rs=5,cs=1 h=282 ... text="총자산"
```

이 셀은 rs=5 — 행 2 부터 5 행을 점유하는 큰 rowspan 셀.

본 PR 의 `compute_row_blocks` 가 이 셀을 보고 행 2~6 을 한 블록 으로 묶습니다. 결과:

• devel: 행 0,1 (제목 + 소득 행) 까지 페이지 5 에 들어감 → 행 2~5 까지 분할 가능 → rows=0..5
• PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401: 행 2~6 한 블록 = 너무 큰 블록 → 페이지 5 잔여 공간에 안 들어감 → 행 0,1 까지만 → rows=0..2

본 PR 의 정책 (rowspan 묶음 단위 분할) 이 너무 보수적:

• 큰 rowspan 셀 (rs=5 등) 에 대한 별도 가드 없음
• 한컴은 큰 rowspan 셀이 페이지에 안 들어가면 셀 내부 분할 을 허용하는데, 본 PR 은 블록 전체를 다음 페이지로 미룸

회귀 정황

• 해당 회귀 검증 샘플 (`synam-001.hwp`) 은 메인테이너 (작업지시자) 가 보유한 샘플이었으나 git 미추가 상태였습니다 — 작성자가 본 샘플을 가지지 못해 회귀 검증 못한 정황입니다
• 본 댓글과 함께 `samples/synam-001.hwp` 를 devel 에 추가했습니다 (commit `b1c97fe`)
• rebase / fetch 후 본 샘플로 회귀 검증 가능합니다

재정정 방향 제안

큰 rowspan 셀에 대한 보강이 필요합니다. 가능 방향:

옵션 1. rowspan 블록 max_height 가드

블록 높이가 페이지 본문 영역의 일정 비율 (예: 50%) 을 넘으면 블록 분할 허용 — 셀 내부 분할로 fallback.

옵션 2. 첫 페이지 잔여 공간 우선 활용

블록이 한 페이지에 안 들어가도 첫 페이지에 일정 행 (블록 시작 행 + n 행) 까지는 배치하고, 나머지는 다음 페이지에서 이어가는 형태 (현재 인트라-로우 분할과 비슷).

옵션 3. 블록 단위 분할은 작은 블록만

특정 임계 (예: 블록 행 수 ≤ 3) 이하만 묶음 단위 분할, 그 외는 기존 행 단위 분할 유지.

작성자 환경에서 `samples/synam-001.hwp` 5 페이지 + 본 PR 의 본 샘플 (`samples/2025년 기부·답례품 실적 지자체 보고서_양식.hwpx`) 1 페이지 양쪽 모두 회귀 없이 정정 가능한 방향을 검토 부탁드립니다.

처리 절차

1. 본 PR 은 OPEN 유지합니다
2. `devel` 기반 rebase + 위 회귀 정정 + `samples/synam-001.hwp` 회귀 점검 후 force-push 부탁드립니다
3. 재제출 시 다시 검토 후 머지 진행하겠습니다

정리

항목	상태
코드 자체	✅ 합리적 (의도 정확)
dry-run merge + cargo test	✅ 1038 passed
`samples/2025년 기부·답례품...hwpx` 정정	✅ 통과
`samples/synam-001.hwp` 5 페이지	❌ 회귀 (35→37 페이지)
재정정 + 회귀 검증	⚠️ 필요

좋은 기여 감사합니다. 큰 rowspan 셀 정황까지 다루는 정정 후 재제출 부탁드립니다.

[planet6897]

Task #398 v2 — synam-001.hwp 회귀 정정 최종 보고서

배경

PR #401 (Task #398) merge 검토 중 메인테이너가 samples/synam-001.hwp 5 페이지에서 회귀 발견:

• devel: 35 페이지 (PDF 동일)
• PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401: 37 페이지 (+2), 페이지 5 표 행 수 5→2 축소, SVG 크기 333KB→101KB

원인: 본 PR 의 rowspan 묶음 단위 분할 정책이 큰 rowspan 셀 (rs=5, 행 2~6 묶음) 에 대해 별도 가드 없이 블록 전체를 다음 페이지로 미룸. 한컴은 큰 rowspan 셀이 페이지에 안 들어가면 셀 내부 분할을 허용함.

정정 방향

메인테이너 피드백의 옵션 3 (블록 단위 분할은 작은 블록만) 채택. 임계값 = 3 행.

블록 크기	정책
1 행 (rowspan=1)	인트라-로우 콘텐츠 분할 가능 (기존 동작)
2~3 행 (보호 블록)	블록 단위 분할만 허용 (Task #398 v1 동작)
4 행 이상 (큰 rowspan)	행 경계 분할 허용 + 인트라-로우 분할 가능 (devel 동작 복귀, HanCom 호환)

근거:

• 2~3 행 블록: 통상 표 머리/제목 셀로, 분할 시 시각적 결합 손상이 큼 → 보호 필요. (PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 원 회귀 케이스: pi=22 의 rs=2 제목 셀)
• 4 행 이상: 통상 세로 레이블이거나 데이터 컬럼으로, 행 경계 분할이 가독성 저하를 유발하지 않음. (synam-001 의 rs=5 "총자산" 셀)

변경 내역

src/renderer/height_measurer.rs

• pub const BLOCK_UNIT_MAX_ROWS: usize = 3 신규 상수.
• snap_to_block_boundary 가 보호 블록 (size ≤ 3) 에서만 후퇴. 큰 블록은 end_row 그대로 반환.

src/renderer/pagination/engine.rs::split_table_rows

• 사전 판정 (pre-loop) split_unit_h: 보호 블록만 first_block_h, 그 외는 row_heights[0] 사용.
• 루프 내 cur_block_protected / next_block_protected 도입. cur_can_intra_split = (single || !protected) && can_intra_split 로 큰 블록도 인트라-로우 분할 허용.
• approx_end <= cursor_row 분기: 보호 블록만 end_row = cur_b_end (블록 통째 배치).

src/renderer/typeset.rs

• 동일 정책을 병행 코드 경로 (split_table_rows) 에 적용. (이 코드 경로가 본 회귀 샘플의 페이지네이션을 실행함을 디버깅 중 확인.)

검증 결과

항목	결과	비고
cargo test --lib	1023 passed, 0 failed	PR #401 baseline 유지
cargo test --release (전체)	모든 suite passed	회귀 없음
samples/synam-001.hwp 페이지 수	35	devel/PDF 동일 ✅
페이지 5 pi=69 행 분할	rows=0..5 + 4..8	devel 동일 ✅
output/synam-001_005.svg 크기	333,125 bytes	devel 333 KB 동일 ✅
samples/2025년 기부·답례품 실적 지자체 보고서_양식.hwpx	27 페이지, pi=22 페이지 2 시작	PR #401 원 목표 보존 ✅

영향 범위

• 정책 변경은 rowspan 셀이 4 행 이상을 점유하는 경우에만 동작.
• 기존 단위 테스트 (test_snap_to_block_boundary 등) 는 size=2 블록만 사용하므로 영향 없음.
• 기존 샘플 골든 테스트 영향 없음 (전체 1023 lib + 49 integration 테스트 통과).

처리 절차 후속

• PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 force-push 대상 (rebase + 본 정정 + samples/synam-001.hwp 회귀 점검 결과 포함).
• 메인테이너 재검토 후 머지 대기.

[edwardkim]

완료. v2 정정 후 `devel` 에 cherry-pick 으로 머지됨 (commit `10fb5fe`).

이슈 #398 close 됩니다.

머지 commit (작성자 attribution 보존)

• `0c7b6dc` (cherry-pick) — Stage 1: MeasuredTable rowspan 묶음 메타데이터
• `81db203` (cherry-pick) — Stage 2: 분할 호출부 rowspan 블록 정책
• `2851365` (cherry-pick) — Stage 3: 회귀 검증 + 최종 보고서
• `c2944a4` (cherry-pick) — 샘플 PDF 갱신
• `0d7e776` (cherry-pick) — v2: synam-001.hwp 회귀 정정 (큰 rowspan 행 단위 분할 허용)

v2 정정 정책 평가

`BLOCK_UNIT_MAX_ROWS = 3` 임계로 보호 블록 / 큰 rowspan 분리:

• 2~3 행 보호 블록 (제목 셀 등): 블록 단위 분할 (PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 원 목표 보존)
• 4 행 이상 큰 rowspan (세로 레이블 / 데이터 컬럼): 행 단위 분할 + 인트라-로우 분할 (HanCom 호환)

근거 분석 ("보호 블록 vs 큰 rowspan" 의 시각적 결합 손상 차이) 도 정확합니다. 메인테이너 피드백 옵션 3 을 정확히 채택하여 두 샘플 모두 회귀 없이 정정됐습니다.

검증

• `cargo test --lib`: 1044 passed (1037 → +7 신규 Task 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 (2025년 기부·답례품 보고서 양식 1쪽 하단) #398 테스트)
• `cargo test --test svg_snapshot`: 6/6 passed
• `cargo test --test issue_418`: 1/1 passed (Task samples/hwpspec.hwp 20 페이지 이미지 이중 출력 (PR 처리 후 회귀) #418 보존)
• `cargo clippy --lib -- -D warnings`: warning 0건
• WASM 빌드 (Docker): 4,127,757 bytes
• `samples/synam-001.hwp`: 35 페이지 정상 (devel 동일, 회귀 없음 ✅)
• `samples/2025년 기부·답례품 실적 지자체 보고서_양식.hwpx`: 27 페이지, pi=22 페이지 2 시작 (PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 원 목표 보존 ✅)
• 작업지시자 시각 판정 통과

정황 정리

1차 검토에서 발견된 회귀 (메인테이너 보유 `samples/synam-001.hwp` 5 페이지) 를 작성자가 본 저장소에 추가된 샘플 (commit `b1c97fe`) 로 회귀 검증 + 옵션 3 정책 채택해서 정확히 정정한 점 — 외부 컨트리뷰터의 환경 한계 극복의 좋은 사례입니다.

좋은 기여 감사합니다.