docs(gift): 선물 상세 구현 프롬프트를 추가한다

2026-10-02 11:34:16 +09:00
parent 31406e7f0a
commit 978206438e
3 changed files with 548 additions and 1 deletions
@@ -0,0 +1,114 @@
+# 선물 받을 주소 관리자 페이지 구현 프롬프트
+
+이 문서는 관리자 페이지에서 전역 선물 받을 주소를 등록/수정하는 화면을 구현할 때 사용하는 프롬프트다.
+
+## 전제
+
+- 여기서 말하는 `선물 받을 주소`는 선물 상대방 주소가 아니다.
+- 관리자가 등록하는 전역 단일 주소다.
+- 팬이 보낸 선물 상세를 정상 진행 상태 중 전달 완료 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)에 조회할 때, 이 주소가 `mailbox`로 노출된다.
+- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 폼, 버튼, 토스트, 에러 표시 패턴을 재사용한다.
+
+## 구현 프롬프트
+
+```text
+관리자 선물 받을 주소 설정 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 받을 주소`에서 팬이 선물을 보낼 전역 단일 주소를 조회하고 저장한다.
+- 이 주소는 상대방 주소가 아니라 관리자가 등록하는 운영 주소다.
+- 팬의 선물 상세 API에서는 `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`일 때 이 주소가 `mailbox`로 노출된다.
+- 기존 관리자 페이지의 폼, 저장 버튼, 토스트, 에러 표시 패턴을 그대로 따른다.
+
+라우트:
+- `/gift/mailbox`
+
+메뉴:
+- parent: `선물함 관리`
+- label: `받을 주소`
+- path: `/gift/mailbox`
+
+필수 화면 구성:
+- 상단 제목: `받을 주소`
+- 설명 문구: `팬이 선물을 발송할 때 확인하는 받을 주소입니다.`
+- 입력 폼:
+  - 받을 사람 이름 `name`
+  - 연락처 `phoneNumber`
+  - 우편번호 `zipCode`
+  - 주소 `address`
+  - 상세주소 `addressDetail`
+- 저장 버튼: `저장`
+
+초기 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gift-mailbox`
+- 모든 API 응답은 기존 공통 envelope를 사용한다.
+- 화면에서는 `response.data`를 실제 payload로 사용한다.
+- response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+} | null;
+```
+- `data`가 null이면 아직 등록된 받을 주소가 없는 상태다.
+- null이면 빈 폼을 표시한다.
+
+저장 API:
+- Method: `PUT`
+- URL: `/api/v2/admin/gift-mailbox`
+- Request:
+```ts
+type AdminGiftMailboxRequest = {
+  name: string;
+  phoneNumber: string;
+  zipCode: string;
+  address: string;
+  addressDetail: string | null;
+};
+```
+- Response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+};
+```
+
+동작 규칙:
+- 받을 주소는 전역 단일 설정이다.
+- 등록과 수정은 같은 `PUT /api/v2/admin/gift-mailbox` API를 사용한다.
+- 최초 저장이면 생성처럼 동작한다.
+- 이미 저장된 값이 있으면 기존 주소를 수정한다.
+- 별도 ID, 목록, 삭제 기능은 만들지 않는다.
+
+폼 validation:
+- `name`, `phoneNumber`, `zipCode`, `address`는 필수다.
+- 필수값은 공백만 입력할 수 없다.
+- `addressDetail`은 선택이다.
+- validation 실패 시 API를 호출하지 않고 기존 관리자 페이지의 필드 에러 표시 방식을 따른다.
+
+저장 성공 UX:
+- 성공 토스트를 표시한다.
+- 저장 API response 기준으로 화면 값을 갱신한다.
+- response의 `address`는 서버가 조립한 `(우편번호) 주소, 상세주소` 형식이다.
+- 입력 필드는 사용자가 입력한 `zipCode`, `address`, `addressDetail` 값을 유지해도 된다.
+
+빈 상태 UX:
+- 조회 결과 `data=null`이면 빈 폼을 보여준다.
+- 필요하면 안내 문구 `등록된 받을 주소가 없습니다. 주소를 입력하고 저장해주세요.`를 표시한다.
+
+에러 처리:
+- API 실패 시 기존 관리자 페이지의 공통 에러 토스트/알림 패턴을 따른다.
+- 인증/권한 처리는 기존 관리자 API client와 토큰 처리 방식을 따른다.
+
+테스트/검증:
+- `/gift/mailbox` route가 선물함 관리 메뉴에서 접근되는지 확인한다.
+- 초기 조회 시 `GET /api/v2/admin/gift-mailbox`를 호출하는지 확인한다.
+- 조회 결과가 null이면 빈 폼을 표시하는지 확인한다.
+- 저장 시 `PUT /api/v2/admin/gift-mailbox`와 request body가 정확한지 확인한다.
+- 필수값 공백 validation 시 API를 호출하지 않는지 확인한다.
+- 저장 성공 후 성공 토스트와 화면 갱신이 일어나는지 확인한다.
+```