# 쇼핑몰 필수 구현 기능 — 회원가입·로그인·마이페이지 포함

쇼핑몰 개발 요청은 아래 기능을 기본 범위로 구현한다. 로그인·회원가입·마이페이지를 선택 기능으로 내려서 완료 처리하지 않는다.
`generate_commerce_code`의 `completion.required_features`가 순서·공개 API 지원 여부·생성 상태·부족한 API task를 제공한다.

| 순서 | 기능 ID | 필수 기능 | 현재 공개 v1 계약 / 판정 |
|---|---|---|---|
| 1 | store-catalog | 상점·정책·상품 탐색 | GET store, products. 실제 상점 설정을 사용 |
| 2 | product-detail | 상세·옵션·재고·본문 | GET products/:id, 서버 가용성·상세 블록 계약 |
| 3 | cart-buy-now | 장바구니·독립 바로 구매 | 가격 없이 ID·옵션·수량 보관, 서버 견적 |
| 4 | login-session | 로그인·복원·로그아웃 | POST users/login, GET/DELETE users/session |
| 5 | signup | 약관·가입·인증/승인 대기 | GET users/signup-policy → POST users/signup, GET users/authenticate/:id, POST users/authenticate/:id/resend |
| 6 | account-home | 마이페이지 본인 정보 | GET users/session의 마스킹된 이름·이메일·전화번호 |
| 7 | profile-update | 본인 정보 조회·수정 | GET users/me, PATCH users/me (수정 가능 필드 + profile_version) |
| 8 | password-change | 현재 비밀번호 확인 후 변경 | PUT users/me/password — 성공 시 전 기기 세션 폐기 |
| 9 | password-recovery | 비밀번호 찾기·재설정 | POST users/password-recovery/requests → verifications → PUT users/password-recovery/password |
| 10 | my-orders | 본인 주문 목록·결과 상세 | 회원(JWT 또는 user_id)을 지정한 GET orders, GET orders/:order_number/result |
| 11 | address-book | 배송지 CRUD·기본 지정 | GET/POST users/address, PUT/DELETE users/address/:address_id |
| 12 | withdrawal | 탈퇴 조건·본인 확인·탈퇴 | GET users/me/withdrawal, POST users/me/withdrawal |
| 13 | quote-checkout | 견적·멱등 준비·호스팅 이동(배송지는 주문서) | POST cart/order-preview → quote_token → POST orders/prepare |
| 14 | buyer-result | 구매자 결과·장바구니 정리 | GET orders/:order_number/result, 회원(JWT 또는 user_id) 또는 비회원 결과 토큰 |

위 경로는 `/v1/` 기준이다. 5·7·8·9·12는 2026-09-21 commerce-api에 구현된 계정 API다.
**아직 배포되지 않은 환경에서는 404가, api_scopes 동기화 전에는 403(API_SCOPE_INVALID, -47)이 난다.** 기능이 없다는 뜻이 아니므로
생성 코드를 관리용 경로로 되돌리지 말고 대상 환경의 배포 상태와 스코프 등록을 확인한다.

## 회원 지정 규칙

- 회원 지정: Bootpay-User-JWT 또는 user_id(24자리 회원 ID 또는 가맹점 외부 ID ex_uid) 또는 login_id 중 하나 — JWT 우선, 함께 보낸 값이 다른 회원이면 403 USER_NOT_MATCH(2302), user_id·login_id 는 secret_key(Basic) 서버 호출에서만 받는다. 값은 쇼핑몰 서버가 자기 로그인 세션에서 꺼내고 브라우저가 보낸 값을 그대로 쓰지 않는다.
- user_id·login_id 모드는 commerce 2026-09-28 계약이며 운영 배포 후 적용 — 그 전 운영에서는 JWT 모드만 동작하므로 기본값으로 켜지 않는다.
- 예외: users/session 은 JWT 전용(user_id 계열 400), password-recovery 는 user_id 계열 거절.

생성 코드·원격 도구는 commerce 운영 배포와 api_scopes 운영 동기화가 확인되기 전까지 `user_id` 모드를 기본값으로 켜지 않는다.

모드별 위치·오류 코드(401 420/419, 403 2302, 404 2300, 400 131, 400 -48)는 설치 스킬의 `contracts.md` §3 을 따른다.

## 기능별 구현 규칙

### 로그인·회원가입

- `POST users/login`은 `{login_id,password}` → `{token}`(운영 배포 후 `{token,user_id}`). token 은 쇼핑몰 서버 세션에만 둔다. `user_id`는 회원 식별자일 뿐 권한 근거가 아니다 — 브라우저가 돌려보낸 값을 믿지 않는다. ID/이메일 모드는 GET store의 회원 설정을 따른다.
  본문의 `login_id`는 자격증명이지 회원 지정이 아니다.
- 확인 중·인증 실패·인증됨을 구분하고 로그인/가입 왕복에서도 안전한 `returnTo`와 구매 선택을 유지한다. 세션 오류를 비회원 구매로 조용히 전환하지 않는다.
- 가입 화면은 먼저 `GET users/signup-policy`를 읽는다. 응답은 `{signup_enabled, membership_type, supported_member_types, fields, terms, policy_version}`이다.
  `terms[]`의 `term_id`가 유일한 정답이다. GET store의 약관 HTML에는 `term_id`가 없으므로 임의 ID·빈 동의·관리자 우회로 가입하지 않는다.
  `use_url=true`인 약관은 `content`가 비어 있고 `url`로만 본문을 연다 — 둘 다 읽어 빈 약관을 그리지 않는다.
- 구매자 가입은 `POST users/signup`의 `{login_id,password,email,name,phone,term_ids,policy_version,address}`다.
  관리/외부 동기화 `users/join`(login_pw)을 가입 폼에 연결하지 않는다.
- `fields.address.required`가 참인 상점은 `address:{zipcode,address,address_detail}`를 함께 보낸다. 이 세 키 외에는 받지 않으며
  `user_group_id`·`role` 같은 키를 address 안에 넣으면 거절된다. 주소를 빼고 가입시키거나 상점 정책을 바꾸지 않는다.
- `policy_version`은 화면이 본 정책의 지문이다. 그 사이 약관이 바뀌면 409(10800)가 오므로 정책을 다시 읽어 동의를 새로 받는다. 조용히 재제출하지 않는다.
- `finish`, `standby`, `pending_approval`을 구분한다. `requires_login:true`이므로 가입 응답을 로그인 토큰으로 해석하지 않는다.
- 가입 거절은 구매자가 고칠 입력 문제다 — 502(상점 오류)로 뭉개지 않는다. 중복 아이디(404 `USER_ID_EXIST`)·이메일(405 `USER_EMAIL_EXIST`)은 409로 사유를 보여 주고 입력과 약관 동의를 유지한다. 약관 변경(10800 `SIGNUP_POLICY_VERSION_CHANGED`·2400 `TERM_NOT_FOUND`)일 때만 정책을 다시 읽고 동의를 새로 받는다. 가입은 `POST users/signup` 한 번이며 비밀번호 변경(`PUT users/me/password`)과 무관하다.
- 이메일 인증 몰은 가입·인증 메일 재발송 때 상점 서버가 메일을 보낸다. 발송 실패(409 `USER_EMAIL_AUTHENTICATE_PROCESS_ERROR`)는 구매자 입력 문제가 아니므로 503으로 "인증 메일을 보내지 못했어요"를 알리고 입력을 유지한다. 이때 가입 대기 정보는 저장되지 않아 같은 입력으로 다시 시도할 수 있다. 계속되면 상점(메시지 발송 설정) 쪽 문제다.
- `standby`(이메일 인증 대기)면 응답의 `verification_context`가 재발송의 소유 증명이다. **브라우저로 내리지 않고 서버 세션에만 보관한다.**
  상태 조회는 `GET users/authenticate/:id`(context 선택), 재발송은 `POST users/authenticate/:id/resend`(context 필수)다.
  재발송에는 쿨다운이 있고 응답의 `resend_after`가 다음 가능 시각이다. 대기 레코드는 인증된 프로젝트 범위에서만 조회된다.

### 마이페이지·본인 정보

- 세션 응답(`users/session`)은 마스킹된 표시용이다. 편집 폼의 원본으로 쓰지 않는다. 수정 폼은 `GET users/me`의 평문 값을 쓴다.
- `PUT/DELETE users/:id`는 관리용이며 본인 정보 수정·탈퇴의 대체가 아니다. 본인 경로는 전부 `users/me` 아래에 있다.
- `GET/DELETE users/session`은 `Bootpay-User-JWT` 전용이다. `user_id` 계열 파라미터를 보내면 거절된다 — 권한 근거가 아니라 거절 사유다.
- `GET/PATCH users/me`는 JWT 또는 서버 세션의 `user_id`·`login_id`로 부른다(2026-09-28, 운영 배포 후 적용). `user_id`로 이 몰의 어느 회원이든 지정할 수 있으므로 로그인한 본인인지는 쇼핑몰 서버가 확인한다 — 관리용 `users/:id`로 대신하지 않는다.
  `PATCH`의 `user_id`·`login_id`는 수정 값이 아니라 회원 지정이다(로그인 아이디는 바꿀 수 없다).
- `PATCH users/me`는 **보낸 필드만** 반영한다(생략 = 보존). 수정 가능 값은 응답의 `editable_fields`(name·nickname·gender·birth)뿐이다.
  `email`·`phone`은 로그인·본인확인 수단이라 이 경로로 바꿀 수 없다. 서버가 파라미터 자체를 거절하므로 **입력 칸을 만들지 말고 읽기 전용으로 보여준다.**
- `profile_version`을 함께 보낸다. 다른 탭·기기가 먼저 저장했으면 409(10802)와 최신 버전이 오므로 덮어쓰지 말고 다시 읽어 수정한다.
- `birth`는 YYMMDD 6자리다. 하이픈 섞인 값을 조용히 고쳐 보내지 말고 입력 단계에서 막는다.

### 비밀번호 변경·찾기

- `PUT users/me/password`는 `{current_password,new_password,new_password_confirmation}`. 새 비밀번호는 8자 이상 72바이트 이하다. 회원은 JWT 또는 `user_id`(서버 세션 값, 운영 배포 후)로 지정한다.
- **성공하면 이 회원의 모든 세션이 끊긴다(요청한 기기 포함).** 응답 `requires_login:true`를 신호로 세션 쿠키를 지우고 로그인 화면으로 보낸다.
  지우지 않으면 화면은 로그인 상태로 보이는데 이후 모든 회원 API가 401이 된다. commerce 는 이 회원의 Bootpay JWT 만 무효화하므로 `user_id` 모드 쇼핑몰은 `requires_login:true`를 보고 자기 로그인 세션(쿠키)도 끊어야 한다.
- 비밀번호가 없는 계정(소셜 전용)은 409(10803)다. 오류로 끝내지 말고 비밀번호 찾기로 설정하도록 안내한다.
- 비밀번호 찾기는 로그아웃 상태라 회원 JWT가 없다. `requests`는 `{login_id,channel}`만 받는다. 회원은 `login_id` → `challenge_id` → `reset_token` 으로만 정해지며 세 단계(requests·verifications·password) 모두 `user_id` 계열 키를 받지 않는다 — 여기의 `login_id`는 본문 자격이지 회원 지정이 아니다.
  **수신처(이메일·전화)를 보내지 않는다** — 발송은 언제나 서버에 등록된 회원 연락처로만 간다. 받을 주소를 화면에서 입력받으면 계정 탈취 경로가 된다.
- `requests` 응답은 회원이 없어도·쿨다운이어도·발송이 실패해도 같은 모양이다. "가입되지 않은 아이디"처럼 계정 존재 여부를 드러내는 문구를 쓰지 않는다.
- `verifications`가 주는 `reset_token`은 1회용 비밀값이다. 브라우저로 내리지 않고 서버 세션에만 담는다. 코드 유효 시간은 3분, 시도 횟수 초과는 472다.

### 본인 주문

- 주문 목록은 BFF가 회원(JWT 또는 서버 세션의 `user_id`)을 필수로 보내고 구매자 ID를 브라우저에서 받지 않는다. `user_id`를 주면 그 회원 주문만 오고, 없는 회원은 전체 목록 대신 404다. `page/limit/search_date_from/search_date_to`를 검증한다. API 날짜 기본값은 오늘이므로 화면 기간(예: 최근 6개월)을 명시한다.
- `{list,count}` 원문은 영수증·고객 데이터가 섞이므로 주문번호·주문명·상태·금액·생성일만 추려 전달한다. 상세는 구매자 `orders/:number/result`의 최소 응답을 사용한다.
- 미로그인은 로그인 복귀, 타인 주문404, 정상0건, 통신 오류, 입금대기, 환불을 각각 처리한다. 조회 화면에서 취소·재주문이 자동 실행되면 안 된다.

### 배송지

- GET 응답은 `{list,count}`. 줄은 `address_id,address_uid,alias_name,name,phone,zipcode,address,address_detail,is_default`다.
- POST는 `{name,phone,zipcode,address,address_detail}`와 선택 `alias_name,address_uid,is_default`; PUT은 부분 수정. 소유자는 회원 지정(JWT 또는 서버 세션의 `user_id`, 운영 배포 후)으로 정하며 JWT 모드도 scope 가 필요하다. 로그인 아이디로 지정할 때는 `user_id`가 아니라 `login_id`를 쓴다. 브라우저가 보낸 회원 값은 쓰지 않는다.
- 첫 주소 기본 지정과 기본 주소 삭제 후 승격은 서버가 처리한다. 변경 후 다시 읽고 이전 주문의 주소 snapshot을 수정하지 않는다. 삭제는 해당 주소를 사용자가 선택해 확인한 경우에만 수행한다.

### 탈퇴

