Skip to content

[FIX] Swagger 갱신 — 정산/환불/다운로드 흐름 변경 사항 반영 + 라우터 마운트 순서 정정 (#494)#495

Merged
minij02 merged 6 commits into
developfrom
fix/#494
May 22, 2026
Merged

[FIX] Swagger 갱신 — 정산/환불/다운로드 흐름 변경 사항 반영 + 라우터 마운트 순서 정정 (#494)#495
minij02 merged 6 commits into
developfrom
fix/#494

Conversation

@minij02
Copy link
Copy Markdown
Collaborator

@minij02 minij02 commented May 22, 2026

Summary

3개 에이전트 교차 검증 결과 CRITICAL/HIGH 6건 정리. 단일 PR이지만 항목별 커밋 분리해 리뷰 용이.

커밋 분리

# 커밋 내용
1 00c94ab refundRouter mount 순서 정정 (CRITICAL — purchaseRouter 뒤로 이동, path 충돌 위험 차단)
2 ca0dad6 prompt download Swagger 전면 재작성 (CRITICAL — 응답 schema 실제 코드와 일치, 403 Refunded 추가, GET /downloads JSDoc 신규)
3 2ea21af /pending-amount stale 멘트 정정 (CRITICAL — settlement-sync 이미 구현됨)
4 4f34826 purchase complete enum에 Refunded 추가 + 미반환 pg 필드 제거 (HIGH)
5 130dc44 admin-seller 상세 응답에 status 필드 추가 (HIGH — /account/detail과 일관성)
6 529b95d swagger.json 재생성

별도 이슈로 분리 (기존 부채)

  • withdrawals, announcements 라우트 Swagger 전체 부재
  • members/tips/inquiries 일부 endpoint Swagger 누락
  • auth/logout HTTP 메서드 일관성
  • prisma select 강제로 PII 회귀 방지 가이드
  • purchase 결제내역 API에 환불 정보(status/refunded_at) 추가 (DTO + service 변경 동반)
  • register 흐름에 subCode 응답 schema (현재 의미 약해 보류)

API 변경 (프론트 동기화)

항목 변경
POST /api/prompts/purchases/complete 응답 status enum에 Refunded 추가
GET /api/prompts/purchases (결제내역) 응답 pg 필드 명세 제거 (실제 미반환이라 swagger 정정만, 코드 변화 없음)
GET /api/prompts/:promptId/downloads 403 Refunded 응답 추가, 응답 schema 정정 (PromptContent{message, title, prompt, is_free, is_paid, statusCode})
GET /api/prompts/downloads Swagger 신규 명세
GET /api/admin/sellers/individual/:userId, /business/:userId 응답에 status 필드 추가 (APPROVED/PENDING/REJECTED)
refundRouter 경로 그대로 (mount 순서만 변경) — 프론트 영향 없음

Test plan

  • pnpm build / pnpm tsc --noEmit 통과
  • swagger.json 정상 생성
  • /api/prompts/purchases/* 라우트 동작 검증 (refundRouter mount 순서 변경 후 path 매칭)
  • 환불 시 다운로드 시도가 403 Refunded 반환하는지 확인
  • admin 상세 응답에 status 필드 노출 확인
  • 프론트 동기화 후 머지

Closes #494

minij02 added 6 commits May 23, 2026 04:41
src/index.ts에서 refundRouter가 purchaseRouter보다 먼저 동일 prefix
(/api/prompts/purchases)에 마운트되어, 향후 purchaseRouter에 :id
동적 라우트가 추가될 경우 refundRouter의 :purchaseId 패턴에 가려질 위험.
순서를 뒤집어 purchaseRouter가 먼저 매치되도록 정정.

프론트 영향 없음 (현재 purchaseRouter는 정적 path만 사용 - /requests, /, /complete).
#485 환불 흐름 도입 후 prompt.download.route.ts의 Swagger가 실제 응답과
완전 불일치 상태였음. 전면 재작성.

- GET /:promptId/downloads
  - 응답 schema를 실제 service 반환 형태({message, title, prompt, is_free, is_paid, statusCode})로 정정
  - 환불된 구매 시 403 Refunded 응답 예시 추가
  - 결제 미완료 시 403 Forbidden 응답 예시 추가
  - 첫 다운로드 시 Purchase.downloaded_at 기록 부작용 설명 추가
- GET /downloads
  - 기존 JSDoc 부재 → 전체 신규 작성
  - 응답 schema에 has_review/is_recent_review/userReview/imageUrls 등 포함
#479 시점 작성된 "Settlement.status를 'Succeed'로 업데이트하는 정산 완료
처리 흐름이 없어서..." 경고문이 #482/#483 settlement-sync 머지 이후로
사실과 달라짐. 실제 동작 (KST 08:00 cron + 환불 시 Refunded 전이)으로 교체.
- POST /complete 응답 status enum에 'Refunded' 추가 (#485에서 Status enum
  확장됐는데 본 응답엔 누락 — 프론트 switch가 default fallthrough될 위험)
- GET / (결제내역) 응답 schema에서 'pg' 필드 제거 — Swagger엔 명시됐으나
  실제 PurchaseHistoryService.list가 반환하지 않는 stale 명세
  (결제내역에 환불 표시 추가는 별도 커밋에서 service/DTO 변경과 함께 진행)
#473에서 /account/detail에 status 추가됐는데 admin 상세 응답엔 누락되어 일관성 결여.

- IndividualSellerDetail / BusinessSellerDetail DTO에 status 필드 추가
- getIndividualSellerDetail / getBusinessSellerDetail 서비스에서 account.status 노출
- admin-seller.route.ts swagger 두 응답에 status enum 명세 추가

현재 admin 상세 API는 status='APPROVED'만 조회하지만, 향후 PENDING/REJECTED도
조회 가능하게 확장될 경우 응답 형식 변경 없이 그대로 동작.
이전 5개 커밋의 라우트 swagger 변경을 swagger.json에 반영.
@minij02 minij02 merged commit ef1614a into develop May 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant