부과요약서 집계 계약 — BE 참고

관리비 상용화 보고서 확충 트랙(2026-07-11, B-2) — 부과요약서(신규). 설계 정본: docs/superpowers/specs/2026-07-11-period-tag-minors-reports-xlsx-design.md §B-2. as-built 정본 소스: src/composables/useChargeSummary.js.

---

1. 개요

부과요약서는 총괄표(useChargeSummaryTable)가 이미 산출한 K-apt 항목별 합계(kapt())와 열 합계(columnTotals())를 항목 축 원페이저로 재투영하고, 항목별 구성비(표시용 비율)를 더해 보여주는 read-only 문서다. 재계산은 일절 하지 않는다 — 신규 산식은 구성비 하나뿐이며 그마저도 표시 전용(회계 계산에 관여하지 않음).

2. 데이터 정본 — useChargeSummary

src/composables/useChargeSummary() → { summaryRows, summaryTotals, formatAmount }. useChargeSummaryTable()(columnTotals·kapt·formatAmount) 하나만 소비한다 — 총괄표(report-summary-table.md)의 K-apt 뷰 계약을 그대로 재사용.

2-1. summaryRows() — kapt() 항목행 + 구성비

function summaryRows() {
  const k = kapt();
  const denominator = columnTotals().세전합계;
  return k.rows.map((r) => ({ ...r, share: denominator > 0 ? r.total / denominator : 0 }));
}

• k.rows({ chargeCode, name, total, unitPrice }, report-summary-table.md §2-5)를 그대로 스프레드하고 share 필드 하나만 추가한다.
• share = total / 세전합계(분모 0이면 0 — 0나누기 방지). 표시 전용 비율이지 청구·배분에 관여하는 산식이 아니다 — 원 단위 반올림 잔차가 있어도 Σshare가 정확히 1이 안 될 수 있으나(부동소수점 합산), 이는 회계 오류가 아니라 표시 근사치의 정상 특성이다.

2-2. summaryTotals()

function summaryTotals() {
  const totals = columnTotals();
  const k = kapt();
  return { ...totals, totalArea: k.totalArea, vatPerArea: k.vat.unitPrice };
}

columnTotals()(세전합계·부가세·당월합계·미납원금·미납연체금·선수금·청구액 — 총괄표 §2-4와 동형)를 그대로 스프레드하고, K-apt 전용 필드(totalArea·vatPerArea)만 kapt()에서 추가로 가져온다.

3. 불변식 4종 (vitest, src/composables/__tests__/useChargeSummary.spec.js)

#	불변식	지키는 회계 정합
①	summaryRows().length === kapt().rows.length · 각 행 total/unitPrice 동치	부과요약서 항목행이 K-apt 뷰(총괄표)와 항등 재투영 — 별도 계산 경로 아님
②	Σrow.share ≈ 1(세전합계 > 0일 때, toBeCloseTo(1, 6))	구성비 표시가 전체를 빠짐없이 나눈다(반올림 근사 허용)
③	Σrow.total === columnTotals().세전합계	부과요약서 항목 합계가 총괄표 세전합계와 항등
④	summaryTotals().{세전합계,부가세,청구액} === columnTotals()의 동일 필드	요약 합계 블록이 총괄표와 동일 소스에서 파생 — drift 불가

as-built 진단(2026-07-11): 4개 불변식 모두 최초 구현에서 통과 — kapt()/columnTotals()를 그대로 스프레드·재사용하는 얇은 레이어라 새 계산 경로가 없기 때문.

4. 스코프 제외

• 조정명세서·대장: 산출표(report-calculation-table.md §5)와 동일 사유로 스코프 밖.
• 기간범위·층/블록 축: 총괄표와 동일한 1차 제한 — 이번 차수·단지 전체 기준만.
• prior-only 세대: 부과요약서는 kapt()(총괄표 파생)를 재사용하므로, 총괄표와 동일하게 당기 부과 세대만 대상이다(prior-only 미수 세대는 이 문서에도 반영되지 않음 — report-summary-table.md §4 스코프 결정과 동일 근거).

5. 확장 포인트

• report-calculation-table.md §6과 동일 — 조정명세서·기간범위 확장은 useCharges/useChargeSummaryTable 자체의 차수별 스냅샷 구조가 선행돼야 한다.
• 구성비 시각화: 현재는 숫자(%)만 표시한다. 막대·도넛 차트 등 시각화가 필요해지면 share 필드를 그대로 소비하면 된다(추가 계산 불요).