- 탈퇴 안내·탈퇴의 회원은 JWT 또는 `user_id`(서버 세션 값, 운영 배포 후)로 지정한다. `GET users/me/withdrawal`이 화면이 그릴 값을 모두 준다: `withdrawable`, `blockers[]`, `confirm_method`(password|phrase), `confirm_phrase`, `retention_options[]`, `rejoin_restriction`, `guide_message`.
- `withdrawable=false`면 실행 버튼을 만들지 않고 `blockers`를 사람이 읽는 문구로 보여준다. 차단 사유는 확정 시점에 서버가 다시 검사한다.
- `POST users/me/withdrawal`은 `{reason,reason_text,password|confirm_phrase,retention_type}`. 되돌릴 수 없으므로 확인 단계를 거친 뒤에만 부른다.
- 성공 응답은 `{withdrawn,requires_login,purge_scheduled_at}`뿐이다. 탈퇴 즉시 Bootpay JWT 가 무효화되므로 쿠키를 지우고 안내 화면으로 보낸다. `user_id` 모드 쇼핑몰은 `requires_login:true`를 보고 자기 로그인 세션도 끊는다.
  **두 번째 호출은 401이다**(`user_id` 모드는 탈퇴 회원이라 404 `USER_NOT_FOUND`) — 중복 탈퇴가 아니라 첫 탈퇴가 세션을 끊었기 때문이다. 이 오류를 "탈퇴 실패"로 표시하지 않는다.
- 탈퇴 미사용 몰은 442(WITHDRAWAL_NOT_ENABLED)다. 관리용 `DELETE users/:id`로 대신하지 않는다.

## 완료 판정

- `template_present`: 파일이 제공됐다는 뜻이다. 동작·운영 검증 완료 뜻이 아니다.
- `implementation_required`: 현재 프레임워크/단계에 구현이 없다. 프레임워크를 임의 변경하지 말고 명시된 v1 계약으로 구현한다.
- `api_blocked`: 필수 공개 API가 없거나 계약 결함이 있다. 임의 endpoint를 만들거나 선택 기능으로 바꾸지 않고 관련 task를 연결한다.
- **모든 필수 기능의 API·구현·검증이 갖춰져야 `complete`다.** 구매 흐름 테스트가 통과해도 회원 기능이 비어 있으면 전체 쇼핑몰은 `incomplete`다.
- 가입/로그인/로그아웃/만료/본인 주문 격리/배송지 CRUD/프로필 동시 수정 409/비밀번호 변경 후 전 기기 로그아웃/탈퇴 차단 사유를 독립 시나리오로 검증한다.
  문서·task 구조 검증은 제품 기능 구현 완료와 구분한다.
- 찜·리뷰 작성·포인트·쿠폰·구독·기업/부서 기능은 명시적으로 확장한다. 구매자용 API와 권한이 입증되기 전 관리 API로 대신하지 않는다.
- 공지사항·FAQ·1:1 문의·상품문의·상품평·찜·쿠폰함/적립금은 필수 14개가 아니라 선택 기능이다. 요청받으면 `generate_commerce_code(features=[…])`로 얹거나,
  같은 구조(공개 v1 을 쇼핑몰 서버에서 호출, 구매자 기능은 회원을 함께 보냄)로 구현한다. 선택 기능이 빠졌다고 필수 기능 판정이 바뀌지 않는다.

## 소스와 후속 수정

2026-09-17 정적 검수 기준: commerce-api `config/routes.rb`, `app/controllers/v1/users/{login,sessions,signup,address,authenticate}_controller.rb`, `app/services/v1/users/{signup,address_book}_service.rb`, `app/controllers/v1/orders_controller.rb`, `app/services/v1/order_result_service.rb`.
2026-09-21 계정 API 반영분: `app/controllers/v1/users/{signup_policy,me,password,password_recovery,withdrawal}_controller.rb`, `app/services/v1/users/{signup_policy,self_profile,password_change,password_recovery,signup_verification}_service.rb`, `config/routes.rb`의 `namespace :users` 블록.
2026-09-28 회원 지정 반영분(운영 배포 전): commerce-api `docs/api/v1/common/{authentication,user-jwt}.md`, `users.md`·`orders.md`·`my-page.md` 변경 이력.
invoice 참고: `app/components/mall/pages/login.vue`, `app/components/mall/join/individual/create.vue`, `app/components/mall/my-page/MyPageLayout.vue`, `app/stores/commerce/my-page/profile.ts`.

API가 바뀌면 실제 입출력·권한·오류를 다시 검수하고 해당 기능의 `REQUIRED_STOREFRONT_FEATURES` 상태, 생성기, fixture, 스킬을 함께 갱신한다. task 상태만 보고 지원됨으로 바꾸지 않는다.
