@yolo-croket-dev/entity-v2 0.3.16 → 0.3.17-sj

package/AGENTS.md

@@ -0,0 +1,50 @@
+# ENTITY-V2 KNOWLEDGE BASE
+
+## OVERVIEW
+
+Mongo 영속 모델과 서비스 contract가 공유하는 최신 entity interface 중심 패키지다. 신규 entity의 우선 위치지만 legacy `entity`와 양방향 호환 import가 남아 있어 일괄 분리하지 않는다.
+
+## STRUCTURE
+
+```text
+entity-v2/
+├── index.ts                  # 약 80개 domain public export
+├── <domain>/index.ts
+├── <domain>/*.entity.ts
+└── <domain>.modules/         # 세부 bounded context
+```
+
+대형 호환 surface는 `store-item/store-item.entity.ts`, `purchased-info/purchased-info.entity.ts`; 수정 전 `@deprecated` 필드와 legacy import를 먼저 확인한다.
+
+## WHERE TO LOOK
+
+| 작업 | 위치 | 확인 |
+|---|---|---|
+| 신규 Mongo entity | `<domain>/*.entity.ts` | 실제 schema field/type/nullability |
+| Public export | `<domain>/index.ts`, root `index.ts` | named/type export 호환성 |
+| Legacy 결합 | `packages/entity`, v2의 legacy imports | 양방향 dependency 확대 여부 |
+| 대형 commerce 모델 | `store-item`, `purchased-info`, `refund`, `cart` | deprecated 대체 필드 |
+
+## CONVENTIONS
+
+- 실제 DB 문서를 표현하는 서비스의 Mongoose `@Schema` class는 이 패키지의 대응 interface를 `implements`해야 한다.
+- `_id`, `ObjectId|string`, optional, `null`, array element type을 실제 저장 shape와 정확히 맞춘다.
+- 신규 domain은 local `index.ts`와 root barrel을 함께 갱신하되 기존 namespace/named export를 깨지 않는다.
+- 기존 v2→legacy import는 호환성 경계로 취급한다. 신규 reverse dependency는 소비 영향 근거 없이 추가하지 않는다.
+- 제거 예정 필드는 `@deprecated`와 대체 필드 설명을 유지한다.
+
+## ANTI-PATTERNS
+
+- DTO/response 전용 임시 shape를 영속 entity로 추가하지 않는다.
+- Deprecated 필드를 신규 feature의 정식 모델로 사용하지 않는다.
+- Legacy field를 소비자와 migration 확인 없이 삭제하거나 type을 축소하지 않는다.
+- `dist`, `.d.ts`, 생성 JS를 source 대신 수정하지 않는다.
+
+## VERIFY
+
+```bash
+yarn workspace @yolo-croket-dev/entity-v2 build
+yarn workspace @yolo-croket-dev/entity-v2 lint
+```
+
+Entity 변경은 `entity`, `dto-v2`, AMQP contract와 실제 Mongoose schema 소비 서비스까지 의존 순서대로 검증한다.

package/bundle-purchased-info/bundle-purchased-info.entity.d.ts

@@ -19,6 +19,11 @@ export interface PInfoOfBundle {
     itemType?: StoreItemTypeEnum;
     /** 분할 배송 여부 (PurchasedInfo.isSplitDelivery의 비정규화 필드, BundlePInfo Atlas Search 필터용) */
     isSplitDelivery?: boolean;
+    /** 셀러 이관 거래 모아보기용 비정규화 여부 */
+    isTransferred?: boolean;
+    /** 셀러 이관 거래 우선 정렬·노출용 최신 이관 일시 */
+    latestTransferDate?: Date;
+    transferPriority?: 0 | 1;
 }
 export interface PastIsPrepay {
     PInfoId: Types.ObjectId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-croket-dev/entity-v2",
-  "version": "0.3.16",
+  "version": "0.3.17-sj",
   "main": "index.js",
   "author": "Yolo Co., Ltd.",
   "description": "크로켓 nest 용 entity-v3",
@@ -23,4 +23,4 @@
   },
   "license": "UNLICENSED",
   "dependencies": {}
