From 1ad33b9a6911a4244c5ffb40319afaa1381122cf Mon Sep 17 00:00:00 2001 From: chanwoo7 Date: Thu, 19 Nov 2026 06:02:56 +0900 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20=EC=A3=BC=EA=B0=84=20=EC=A0=95?= =?UTF-8?q?=EC=82=B0=C2=B7=EC=9B=94=20=EC=88=98=EC=88=98=EB=A3=8C=20?= =?UTF-8?q?=EC=A7=91=EA=B3=84=EC=99=80=20=ED=8C=90=EB=A7=A4=EC=9E=90=20?= =?UTF-8?q?=EC=A0=95=EC=82=B0=20=EC=A1=B0=ED=9A=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 정산이 확정된 주문(픽업 완료·노쇼·구매자 사정 취소의 남은 금액)을 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 밖 적재·경계 <=·부팅 역할 게이트 제거·판매자 매장 범위 제거가 각각 해당 테스트를 실패시키는 것을 확인하고 되돌렸다 --- src/common/errors/error-catalog.ts | 13 + src/common/utils/kst-time.spec.ts | 37 ++ src/common/utils/kst-time.ts | 11 + .../admin-mark-settlement-paid.input.ts | 10 + .../inputs/admin-monthly-commission.input.ts | 7 + .../dto/inputs/admin-settlement-list.input.ts | 19 + .../inputs/seller-settlement-list.input.ts | 3 + .../events/settlement-created.event.spec.ts | 55 ++ .../order/events/settlement-created.event.ts | 72 +++ src/features/order/order-admin.graphql | 25 + .../order/order-deposit-admin.graphql | 4 + src/features/order/order-seller.graphql | 17 + .../order/order-settlement-admin.graphql | 266 ++++++++++ .../order/order-settlement-seller.graphql | 134 +++++ src/features/order/order.module.ts | 13 +- src/features/order/order.types.graphql | 67 +++ .../order/repositories/order.repository.ts | 2 +- .../repositories/settlement.repository.ts | 309 +++++++++++ .../store-settlement-account.repository.ts | 9 + .../order-deposit-admin.resolver.spec.ts | 3 + .../resolvers/order-payment.resolver.spec.ts | 4 + ...rder-settlement-admin-mutation.resolver.ts | 32 ++ .../order-settlement-admin-query.resolver.ts | 58 ++ .../order-settlement-seller-query.resolver.ts | 31 +- .../order-settlement.resolver.spec.ts | 131 +++++ .../order-admin-alert-messages.helper.ts | 20 + .../order-admin-alert.consumer.spec.ts | 59 +++ .../services/order-admin-alert.consumer.ts | 11 + .../services/order-admin-mappers.helper.ts | 4 + .../services/order-admin.service.spec.ts | 35 ++ .../order-deposit-admin.service.spec.ts | 8 +- .../services/order-deposit-admin.service.ts | 5 + .../services/order-seller.service.spec.ts | 39 ++ .../order/services/order-seller.service.ts | 11 +- .../order-settlement-admin.service.spec.ts | 494 ++++++++++++++++++ .../order-settlement-admin.service.ts | 164 ++++++ .../order-settlement-mappers.helper.spec.ts | 51 ++ .../order-settlement-mappers.helper.ts | 165 ++++++ .../order-settlement-seller.service.spec.ts | 150 +++++- .../order-settlement-seller.service.ts | 52 +- .../order-settlement.scheduler.spec.ts | 419 +++++++++++++++ .../services/order-settlement.scheduler.ts | 102 ++++ .../order/types/order-admin-output.type.ts | 6 +- .../order/types/order-payment-output.type.ts | 1 + .../order/types/order-seller-output.type.ts | 4 +- .../types/order-settlement-output.type.ts | 80 +++ src/test/admin-query-null-inputs.spec.ts | 14 +- src/test/enum-sdl-sync.spec.ts | 7 + src/test/factories/order.factory.ts | 91 ++++ src/test/roles-coverage.spec.ts | 4 +- 50 files changed, 3315 insertions(+), 13 deletions(-) create mode 100644 src/features/order/dto/inputs/admin-mark-settlement-paid.input.ts create mode 100644 src/features/order/dto/inputs/admin-monthly-commission.input.ts create mode 100644 src/features/order/dto/inputs/admin-settlement-list.input.ts create mode 100644 src/features/order/dto/inputs/seller-settlement-list.input.ts create mode 100644 src/features/order/events/settlement-created.event.spec.ts create mode 100644 src/features/order/events/settlement-created.event.ts create mode 100644 src/features/order/order-settlement-admin.graphql create mode 100644 src/features/order/repositories/settlement.repository.ts create mode 100644 src/features/order/resolvers/order-settlement-admin-mutation.resolver.ts create mode 100644 src/features/order/resolvers/order-settlement-admin-query.resolver.ts create mode 100644 src/features/order/resolvers/order-settlement.resolver.spec.ts create mode 100644 src/features/order/services/order-settlement-admin.service.spec.ts create mode 100644 src/features/order/services/order-settlement-admin.service.ts create mode 100644 src/features/order/services/order-settlement-mappers.helper.spec.ts create mode 100644 src/features/order/services/order-settlement-mappers.helper.ts create mode 100644 src/features/order/services/order-settlement.scheduler.spec.ts create mode 100644 src/features/order/services/order-settlement.scheduler.ts create mode 100644 src/features/order/types/order-settlement-output.type.ts diff --git a/src/common/errors/error-catalog.ts b/src/common/errors/error-catalog.ts index 82af049d..d4cde05c 100644 --- a/src/common/errors/error-catalog.ts +++ b/src/common/errors/error-catalog.ts @@ -485,6 +485,19 @@ export const ERROR_CATALOG = { status: HttpStatus.CONFLICT, message: '이미 반환 대상으로 연결된 입금 기록입니다.', }, + SETTLEMENT_NOT_FOUND: { + status: HttpStatus.NOT_FOUND, + message: '정산 내역을 찾을 수 없어요.', + }, + SETTLEMENT_ALREADY_PAID: { + status: HttpStatus.CONFLICT, + message: '이미 송금 완료로 처리된 정산이에요.', + }, + SETTLEMENT_ACCOUNT_REQUIRED: { + status: HttpStatus.BAD_REQUEST, + message: + '매장 정산 계좌가 등록되지 않아 송금 완료로 처리할 수 없어요. 정산 계좌를 먼저 등록해 주세요.', + }, // ── 판매자 SELLER_ONLY: { status: HttpStatus.FORBIDDEN, diff --git a/src/common/utils/kst-time.spec.ts b/src/common/utils/kst-time.spec.ts index 8068b2a6..fe5ec6ed 100644 --- a/src/common/utils/kst-time.spec.ts +++ b/src/common/utils/kst-time.spec.ts @@ -1,11 +1,13 @@ import { daysInMonth, + formatDateOnly, formatKstDate, formatMinutesOfDay, kstDayBoundaries, kstDayDiff, kstMidnightUtc, kstMinutesOfDay, + kstWeekStart, parseKstDate, parseKstYearMonth, toKstYmd, @@ -105,6 +107,41 @@ describe('kst-time', () => { }); }); + describe('kstWeekStart', () => { + it.each([ + [ + '월 00:00 KST는 그 주의 시작이다', + '2026-11-15T15:00:00.000Z', + '2026-11-15T15:00:00.000Z', + ], + [ + '일 23:59:59.999 KST는 앞 주에 속한다', + '2026-11-15T14:59:59.999Z', + '2026-11-08T15:00:00.000Z', + ], + [ + 'UTC로는 수요일인 목 00:30 KST', + '2026-11-18T15:30:00.000Z', + '2026-11-15T15:00:00.000Z', + ], + [ + '연말 금요일은 전년 12월 월요일로 간다', + '2027-01-01T01:00:00.000Z', + '2026-12-27T15:00:00.000Z', + ], + ])('%s', (_label, at, expected) => { + expect(kstWeekStart(new Date(at)).toISOString()).toBe(expected); + }); + }); + + describe('formatDateOnly', () => { + it('@db.Date 값을 YYYY-MM-DD로 쓴다', () => { + expect(formatDateOnly(new Date('2026-11-09T00:00:00.000Z'))).toBe( + '2026-11-09', + ); + }); + }); + describe('daysInMonth', () => { it('말일을 계산한다(윤년 포함)', () => { expect(daysInMonth(2026, 9)).toBe(30); diff --git a/src/common/utils/kst-time.ts b/src/common/utils/kst-time.ts index 2b53906b..b1530b1a 100644 --- a/src/common/utils/kst-time.ts +++ b/src/common/utils/kst-time.ts @@ -47,6 +47,17 @@ export function kstDayBoundaries(at: Date): KstDayBoundaries { }; } +/** 그 시각이 속한 KST 주(월~일)의 월요일 00:00 KST(UTC 시각). */ +export function kstWeekStart(at: Date): Date { + const { dayStartUtc, weekday } = kstDayBoundaries(at); + return new Date(dayStartUtc.getTime() - ((weekday + 6) % 7) * DAY_MS); +} + +/** `@db.Date` 값(KST 달력일의 UTC 자정 표현)을 YYYY-MM-DD로. */ +export function formatDateOnly(dateOnlyUtc: Date): string { + return dateOnlyUtc.toISOString().slice(0, 10); +} + export function daysInMonth(year: number, month: number): number { return new Date(Date.UTC(year, month, 0)).getUTCDate(); } diff --git a/src/features/order/dto/inputs/admin-mark-settlement-paid.input.ts b/src/features/order/dto/inputs/admin-mark-settlement-paid.input.ts new file mode 100644 index 00000000..ed774e71 --- /dev/null +++ b/src/features/order/dto/inputs/admin-mark-settlement-paid.input.ts @@ -0,0 +1,10 @@ +import { IsOptional, IsString } from 'class-validator'; + +export class AdminMarkSettlementPaidInput { + @IsString() + settlementId!: string; + + @IsOptional() + @IsString() + note?: string; +} diff --git a/src/features/order/dto/inputs/admin-monthly-commission.input.ts b/src/features/order/dto/inputs/admin-monthly-commission.input.ts new file mode 100644 index 00000000..f3bd8025 --- /dev/null +++ b/src/features/order/dto/inputs/admin-monthly-commission.input.ts @@ -0,0 +1,7 @@ +import { IsString } from 'class-validator'; + +export class AdminMonthlyCommissionInput { + // 형식(YYYY-MM)은 서비스가 INVALID_YEAR_MONTH로 거절한다 + @IsString() + month!: string; +} diff --git a/src/features/order/dto/inputs/admin-settlement-list.input.ts b/src/features/order/dto/inputs/admin-settlement-list.input.ts new file mode 100644 index 00000000..f9ecb781 --- /dev/null +++ b/src/features/order/dto/inputs/admin-settlement-list.input.ts @@ -0,0 +1,19 @@ +import { IsEnum, IsOptional, IsString } from 'class-validator'; + +import { CursorInput } from '@/common/dto/inputs/cursor.input'; +import { SettlementStatus } from '@/generated/prisma/client'; + +export class AdminSettlementListInput extends CursorInput { + @IsOptional() + @IsEnum(SettlementStatus) + status?: SettlementStatus; + + @IsOptional() + @IsString() + storeId?: string; + + // 형식(YYYY-MM-DD)은 서비스가 INVALID_DATE로 거절한다 + @IsOptional() + @IsString() + periodStart?: string; +} diff --git a/src/features/order/dto/inputs/seller-settlement-list.input.ts b/src/features/order/dto/inputs/seller-settlement-list.input.ts new file mode 100644 index 00000000..c71b10b9 --- /dev/null +++ b/src/features/order/dto/inputs/seller-settlement-list.input.ts @@ -0,0 +1,3 @@ +import { CursorInput } from '@/common/dto/inputs/cursor.input'; + +export class SellerSettlementListInput extends CursorInput {} diff --git a/src/features/order/events/settlement-created.event.spec.ts b/src/features/order/events/settlement-created.event.spec.ts new file mode 100644 index 00000000..b66896c9 --- /dev/null +++ b/src/features/order/events/settlement-created.event.spec.ts @@ -0,0 +1,55 @@ +import { + parseSettlementCreatedPayload, + SETTLEMENT_CREATED, + settlementCreatedEvent, +} from '@/features/order/events/settlement-created.event'; +import type { Prisma } from '@/generated/prisma/client'; + +const VALID = { + settlementId: '5', + storeId: '9', + storeName: '해즈 케이크', + periodStart: '2026-11-09', + periodEnd: '2026-11-15', + orderCount: 3, + settlementBaseAmount: 90_000, + commissionAmount: 4_995, + payoutAmount: 85_005, +}; + +describe('settlement.created 이벤트', () => { + it('정산 단위 aggregate에 묶고 시스템 행위(행위자 없음)다', () => { + const occurredAt = new Date('2026-11-15T20:00:00.000Z'); + const event = settlementCreatedEvent(VALID, occurredAt); + + expect(event).toEqual({ + aggregateType: 'settlement', + aggregateId: '5', + eventType: SETTLEMENT_CREATED, + payload: VALID, + occurredAt, + actorAccountId: null, + }); + expect( + parseSettlementCreatedPayload(event.payload as Prisma.JsonValue), + ).toEqual(VALID); + }); + + it.each([ + ['null', null], + ['배열', [VALID]], + ['settlementId 숫자', { ...VALID, settlementId: 5 }], + ['storeName 누락', { ...VALID, storeName: undefined }], + [ + 'periodStart 시각 형식', + { ...VALID, periodStart: '2026-11-09T00:00:00Z' }, + ], + ['periodEnd 누락', { ...VALID, periodEnd: undefined }], + ['orderCount 문자열', { ...VALID, orderCount: '3' }], + ['payoutAmount 소수', { ...VALID, payoutAmount: 1.5 }], + ])('반증: %s payload는 던진다', (_label, payload) => { + expect(() => + parseSettlementCreatedPayload(payload as Prisma.JsonValue), + ).toThrow('payload 형식 오류'); + }); +}); diff --git a/src/features/order/events/settlement-created.event.ts b/src/features/order/events/settlement-created.event.ts new file mode 100644 index 00000000..46f4bac4 --- /dev/null +++ b/src/features/order/events/settlement-created.event.ts @@ -0,0 +1,72 @@ +import type { OutboxEventInput } from '@/features/outbox'; +import type { Prisma } from '@/generated/prisma/client'; + +/** 주간 정산 생성(매장별). 관리자 '정산 송금' 알림의 원천이다. */ +export const SETTLEMENT_CREATED = 'settlement.created'; + +export interface SettlementCreatedPayload { + settlementId: string; + storeId: string; + storeName: string; + /** 정산 기간(KST 월~일), YYYY-MM-DD */ + periodStart: string; + periodEnd: string; + orderCount: number; + settlementBaseAmount: number; + commissionAmount: number; + payoutAmount: number; +} + +export function settlementCreatedEvent( + payload: SettlementCreatedPayload, + occurredAt: Date, +): OutboxEventInput { + return { + aggregateType: 'settlement', + aggregateId: payload.settlementId, + eventType: SETTLEMENT_CREATED, + payload: { ...payload }, + occurredAt, + actorAccountId: null, + }; +} + +const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/; +const AMOUNT_KEYS = [ + 'orderCount', + 'settlementBaseAmount', + 'commissionAmount', + 'payoutAmount', +] as const; + +export function parseSettlementCreatedPayload( + value: Prisma.JsonValue, +): SettlementCreatedPayload { + const p = value as Partial>; + if ( + typeof value !== 'object' || + value === null || + Array.isArray(value) || + typeof p.settlementId !== 'string' || + typeof p.storeId !== 'string' || + typeof p.storeName !== 'string' || + typeof p.periodStart !== 'string' || + !DATE_ONLY.test(p.periodStart) || + typeof p.periodEnd !== 'string' || + !DATE_ONLY.test(p.periodEnd) || + AMOUNT_KEYS.some((key) => !Number.isSafeInteger(p[key])) + ) { + throw new Error(`${SETTLEMENT_CREATED} payload 형식 오류`); + } + return { + settlementId: p.settlementId, + storeId: p.storeId, + storeName: p.storeName, + periodStart: p.periodStart, + periodEnd: p.periodEnd, + orderCount: p.orderCount as number, + settlementBaseAmount: p.settlementBaseAmount as number, + commissionAmount: p.commissionAmount as number, + payoutAmount: p.payoutAmount as number, + }; +} diff --git a/src/features/order/order-admin.graphql b/src/features/order/order-admin.graphql index 69730da3..376ece4b 100644 --- a/src/features/order/order-admin.graphql +++ b/src/features/order/order-admin.graphql @@ -253,6 +253,31 @@ type AdminOrderDetail { 판매자 픽업 일시 변경 이력. 오래된 순, 없으면 빈 배열. """ pickupChanges: [OrderPickupChange!]! + """ + 주문 생성 시점의 수수료율(bp, 1bp = 0.01%). 바뀐 설정은 그 뒤 주문부터 적용된다. + """ + commissionRateBps: Int! + """ + 정산 예정 금액(원). 정산 확정 뒤에는 실제 지급액(기준액 − 수수료), 확정 전에는 결제 금액에서 수수료(원 미만 버림)를 뺀 + 예상값이다. 입금이 확인되지 않았거나 결제 도입 전 주문이면 null, 확정 없이 취소된 주문(전액 환불)은 0. + """ + expectedPayoutAmount: Int + """ + 확정된 수수료 기준액(원). 픽업 완료·노쇼는 결제 금액, 구매자 사정 취소는 결제 금액 − 환불 금액. 확정 전이면 null. + """ + settlementBaseAmount: Int + """ + 확정된 수수료(원). 기준액 × 수수료율, 원 미만 버림. 확정 전이면 null. + """ + commissionAmount: Int + """ + 정산 확정 시각. 확정 전이면 null. + """ + settlementFinalizedAt: DateTime + """ + 이 주문이 묶인 주간 정산(adminSettlement). 아직 묶이지 않았으면 null. + """ + settlementId: ID } """ diff --git a/src/features/order/order-deposit-admin.graphql b/src/features/order/order-deposit-admin.graphql index fed915d9..1ab5556b 100644 --- a/src/features/order/order-deposit-admin.graphql +++ b/src/features/order/order-deposit-admin.graphql @@ -140,6 +140,10 @@ type AdminTaskCounts { 계좌가 들어와 송금을 기다리는 환불 수(adminRefunds status=AWAITING_TRANSFER의 totalCount). """ refundsAwaitingTransfer: Int! + """ + 송금을 기다리는 주간 정산 수(adminSettlements status=PENDING의 totalCount). + """ + pendingSettlements: Int! } """ diff --git a/src/features/order/order-seller.graphql b/src/features/order/order-seller.graphql index 7b0965ad..64102e87 100644 --- a/src/features/order/order-seller.graphql +++ b/src/features/order/order-seller.graphql @@ -256,6 +256,23 @@ type SellerOrderDetail { 픽업 일시 변경 이력. 오래된 순, 없으면 빈 배열. """ pickupChanges: [OrderPickupChange!]! + """ + 주문 생성 시점의 수수료율(bp, 1bp = 0.01%). 바뀐 설정은 그 뒤 주문부터 적용된다. + """ + commissionRateBps: Int! + """ + 정산 예정 금액(원). 정산 확정 뒤에는 실제 지급액(기준액 − 수수료), 확정 전에는 결제 금액에서 수수료(원 미만 버림)를 뺀 + 예상값이다. 입금이 확인되지 않았거나 결제 도입 전 주문이면 null, 확정 없이 취소된 주문(전액 환불)은 0. + """ + expectedPayoutAmount: Int + """ + 확정된 수수료 기준액(원). 픽업 완료·노쇼는 결제 금액, 구매자 사정 취소는 결제 금액 − 환불 금액. 확정 전이면 null. + """ + settlementBaseAmount: Int + """ + 확정된 수수료(원). 기준액 × 수수료율, 원 미만 버림. 확정 전이면 null. + """ + commissionAmount: Int } """ diff --git a/src/features/order/order-settlement-admin.graphql b/src/features/order/order-settlement-admin.graphql new file mode 100644 index 00000000..4a98c577 --- /dev/null +++ b/src/features/order/order-settlement-admin.graphql @@ -0,0 +1,266 @@ +extend type Query { + """ + 주간 정산 목록. 최근 생성 순. 매주 월요일 05:00(KST)에 지난주(월~일)까지 정산이 확정된 주문을 매장별로 묶어 만든다. + 날짜 형식이 어긋나면 INVALID_DATE(BAD_USER_INPUT). 관리자 로그인 필수. ADMIN 계정이 아니면 FORBIDDEN. + """ + adminSettlements(input: AdminSettlementListInput): AdminSettlementConnection! + """ + 주간 정산 1건과 포함 주문·현재 매장 정산 계좌(원문). 없으면 NOT_FOUND(SETTLEMENT_NOT_FOUND). + 관리자 로그인 필수. ADMIN 계정이 아니면 FORBIDDEN. + """ + adminSettlement(settlementId: ID!): AdminSettlementDetail! + """ + 월 수수료 집계. 정산 확정 시각의 KST 월로 매장별 주문 수·기준액·수수료를 묶는다(주간 정산 여부와 무관). + 월 형식이 어긋나면 INVALID_YEAR_MONTH(BAD_USER_INPUT). 관리자 로그인 필수. ADMIN 계정이 아니면 FORBIDDEN. + """ + adminMonthlyCommissions( + input: AdminMonthlyCommissionInput! + ): AdminMonthlyCommissionReport! +} + +extend type Mutation { + """ + 은행 앱에서 매장 정산 계좌로 송금한 뒤 송금 완료로 처리한다. 그 시점 매장 정산 계좌를 송금 계좌로 남기고 감사 로그(SETTLEMENT)를 쓴다. + 이미 송금 완료면 SETTLEMENT_ALREADY_PAID(CONFLICT), 매장 정산 계좌가 없으면 SETTLEMENT_ACCOUNT_REQUIRED(BAD_USER_INPUT), + 메모가 500자를 넘으면 TEXT_TOO_LONG, 없는 정산이면 NOT_FOUND. 관리자 로그인 필수. ADMIN 계정이 아니면 FORBIDDEN. + """ + adminMarkSettlementPaid( + input: AdminMarkSettlementPaidInput! + ): AdminSettlementDetail! +} + +""" +주간 정산 목록 조회 조건. 모든 필터는 AND로 결합된다. +""" +input AdminSettlementListInput { + """ + 한 번에 가져올 개수. 기본 20, 1~100만 허용하며 벗어나면 BAD_USER_INPUT. + """ + limit: Int = 20 + """ + 이전 응답의 nextCursor. 첫 페이지는 생략한다. 필터를 바꾸면 커서를 버리고 첫 페이지부터 다시 조회한다. + """ + cursor: String + """ + 송금 상태 필터. null이면 전체. + """ + status: SettlementStatusType + """ + 매장 필터. null이면 전체. + """ + storeId: ID + """ + 정산 기간 시작일(월요일, KST, YYYY-MM-DD) 필터. 관리자 알림 링크의 periodStart와 같다. null이면 전체. + """ + periodStart: String +} + +""" +주간 정산 1건(관리자 시점). +""" +type AdminSettlementSummary { + id: ID! + storeId: ID! + """ + 매장명(정산에 묶인 가장 최근 주문의 스냅샷). + """ + storeName: String! + """ + 정산 기간 시작일(월요일, KST). YYYY-MM-DD. + """ + periodStart: String! + """ + 정산 기간 마지막 날(일요일, KST). YYYY-MM-DD. + """ + periodEnd: String! + """ + 포함 주문 수. 앞 정산에서 빠진 주문(늦게 확정된 주문)도 함께 묶인다. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! + """ + 송금할 금액(원) = 기준액 합계 − 수수료 합계. + """ + payoutAmount: Int! + """ + 송금 상태. + """ + status: SettlementStatusType! + """ + 송금 완료 시각. 송금 전이면 null. + """ + paidAt: DateTime + """ + 지금 매장 정산 계좌가 등록돼 있는지. false면 송금 완료로 처리할 수 없다. + """ + accountRegistered: Boolean! + createdAt: DateTime! +} + +""" +주간 정산 목록 페이지. +""" +type AdminSettlementConnection { + """ + 주간 정산. 최근 생성 순. + """ + items: [AdminSettlementSummary!]! + """ + 조건에 맞는 전체 건수(현재 페이지와 무관). 커서 필터는 제외하고 센다. + """ + totalCount: Int! + """ + 다음 페이지 존재 여부. + """ + hasMore: Boolean! + """ + 다음 페이지 커서. null이면 마지막 페이지다. + """ + nextCursor: String +} + +""" +주간 정산 상세(관리자 시점). 현재 계좌 원문이 들어 있으니 화면 밖(로그·분석 이벤트)에 남기지 않는다. +""" +type AdminSettlementDetail { + id: ID! + storeId: ID! + """ + 매장명(정산에 묶인 가장 최근 주문의 스냅샷). + """ + storeName: String! + """ + 정산 기간 시작일(월요일, KST). YYYY-MM-DD. + """ + periodStart: String! + """ + 정산 기간 마지막 날(일요일, KST). YYYY-MM-DD. + """ + periodEnd: String! + """ + 포함 주문 수. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! + """ + 송금할 금액(원) = 기준액 합계 − 수수료 합계. + """ + payoutAmount: Int! + """ + 송금 상태. + """ + status: SettlementStatusType! + """ + 송금 완료 시각. 송금 전이면 null. + """ + paidAt: DateTime + """ + 지금 매장 정산 계좌가 등록돼 있는지(currentAccount가 있는지). + """ + accountRegistered: Boolean! + createdAt: DateTime! + """ + 송금 완료로 처리한 관리자 표시 이름(처리 시점 스냅샷). 송금 전이거나 이름이 없으면 null. + """ + paidByLabel: String + """ + 송금 메모. 없으면 null. + """ + paidNote: String + """ + 송금한 계좌(송금 시점 스냅샷, 끝 4자리만). 송금 전이면 null. + """ + paidAccount: SettlementPaidAccount + """ + 지금 매장 정산 계좌(계좌번호 원문 포함). 송금할 때 쓴다. 등록 전이면 null. + """ + currentAccount: AdminStoreSettlementAccount + """ + 포함 주문. 주문 id 순. + """ + orders: [SettlementOrder!]! +} + +""" +송금 완료 입력. +""" +input AdminMarkSettlementPaidInput { + settlementId: ID! + """ + 송금 메모(선택, 500자 이하). 정산과 감사 로그에 남는다. + """ + note: String +} + +""" +월 수수료 집계 조건. +""" +input AdminMonthlyCommissionInput { + """ + 집계 월(KST). "YYYY-MM" 형식. 예: "2026-11". + """ + month: String! +} + +""" +월 수수료 집계. +""" +type AdminMonthlyCommissionReport { + """ + 집계 월. "YYYY-MM". + """ + month: String! + """ + 정산이 확정된 주문 수 합계. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! + """ + 매장별 집계. 매장 id 순, 확정 주문이 없는 매장은 빠진다. + """ + stores: [AdminMonthlyCommissionStore!]! +} + +""" +매장 1곳의 월 수수료. +""" +type AdminMonthlyCommissionStore { + storeId: ID! + """ + 매장명(그 달 가장 최근 확정 주문의 스냅샷). + """ + storeName: String! + """ + 정산이 확정된 주문 수. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! +} diff --git a/src/features/order/order-settlement-seller.graphql b/src/features/order/order-settlement-seller.graphql index 74627014..ad07a734 100644 --- a/src/features/order/order-settlement-seller.graphql +++ b/src/features/order/order-settlement-seller.graphql @@ -4,6 +4,140 @@ extend type Query { 판매자 로그인 필수. SELLER 계정이 아니면 FORBIDDEN, 매장을 보유하지 않으면 NOT_FOUND. """ sellerSettlementAccount: SellerSettlementAccount + """ + 내 매장 주간 정산 내역. 최근 생성 순(매주 월요일에 지난주분이 생긴다). + 판매자 로그인 필수. SELLER 계정이 아니면 FORBIDDEN, 매장을 보유하지 않으면 NOT_FOUND. + """ + sellerSettlements(input: SellerSettlementListInput): SellerSettlementConnection! + """ + 내 매장 주간 정산 1건과 포함 주문. 다른 매장 정산이거나 없으면 NOT_FOUND(SETTLEMENT_NOT_FOUND). + 판매자 로그인 필수. SELLER 계정이 아니면 FORBIDDEN, 매장을 보유하지 않으면 NOT_FOUND. + """ + sellerSettlement(settlementId: ID!): SellerSettlementDetail! +} + +""" +주간 정산 목록 조회 조건. +""" +input SellerSettlementListInput { + """ + 한 번에 가져올 개수. 기본 20, 1~100만 허용하며 벗어나면 BAD_USER_INPUT. + """ + limit: Int = 20 + """ + 이전 응답의 nextCursor. 첫 페이지는 생략한다. + """ + cursor: String +} + +""" +주간 정산 1건(판매자 시점). 월~일(KST) 동안 정산이 확정된 주문(그 전에 빠진 주문 포함)을 묶는다. +""" +type SellerSettlementSummary { + id: ID! + """ + 정산 기간 시작일(월요일, KST). YYYY-MM-DD. + """ + periodStart: String! + """ + 정산 기간 마지막 날(일요일, KST). YYYY-MM-DD. + """ + periodEnd: String! + """ + 포함 주문 수. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! + """ + 정산 금액(원) = 기준액 합계 − 수수료 합계. 케이퀵이 매장 정산 계좌로 보내는 금액이다. + """ + payoutAmount: Int! + """ + 송금 여부. PENDING이면 송금 대기, PAID면 송금 완료. + """ + status: SettlementStatusType! + """ + 송금 완료 시각. 송금 전이면 null. + """ + paidAt: DateTime + createdAt: DateTime! +} + +""" +주간 정산 목록 페이지. +""" +type SellerSettlementConnection { + """ + 주간 정산. 최근 생성 순. + """ + items: [SellerSettlementSummary!]! + """ + 전체 건수(현재 페이지와 무관). + """ + totalCount: Int! + """ + 다음 페이지 존재 여부. + """ + hasMore: Boolean! + """ + 다음 페이지 커서. null이면 마지막 페이지다. + """ + nextCursor: String +} + +""" +주간 정산 상세(판매자 시점). +""" +type SellerSettlementDetail { + id: ID! + """ + 정산 기간 시작일(월요일, KST). YYYY-MM-DD. + """ + periodStart: String! + """ + 정산 기간 마지막 날(일요일, KST). YYYY-MM-DD. + """ + periodEnd: String! + """ + 포함 주문 수. + """ + orderCount: Int! + """ + 수수료 기준액 합계(원). + """ + settlementBaseAmount: Int! + """ + 수수료 합계(원). + """ + commissionAmount: Int! + """ + 정산 금액(원) = 기준액 합계 − 수수료 합계. + """ + payoutAmount: Int! + """ + 송금 여부. + """ + status: SettlementStatusType! + """ + 송금 완료 시각. 송금 전이면 null. + """ + paidAt: DateTime + createdAt: DateTime! + """ + 송금한 계좌(송금 시점 스냅샷, 끝 4자리만). 송금 전이면 null. + """ + paidAccount: SettlementPaidAccount + """ + 포함 주문. 주문 id 순. + """ + orders: [SettlementOrder!]! } extend type Mutation { diff --git a/src/features/order/order.module.ts b/src/features/order/order.module.ts index 28c9692b..199a9584 100644 --- a/src/features/order/order.module.ts +++ b/src/features/order/order.module.ts @@ -19,6 +19,7 @@ import { OrderRepository } from '@/features/order/repositories/order.repository' import { PaymentSettingRepository } from '@/features/order/repositories/payment-setting.repository'; import { PaymentRepository } from '@/features/order/repositories/payment.repository'; import { RefundRepository } from '@/features/order/repositories/refund.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; import { AdminOrderMutationResolver } from '@/features/order/resolvers/order-admin-mutation.resolver'; import { AdminOrderQueryResolver } from '@/features/order/resolvers/order-admin-query.resolver'; @@ -36,6 +37,8 @@ import { SellerOrderMutationResolver } from '@/features/order/resolvers/order-se import { SellerOrderPickupMutationResolver } from '@/features/order/resolvers/order-seller-pickup-mutation.resolver'; import { SellerOrderPickupQueryResolver } from '@/features/order/resolvers/order-seller-pickup-query.resolver'; import { SellerOrderQueryResolver } from '@/features/order/resolvers/order-seller-query.resolver'; +import { AdminSettlementMutationResolver } from '@/features/order/resolvers/order-settlement-admin-mutation.resolver'; +import { AdminSettlementQueryResolver } from '@/features/order/resolvers/order-settlement-admin-query.resolver'; import { SellerSettlementMutationResolver } from '@/features/order/resolvers/order-settlement-seller-mutation.resolver'; import { SellerSettlementQueryResolver } from '@/features/order/resolvers/order-settlement-seller-query.resolver'; import { OrderSubscriptionResolver } from '@/features/order/resolvers/order-subscription.resolver'; @@ -52,7 +55,9 @@ import { AdminPaymentService } from '@/features/order/services/order-payment-adm import { AdminRefundService } from '@/features/order/services/order-refund-admin.service'; import { SellerOrderPickupService } from '@/features/order/services/order-seller-pickup.service'; import { SellerOrderService } from '@/features/order/services/order-seller.service'; +import { AdminSettlementService } from '@/features/order/services/order-settlement-admin.service'; import { SellerSettlementService } from '@/features/order/services/order-settlement-seller.service'; +import { SettlementScheduler } from '@/features/order/services/order-settlement.scheduler'; import { OrderStoreDailyLimitConsumer } from '@/features/order/services/order-store-daily-limit.consumer'; import { OrderSubscriptionService } from '@/features/order/services/order-subscription.service'; import { OutboxModule } from '@/features/outbox'; @@ -127,7 +132,7 @@ import { StoreModule } from '@/features/store'; provide: WithdrawalBlockingOrderQuery, useClass: OrderWithdrawalBlockingRepository, }, - // 입금 대기·'입금했어요'·환불 송금 대기 관리자 디스코드 알림(worker 소비자) + // 입금 대기·'입금했어요'·환불 송금 대기·주간 정산 관리자 디스코드 알림(worker 소비자) OrderAdminAlertConsumer, // 결제 설정·매장 정산 계좌(계좌번호는 global AccountCipher로 암호화) PaymentSettingRepository, @@ -141,6 +146,12 @@ import { StoreModule } from '@/features/store'; SellerSettlementMutationResolver, // 채팅 주문 카드·숨김 매장 문의 판정(conversation) OrderInquiryRepository, + // 주간 정산(worker 크론·부팅 1회)과 관리자 송금 완료·월 수수료, 판매자 정산 내역 + SettlementRepository, + SettlementScheduler, + AdminSettlementService, + AdminSettlementQueryResolver, + AdminSettlementMutationResolver, ], exports: [ OrderRepository, diff --git a/src/features/order/order.types.graphql b/src/features/order/order.types.graphql index 278e17ba..a322dbb8 100644 --- a/src/features/order/order.types.graphql +++ b/src/features/order/order.types.graphql @@ -127,6 +127,73 @@ enum RefundStatusType { COMPLETED } +""" +주간 정산 상태. 값은 늘어날 수 있으니 모르는 값을 받아도 화면이 죽지 않게 처리한다. +""" +enum SettlementStatusType { + """케이퀵의 매장 송금 대기.""" + PENDING + """송금 완료.""" + PAID +} + +""" +정산을 송금한 계좌(송금 시점 스냅샷). 계좌번호는 끝 4자리만 내려준다. +""" +type SettlementPaidAccount { + """ + 은행. + """ + bank: Bank! + """ + 예금주. + """ + accountHolder: String! + """ + 끝 4자리만 남긴 계좌번호(예: ****1234). + """ + accountNumberMasked: String! +} + +""" +주간 정산에 묶인 주문 1건. +""" +type SettlementOrder { + orderId: ID! + """ + 주문번호. + """ + orderNumber: String! + """ + 상품명(주문 시점 스냅샷). 품목이 없으면 null. + """ + productName: String + """ + 주문 상태(픽업 완료·노쇼, 구매자 사정 취소의 남은 금액이면 취소). + """ + status: OrderStatusType! + """ + 주문 생성 시점의 수수료율(bp, 1bp = 0.01%). + """ + commissionRateBps: Int! + """ + 수수료 기준액(원). 결제 금액, 구매자 사정 취소면 결제 금액 − 환불 금액. + """ + settlementBaseAmount: Int! + """ + 수수료(원). 기준액 × 수수료율, 원 미만 버림. + """ + commissionAmount: Int! + """ + 매장 지급액(원) = 기준액 − 수수료. + """ + payoutAmount: Int! + """ + 정산 확정 시각(픽업 완료·노쇼·구매자 사정 취소 시각). 이 시각이 속한 주(월~일, KST)가 끝난 뒤 첫 주간 정산에 묶인다. + """ + settlementFinalizedAt: DateTime! +} + """ 주문 취소 정보. 취소된 주문에만 있다. """ diff --git a/src/features/order/repositories/order.repository.ts b/src/features/order/repositories/order.repository.ts index 767b4ce9..575aa347 100644 --- a/src/features/order/repositories/order.repository.ts +++ b/src/features/order/repositories/order.repository.ts @@ -863,7 +863,7 @@ export class OrderRepository { }, // 유저측 상세(findOrderDetailByUser)와 동일하게 soft-delete 자식을 가드한다 include: { - payment: { select: { method: true } }, + payment: { select: { method: true, amount: true, confirmed_at: true } }, // 입금 반환은 구매자와 플랫폼 사이 일이라 취소 환불만 본다 refunds: { where: { kind: RefundKind.CANCEL } }, pickup_changes: pickupChangesInclude, diff --git a/src/features/order/repositories/settlement.repository.ts b/src/features/order/repositories/settlement.repository.ts new file mode 100644 index 00000000..4ee2361d --- /dev/null +++ b/src/features/order/repositories/settlement.repository.ts @@ -0,0 +1,309 @@ +import { Inject, Injectable } from '@nestjs/common'; + +import { formatDateOnly } from '@/common/utils/kst-time'; +import { + AUDIT_LOG_REPOSITORY, + type IAuditLogRepository, +} from '@/features/audit-log'; +import { settlementCreatedEvent } from '@/features/order/events/settlement-created.event'; +import { OutboxPublisher } from '@/features/outbox'; +import { + AuditActionType, + AuditTargetType, + Prisma, + SettlementStatus, + type Settlement, +} from '@/generated/prisma/client'; +import { activeWhere, PrismaService } from '@/prisma'; + +/** 정산 매장은 주문의 첫 품목(남은 품목 중 id가 가장 작은 것)이 정한다 — 주문 1건 = 매장 1곳. */ +const FIRST_ITEM_JOIN = Prisma.sql`JOIN order_item oi ON oi.id = ( + SELECT MIN(i.id) FROM order_item i WHERE i.order_id = o.id AND i.deleted_at IS NULL)`; + +/** 정산이 확정됐지만 아직 주간 정산에 묶이지 않은 주문. raw라 deleted_at을 직접 건다. */ +function unsettledBefore(before: Date): Prisma.Sql { + return Prisma.sql`o.settlement_finalized_at < ${before} + AND o.settlement_id IS NULL AND o.settlement_base_amount > 0 + AND o.deleted_at IS NULL`; +} + +export const settlementDetailInclude = { + orders: { + where: activeWhere, + orderBy: { id: 'asc' }, + select: { + id: true, + order_number: true, + status: true, + commission_rate_bps: true, + settlement_base_amount: true, + commission_amount: true, + settlement_finalized_at: true, + items: { + where: activeWhere, + orderBy: { id: 'asc' }, + take: 1, + select: { product_name_snapshot: true }, + }, + }, + }, +} satisfies Prisma.SettlementInclude; + +export type SettlementDetailRow = Prisma.SettlementGetPayload<{ + include: typeof settlementDetailInclude; +}>; + +export interface SettlementListFilter { + storeId?: bigint; + status?: SettlementStatus; + /** `@db.Date` 값 */ + periodStart?: Date; +} + +export type MarkSettlementPaidResult = + | { kind: 'paid' } + | { kind: 'not-found' } + | { kind: 'already-paid' } + | { kind: 'account-required' }; + +export interface MonthlyCommissionRow { + storeId: bigint; + storeName: string; + orderCount: number; + settlementBaseAmount: number; + commissionAmount: number; +} + +@Injectable() +export class SettlementRepository { + constructor( + private readonly prisma: PrismaService, + private readonly outbox: OutboxPublisher, + @Inject(AUDIT_LOG_REPOSITORY) + private readonly auditLogs: IAuditLogRepository, + ) {} + + async findUnsettledStoreIds(before: Date): Promise { + const rows = await this.prisma.$queryRaw<{ store_id: bigint }[]>` + SELECT DISTINCT oi.store_id FROM \`order\` o ${FIRST_ITEM_JOIN} + WHERE ${unsettledBefore(before)} + ORDER BY oi.store_id`; + return rows.map((row) => row.store_id); + } + + /** + * 한 매장의 주간 정산. 주문 행을 id 순으로 잠근 뒤 다시 골라 합계를 내고, 정산 행·주문 연결·outbox를 한 tx에 남긴다. + * 그 기간 정산이 이미 있거나(재실행) 묶을 주문이 없으면 만들지 않는다 — 남은 주문은 다음 주 정산에 들어간다. + */ + async createWeeklySettlement(args: { + storeId: bigint; + /** 이 시각 전에 확정된 주문을 묶는다(이번 주 월요일 00:00 KST) */ + settledBefore: Date; + periodStart: Date; + periodEnd: Date; + now: Date; + }): Promise { + return this.prisma.$transaction(async (tx) => { + const orders = await tx.$queryRaw< + { id: bigint; base: bigint; commission: bigint; store_name: string }[] + >` + SELECT o.id, o.settlement_base_amount AS base, COALESCE(o.commission_amount, 0) AS commission, + oi.store_name_snapshot AS store_name + FROM \`order\` o ${FIRST_ITEM_JOIN} + WHERE ${unsettledBefore(args.settledBefore)} AND oi.store_id = ${args.storeId} + ORDER BY o.id + FOR UPDATE OF o`; + if (orders.length === 0) return null; + const existing = await tx.settlement.findUnique({ + where: { + store_id_period_start: { + store_id: args.storeId, + period_start: args.periodStart, + }, + }, + select: { id: true }, + }); + if (existing) return null; + + // raw는 INT UNSIGNED를 bigint로 돌려준다 + const base = orders.reduce((sum, o) => sum + Number(o.base), 0); + const commission = orders.reduce( + (sum, o) => sum + Number(o.commission), + 0, + ); + const settlement = await tx.settlement.create({ + data: { + store_id: args.storeId, + // 가장 최근 주문의 매장명 + store_name_snapshot: orders[orders.length - 1].store_name, + period_start: args.periodStart, + period_end: args.periodEnd, + order_count: orders.length, + settlement_base_amount: base, + commission_amount: commission, + payout_amount: base - commission, + }, + }); + await tx.order.updateMany({ + where: { id: { in: orders.map((o) => o.id) } }, + data: { settlement_id: settlement.id }, + }); + await this.outbox.publish( + tx, + settlementCreatedEvent( + { + settlementId: settlement.id.toString(), + storeId: args.storeId.toString(), + storeName: settlement.store_name_snapshot, + periodStart: formatDateOnly(args.periodStart), + periodEnd: formatDateOnly(args.periodEnd), + orderCount: settlement.order_count, + settlementBaseAmount: base, + commissionAmount: commission, + payoutAmount: settlement.payout_amount, + }, + args.now, + ), + ); + return settlement; + }); + } + + private listWhere(filter: SettlementListFilter): Prisma.SettlementWhereInput { + return { + ...(filter.storeId !== undefined ? { store_id: filter.storeId } : {}), + ...(filter.status ? { status: filter.status } : {}), + ...(filter.periodStart ? { period_start: filter.periodStart } : {}), + }; + } + + /** 최근 생성 순(id 내림차순). */ + async list( + filter: SettlementListFilter & { limit: number; cursor?: bigint }, + ): Promise { + return this.prisma.settlement.findMany({ + where: { + ...this.listWhere(filter), + ...(filter.cursor !== undefined ? { id: { lt: filter.cursor } } : {}), + }, + orderBy: { id: 'desc' }, + take: filter.limit + 1, + }); + } + + async count(filter: SettlementListFilter): Promise { + return this.prisma.settlement.count({ where: this.listWhere(filter) }); + } + + /** storeId를 주면 그 매장 정산만 찾는다. */ + async findDetail( + settlementId: bigint, + storeId?: bigint, + ): Promise { + return this.prisma.settlement.findFirst({ + where: { + id: settlementId, + ...(storeId !== undefined ? { store_id: storeId } : {}), + }, + include: settlementDetailInclude, + }); + } + + /** + * 송금 완료. 그 시점 매장 정산 계좌를 paid_*에 옮겨 적는다(암호문은 같은 용도 키라 그대로 복사). + * 감사에는 끝 4자리만 남긴다. + */ + async markPaid(args: { + settlementId: bigint; + actorAccountId: bigint; + actorLabel: string | null; + note: string | null; + now: Date; + }): Promise { + return this.prisma.$transaction(async (tx) => { + const [locked] = await tx.$queryRaw< + { id: bigint; store_id: bigint; status: SettlementStatus }[] + >`SELECT id, store_id, status FROM settlement WHERE id = ${args.settlementId} FOR UPDATE`; + if (!locked) return { kind: 'not-found' }; + if (locked.status !== SettlementStatus.PENDING) { + return { kind: 'already-paid' }; + } + const account = await tx.storeSettlementAccount.findUnique({ + where: { store_id: locked.store_id }, + }); + if (!account) return { kind: 'account-required' }; + + const paid = await tx.settlement.update({ + where: { id: locked.id }, + data: { + status: SettlementStatus.PAID, + paid_at: args.now, + paid_by_account_id: args.actorAccountId, + paid_by_label_snapshot: args.actorLabel, + paid_note: args.note, + paid_bank_code: account.bank_code, + paid_account_holder: account.account_holder, + paid_account_number_enc: account.account_number_enc, + paid_account_last4: account.account_number_last4, + }, + }); + await this.auditLogs.recordAudit(tx, { + actorAccountId: args.actorAccountId, + storeId: locked.store_id, + targetType: AuditTargetType.SETTLEMENT, + targetId: locked.id, + action: AuditActionType.STATUS_CHANGE, + beforeJson: { status: SettlementStatus.PENDING }, + afterJson: { + status: SettlementStatus.PAID, + payoutAmount: paid.payout_amount, + bank_code: account.bank_code, + account_holder: account.account_holder, + account_number_last4: account.account_number_last4, + note: args.note, + }, + }); + return { kind: 'paid' }; + }); + } + + async countPending(): Promise { + return this.prisma.settlement.count({ + where: { status: SettlementStatus.PENDING }, + }); + } + + /** [from, to)에 정산이 확정된 주문을 매장별로 묶는다. 매장명은 그 달 가장 최근 주문의 것. */ + async monthlyCommissions( + from: Date, + to: Date, + ): Promise { + const rows = await this.prisma.$queryRaw< + { + store_id: bigint; + store_name: string; + order_count: bigint; + base: bigint; + commission: bigint; + }[] + >` + SELECT t.store_id, t.store_name, COUNT(*) AS order_count, + CAST(SUM(t.base) AS UNSIGNED) AS base, CAST(SUM(t.commission) AS UNSIGNED) AS commission + FROM ( + SELECT oi.store_id, o.settlement_base_amount AS base, COALESCE(o.commission_amount, 0) AS commission, + FIRST_VALUE(oi.store_name_snapshot) OVER (PARTITION BY oi.store_id ORDER BY o.id DESC) AS store_name + FROM \`order\` o ${FIRST_ITEM_JOIN} + WHERE o.settlement_finalized_at >= ${from} AND o.settlement_finalized_at < ${to} + AND o.settlement_base_amount > 0 AND o.deleted_at IS NULL + ) t + GROUP BY t.store_id, t.store_name + ORDER BY t.store_id`; + return rows.map((row) => ({ + storeId: row.store_id, + storeName: row.store_name, + orderCount: Number(row.order_count), + settlementBaseAmount: Number(row.base), + commissionAmount: Number(row.commission), + })); + } +} diff --git a/src/features/order/repositories/store-settlement-account.repository.ts b/src/features/order/repositories/store-settlement-account.repository.ts index e0641489..e8519d91 100644 --- a/src/features/order/repositories/store-settlement-account.repository.ts +++ b/src/features/order/repositories/store-settlement-account.repository.ts @@ -38,6 +38,15 @@ export class StoreSettlementAccountRepository { }); } + async findStoreIdsWithAccount(storeIds: bigint[]): Promise> { + if (storeIds.length === 0) return new Set(); + const rows = await this.prisma.storeSettlementAccount.findMany({ + where: { store_id: { in: storeIds } }, + select: { store_id: true }, + }); + return new Set(rows.map((row) => row.store_id)); + } + /** * 매장당 1행. 판매자 본인·관리자 대리 수정이 같은 경로다. 계좌번호는 암호문과 끝 4자리로만 저장하고, * 감사는 매장 ID를 달아 판매자 감사 로그에도 보인다. diff --git a/src/features/order/resolvers/order-deposit-admin.resolver.spec.ts b/src/features/order/resolvers/order-deposit-admin.resolver.spec.ts index fccc3110..b8441136 100644 --- a/src/features/order/resolvers/order-deposit-admin.resolver.spec.ts +++ b/src/features/order/resolvers/order-deposit-admin.resolver.spec.ts @@ -8,6 +8,7 @@ import { AccountAdminRepository } from '@/features/auth/repositories/account-adm import { OrderTransitionRepository } from '@/features/order/repositories/order-transition.repository'; import { PaymentRepository } from '@/features/order/repositories/payment.repository'; import { RefundRepository } from '@/features/order/repositories/refund.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { AdminDepositMutationResolver } from '@/features/order/resolvers/order-deposit-admin-mutation.resolver'; import { AdminDepositQueryResolver } from '@/features/order/resolvers/order-deposit-admin-query.resolver'; import { AdminDepositService } from '@/features/order/services/order-deposit-admin.service'; @@ -39,6 +40,7 @@ describe('Admin Deposit Resolvers (real DB)', () => { AdminDepositService, AccountAdminRepository, PaymentRepository, + SettlementRepository, OrderTransitionRepository, RefundRepository, OrderEventsService, @@ -78,6 +80,7 @@ describe('Admin Deposit Resolvers (real DB)', () => { pendingPayments: 1, refundsAwaitingAccount: 0, refundsAwaitingTransfer: 0, + pendingSettlements: 0, }); const confirmed = await mutationResolver.adminConfirmPayment(user, { diff --git a/src/features/order/resolvers/order-payment.resolver.spec.ts b/src/features/order/resolvers/order-payment.resolver.spec.ts index cd65f2bb..d009711b 100644 --- a/src/features/order/resolvers/order-payment.resolver.spec.ts +++ b/src/features/order/resolvers/order-payment.resolver.spec.ts @@ -5,6 +5,7 @@ import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log. import { AccountAdminRepository } from '@/features/auth/repositories/account-admin.repository'; import { PAYMENT_BANKS } from '@/features/order/constants/payment-banks'; import { PaymentSettingRepository } from '@/features/order/repositories/payment-setting.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; import { AdminPaymentMutationResolver } from '@/features/order/resolvers/order-payment-admin-mutation.resolver'; import { AdminPaymentQueryResolver } from '@/features/order/resolvers/order-payment-admin-query.resolver'; @@ -22,6 +23,7 @@ import { disconnectTestPrismaClient } from '@/test/db/prisma-test-client'; import { closeTruncateConnection, truncateAll } from '@/test/db/truncate'; import { createAccount, setupSellerWithStore } from '@/test/factories'; import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; +import { outboxPublisherProviders } from '@/test/outbox'; describe('결제 설정·정산 계좌 Resolvers (real DB)', () => { let banks: PaymentQueryResolver; @@ -46,6 +48,8 @@ describe('결제 설정·정산 계좌 Resolvers (real DB)', () => { StoreSellerRepository, PaymentSettingRepository, StoreSettlementAccountRepository, + SettlementRepository, + ...outboxPublisherProviders(), { provide: AUDIT_LOG_REPOSITORY, useClass: AuditLogRepository }, { provide: AccountCipher, useValue: createTestAccountCipher() }, ], diff --git a/src/features/order/resolvers/order-settlement-admin-mutation.resolver.ts b/src/features/order/resolvers/order-settlement-admin-mutation.resolver.ts new file mode 100644 index 00000000..73232325 --- /dev/null +++ b/src/features/order/resolvers/order-settlement-admin-mutation.resolver.ts @@ -0,0 +1,32 @@ +import { UseGuards } from '@nestjs/common'; +import { Args, Mutation, Resolver } from '@nestjs/graphql'; + +import { AdminMarkSettlementPaidInput } from '@/features/order/dto/inputs/admin-mark-settlement-paid.input'; +import { AdminSettlementService } from '@/features/order/services/order-settlement-admin.service'; +import type { AdminSettlementDetailOutput } from '@/features/order/types/order-settlement-output.type'; +import { + CurrentUser, + JwtAuthGuard, + Roles, + RolesGuard, + parseAccountId, + type JwtUser, +} from '@/global/auth'; + +@Resolver('Mutation') +@UseGuards(JwtAuthGuard, RolesGuard) +@Roles('ADMIN') +export class AdminSettlementMutationResolver { + constructor(private readonly settlementService: AdminSettlementService) {} + + @Mutation('adminMarkSettlementPaid') + adminMarkSettlementPaid( + @CurrentUser() user: JwtUser, + @Args('input') input: AdminMarkSettlementPaidInput, + ): Promise { + return this.settlementService.adminMarkSettlementPaid( + parseAccountId(user), + input, + ); + } +} diff --git a/src/features/order/resolvers/order-settlement-admin-query.resolver.ts b/src/features/order/resolvers/order-settlement-admin-query.resolver.ts new file mode 100644 index 00000000..4d1e7681 --- /dev/null +++ b/src/features/order/resolvers/order-settlement-admin-query.resolver.ts @@ -0,0 +1,58 @@ +import { UseGuards } from '@nestjs/common'; +import { Args, Query, Resolver } from '@nestjs/graphql'; + +import type { CursorConnection } from '@/common/types/cursor-connection.type'; +import { parseId } from '@/common/utils/id-parser'; +import { AdminMonthlyCommissionInput } from '@/features/order/dto/inputs/admin-monthly-commission.input'; +import { AdminSettlementListInput } from '@/features/order/dto/inputs/admin-settlement-list.input'; +import { AdminSettlementService } from '@/features/order/services/order-settlement-admin.service'; +import type { + AdminMonthlyCommissionReportOutput, + AdminSettlementDetailOutput, + AdminSettlementSummaryOutput, +} from '@/features/order/types/order-settlement-output.type'; +import { + CurrentUser, + JwtAuthGuard, + Roles, + RolesGuard, + parseAccountId, + type JwtUser, +} from '@/global/auth'; + +@Resolver('Query') +@UseGuards(JwtAuthGuard, RolesGuard) +@Roles('ADMIN') +export class AdminSettlementQueryResolver { + constructor(private readonly settlementService: AdminSettlementService) {} + + @Query('adminSettlements') + adminSettlements( + @CurrentUser() user: JwtUser, + @Args('input', { nullable: true }) input?: AdminSettlementListInput, + ): Promise> { + return this.settlementService.adminSettlements(parseAccountId(user), input); + } + + @Query('adminSettlement') + adminSettlement( + @CurrentUser() user: JwtUser, + @Args('settlementId') settlementId: string, + ): Promise { + return this.settlementService.adminSettlement( + parseAccountId(user), + parseId(settlementId), + ); + } + + @Query('adminMonthlyCommissions') + adminMonthlyCommissions( + @CurrentUser() user: JwtUser, + @Args('input') input: AdminMonthlyCommissionInput, + ): Promise { + return this.settlementService.adminMonthlyCommissions( + parseAccountId(user), + input, + ); + } +} diff --git a/src/features/order/resolvers/order-settlement-seller-query.resolver.ts b/src/features/order/resolvers/order-settlement-seller-query.resolver.ts index 89d17030..58935bf0 100644 --- a/src/features/order/resolvers/order-settlement-seller-query.resolver.ts +++ b/src/features/order/resolvers/order-settlement-seller-query.resolver.ts @@ -1,8 +1,15 @@ import { UseGuards } from '@nestjs/common'; -import { Query, Resolver } from '@nestjs/graphql'; +import { Args, Query, Resolver } from '@nestjs/graphql'; +import type { CursorConnection } from '@/common/types/cursor-connection.type'; +import { parseId } from '@/common/utils/id-parser'; +import { SellerSettlementListInput } from '@/features/order/dto/inputs/seller-settlement-list.input'; import { SellerSettlementService } from '@/features/order/services/order-settlement-seller.service'; import type { SellerSettlementAccountOutput } from '@/features/order/types/order-payment-output.type'; +import type { + SellerSettlementDetailOutput, + SellerSettlementSummaryOutput, +} from '@/features/order/types/order-settlement-output.type'; import { CurrentUser, JwtAuthGuard, @@ -24,4 +31,26 @@ export class SellerSettlementQueryResolver { ): Promise { return this.settlementService.sellerSettlementAccount(parseAccountId(user)); } + + @Query('sellerSettlements') + sellerSettlements( + @CurrentUser() user: JwtUser, + @Args('input', { nullable: true }) input?: SellerSettlementListInput, + ): Promise> { + return this.settlementService.sellerSettlements( + parseAccountId(user), + input, + ); + } + + @Query('sellerSettlement') + sellerSettlement( + @CurrentUser() user: JwtUser, + @Args('settlementId') settlementId: string, + ): Promise { + return this.settlementService.sellerSettlement( + parseAccountId(user), + parseId(settlementId), + ); + } } diff --git a/src/features/order/resolvers/order-settlement.resolver.spec.ts b/src/features/order/resolvers/order-settlement.resolver.spec.ts new file mode 100644 index 00000000..7d47dca2 --- /dev/null +++ b/src/features/order/resolvers/order-settlement.resolver.spec.ts @@ -0,0 +1,131 @@ +// 분기/검증 세부는 order-settlement-admin.service.spec.ts·order-settlement-seller.service.spec.ts에서 담당. 여기서는 리졸버→서비스→DB 경로만 본다. + +import { ClockService } from '@/common/providers/clock.service'; +import { AUDIT_LOG_REPOSITORY } from '@/features/audit-log'; +import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log.repository'; +import { AccountAdminRepository } from '@/features/auth/repositories/account-admin.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; +import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; +import { AdminSettlementMutationResolver } from '@/features/order/resolvers/order-settlement-admin-mutation.resolver'; +import { AdminSettlementQueryResolver } from '@/features/order/resolvers/order-settlement-admin-query.resolver'; +import { SellerSettlementQueryResolver } from '@/features/order/resolvers/order-settlement-seller-query.resolver'; +import { AdminSettlementService } from '@/features/order/services/order-settlement-admin.service'; +import { SellerSettlementService } from '@/features/order/services/order-settlement-seller.service'; +import { StoreSellerRepository } from '@/features/store/repositories/store-seller.repository'; +import type { PrismaClient } from '@/generated/prisma/client'; +import type { JwtUser } from '@/global/auth'; +import { AccountCipher } from '@/global/crypto/account-cipher.service'; +import { createTestAccountCipher } from '@/test/account-cipher'; +import { disconnectTestPrismaClient } from '@/test/db/prisma-test-client'; +import { closeTruncateConnection, truncateAll } from '@/test/db/truncate'; +import { + createAccount, + createFinalizedOrder, + createSettlement, + setupSellerWithStore, +} from '@/test/factories'; +import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; +import { outboxPublisherProviders } from '@/test/outbox'; + +describe('주간 정산 Resolvers (real DB)', () => { + let adminQuery: AdminSettlementQueryResolver; + let adminMutation: AdminSettlementMutationResolver; + let sellerQuery: SellerSettlementQueryResolver; + let cipher: AccountCipher; + let prisma: PrismaClient; + + beforeAll(async () => { + const { module, prisma: p } = await createTestingModuleWithRealDb({ + providers: [ + AdminSettlementQueryResolver, + AdminSettlementMutationResolver, + SellerSettlementQueryResolver, + AdminSettlementService, + SellerSettlementService, + AccountAdminRepository, + StoreSellerRepository, + SettlementRepository, + StoreSettlementAccountRepository, + ClockService, + { provide: AUDIT_LOG_REPOSITORY, useClass: AuditLogRepository }, + { provide: AccountCipher, useValue: createTestAccountCipher() }, + ...outboxPublisherProviders({ clock: true }), + ], + }); + adminQuery = module.get(AdminSettlementQueryResolver); + adminMutation = module.get(AdminSettlementMutationResolver); + sellerQuery = module.get(SellerSettlementQueryResolver); + cipher = module.get(AccountCipher); + prisma = p; + }); + + afterAll(async () => { + await closeTruncateConnection(); + await disconnectTestPrismaClient(); + }); + + beforeEach(async () => { + await truncateAll(); + }); + + it('판매자 정산 내역 → 관리자 목록·상세 → 송금 완료 → 판매자 상세·월 집계를 ID 문자열로 잇는다', async () => { + const { account: seller, store } = await setupSellerWithStore(prisma); + const sellerUser = { accountId: seller.id.toString() } as JwtUser; + const admin = await createAccount(prisma, { account_type: 'ADMIN' }); + const adminUser = { accountId: admin.id.toString() } as JwtUser; + await prisma.storeSettlementAccount.create({ + data: { + store_id: store.id, + bank_code: '090', + account_holder: '홍길동', + account_number_enc: cipher.encrypt( + '33330123455678', + 'settlement-account', + ), + account_number_last4: '5678', + updated_by_account_id: seller.id, + updated_by_role: 'SELLER', + }, + }); + const order = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-12T05:00:00.000Z'), + }); + const settlement = await createSettlement(prisma, { store_id: store.id }); + await prisma.order.update({ + where: { id: order.id }, + data: { settlement_id: settlement.id }, + }); + const id = settlement.id.toString(); + + const mine = await sellerQuery.sellerSettlements(sellerUser, {}); + expect(mine.items.map((i) => i.id)).toEqual([id]); + const list = await adminQuery.adminSettlements(adminUser, { + storeId: store.id.toString(), + }); + expect(list.items).toEqual([ + expect.objectContaining({ id, accountRegistered: true }), + ]); + await expect( + adminQuery.adminSettlement(adminUser, id), + ).resolves.toMatchObject({ + id, + currentAccount: { accountNumber: '33330123455678' }, + }); + + await expect( + adminMutation.adminMarkSettlementPaid(adminUser, { settlementId: id }), + ).resolves.toMatchObject({ id, status: 'PAID' }); + + await expect( + sellerQuery.sellerSettlement(sellerUser, id), + ).resolves.toMatchObject({ + status: 'PAID', + paidAccount: { accountNumberMasked: '****5678' }, + orders: [expect.objectContaining({ orderId: order.id.toString() })], + }); + await expect( + adminQuery.adminMonthlyCommissions(adminUser, { month: '2026-11' }), + ).resolves.toMatchObject({ orderCount: 1, settlementBaseAmount: 10_000 }); + }); +}); diff --git a/src/features/order/services/order-admin-alert-messages.helper.ts b/src/features/order/services/order-admin-alert-messages.helper.ts index 10b82d26..8ebd61ae 100644 --- a/src/features/order/services/order-admin-alert-messages.helper.ts +++ b/src/features/order/services/order-admin-alert-messages.helper.ts @@ -6,6 +6,7 @@ import { import type { OrderPaymentPendingPayload } from '@/features/order/events/order-payment-pending.event'; import type { PaymentDepositClaimedPayload } from '@/features/order/events/payment-deposit-claimed.event'; import type { RefundEventPayload } from '@/features/order/events/refund-requested.event'; +import type { SettlementCreatedPayload } from '@/features/order/events/settlement-created.event'; import { RefundKind } from '@/generated/prisma/client'; import type { AlertMessage } from '@/global/alerting'; @@ -92,3 +93,22 @@ export function buildRefundReadyAlert( ].join('\n'), }; } + +/** 매장별 이벤트를 주 단위 key로 묶어 억제 창 안에서 한 번만 보낸다 — 매장별 금액은 처리 화면에서 본다. */ +export function buildSettlementCreatedAlert( + p: SettlementCreatedPayload, + baseUrl: string | null, +): AlertMessage { + const link = adminTaskLink(baseUrl, '/tasks/settlements', { + periodStart: p.periodStart, + }); + return { + level: 'info', + title: '주간 정산 생성', + key: `settlement-week:${p.periodStart}`, + detail: [ + `${p.periodStart} ~ ${p.periodEnd} 정산이 생성됐어요. 매장별 정산을 확인하고 송금해 주세요.`, + ...(link ? [link] : []), + ].join('\n'), + }; +} diff --git a/src/features/order/services/order-admin-alert.consumer.spec.ts b/src/features/order/services/order-admin-alert.consumer.spec.ts index b928618c..fa637668 100644 --- a/src/features/order/services/order-admin-alert.consumer.spec.ts +++ b/src/features/order/services/order-admin-alert.consumer.spec.ts @@ -7,6 +7,7 @@ import { ORDER_PAYMENT_PENDING } from '@/features/order/events/order-payment-pen import { PAYMENT_DEPOSIT_CLAIMED } from '@/features/order/events/payment-deposit-claimed.event'; import { REFUND_ACCOUNT_SUBMITTED } from '@/features/order/events/refund-account-submitted.event'; import { REFUND_REQUESTED } from '@/features/order/events/refund-requested.event'; +import { SETTLEMENT_CREATED } from '@/features/order/events/settlement-created.event'; import { OrderAdminAlertConsumer } from '@/features/order/services/order-admin-alert.consumer'; import type { OutboxEvent } from '@/features/outbox'; import { AlertService } from '@/global/alerting'; @@ -39,6 +40,18 @@ const REFUND = { productName: '레터링 케이크', }; +const SETTLED = { + settlementId: '5', + storeId: '9', + storeName: '해즈 케이크', + periodStart: '2026-11-09', + periodEnd: '2026-11-15', + orderCount: 3, + settlementBaseAmount: 90_000, + commissionAmount: 4_995, + payoutAmount: 85_005, +}; + function event( eventType: string, payload: OutboxEvent['payload'], @@ -164,6 +177,51 @@ describe('OrderAdminAlertConsumer', () => { ).toEqual(['deposit-pending:42', 'deposit-claim:42', 'deposit-pending:44']); }); + it('주간 정산 생성: info, 주 단위 key, 기간·처리 화면 링크(periodStart)', async () => { + const consumer = build({ baseUrl: 'https://admin.caquick.com' }); + + await consumer.handle(event(SETTLEMENT_CREATED, SETTLED)); + + expect(transport).toHaveBeenCalledWith( + expect.any(String), + { + level: 'info', + title: '주간 정산 생성', + key: 'settlement-week:2026-11-09', + detail: [ + '2026-11-09 ~ 2026-11-15 정산이 생성됐어요. 매장별 정산을 확인하고 송금해 주세요.', + 'https://admin.caquick.com/tasks/settlements?periodStart=2026-11-09', + ].join('\n'), + }, + expect.any(Object), + ); + }); + + it('같은 주의 매장별 정산 이벤트는 억제 창 안에서 한 번만 보내고, 다른 주는 따로 보낸다', async () => { + const consumer = build({ baseUrl: null }); + + await consumer.handle(event(SETTLEMENT_CREATED, SETTLED)); + await consumer.handle( + event(SETTLEMENT_CREATED, { + ...SETTLED, + settlementId: '6', + storeId: '10', + }), + ); + await consumer.handle( + event(SETTLEMENT_CREATED, { + ...SETTLED, + settlementId: '7', + periodStart: '2026-11-16', + periodEnd: '2026-11-22', + }), + ); + + expect( + transport.mock.calls.map(([, m]) => (m as { key: string }).key), + ).toEqual(['settlement-week:2026-11-09', 'settlement-week:2026-11-16']); + }); + it.each([ [ '취소와 함께 계좌 입력', @@ -234,6 +292,7 @@ describe('OrderAdminAlertConsumer', () => { it.each([ [REFUND_REQUESTED, { ...REFUND, kind: 'CHARGEBACK' }], [REFUND_ACCOUNT_SUBMITTED, { ...REFUND, amount: '30000' }], + [SETTLEMENT_CREATED, { ...SETTLED, periodStart: 20261109 }], [ORDER_PAYMENT_PENDING, { ...PENDING, amount: '56000' }], [ORDER_PAYMENT_PENDING, { ...PENDING, expiresAt: 'not-a-date' }], [PAYMENT_DEPOSIT_CLAIMED, { ...CLAIMED, orderId: 43 }], diff --git a/src/features/order/services/order-admin-alert.consumer.ts b/src/features/order/services/order-admin-alert.consumer.ts index 957d4a79..3e0983f1 100644 --- a/src/features/order/services/order-admin-alert.consumer.ts +++ b/src/features/order/services/order-admin-alert.consumer.ts @@ -18,10 +18,15 @@ import { parseRefundRequestedPayload, REFUND_REQUESTED, } from '@/features/order/events/refund-requested.event'; +import { + parseSettlementCreatedPayload, + SETTLEMENT_CREATED, +} from '@/features/order/events/settlement-created.event'; import { buildDepositClaimedAlert, buildDepositPendingAlert, buildRefundReadyAlert, + buildSettlementCreatedAlert, } from '@/features/order/services/order-admin-alert-messages.helper'; import { type OutboxConsumer, @@ -40,6 +45,7 @@ import { AlertService, type AlertMessage } from '@/global/alerting'; PAYMENT_DEPOSIT_CLAIMED, REFUND_REQUESTED, REFUND_ACCOUNT_SUBMITTED, + SETTLEMENT_CREATED, ) export class OrderAdminAlertConsumer implements OutboxConsumer { constructor( @@ -75,6 +81,11 @@ export class OrderAdminAlertConsumer implements OutboxConsumer { parseRefundAccountSubmittedPayload(event.payload), baseUrl, ); + case SETTLEMENT_CREATED: + return buildSettlementCreatedAlert( + parseSettlementCreatedPayload(event.payload), + baseUrl, + ); default: throw new Error(`구독하지 않은 outbox 이벤트: ${event.eventType}`); } diff --git a/src/features/order/services/order-admin-mappers.helper.ts b/src/features/order/services/order-admin-mappers.helper.ts index 10212d0f..722c08ba 100644 --- a/src/features/order/services/order-admin-mappers.helper.ts +++ b/src/features/order/services/order-admin-mappers.helper.ts @@ -13,6 +13,7 @@ import { toOrderStatusHistory, } from '@/features/order/services/order-output-mappers.helper'; import { toAdminOrderPaymentOutput } from '@/features/order/services/order-payment-mappers.helper'; +import { toOrderSettlementFields } from '@/features/order/services/order-settlement-mappers.helper'; import type { AdminOrderCancelOptionsOutput, AdminOrderDetailOutput, @@ -79,5 +80,8 @@ export function toAdminOrderDetailOutput( cancelOptions, ...toOrderAutoTransitionTimes(row), pickupChanges: row.pickup_changes.map(toOrderPickupChange), + ...toOrderSettlementFields(row), + settlementFinalizedAt: row.settlement_finalized_at, + settlementId: row.settlement_id?.toString() ?? null, }; } diff --git a/src/features/order/services/order-admin.service.spec.ts b/src/features/order/services/order-admin.service.spec.ts index 0ce54844..cbeb48fb 100644 --- a/src/features/order/services/order-admin.service.spec.ts +++ b/src/features/order/services/order-admin.service.spec.ts @@ -26,6 +26,7 @@ import { createOrder, createOrderItem, createPayment, + createSettlement, createStore, createThreeDOrderItemCustom, createUserProfile, @@ -517,6 +518,40 @@ describe('AdminOrderService (real DB)', () => { ]); }); + it('수수료·정산 확정과 묶인 주간 정산을 준다', async () => { + const { order, storeId } = await orderWithItem({ + status: 'PICKED_UP', + paid: true, + }); + expect(await service.adminOrder(await admin(), order.id)).toMatchObject({ + commissionRateBps: 0, + expectedPayoutAmount: 10_000, + settlementFinalizedAt: null, + settlementId: null, + }); + const finalizedAt = new Date('2026-11-12T05:00:00.000Z'); + const settlement = await createSettlement(prisma, { store_id: storeId }); + await prisma.order.update({ + where: { id: order.id }, + data: { + commission_rate_bps: 500, + settlement_base_amount: 10_000, + commission_amount: 500, + settlement_finalized_at: finalizedAt, + settlement_id: settlement.id, + }, + }); + + expect(await service.adminOrder(await admin(), order.id)).toMatchObject({ + commissionRateBps: 500, + expectedPayoutAmount: 9_500, + settlementBaseAmount: 10_000, + commissionAmount: 500, + settlementFinalizedAt: finalizedAt, + settlementId: settlement.id.toString(), + }); + }); + it('결제와 입금 확인 처리자·메모를 준다', async () => { const { order } = await orderWithItem(); const confirmedAt = new Date('2026-09-16T07:00:00.000Z'); diff --git a/src/features/order/services/order-deposit-admin.service.spec.ts b/src/features/order/services/order-deposit-admin.service.spec.ts index 46f84c36..1a8a4063 100644 --- a/src/features/order/services/order-deposit-admin.service.spec.ts +++ b/src/features/order/services/order-deposit-admin.service.spec.ts @@ -16,6 +16,7 @@ import { OrderTransitionRepository } from '@/features/order/repositories/order-t import { OrderRepository } from '@/features/order/repositories/order.repository'; import { PaymentRepository } from '@/features/order/repositories/payment.repository'; import { RefundRepository } from '@/features/order/repositories/refund.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { AdminDepositService } from '@/features/order/services/order-deposit-admin.service'; import { OrderEventsService } from '@/features/order/services/order-events.service'; import { OutboxDispatcherService } from '@/features/outbox'; @@ -29,6 +30,7 @@ import { createOrderItem, createPayment, createRefund, + createSettlement, createStore, } from '@/test/factories'; import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; @@ -58,6 +60,7 @@ describe('AdminDepositService (real DB)', () => { AdminDepositService, AccountAdminRepository, PaymentRepository, + SettlementRepository, OrderTransitionRepository, OrderRepository, RefundRepository, @@ -576,7 +579,7 @@ describe('AdminDepositService (real DB)', () => { }, ); - it("처리 대기 건수는 '입금했어요'·전체 입금 대기와 환불 상태별(종류 무관)을 센다", async () => { + it("처리 대기 건수는 '입금했어요'·전체 입금 대기, 환불 상태별(종류 무관), 송금 대기 정산을 센다", async () => { const adminId = await admin(); await pendingOrder({ claimedAt: NOW }); await pendingOrder(); @@ -585,12 +588,15 @@ describe('AdminDepositService (real DB)', () => { await createRefund(prisma, { kind: 'DEPOSIT_RETURN' }); await createRefund(prisma, { status: 'AWAITING_TRANSFER' }); await createRefund(prisma, { status: 'COMPLETED' }); + await createSettlement(prisma); + await createSettlement(prisma, { status: 'PAID', paid_at: NOW }); await expect(service.adminTaskCounts(adminId)).resolves.toEqual({ claimedPayments: 1, pendingPayments: 2, refundsAwaitingAccount: 2, refundsAwaitingTransfer: 1, + pendingSettlements: 1, }); }); }); diff --git a/src/features/order/services/order-deposit-admin.service.ts b/src/features/order/services/order-deposit-admin.service.ts index d1ff6210..320d1d93 100644 --- a/src/features/order/services/order-deposit-admin.service.ts +++ b/src/features/order/services/order-deposit-admin.service.ts @@ -26,6 +26,7 @@ import { assertPaymentConfirmable } from '@/features/order/policies/payment-conf import { OrderTransitionRepository } from '@/features/order/repositories/order-transition.repository'; import { PaymentRepository } from '@/features/order/repositories/payment.repository'; import { RefundRepository } from '@/features/order/repositories/refund.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { toAdminOrderSummaryOutput } from '@/features/order/services/order-admin-mappers.helper'; import { toSellerOrderUpdateEvent } from '@/features/order/services/order-events-mappers.helper'; import { OrderEventsService } from '@/features/order/services/order-events.service'; @@ -51,6 +52,7 @@ export class AdminDepositService extends AdminBaseService { private readonly clock: ClockService, private readonly events: OrderEventsService, private readonly refunds: RefundRepository, + private readonly settlements: SettlementRepository, ) { super(accounts, auditLogs); } @@ -96,17 +98,20 @@ export class AdminDepositService extends AdminBaseService { pendingPayments, refundsAwaitingAccount, refundsAwaitingTransfer, + pendingSettlements, ] = await Promise.all([ this.payments.countPendingPayments({ claimedOnly: true }), this.payments.countPendingPayments({ claimedOnly: false }), this.refunds.countRefunds({ status: RefundStatus.AWAITING_ACCOUNT }), this.refunds.countRefunds({ status: RefundStatus.AWAITING_TRANSFER }), + this.settlements.countPending(), ]); return { claimedPayments, pendingPayments, refundsAwaitingAccount, refundsAwaitingTransfer, + pendingSettlements, }; } diff --git a/src/features/order/services/order-seller.service.spec.ts b/src/features/order/services/order-seller.service.spec.ts index ffb09013..75fb606b 100644 --- a/src/features/order/services/order-seller.service.spec.ts +++ b/src/features/order/services/order-seller.service.spec.ts @@ -515,6 +515,45 @@ describe('SellerOrderService (real DB)', () => { expect(result.paymentMethod).toBe('BANK_TRANSFER'); }); + it('수수료율과 정산 예정 금액을 준다: 입금 전 null, 확정 전 예상값, 확정 뒤 실제 지급액', async () => { + const { account, store } = await setupSellerWithStore(prisma); + const legacy = await createStoreOrder(store.id, { status: 'CONFIRMED' }); + const order = await createStoreOrder(store.id, { + status: 'CONFIRMED', + paid: true, + commissionRateBps: 555, + }); + + expect(await service.sellerOrder(account.id, legacy.id)).toMatchObject({ + commissionRateBps: 0, + expectedPayoutAmount: null, + settlementBaseAmount: null, + commissionAmount: null, + }); + // 10000 × 5.55% = 555 + expect(await service.sellerOrder(account.id, order.id)).toMatchObject({ + commissionRateBps: 555, + expectedPayoutAmount: 9_445, + settlementBaseAmount: null, + commissionAmount: null, + }); + + await prisma.order.update({ + where: { id: order.id }, + data: { + status: 'CANCELED', + settlement_base_amount: 4_000, + commission_amount: 222, + settlement_finalized_at: new Date(), + }, + }); + expect(await service.sellerOrder(account.id, order.id)).toMatchObject({ + expectedPayoutAmount: 3_778, + settlementBaseAmount: 4_000, + commissionAmount: 222, + }); + }); + it('soft-delete된 아이템·상태 이력은 상세에서 제외한다', async () => { const { account, store } = await setupSellerWithStore(prisma); const order = await createStoreOrder(store.id, { status: 'CONFIRMED' }); diff --git a/src/features/order/services/order-seller.service.ts b/src/features/order/services/order-seller.service.ts index e2d6c0f2..5822f0ce 100644 --- a/src/features/order/services/order-seller.service.ts +++ b/src/features/order/services/order-seller.service.ts @@ -35,6 +35,7 @@ import { type OrderStatusHistoryRow, } from '@/features/order/services/order-output-mappers.helper'; import { toSellerOrderSummaryOutput } from '@/features/order/services/order-seller-mappers.helper'; +import { toOrderSettlementFields } from '@/features/order/services/order-settlement-mappers.helper'; import type { SellerOrderDetailOutput, SellerOrderSummaryOutput, @@ -203,7 +204,14 @@ export class SellerOrderService extends SellerBaseService { buyer_name: string; buyer_phone: string; request_note: string | null; - payment: { method: PaymentMethod } | null; + payment: { + method: PaymentMethod; + amount: number; + confirmed_at: Date | null; + } | null; + commission_rate_bps: number; + settlement_base_amount: number | null; + commission_amount: number | null; subtotal_price: number; discount_price: number; total_price: number; @@ -260,6 +268,7 @@ export class SellerOrderService extends SellerBaseService { pickupAt: row.pickup_at, }), pickupChanges: row.pickup_changes.map(toOrderPickupChange), + ...toOrderSettlementFields(row), }; } } diff --git a/src/features/order/services/order-settlement-admin.service.spec.ts b/src/features/order/services/order-settlement-admin.service.spec.ts new file mode 100644 index 00000000..4d3c8fb4 --- /dev/null +++ b/src/features/order/services/order-settlement-admin.service.spec.ts @@ -0,0 +1,494 @@ +import { ClockService } from '@/common/providers/clock.service'; +import { + AUDIT_LOG_REPOSITORY, + type IAuditLogRepository, +} from '@/features/audit-log'; +import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log.repository'; +import { AccountAdminRepository } from '@/features/auth/repositories/account-admin.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; +import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; +import { AdminSettlementService } from '@/features/order/services/order-settlement-admin.service'; +import type { PrismaClient, Store } from '@/generated/prisma/client'; +import { AccountCipher } from '@/global/crypto/account-cipher.service'; +import { createTestAccountCipher } from '@/test/account-cipher'; +import { disconnectTestPrismaClient } from '@/test/db/prisma-test-client'; +import { closeTruncateConnection, truncateAll } from '@/test/db/truncate'; +import { + createAccount, + createFinalizedOrder, + createSettlement, + createStore, +} from '@/test/factories'; +import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; +import { outboxPublisherProviders } from '@/test/outbox'; + +// 2026-11-17(화) 11:00 KST +const NOW = new Date('2026-11-17T02:00:00.000Z'); +const dateOnly = (ymd: string) => new Date(`${ymd}T00:00:00.000Z`); + +describe('AdminSettlementService (real DB)', () => { + let service: AdminSettlementService; + let auditLogs: IAuditLogRepository; + let cipher: AccountCipher; + let prisma: PrismaClient; + + beforeAll(async () => { + const { module, prisma: p } = await createTestingModuleWithRealDb({ + providers: [ + AdminSettlementService, + AccountAdminRepository, + SettlementRepository, + StoreSettlementAccountRepository, + { provide: AUDIT_LOG_REPOSITORY, useClass: AuditLogRepository }, + { provide: AccountCipher, useValue: createTestAccountCipher() }, + { provide: ClockService, useValue: { now: () => NOW } }, + ...outboxPublisherProviders({ clock: true }), + ], + }); + service = module.get(AdminSettlementService); + auditLogs = module.get(AUDIT_LOG_REPOSITORY); + cipher = module.get(AccountCipher); + prisma = p; + }); + + afterAll(async () => { + await closeTruncateConnection(); + await disconnectTestPrismaClient(); + }); + + beforeEach(async () => { + await truncateAll(); + }); + + afterEach(() => { + jest.restoreAllMocks(); + }); + + async function admin(name = '김운영'): Promise { + return (await createAccount(prisma, { account_type: 'ADMIN', name })).id; + } + + async function registerAccount( + store: Store, + accountNumber = '33330123455678', + ): Promise { + await prisma.storeSettlementAccount.upsert({ + where: { store_id: store.id }, + create: { + store_id: store.id, + bank_code: '090', + account_holder: '홍길동', + account_number_enc: cipher.encrypt(accountNumber, 'settlement-account'), + account_number_last4: accountNumber.slice(-4), + updated_by_account_id: 1n, + updated_by_role: 'SELLER', + }, + update: { + bank_code: '004', + account_holder: '바뀐 예금주', + account_number_enc: cipher.encrypt(accountNumber, 'settlement-account'), + account_number_last4: accountNumber.slice(-4), + }, + }); + } + + describe('adminSettlements', () => { + it('최근 생성 순·키셋 커서로 넘기고 매장 정산 계좌 등록 여부를 붙인다', async () => { + const adminId = await admin(); + const registered = await createStore(prisma); + const missing = await createStore(prisma); + await registerAccount(registered); + const a = await createSettlement(prisma, { store_id: registered.id }); + const b = await createSettlement(prisma, { + store_id: missing.id, + store_name_snapshot: '해즈 케이크', + period_start: dateOnly('2026-11-09'), + period_end: dateOnly('2026-11-15'), + }); + const c = await createSettlement(prisma, { store_id: registered.id }); + + const first = await service.adminSettlements(adminId, { limit: 2 }); + expect(first.items.map((i) => [i.id, i.accountRegistered])).toEqual([ + [c.id.toString(), true], + [b.id.toString(), false], + ]); + expect(first).toMatchObject({ totalCount: 3, hasMore: true }); + expect(first.items[1]).toEqual({ + id: b.id.toString(), + storeId: missing.id.toString(), + storeName: '해즈 케이크', + periodStart: '2026-11-09', + periodEnd: '2026-11-15', + orderCount: 1, + settlementBaseAmount: 10_000, + commissionAmount: 0, + payoutAmount: 10_000, + status: 'PENDING', + paidAt: null, + accountRegistered: false, + createdAt: b.created_at, + }); + + const second = await service.adminSettlements(adminId, { + limit: 2, + cursor: first.nextCursor!, + }); + expect(second.items.map((i) => i.id)).toEqual([a.id.toString()]); + expect(second).toMatchObject({ hasMore: false, nextCursor: null }); + }); + + it('상태·매장·기간 시작일 필터는 AND로 묶이고, null은 생략과 같다', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + const target = await createSettlement(prisma, { + store_id: store.id, + period_start: dateOnly('2026-11-09'), + }); + await createSettlement(prisma, { + store_id: store.id, + period_start: dateOnly('2026-11-02'), + }); + await createSettlement(prisma, { + store_id: store.id, + period_start: dateOnly('2026-10-26'), + status: 'PAID', + paid_at: NOW, + }); + await createSettlement(prisma, { period_start: dateOnly('2026-11-09') }); + + const found = await service.adminSettlements(adminId, { + status: 'PENDING', + storeId: store.id.toString(), + periodStart: ' 2026-11-09 ', + }); + expect(found.items.map((i) => i.id)).toEqual([target.id.toString()]); + expect(found.totalCount).toBe(1); + + const paid = await service.adminSettlements(adminId, { status: 'PAID' }); + expect(paid.totalCount).toBe(1); + + const all = await service.adminSettlements(adminId, { + status: null, + storeId: null, + periodStart: null, + cursor: null, + limit: null, + } as never); + expect(all.totalCount).toBe(4); + expect((await service.adminSettlements(adminId)).totalCount).toBe(4); + }); + + it.each([ + [{ periodStart: '2026-11-9' }, 'INVALID_DATE'], + [{ periodStart: '2026-02-30' }, 'INVALID_DATE'], + [{ periodStart: '' }, 'INVALID_DATE'], + [{ storeId: '' }, 'INVALID_ID'], + [{ cursor: 'abc' }, 'INVALID_CURSOR'], + ])('잘못된 입력 %p은 %s다', async (input, code) => { + const adminId = await admin(); + await expect( + service.adminSettlements(adminId, input), + ).rejects.toThrowDomain(code); + }); + + it('관리자가 아니면 거절한다', async () => { + const buyer = await createAccount(prisma, { account_type: 'USER' }); + await expect(service.adminSettlements(buyer.id)).rejects.toThrowDomain( + 'ADMIN_ONLY', + ); + }); + }); + + describe('adminSettlement·adminMarkSettlementPaid', () => { + async function settlementWithOrders(store: Store) { + const settlement = await createSettlement(prisma, { + store_id: store.id, + order_count: 1, + settlement_base_amount: 30_000, + commission_amount: 1_665, + payout_amount: 28_335, + }); + const order = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-12T05:00:00.000Z'), + base_amount: 30_000, + commission_rate_bps: 555, + }); + await prisma.order.update({ + where: { id: order.id }, + data: { settlement_id: settlement.id }, + }); + return { settlement, order }; + } + + it('상세는 포함 주문과 지금 매장 정산 계좌 원문을 내려주고, 송금 전이면 송금 계좌가 없다', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + await registerAccount(store); + const { settlement, order } = await settlementWithOrders(store); + + const detail = await service.adminSettlement(adminId, settlement.id); + + expect(detail).toMatchObject({ + id: settlement.id.toString(), + status: 'PENDING', + accountRegistered: true, + paidAt: null, + paidByLabel: null, + paidNote: null, + paidAccount: null, + currentAccount: { + storeId: store.id.toString(), + bank: { code: '090', name: '카카오뱅크' }, + accountHolder: '홍길동', + accountNumber: '33330123455678', + accountNumberMasked: '****5678', + }, + }); + expect(detail.orders).toEqual([ + expect.objectContaining({ + orderId: order.id.toString(), + settlementBaseAmount: 30_000, + commissionAmount: 1_665, + payoutAmount: 28_335, + }), + ]); + await expect( + service.adminSettlement(adminId, settlement.id + 100n), + ).rejects.toThrowDomain('SETTLEMENT_NOT_FOUND'); + }); + + it('송금 완료는 그때 계좌를 스냅샷하고 처리자·메모·감사(끝 4자리만)를 남긴다', async () => { + const adminId = await admin('김운영'); + const store = await createStore(prisma); + await registerAccount(store); + const { settlement } = await settlementWithOrders(store); + + const out = await service.adminMarkSettlementPaid(adminId, { + settlementId: settlement.id.toString(), + note: ' 카카오 11:05 이체 ', + }); + + expect(out).toMatchObject({ + status: 'PAID', + paidAt: NOW, + paidByLabel: '김운영', + paidNote: '카카오 11:05 이체', + paidAccount: { + bank: { code: '090', name: '카카오뱅크' }, + accountHolder: '홍길동', + accountNumberMasked: '****5678', + }, + }); + const row = await prisma.settlement.findUniqueOrThrow({ + where: { id: settlement.id }, + }); + expect(row.paid_by_account_id).toBe(adminId); + expect( + cipher.decrypt(row.paid_account_number_enc!, 'settlement-account'), + ).toBe('33330123455678'); + const [audit] = await prisma.auditLog.findMany({ + where: { target_type: 'SETTLEMENT' }, + }); + expect(audit).toMatchObject({ + actor_account_id: adminId, + store_id: store.id, + target_id: settlement.id, + action: 'STATUS_CHANGE', + before_json: { status: 'PENDING' }, + after_json: { + status: 'PAID', + payoutAmount: 28_335, + bank_code: '090', + account_holder: '홍길동', + account_number_last4: '5678', + note: '카카오 11:05 이체', + }, + }); + expect(JSON.stringify(audit.after_json)).not.toContain('33330123455678'); + + // 송금 뒤 계좌가 바뀌어도 송금 계좌는 그대로, 현재 계좌는 새 값 + await registerAccount(store, '11112222333344'); + const after = await service.adminSettlement(adminId, settlement.id); + expect(after.paidAccount?.accountNumberMasked).toBe('****5678'); + expect(after.currentAccount?.accountNumber).toBe('11112222333344'); + }); + + it('이미 송금 완료면 SETTLEMENT_ALREADY_PAID이고 처음 기록은 그대로다', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + await registerAccount(store); + const { settlement } = await settlementWithOrders(store); + await service.adminMarkSettlementPaid(adminId, { + settlementId: settlement.id.toString(), + note: '처음', + }); + + await expect( + service.adminMarkSettlementPaid(await admin('다른 운영자'), { + settlementId: settlement.id.toString(), + note: '두 번째', + }), + ).rejects.toThrowDomain('SETTLEMENT_ALREADY_PAID'); + const row = await prisma.settlement.findUniqueOrThrow({ + where: { id: settlement.id }, + }); + expect(row.paid_note).toBe('처음'); + expect( + await prisma.auditLog.count({ where: { target_type: 'SETTLEMENT' } }), + ).toBe(1); + }); + + it('동시에 두 번 눌러도 한 번만 송금 완료된다', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + await registerAccount(store); + const { settlement } = await settlementWithOrders(store); + const input = { settlementId: settlement.id.toString() }; + + const results = await Promise.allSettled([ + service.adminMarkSettlementPaid(adminId, input), + service.adminMarkSettlementPaid(adminId, input), + ]); + + expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1); + const rejected = results.find((r) => r.status === 'rejected'); + expect(rejected?.reason).toMatchObject({ + code: 'SETTLEMENT_ALREADY_PAID', + }); + }); + + it('매장 정산 계좌가 없으면 SETTLEMENT_ACCOUNT_REQUIRED이고 송금 대기로 남는다', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + const { settlement } = await settlementWithOrders(store); + + await expect( + service.adminMarkSettlementPaid(adminId, { + settlementId: settlement.id.toString(), + }), + ).rejects.toThrowDomain('SETTLEMENT_ACCOUNT_REQUIRED'); + await expect( + service.adminSettlement(adminId, settlement.id), + ).resolves.toMatchObject({ + status: 'PENDING', + accountRegistered: false, + currentAccount: null, + }); + }); + + it('감사 기록이 실패하면 송금 완료도 남지 않는다(같은 트랜잭션)', async () => { + const adminId = await admin(); + const store = await createStore(prisma); + await registerAccount(store); + const { settlement } = await settlementWithOrders(store); + jest + .spyOn(auditLogs, 'recordAudit') + .mockRejectedValueOnce(new Error('audit down')); + + await expect( + service.adminMarkSettlementPaid(adminId, { + settlementId: settlement.id.toString(), + }), + ).rejects.toThrow('audit down'); + const row = await prisma.settlement.findUniqueOrThrow({ + where: { id: settlement.id }, + }); + expect(row).toMatchObject({ status: 'PENDING', paid_at: null }); + }); + + it.each([ + [{ settlementId: '999' }, 'SETTLEMENT_NOT_FOUND'], + [{ settlementId: '' }, 'INVALID_ID'], + [{ settlementId: '1', note: '가'.repeat(501) }, 'TEXT_TOO_LONG'], + ])('잘못된 입력 %p은 %s다', async (input, code) => { + const adminId = await admin(); + await expect( + service.adminMarkSettlementPaid(adminId, input), + ).rejects.toThrowDomain(code); + }); + }); + + describe('adminMonthlyCommissions', () => { + it('정산 확정 시각의 KST 월로 매장별 건수·기준액·수수료를 묶는다(경계·삭제·미확정 제외)', async () => { + const adminId = await admin(); + const hazz = await createStore(prisma); + const other = await createStore(prisma); + const finalize = ( + store: Store, + at: string, + base: number, + name?: string, + ) => + createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date(at), + base_amount: base, + commission_rate_bps: 500, + ...(name ? { store_name_snapshot: name } : {}), + }); + // 10-31 23:59:59.999 KST — 10월 + await finalize(hazz, '2026-10-31T14:59:59.999Z', 99_000); + // 11-01 00:00 KST, 11-30 23:59:59.999 KST — 11월 + await finalize(hazz, '2026-10-31T15:00:00.000Z', 20_000, '옛 이름'); + await finalize(hazz, '2026-11-30T14:59:59.999Z', 10_010, '해즈 케이크'); + // 12-01 00:00 KST — 12월 + await finalize(hazz, '2026-11-30T15:00:00.000Z', 99_000); + await finalize(other, '2026-11-10T00:00:00.000Z', 5_000, '다른 매장'); + const deleted = await finalize(other, '2026-11-10T00:00:00.000Z', 7_000); + await prisma.order.update({ + where: { id: deleted.id }, + data: { deleted_at: NOW }, + }); + + const report = await service.adminMonthlyCommissions(adminId, { + month: ' 2026-11 ', + }); + + // 수수료 5%: 20000 → 1000, 10010 → 500(500.5 버림), 5000 → 250 + expect(report).toEqual({ + month: '2026-11', + orderCount: 3, + settlementBaseAmount: 35_010, + commissionAmount: 1_750, + stores: [ + { + storeId: hazz.id.toString(), + storeName: '해즈 케이크', + orderCount: 2, + settlementBaseAmount: 30_010, + commissionAmount: 1_500, + }, + { + storeId: other.id.toString(), + storeName: '다른 매장', + orderCount: 1, + settlementBaseAmount: 5_000, + commissionAmount: 250, + }, + ], + }); + }); + + it('확정 주문이 없는 달은 빈 집계다', async () => { + await expect( + service.adminMonthlyCommissions(await admin(), { month: '2027-01' }), + ).resolves.toEqual({ + month: '2027-01', + orderCount: 0, + settlementBaseAmount: 0, + commissionAmount: 0, + stores: [], + }); + }); + + it.each(['2026-13', '2026-1', 'x', ''])( + '월 형식 %p는 INVALID_YEAR_MONTH다', + async (month) => { + await expect( + service.adminMonthlyCommissions(await admin(), { month }), + ).rejects.toThrowDomain('INVALID_YEAR_MONTH'); + }, + ); + }); +}); diff --git a/src/features/order/services/order-settlement-admin.service.ts b/src/features/order/services/order-settlement-admin.service.ts new file mode 100644 index 00000000..0b92a584 --- /dev/null +++ b/src/features/order/services/order-settlement-admin.service.ts @@ -0,0 +1,164 @@ +import { Inject, Injectable } from '@nestjs/common'; + +import { MAX_REASON_LENGTH } from '@/common/constants/reason.constants'; +import { DomainException } from '@/common/errors/error-catalog'; +import { ClockService } from '@/common/providers/clock.service'; +import type { CursorConnection } from '@/common/types/cursor-connection.type'; +import { parseId, parseOptionalId } from '@/common/utils/id-parser'; +import { parseIdCursor } from '@/common/utils/keyset-cursor'; +import { + kstDayBoundaries, + kstMidnightUtc, + parseKstDate, + parseKstYearMonth, +} from '@/common/utils/kst-time'; +import { + normalizeCursorInput, + sliceIdCursorPage, + toCursorConnection, +} from '@/common/utils/pagination'; +import { cleanNullableText } from '@/common/utils/text-cleaner'; +import { + AUDIT_LOG_REPOSITORY, + type IAuditLogRepository, +} from '@/features/audit-log'; +import { AccountAdminRepository, AdminBaseService } from '@/features/auth'; +import type { AdminMarkSettlementPaidInput } from '@/features/order/dto/inputs/admin-mark-settlement-paid.input'; +import type { AdminMonthlyCommissionInput } from '@/features/order/dto/inputs/admin-monthly-commission.input'; +import type { AdminSettlementListInput } from '@/features/order/dto/inputs/admin-settlement-list.input'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; +import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; +import { toAdminStoreSettlementAccountOutput } from '@/features/order/services/order-payment-mappers.helper'; +import { + toAdminMonthlyCommissionReport, + toAdminSettlementDetailOutput, + toAdminSettlementSummaryOutput, +} from '@/features/order/services/order-settlement-mappers.helper'; +import type { + AdminMonthlyCommissionReportOutput, + AdminSettlementDetailOutput, + AdminSettlementSummaryOutput, +} from '@/features/order/types/order-settlement-output.type'; +import { AccountCipher } from '@/global/crypto/account-cipher.service'; + +const PAID_ERRORS = { + 'not-found': 'SETTLEMENT_NOT_FOUND', + 'already-paid': 'SETTLEMENT_ALREADY_PAID', + 'account-required': 'SETTLEMENT_ACCOUNT_REQUIRED', +} as const; + +/** 주간 정산 조회·송금 완료와 월 수수료 집계. 계좌번호 원문은 정산 상세의 현재 계좌에서만 복호화한다. */ +@Injectable() +export class AdminSettlementService extends AdminBaseService { + constructor( + accounts: AccountAdminRepository, + @Inject(AUDIT_LOG_REPOSITORY) + auditLogs: IAuditLogRepository, + private readonly settlements: SettlementRepository, + private readonly settlementAccounts: StoreSettlementAccountRepository, + private readonly cipher: AccountCipher, + private readonly clock: ClockService, + ) { + super(accounts, auditLogs); + } + + async adminSettlements( + accountId: bigint, + input?: AdminSettlementListInput, + ): Promise> { + await this.requireAdminContext(accountId); + // 관리자 FE는 '전체'를 null로 보낸다 — 생략과 같다 + const filter = { + status: input?.status ?? undefined, + storeId: parseOptionalId(input?.storeId) ?? undefined, + periodStart: + input?.periodStart == null + ? undefined + : parseDateOnly(input.periodStart), + }; + const normalized = normalizeCursorInput({ + limit: input?.limit, + cursor: input?.cursor == null ? null : parseIdCursor(input.cursor), + }); + const [rows, totalCount] = await Promise.all([ + this.settlements.list({ ...filter, ...normalized }), + this.settlements.count(filter), + ]); + const page = sliceIdCursorPage(rows, normalized.limit); + const registered = await this.settlementAccounts.findStoreIdsWithAccount( + page.items.map((row) => row.store_id), + ); + return toCursorConnection(page, totalCount, (row) => + toAdminSettlementSummaryOutput(row, registered.has(row.store_id)), + ); + } + + async adminSettlement( + accountId: bigint, + settlementId: bigint, + ): Promise { + await this.requireAdminContext(accountId); + return this.detailOf(settlementId); + } + + async adminMarkSettlementPaid( + accountId: bigint, + input: AdminMarkSettlementPaidInput, + ): Promise { + const ctx = await this.requireAdminContext(accountId); + const settlementId = parseId(input.settlementId); + const result = await this.settlements.markPaid({ + settlementId, + actorAccountId: ctx.accountId, + actorLabel: ctx.displayLabel, + note: cleanNullableText(input.note, MAX_REASON_LENGTH), + now: this.clock.now(), + }); + if (result.kind !== 'paid') { + throw new DomainException(PAID_ERRORS[result.kind]); + } + return this.detailOf(settlementId); + } + + async adminMonthlyCommissions( + accountId: bigint, + input: AdminMonthlyCommissionInput, + ): Promise { + await this.requireAdminContext(accountId); + const month = input.month.trim(); + const parsed = parseKstYearMonth(month); + if (!parsed) throw new DomainException('INVALID_YEAR_MONTH'); + const rows = await this.settlements.monthlyCommissions( + kstMidnightUtc(parsed.year, parsed.month, 1), + kstMidnightUtc(parsed.year, parsed.month + 1, 1), + ); + return toAdminMonthlyCommissionReport(month, rows); + } + + private async detailOf( + settlementId: bigint, + ): Promise { + const row = await this.settlements.findDetail(settlementId); + if (!row) throw new DomainException('SETTLEMENT_NOT_FOUND'); + const account = await this.settlementAccounts.findByStoreId(row.store_id); + return toAdminSettlementDetailOutput( + row, + account + ? toAdminStoreSettlementAccountOutput( + account, + this.cipher.decrypt( + account.account_number_enc, + 'settlement-account', + ), + ) + : null, + ); + } +} + +/** YYYY-MM-DD(KST 달력일)을 `@db.Date` 비교값으로. */ +function parseDateOnly(value: string): Date { + const date = parseKstDate(value.trim()); + if (!date) throw new DomainException('INVALID_DATE'); + return kstDayBoundaries(date).dateOnlyUtc; +} diff --git a/src/features/order/services/order-settlement-mappers.helper.spec.ts b/src/features/order/services/order-settlement-mappers.helper.spec.ts new file mode 100644 index 00000000..d4894b6f --- /dev/null +++ b/src/features/order/services/order-settlement-mappers.helper.spec.ts @@ -0,0 +1,51 @@ +import { toOrderSettlementFields } from '@/features/order/services/order-settlement-mappers.helper'; + +const CONFIRMED_AT = new Date('2026-11-12T05:00:00.000Z'); +const paid = (amount: number) => ({ amount, confirmed_at: CONFIRMED_AT }); + +describe('toOrderSettlementFields — 정산 예정 금액', () => { + it.each([ + ['결제 도입 전', 'CONFIRMED', null, null, null, null], + [ + '입금 대기(미확인 결제)', + 'PENDING_PAYMENT', + { amount: 10_000, confirmed_at: null }, + null, + null, + null, + ], + ['확정 전: 결제액 − 수수료', 'CONFIRMED', paid(10_000), null, null, 9_445], + [ + '확정 전 원 미만 버림(10001 × 5.55% = 555.05)', + 'MADE', + paid(10_001), + null, + null, + 9_446, + ], + ['확정 없이 취소(전액 환불)', 'CANCELED', paid(10_000), null, null, 0], + [ + '구매자 사정 취소 확정: 남은 금액 기준', + 'CANCELED', + paid(10_000), + 4_000, + 222, + 3_778, + ], + ['픽업 완료 확정', 'PICKED_UP', paid(10_000), 10_000, 555, 9_445], + ] as const)('%s', (_label, status, payment, base, commission, expected) => { + const fields = toOrderSettlementFields({ + status, + commission_rate_bps: 555, + settlement_base_amount: base, + commission_amount: commission, + payment, + }); + expect(fields).toEqual({ + commissionRateBps: 555, + expectedPayoutAmount: expected, + settlementBaseAmount: base, + commissionAmount: commission, + }); + }); +}); diff --git a/src/features/order/services/order-settlement-mappers.helper.ts b/src/features/order/services/order-settlement-mappers.helper.ts new file mode 100644 index 00000000..18295d07 --- /dev/null +++ b/src/features/order/services/order-settlement-mappers.helper.ts @@ -0,0 +1,165 @@ +import { formatDateOnly } from '@/common/utils/kst-time'; +import { + confirmedPaidAmount, + settlementAmounts, +} from '@/features/order/repositories/order-settlement-finalizer.helper'; +import type { + MonthlyCommissionRow, + SettlementDetailRow, +} from '@/features/order/repositories/settlement.repository'; +import { + maskAccountNumber, + toBank, +} from '@/features/order/services/order-bank-account.helper'; +import type { AdminStoreSettlementAccountOutput } from '@/features/order/types/order-payment-output.type'; +import type { + AdminMonthlyCommissionReportOutput, + AdminSettlementDetailOutput, + AdminSettlementSummaryOutput, + OrderSettlementFieldsOutput, + SellerSettlementDetailOutput, + SellerSettlementSummaryOutput, + SettlementOrderOutput, + SettlementPaidAccountOutput, +} from '@/features/order/types/order-settlement-output.type'; +import { OrderStatus, type Settlement } from '@/generated/prisma/client'; + +/** + * 확정 뒤에는 실제 지급액, 확정 전에는 결제액에서 그 주문의 수수료율로 미리 계산한 값이다. + * 확인된 결제가 없으면 null, 확정 없이 취소된 주문(전액 환불)은 정산되지 않으니 0이다. + */ +export function toOrderSettlementFields(row: { + status: OrderStatus; + commission_rate_bps: number; + settlement_base_amount: number | null; + commission_amount: number | null; + payment: { amount: number; confirmed_at: Date | null } | null; +}): OrderSettlementFieldsOutput { + let expectedPayoutAmount: number | null = null; + if (row.settlement_base_amount !== null) { + expectedPayoutAmount = + row.settlement_base_amount - (row.commission_amount ?? 0); + } else if (row.payment?.confirmed_at) { + expectedPayoutAmount = + row.status === OrderStatus.CANCELED + ? 0 + : settlementAmounts( + confirmedPaidAmount(row.payment), + row.commission_rate_bps, + ).payoutAmount; + } + return { + commissionRateBps: row.commission_rate_bps, + expectedPayoutAmount, + settlementBaseAmount: row.settlement_base_amount, + commissionAmount: row.commission_amount, + }; +} + +function toPaidAccount(row: Settlement): SettlementPaidAccountOutput | null { + if ( + !row.paid_bank_code || + !row.paid_account_holder || + !row.paid_account_last4 + ) { + return null; + } + return { + bank: toBank(row.paid_bank_code), + accountHolder: row.paid_account_holder, + accountNumberMasked: maskAccountNumber(row.paid_account_last4), + }; +} + +function toSettlementOrders(row: SettlementDetailRow): SettlementOrderOutput[] { + return row.orders.map((order) => { + const base = order.settlement_base_amount ?? 0; + const commission = order.commission_amount ?? 0; + return { + orderId: order.id.toString(), + orderNumber: order.order_number, + productName: order.items[0]?.product_name_snapshot ?? null, + status: order.status, + commissionRateBps: order.commission_rate_bps, + settlementBaseAmount: base, + commissionAmount: commission, + payoutAmount: base - commission, + // 정산에 묶인 주문은 확정된 주문뿐이다 + settlementFinalizedAt: order.settlement_finalized_at!, + }; + }); +} + +export function toSellerSettlementSummaryOutput( + row: Settlement, +): SellerSettlementSummaryOutput { + return { + id: row.id.toString(), + periodStart: formatDateOnly(row.period_start), + periodEnd: formatDateOnly(row.period_end), + orderCount: row.order_count, + settlementBaseAmount: row.settlement_base_amount, + commissionAmount: row.commission_amount, + payoutAmount: row.payout_amount, + status: row.status, + paidAt: row.paid_at, + createdAt: row.created_at, + }; +} + +export function toSellerSettlementDetailOutput( + row: SettlementDetailRow, +): SellerSettlementDetailOutput { + return { + ...toSellerSettlementSummaryOutput(row), + paidAccount: toPaidAccount(row), + orders: toSettlementOrders(row), + }; +} + +export function toAdminSettlementSummaryOutput( + row: Settlement, + accountRegistered: boolean, +): AdminSettlementSummaryOutput { + return { + ...toSellerSettlementSummaryOutput(row), + storeId: row.store_id.toString(), + storeName: row.store_name_snapshot, + accountRegistered, + }; +} + +export function toAdminSettlementDetailOutput( + row: SettlementDetailRow, + currentAccount: AdminStoreSettlementAccountOutput | null, +): AdminSettlementDetailOutput { + return { + ...toAdminSettlementSummaryOutput(row, currentAccount !== null), + paidByLabel: row.paid_by_label_snapshot, + paidNote: row.paid_note, + paidAccount: toPaidAccount(row), + currentAccount, + orders: toSettlementOrders(row), + }; +} + +export function toAdminMonthlyCommissionReport( + month: string, + rows: MonthlyCommissionRow[], +): AdminMonthlyCommissionReportOutput { + const total = (pick: (row: MonthlyCommissionRow) => number) => + rows.reduce((sum, row) => sum + pick(row), 0); + return { + month, + orderCount: total((row) => row.orderCount), + settlementBaseAmount: total((row) => row.settlementBaseAmount), + commissionAmount: total((row) => row.commissionAmount), + stores: rows.map((row) => ({ + storeId: row.storeId.toString(), + storeName: row.storeName, + orderCount: row.orderCount, + settlementBaseAmount: row.settlementBaseAmount, + commissionAmount: row.commissionAmount, + })), + }; +} diff --git a/src/features/order/services/order-settlement-seller.service.spec.ts b/src/features/order/services/order-settlement-seller.service.spec.ts index 7d68f46f..71ffeec3 100644 --- a/src/features/order/services/order-settlement-seller.service.spec.ts +++ b/src/features/order/services/order-settlement-seller.service.spec.ts @@ -1,5 +1,6 @@ import { AUDIT_LOG_REPOSITORY } from '@/features/audit-log'; import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log.repository'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; import { SellerSettlementService } from '@/features/order/services/order-settlement-seller.service'; import { StoreSellerRepository } from '@/features/store/repositories/store-seller.repository'; @@ -8,8 +9,15 @@ import { AccountCipher } from '@/global/crypto/account-cipher.service'; import { createTestAccountCipher } from '@/test/account-cipher'; import { disconnectTestPrismaClient } from '@/test/db/prisma-test-client'; import { closeTruncateConnection, truncateAll } from '@/test/db/truncate'; -import { createAccount, setupSellerWithStore } from '@/test/factories'; +import { + createAccount, + createFinalizedOrder, + createSettlement, + createStore, + setupSellerWithStore, +} from '@/test/factories'; import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; +import { outboxPublisherProviders } from '@/test/outbox'; describe('SellerSettlementService (real DB)', () => { let service: SellerSettlementService; @@ -22,6 +30,8 @@ describe('SellerSettlementService (real DB)', () => { SellerSettlementService, StoreSellerRepository, StoreSettlementAccountRepository, + SettlementRepository, + ...outboxPublisherProviders(), { provide: AUDIT_LOG_REPOSITORY, useClass: AuditLogRepository }, { provide: AccountCipher, useValue: createTestAccountCipher() }, ], @@ -140,4 +150,142 @@ describe('SellerSettlementService (real DB)', () => { service.sellerUpsertSettlementAccount(storeless.id, input), ).rejects.toThrowDomain('STORE_NOT_FOUND'); }); + + describe('sellerSettlements·sellerSettlement', () => { + const PAID_AT = new Date('2026-11-17T02:00:00.000Z'); + + it('내 매장 정산만 최근 생성 순으로 키셋 커서로 넘긴다', async () => { + const { account, store } = await setupSellerWithStore(prisma); + const other = await createStore(prisma); + const oldest = await createSettlement(prisma, { + store_id: store.id, + period_start: new Date('2026-11-02T00:00:00.000Z'), + }); + const paid = await createSettlement(prisma, { + store_id: store.id, + period_start: new Date('2026-11-09T00:00:00.000Z'), + order_count: 2, + settlement_base_amount: 40_001, + commission_amount: 2_220, + payout_amount: 37_781, + status: 'PAID', + paid_at: PAID_AT, + }); + const latest = await createSettlement(prisma, { store_id: store.id }); + await createSettlement(prisma, { store_id: other.id }); + + const first = await service.sellerSettlements(account.id, { limit: 2 }); + expect(first.items.map((i) => i.id)).toEqual([ + latest.id.toString(), + paid.id.toString(), + ]); + expect(first).toMatchObject({ totalCount: 3, hasMore: true }); + expect(first.items[1]).toEqual({ + id: paid.id.toString(), + periodStart: '2026-11-09', + periodEnd: '2026-11-15', + orderCount: 2, + settlementBaseAmount: 40_001, + commissionAmount: 2_220, + payoutAmount: 37_781, + status: 'PAID', + paidAt: PAID_AT, + createdAt: paid.created_at, + }); + + const second = await service.sellerSettlements(account.id, { + limit: 2, + cursor: first.nextCursor!, + }); + expect(second.items.map((i) => i.id)).toEqual([oldest.id.toString()]); + expect(second).toMatchObject({ hasMore: false, nextCursor: null }); + }); + + it('상세는 포함 주문(주문 id 순)과 송금 계좌 끝 4자리를 내려준다', async () => { + const { account, store } = await setupSellerWithStore(prisma); + const finalizedAt = new Date('2026-11-12T05:00:00.000Z'); + const orders = [ + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: finalizedAt, + base_amount: 30_000, + commission_rate_bps: 555, + product_name_snapshot: '딸기 케이크', + }), + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: finalizedAt, + base_amount: 7_000, + status: 'NO_SHOW', + }), + ]; + const settlement = await createSettlement(prisma, { + store_id: store.id, + status: 'PAID', + paid_at: PAID_AT, + }); + await prisma.settlement.update({ + where: { id: settlement.id }, + data: { + paid_bank_code: '090', + paid_account_holder: '홍길동', + paid_account_number_enc: cipher.encrypt( + '33330123455678', + 'settlement-account', + ), + paid_account_last4: '5678', + }, + }); + await prisma.order.updateMany({ + where: { id: { in: orders.map((o) => o.id) } }, + data: { settlement_id: settlement.id }, + }); + + const detail = await service.sellerSettlement(account.id, settlement.id); + + expect(detail.paidAccount).toEqual({ + bank: { code: '090', name: '카카오뱅크' }, + accountHolder: '홍길동', + accountNumberMasked: '****5678', + }); + expect(detail.orders).toEqual([ + { + orderId: orders[0].id.toString(), + orderNumber: orders[0].order_number, + productName: '딸기 케이크', + status: 'PICKED_UP', + commissionRateBps: 555, + settlementBaseAmount: 30_000, + commissionAmount: 1_665, + payoutAmount: 28_335, + settlementFinalizedAt: finalizedAt, + }, + expect.objectContaining({ + orderId: orders[1].id.toString(), + status: 'NO_SHOW', + payoutAmount: 7_000, + }), + ]); + }); + + it('송금 전 정산은 송금 계좌가 null이고, 다른 매장·없는 정산은 SETTLEMENT_NOT_FOUND다', async () => { + const { account, store } = await setupSellerWithStore(prisma); + const mine = await createSettlement(prisma, { store_id: store.id }); + const others = await createSettlement(prisma); + + await expect( + service.sellerSettlement(account.id, mine.id), + ).resolves.toMatchObject({ + status: 'PENDING', + paidAccount: null, + orders: [], + }); + await expect( + service.sellerSettlement(account.id, others.id), + ).rejects.toThrowDomain('SETTLEMENT_NOT_FOUND'); + await expect( + service.sellerSettlement(account.id, others.id + 100n), + ).rejects.toThrowDomain('SETTLEMENT_NOT_FOUND'); + }); + }); }); diff --git a/src/features/order/services/order-settlement-seller.service.ts b/src/features/order/services/order-settlement-seller.service.ts index 7b3a3bdf..680fbaf4 100644 --- a/src/features/order/services/order-settlement-seller.service.ts +++ b/src/features/order/services/order-settlement-seller.service.ts @@ -1,18 +1,36 @@ import { Inject, Injectable } from '@nestjs/common'; +import { DomainException } from '@/common/errors/error-catalog'; +import type { CursorConnection } from '@/common/types/cursor-connection.type'; +import { parseIdCursor } from '@/common/utils/keyset-cursor'; +import { + normalizeCursorInput, + sliceIdCursorPage, + toCursorConnection, +} from '@/common/utils/pagination'; import { AUDIT_LOG_REPOSITORY, type IAuditLogRepository, } from '@/features/audit-log'; +import type { SellerSettlementListInput } from '@/features/order/dto/inputs/seller-settlement-list.input'; import type { SellerUpsertSettlementAccountInput } from '@/features/order/dto/inputs/seller-upsert-settlement-account.input'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { StoreSettlementAccountRepository } from '@/features/order/repositories/store-settlement-account.repository'; import { normalizeBankAccount } from '@/features/order/services/order-bank-account.helper'; import { toSellerSettlementAccountOutput } from '@/features/order/services/order-payment-mappers.helper'; +import { + toSellerSettlementDetailOutput, + toSellerSettlementSummaryOutput, +} from '@/features/order/services/order-settlement-mappers.helper'; import type { SellerSettlementAccountOutput } from '@/features/order/types/order-payment-output.type'; +import type { + SellerSettlementDetailOutput, + SellerSettlementSummaryOutput, +} from '@/features/order/types/order-settlement-output.type'; import { SellerBaseService, StoreSellerRepository } from '@/features/store'; import { OrderActor } from '@/generated/prisma/client'; -/** 판매자 본인 정산 계좌. 계좌번호는 끝 4자리만 내려주고 원문은 복호화하지 않는다. */ +/** 판매자 본인 정산 계좌와 주간 정산 내역. 계좌번호는 끝 4자리만 내려주고 원문은 복호화하지 않는다. */ @Injectable() export class SellerSettlementService extends SellerBaseService { constructor( @@ -20,6 +38,7 @@ export class SellerSettlementService extends SellerBaseService { @Inject(AUDIT_LOG_REPOSITORY) auditLogs: IAuditLogRepository, private readonly settlementAccounts: StoreSettlementAccountRepository, + private readonly settlements: SettlementRepository, ) { super(repo, auditLogs); } @@ -45,4 +64,35 @@ export class SellerSettlementService extends SellerBaseService { }); return toSellerSettlementAccountOutput(row); } + + async sellerSettlements( + accountId: bigint, + input?: SellerSettlementListInput, + ): Promise> { + const ctx = await this.requireSellerContext(accountId); + const normalized = normalizeCursorInput({ + limit: input?.limit, + cursor: input?.cursor == null ? null : parseIdCursor(input.cursor), + }); + const filter = { storeId: ctx.storeId }; + const [rows, totalCount] = await Promise.all([ + this.settlements.list({ ...filter, ...normalized }), + this.settlements.count(filter), + ]); + return toCursorConnection( + sliceIdCursorPage(rows, normalized.limit), + totalCount, + toSellerSettlementSummaryOutput, + ); + } + + async sellerSettlement( + accountId: bigint, + settlementId: bigint, + ): Promise { + const ctx = await this.requireSellerContext(accountId); + const row = await this.settlements.findDetail(settlementId, ctx.storeId); + if (!row) throw new DomainException('SETTLEMENT_NOT_FOUND'); + return toSellerSettlementDetailOutput(row); + } } diff --git a/src/features/order/services/order-settlement.scheduler.spec.ts b/src/features/order/services/order-settlement.scheduler.spec.ts new file mode 100644 index 00000000..05ad2c9f --- /dev/null +++ b/src/features/order/services/order-settlement.scheduler.spec.ts @@ -0,0 +1,419 @@ +import { Logger } from '@nestjs/common'; + +import { ClockService } from '@/common/providers/clock.service'; +import { AUDIT_LOG_REPOSITORY } from '@/features/audit-log'; +import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log.repository'; +import { SETTLEMENT_CREATED } from '@/features/order/events/settlement-created.event'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; +import { SettlementScheduler } from '@/features/order/services/order-settlement.scheduler'; +import { OutboxPublisher } from '@/features/outbox'; +import type { PrismaClient } from '@/generated/prisma/client'; +import { AlertService } from '@/global/alerting'; +import { disconnectTestPrismaClient } from '@/test/db/prisma-test-client'; +import { closeTruncateConnection, truncateAll } from '@/test/db/truncate'; +import { + createFinalizedOrder, + createOrder, + createOrderItem, + createPayment, + createSettlement, + createStore, +} from '@/test/factories'; +import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.builder'; +import { outboxPublisherProviders } from '@/test/outbox'; + +// 2026-11-16(월) 05:00 KST — 지난주는 11-09(월) ~ 11-15(일) +const MONDAY_5AM = new Date('2026-11-15T20:00:00.000Z'); +const SUNDAY_LAST_MS = new Date('2026-11-15T14:59:59.999Z'); +const MONDAY_0AM = new Date('2026-11-15T15:00:00.000Z'); +const WEEK_MS = 7 * 24 * 60 * 60_000; +const dateOnly = (ymd: string) => new Date(`${ymd}T00:00:00.000Z`); + +// 주간 정산: KST 주 경계, 매장별 묶음·합계, 재실행 멱등, 정산 행과 outbox의 같은 tx, 묵은 주문, soft-delete 제외, 역할 게이트. +describe('SettlementScheduler (real DB)', () => { + let scheduler: SettlementScheduler; + let publisher: OutboxPublisher; + let repository: SettlementRepository; + let prisma: PrismaClient; + let now = MONDAY_5AM; + const alerts = { notify: jest.fn().mockResolvedValue('sent') }; + const savedRole = process.env.APP_ROLE; + + beforeAll(async () => { + const { module, prisma: p } = await createTestingModuleWithRealDb({ + providers: [ + SettlementScheduler, + SettlementRepository, + { provide: AUDIT_LOG_REPOSITORY, useClass: AuditLogRepository }, + { provide: ClockService, useValue: { now: () => now } }, + { provide: AlertService, useValue: alerts }, + ...outboxPublisherProviders({ clock: true }), + ], + }); + scheduler = module.get(SettlementScheduler); + publisher = module.get(OutboxPublisher); + repository = module.get(SettlementRepository); + prisma = p; + }); + + afterAll(async () => { + if (savedRole === undefined) delete process.env.APP_ROLE; + else process.env.APP_ROLE = savedRole; + await closeTruncateConnection(); + await disconnectTestPrismaClient(); + }); + + beforeEach(async () => { + await truncateAll(); + process.env.APP_ROLE = 'worker'; + now = MONDAY_5AM; + alerts.notify.mockClear(); + jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined); + }); + + afterEach(() => jest.restoreAllMocks()); + + const settlementIdOf = async (orderId: bigint) => + (await prisma.order.findUniqueOrThrow({ where: { id: orderId } })) + .settlement_id; + const createdEvents = () => + prisma.outbox.findMany({ + where: { event_type: SETTLEMENT_CREATED }, + orderBy: { id: 'asc' }, + }); + + it('지난주(월~일 KST)에 확정된 주문을 매장별로 묶고 합계·기간·매장명과 settlement.created를 남긴다', async () => { + const store = await createStore(prisma); + const first = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-09T01:00:00.000Z'), + base_amount: 30_000, + commission_rate_bps: 555, + store_name_snapshot: '옛 이름', + }); + // 구매자 사정 취소의 남은 금액도 정산에 들어간다 + const second = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-12T05:00:00.000Z'), + base_amount: 10_001, + commission_rate_bps: 555, + status: 'CANCELED', + store_name_snapshot: '해즈 케이크', + }); + + await expect(scheduler.settleLastWeek()).resolves.toBe(1); + + const [settlement] = await prisma.settlement.findMany(); + // 30000×5.55% = 1665, 10001×5.55% = 555.05 → 555 + expect(settlement).toMatchObject({ + store_id: store.id, + store_name_snapshot: '해즈 케이크', + period_start: dateOnly('2026-11-09'), + period_end: dateOnly('2026-11-15'), + order_count: 2, + settlement_base_amount: 40_001, + commission_amount: 2_220, + payout_amount: 37_781, + status: 'PENDING', + }); + expect(await settlementIdOf(first.id)).toBe(settlement.id); + expect(await settlementIdOf(second.id)).toBe(settlement.id); + const events = await createdEvents(); + expect(events).toHaveLength(1); + expect(events[0]).toMatchObject({ + aggregate_type: 'settlement', + aggregate_id: settlement.id.toString(), + occurred_at: MONDAY_5AM, + payload_json: { + settlementId: settlement.id.toString(), + storeId: store.id.toString(), + storeName: '해즈 케이크', + periodStart: '2026-11-09', + periodEnd: '2026-11-15', + orderCount: 2, + settlementBaseAmount: 40_001, + commissionAmount: 2_220, + payoutAmount: 37_781, + }, + }); + }); + + it('일요일 23:59:59.999에 확정된 주문은 지난주에, 월요일 00:00에 확정된 주문은 다음 주에 들어간다', async () => { + const store = await createStore(prisma); + const sunday = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: SUNDAY_LAST_MS, + }); + const monday = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: MONDAY_0AM, + }); + + await scheduler.settleLastWeek(); + + expect(await settlementIdOf(sunday.id)).not.toBeNull(); + expect(await settlementIdOf(monday.id)).toBeNull(); + + now = new Date(MONDAY_5AM.getTime() + WEEK_MS); + await scheduler.settleLastWeek(); + + const next = await prisma.settlement.findFirstOrThrow({ + where: { period_start: dateOnly('2026-11-16') }, + }); + expect(await settlementIdOf(monday.id)).toBe(next.id); + }); + + it('실행 시각이 일요일 23:59:59.999면 그 전주(11-02~11-08)를 정산하고 이번 주 확정분은 남긴다', async () => { + now = SUNDAY_LAST_MS; + const store = await createStore(prisma); + const before = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-08T14:59:59.999Z'), + }); + const thisWeek = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-12T00:00:00.000Z'), + }); + + await scheduler.settleLastWeek(); + + const [settlement] = await prisma.settlement.findMany(); + expect(settlement.period_start).toEqual(dateOnly('2026-11-02')); + expect(settlement.period_end).toEqual(dateOnly('2026-11-08')); + expect(await settlementIdOf(before.id)).toBe(settlement.id); + expect(await settlementIdOf(thisWeek.id)).toBeNull(); + }); + + it('재실행해도 같은 주 정산·이벤트는 한 번만 생긴다', async () => { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + + await expect(scheduler.settleLastWeek()).resolves.toBe(1); + await expect(scheduler.settleLastWeek()).resolves.toBe(0); + + expect(await prisma.settlement.count()).toBe(1); + expect(await createdEvents()).toHaveLength(1); + }); + + it('같은 주 정산이 이미 있으면 늦게 들어온 주문은 건드리지 않고 다음 주 정산에 넣는다', async () => { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + await scheduler.settleLastWeek(); + // 첫 실행 뒤 커밋된 지난주 확정분(경계에 걸친 tx 등) + const late = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-15T14:00:00.000Z'), + }); + + await expect(scheduler.settleLastWeek()).resolves.toBe(0); + expect(await settlementIdOf(late.id)).toBeNull(); + + now = new Date(MONDAY_5AM.getTime() + WEEK_MS); + await scheduler.settleLastWeek(); + const next = await prisma.settlement.findFirstOrThrow({ + where: { period_start: dateOnly('2026-11-16') }, + }); + expect(next.order_count).toBe(1); + expect(await settlementIdOf(late.id)).toBe(next.id); + }); + + it('묵은 주문(몇 주 전 확정·미정산)도 이번 정산에 함께 묶는다', async () => { + const store = await createStore(prisma); + const stale = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-10-20T00:00:00.000Z'), + }); + + await scheduler.settleLastWeek(); + + const [settlement] = await prisma.settlement.findMany(); + expect(settlement.period_start).toEqual(dateOnly('2026-11-09')); + expect(await settlementIdOf(stale.id)).toBe(settlement.id); + }); + + it('확정 전·기준액 0·이미 정산됨·삭제된 주문·품목이 모두 삭제된 주문은 묶지 않는다', async () => { + const store = await createStore(prisma); + const at = new Date('2026-11-10T00:00:00.000Z'); + const target = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: at, + }); + // 확정 전(결제만 확인) + const unfinalized = await createOrder(prisma, { status: 'CONFIRMED' }); + await createOrderItem(prisma, { + order_id: unfinalized.id, + store_id: store.id, + }); + await createPayment(prisma, { + order_id: unfinalized.id, + status: 'CONFIRMED', + confirmed_at: at, + }); + const zero = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: at, + base_amount: 0, + }); + const settled = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: at, + }); + const old = await createSettlement(prisma, { store_id: store.id }); + await prisma.order.update({ + where: { id: settled.id }, + data: { settlement_id: old.id }, + }); + const deleted = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: at, + }); + await prisma.order.update({ + where: { id: deleted.id }, + data: { deleted_at: at }, + }); + const itemDeleted = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: at, + }); + await prisma.orderItem.updateMany({ + where: { order_id: itemDeleted.id }, + data: { deleted_at: at }, + }); + + await scheduler.settleLastWeek(); + + const created = await prisma.settlement.findFirstOrThrow({ + where: { period_start: dateOnly('2026-11-09') }, + }); + expect(created.order_count).toBe(1); + expect(await settlementIdOf(target.id)).toBe(created.id); + for (const order of [unfinalized, zero, deleted, itemDeleted]) { + expect(await settlementIdOf(order.id)).toBeNull(); + } + expect(await settlementIdOf(settled.id)).toBe(old.id); + }); + + it('이벤트를 적재한 뒤 tx가 실패하면 정산 행·주문 연결·이벤트가 모두 남지 않고 경보한 뒤, 다음 실행에서 다시 만든다', async () => { + const store = await createStore(prisma); + const order = await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + // 적재는 실제로 하고 그 뒤에 실패시킨다 — 같은 tx가 아니면 이벤트 행이 남는다 + const publish = publisher.publish.bind(publisher); + jest + .spyOn(publisher, 'publish') + .mockImplementationOnce(async (tx, event) => { + await publish(tx, event); + throw new Error('outbox down'); + }); + + await expect(scheduler.settleLastWeek()).resolves.toBe(0); + + expect(await prisma.settlement.count()).toBe(0); + expect(await settlementIdOf(order.id)).toBeNull(); + expect(await createdEvents()).toHaveLength(0); + expect(alerts.notify).toHaveBeenCalledWith( + expect.objectContaining({ + level: 'warn', + key: 'order-cron:weekly-settlement', + detail: expect.stringContaining('outbox down'), + }), + ); + + await expect(scheduler.settleLastWeek()).resolves.toBe(1); + expect(await createdEvents()).toHaveLength(1); + }); + + it('한 매장이 실패해도 다른 매장 정산은 만든다', async () => { + const failing = await createStore(prisma); + const healthy = await createStore(prisma); + for (const store of [failing, healthy]) { + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + } + // 매장 id 오름차순으로 돈다 — 첫 매장의 적재만 실패시킨다 + jest + .spyOn(publisher, 'publish') + .mockRejectedValueOnce(new Error('outbox down')); + + await expect(scheduler.settleLastWeek()).resolves.toBe(1); + + const settlements = await prisma.settlement.findMany(); + expect(settlements.map((s) => s.store_id)).toEqual([healthy.id]); + expect(alerts.notify).toHaveBeenCalledTimes(1); + expect(alerts.notify.mock.calls[0][0].detail).toContain( + `매장 ${failing.id}`, + ); + }); + + it('후보 조회가 실패해도 던지지 않고 경보한다', async () => { + jest + .spyOn(repository, 'findUnsettledStoreIds') + .mockRejectedValueOnce(new Error('db down')); + + await expect(scheduler.settleLastWeek()).resolves.toBe(0); + expect(alerts.notify).toHaveBeenCalledWith( + expect.objectContaining({ key: 'order-cron:weekly-settlement' }), + ); + }); + + it('겹친 실행은 건너뛴다', async () => { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + + const results = await Promise.all([ + scheduler.settleLastWeek(), + scheduler.settleLastWeek(), + ]); + + expect([...results].sort()).toEqual([0, 1]); + expect(await prisma.settlement.count()).toBe(1); + }); + + describe('역할 게이트', () => { + async function withPendingOrder() { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + } + + it.each(['api', 'ws'])( + '반증: %s 역할은 부팅·크론에서 정산을 만들지 않는다', + async (role) => { + process.env.APP_ROLE = role; + await withPendingOrder(); + + await scheduler.onApplicationBootstrap(); + await scheduler.weeklySettlement(); + + expect(await prisma.settlement.count()).toBe(0); + }, + ); + + it('worker는 부팅 때 한 번, 크론마다 정산한다', async () => { + await withPendingOrder(); + + await scheduler.onApplicationBootstrap(); + expect(await prisma.settlement.count()).toBe(1); + + now = new Date(MONDAY_5AM.getTime() + WEEK_MS); + await withPendingOrder(); + await scheduler.weeklySettlement(); + expect(await prisma.settlement.count()).toBe(2); + }); + }); +}); diff --git a/src/features/order/services/order-settlement.scheduler.ts b/src/features/order/services/order-settlement.scheduler.ts new file mode 100644 index 00000000..740044a1 --- /dev/null +++ b/src/features/order/services/order-settlement.scheduler.ts @@ -0,0 +1,102 @@ +import { + Injectable, + Logger, + type OnApplicationBootstrap, +} from '@nestjs/common'; +import { Cron } from '@nestjs/schedule'; + +import { ClockService } from '@/common/providers/clock.service'; +import { + DAY_MS, + kstDayBoundaries, + kstWeekStart, +} from '@/common/utils/kst-time'; +import { resolveAppRole, runsBackgroundJobs } from '@/config/app.config'; +import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; +import { AlertService } from '@/global/alerting'; + +/** + * 주간 정산(월 05:00 KST, worker). 지난주(월~일, KST)까지 확정된 주문을 매장별 정산(PENDING)으로 묶는다. + * 매장마다 따로 커밋하고 이미 만든 주는 건너뛰어, 실패한 매장만 다음 실행(부팅·다음 주)에서 다시 시도된다. + */ +@Injectable() +export class SettlementScheduler implements OnApplicationBootstrap { + private readonly logger = new Logger(SettlementScheduler.name); + private running = false; + + constructor( + private readonly settlements: SettlementRepository, + private readonly clock: ClockService, + private readonly alerts: AlertService, + ) {} + + /** 크론을 놓친 주(배포·중단)도 부팅 때 만든다. 이 훅은 모든 역할에서 돌아 역할을 본다. */ + async onApplicationBootstrap(): Promise { + if (!runsBackgroundJobs(resolveAppRole())) return; + await this.settleLastWeek(); + } + + @Cron('0 0 5 * * 1', { timeZone: 'Asia/Seoul' }) + async weeklySettlement(): Promise { + if (!runsBackgroundJobs(resolveAppRole())) return; + await this.settleLastWeek(); + } + + /** 만든 정산 수. 실패는 던지지 않고 경보한다. */ + async settleLastWeek(): Promise { + if (this.running) return 0; + this.running = true; + try { + return await this.run(); + } catch (error) { + await this.fail(error instanceof Error ? error.message : String(error)); + return 0; + } finally { + this.running = false; + } + } + + private async run(): Promise { + const now = this.clock.now(); + const weekStart = kstWeekStart(now); + const periodStart = kstDayBoundaries( + new Date(weekStart.getTime() - 7 * DAY_MS), + ).dateOnlyUtc; + const periodEnd = kstDayBoundaries( + new Date(weekStart.getTime() - DAY_MS), + ).dateOnlyUtc; + + let created = 0; + const failed: string[] = []; + for (const storeId of await this.settlements.findUnsettledStoreIds( + weekStart, + )) { + try { + const settlement = await this.settlements.createWeeklySettlement({ + storeId, + settledBefore: weekStart, + periodStart, + periodEnd, + now, + }); + if (settlement) created++; + } catch (error) { + failed.push( + `매장 ${storeId}: ${error instanceof Error ? error.message : String(error)}`, + ); + } + } + if (failed.length > 0) await this.fail(failed.join('\n')); + return created; + } + + private async fail(detail: string): Promise { + this.logger.error(`주간 정산 실패: ${detail}`); + await this.alerts.notify({ + level: 'warn', + title: '주간 정산 생성 실패', + key: 'order-cron:weekly-settlement', + detail, + }); + } +} diff --git a/src/features/order/types/order-admin-output.type.ts b/src/features/order/types/order-admin-output.type.ts index 93213c05..f7fb19ff 100644 --- a/src/features/order/types/order-admin-output.type.ts +++ b/src/features/order/types/order-admin-output.type.ts @@ -8,6 +8,7 @@ import type { OrderStatusHistoryOutput, } from '@/features/order/types/order-output.type'; import type { AdminOrderPaymentOutput } from '@/features/order/types/order-payment-output.type'; +import type { OrderSettlementFieldsOutput } from '@/features/order/types/order-settlement-output.type'; import type { AccountStatus, OrderCancelReason, @@ -38,7 +39,8 @@ export interface AdminStoreInProgressOrderSummaryOutput { byStatus: { status: OrderStatus; count: number }[]; } -export interface AdminOrderDetailOutput extends OrderAutoTransitionTimes { +export interface AdminOrderDetailOutput + extends OrderAutoTransitionTimes, OrderSettlementFieldsOutput { id: string; orderNumber: string; buyer: { @@ -69,6 +71,8 @@ export interface AdminOrderDetailOutput extends OrderAutoTransitionTimes { cancellation: OrderCancellationOutput | null; cancelOptions: AdminOrderCancelOptionsOutput; pickupChanges: OrderPickupChangeOutput[]; + settlementFinalizedAt: Date | null; + settlementId: string | null; } export interface AdminOrderCancelOptionsOutput { diff --git a/src/features/order/types/order-payment-output.type.ts b/src/features/order/types/order-payment-output.type.ts index f22e5fa7..63be9a17 100644 --- a/src/features/order/types/order-payment-output.type.ts +++ b/src/features/order/types/order-payment-output.type.ts @@ -71,4 +71,5 @@ export interface AdminTaskCountsOutput { pendingPayments: number; refundsAwaitingAccount: number; refundsAwaitingTransfer: number; + pendingSettlements: number; } diff --git a/src/features/order/types/order-seller-output.type.ts b/src/features/order/types/order-seller-output.type.ts index 917aef0c..1df3daa8 100644 --- a/src/features/order/types/order-seller-output.type.ts +++ b/src/features/order/types/order-seller-output.type.ts @@ -5,6 +5,7 @@ import type { OrderPickupChangeOutput, OrderStatusHistoryOutput, } from '@/features/order/types/order-output.type'; +import type { OrderSettlementFieldsOutput } from '@/features/order/types/order-settlement-output.type'; import type { OrderStatus, PaymentMethod } from '@/generated/prisma/client'; export interface SellerOrderSummaryOutput { @@ -23,7 +24,8 @@ export interface SellerOrderSummaryOutput { confirmDeadlineAt: Date | null; } -export interface SellerOrderDetailOutput extends OrderAutoTransitionTimes { +export interface SellerOrderDetailOutput + extends OrderAutoTransitionTimes, OrderSettlementFieldsOutput { id: string; orderNumber: string; accountId: string; diff --git a/src/features/order/types/order-settlement-output.type.ts b/src/features/order/types/order-settlement-output.type.ts new file mode 100644 index 00000000..3e178b9d --- /dev/null +++ b/src/features/order/types/order-settlement-output.type.ts @@ -0,0 +1,80 @@ +import type { + AdminStoreSettlementAccountOutput, + BankOutput, +} from '@/features/order/types/order-payment-output.type'; +import type { OrderStatus, SettlementStatus } from '@/generated/prisma/client'; + +/** 주문 상세(판매자·관리자)의 수수료·정산 표시. */ +export interface OrderSettlementFieldsOutput { + commissionRateBps: number; + expectedPayoutAmount: number | null; + settlementBaseAmount: number | null; + commissionAmount: number | null; +} + +export interface SettlementPaidAccountOutput { + bank: BankOutput; + accountHolder: string; + accountNumberMasked: string; +} + +export interface SettlementOrderOutput { + orderId: string; + orderNumber: string; + productName: string | null; + status: OrderStatus; + commissionRateBps: number; + settlementBaseAmount: number; + commissionAmount: number; + payoutAmount: number; + settlementFinalizedAt: Date; +} + +export interface SellerSettlementSummaryOutput { + id: string; + periodStart: string; + periodEnd: string; + orderCount: number; + settlementBaseAmount: number; + commissionAmount: number; + payoutAmount: number; + status: SettlementStatus; + paidAt: Date | null; + createdAt: Date; +} + +export interface SellerSettlementDetailOutput extends SellerSettlementSummaryOutput { + paidAccount: SettlementPaidAccountOutput | null; + orders: SettlementOrderOutput[]; +} + +export interface AdminSettlementSummaryOutput extends SellerSettlementSummaryOutput { + storeId: string; + storeName: string; + accountRegistered: boolean; +} + +export interface AdminSettlementDetailOutput extends AdminSettlementSummaryOutput { + paidByLabel: string | null; + paidNote: string | null; + paidAccount: SettlementPaidAccountOutput | null; + /** 원문. 관리자 상세에서만 복호화해 내려준다. */ + currentAccount: AdminStoreSettlementAccountOutput | null; + orders: SettlementOrderOutput[]; +} + +export interface AdminMonthlyCommissionStoreOutput { + storeId: string; + storeName: string; + orderCount: number; + settlementBaseAmount: number; + commissionAmount: number; +} + +export interface AdminMonthlyCommissionReportOutput { + month: string; + orderCount: number; + settlementBaseAmount: number; + commissionAmount: number; + stores: AdminMonthlyCommissionStoreOutput[]; +} diff --git a/src/test/admin-query-null-inputs.spec.ts b/src/test/admin-query-null-inputs.spec.ts index 18ac484e..ce3d8441 100644 --- a/src/test/admin-query-null-inputs.spec.ts +++ b/src/test/admin-query-null-inputs.spec.ts @@ -44,7 +44,7 @@ import { createTestingModuleWithRealDb } from '@/test/modules/testing-module.bui // admin 접두 Query 전수에 nullable 필드를 전부 null로 채워 실제 앱(파이프·필터·가드·실DB)으로 보낸다. const FEATURES_DIR = join(__dirname, '..', 'features'); -const ADMIN_QUERY_COUNT = 20; +const ADMIN_QUERY_COUNT = 22; /** 필수 스칼라의 최소 유효값. 새 스칼라가 필수 필드로 오면 표에 없다고 던져 결정을 강제한다 */ const MINIMAL_SCALARS: Record = { @@ -81,11 +81,21 @@ function minimalValue(type: GraphQLInputType): unknown { return MINIMAL_SCALARS[inner.name]; } +/** 형식이 정해진 필수 입력 필드는 스칼라 최소값으로는 리졸버 검증을 넘지 못한다 — 필드 이름으로 유효값을 준다 */ +const MINIMAL_REQUIRED_FIELDS: Record = { + month: '2026-01', +}; + function nullFilledInput( type: GraphQLInputObjectType, ): Record { return Object.fromEntries( - Object.values(type.getFields()).map((f) => [f.name, minimalValue(f.type)]), + Object.values(type.getFields()).map((f) => [ + f.name, + isNonNullType(f.type) && f.name in MINIMAL_REQUIRED_FIELDS + ? MINIMAL_REQUIRED_FIELDS[f.name] + : minimalValue(f.type), + ]), ); } diff --git a/src/test/enum-sdl-sync.spec.ts b/src/test/enum-sdl-sync.spec.ts index ea4e0df7..767b2dcf 100644 --- a/src/test/enum-sdl-sync.spec.ts +++ b/src/test/enum-sdl-sync.spec.ts @@ -19,6 +19,7 @@ import { OrderStatus, RefundKind, RefundStatus, + SettlementStatus, } from '@/generated/prisma/client'; import { UPLOAD_POLICIES } from '@/global/storage/constants/storage.constants'; @@ -89,6 +90,12 @@ const PAIRS: Array< 'src/features/order/order-refund-admin.graphql', 'DepositRecordKindType', ], + [ + 'SettlementStatus', + Object.values(SettlementStatus), + 'src/features/order/order.types.graphql', + 'SettlementStatusType', + ], [ 'CustomMode', Object.values(CustomMode), diff --git a/src/test/factories/order.factory.ts b/src/test/factories/order.factory.ts index 160deb58..96c5253e 100644 --- a/src/test/factories/order.factory.ts +++ b/src/test/factories/order.factory.ts @@ -15,11 +15,13 @@ import type { Refund, RefundKind, RefundStatus, + Settlement, } from '@/generated/prisma/client'; import { activeWhere } from '@/prisma'; import { createAccount } from '@/test/factories/account.factory'; import { createProduct } from '@/test/factories/product.factory'; import { nextSeq } from '@/test/factories/sequence'; +import { createStore } from '@/test/factories/store.factory'; export interface OrderOverrides { account_id?: bigint; @@ -374,3 +376,92 @@ export async function createOrderCustomUpload( }, }); } + +export interface FinalizedOrderArgs { + store_id: bigint; + finalized_at: Date; + /** 기본 10000. 결제액도 같은 값이다 */ + base_amount?: number; + commission_rate_bps?: number; + status?: OrderStatus; + store_name_snapshot?: string; + product_name_snapshot?: string; +} + +/** 정산이 확정된 주문(확인된 결제·품목 포함). 수수료는 확정 규칙과 같이 원 미만 버림. */ +export async function createFinalizedOrder( + prisma: PrismaClient, + args: FinalizedOrderArgs, +): Promise { + const base = args.base_amount ?? 10000; + const bps = args.commission_rate_bps ?? 0; + const order = await createOrder(prisma, { + status: args.status ?? 'PICKED_UP', + total_price: base, + commission_rate_bps: bps, + }); + await createOrderItem(prisma, { + order_id: order.id, + store_id: args.store_id, + ...(args.store_name_snapshot + ? { store_name_snapshot: args.store_name_snapshot } + : {}), + ...(args.product_name_snapshot + ? { product_name_snapshot: args.product_name_snapshot } + : {}), + }); + await createPayment(prisma, { + order_id: order.id, + status: 'CONFIRMED', + confirmed_at: order.created_at, + }); + return prisma.order.update({ + where: { id: order.id }, + data: { + settlement_base_amount: base, + commission_amount: Math.floor((base * bps) / 10000), + settlement_finalized_at: args.finalized_at, + }, + }); +} + +export type SettlementOverrides = Partial< + Pick< + Settlement, + | 'store_id' + | 'store_name_snapshot' + | 'period_start' + | 'period_end' + | 'order_count' + | 'settlement_base_amount' + | 'commission_amount' + | 'payout_amount' + | 'status' + | 'paid_at' + > +>; + +/** 주간 정산 행. 기간을 안 주면 겹치지 않는 주(월~일)를 고른다. */ +export async function createSettlement( + prisma: PrismaClient, + overrides: SettlementOverrides = {}, +): Promise { + const storeId = overrides.store_id ?? (await createStore(prisma)).id; + // 2030-01-07(월)부터 시퀀스만큼 뒤 주 — spec이 직접 고르는 기간과 겹치지 않게 멀리 둔다 + const periodStart = + overrides.period_start ?? + new Date(Date.UTC(2030, 0, 7) + nextSeq() * 7 * DAY_MS); + return prisma.settlement.create({ + data: { + store_name_snapshot: 'Store snapshot', + period_end: new Date(periodStart.getTime() + 6 * DAY_MS), + order_count: 1, + settlement_base_amount: 10000, + commission_amount: 0, + payout_amount: 10000, + ...overrides, + store_id: storeId, + period_start: periodStart, + }, + }); +} diff --git a/src/test/roles-coverage.spec.ts b/src/test/roles-coverage.spec.ts index e2a45025..b2fed23f 100644 --- a/src/test/roles-coverage.spec.ts +++ b/src/test/roles-coverage.spec.ts @@ -13,8 +13,8 @@ describe('접두 루트 필드 인가 커버리지', () => { const handlerAuth = collectHandlerAuth(collectFeatureResolverClasses()); describe.each([ - ['seller', 'SELLER', 63], - ['admin', 'ADMIN', 75], + ['seller', 'SELLER', 65], + ['admin', 'ADMIN', 79], ] as const)('%s 접두 → @Roles(%s)', (prefix, role, count) => { const fields = collectRootFieldsWithPrefix(prefix); From af2ad00d3654b05860e18450affee2ea133150bb Mon Sep 17 00:00:00 2001 From: chanwoo7 Date: Thu, 19 Nov 2026 06:24:16 +0900 Subject: [PATCH 2/3] =?UTF-8?q?fix:=20=EC=9B=94=20=EC=88=98=EC=88=98?= =?UTF-8?q?=EB=A3=8C=20=EC=A7=91=EA=B3=84=20=EB=A7=A4=EC=9E=A5=EB=AA=85?= =?UTF-8?q?=EC=9D=84=20=EA=B7=B8=20=EB=8B=AC=20=EA=B0=80=EC=9E=A5=20?= =?UTF-8?q?=EB=8A=A6=EA=B2=8C=20=ED=99=95=EC=A0=95=EB=90=9C=20=EC=A3=BC?= =?UTF-8?q?=EB=AC=B8=20=EA=B8=B0=EC=A4=80=EC=9C=BC=EB=A1=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 무엇·왜 - 월 집계 매장명은 SDL 설명대로 '그 달 가장 최근 확정 주문의 스냅샷'이어야 하는데, 윈도 정렬이 주문 id라 먼저 생성되고 늦게 확정된 주문의 이름을 놓쳤다. - 변경점 - monthlyCommissions의 FIRST_VALUE 정렬을 settlement_finalized_at DESC, id DESC로 바꿈(같은 시각이면 최근 주문) - 테스트 - 생성 순서와 확정 순서가 엇갈린 같은 매장 주문 2건에서 늦게 확정된 주문의 이름이 나오는지 확인. id 정렬로 되돌리면 실패 - 같은 주 정산이 이미 있어 건너뛸 때·재실행 때 경보가 나가지 않는지 단언 추가. 기존 정산 가드를 빼면 실패 --- .../repositories/settlement.repository.ts | 5 ++-- .../order-settlement-admin.service.spec.ts | 25 +++++++++++++++++++ .../order-settlement.scheduler.spec.ts | 3 +++ 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/src/features/order/repositories/settlement.repository.ts b/src/features/order/repositories/settlement.repository.ts index 4ee2361d..55a4b15e 100644 --- a/src/features/order/repositories/settlement.repository.ts +++ b/src/features/order/repositories/settlement.repository.ts @@ -273,7 +273,7 @@ export class SettlementRepository { }); } - /** [from, to)에 정산이 확정된 주문을 매장별로 묶는다. 매장명은 그 달 가장 최근 주문의 것. */ + /** [from, to)에 정산이 확정된 주문을 매장별로 묶는다. 매장명은 그 달 가장 늦게 확정된 주문의 것. */ async monthlyCommissions( from: Date, to: Date, @@ -291,7 +291,8 @@ export class SettlementRepository { CAST(SUM(t.base) AS UNSIGNED) AS base, CAST(SUM(t.commission) AS UNSIGNED) AS commission FROM ( SELECT oi.store_id, o.settlement_base_amount AS base, COALESCE(o.commission_amount, 0) AS commission, - FIRST_VALUE(oi.store_name_snapshot) OVER (PARTITION BY oi.store_id ORDER BY o.id DESC) AS store_name + FIRST_VALUE(oi.store_name_snapshot) OVER ( + PARTITION BY oi.store_id ORDER BY o.settlement_finalized_at DESC, o.id DESC) AS store_name FROM \`order\` o ${FIRST_ITEM_JOIN} WHERE o.settlement_finalized_at >= ${from} AND o.settlement_finalized_at < ${to} AND o.settlement_base_amount > 0 AND o.deleted_at IS NULL diff --git a/src/features/order/services/order-settlement-admin.service.spec.ts b/src/features/order/services/order-settlement-admin.service.spec.ts index 4d3c8fb4..645e459d 100644 --- a/src/features/order/services/order-settlement-admin.service.spec.ts +++ b/src/features/order/services/order-settlement-admin.service.spec.ts @@ -470,6 +470,31 @@ describe('AdminSettlementService (real DB)', () => { }); }); + it('매장명은 생성 순서가 아니라 그 달 가장 늦게 확정된 주문의 스냅샷이다', async () => { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-20T00:00:00.000Z'), + store_name_snapshot: '나중 확정(새 이름)', + }); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-05T00:00:00.000Z'), + store_name_snapshot: '먼저 확정(옛 이름)', + }); + + const report = await service.adminMonthlyCommissions(await admin(), { + month: '2026-11', + }); + + expect(report.stores).toEqual([ + expect.objectContaining({ + storeName: '나중 확정(새 이름)', + orderCount: 2, + }), + ]); + }); + it('확정 주문이 없는 달은 빈 집계다', async () => { await expect( service.adminMonthlyCommissions(await admin(), { month: '2027-01' }), diff --git a/src/features/order/services/order-settlement.scheduler.spec.ts b/src/features/order/services/order-settlement.scheduler.spec.ts index 05ad2c9f..35668b8e 100644 --- a/src/features/order/services/order-settlement.scheduler.spec.ts +++ b/src/features/order/services/order-settlement.scheduler.spec.ts @@ -196,6 +196,7 @@ describe('SettlementScheduler (real DB)', () => { expect(await prisma.settlement.count()).toBe(1); expect(await createdEvents()).toHaveLength(1); + expect(alerts.notify).not.toHaveBeenCalled(); }); it('같은 주 정산이 이미 있으면 늦게 들어온 주문은 건드리지 않고 다음 주 정산에 넣는다', async () => { @@ -213,6 +214,8 @@ describe('SettlementScheduler (real DB)', () => { await expect(scheduler.settleLastWeek()).resolves.toBe(0); expect(await settlementIdOf(late.id)).toBeNull(); + // 이미 만든 주는 실패가 아니라 건너뜀이라 재실행마다 경보가 나가지 않는다 + expect(alerts.notify).not.toHaveBeenCalled(); now = new Date(MONDAY_5AM.getTime() + WEEK_MS); await scheduler.settleLastWeek(); From 71a3bdaebff4c28514f7c5a17c62a95c8ef0c8eb Mon Sep 17 00:00:00 2001 From: chanwoo7 Date: Thu, 19 Nov 2026 07:01:47 +0900 Subject: [PATCH 3/3] =?UTF-8?q?feat:=20=EC=A3=BC=EA=B0=84=20=EC=A0=95?= =?UTF-8?q?=EC=82=B0=20=ED=9B=84=EB=B3=B4=20=EB=A7=A4=EC=9E=A5=EC=9D=84=20?= =?UTF-8?q?100=EA=B3=B3=EC=94=A9=20=ED=82=A4=EC=85=8B=EC=9C=BC=EB=A1=9C,?= =?UTF-8?q?=20=ED=95=9C=20=EC=8B=A4=ED=96=89=EC=97=90=20=EC=B5=9C=EB=8C=80?= =?UTF-8?q?=201000=EA=B3=B3=EA=B9=8C=EC=A7=80=20=EC=B2=98=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 플랜 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 제거·스케줄러 배치 제거·키셋 조건 제거·경고 제거가 각각 위 테스트를 실패시키는 것을 확인하고 되돌렸다 --- .../repositories/settlement.repository.ts | 13 +- .../order-settlement.scheduler.spec.ts | 159 +++++++++++++++++- .../services/order-settlement.scheduler.ts | 61 ++++++- 3 files changed, 219 insertions(+), 14 deletions(-) diff --git a/src/features/order/repositories/settlement.repository.ts b/src/features/order/repositories/settlement.repository.ts index 55a4b15e..263c4513 100644 --- a/src/features/order/repositories/settlement.repository.ts +++ b/src/features/order/repositories/settlement.repository.ts @@ -83,11 +83,18 @@ export class SettlementRepository { private readonly auditLogs: IAuditLogRepository, ) {} - async findUnsettledStoreIds(before: Date): Promise { + /** 정산할 주문이 남은 매장 id의 키셋 한 페이지(id 오름차순). afterStoreId 다음부터 limit곳. */ + async findUnsettledStoreIds(args: { + before: Date; + afterStoreId?: bigint; + limit: number; + }): Promise { const rows = await this.prisma.$queryRaw<{ store_id: bigint }[]>` SELECT DISTINCT oi.store_id FROM \`order\` o ${FIRST_ITEM_JOIN} - WHERE ${unsettledBefore(before)} - ORDER BY oi.store_id`; + WHERE ${unsettledBefore(args.before)} + ${args.afterStoreId !== undefined ? Prisma.sql`AND oi.store_id > ${args.afterStoreId}` : Prisma.empty} + ORDER BY oi.store_id + LIMIT ${args.limit}`; return rows.map((row) => row.store_id); } diff --git a/src/features/order/services/order-settlement.scheduler.spec.ts b/src/features/order/services/order-settlement.scheduler.spec.ts index 35668b8e..18cadfe3 100644 --- a/src/features/order/services/order-settlement.scheduler.spec.ts +++ b/src/features/order/services/order-settlement.scheduler.spec.ts @@ -5,7 +5,11 @@ import { AUDIT_LOG_REPOSITORY } from '@/features/audit-log'; import { AuditLogRepository } from '@/features/audit-log/repositories/audit-log.repository'; import { SETTLEMENT_CREATED } from '@/features/order/events/settlement-created.event'; import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; -import { SettlementScheduler } from '@/features/order/services/order-settlement.scheduler'; +import { + SETTLEMENT_BATCH_SIZE, + SETTLEMENT_MAX_PER_RUN, + SettlementScheduler, +} from '@/features/order/services/order-settlement.scheduler'; import { OutboxPublisher } from '@/features/outbox'; import type { PrismaClient } from '@/generated/prisma/client'; import { AlertService } from '@/global/alerting'; @@ -29,7 +33,7 @@ const MONDAY_0AM = new Date('2026-11-15T15:00:00.000Z'); const WEEK_MS = 7 * 24 * 60 * 60_000; const dateOnly = (ymd: string) => new Date(`${ymd}T00:00:00.000Z`); -// 주간 정산: KST 주 경계, 매장별 묶음·합계, 재실행 멱등, 정산 행과 outbox의 같은 tx, 묵은 주문, soft-delete 제외, 역할 게이트. +// 주간 정산: KST 주 경계, 매장별 묶음·합계, 재실행 멱등, 정산 행과 outbox의 같은 tx, 묵은 주문, soft-delete 제외, 후보 배치·상한·키셋, 역할 게이트. describe('SettlementScheduler (real DB)', () => { let scheduler: SettlementScheduler; let publisher: OutboxPublisher; @@ -81,6 +85,25 @@ describe('SettlementScheduler (real DB)', () => { where: { event_type: SETTLEMENT_CREATED }, orderBy: { id: 'asc' }, }); + const settledStoreIds = async () => + (await prisma.settlement.findMany({ orderBy: { store_id: 'asc' } })).map( + (s) => s.store_id, + ); + /** 매장마다 지난주 확정 주문 1건. 매장 id 오름차순. */ + async function pendingStores(count: number): Promise { + const ids: bigint[] = []; + for (let i = 0; i < count; i++) { + const store = await createStore(prisma); + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + ids.push(store.id); + } + return ids; + } + const silenceWarn = () => + jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined); it('지난주(월~일 KST)에 확정된 주문을 매장별로 묶고 합계·기간·매장명과 settlement.created를 남긴다', async () => { const store = await createStore(prisma); @@ -385,6 +408,138 @@ describe('SettlementScheduler (real DB)', () => { expect(await prisma.settlement.count()).toBe(1); }); + describe('후보 배치·상한', () => { + it.each([100, 101])( + '후보 매장 %i곳을 100곳씩 키셋으로 나눠 모두 정산한다', + async (count) => { + const storeIds = await pendingStores(count); + const find = jest.spyOn(repository, 'findUnsettledStoreIds'); + const warn = silenceWarn(); + + await expect(scheduler.settleLastWeek()).resolves.toBe(count); + + expect(find.mock.calls.map(([args]) => args)).toEqual([ + { before: MONDAY_0AM, afterStoreId: undefined, limit: 100 }, + { before: MONDAY_0AM, afterStoreId: storeIds[99], limit: 100 }, + ]); + const pages = await Promise.all( + find.mock.results.map((r) => r.value as Promise), + ); + expect(pages.map((page) => page.length)).toEqual([100, count - 100]); + expect(await settledStoreIds()).toEqual(storeIds); + expect(warn).not.toHaveBeenCalled(); + }, + ); + + it('운영 값은 배치 100곳·상한 1000곳이고, 상한에 닿으면 멈추고 남은 매장을 경고로 남긴다', async () => { + expect(SETTLEMENT_BATCH_SIZE).toBe(100); + expect(SETTLEMENT_MAX_PER_RUN).toBe(1000); + // 후보 매장 1~1050 — 1000곳을 실제로 만들지 않고 루프만 본다(상한이 없으면 1050곳을 돈다) + const find = jest + .spyOn(repository, 'findUnsettledStoreIds') + .mockImplementation(({ afterStoreId = 0n, limit }) => + Promise.resolve( + Array.from( + { length: Math.min(limit, 1050 - Number(afterStoreId)) }, + (_, i) => afterStoreId + BigInt(i + 1), + ), + ), + ); + const create = jest + .spyOn(repository, 'createWeeklySettlement') + .mockResolvedValue(null); + const warn = silenceWarn(); + + await scheduler.settleLastWeek(); + + expect(create).toHaveBeenCalledTimes(1000); + expect(create.mock.calls[999][0].storeId).toBe(1000n); + // 100곳씩 10쪽, 그 뒤 남은 매장이 있는지 1곳만 본다 + expect(find.mock.calls.map(([args]) => args.limit)).toEqual([ + ...Array(10).fill(100), + 1, + ]); + expect(find.mock.calls[10][0].afterStoreId).toBe(1000n); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0][0]).toBe( + '주간 정산 상한(1000곳)에 걸려 매장 1001부터는 다음 실행에서 정산한다', + ); + }); + + it('상한을 넘는 후보는 매장 id 순으로 상한만큼만 정산하고 경고를 남긴 뒤, 다음 실행에서 남은 매장을 정산한다', async () => { + const storeIds = await pendingStores(7); + const warn = silenceWarn(); + const limits = { batchSize: 2, maxPerRun: 5 }; + + await expect(scheduler.settleLastWeek(limits)).resolves.toBe(5); + + expect(await settledStoreIds()).toEqual(storeIds.slice(0, 5)); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn.mock.calls[0][0]).toBe( + `주간 정산 상한(5곳)에 걸려 매장 ${storeIds[5]}부터는 다음 실행에서 정산한다`, + ); + // 상한은 실패가 아니라 경보하지 않는다 + expect(alerts.notify).not.toHaveBeenCalled(); + + // 다음 실행(부팅 등) — 정산된 매장은 후보에서 빠지고 남은 매장만 같은 주로 정산한다 + warn.mockClear(); + await expect(scheduler.settleLastWeek(limits)).resolves.toBe(2); + + expect(await settledStoreIds()).toEqual(storeIds); + expect(await createdEvents()).toHaveLength(7); + expect( + await prisma.settlement.count({ + where: { period_start: dateOnly('2026-11-09') }, + }), + ).toBe(7); + expect(warn).not.toHaveBeenCalled(); + }); + + it('반증: 후보가 상한과 같으면 모두 정산하고 경고하지 않는다', async () => { + const storeIds = await pendingStores(4); + const warn = silenceWarn(); + + await expect( + scheduler.settleLastWeek({ batchSize: 2, maxPerRun: 4 }), + ).resolves.toBe(4); + + expect(await settledStoreIds()).toEqual(storeIds); + expect(warn).not.toHaveBeenCalled(); + }); + + it('키셋은 매장 id 오름차순이고, 실패한 매장은 같은 실행에서 다시 잡지 않는다', async () => { + const stores = []; + for (let i = 0; i < 5; i++) stores.push(await createStore(prisma)); + // 주문은 매장 역순으로 만들어 주문 id 순과 매장 id 순을 어긋나게 한다 + for (const store of [...stores].reverse()) { + await createFinalizedOrder(prisma, { + store_id: store.id, + finalized_at: new Date('2026-11-10T00:00:00.000Z'), + }); + } + const storeIds = stores.map((store) => store.id); + const find = jest.spyOn(repository, 'findUnsettledStoreIds'); + const create = jest.spyOn(repository, 'createWeeklySettlement'); + // 첫 매장만 실패 — 다음 쪽 후보에 그대로 남아 있다 + jest + .spyOn(publisher, 'publish') + .mockRejectedValueOnce(new Error('outbox down')); + + await expect( + scheduler.settleLastWeek({ batchSize: 2, maxPerRun: 10 }), + ).resolves.toBe(4); + + expect(create.mock.calls.map(([args]) => args.storeId)).toEqual(storeIds); + expect(find.mock.calls.map(([args]) => args.afterStoreId)).toEqual([ + undefined, + storeIds[1], + storeIds[3], + ]); + expect(await settledStoreIds()).toEqual(storeIds.slice(1)); + expect(alerts.notify).toHaveBeenCalledTimes(1); + }); + }); + describe('역할 게이트', () => { async function withPendingOrder() { const store = await createStore(prisma); diff --git a/src/features/order/services/order-settlement.scheduler.ts b/src/features/order/services/order-settlement.scheduler.ts index 740044a1..61da0434 100644 --- a/src/features/order/services/order-settlement.scheduler.ts +++ b/src/features/order/services/order-settlement.scheduler.ts @@ -15,9 +15,18 @@ import { resolveAppRole, runsBackgroundJobs } from '@/config/app.config'; import { SettlementRepository } from '@/features/order/repositories/settlement.repository'; import { AlertService } from '@/global/alerting'; +/** 후보 매장은 id 순 100곳씩, 한 실행에 최대 1000곳까지 본다(남은 매장은 다음 실행으로). */ +export const SETTLEMENT_BATCH_SIZE = 100; +export const SETTLEMENT_MAX_PER_RUN = 1000; + +interface RunLimits { + batchSize: number; + maxPerRun: number; +} + /** * 주간 정산(월 05:00 KST, worker). 지난주(월~일, KST)까지 확정된 주문을 매장별 정산(PENDING)으로 묶는다. - * 매장마다 따로 커밋하고 이미 만든 주는 건너뛰어, 실패한 매장만 다음 실행(부팅·다음 주)에서 다시 시도된다. + * 매장마다 따로 커밋하고 이미 만든 주는 건너뛰어, 실패했거나 상한에 걸려 남은 매장은 다음 실행(부팅·다음 주)에서 다시 시도된다. */ @Injectable() export class SettlementScheduler implements OnApplicationBootstrap { @@ -42,12 +51,17 @@ export class SettlementScheduler implements OnApplicationBootstrap { await this.settleLastWeek(); } - /** 만든 정산 수. 실패는 던지지 않고 경보한다. */ - async settleLastWeek(): Promise { + /** 만든 정산 수. 실패는 던지지 않고 경보한다. limits는 테스트만 바꾼다. */ + async settleLastWeek( + limits: RunLimits = { + batchSize: SETTLEMENT_BATCH_SIZE, + maxPerRun: SETTLEMENT_MAX_PER_RUN, + }, + ): Promise { if (this.running) return 0; this.running = true; try { - return await this.run(); + return await this.run(limits); } catch (error) { await this.fail(error instanceof Error ? error.message : String(error)); return 0; @@ -56,7 +70,7 @@ export class SettlementScheduler implements OnApplicationBootstrap { } } - private async run(): Promise { + private async run(limits: RunLimits): Promise { const now = this.clock.now(); const weekStart = kstWeekStart(now); const periodStart = kstDayBoundaries( @@ -68,9 +82,7 @@ export class SettlementScheduler implements OnApplicationBootstrap { let created = 0; const failed: string[] = []; - for (const storeId of await this.settlements.findUnsettledStoreIds( - weekStart, - )) { + await this.forEachCandidateStore(weekStart, limits, async (storeId) => { try { const settlement = await this.settlements.createWeeklySettlement({ storeId, @@ -85,11 +97,42 @@ export class SettlementScheduler implements OnApplicationBootstrap { `매장 ${storeId}: ${error instanceof Error ? error.message : String(error)}`, ); } - } + }); if (failed.length > 0) await this.fail(failed.join('\n')); return created; } + /** 후보 매장을 id 키셋으로 넘긴다. 실패한 매장도 키셋이 지나가 같은 실행에서 다시 잡히지 않는다. */ + private async forEachCandidateStore( + before: Date, + limits: RunLimits, + handle: (storeId: bigint) => Promise, + ): Promise { + let afterStoreId: bigint | undefined; + for (let seen = 0; seen < limits.maxPerRun;) { + const limit = Math.min(limits.batchSize, limits.maxPerRun - seen); + const storeIds = await this.settlements.findUnsettledStoreIds({ + before, + afterStoreId, + limit, + }); + for (const storeId of storeIds) await handle(storeId); + if (storeIds.length < limit) return; + seen += limit; + afterStoreId = storeIds[storeIds.length - 1]; + } + const [next] = await this.settlements.findUnsettledStoreIds({ + before, + afterStoreId, + limit: 1, + }); + if (next !== undefined) { + this.logger.warn( + `주간 정산 상한(${limits.maxPerRun}곳)에 걸려 매장 ${next}부터는 다음 실행에서 정산한다`, + ); + } + } + private async fail(detail: string): Promise { this.logger.error(`주간 정산 실패: ${detail}`); await this.alerts.notify({