Skip to content

feat: 주간 정산·월 수수료 집계와 판매자 정산 조회 - #586

Merged
chanwoo7 merged 3 commits into
developfrom
feat/weekly-settlement
Nov 18, 2026
Merged

chanwoo7 merged 3 commits into
developfrom
feat/weekly-settlement

Conversation

@chanwoo7

Copy link
Copy Markdown
Member

개요

정산이 확정된 주문을 매주 매장별 정산으로 묶고, 관리자가 송금 뒤 '송금 완료'로 닫으며, 월 수수료를 매장별로 보고, 판매자가 정산 내역과 주문별 정산 예정 금액을 보게 합니다.

  • worker가 매주 월요일 05:00(KST)과 부팅 때 지난주(월~일)까지 확정된 주문을 매장별 정산(PENDING)으로 묶습니다.
    • 확정 주문은 픽업 완료·노쇼(결제액)와 구매자 사정 취소의 남은 금액입니다. 확정은 BE-05의 finalizeSettlementLocked가 이미 주문에 고정해 두었고, 이 PR은 그 값을 모읍니다.
    • 매장마다 따로 커밋하고, 정산 행·주문 연결·outbox settlement.created를 같은 tx에 남깁니다.
  • 관리자는 정산 목록·상세(현재 계좌 원문)를 보고 은행 앱에서 송금한 뒤 송금 완료로 처리합니다. 그때의 매장 정산 계좌를 정산에 스냅샷합니다.
  • 주간 정산이 생기면 관리자 디스코드에 주 단위로 한 번 알리고, 처리 대기 건수에 송금 대기 정산 수를 더했습니다.
  • 스키마는 BE-01이 만든 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을 직접 겁니다.
    • 매장은 주문의 첫 품목(남은 품목 중 최소 id)의 store_id입니다. 품목이 모두 삭제된 주문은 매장이 없어 빠집니다.
    • 한 매장의 tx 안에서 하는 일
      • 대상 주문을 id 오름차순 FOR UPDATE로 잠그고 잠금 읽기 결과로 다시 고릅니다(잠금 순서 order → settlement).
      • 같은 (store_id, period_start) 정산이 이미 있으면 아무것도 만들지 않습니다. 그래서 재실행이 멱등이고, 그때 남은 주문은 다음 주 정산에 묶입니다.
      • 정산 행(지난주 월~일, 건수·기준액 합·수수료 합·지급액), 주문 settlement_id, outbox settlement.created(periodStart·periodEnd·storeId·매장명·금액)
    • 매장명 스냅샷은 묶인 주문 중 가장 최근 주문의 store_name_snapshot입니다(store 테이블을 읽지 않아 경계 read가 늘지 않습니다).
    • 몇 주 전에 확정됐는데 아직 묶이지 않은 주문(크론 중단 등)도 이번 정산에 함께 들어갑니다.
  • SettlementScheduler(worker)
    • 크론 0 0 5 * * 1(Asia/Seoul)과 부팅 1회. 부팅 훅은 모든 역할에서 돌아 역할 게이트가 필수이고, 크론 메서드에도 방어용으로 둡니다.
    • 겹친 실행은 건너뜁니다. 한 매장이 실패해도 다른 매장은 계속 만들고, 실패는 로그와 warn 경보(key order-cron:weekly-settlement)로 남깁니다. 실패한 매장은 다음 실행(부팅·다음 주)에서 다시 시도됩니다.
    • 후보 매장은 플랜 7절 크론 공통 규칙대로 고릅니다.
      • findUnsettledStoreIds가 store_id 오름차순 키셋으로 한 쪽(afterStoreId·limit)씩 돌려주고, 스케줄러는 100곳씩(SETTLEMENT_BATCH_SIZE) 한 실행에 최대 1000곳(SETTLEMENT_MAX_PER_RUN)까지 봅니다. 매장마다 별도 tx(FOR UPDATE → 재검사 → 정산 생성)는 그대로입니다.
      • 실패한 매장도 키셋이 지나가서 같은 실행에서 다시 잡히지 않습니다.
      • 상한에 닿으면 남은 매장이 있는지 1곳만 더 보고, 있으면 다음 매장 id를 warn 로그로 남깁니다(경보는 보내지 않습니다).
      • 남은 매장은 다음 실행(부팅 1회·다음 주 크론)에서 정산됩니다. 정산 생성이 (store_id, period_start) 기준으로 멱등이라(같은 기간 정산이 있으면 건너뜀, uk_settlement_store_period) 재실행이 안전하고, 다음 주 크론까지 밀리면 그 매장의 남은 주문은 다음 주 정산에 묵은 주문으로 함께 묶입니다.
      • settleLastWeek(limits)의 인자는 테스트만 작은 값을 넘기고, 크론·부팅은 기본값(100·1000)으로 돕니다.
    • KST 주 경계는 kst-time에 kstWeekStart를 더해 계산합니다.
  • 관리자 API
    • 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: 송금 대기 정산 수
  • 판매자 API
    • sellerSettlements(input: { limit cursor }): 내 매장 정산, 최근 생성 순 키셋
    • sellerSettlement(settlementId): 포함 주문과 송금 계좌(끝 4자리만). 다른 매장 정산은 SETTLEMENT_NOT_FOUND
  • 주문 상세의 수수료·정산 필드(7절 표의 BE-08 행)
    • SellerOrderDetail·AdminOrderDetail에 commissionRateBps·expectedPayoutAmount·settlementBaseAmount·commissionAmount, 관리자에는 settlementFinalizedAt·settlementId도 더했습니다.
    • expectedPayoutAmount
      • 확정 뒤: 실제 지급액(기준액 − 수수료)
      • 확정 전: 결제액 − floor(결제액 × 수수료율 / 10000)
      • 입금이 확인되지 않았거나 결제 도입 전 주문: null
      • 확정 없이 취소된 주문(전액 환불·판매자 사정): 0. 플랜 문구에 이 경우가 따로 없어, 취소는 정산 0이라는 D14에 맞춰 정했습니다.
  • 관리자 경보(9절)
    • OrderAdminAlertConsumer가 settlement.created를 구독해 info, key settlement-week:{periodStart}로 보냅니다. 매장별 이벤트가 같은 key로 묶여 억제 창 안에서 주당 한 번만 갑니다.
      • BE-06의 환불 송금 대기 구독(refund.requested·refund.account_submitted)은 그대로 두고 그 뒤에 더했습니다.
    • 문구는 '{periodStart} ~ {periodEnd} 정산이 생성됐어요. 매장별 정산을 확인하고 송금해 주세요.'이고, ADMIN_WEB_BASE_URL이 있으면 /tasks/settlements?periodStart= 링크를 붙입니다(adminTaskLink).
  • SDL·오류
    • 새 enum SettlementStatusType, 공용 타입 SettlementOrder·SettlementPaidAccount, 관리자·판매자 정산 타입과 입력 DTO 4개
    • 오류 SETTLEMENT_NOT_FOUND(404)·SETTLEMENT_ALREADY_PAID(409)·SETTLEMENT_ACCOUNT_REQUIRED(400)
    • 기존 필드는 바꾸거나 지우지 않았고 추가만 했습니다.
  • 게이트·팩토리
    • admin-query-null-inputs: ADMIN_QUERY_COUNT 20 → 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로 빌드해 접두 루트 필드 수를 다시 셌습니다.
      • base의 판매자 63은 BE-07 2/2의 픽업 변경 3개(sellerRescheduleOrderPickup·sellerOrderPickupCalendar·sellerOrderPickupTimeSlots)를 더한 값입니다.
      • base의 관리자 75는 BE-06이 67에서 74로, BE-07 1/2(feat: 노쇼 처리와 주문 자동 전이 크론, 관리자 픽업 완료 #583)의 adminCompleteOrderPickup이 75로 올린 값입니다.
      • 이 PR이 판매자 sellerSettlements·sellerSettlement 2개, 관리자 adminSettlements·adminSettlement·adminMarkSettlementPaid·adminMonthlyCommissions 4개를 더합니다.
    • enum-sdl-sync: SettlementStatus 쌍(BE-06의 DepositRecordKind 쌍 다음)
    • 팩토리 createFinalizedOrder(확인된 결제·품목·확정값)·createSettlement(BE-06의 createRefund와 나란히)
  • 크기·커밋
    • BE-06(feat: 환불 계좌 입력·환불 완료와 입금 반환·종결 기록, 탈퇴 차단 #581)·BE-07 1/2(feat: 노쇼 처리와 주문 자동 전이 크론, 관리자 픽업 완료 #583)이 머지된 develop에 BE-07 2/2(feat/order-pickup-reschedule)를 올린 위에 쌓았습니다. BE-07 2/2 머지 뒤 develop 기준으로 올립니다.
    • BE-06과는 오류 카탈로그·AdminTaskCounts·모듈 providers·관리자 알림 소비자·enum 쌍·팩토리·게이트 수에서 겹친 부분을 양쪽 모두 살렸습니다.
    • BE-07과는 SellerOrderDetail·AdminOrderDetail(SDL·출력 타입·매퍼)에서 겹쳤습니다. 확정 마감·자동 픽업 완료·노쇼 시각, canMarkNoShow, pickupChanges와 이 PR의 수수료·정산 필드가 함께 있고, 관리자 주문 상세 spec도 두 쪽 테스트를 모두 둡니다.
    • +3,549/−13줄이고 그중 spec이 +1,687/−6줄입니다.
    • 커밋은 3개입니다. 기능 커밋 뒤에 월 집계 매장명 정렬을 바로잡는 fix 커밋, 주간 정산 후보에 배치 100·상한 1000을 적용한 커밋이 있습니다.
    • 2,500줄을 넘지만 플랜이 BE-08에 분할 경계를 두지 않아 나누지 않았습니다.

테스트

  • 주간 정산(20건, 운영 상한 1건만 후보 조회·생성을 stub하고 나머지는 real DB)
    • 일요일 23:59:59.999 KST 확정은 지난주에, 월요일 00:00 확정은 다음 주 정산에 들어감
    • 실행 시각이 일요일 23:59:59.999면 그 전주(11-02~11-08)를 정산하고 이번 주 확정분은 남김
    • 합계·수수료(원 미만 버림)·기간·최근 매장명·주문 연결·settlement.created payload, 구매자 사정 취소의 남은 금액 포함
    • 재실행 멱등(정산·이벤트 1건), 같은 주 정산이 이미 있으면 늦게 들어온 주문은 다음 주 정산으로. 두 경우 모두 경보가 나가지 않음
    • 묵은 주문(3주 전 확정) 포함
    • 제외: 확정 전, 기준액 0, 이미 정산됨, 주문 삭제, 품목 전부 삭제
    • 이벤트를 실제로 적재한 뒤 tx를 실패시키면 정산 행·주문 연결·이벤트가 모두 남지 않고 경보, 다음 실행에서 생성
    • 매장별 실패 격리, 후보 조회 실패 경보, 겹친 실행 건너뜀
    • api·ws 역할은 부팅·크론 모두 미실행, worker는 부팅 1회·크론마다 실행
    • 배치 경계(운영 값): 후보 100곳·101곳이 100곳씩 두 쪽으로 나뉘고(두 번째 쪽 afterStoreId는 100번째 매장) 모두 정산, 경고 없음
    • 운영 상한: 배치 100·상한 1000 값을 단언하고, 후보 1050곳에서 1000곳만 처리한 뒤 남은 매장 확인 1회와 경고(매장 1000곳을 만들지 않으려고 이 1건만 stub)
    • 상한(배치 2·상한 5): 7곳 중 id 순 5곳만 정산하고 경고, 경보는 없음. 다음 실행에서 남은 2곳을 같은 주로 정산(정산·이벤트 7건). 후보가 상한과 같으면 경고 없음
    • 키셋: 주문 id 순과 어긋난 매장 id 오름차순으로 돌고, 실패한 첫 매장은 같은 실행에서 다시 잡지 않음
  • 관리자 정산(real DB, 24건)
    • 목록 커서·계좌 등록 여부, 상태·매장·기간 필터 AND, status·storeId·periodStart·cursor·limit null = 전체, 형식 오류 5경우
    • 상세의 포함 주문·현재 계좌 원문, 없는 정산 404
    • 송금 완료: 계좌 스냅샷(암호문 복호화 대조)·처리자 라벨·메모·감사(원문 미포함), 송금 뒤 계좌가 바뀌어도 송금 계좌는 그대로
    • 이미 송금 409(처음 기록 유지), 동시 두 번은 한 번만 성공, 계좌 미등록 400·송금 대기 유지, 감사 실패 시 롤백, 입력 오류 3경우
    • 월 집계 KST 경계(10/31 23:59:59.999 제외, 11/1 00:00·11/30 23:59:59.999 포함, 12/1 00:00 제외), 삭제 주문 제외, 매장별·합계, 빈 달, 월 형식 오류 4경우
    • 월 집계 매장명: 먼저 생성된 주문이 늦게 확정되면 그 주문의 이름
  • 판매자 정산(real DB, 3건): 내 매장만·키셋, 상세의 포함 주문·송금 계좌 끝 4자리, 다른 매장·없는 정산 SETTLEMENT_NOT_FOUND
  • 정산 예정 금액 표 7건(결제 없음·미확인·확정 전·버림 경계·확정 없이 취소·부분 환불 확정·픽업 완료 확정), 판매자·관리자 주문 상세 각 1건
  • 경보 소비자: 문구·key·링크, 같은 주 두 매장은 1회·다른 주는 따로, 형식 오류 payload
  • settlement.created 생성·파싱과 반증 8행, kstWeekStart 4건·formatDateOnly 1건, 처리 대기 건수(PAID 제외), 리졸버 전체 경로 1건
  • 반증: 아래를 하나씩 깨면 해당 테스트가 실패하는 것을 확인하고 되돌렸습니다.
    • outbox 적재를 tx 밖 클라이언트로 바꾸면 같은 tx 테스트
    • 대상 경계를 <=로 바꾸면 일요일·월요일 경계 테스트
    • 부팅 훅의 역할 게이트를 빼면 api·ws 테스트
    • 판매자 상세의 매장 범위를 빼면 다른 매장 404 테스트
    • 같은 기간 정산이 있으면 건너뛰는 가드를 빼면 늦게 들어온 주문 테스트(unique 위반이 매장별 실패로 잡혀 경보가 나감)
    • 월 집계 매장명 정렬을 주문 id로 되돌리면 매장명 테스트
    • 스케줄러 상한 가드를 빼면 운영 상한(1050곳 처리)·상한 테스트(7곳 정산)
    • 후보 SQL의 LIMIT을 빼면 101곳 경계·상한·키셋 테스트
    • 스케줄러 배치를 빼고 상한만큼 한 번에 고르면 100곳·101곳 경계·운영 상한·키셋 테스트
    • 후보 SQL의 키셋 조건을 빼면 키셋 테스트(실패한 매장을 다시 잡아 5곳 정산)
    • 상한 경고를 빼면 운영 상한·상한 테스트
  • 경로 지정 실행(BE-06이 머지된 develop 위로 올린 뒤)
    • order·notification feature, auth-user-profile.service.spec(탈퇴 차단), src/test(게이트) 97 스위트 2,264건 통과
    • 오류 카탈로그·kst-time 2 스위트 241건 통과
  • 경로 지정 실행(BE-07 2/2 위로 다시 쌓은 뒤)
    • order·notification feature, auth-user-profile.service.spec, src/test 103 스위트 2,579건 통과
    • 오류 카탈로그·kst-time 2 스위트 244건 통과
  • 정적 검사: lint·tsc·dto:check·docs:check·arch:check 통과. 전체 jest는 pre-push에서 돕니다.

플랜 대조

플랜 항목 BE-08 불릿 상태
8절 주간 정산: 대상 settlement_finalized_at < 이번 주 월요일 00:00 KST ∧ settlement_id IS NULL ∧ settlement_base_amount > 0(raw SQL, deleted_at 명시) 한 것
8절 매장별 Settlement(지난주, PENDING), 주문 행 id 오름차순 FOR UPDATE, settlement_id 채움 한 것
8절 (store_id, period_start) unique로 재실행 멱등, 묵은 주문은 다음 정산에 들어감 한 것
8절 매장별 Settlement 생성 tx 안에서 outbox settlement.created(periodStart·storeId·금액) 한 것
8절 KST 주 경계 helper는 kst-time 한 것(kstWeekStart)
8절 expectedPayoutAmount: 확정 전 결제액 − floor(결제액 × bps / 10000), 확정 뒤 실제 지급액, 확인된 결제가 없으면 null 한 것(확정 없이 취소된 주문은 0, 개요에 적은 대로)
8절 adminMarkSettlementPaid(settlementId, note?): PENDING → PAID, 매장 정산 계좌를 paid_*에 스냅샷, 없으면 SETTLEMENT_ACCOUNT_REQUIRED 한 것
8절 adminMonthlyCommissions(month): 확정 시각의 KST 월로 매장별 건수·기준액·수수료 한 것
8절 조회 API: adminSettlements(status, storeId, periodStart, cursor) 한 것
8절 조회 API: adminSettlement(id)(포함 주문·현재 계좌 원문·송금 계좌 마스킹·처리자 라벨) 한 것
8절 조회 API: sellerSettlements(cursor)·sellerSettlement(id) 한 것
8절 조회·변경 API 중 adminPaymentSetting·adminStoreSettlementAccount·sellerSettlementAccount·결제 설정·정산 계좌 변경, 계좌 암호화 한 것(BE-02에서 들어가 있어 이 PR은 정산 상세의 복호화·스냅샷 복사에 그대로 씀)
8절 finalizeSettlementLocked 한 것(BE-05에서 들어가 있어 이 PR은 확정값을 모으고 settlementAmounts·confirmedPaidAmount를 정산 예정 금액에 재사용)
13절 오류 SETTLEMENT_ACCOUNT_REQUIRED(400)·SETTLEMENT_NOT_FOUND(404)·SETTLEMENT_ALREADY_PAID(409) 한 것
7절 크론 ⑤ 주간 정산: 월 05:00 KST + worker 부팅 1회, SettlementScheduler 한 것
7절 크론 공통: 부팅 훅 역할 게이트 필수·크론 메서드 방어, running 플래그, 실패는 로그 + warn 경보 key order-cron:<job> 한 것(order-cron:weekly-settlement)
7절 크론 공통: 후보 id 배치 100·상한 1000 한 것(후보 매장 id를 store_id 키셋으로 100곳씩, 한 실행 최대 1000곳. 남은 매장은 warn 로그를 남기고 다음 실행에서 정산)
7절 표 BE-08 행: SellerOrderDetail.commissionRateBps·expectedPayoutAmount·settlementBaseAmount·commissionAmount 한 것
7절 표 BE-08 행: AdminOrderDetail의 수수료·정산 필드 한 것(같은 4필드 + settlementFinalizedAt·settlementId)
pendingSettlements(AdminTaskCounts) 한 것
ADMIN_QUERY_COUNT +2(adminSettlements·adminMonthlyCommissions), null 입력 무오류 한 것
9절(BE-04에서 넘어옴) 주간 정산 생성 관리자 알림: OrderAdminAlertConsumer가 settlement.created 구독, key settlement-week:{periodStart}, adminTaskLink(baseUrl, '/tasks/settlements', …), info 한 것
1절 정산 매장은 첫 품목 store_id, 매장명은 store_name_snapshot(경계 read 증가 없음) 한 것
1절 잠금 순서 order → … → settlement 한 것
1절 게이트 갱신 한 것(admin-query-null-inputs·roles-coverage·enum-sdl-sync. model-ownership·read-boundary·audit-target-type-sync·seed-reset-scope는 늘어난 대상이 없어 그대로)
테스트: KST 일 23:59:59.999 / 월 00:00 한 것
테스트: 재실행 멱등 한 것
테스트: 정산 행과 outbox가 같은 tx(롤백 시 둘 다 없음) 한 것
테스트: 주간 경보 key 1회 한 것
테스트: status·storeId null 입력 = 전체 한 것
테스트: 묵은 주문 한 것
테스트: 계좌 스냅샷·미등록 한 것
테스트: soft-delete 제외 한 것(주문 삭제·품목 전부 삭제, 월 집계 삭제 주문)
테스트: api 역할 부팅 미실행 한 것(ws 포함, 크론 메서드도)
결정 이 PR에서 한 일 상태
D2 주문 1건 = 매장 1곳 전제로 첫 품목 매장에 정산 한 것
D12 주문 상세의 수수료율·수수료액 표시, 관리자 매장별 월 집계 한 것
D14 확정값(결제액, 픽업 완료·노쇼)만 정산, 취소는 정산 0 한 것
D15 worker가 월~일(KST) 확정분을 매장별 정산으로 묶고 관리자가 송금 뒤 '송금 완료' 한 것
D19 부분 환불 잔액(취소 시각 확정분)도 주간 정산·월 집계에 포함 한 것
D27 주간 정산 생성 디스코드 알림과 처리 대기 건수·목록 한 것(화면은 AD-3·AD-4)
D73 판매자 정산 내역(기간·건수·수수료·정산 금액·송금 여부)과 주문 상세의 수수료율·정산 예정 금액 한 것(화면은 SL-2·SL-3)

정산이 확정된 주문(픽업 완료·노쇼·구매자 사정 취소의 남은 금액)을 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 제거·스케줄러 배치 제거·키셋 조건 제거·경고 제거가 각각 위 테스트를 실패시키는 것을 확인하고 되돌렸다
@coderabbitai

coderabbitai Bot commented Nov 18, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T22:48:31.427367Z 71a3bda PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown

🧹 knip — dead-code 리포트

Unused exports (1)
Unused exported types (4)
전체 리포트
Unused exports (1)
effectiveLeadTimeMinutes  src/features/store/index.ts:20:10
Unused exported types (4)
OrderPickupRescheduledPayload  type  src/features/order/index.ts:44:8  
ProductCustomIssue             type  src/features/product/index.ts:11:8
ThreeDDesignSource             type  src/features/product/index.ts:16:8
ThreeDDesignV1                 type  src/features/product/index.ts:17:8

청소 후보(오탐 가능) · 기준 docs/guide/architecture-conventions.md

@github-actions

Copy link
Copy Markdown

🩺 NestJS Doctor — 90/100 (Excellent)

진단 539건 (error 14).

Category error warning info
architecture 2 2 46
correctness 0 295 0
performance 0 44 29
schema 0 0 87
security 12 22 0
architecture / security 상위 항목
  • error security/security/no-hardcoded-secrets: Variable 'SEED_PASSWORD' appears to contain a hardcoded secret.
  • error architecture/architecture/no-manual-instantiation: Manual instantiation of 'AccountNumberReencryptRepository' detected. Use dependency injection instead.
  • warning security/security/no-weak-crypto: Weak hashing algorithm 'md5' used in createHash().
  • error architecture/architecture/no-manual-instantiation: Manual instantiation of 'OutboxRepository' detected. Use dependency injection instead.
  • info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal type 'IAuditLogRepository'.
  • warning security/security/no-exposed-env-vars: Direct 'process.env.NODE_ENV' access in 'AuthController'. Use ConfigService instead.
  • warning security/security/require-guards-on-endpoints: Endpoint 'start' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'callback' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'refresh' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'logout' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'sellerLogin' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'sellerRefresh' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'sellerLogout' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'devIssueToken' has no @UseGuards() at class or method level.
  • warning security/security/require-guards-on-endpoints: Endpoint 'adminLogin' has no @UseGuards() at class or method level.

오탐 포함 가능 · 기준 docs/guide/architecture-conventions.md

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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!

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

미반영(기록): 유효하나 플랫폼 월 합계가 약 21억 원을 넘어야 생기는 한계라 현재 규모(운영 주문 0건) 밖이고, 금액 합계용 스칼라 도입은 SDL·관리자 FE에 걸친 새 장치. 후속 #587.

@github-actions

Copy link
Copy Markdown

Coverage report

St.❔
Category Percentage Covered / Total
🟢 Statements
98.44% (+0.03% 🔼)
13419/13631
🟢 Branches
93.84% (-0.01% 🔻)
5254/5599
🟢 Functions
98.08% (+0.05% 🔼)
2712/2765
🟢 Lines
98.91% (+0.02% 🔼)
12211/12345
Show new covered files 🐣
St.❔
File Statements Branches Functions Lines
🟢
... / settlement.repository.ts
98.18% 95.45% 100% 100%
🟢
... / settlement-created.event.ts
100% 100% 100% 100%
🟢
... / order-settlement-mappers.helper.ts
100% 78.95% 100% 100%
🟢
... / order-settlement-admin-mutation.resolver.ts
100% 100% 100% 100%
🟢
... / admin-mark-settlement-paid.input.ts
100% 100% 100% 100%
🟢
... / order-settlement-admin.service.ts
100% 100% 100% 100%
🟢
... / order-settlement-admin-query.resolver.ts
100% 100% 100% 100%
🟢
... / admin-monthly-commission.input.ts
100% 100% 100% 100%
🟢
... / admin-settlement-list.input.ts
100% 100% 100% 100%
🟢
... / seller-settlement-list.input.ts
100% 100% 100% 100%
🟢
... / order-settlement.scheduler.ts
100% 89.47% 100% 100%

Test suite run success

6646 tests passing in 444 suites.

Report generated by 🧪jest coverage report action from 71a3bda

@chanwoo7
chanwoo7 merged commit b2ee9d3 into develop Nov 18, 2026
17 checks passed
@chanwoo7
chanwoo7 deleted the feat/weekly-settlement branch November 18, 2026 22:53
@codecov

codecov Bot commented Nov 18, 2026

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant