klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
klaus
2026-09-30 17:37:16 +09:00
parent 38941d9fe9
commit dda5de4d61
2 changed files with 40 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/20260929_크리에이터_선물하기/client-api-summary.md
+27 -19
View File
@@ -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<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 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<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
+13 -6
View File
@@ -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='선물 신청번호 날짜별 채번';