Leyve Docs

다크모드

빌링 제품군 capability vocabulary — BE 참고 ​

목적 ​

판매·매출채권, 관리비관리, 임대차관리가 같은 청구·수납 생애주기를 설명할 수 있게 하되 각 도메인 원장의 소유권은 분리한다. Billing Core는 제품이 아니며 별도 API 권한·entitlement·공통 write model을 소유하지 않는다. 정본 결정은 docs/decisions/BILLING-FAMILY-BOUNDED-CONTEXTS-2026-07-19.md, 실행 가능한 FE 계약은 src/composables/billingCapabilityVocabulary.js다.

데이터·API 영향 ​

초기 vocabulary slice 자체는 DB를 추가하지 않았고, 후속 임대 차임 수납 Wave가 lease owner 행을 구현했다. 다음 owner는 상품별로 분리된다.

선택 전달은 기존 platform_integration_events와 platform_integration_deliveries를 사용한다. 연결 불가 시 delivery 자체가 없을 수 있고, 생성된 delivery 상태는 pending | processing | failed | delivered | dead다.

상품부과 owner미수·수납 owner
service-chargeworkflow, charging confirmation, invoice versionservice_charge_receivable_installments/receipts/allocations/reversals
leaselease_contracts/terms/rent_chargeslease_rent_receivable_installments/receipts/allocations/reversals

임대 보증금 lease_deposit_ledger_entries는 보증금 부채의 증감 원장이다. 차임 채권의 installment·receipt allocation으로 해석하거나 통합 미수 projection에 넣지 않는다. 차임 수납은 별도 임대차관리 소유 원장을 사용한다.

2026-07-19 표시 수렴 Wave에서 관리비관리와 임대차관리의 목록·상세가 billingReceivableStatusMeta를 직접 소비한다. 이는 서버 상태를 변경하거나 공통 write model을 도입한 것이 아니다. 각 RPC가 반환한 current|overdue|paid와 상품별 명령 gate가 계속 정본이다.

판매·매출채권 owner는 실제 채권 원장과 RPC를 구현할 때 추가한다. 과거 contract_billing_* 스키마는 폐기된 프로토타입 이력이며 신규 API나 도메인 모델의 정본으로 재사용하지 않는다.

공통 상태 ​

미수 read model의 공통 표시 상태는 다음 세 개다.

  • current: 잔액이 있고 as-of에 납기가 지나지 않음
  • overdue: 잔액이 있고 dueOn < asOf
  • paid: 유효 수납·반전을 반영한 잔액이 0 이하

서버 응답의 유효 상태가 정본이다. FE fallback은 provider가 상태를 생략한 경우에만 사용한다. 각 제품의 KST as-of, superseded invoice 제외, append-only reversal 규칙은 기존 RPC가 계속 소유한다.

공통 오류 category ​

classifyBillingCapabilityError는 상품 오류 문자열을 unavailable, entitlement, permission, conflict, not-found, already-applied, limit, immutable, invalid, unknown으로 분류한다. 이는 UI의 재시도·관측 category일 뿐이다.

  • 상품별 오류 코드를 공통 코드로 변환해 서버에 다시 보내지 않는다.
  • 공통 category로 RLS나 명령 권한을 결정하지 않는다.
  • 사용자 메시지는 serviceChargeCollectionErrorMessage, leaseRentCollectionErrorMessage 등 상품 adapter가 계속 소유한다.

검증 ​

src/composables/__tests__/billingCapabilityVocabulary.spec.js가 owner 분리, 보증금/차임 경계, deep-freeze, 상태 fallback과 오류 분류를 고정한다. 각 repo 테스트가 정규화 회귀를 검증한다.