Develop

prisma/migrations/20260523140000_add_refund_model_and_status/migration.sql

@@ -0,0 +1,33 @@
+-- AlterTable: Purchase 다운로드 시점 컬럼
+ALTER TABLE `Purchase` ADD COLUMN `downloaded_at` DATETIME(3) NULL;
+
+-- AlterTable: Status enum에 Refunded 추가
+ALTER TABLE `Payment` MODIFY COLUMN `status` ENUM('Pending','Succeed','Failed','Refunded') NOT NULL;
+ALTER TABLE `Settlement` MODIFY COLUMN `status` ENUM('Pending','Succeed','Failed','Refunded') NOT NULL;
+
+-- CreateTable: Refund
+CREATE TABLE `Refund` (
+    `refund_id` INTEGER NOT NULL AUTO_INCREMENT,
+    `purchase_id` INTEGER NOT NULL,
+    `payment_id` INTEGER NOT NULL,
+    `user_id` INTEGER NOT NULL,
+    `amount` INTEGER NOT NULL,
+    `reason` VARCHAR(200) NULL,
+    `initiator` VARCHAR(20) NOT NULL,
+    `payple_pay_code` VARCHAR(20) NULL,
+    `payple_card_trade_num` VARCHAR(64) NULL,
+    `refunded_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    UNIQUE INDEX `Refund_purchase_id_key`(`purchase_id`),
+    UNIQUE INDEX `Refund_payment_id_key`(`payment_id`),
+    INDEX `Refund_user_id_idx`(`user_id`),
+    PRIMARY KEY (`refund_id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `Refund` ADD CONSTRAINT `Refund_purchase_id_fkey`
+    FOREIGN KEY (`purchase_id`) REFERENCES `Purchase`(`purchase_id`) ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE `Refund` ADD CONSTRAINT `Refund_payment_id_fkey`
+    FOREIGN KEY (`payment_id`) REFERENCES `Payment`(`payment_id`) ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE `Refund` ADD CONSTRAINT `Refund_user_id_fkey`
+    FOREIGN KEY (`user_id`) REFERENCES `User`(`user_id`) ON DELETE CASCADE ON UPDATE CASCADE;

src/index.ts

@@ -16,6 +16,7 @@ import membersRouter from "./members/routes/member.route"; // members 라우터
 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 purchaseWebhookRouter from "./purchases/routes/purchase.webhook.route";
 import settlementRouter from "./settlements/routes/settlement.route";
 import withdrawalRouter from "./withdrawals/routes/withdrawal.route";
@@ -138,6 +139,7 @@ app.use("/api/prompts", promptRoutes);
 app.use("/api/prompts/purchases", purchaseWebhookRouter);
 
 // 프롬프트 결제 라우터
+app.use("/api/prompts/purchases", refundRouter);
 app.use(
   "/api/prompts/purchases",
   express.text({ type: "text/plain" }),

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

@@ -14,22 +14,35 @@ async getPromptContent(userId: number, promptId: number): Promise<PromptDownload
   let isPaid = false;
 
   if (!prompt.is_free) {
-    // 유료 프롬프트일 경우 결제 상태 확인
+    // 유료 프롬프트일 경우 결제 상태 + 환불 여부 확인
     const purchase = await prisma.purchase.findFirst({
       where: {
         user_id: userId,
         prompt_id: promptId,
       },
       include: {
         payment: true,
+        refund: { select: { refund_id: true } },
       },
     });
 
+    if (purchase?.refund) {
+      throw new AppError('환불된 프롬프트는 다시 다운로드할 수 없습니다.', 403, 'Refunded');
+    }
+
     isPaid = purchase?.payment?.status === 'Succeed';
 
     if (!isPaid) {
       throw new AppError('해당 프롬프트는 무료가 아니며, 결제가 완료되지 않았습니다.', 403, 'Forbidden');
     }
+
+    // 첫 다운로드 시점 기록 — 이후 환불 불가 (#485)
+    if (purchase && !purchase.downloaded_at) {
+      await prisma.purchase.update({
+        where: { purchase_id: purchase.purchase_id },
+        data: { downloaded_at: new Date() },
+      });
+    }
   } else {
     // 무료 프롬프트일 경우 purchase 기록이 없다면 추가
     const existingPurchase = await prisma.purchase.findFirst({

src/refunds/controllers/refund.controller.ts

@@ -0,0 +1,57 @@
+import { Request, Response } from 'express';
+import { getRefundEligibility, refundPurchase } from '../services/refund.service';
+
+const getUserId = (req: Request): number | null => {
+  if (!req.user) return null;
+  return (req.user as { user_id: number }).user_id;
+};
+
+const parsePurchaseId = (raw: string): number | null => {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) return null;
+  return n;
+};
+
+export const checkRefundEligibility = async (req: Request, res: Response) => {
+  const userId = getUserId(req);
+  if (!userId) {
+    return res.status(401).json({ error: 'Unauthorized', message: '로그인이 필요합니다.', statusCode: 401 });
+  }
+  const purchaseId = parsePurchaseId(req.params.purchaseId);
+  if (!purchaseId) {
+    return res.status(400).json({ error: 'ValidationError', message: 'purchaseId가 올바르지 않습니다.', statusCode: 400 });
+  }
+  try {
+    const result = await getRefundEligibility(userId, purchaseId);
+    return res.status(200).json(result);
+  } catch (error: any) {
+    const status = error.statusCode || 500;
+    return res.status(status).json({
+      error: error.error || 'InternalServerError',
+      message: error.message || '서버 오류가 발생했습니다.',
+      statusCode: status,
+    });
+  }
+};
+
+export const refundPurchaseHandler = async (req: Request, res: Response) => {
+  const userId = getUserId(req);
+  if (!userId) {
+    return res.status(401).json({ error: 'Unauthorized', message: '로그인이 필요합니다.', statusCode: 401 });
+  }
+  const purchaseId = parsePurchaseId(req.params.purchaseId);
+  if (!purchaseId) {
+    return res.status(400).json({ error: 'ValidationError', message: 'purchaseId가 올바르지 않습니다.', statusCode: 400 });
+  }
+  try {
+    const result = await refundPurchase(userId, purchaseId);
+    return res.status(200).json(result);
+  } catch (error: any) {
+    const status = error.statusCode || 500;
+    return res.status(status).json({
+      error: error.error || 'InternalServerError',
+      message: error.message || '서버 오류가 발생했습니다.',
+      statusCode: status,
+    });
+  }
+};

src/refunds/dtos/refund.dto.ts

@@ -0,0 +1,24 @@
+export type RefundIneligibleReason =
+  | 'EXPIRED_7DAYS'
+  | 'ALREADY_DOWNLOADED'
+  | 'ALREADY_REFUNDED'
+  | 'NOT_OWNER'
+  | 'NOT_PURCHASED'
+  | 'PAYMENT_NOT_SUCCEEDED'
+  | 'FREE_PURCHASE';
+
+export interface RefundEligibilityResponseDto {
+  message: string;
+  eligible: boolean;
+  reason?: RefundIneligibleReason;
+  remaining_seconds?: number;  // 환불 가능한 잔여 시간 (eligible=true일 때만)
+  statusCode: number;
+}
+
+export interface RefundResultDto {
+  message: string;
+  refund_id: number;
+  refunded_amount: number;
+  refunded_at: string;
+  statusCode: number;
+}

src/refunds/routes/refund.route.ts

@@ -0,0 +1,103 @@
+import { Router } from 'express';
+import { authenticateJwt } from '../../config/passport';
+import {
+  checkRefundEligibility,
+  refundPurchaseHandler,
+} from '../controllers/refund.controller';
+
+const router = Router();
+
+/**
+ * @swagger
+ * tags:
+ *   - name: Refund
+ *     description: 구매 환불 (7일 이내 미열람 자동 환불)
+ */
+
+/**
+ * @swagger
+ * /api/prompts/purchases/{purchaseId}/refund-eligibility:
+ *   get:
+ *     summary: 환불 가능 여부 조회
+ *     description: |
+ *       구매 건이 환불 가능한지 검증. 환불 가능 조건은 다음을 모두 만족:
+ *       - 본인 구매
+ *       - 유료 구매
+ *       - 결제 상태 Succeed
+ *       - 환불 이력 없음
+ *       - 다운로드 이력 없음 (`Purchase.downloaded_at` 미값)
+ *       - 구매 후 7일(168시간) 이내
+ *     tags: [Refund]
+ *     security:
+ *       - jwt: []
+ *     parameters:
+ *       - in: path
+ *         name: purchaseId
+ *         required: true
+ *         schema: { type: integer }
+ *     responses:
+ *       200:
+ *         description: 조회 성공 (eligible true/false)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message: { type: string }
+ *                 eligible: { type: boolean }
+ *                 reason:
+ *                   type: string
+ *                   enum: [EXPIRED_7DAYS, ALREADY_DOWNLOADED, ALREADY_REFUNDED, NOT_OWNER, NOT_PURCHASED, PAYMENT_NOT_SUCCEEDED, FREE_PURCHASE]
+ *                   description: eligible=false일 때만 존재
+ *                 remaining_seconds:
+ *                   type: integer
+ *                   description: eligible=true일 때 환불 가능 잔여 시간(초)
+ *                 statusCode: { type: integer, example: 200 }
+ *       401:
+ *         description: 로그인 필요
+ *       400:
+ *         description: 잘못된 purchaseId
+ */
+router.get('/:purchaseId/refund-eligibility', authenticateJwt, checkRefundEligibility);
+
+/**
+ * @swagger
+ * /api/prompts/purchases/{purchaseId}/refund:
+ *   post:
+ *     summary: 환불 실행
+ *     description: |
+ *       7일 이내 + 미열람 조건을 만족하면 Payple 결제 취소를 호출하고 DB(Refund/Payment/Settlement) 정합화.
+ *       조건 미충족 시 400 RefundNotEligible.
+ *     tags: [Refund]
+ *     security:
+ *       - jwt: []
+ *     parameters:
+ *       - in: path
+ *         name: purchaseId
+ *         required: true
+ *         schema: { type: integer }
+ *     responses:
+ *       200:
+ *         description: 환불 성공
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message: { type: string, example: 환불이 완료되었습니다. }
+ *                 refund_id: { type: integer }
+ *                 refunded_amount: { type: integer }
+ *                 refunded_at: { type: string, format: date-time }
+ *                 statusCode: { type: integer, example: 200 }
+ *       400:
+ *         description: 환불 불가 (RefundNotEligible)
+ *       401:
+ *         description: 로그인 필요
+ *       404:
+ *         description: 환불 대상 결제 정보를 찾을 수 없음
+ *       502:
+ *         description: Payple 환불 호출 실패 (PaypleRefundFailed)
+ */
+router.post('/:purchaseId/refund', authenticateJwt, refundPurchaseHandler);
+
+export default router;