수납 대사 3채널 — BE 핸드오프

Provider seam

세 repo는 async listIncoming()으로 정규화된 입금 원자를 반환한다. 실제 연동 시 브라우저에서 provider 인증정보를 다루지 말고 Supabase Edge Function 또는 제품 BE 어댑터에서 호출한다.

필수 정규 필드: externalKey, channel, kind, payerName, unitHint, amount, receivedAt, sourceType, eligibleForReceipt, 선택적 contractCode.

수납 원자와 채널 정산 원자

더빌 가상계좌/CMS는 개별 입금 시점에 이미 세대 수납을 만든다. 이후 관리비 계좌에 입금되는 더빌가상*·더빌이체*·더빌카드*·더빌CMS*(또는 TheBill*) 합산액은 sourceType:'channelSettlement', eligibleForReceipt:false인 채널 정산 원자다. 이를 receipt 또는 가수금으로 다시 기록하면 이중 수납이므로 서버에서도 차단해야 한다.

채널 정산 원자는 숨기지 않고 별도 settlement 대사 대상으로 보존한다. 개발팀 구현에서는 더빌 개별 수납 합계·수수료·실입금액의 정산식을 별도 집합으로 구성하고, 세대 수납 원장과 은행 입금 원장의 총액 대사에만 사용한다. 현재 프로토타입의 적요 prefix 규칙은 골드너스 실데이터 기반 참조 규칙이며 운영 구현은 provider 정산 식별자/정산 API를 우선한다.

externalKey + channel에 unique 제약을 두고 수집 재시도와 확정 커밋을 멱등 처리해야 한다. 추천 점수는 설명 가능한 제안이며 서버 권위 귀속값이 아니다. 최종 확정은 기존 수납 트랜잭션과 같은 원자성으로 receipt·FIFO 충당·선수금/가수금을 함께 저장해야 한다.

채널 장애는 서로 전파하지 않는다. 채널별 cursor·최종 성공시각·오류 코드·trace ID를 별도로 저장하며, 부분 성공 응답은 성공 원자를 커밋한 뒤 실패 채널을 재시도 가능 상태로 남긴다. 클라이언트가 eligibleForReceipt=false를 변조하더라도 서버는 provider settlement ID 또는 정산 적요 규칙으로 재분류하여 receipt·가수금 쓰기를 거부해야 한다.

정산 대사 최소 필드는 settlementGross, settlementFee, bankNetAmount, difference, settlementStatus다. 불변식은 settlementGross - settlementFee - bankNetAmount = difference이며, difference=0은 정산 일치를 뜻할 뿐 신규 수납 생성을 허용하지 않는다.

PG 1차 구현은 결제 원자만 포함한다. 더빌·PG의 수수료 차감 정산금 및 D+N 입금 대사는 별도 settlement 테이블/트랙으로 추가한다.