# 선물 관리자 페이지 구현 프롬프트

이 문서는 관리자 페이지의 선물 관련 3개 화면을 프론트엔드 구현 에이전트에게 전달하기 위한 프롬프트 모음이다.

공통 전제:

- 관리자 메뉴에는 parent 메뉴 `선물함 관리` 아래에 다음 3개 하위 메뉴가 있다.
  - `선물함 리스트` → `/gift/list`
  - `선물 카테고리` → `/gift/category`
  - `선물 사이즈` → `/gift/size`
- 모든 API 응답은 기존 공통 envelope를 사용한다. 화면에서는 `response.data`를 실제 payload로 사용한다.
- 인증/권한 처리는 기존 관리자 페이지의 API 클라이언트, 토큰 저장 방식, 에러 처리 방식을 따른다.
- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 테이블, 필터, 버튼, 모달, 폼, 토스트, 확인창 패턴을 재사용한다.
- 화면 문구는 한국어로 작성한다.
- API 실패 시 기존 관리자 페이지의 공통 에러 표시 방식을 따른다.

---

## 1. 선물함 리스트 페이지 프롬프트

```text
관리자 선물함 리스트 페이지를 구현해줘.

목표:
- 관리자 메뉴 `선물함 관리 > 선물함 리스트`에서 전체 선물 신청 목록을 조회한다.
- 상태, 신청번호, 닉네임으로 필터링할 수 있다.
- 목록 row에서 선물 상세를 확인하고, 현재 상태에서 가능한 운영 액션을 실행할 수 있다.
- 기존 관리자 페이지의 테이블/필터/페이지네이션/모달/확인창 스타일을 그대로 따른다.

라우트:
- `/gift/list`

필수 화면 구성:
- 상단 제목: `선물함 리스트`
- 필터 영역:
  - 상태 select: 전체, 접수 완료, 발송 확인, 사서함 도착, 검수 완료, 전달 완료, 전달 불가, 신청 취소
  - 신청번호 검색 input: `applicationNo` 부분 검색
  - 닉네임 검색 input: 발송인 또는 수취인 닉네임 부분 검색
  - 검색 버튼, 초기화 버튼
- 목록 테이블 컬럼:
  - 신청번호 `applicationNo`
  - 발송인 닉네임 `senderNickname`
  - 수취인 닉네임 `recipientNickname`
  - 사이즈 `sizeName` / `sizeCode`
  - 카테고리 `categoryName`
  - 분류번호 `classificationNumber`
  - 택배사 `courierCompanyName`
  - 운송장번호 `trackingNumber`
  - 상태 `statusName`
  - 액션 버튼
- 페이지네이션:
  - 서버의 `page`, `size`, `totalCount`, `hasNext` 기준으로 기존 관리자 페이지 패턴에 맞춘다.

목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gifts`
- Query:
  - `status?: GiftStatus`
  - `applicationNo?: string`
  - `nickname?: string`
  - `page?: number` 기본 `0`
  - `size?: number` 기본 `20`
- 필터 조합:
  - 선택 필터는 AND 조건이다.
  - `nickname`은 발송인/수취인 닉네임 중 하나에 포함되면 매칭된다.

목록 조회 response `data`:
```ts
type AdminGiftListResponse = {
  totalCount: number;
  items: AdminGiftListItemResponse[];
  page: number;
  size: number;
  hasNext: boolean;
};

type AdminGiftListItemResponse = {
  applicationNo: string;
  senderNickname: string;
  recipientNickname: string;
  sizeCode: string;
  sizeName: string;
  categoryName: string;
  classificationNumber: string;
  courierCompanyName: string | null;
  trackingNumber: string | null;
  status: GiftStatus;
  statusName: string;
  availableActions: AdminGiftAction[];
};
```

상태 enum:
```ts
type GiftStatus =
  | "RECEIVED"
  | "TRACKING_REGISTERED"
  | "ARRIVED_AT_MAILBOX"
  | "INSPECTION_COMPLETED"
  | "DELIVERED"
  | "UNDELIVERABLE"
  | "CANCELED";
```

상태 표시명:
- `RECEIVED`: `접수 완료`
- `TRACKING_REGISTERED`: `발송 확인`
- `ARRIVED_AT_MAILBOX`: `사서함 도착`
- `INSPECTION_COMPLETED`: `검수 완료`
- `DELIVERED`: `전달 완료`
- `UNDELIVERABLE`: `전달 불가`
- `CANCELED`: `신청 취소`

