Repository navigation
feat: 주간 정산·월 수수료 집계와 판매자 정산 조회 - #586
Conversation
정산이 확정된 주문(픽업 완료·노쇼·구매자 사정 취소의 남은 금액)을 worker가 매주 월요일 05:00(KST)과 부팅 때 지난주(월~일)까지 확정분으로 매장별 정산(PENDING)에 묶는다. 관리자는 은행 앱에서 송금한 뒤 송금 완료로 처리하고 월 수수료를 매장별로 본다. 판매자는 정산 내역과 주문 상세의 수수료율·정산 예정 금액을 본다. 주간 정산 생성은 관리자 디스코드에 주 단위로 한 번 알린다.
변경점
- 주간 정산: SettlementRepository.createWeeklySettlement가 매장마다 별도 tx에서 대상 주문(settlement_finalized_at < 이번 주 월요일 00:00 KST ∧ settlement_id 없음 ∧ 기준액 > 0, raw SQL에 deleted_at 직접)을 id 순 FOR UPDATE로 잡고 다시 고른 뒤, 정산 행·주문 settlement_id·outbox settlement.created를 같은 tx에 남긴다. (store_id, period_start) 정산이 이미 있으면 건너뛰어 재실행이 멱등이고, 그때 남은 주문은 다음 주 정산에 묶인다. 매장은 첫 품목(남은 품목 중 최소 id), 매장명은 가장 최근 주문의 스냅샷
- SettlementScheduler: 월 05:00 KST 크론 + worker 부팅 1회, 역할 게이트(부팅 훅은 전 역할에서 돌아 필수), 겹친 실행 건너뜀, 매장별 실패는 다른 매장을 막지 않고 warn 경보(key order-cron:weekly-settlement)
- 관리자: adminSettlements(status·storeId·periodStart 필터, null = 전체, 계좌 등록 여부), adminSettlement(포함 주문·현재 계좌 원문·송금 계좌 끝 4자리·처리자 라벨), adminMarkSettlementPaid(PENDING → PAID, 그때 매장 정산 계좌를 paid_*에 스냅샷, 감사 SETTLEMENT는 끝 4자리만), adminMonthlyCommissions(확정 시각의 KST 월로 매장별 건수·기준액·수수료)
- 판매자: sellerSettlements(내 매장, 키셋)·sellerSettlement(포함 주문·송금 계좌 끝 4자리)
- 주문 상세: SellerOrderDetail·AdminOrderDetail에 commissionRateBps·expectedPayoutAmount·settlementBaseAmount·commissionAmount, 관리자는 settlementFinalizedAt·settlementId도. 정산 예정 금액은 확정 뒤 실제 지급액, 확정 전 결제액 − 수수료(원 미만 버림), 미입금 null, 확정 없이 취소된 주문 0
- adminTaskCounts.pendingSettlements(환불 대기 두 필드와 함께), OrderAdminAlertConsumer가 settlement.created를 info·key settlement-week:{periodStart}·/tasks/settlements?periodStart= 링크로 보낸다
- 오류: SETTLEMENT_NOT_FOUND(404)·SETTLEMENT_ALREADY_PAID(409)·SETTLEMENT_ACCOUNT_REQUIRED(400). SDL SettlementStatusType·SettlementOrder·SettlementPaidAccount, kst-time에 kstWeekStart·formatDateOnly
- 게이트: ADMIN_QUERY_COUNT 20 → 22(필수 형식 입력 month는 필드 이름 최소값 표로 유효값), roles-coverage 판매자 63 → 65·관리자 75 → 79, enum-sdl-sync에 SettlementStatus. 팩토리 createFinalizedOrder·createSettlement
테스트
- 주간 정산 14건(real DB): 일 23:59:59.999 포함·월 00:00 다음 주, 실행 시각 일 23:59:59.999면 전주, 재실행 멱등, 같은 주 정산이 있으면 늦은 주문은 다음 주로, 묵은 주문, 미확정·기준액 0·이미 정산·주문 삭제·품목 전부 삭제 제외, 적재 뒤 tx 실패 시 정산·연결·이벤트 모두 없음, 매장별 실패 격리, 후보 조회 실패 경보, 겹친 실행, api·ws 부팅·크론 미실행
- 관리자 정산 23건: 목록 커서·계좌 등록 여부, 필터 AND·null = 전체, 형식 오류, 송금 완료 스냅샷·감사·이후 계좌 변경, 이미 송금 409·동시 2회, 계좌 미등록, 감사 실패 롤백, 월 경계(10/31 23:59:59.999·11/1 00:00·11/30 23:59:59.999·12/1 00:00)·삭제 제외·최근 매장명
- 판매자 정산 3건, 정산 예정 금액 표 7건, 주문 상세 2건, 경보 key·링크·주 1회 3건, 이벤트 9건, kstWeekStart 4건·formatDateOnly 1건, 리졸버 1건
- 반증: tx 밖 적재·경계 <=·부팅 역할 게이트 제거·판매자 매장 범위 제거가 각각 해당 테스트를 실패시키는 것을 확인하고 되돌렸다
- 무엇·왜 - 월 집계 매장명은 SDL 설명대로 '그 달 가장 최근 확정 주문의 스냅샷'이어야 하는데, 윈도 정렬이 주문 id라 먼저 생성되고 늦게 확정된 주문의 이름을 놓쳤다. - 변경점 - monthlyCommissions의 FIRST_VALUE 정렬을 settlement_finalized_at DESC, id DESC로 바꿈(같은 시각이면 최근 주문) - 테스트 - 생성 순서와 확정 순서가 엇갈린 같은 매장 주문 2건에서 늦게 확정된 주문의 이름이 나오는지 확인. id 정렬로 되돌리면 실패 - 같은 주 정산이 이미 있어 건너뛸 때·재실행 때 경보가 나가지 않는지 단언 추가. 기존 정산 가드를 빼면 실패
플랜 7절 크론 공통 규칙(후보 id만 고른 뒤 배치 100, 상한 1000)을 SettlementScheduler에도 적용한다. 이전에는 후보 매장을 한 번에 전부 읽었다. 상한에 걸려 남은 매장은 다음 실행(부팅 1회·다음 주 크론)에서 정산되고, 정산 생성은 (store_id, period_start) 기준으로 멱등(같은 기간 정산이 있으면 건너뜀 + uk_settlement_store_period)이라 재실행이 안전하다. 다음 주 크론까지 밀리면 그 매장의 남은 주문은 다음 주 정산에 함께 묶인다(묵은 주문). 변경점 - SettlementRepository.findUnsettledStoreIds: (before, afterStoreId, limit) 키셋 한 페이지(store_id 오름차순, LIMIT) - SettlementScheduler: SETTLEMENT_BATCH_SIZE 100·SETTLEMENT_MAX_PER_RUN 1000. 후보를 store_id 키셋으로 넘기며 매장마다 기존 별도 tx(FOR UPDATE → 재검사 → 정산 생성)를 연다. 실패한 매장은 키셋이 지나가 같은 실행에서 다시 잡지 않는다 - 상한에 닿으면 남은 매장이 있는지 1곳만 더 보고, 있으면 warn 로그(경보 아님)로 다음 매장 id를 남긴다 - settleLastWeek(limits)는 테스트만 작은 값을 넘긴다. 크론·부팅은 기본값(100·1000) 테스트 - 배치 경계 2건(real DB, 운영 값): 후보 100곳·101곳이 100곳씩 두 쪽으로 나뉘고(두 번째 쪽 afterStoreId = 100번째 매장) 모두 정산, 경고 없음 - 운영 상한 1건: 배치 100·상한 1000 단언, 후보 1050곳에서 1000곳만 처리하고 남은 매장 확인 1회와 경고(조회·생성은 stub) - 상한 2건(real DB, 배치 2·상한 5): 7곳 중 id 순 5곳만 정산·경고·경보 없음, 다음 실행에서 남은 2곳을 같은 주로 정산(정산·이벤트 7건). 후보가 상한과 같으면 경고 없음 - 키셋 1건(real DB): 주문 id 순과 어긋난 매장 id 오름차순, 실패한 첫 매장은 같은 실행에서 다시 잡지 않음 - 반증: 상한 가드 제거·SQL LIMIT 제거·스케줄러 배치 제거·키셋 조건 제거·경고 제거가 각각 위 테스트를 실패시키는 것을 확인하고 되돌렸다
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the
|
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
🧹 knip — dead-code 리포트전체 리포트
|
🩺 NestJS Doctor — 90/100 (Excellent)진단 539건 (error 14).
architecture / security 상위 항목
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 71a3bdaebf
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| """ | ||
| 수수료 기준액 합계(원). | ||
| """ | ||
| settlementBaseAmount: Int! |
There was a problem hiding this comment.
Use a wider scalar for monthly monetary totals
When the platform-wide monthly settlement base exceeds 2,147,483,647 won, adminMonthlyCommissions cannot serialize this field because GraphQL Int is signed 32-bit. For example, 21,475 finalized orders at 100,000 won each exceed that limit even though every individual order and per-store settlement can remain within its limits. toAdminMonthlyCommissionReport sums all stores without imposing this bound, so requesting this non-null field causes the entire report to fail instead of returning the monthly figures. Use a monetary scalar capable of representing aggregate totals, and apply it consistently to the other monthly monetary fields.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
미반영(기록): 유효하나 플랫폼 월 합계가 약 21억 원을 넘어야 생기는 한계라 현재 규모(운영 주문 0건) 밖이고, 금액 합계용 스칼라 도입은 SDL·관리자 FE에 걸친 새 장치. 후속 #587.
Coverage report
Show new covered files 🐣
Test suite run success6646 tests passing in 444 suites. Report generated by 🧪jest coverage report action from 71a3bda |
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
개요
정산이 확정된 주문을 매주 매장별 정산으로 묶고, 관리자가 송금 뒤 '송금 완료'로 닫으며, 월 수수료를 매장별로 보고, 판매자가 정산 내역과 주문별 정산 예정 금액을 보게 합니다.
PENDING)으로 묶습니다.finalizeSettlementLocked가 이미 주문에 고정해 두었고, 이 PR은 그 값을 모읍니다.settlement.created를 같은 tx에 남깁니다.Settlement·Order.settlement_*를 그대로 써서 마이그레이션은 없습니다.변경 사항
SettlementRepository.createWeeklySettlement)settlement_finalized_at < 이번 주 월요일 00:00 KST ∧ settlement_id IS NULL ∧ settlement_base_amount > 0. raw SQL이라 주문deleted_at과 품목deleted_at을 직접 겁니다.store_id입니다. 품목이 모두 삭제된 주문은 매장이 없어 빠집니다.FOR UPDATE로 잠그고 잠금 읽기 결과로 다시 고릅니다(잠금 순서 order → settlement).(store_id, period_start)정산이 이미 있으면 아무것도 만들지 않습니다. 그래서 재실행이 멱등이고, 그때 남은 주문은 다음 주 정산에 묶입니다.settlement_id, outboxsettlement.created(periodStart·periodEnd·storeId·매장명·금액)store_name_snapshot입니다(store 테이블을 읽지 않아 경계 read가 늘지 않습니다).SettlementScheduler(worker)0 0 5 * * 1(Asia/Seoul)과 부팅 1회. 부팅 훅은 모든 역할에서 돌아 역할 게이트가 필수이고, 크론 메서드에도 방어용으로 둡니다.warn경보(keyorder-cron:weekly-settlement)로 남깁니다. 실패한 매장은 다음 실행(부팅·다음 주)에서 다시 시도됩니다.findUnsettledStoreIds가 store_id 오름차순 키셋으로 한 쪽(afterStoreId·limit)씩 돌려주고, 스케줄러는 100곳씩(SETTLEMENT_BATCH_SIZE) 한 실행에 최대 1000곳(SETTLEMENT_MAX_PER_RUN)까지 봅니다. 매장마다 별도 tx(FOR UPDATE → 재검사 → 정산 생성)는 그대로입니다.warn로그로 남깁니다(경보는 보내지 않습니다).(store_id, period_start)기준으로 멱등이라(같은 기간 정산이 있으면 건너뜀,uk_settlement_store_period) 재실행이 안전하고, 다음 주 크론까지 밀리면 그 매장의 남은 주문은 다음 주 정산에 묵은 주문으로 함께 묶입니다.settleLastWeek(limits)의 인자는 테스트만 작은 값을 넘기고, 크론·부팅은 기본값(100·1000)으로 돕니다.kst-time에kstWeekStart를 더해 계산합니다.adminSettlements(input: { limit cursor status storeId periodStart }): 최근 생성 순 키셋. 필터는 AND이고 명시적 null은 생략과 같습니다.periodStart는 YYYY-MM-DD(KST)이고 알림 링크의 값과 같습니다. 항목마다 지금 매장 정산 계좌가 있는지(accountRegistered)를 붙여 처리 대기 허브가 송금 버튼을 막을 수 있게 했습니다.adminSettlement(settlementId): 포함 주문, 지금 매장 정산 계좌(원문,AdminStoreSettlementAccount), 송금 계좌(송금 시점 스냅샷, 끝 4자리만), 처리자 라벨·메모adminMarkSettlementPaid(input: { settlementId note })PENDING → PAID, 그 시점 매장 정산 계좌를paid_*에 옮겨 적습니다. 계좌번호 암호문은 같은 용도 키(settlement-account)라 그대로 복사합니다.SETTLEMENT/STATUS_CHANGE(같은 tx)에는 끝 4자리만 남깁니다. 판매자 감사 로그 대상은 아닙니다.SETTLEMENT_ALREADY_PAID(409), 계좌가 없으면SETTLEMENT_ACCOUNT_REQUIRED(400), 없는 정산이면SETTLEMENT_NOT_FOUND(404)adminMonthlyCommissions(input: { month }): 정산 확정 시각의 KST 월로 매장별 건수·기준액·수수료와 합계를 냅니다. 주간 정산에 묶였는지와 관계없이 셉니다. 매장명은 그 달 가장 늦게 확정된 주문의 스냅샷입니다(확정 시각순, 같으면 주문 id순).adminTaskCounts.pendingSettlements: 송금 대기 정산 수refundsAwaitingAccount·refundsAwaitingTransfer옆에 더했습니다. 서비스·SDL·출력 타입·spec 기대값에 세 필드가 함께 있습니다.sellerSettlements(input: { limit cursor }): 내 매장 정산, 최근 생성 순 키셋sellerSettlement(settlementId): 포함 주문과 송금 계좌(끝 4자리만). 다른 매장 정산은SETTLEMENT_NOT_FOUNDSellerOrderDetail·AdminOrderDetail에commissionRateBps·expectedPayoutAmount·settlementBaseAmount·commissionAmount, 관리자에는settlementFinalizedAt·settlementId도 더했습니다.expectedPayoutAmountOrderAdminAlertConsumer가settlement.created를 구독해info, keysettlement-week:{periodStart}로 보냅니다. 매장별 이벤트가 같은 key로 묶여 억제 창 안에서 주당 한 번만 갑니다.refund.requested·refund.account_submitted)은 그대로 두고 그 뒤에 더했습니다.ADMIN_WEB_BASE_URL이 있으면/tasks/settlements?periodStart=링크를 붙입니다(adminTaskLink).SettlementStatusType, 공용 타입SettlementOrder·SettlementPaidAccount, 관리자·판매자 정산 타입과 입력 DTO 4개SETTLEMENT_NOT_FOUND(404)·SETTLEMENT_ALREADY_PAID(409)·SETTLEMENT_ACCOUNT_REQUIRED(400)admin-query-null-inputs:ADMIN_QUERY_COUNT20 → 22(adminSettlements·adminMonthlyCommissions). base의 20은 BE-06이 18에서 올린 값이고(BE-07은 바꾸지 않음), 합친 SDL을buildSchema로 빌드해 input 객체 인자를 받는 admin 접두 Query가 22개인 것을 셌습니다. 필수 입력month는 스칼라 최소값('x')으로는 리졸버 검증을 넘지 못해, 필수 필드에만 쓰는 필드 이름 최소값 표(month: '2026-01')를 더했습니다. 표가 없으면 이 Query가INVALID_YEAR_MONTH로 실패하는 것을 확인했습니다.roles-coverage: 판매자 63 → 65, 관리자 75 → 79. 합친 SDL을buildSchema로 빌드해 접두 루트 필드 수를 다시 셌습니다.sellerRescheduleOrderPickup·sellerOrderPickupCalendar·sellerOrderPickupTimeSlots)를 더한 값입니다.adminCompleteOrderPickup이 75로 올린 값입니다.sellerSettlements·sellerSettlement2개, 관리자adminSettlements·adminSettlement·adminMarkSettlementPaid·adminMonthlyCommissions4개를 더합니다.enum-sdl-sync:SettlementStatus쌍(BE-06의DepositRecordKind쌍 다음)createFinalizedOrder(확인된 결제·품목·확정값)·createSettlement(BE-06의createRefund와 나란히)feat/order-pickup-reschedule)를 올린 위에 쌓았습니다. BE-07 2/2 머지 뒤 develop 기준으로 올립니다.AdminTaskCounts·모듈 providers·관리자 알림 소비자·enum 쌍·팩토리·게이트 수에서 겹친 부분을 양쪽 모두 살렸습니다.SellerOrderDetail·AdminOrderDetail(SDL·출력 타입·매퍼)에서 겹쳤습니다. 확정 마감·자동 픽업 완료·노쇼 시각,canMarkNoShow,pickupChanges와 이 PR의 수수료·정산 필드가 함께 있고, 관리자 주문 상세 spec도 두 쪽 테스트를 모두 둡니다.테스트
settlement.createdpayload, 구매자 사정 취소의 남은 금액 포함afterStoreId는 100번째 매장) 모두 정산, 경고 없음status·storeId·periodStart·cursor·limitnull = 전체, 형식 오류 5경우SETTLEMENT_NOT_FOUNDsettlement.created생성·파싱과 반증 8행,kstWeekStart4건·formatDateOnly1건, 처리 대기 건수(PAID제외), 리졸버 전체 경로 1건<=로 바꾸면 일요일·월요일 경계 테스트LIMIT을 빼면 101곳 경계·상한·키셋 테스트auth-user-profile.service.spec(탈퇴 차단),src/test(게이트) 97 스위트 2,264건 통과kst-time2 스위트 241건 통과auth-user-profile.service.spec,src/test103 스위트 2,579건 통과kst-time2 스위트 244건 통과dto:check·docs:check·arch:check통과. 전체 jest는 pre-push에서 돕니다.플랜 대조
settlement_finalized_at < 이번 주 월요일 00:00 KST ∧ settlement_id IS NULL ∧ settlement_base_amount > 0(raw SQL, deleted_at 명시)settlement_id채움(store_id, period_start)unique로 재실행 멱등, 묵은 주문은 다음 정산에 들어감settlement.created(periodStart·storeId·금액)kst-timekstWeekStart)expectedPayoutAmount: 확정 전 결제액 − floor(결제액 × bps / 10000), 확정 뒤 실제 지급액, 확인된 결제가 없으면 nulladminMarkSettlementPaid(settlementId, note?): PENDING → PAID, 매장 정산 계좌를paid_*에 스냅샷, 없으면SETTLEMENT_ACCOUNT_REQUIREDadminMonthlyCommissions(month): 확정 시각의 KST 월로 매장별 건수·기준액·수수료adminSettlements(status, storeId, periodStart, cursor)adminSettlement(id)(포함 주문·현재 계좌 원문·송금 계좌 마스킹·처리자 라벨)sellerSettlements(cursor)·sellerSettlement(id)adminPaymentSetting·adminStoreSettlementAccount·sellerSettlementAccount·결제 설정·정산 계좌 변경, 계좌 암호화finalizeSettlementLockedsettlementAmounts·confirmedPaidAmount를 정산 예정 금액에 재사용)SETTLEMENT_ACCOUNT_REQUIRED(400)·SETTLEMENT_NOT_FOUND(404)·SETTLEMENT_ALREADY_PAID(409)SettlementSchedulerrunning플래그, 실패는 로그 +warn경보 keyorder-cron:<job>order-cron:weekly-settlement)warn로그를 남기고 다음 실행에서 정산)SellerOrderDetail.commissionRateBps·expectedPayoutAmount·settlementBaseAmount·commissionAmountAdminOrderDetail의 수수료·정산 필드settlementFinalizedAt·settlementId)pendingSettlements(AdminTaskCounts)ADMIN_QUERY_COUNT+2(adminSettlements·adminMonthlyCommissions), null 입력 무오류OrderAdminAlertConsumer가settlement.created구독, keysettlement-week:{periodStart},adminTaskLink(baseUrl, '/tasks/settlements', …),infostore_id, 매장명은store_name_snapshot(경계 read 증가 없음)admin-query-null-inputs·roles-coverage·enum-sdl-sync. model-ownership·read-boundary·audit-target-type-sync·seed-reset-scope는 늘어난 대상이 없어 그대로)status·storeIdnull 입력 = 전체