From dda5de4d61ffbd847bb541b6eaa326ad194dedf0 Mon Sep 17 00:00:00 2001 From: Klaus Date: Wed, 30 Sep 2026 17:37:16 +0900 Subject: [PATCH] =?UTF-8?q?docs(gift):=20=EC=84=A0=EB=AC=BC=20=ED=81=B4?= =?UTF-8?q?=EB=9D=BC=EC=9D=B4=EC=96=B8=ED=8A=B8=20=EA=B3=84=EC=95=BD?= =?UTF-8?q?=EA=B3=BC=20DDL=EC=9D=84=20=EA=B0=B1=EC=8B=A0=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../client-api-summary.md | 46 +++++++++++-------- .../gift-schema.sql | 19 +++++--- 2 files changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/20260929_크리에이터_선물하기/client-api-summary.md b/docs/20260929_크리에이터_선물하기/client-api-summary.md index be779547..c78f353e 100644 --- a/docs/20260929_크리에이터_선물하기/client-api-summary.md +++ b/docs/20260929_크리에이터_선물하기/client-api-summary.md @@ -42,9 +42,9 @@ PRD에는 상세 API 계약, request/response 예시, 요구사항을 유지한 | 사용자 | Method | URI | 역할 | Request | Response | |---|---:|---|---|---|---| | 관리자 | GET | `/api/v2/admin/gift-categories` | 선물 카테고리 목록을 조회한다. | 없음 | `AdminGiftCategoryResponse[]` | -| 관리자 | POST | `/api/v2/admin/gift-categories` | 선물 카테고리를 등록한다. | body: `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` | `categoryId`, `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` | -| 관리자 | PUT | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 수정한다. | path: `categoryId`, body: `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` | `categoryId`, `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` | -| 관리자 | DELETE | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 비활성화한다. | path: `categoryId` | `categoryId`, `categoryCode`, `name`, `requiresDamageWaiver`, `isActive=false` | +| 관리자 | POST | `/api/v2/admin/gift-categories` | 선물 카테고리를 등록한다. | body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | +| 관리자 | PUT | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 수정한다. | path: `categoryId`, body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | +| 관리자 | DELETE | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 비활성화한다. | path: `categoryId` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive=false` | | 관리자 | GET | `/api/v2/admin/gift-size-prices` | 사이즈별 기본가와 판매가를 조회한다. | 없음 | `AdminGiftSizePriceResponse[]` | | 관리자 | PUT | `/api/v2/admin/gift-size-prices/{sizeCode}` | 사이즈별 기본가와 판매가를 수정한다. | path: `sizeCode`, body: `basePriceCan`, `salePriceCan`, `isActive` | `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive` | | 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox` | 발송 확인 선물을 사서함 도착 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` | @@ -54,13 +54,13 @@ PRD에는 상세 API 계약, request/response 예시, 요구사항을 유지한 관리자 응답 DTO 요약: -- `AdminGiftCategoryResponse`: `categoryId`, `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` +- `AdminGiftCategoryResponse`: `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` - `AdminGiftSizePriceResponse`: `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive` - `AdminGiftOperationStatusResponse`: `applicationNo`, `status`, `statusName`, `occurredAt` ## Kotlin DTO 형태 -아래는 JSON으로 변환되기 직전의 API request/response `data class` 형태다. `companion object` 변환 함수는 클라이언트 입력/출력 형태와 직접 관련이 없어 생략했다. +아래는 JSON으로 변환되기 직전의 API request/response `data class` 형태다. `companion object` 변환 함수는 클라이언트 입력/출력 형태와 직접 관련이 없어 생략했다. 응답 시각 필드는 UTC ISO 문자열이다. 예: `2026-09-30T12:00:00Z`. ### 사용자 Request DTO @@ -122,6 +122,8 @@ data class GiftCategoryOptionResponse( val requiresDamageWaiver: Boolean ) +// name은 사용자 폼 옵션에서만 "분류명/대표품목" 형태로 조합된다. + data class GiftListResponse( val totalCount: Long, val items: List, @@ -138,7 +140,7 @@ data class GiftListItemResponse( val priceCan: Int, val categoryName: String, val sizeName: String, - val createdAt: LocalDateTime? + val createdAt: String? ) data class GiftDetailResponse( @@ -152,7 +154,7 @@ data class GiftDetailResponse( val mailbox: GiftMailboxResponse?, val trackingRequired: Boolean, val recipientAddressRequired: Boolean, - val recipientAddressDeadlineAt: LocalDateTime?, + val recipientAddressDeadlineAt: String?, val delivery: GiftDeliveryInfoResponse, val statusTimeline: List ) @@ -165,7 +167,7 @@ data class GiftDetailInfoResponse( val applicationNo: String?, val paidCan: Int?, val tracking: String?, - val shippingRequestedAt: LocalDateTime? + val shippingRequestedAt: String? ) data class GiftAddressResponse( @@ -181,15 +183,15 @@ data class GiftMailboxResponse( ) data class GiftDeliveryInfoResponse( - val canceledAt: LocalDateTime?, - val undeliverableAt: LocalDateTime?, + val canceledAt: String?, + val undeliverableAt: String?, val undeliverableReason: String? ) data class GiftStatusTimelineResponse( val status: String, val statusName: String, - val occurredAt: LocalDateTime? + val occurredAt: String? ) data class GiftApplicationResponse( @@ -197,7 +199,7 @@ data class GiftApplicationResponse( val status: String, val statusName: String, val priceCan: Int, - val trackingDeadlineAt: LocalDateTime + val trackingDeadlineAt: String ) data class GiftCancellationResponse( @@ -205,7 +207,7 @@ data class GiftCancellationResponse( val status: String, val statusName: String, val priceCan: Int, - val canceledAt: LocalDateTime + val canceledAt: String ) data class GiftTrackingRegistrationResponse( @@ -214,22 +216,22 @@ data class GiftTrackingRegistrationResponse( val statusName: String, val courierCompanyName: String, val trackingNumber: String, - val trackingRegisteredAt: LocalDateTime, - val recipientAddressDeadlineAt: LocalDateTime + val trackingRegisteredAt: String, + val recipientAddressDeadlineAt: String ) data class GiftRecipientAddressRegistrationResponse( val applicationNo: String, val status: String, val statusName: String, - val recipientAddressRegisteredAt: LocalDateTime + val recipientAddressRegisteredAt: String ) data class GiftDeliveryConfirmationResponse( val applicationNo: String, val status: String, val statusName: String, - val deliveredAt: LocalDateTime + val deliveredAt: String ) data class GiftReviewResponse( @@ -238,7 +240,7 @@ data class GiftReviewResponse( val rating: Int, val keywords: List, val comment: String?, - val createdAt: LocalDateTime? + val createdAt: String? ) ``` @@ -246,8 +248,11 @@ data class GiftReviewResponse( ```kotlin data class AdminGiftCategoryRequest( + val classificationNumber: String, val categoryCode: String, val name: String, + val receiptCode: String, + val representativeItem: String, val requiresDamageWaiver: Boolean, val isActive: Boolean ) @@ -268,8 +273,11 @@ data class AdminGiftMarkUndeliverableRequest( ```kotlin data class AdminGiftCategoryResponse( val categoryId: Long, + val classificationNumber: String, val categoryCode: String, val name: String, + val receiptCode: String, + val representativeItem: String, val requiresDamageWaiver: Boolean, val isActive: Boolean ) @@ -286,7 +294,7 @@ data class AdminGiftOperationStatusResponse( val applicationNo: String, val status: GiftStatus, val statusName: String, - val occurredAt: LocalDateTime + val occurredAt: String ) ``` diff --git a/docs/20260929_크리에이터_선물하기/gift-schema.sql b/docs/20260929_크리에이터_선물하기/gift-schema.sql index f8302a87..7e969356 100644 --- a/docs/20260929_크리에이터_선물하기/gift-schema.sql +++ b/docs/20260929_크리에이터_선물하기/gift-schema.sql @@ -1,18 +1,23 @@ CREATE TABLE gift_category ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키', - category_code VARCHAR(50) NOT NULL COMMENT '내부 분류번호', - name VARCHAR(50) NOT NULL COMMENT '카테고리 표시명', + classification_number VARCHAR(3) NOT NULL COMMENT '신청번호에 사용하는 3자리 분류번호', + category_code VARCHAR(50) NOT NULL COMMENT '내부 범용코드', + name VARCHAR(50) NOT NULL COMMENT '분류명', + receipt_code VARCHAR(9) NOT NULL COMMENT '신청번호에 사용하는 접수코드', + representative_item VARCHAR(100) NOT NULL COMMENT '대표품목', requires_damage_waiver TINYINT(1) NOT NULL COMMENT '파손면책 동의 필요 여부', is_active TINYINT(1) NOT NULL COMMENT '활성 여부', created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각', PRIMARY KEY (id), - UNIQUE KEY uk_gift_category_code (category_code) + UNIQUE KEY uk_gift_category_classification_number (classification_number), + UNIQUE KEY uk_gift_category_code (category_code), + UNIQUE KEY uk_gift_category_receipt_code (receipt_code) ) COMMENT='선물 카테고리'; CREATE TABLE gift ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키', - application_no VARCHAR(20) NOT NULL COMMENT '신청번호', + application_no VARCHAR(40) NOT NULL COMMENT '신청번호', sender_member_id BIGINT NOT NULL COMMENT '보내는 팬 회원번호', recipient_member_id BIGINT NOT NULL COMMENT '받는 크리에이터 회원번호', status VARCHAR(30) NOT NULL COMMENT '선물 상태', @@ -102,10 +107,12 @@ CREATE TABLE gift_review ( CREATE TABLE gift_application_no_sequence ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키', - sequence_date VARCHAR(8) NOT NULL COMMENT '채번 기준일 yyyyMMdd', + category_id BIGINT NOT NULL COMMENT '채번 기준 카테고리 ID', + sequence_date VARCHAR(6) NOT NULL COMMENT '채번 기준일 yyMMdd', last_sequence INT NOT NULL COMMENT '마지막 일련번호', created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각', updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각', PRIMARY KEY (id), - UNIQUE KEY uk_gift_application_no_sequence_date (sequence_date) + UNIQUE KEY uk_gift_application_no_sequence_category_date (category_id, sequence_date), + CONSTRAINT fk_gift_application_no_sequence_category FOREIGN KEY (category_id) REFERENCES gift_category (id) ) COMMENT='선물 신청번호 날짜별 채번';