docs(gift): 선물 클라이언트 계약과 DDL을 갱신한다

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` |
+| 관리자 | 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: `categoryCode`, `name`, `requiresDamageWaiver`, `isActive` | `categoryId`, `categoryCode`, `name`, `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`, `categoryCode`, `name`, `requiresDamageWaiver`, `isActive=false` |
+| 관리자 | 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<GiftListItemResponse>,
@@ -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<GiftStatusTimelineResponse>
 )
@@ -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 canceledAt: String?,
-    val undeliverableAt: LocalDateTime?,
+    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 trackingRegisteredAt: String,
-    val recipientAddressDeadlineAt: LocalDateTime
+    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<String>,
     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
 )
 ```
 

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 '내부 분류번호',
+    classification_number VARCHAR(3) NOT NULL COMMENT '신청번호에 사용하는 3자리 분류번호',
-    name VARCHAR(50) NOT NULL COMMENT '카테고리 표시명',
+    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='선물 신청번호 날짜별 채번';