-}
+}

package/purchased-info/purchased-info-for-seller.entity.d.ts

@@ -1,6 +1,6 @@
 import { Types } from 'mongoose';
-import { PurchasedInfoEntity } from '@yolo-croket-dev/entity/src/purchased-info/purchased-info.entity';
 import { StoreItemKeyword } from '@yolo-croket-dev/entity/src/store-item';
+import { PurchasedInfoEntity } from './purchased-info.entity';
 import { CustomPurchasedInfo } from './custom-purchased-info.entity';
 import { StoreItemTypeEnum } from '../store-item/store-item.entity';
 import { UserEntity } from '../user/user.entity';
@@ -12,13 +12,15 @@ export default interface PurchasedInfoForSeller {
 }
 export type RefundInfoPickedForSeller = Pick<RefundEntity, '_id' | 'reg_date' | 'acceptInfo' | 'process' | '_authorType' | 'openInfo' | 'refundVersion' | 'returnInfo' | 'rejectInfo' | 'PInfoLastProcess'>;
 export type UserInfoPickedForSeller = Pick<UserEntity, '_id' | 'username' | 'phoneCountry' | 'phoneNumber' | 'photos' | 'subContactList'>;
-export type PInfoPickedForSeller = Pick<PurchasedInfoEntity, '_id' | 'publicId' | 'process' | 'pOptionInfo' | 'proceedsInfo' | 'itemId' | 'pastName' | 'pastImg' | 'pastPrice' | 'deliveryMethod' | 'deliveryData' | 'paymentDate' | 'pastSellingInfo' | 'PCCCInfo' | 'cancelInfo' | 'requirement' | 'originPrice' | 'buyerInfo' | 'lastPartialRefundProcess' | 'lastPartialRefundId' | 'waitingReceiveInfo' | 'cancelledDate' | 'process_v2' | 'isPOptionChanged' | 'pInfoType' | 'isSplitDelivery' | 'splitDeliveryDataList' | 'remainingShipQuantity'> & {
+export type PInfoPickedForSeller = Pick<PurchasedInfoEntity, '_id' | 'publicId' | 'process' | 'pOptionInfo' | 'proceedsInfo' | 'itemId' | 'pastName' | 'pastImg' | 'pastPrice' | 'deliveryMethod' | 'deliveryData' | 'paymentDate' | 'pastSellingInfo' | 'PCCCInfo' | 'cancelInfo' | 'requirement' | 'originPrice' | 'buyerInfo' | 'lastPartialRefundProcess' | 'lastPartialRefundId' | 'waitingReceiveInfo' | 'cancelledDate' | 'process_v2' | 'isPOptionChanged' | 'pInfoType' | 'isSplitDelivery' | 'splitDeliveryDataList' | 'remainingShipQuantity' | 'refundWaitingInfo' | 'transferSellerInfo'> & {
     /** 주문 당시 상품 키워드 스냅샷 */
     itemKeywords?: StoreItemKeyword[];
     isPcccDeferred?: boolean;
     isReceiveInfoChangedInBeforeDelivery?: boolean;
     /** 구매 당시 상품 타입 */
     itemType?: StoreItemTypeEnum;
+    /** 목록 응답에서는 용량이 큰 이관 이력을 제외하고 최신 이관 정보만 제공한다. */
+    transferSellerInfo?: Omit<NonNullable<PurchasedInfoEntity['transferSellerInfo']>, 'history'>;
 };
 export type PurchasedInfoForSellerDetail = {
     pInfo: PInfoPickedForSeller;

package/purchased-info/purchased-info.entity.d.ts

@@ -81,6 +81,91 @@ export declare enum PurchasedProcessV2Enum {
     /** 예약 취소 요청으로 취소됨 */
     cancelledByReserveCancelAsk = "cancelledByReserveCancelAsk"
 }
+/** @description 셀러 귀책 환불 대기 워크플로 상태 */
+export declare enum RefundWaitingStatusEnum {
+    /** 구매자 응답 또는 관리자 이관 판단 대기. 3일 자동 환불 대상 */
+    PENDING = "PENDING",
+    /** 구매자가 타 셀러 이관을 기다리기로 선택한 상태 */
+    WAITING_FOR_ITEM = "WAITING_FOR_ITEM",
+    /** 관리자 이관 불가 확정 후 실제 환불을 시작하기 전 상태 */
+    UNAVAILABLE = "UNAVAILABLE",
+    /** 이관 성공으로 환불 대기 워크플로가 종료된 상태 */
+    TRANSFERRED = "TRANSFERRED",
+    /** 실제 Refund 생성 작업을 선점한 내부 상태 */
+    REFUND_REQUESTED = "REFUND_REQUESTED"
+}
+/** @description 셀러 귀책 환불 대기 사유 코드 */
+export declare enum RefundWaitingReasonCode {
+    /** 셀러의 현지 품절로 대체 셀러 이관 또는 환불 판단이 필요한 경우 */
+    SOLD_OUT = "SOLD_OUT",
+    /** 셀러의 현지 가격 또는 재고 변동으로 기존 주문 이행이 어려운 경우 */
+    PRICE_OR_STOCK_CHANGED = "PRICE_OR_STOCK_CHANGED",
+    /** 셀러 귀책 배송 지연으로 구매자 선택이 필요한 경우 */
+    DELIVERY_DELAY = "DELIVERY_DELAY"
+}
+/** @description 구매자의 환불 대기 선택 */
+export declare enum RefundWaitingBuyerActionTypeEnum {
+    /** 구매자가 환불 대신 관리자에게 다른 셀러 이관을 요청함 */
+    WAIT_FOR_ITEM = "WAIT_FOR_ITEM",
+    /** 구매자가 대기 중단 후 기존 환불 절차 진행을 선택함 */
+    REQUEST_REFUND = "REQUEST_REFUND"
+}
+/** @description 셀러 귀책 환불 대기 정보 */
+export interface RefundWaitingInfo {
+    /** 환불 대기 워크플로 상태 */
+    status: RefundWaitingStatusEnum;
+    /** 환불 대기로 전환한 시각. SLA와 대기 리드타임의 기준점이다. */
+    startDate: Date;
+    /** 자동 환불 대상 시각. 진입 시점에 startDate + 3일을 확정 저장해 정책 변경의 영향을 받지 않는다. */
+    autoRefundDueDate: Date;
+    /** 셀러 귀책 사유의 코드와 당시 구매자 화면에 노출한 문구 스냅샷 */
+    refundReason: {
+        /** 분기, 통계, 정책 적용에 사용하는 정규화된 사유 코드 */
+        code: RefundWaitingReasonCode;
+        /** 사유 코드의 당시 표시명. 사유 마스터 변경 후에도 이력을 보존한다. */
+        name: string;
+        /** 구매자/셀러가 입력한 보조 사유. 입력이 있을 때만 저장한다. */
+        detail?: string;
+    };
+    /** 환불 대기 진입을 유발한 셀러 ID. 이후 이관되더라도 최초 귀책 셀러를 추적한다. */
+    requestedSellerId: Types.ObjectId | string;
+    /** 구매자가 마지막으로 환불 대기 관련 액션을 선택한 시각 */
+    buyerActionDate?: Date;
+    /** 구매자의 마지막 액션. WAIT_FOR_ITEM 또는 REQUEST_REFUND만 저장한다. */
+    buyerActionType?: RefundWaitingBuyerActionTypeEnum;
+    /** 실제 환불 생성을 선점하기 전의 상태. 실패 시 재시도 가능한 상태로 복구하는 데 사용한다. */
+    refundRequestPreviousStatus?: RefundWaitingStatusEnum;
+    /** 구매자가 실제 환불 생성을 마지막으로 시도한 시각 */
+    refundRequestAttemptedDate?: Date;
+    /** 구매자 환불 생성 시도 횟수 */
+    refundRequestAttemptCount?: number;
+    /** 마지막 구매자 환불 생성 실패의 운영 분류 코드 */
+    refundRequestLastErrorCode?: string;
+    /** 관리자가 이관 불가를 확정한 시각. UNAVAILABLE 상태의 감사 이력이다. */
+    unavailableDate?: Date;
+    /** 이관 불가 처리를 수행한 관리자 ID */
+    unavailableManagerId?: Types.ObjectId | string;
+    /** 이관 불가 후 환불 생성을 마지막으로 시도한 시각 */
+    unavailableRefundAttemptedDate?: Date;
+    /** 이관 불가 후 환불 생성 시도 횟수 */
+    unavailableRefundAttemptCount?: number;
+    /** 마지막 이관 불가 환불 생성 실패 코드 */
+    unavailableRefundLastErrorCode?: string;
+    /** 스케줄러가 자동 환불 작업을 마지막으로 선점한 시각. 중복 실행 방지에 사용한다. */
+    autoRefundAttemptedDate?: Date;
+    /** 자동 환불 실행 시도 횟수. 재시도 한도와 운영 모니터링에 사용한다. */
+    autoRefundAttemptCount?: number;
+    /** 마지막 자동 환불 실패 코드. 원문 오류 대신 운영 분류용 코드만 저장한다. */
+    autoRefundLastErrorCode?: string;
+    /** 구매자 응답 만기 전 알림 발송 작업을 선점한 시각 */
+    buyerResponseReminderClaimedDate?: Date;
+    /** 구매자 응답 만기 전 알림 발송 완료 시각 */
+    buyerResponseReminderSentDate?: Date;
+    /** 구매자 응답 만기 전 알림 발송 시도 횟수 */
+    buyerResponseReminderAttemptCount?: number;
+    /** 마지막 구매자 응답 만기 전 알림 발송 실패 코드 */
+    buyerResponseReminderLastErrorCode?: string;
+}
 export interface PastSellingInfoShippingTermsInfo {
     /** 조건 배송 종류 <shippingFeeBySection, > */
     shippingTermsType: string;
@@ -1248,12 +1333,17 @@ export default interface PurchasedInfoEntity {
     priceCompareAffiliateInfo?: PriceCompareAffiliateInfo;
     pInfoType?: PInfoTypeEnum;
     reservationInfo?: PurchasedReservationInfo;
+    /** @description 셀러 귀책 환불 대기 워크플로 정보 */
+    refundWaitingInfo?: RefundWaitingInfo;
     /** @description 셀러 변경 이력 (관리자 셀러 이전 기능) */
     transferSellerInfo?: {
         /** 셀러 변경 여부 (DB 필터링용) */
         isTransferred: boolean;
         /** 셀러 변경 횟수 */
         transferCount: number;
+        /** 셀러 거래내역 목록 정렬·노출을 위한 가장 최근 이관 완료 시각 */
+        latestTransferDate?: Date;
+        transferPriority?: 0 | 1;
         /** 변경 이력 목록 */
         history: Array<{
             transferDate: Date;

package/purchased-info/purchased-info.entity.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PriceCompareAffiliateSettleStatusEnum = exports.PriceCompareAffiliateTypeEnum = exports.InsuranceProcessTypeEnum = exports.ShippingForwarderProviderEnum = exports.CrawlerProxyOrderForeignCurrencyEnum = exports.CrawlerProxyForwardingStatusEnum = exports.CrawlerProxyPurchaseStatusEnum = exports.PastSelectionFrameDataInfo = exports.PurchasedProcessV2Enum = exports.PurchasedProcessEnum = exports.UserTypeEnum = exports.TaxInvoiceIssueProcessEnum = exports.POptionTypeEnum = exports.PInfoTypeEnum = exports.ReservationCancelReasonEnum = exports.CardQuotaEnum = void 0;
+exports.PriceCompareAffiliateSettleStatusEnum = exports.PriceCompareAffiliateTypeEnum = exports.InsuranceProcessTypeEnum = exports.ShippingForwarderProviderEnum = exports.CrawlerProxyOrderForeignCurrencyEnum = exports.CrawlerProxyForwardingStatusEnum = exports.CrawlerProxyPurchaseStatusEnum = exports.PastSelectionFrameDataInfo = exports.RefundWaitingBuyerActionTypeEnum = exports.RefundWaitingReasonCode = exports.RefundWaitingStatusEnum = exports.PurchasedProcessV2Enum = exports.PurchasedProcessEnum = exports.UserTypeEnum = exports.TaxInvoiceIssueProcessEnum = exports.POptionTypeEnum = exports.PInfoTypeEnum = exports.ReservationCancelReasonEnum = exports.CardQuotaEnum = void 0;
 var CardQuotaEnum;
 (function (CardQuotaEnum) {
     CardQuotaEnum["\uC77C\uC2DC\uBD88"] = "00";
@@ -82,6 +82,38 @@ var PurchasedProcessV2Enum;
     /** 예약 취소 요청으로 취소됨 */
     PurchasedProcessV2Enum["cancelledByReserveCancelAsk"] = "cancelledByReserveCancelAsk";
 })(PurchasedProcessV2Enum || (exports.PurchasedProcessV2Enum = PurchasedProcessV2Enum = {}));
+/** @description 셀러 귀책 환불 대기 워크플로 상태 */
+var RefundWaitingStatusEnum;
+(function (RefundWaitingStatusEnum) {
+    /** 구매자 응답 또는 관리자 이관 판단 대기. 3일 자동 환불 대상 */
+    RefundWaitingStatusEnum["PENDING"] = "PENDING";
+    /** 구매자가 타 셀러 이관을 기다리기로 선택한 상태 */
+    RefundWaitingStatusEnum["WAITING_FOR_ITEM"] = "WAITING_FOR_ITEM";
+    /** 관리자 이관 불가 확정 후 실제 환불을 시작하기 전 상태 */
+    RefundWaitingStatusEnum["UNAVAILABLE"] = "UNAVAILABLE";
+    /** 이관 성공으로 환불 대기 워크플로가 종료된 상태 */
+    RefundWaitingStatusEnum["TRANSFERRED"] = "TRANSFERRED";
+    /** 실제 Refund 생성 작업을 선점한 내부 상태 */
+    RefundWaitingStatusEnum["REFUND_REQUESTED"] = "REFUND_REQUESTED";
+})(RefundWaitingStatusEnum || (exports.RefundWaitingStatusEnum = RefundWaitingStatusEnum = {}));
+/** @description 셀러 귀책 환불 대기 사유 코드 */
+var RefundWaitingReasonCode;
+(function (RefundWaitingReasonCode) {
+    /** 셀러의 현지 품절로 대체 셀러 이관 또는 환불 판단이 필요한 경우 */
+    RefundWaitingReasonCode["SOLD_OUT"] = "SOLD_OUT";
+    /** 셀러의 현지 가격 또는 재고 변동으로 기존 주문 이행이 어려운 경우 */
+    RefundWaitingReasonCode["PRICE_OR_STOCK_CHANGED"] = "PRICE_OR_STOCK_CHANGED";
+    /** 셀러 귀책 배송 지연으로 구매자 선택이 필요한 경우 */
+    RefundWaitingReasonCode["DELIVERY_DELAY"] = "DELIVERY_DELAY";
+})(RefundWaitingReasonCode || (exports.RefundWaitingReasonCode = RefundWaitingReasonCode = {}));
+/** @description 구매자의 환불 대기 선택 */
+var RefundWaitingBuyerActionTypeEnum;
+(function (RefundWaitingBuyerActionTypeEnum) {
+    /** 구매자가 환불 대신 관리자에게 다른 셀러 이관을 요청함 */
+    RefundWaitingBuyerActionTypeEnum["WAIT_FOR_ITEM"] = "WAIT_FOR_ITEM";
+    /** 구매자가 대기 중단 후 기존 환불 절차 진행을 선택함 */
+    RefundWaitingBuyerActionTypeEnum["REQUEST_REFUND"] = "REQUEST_REFUND";
+})(RefundWaitingBuyerActionTypeEnum || (exports.RefundWaitingBuyerActionTypeEnum = RefundWaitingBuyerActionTypeEnum = {}));
 // 당시 셀렉션 프레임 데이터 정보
 class PastSelectionFrameDataInfo {
 }