feat(wholesale): 정산 선수금 3카드 · 총 사용 가능 · 선수금 정산 · 입금 취소 #138

[OhChangEun]

무엇

정산 탭에 선수금 축을 넣는다. 2026-09-10에 "서버 데이터가 없다"로 보류했던 #138을 #237 스냅샷 재동기화로 다시 열었다.

1. 선수금 잔액 3카드 — 우측 상단, 입금 등록 위. 총 입금액 · 배분 완료액 · 남은 선수금(강조). GET /receivables/retailers/{id}/prepaid 값 그대로. Figma의 보조 문구(입금 회수·완료율·미정산 건수)는 서버가 안 줘서 안 그린다
2. 입금 폼의 총 사용 가능 = 이번 입금액 + 남은 선수금. 자동 배분·행별 상한·합계 검증이 전부 이 값 기준이다. 예전 "배분 합계가 입금액과 딱 맞아야 정산" 규칙은 없앴다 — 덜 붙인 돈은 선수금으로 남아 카드에 보이고, 옛 선수금을 끌어 쓰면 합계가 입금액을 넘는 게 정상이다
3. 배분 표 열 이름 미수→남은 미수, 배분→이번 배분, 합계행 추가. 남은 미수는 서버 outstandingAmount(출고 미수 − 이미 붙은 배분) 그대로. 출고 여부는 새 shippedAmount로 본다(이행 상태 근사 폐기)
4. 선수금으로 정산 (POST /allocations) — 3카드의 버튼으로 진입. 새 입금 없이 남은 선수금만으로 배분하는 패널. 입금 폼과 같은 배분 표·같은 derive를 쓰고, 남은 선수금이 0이면 버튼이 잠긴다. Idempotency-Key는 입금 등록과 같은 방식
5. 입금 취소 (POST /payments/{id}/void) — 미수원장 입금 줄의 취소 → 사유 필수 다이얼로그. 같은 페이지에 취소 줄이 이미 붙은 입금은 버튼을 안 단다
6. 입금 등록 후엔 원장 잔액과 같은 방식으로 선수금 키도 무효화한다. 결과 문구 꼬리에 응답 prepaidRemaining을 적는다

왜

• 선수금 세 값을 화면에서 더하거나 빼지 않는다. 취소된 입금·취소된 배분을 빼는 규칙이 서버에 있어 화면이 다시 세면 그 순간 갈린다. 입금 응답의 prepaidRemaining으로 캐시를 직접 고치지 않는 것도 같은 이유(totalPaid·totalAllocated가 응답에 없다)
• 선수금 쿼리는 3카드 패널만 들고 남은 선수금을 부모에게 올린다. 입금 폼이 같은 키를 따로 보면 실패했을 때 다시 시도가 둘이 된다(확정 주문과 같은 흐름)
• 입금 취소는 되돌릴 수 없어(스펙) 계좌 삭제처럼 다이얼로그가 한 번 막고, 빨강은 그 마지막 확인에만 쓴다

확인

• pnpm typecheck && pnpm lint && pnpm build 통과
• dev 서버(raon · moodon · cottonclub) 읽기만 확인: prepaid 응답 모양, 404 RESOURCE_NOT_FOUND, outstandingAmount가 출고 기준으로 내려오는 것(출고 전 주문 0, moodon 7007은 shipped 46,000 = outstanding 46,000). 쓰기 호출(payments·allocations·void)은 하지 않았다 — dev 데이터를 안 바꿨다
• 선수금이 0이 아닌 거래처가 dev에 없어 3카드가 값을 채운 화면과 선수금 정산·입금 취소의 왕복은 실서버로 못 봤다. 스펙 description 기준으로 짰다
• 브라우저 확인은 못 했다 — 이 세션의 크롬 탭 그룹을 다른 작업이 같이 쓰고 있어 탭이 닫혔다. 머지 전에 한 번 눌러 볼 것: 거래처 펼침 → 3카드, 입금액 입력 → 총 사용 가능·합계행, 미수원장 → 입금 줄 취소

범위에서 뺀 것

