계정 허브 (세대×기간) — BE 참고 매뉴얼

대상: BE 개발자/AI. 이 페이지는 새 데이터 모델을 만들지 않는다 — 기존 수납 상세 모델(useCollectingDetail)을 세대×기간 단위로 재조망하는 read/action 합성일 뿐. 신규 계약은 P2(고지서)에서 발생.

개념 모델 — 문서 vs 원장 (정본)

빌링 정보는 두 부류로 갈린다. 허브 탭이 이 분리를 그대로 따른다.

부류	탭	성격	묶이는 단위
문서(static)	부과 · 청구(고지서)	발행 시점에 동결된 스냅샷	세대 × 그 청구월
원장(dynamic)	정산 · 연체 · 이월 · 조정	as-of 계속 변함	그 세대 계정의 현재 상태

핵심 불변식(BE 구현 시 강제):

1. 고지서(청구 문서)는 불변. 이미 발행한 고지서를 mutate하지 않는다. 연체료·이월이 반영된 고지서가 필요하면 현재 원장 상태로 새 버전(v2…)을 발행한다(재발행 = append, not update). → P2 useInvoiceDocuments.
2. 수납(receipt) ≠ 청구액. 수납은 "돈 받은 기록(credit event)". 라이브 "납부하실 금액"은 원장에서 계산되는 별개 값.
3. 청구액 체인 (useCollectingDetail.detailFor):

   부과액(매출+비매출, 당기 billed)
     + 이월미납(forwarded principal) + 연체료(lateFee)
     = 받을금액(outstanding)
     − 선수금 잔액(advanceBalance)
     = 청구액(payable = max(0, outstanding − advanceBalance))

4. 정산대기: 당기 부과(kind==='current') 없이 이월 미납만 있는 상태 → billingStatus='정산대기'. 미납 원금에 연체료만 가산.

탭별 데이터 계약 (read)

전부 detailFor('unit', unitKey, asOf) 단일 소스에서 파생. 신규 API 없음.

탭	소스 필드	비고
부과	periods.find(kind==='current').billedByComponent	성격×세금 구성요소별 부과액(period-locked). 없으면 정산대기.
청구	— (P2)	useInvoiceDocuments 스냅샷 이력. 불변식 1.
정산	periods/totals/advance/receipts/adjustments 전부	수납 처리(action) 포함 — 아래.
연체	periods[].lateFee.breakdown[] {from,to,days,annualRate,balance,fee}	구간 분절. 발생주의 E3 / 현금주의 E4 split는 lateFeePolicy.recognitionBasis.
이월	periods.filter(kind==='forwarded')	전기 미납 유입. 차기 이월 공식화는 forwarding 페이지 소관.
조정	detail.adjustments[] {id,kind,amount,breakdown,status,reason,at}	kind ∈ {discount, lateFeeWaiver, writeOff}.

액션 (정산 탭) — 기존 수납 경로와 동일

허브는 수납 시트와 동일 핸들러(useCollectingActions)를 호출한다. BE 계약 변경 없음.

• 수납: recordReceipt({contractCode, memberCode, amount, method, receivedAt, identified})
• 조정: recordAdjustment({contractCode, kind, amount, breakdown, reason, at}) — discount(매출에누리)/lateFeeWaiver(연체료수입 0922 차감)/writeOff(대손, 승인대기).
• 수납취소: cancelReceipt(id) (+옵션 정정 recordReceipt).
• 불변식: amount === applied + toAdvance + toSuspense; 모든 전표 차변합===대변합(useBillingJournal).
• 충당순서(법정 연체료→원금, 차수 FIFO/LIFO, 원금 내부 버킷)는 lateFeePolicy.collectionPolicy — 허브가 별도로 손대지 않음.

단위(세대) 귀속

• 허브 키 = unitCode (axis 'unit'). toContract('unit', unitCode) = 그 호의 첫 배분라인 계약(useCollectingDetail §toContract). 선수금/조정은 계약 단위 귀속.
• P1 진입은 unit 리스트 한정. contract/member 귀속에서의 진입은 unit 해석이 선행돼야 함(후속).

엣지/후속

• 기간 셀렉터(과거 청구월) → asOf/period 파라미터화.
• 고지서 발행/재발행 분개·번호 채번·인쇄 스냅샷(P2). PROCESS-RECEIPTS-CANON-2026-06-19.md에 "고지서 불변·재발행=append" 불변식 추가 예정.
• 정산대기 세대의 연체료만 가산 흐름은 useForwarding/useLateFee 기존 규칙 그대로.