상세 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gifts/{applicationNo}`
- 용도:
  - 목록 row 클릭 또는 `상세` 버튼 클릭 시 상세 모달/상세 패널을 연다.

상세 response `data`:
```ts
type AdminGiftDetailResponse = {
  applicationNo: string;
  senderInfo: AdminGiftMemberInfoResponse;
  recipientInfo: AdminGiftMemberInfoResponse;
  productInfo: AdminGiftProductInfoResponse;
  inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse;
  status: GiftStatus;
  statusName: string;
  availableActions: AdminGiftAction[];
};

type AdminGiftMemberInfoResponse = {
  nickname: string;
  name: string;
  phoneNumber: string;
  address: string;
};

type AdminGiftProductInfoResponse = {
  sizeCode: string;
  sizeName: string;
  categoryName: string;
  classificationNumber: string;
};

type AdminGiftInboundDeliveryInfoResponse = {
  courierCompanyName: string | null;
  trackingNumber: string | null;
};
```

상세 표시 요구사항:
- 발송인 정보: 닉네임, 이름, 전화번호, 주소
- 수취인 정보: 닉네임, 이름, 전화번호, 주소
- 상품 정보: 사이즈, 카테고리, 분류번호
- 입고 배송 정보: 택배사, 운송장번호
- 현재 상태와 가능한 액션
- 수취인이 배송지를 아직 입력하지 않은 경우 `recipientInfo.nickname`은 표시하고 `name`, `phoneNumber`, `address`는 빈 문자열로 온다. 화면에서는 `미입력`으로 표시해도 된다.

운영 액션 enum:
```ts
type AdminGiftAction =
  | "ARRIVE_MAILBOX"
  | "COMPLETE_INSPECTION"
  | "COMPLETE_DELIVERY"
  | "MARK_UNDELIVERABLE";
```

상태별 `availableActions`:
- `RECEIVED`: 없음
- `TRACKING_REGISTERED`: `ARRIVE_MAILBOX`, `MARK_UNDELIVERABLE`
- `ARRIVED_AT_MAILBOX`: `COMPLETE_INSPECTION`, `MARK_UNDELIVERABLE`
- `INSPECTION_COMPLETED`: `COMPLETE_DELIVERY`, `MARK_UNDELIVERABLE`
- `DELIVERED`: 없음
- `UNDELIVERABLE`: 없음
- `CANCELED`: 없음

액션 버튼 문구:
- `ARRIVE_MAILBOX`: `사서함 도착 처리`
- `COMPLETE_INSPECTION`: `검수 완료 처리`
- `COMPLETE_DELIVERY`: `전달 완료 처리`
- `MARK_UNDELIVERABLE`: `전달 불가 처리`

액션 API:
- 사서함 도착 처리
  - Method: `POST`
  - URL: `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox`
  - Body: 없음
- 검수 완료 처리
  - Method: `POST`
  - URL: `/api/v2/admin/gifts/{applicationNo}/complete-inspection`
  - Body: 없음
- 전달 완료 처리
  - Method: `POST`
  - URL: `/api/v2/admin/gifts/{applicationNo}/complete-delivery`
  - Body: 없음
- 전달 불가 처리
  - Method: `POST`
  - URL: `/api/v2/admin/gifts/{applicationNo}/mark-undeliverable`
  - Body:
```ts
type AdminGiftMarkUndeliverableRequest = {
  reason: string;
};
```

액션 response `data`:
```ts
type AdminGiftOperationStatusResponse = {
  applicationNo: string;
  status: GiftStatus;
  statusName: string;
  occurredAt: string; // UTC ISO string, e.g. 2026-09-30T12:00:00Z
};
```

액션 UX:
- 모든 상태 변경 액션은 확인창을 띄운다.
- `MARK_UNDELIVERABLE`은 사유 입력 모달을 띄운다.
- 전달 불가 사유는 공백만 입력할 수 없고 255자 이내로 제한한다.
- 액션 성공 후:
  - 상세 모달이 열려 있으면 상세를 다시 조회한다.
  - 목록도 현재 필터/페이지 기준으로 다시 조회한다.
  - 성공 토스트를 표시한다.
- 액션 실패 시 기존 관리자 페이지 에러 토스트/알림 패턴을 따른다.

빈 값 표시:
- `courierCompanyName`, `trackingNumber`가 null이면 `-`로 표시한다.
- 수취인 개인정보가 빈 문자열이면 `미입력`으로 표시한다.

테스트/검증:
- API 클라이언트 함수 단위 테스트 또는 페이지 테스트에서 query parameter가 올바르게 전달되는지 확인한다.
- `availableActions`에 따라 버튼 노출이 달라지는지 확인한다.
- 전달 불가 사유 빈 값 validation을 확인한다.
```