• 배분 취소(POST /allocations/{id}/cancel) — 화면에 배분 id를 보여 주는 자리가 없다. 억지로 만들지 않고 뺐다. 필요하면 별도 이슈
• 계좌 등록·관리 화면(feat(wholesale): 정산 계좌 패널 사양 확정 — 진입 위치·카드/표·은행 선택·성공 문구 #208 PM 대기). BankAccountPanel은 손대지 않았다
• Figma 3카드의 보조 문구(입금 회수 12회 · 완료율 · 미정산 8건) — 서버에 없다. 더미를 두지 않았다

800줄 초과 사유와 파일 구성

정산 화면 한 장이다. 3카드·총 사용 가능·선수금 정산·입금 취소가 같은 derive(배분 표 규칙)와 같은 결과 문구(notice)를 나눠 써서 나누면 중간 상태가 어색하다. 커밋은 셋으로 나눴다(선수금 조회·3카드 / 사용 가능액·배분 표 / 선수금 정산·입금 취소).

파일	역할
types.ts	PrepaidSummary·AllocationCreateRequest·PaymentVoid* wire 별칭, PrepaidView·AllocationDraft, LedgerRowView.paymentId/voidable, SettlementNotice.kind
constants.ts	오류 문구 갱신(ALLOCATION_EXCEEDS_PAYMENT·_PREPAID), 입금 취소 문구·사유 상한
derive.ts	availableTotal, 배분 표 상한을 사용 가능액으로, toPrepaidView, hasShipped(shippedAmount), 원장 voidable, 선수금 정산·입금 취소 요청 변환, noticeText 3종
api/keys.ts · api/queries.ts	prepaid(retailerId) 키·경로·usePrepaidQuery, allocations·paymentVoid 경로
api/mutations.ts	입금 후 선수금 무효화, useCreateAllocationMutation, useVoidPaymentMutation
components/PrepaidSummaryPanel.tsx (신규)	3카드 + 선수금으로 정산 진입
components/PrepaidAllocationPanel.tsx (신규)	새 입금 없이 배분만 하는 패널
components/PaymentVoidDialog.tsx (신규)	사유 입력 + 되돌릴 수 없음 확인
components/AllocationTable.tsx	열 이름·합계행
components/DepositFormPanel.tsx	총 사용 가능 표시, 배분 상한·정산 조건
components/ReceivableLedgerTable.tsx · SettlementSegmentView.tsx	입금 줄 취소 버튼·다이얼로그
components/SettlementListView.tsx	3카드·선수금 정산 모드·취소 결과 조립
shared/api/errorCodes.ts	ALLOCATION_EXCEEDS_PREPAID

Closes #138

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ondo-wholesale	Ready	Preview	Sep 18, 2026 4:14am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
ondo-retail	Skipped		Sep 18, 2026 4:14am UTC

[coderabbitai]

Warning

Review limit reached

Next included review available in 31 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 0c536b2f-4c60-4811-bcad-96f530e68dc1

📥 Commits

Reviewing files that changed from the base of the PR and between 5528968 and 0c59e42.

📒 Files selected for processing (15)

• apps/wholesale/src/features/settlement/api/keys.ts
• apps/wholesale/src/features/settlement/api/mutations.ts
• apps/wholesale/src/features/settlement/api/queries.ts
• apps/wholesale/src/features/settlement/components/AllocationTable.tsx
• apps/wholesale/src/features/settlement/components/DepositFormPanel.tsx
• apps/wholesale/src/features/settlement/components/PaymentVoidDialog.tsx
• apps/wholesale/src/features/settlement/components/PrepaidAllocationPanel.tsx
• apps/wholesale/src/features/settlement/components/PrepaidSummaryPanel.tsx
• apps/wholesale/src/features/settlement/components/ReceivableLedgerTable.tsx
• apps/wholesale/src/features/settlement/components/SettlementListView.tsx
• apps/wholesale/src/features/settlement/components/SettlementSegmentView.tsx
• apps/wholesale/src/features/settlement/constants.ts
• apps/wholesale/src/features/settlement/derive.ts
• apps/wholesale/src/features/settlement/types.ts
• apps/wholesale/src/shared/api/errorCodes.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}