Develop

prisma/migrations/20260729140000_add_refund_workflow_and_policy_consent/migration.sql

@@ -0,0 +1,24 @@
+-- AlterTable: Purchase 환불정책 동의 시점 (#533)
+ALTER TABLE `Purchase` ADD COLUMN `refund_policy_agreed_at` DATETIME(3) NULL;
+
+-- AlterTable: Refund 수동 환불 워크플로 컬럼 (#533)
+-- status 기본값을 COMPLETED로 두어 기존 자동 환불 레코드가 그대로 완료 상태로 백필된다.
+ALTER TABLE `Refund`
+    ADD COLUMN `status` ENUM('REQUESTED', 'APPROVED', 'REJECTED', 'COMPLETED') NOT NULL DEFAULT 'COMPLETED',
+    ADD COLUMN `request_reason` VARCHAR(500) NULL,
+    ADD COLUMN `reject_reason` VARCHAR(500) NULL,
+    ADD COLUMN `reviewed_by` INTEGER NULL,
+    ADD COLUMN `reviewed_at` DATETIME(3) NULL,
+    ADD COLUMN `payple_fail_code` VARCHAR(40) NULL,
+    ADD COLUMN `requested_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3);
+
+-- 기존 레코드의 requested_at은 실제 환불 시점으로 맞춘다 (기본값 CURRENT_TIMESTAMP 대신).
+UPDATE `Refund` SET `requested_at` = `refunded_at`;
+
+-- refunded_at은 "환불 완료 시각"으로 의미를 좁힌다.
+-- REQUESTED/REJECTED 단계에서 값이 채워지면 완료된 환불로 오인되므로 nullable + 기본값 제거.
+-- 기존 레코드는 모두 COMPLETED이므로 값이 그대로 유지된다.
+ALTER TABLE `Refund` MODIFY COLUMN `refunded_at` DATETIME(3) NULL;
+
+-- CreateIndex
+CREATE INDEX `Refund_status_idx` ON `Refund`(`status`);

prisma/schema.prisma

@@ -396,6 +396,7 @@ model Purchase {
   created_at    DateTime  @default(now())
   updated_at    DateTime  @updatedAt
   downloaded_at DateTime? // 첫 다운로드 시점 — 환불 가능 조건 판단용 (#485)
+  refund_policy_agreed_at DateTime? // 결제 시 "열람 후 단순변심 환불 불가" 동의 시점 (#533)
   payment       Payment?
   refund        Refund?
   prompt        Prompt    @relation(fields: [prompt_id], references: [prompt_id])
@@ -444,23 +445,42 @@ model Payment {
   cash_receipt_url String?
 }
 
+// 환불 처리 상태 (#533)
+// 열람 전 7일 이내 자동 환불은 곧바로 COMPLETED로 생성되고,
+// 열람 후 수동 환불은 REQUESTED → APPROVED/REJECTED → COMPLETED 로 진행된다.
+enum RefundStatus {
+  REQUESTED // 사용자 신청, 담당자 검토 대기
+  APPROVED // 승인됐으나 Payple 취소 미완료 (카드사 기간 초과 등) — 수동 송금 대상
+  REJECTED // 담당자 거절
+  COMPLETED // 환불 완료
+}
+
 model Refund {
-  refund_id             Int      @id @default(autoincrement())
-  purchase_id           Int      @unique
-  payment_id            Int      @unique
+  refund_id             Int          @id @default(autoincrement())
+  purchase_id           Int          @unique
+  payment_id            Int          @unique
   user_id               Int
   amount                Int
-  reason                String?  @db.VarChar(200)
-  initiator             String   @db.VarChar(20) // 'USER' | 'ADMIN'
-  payple_pay_code       String?  @db.VarChar(20) // PCD_PAY_CODE (e.g. PAYC0000)
-  payple_card_trade_num String?  @db.VarChar(64) // PCD_PAY_CARDTRADENUM 감사 추적용
-  refunded_at           DateTime @default(now())
+  reason                String?      @db.VarChar(200)
+  initiator             String       @db.VarChar(20) // 'USER' | 'ADMIN'
+  payple_pay_code       String?      @db.VarChar(20) // PCD_PAY_CODE (e.g. PAYC0000)
+  payple_card_trade_num String?      @db.VarChar(64) // PCD_PAY_CARDTRADENUM 감사 추적용
+  refunded_at           DateTime? // 실제 환불 완료 시각 — REQUESTED/REJECTED 단계에서는 null (#533)
+  // 수동 환불 워크플로 (#533)
+  status                RefundStatus @default(COMPLETED) // 기존 자동 환불 레코드는 COMPLETED
+  request_reason        String?      @db.VarChar(500) // 사용자 신청 사유
+  reject_reason         String?      @db.VarChar(500) // 담당자 거절 사유
+  reviewed_by           Int? // 처리한 관리자 user_id — 감사용이라 FK 없이 값만 보관
+  reviewed_at           DateTime?
+  payple_fail_code      String?      @db.VarChar(40) // 승인 후 Payple 취소 실패 시 응답 코드
+  requested_at          DateTime     @default(now())
 
   purchase Purchase @relation(fields: [purchase_id], references: [purchase_id], onDelete: Cascade)
   payment  Payment  @relation(fields: [payment_id], references: [payment_id], onDelete: Cascade)
   user     User     @relation(fields: [user_id], references: [user_id], onDelete: Cascade)
 
   @@index([user_id])
+  @@index([status])
 }
 
 model Settlement {

src/index.ts

@@ -18,6 +18,7 @@ import promptRoutes from "./prompts/routes/prompt.route"; // 프롬프트 관련
 import ReviewRouter from "./reviews/routes/review.route";
 import purchaseRouter from "./purchases/routes/purchase.route";
 import refundRouter from "./refunds/routes/refund.route";
+import adminRefundRouter from "./refunds/routes/admin-refund.route";
 import payoutWebhookRouter from "./settlements/routes/payout-webhook.route";
 import purchaseWebhookRouter from "./purchases/routes/purchase.webhook.route";
 import settlementRouter from "./settlements/routes/settlement.route";
@@ -173,6 +174,8 @@ app.use("/api/prompts", promptLikeRouter);
 app.use("/api/admin/prompts", adminPromptRouter);
 app.use("/api/admin/sellers", adminSellerRouter);
 app.use("/api/admin/stats", adminStatsRouter);
+app.use("/api/admin/refunds", adminRefundRouter);
+// adminMemberRouter는 /api/admin 전체를 받으므로 하위 경로 라우터보다 뒤에 마운트.
 app.use("/api/admin", adminMemberRouter);
 
 // 팁 라우터

src/prompts/dtos/prompt.download.dto.ts

@@ -11,7 +11,11 @@ export interface DownloadedPromptResponseDTO {
   message: string;
   prompt_id: number;
   purchase_id: number;
-  is_refunded: boolean;
+  is_refunded: boolean; // 환불 확정(APPROVED/COMPLETED) 여부
+  refund_status: string | null; // REQUESTED | APPROVED | REJECTED | COMPLETED (#533)
+  refundable: boolean; // 열람 전 + 7일 이내 → 즉시 환불 버튼 활성화 (#533)
+  refund_deadline: string | null; // 자동 환불 마감 시각 (#533)
+  manual_refund_available: boolean; // 열람 후 + 3개월 이내 → 환불 신청 버튼 활성화 (#533)
   title: string;
   description: string;
   models: string[];

src/prompts/repositories/prompt.download.repository.ts

@@ -28,7 +28,9 @@ export const PromptDownloadRepository = {
     return prisma.purchase.findMany({
       where: { user_id: userId },
       include: {
-        refund: { select: { refund_id: true } },
+        // 환불 가능 여부 판정에 필요한 필드 (#533) — 판정 자체는 refund-policy가 담당
+        refund: { select: { refund_id: true, status: true } },
+        payment: { select: { status: true } },
         prompt: {
           select: {
             prompt_id: true,

src/prompts/routes/prompt.download.route.ts

@@ -99,7 +99,23 @@ router.get('/:promptId/downloads', authenticateJwt, PromptDownloadController.get
  *                     properties:
  *                       prompt_id: { type: integer }
  *                       purchase_id: { type: integer, description: 환불 API 호출에 필요한 구매 ID }
- *                       is_refunded: { type: boolean, description: 환불 완료 여부 }
+ *                       is_refunded: { type: boolean, description: '환불 확정 여부 (APPROVED/COMPLETED)' }
+ *                       refund_status:
+ *                         type: string
+ *                         nullable: true
+ *                         enum: [REQUESTED, APPROVED, REJECTED, COMPLETED]
+ *                         description: 환불 진행 상태 (환불 이력 없으면 null)
+ *                       refundable:
+ *                         type: boolean
+ *                         description: '즉시 환불 버튼 활성화 여부 — 미열람 + 구매 후 7일 이내(KST 날짜 기준)'
+ *                       refund_deadline:
+ *                         type: string
+ *                         format: date-time
+ *                         nullable: true
+ *                         description: 즉시 환불 마감 시각
+ *                       manual_refund_available:
+ *                         type: boolean
+ *                         description: '환불 신청 버튼 활성화 여부 — 열람함 + 구매 후 3개월 이내'
  *                       title: { type: string }
  *                       description: { type: string, nullable: true }
  *                       price: { type: integer }

src/prompts/services/prompt.download.service.ts

@@ -2,6 +2,12 @@ import { PromptDownloadRepository } from '../repositories/prompt.download.reposi
 import { PromptDownloadResponseDTO, DownloadedPromptResponseDTO } from '../dtos/prompt.download.dto';
 import { AppError } from '../../errors/AppError';
 import prisma from "../../config/prisma";
+import {
+  checkAutoRefund,
+  checkManualRefund,
+  isRefundSettled,
+  toPolicyInput,
+} from '../../refunds/utils/refund-policy';
 
 export const PromptDownloadService = {
 async getPromptContent(userId: number, promptId: number): Promise<PromptDownloadResponseDTO> {
@@ -22,11 +28,12 @@ async getPromptContent(userId: number, promptId: number): Promise<PromptDownload
       },
       include: {
         payment: true,
-        refund: { select: { refund_id: true } },
+        refund: { select: { refund_id: true, status: true } },
       },
     });
 
-    if (purchase?.refund) {
+    // 신청(REQUESTED) 단계는 아직 검토 중이므로 열람을 막지 않는다. 확정된 건만 차단. (#533)
+    if (isRefundSettled(purchase?.refund?.status)) {
       throw new AppError('환불된 프롬프트는 다시 다운로드할 수 없습니다.', 403, 'Refunded');
     }
 
@@ -97,6 +104,11 @@ async getDownloadedPrompts(userId: number): Promise<DownloadedPromptResponseDTO[
 
     return downloads.map((purchase) => {
         const { prompt } = purchase;
+        // 환불 버튼 활성화 판정 — 단건 환불 API와 동일한 정책 함수를 쓴다 (#533)
+        const policyInput = toPolicyInput(purchase);
+        const autoVerdict = checkAutoRefund(policyInput, userId);
+        const manualVerdict = checkManualRefund(policyInput, userId);
+
         const userReviewRaw = prompt.reviews[0];
         const hasReview = !!userReviewRaw;
         const isRecentReview = hasReview && new Date(userReviewRaw.created_at) >= THIRTY_DAYS_AGO;
@@ -115,7 +127,11 @@ async getDownloadedPrompts(userId: number): Promise<DownloadedPromptResponseDTO[
 
             prompt_id: prompt.prompt_id,
             purchase_id: purchase.purchase_id,
-            is_refunded: !!purchase.refund,
+            is_refunded: isRefundSettled(purchase.refund?.status),
+            refund_status: purchase.refund?.status ?? null,
+            refundable: autoVerdict.eligible,
+            refund_deadline: autoVerdict.refund_deadline,
+            manual_refund_available: manualVerdict.eligible,
             title: prompt.title,
              description: prompt.description,
             price: prompt.price,

src/purchases/dtos/purchase.request.dto.ts

@@ -3,6 +3,8 @@ export type PaypleClientPayType = 'card' | 'transfer';
 export interface PurchaseRequestDTO {
   prompt_id: number;
   pay_type?: PaypleClientPayType;
+  // "디지털콘텐츠 특성상 열람(제공 개시) 후에는 단순 변심 환불이 불가합니다" 동의 (#533)
+  refund_policy_agreed: boolean;
 }
 
 export interface PurchaseRequestResponseDTO {

src/purchases/repositories/purchase.complete.repository.ts

@@ -8,6 +8,7 @@ export const PurchaseCompleteRepository = {
     prompt_id: number;
     amount: number;
     is_free: false;
+    refund_policy_agreed_at?: Date | null;
   }) {
     return tx.purchase.create({ data });
   },

src/purchases/routes/purchase.route.ts

@@ -30,6 +30,7 @@ const router = Router();
  *             type: object
  *             required:
  *               - prompt_id
+ *               - refund_policy_agreed
  *             properties:
  *               prompt_id:
  *                 type: integer
@@ -39,6 +40,14 @@ const router = Router();
  *                 enum: [card, transfer]
  *                 default: card
  *                 description: 결제 수단 (card=카드, transfer=계좌이체)
+ *               refund_policy_agreed:
+ *                 type: boolean
+ *                 example: true
+ *                 description: |
+ *                   환불정책 동의 체크박스. 결제 화면에 아래 문구와 함께 노출해야 하며,
+ *                   true가 아니면 400 `RefundPolicyNotAgreed`로 주문서가 생성되지 않습니다.
+ *
+ *                   "디지털콘텐츠 특성상 열람(제공 개시) 후에는 단순 변심 환불이 불가합니다"
  *     responses:
  *       200:
  *         description: 주문서 생성 성공 (페이플 일반결제 연동 데이터 반환)

src/purchases/services/purchase.complete.service.ts

@@ -3,7 +3,7 @@ import { PurchaseRequestRepository } from '../repositories/purchase.request.repo
 import { PurchaseCompleteRepository } from '../repositories/purchase.complete.repository';
 import { AppError } from '../../errors/AppError';
 import prisma from '../../config/prisma';
-import { verifyPayplePayment } from '../utils/payple';
+import { parseAgreedAt, verifyPayplePayment } from '../utils/payple';
 import { calculateSettlementFee } from '../utils/fee';
 
 export const PurchaseCompleteService = {
@@ -32,6 +32,8 @@ export const PurchaseCompleteService = {
         prompt_id: prompt.prompt_id,
         amount: serverPrice,
         is_free: false,
+        // 주문서 생성 시 검증된 환불정책 동의 시각 (#533)
+        refund_policy_agreed_at: parseAgreedAt(verifiedPayment.customData?.agreed_at),
       });
 
       const payment = await PurchaseCompleteRepository.createPaymentTx(tx, {

src/purchases/services/purchase.request.service.ts

@@ -6,6 +6,15 @@ import { requestPaypleAuth } from '../utils/payple';
 
 export const PurchaseRequestService = {
   async createPurchaseRequest(userId: number, dto: PurchaseRequestDTO): Promise<PurchaseRequestResponseDTO> {
+    // 환불정책 동의 없이는 주문서 자체를 만들지 않는다 (#533)
+    if (dto.refund_policy_agreed !== true) {
+      throw new AppError(
+        '디지털콘텐츠 특성상 열람(제공 개시) 후에는 단순 변심 환불이 불가합니다. 동의가 필요합니다.',
+        400,
+        'RefundPolicyNotAgreed',
+      );
+    }
+
     const prompt = await PurchaseRequestRepository.findPromptWithSeller(dto.prompt_id);
     if (!prompt) throw new AppError('프롬프트를 찾을 수 없습니다.', 404, 'NotFound');
 
@@ -35,6 +44,8 @@ export const PurchaseRequestService = {
       PCD_USER_DEFINE1: JSON.stringify({
         prompt_id: dto.prompt_id,
         user_id: userId,
+        // 동의 시각은 결제 완료 시 Purchase에 기록된다 (#533)
+        agreed_at: new Date().toISOString(),
       }),
       PCD_RST_URL: process.env.PAYPLE_RST_URL || '',
     };

src/purchases/services/purchase.webhook.service.ts

@@ -1,7 +1,7 @@
 import { PurchaseRequestRepository } from '../repositories/purchase.request.repository';
 import { PurchaseCompleteRepository } from '../repositories/purchase.complete.repository';
 import prisma from '../../config/prisma';
-import { PayplePaymentResult, verifyPayplePayment } from '../utils/payple';
+import { PayplePaymentResult, parseAgreedAt, verifyPayplePayment } from '../utils/payple';
 import { calculateSettlementFee } from '../utils/fee';
 
 export const WebhookService = {
@@ -44,6 +44,9 @@ export const WebhookService = {
           prompt_id: prompt.prompt_id,
           amount: serverPrice,
           is_free: false,
+          // 웹훅이 /complete보다 먼저 도착하면 여기서 Purchase가 만들어지므로
+          // 동의 시각도 같이 기록해야 유실되지 않는다 (#533)
+          refund_policy_agreed_at: parseAgreedAt(verified.customData?.agreed_at),
         });
 
         const payment = await PurchaseCompleteRepository.createPaymentTx(tx, {

src/purchases/utils/payple.ts

@@ -114,7 +114,7 @@ export type PaypleVerifiedPayment = {
   bankName?: string | null;
   bankNum?: string | null;
   cashReceiptUrl?: string | null;
-  customData: { prompt_id?: number; user_id?: number };
+  customData: { prompt_id?: number; user_id?: number; agreed_at?: string };
 };
 
 function parseCustomDefine(define?: string): any {
@@ -126,6 +126,15 @@ function parseCustomDefine(define?: string): any {
   }
 }
 
+// 주문서(PCD_USER_DEFINE1)에 실어 보낸 환불정책 동의 시각.
+// 결제 완료 경로가 클라이언트 /complete와 웹훅 두 갈래라 양쪽이 같은 파서를 쓴다. (#533)
+// 값이 손상됐으면 기록만 생략하고 결제 자체는 진행한다.
+export function parseAgreedAt(raw?: string): Date | null {
+  if (!raw) return null;
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
 function parsePaypleTime(t?: string): Date {
   if (!t) return new Date();
   const m = t.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/);