---

## 2. 선물 카테고리 CRUD 페이지 프롬프트

```text
관리자 선물 카테고리 CRUD 페이지를 구현해줘.

목표:
- 관리자 메뉴 `선물함 관리 > 선물 카테고리`에서 선물 카테고리를 조회, 등록, 수정, 비활성화한다.
- 기존 관리자 페이지의 CRUD 테이블, 등록/수정 모달, 삭제 확인창, 토스트 패턴을 그대로 따른다.

라우트:
- `/gift/category`

필수 화면 구성:
- 상단 제목: `선물 카테고리`
- 상단 우측 `카테고리 등록` 버튼
- 목록 테이블 컬럼:
  - 카테고리 ID `categoryId`
  - 분류번호 `classificationNumber`
  - 카테고리 코드 `categoryCode`
  - 카테고리명 `name`
  - 접수 코드 `receiptCode`
  - 대표 품목 `representativeItem`
  - 파손면책 동의 필요 여부 `requiresDamageWaiver`
  - 활성 여부 `isActive`
  - 관리 버튼: 수정, 비활성화
- 등록/수정 폼 필드:
  - `classificationNumber`
  - `categoryCode`
  - `name`
  - `receiptCode`
  - `representativeItem`
  - `requiresDamageWaiver`
  - `isActive`

목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-categories`
- Request: 없음
- Response `data`:
```ts
type AdminGiftCategoryResponse = {
  categoryId: number;
  classificationNumber: string;
  categoryCode: string;
  name: string;
  receiptCode: string;
  representativeItem: string;
  requiresDamageWaiver: boolean;
  isActive: boolean;
};
```

등록 API:
- Method: `POST`
- URL: `/api/v2/admin/gift-categories`
- Body:
```ts
type AdminGiftCategoryRequest = {
  classificationNumber: string;
  categoryCode: string;
  name: string;
  receiptCode: string;
  representativeItem: string;
  requiresDamageWaiver: boolean;
  isActive: boolean;
};
```
- Response `data`: `AdminGiftCategoryResponse`

수정 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-categories/{categoryId}`
- Body: `AdminGiftCategoryRequest`
- Response `data`: `AdminGiftCategoryResponse`

비활성화 API:
- Method: `DELETE`
- URL: `/api/v2/admin/gift-categories/{categoryId}`
- Body: 없음
- Response `data`: `AdminGiftCategoryResponse`
- 서버는 실제 삭제가 아니라 `isActive=false` 논리 삭제로 처리한다.

폼 validation:
- `classificationNumber`: 필수, 숫자 3자리. 예: `100`
- `categoryCode`: 필수, 50자 이하. 예: `DOLL`
- `name`: 필수, 50자 이하. 예: `인형`
- `receiptCode`: 필수, 영문 대문자 1~9자. 예: `A`
- `representativeItem`: 필수, 100자 이하. 예: `피규어`
- `requiresDamageWaiver`: boolean
- `isActive`: boolean

UX 요구사항:
- 등록 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 수정 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 비활성화 버튼은 확인창을 띄운 뒤 호출한다.
- 이미 비활성화된 row는 비활성화 버튼을 disabled 처리한다.
- boolean 값은 기존 관리자 페이지 표현에 맞춰 `예/아니오`, `활성/비활성` 또는 badge로 표시한다.
- `categoryCode`는 수정 폼에 표시하되 서버 쪽 엔티티는 코드 변경을 실제로 반영하지 않을 수 있으므로, 가능하면 수정 시 읽기 전용으로 두고 나머지 운영 필드만 수정하도록 UX를 구성한다.

테스트/검증:
- 목록 조회가 `GET /api/v2/admin/gift-categories`를 호출하는지 확인한다.
- 등록/수정 body가 `AdminGiftCategoryRequest` 형태와 일치하는지 확인한다.
- validation 실패 시 API를 호출하지 않고 폼 에러를 표시한다.
- 비활성화 성공 후 해당 row의 `isActive=false`가 반영되는지 확인한다.
```

---

## 3. 선물 사이즈 가격 CRUD 페이지 프롬프트

```text
관리자 선물 사이즈 가격 CRUD 페이지를 구현해줘.

목표:
- 관리자 메뉴 `선물함 관리 > 선물 사이즈`에서 선물 사이즈별 기본가/판매가/활성 여부를 조회하고 수정한다.
- 현재 API는 사이즈 가격의 목록 조회와 수정만 제공한다. 신규 생성과 물리 삭제 기능은 만들지 않는다.
- 기존 관리자 페이지의 테이블, 수정 모달, 저장 확인/토스트 패턴을 그대로 따른다.

라우트:
- `/gift/size`

필수 화면 구성:
- 상단 제목: `선물 사이즈`
- 목록 테이블 컬럼:
  - 사이즈 코드 `sizeCode`
  - 사이즈명 `name`
  - 기본가 `basePriceCan`
  - 판매가 `salePriceCan`
  - 활성 여부 `isActive`
  - 관리 버튼: 수정
- 수정 폼 필드:
  - `sizeCode`: 읽기 전용
  - `name`: 읽기 전용
  - `basePriceCan`: number input
  - `salePriceCan`: number input
  - `isActive`: checkbox/switch

목록 조회 API:
- Method: `GET`
- URL: `/api/v2/admin/gift-size-prices`
- Request: 없음
- Response `data`:
```ts
type AdminGiftSizePriceResponse = {
  sizeCode: GiftSize;
  name: string;
  basePriceCan: number;
  salePriceCan: number;
  isActive: boolean;
};
```

수정 API:
- Method: `PUT`
- URL: `/api/v2/admin/gift-size-prices/{sizeCode}`
- Body:
```ts
type AdminGiftSizePriceRequest = {
  basePriceCan: number;
  salePriceCan: number;
  isActive: boolean;
};
```
- Response `data`: `AdminGiftSizePriceResponse`

사이즈 enum:
```ts
type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
```

서버 validation:
- `salePriceCan`은 0보다 커야 한다.
- `salePriceCan`은 `basePriceCan`보다 클 수 없다.

프론트 validation:
- `basePriceCan`: 필수, 1 이상 정수
- `salePriceCan`: 필수, 1 이상 정수
- `salePriceCan <= basePriceCan`
- validation 실패 시 API 호출을 막고 필드 에러를 표시한다.

UX 요구사항:
- 가격은 숫자 입력이지만 테이블 표시에서는 기존 관리자 페이지의 숫자 포맷을 따른다.
- 수정 버튼 클릭 시 현재 row 값을 폼 초기값으로 넣는다.
- 저장 전 확인창은 기존 관리자 페이지 패턴이 있으면 따른다.
- 저장 성공 후 목록을 다시 조회하고 모달을 닫는다.
- 신규 생성/삭제 버튼은 만들지 않는다.

테스트/검증:
- 목록 조회가 `GET /api/v2/admin/gift-size-prices`를 호출하는지 확인한다.
- 수정 저장 시 `PUT /api/v2/admin/gift-size-prices/{sizeCode}`와 request body가 정확한지 확인한다.
- `salePriceCan > basePriceCan`일 때 API를 호출하지 않고 validation 메시지를 표시하는지 확인한다.
- 저장 성공 후 목록 refresh가 일어나는지 확인한다.
```

---

## 구현 시 참고할 공통 타입

```ts
type ApiResponse<T> = {
  success: boolean;
  data: T;
  message?: string;
};

type GiftStatus =
  | "RECEIVED"
  | "TRACKING_REGISTERED"
  | "ARRIVED_AT_MAILBOX"
  | "INSPECTION_COMPLETED"
  | "DELIVERED"
  | "UNDELIVERABLE"
  | "CANCELED";

type AdminGiftAction =
  | "ARRIVE_MAILBOX"
  | "COMPLETE_INSPECTION"
  | "COMPLETE_DELIVERY"
  | "MARK_UNDELIVERABLE";

type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
```

## 구현 순서 추천

1. API client 함수와 TypeScript 타입을 먼저 추가한다.
2. `/gift/list` 선물함 리스트와 상세/상태변경 모달을 구현한다.
3. `/gift/category` 카테고리 CRUD를 구현한다.
4. `/gift/size` 사이즈 가격 수정 화면을 구현한다.
5. 기존 관리자 메뉴의 `선물함 관리` 하위 route와 연결되는지 확인한다.
6. 각 페이지별 loading/empty/error/success 상태를 확인한다.