HeuJung
b5c0ec1178
관리자 상품목록을 한 페이지 여는 것만으로 그 페이지 모든 상품의 옵션이 응답에 실렸다. 같은 패턴을 저장소 전역에서 찾아 14개 목록 엔드포인트를 함께 정리했다. 근본 원인은 둘이다. Resource 가 whenLoaded 로 방어하는데 Repository 가 목록 쿼리에서 관계를 무조건 로드해 가드가 항상 참이 되는 가짜 가드, 그리고 toListArray 경량 표현을 정의해 두고도 컬렉션이 toArray 를 부르는 목록/상세 미분리다. 둘 다 응답만 보면 정상이라 오류도 경고도 없이 페이로드만 불어난다. 목록은 화면이 실제로 그리는 것만 싣는다. 개수·합계는 PHP 컬렉션 연산이 아니라 DB 집계로, 대표 1건이 필요한 곳은 관계 자체를 oldestOfMany 로 좁힌다. eager load 의 limit(1) 은 부모별이 아니라 배치 쿼리 전체에 걸려 첫 행만 값을 갖게 되므로 쓸 수 없다. 뺀 값에는 대체 경로를 먼저 만들었다. 상품 옵션은 행을 펼칠 때 배치로 불러오고(상품 수와 무관하게 쿼리 상수), 종전 동작이 필요한 호출자를 위해 ?with_options=1 등 opt-in 을 남겼다. 배송정책 국가설정과 리뷰 첨부 이미지는 소비처를 실측한 결과 화면이 실제로 그리고 있어 제거하지 않았다 — 그 소비 사실을 회귀 테스트로 고정했다. 재발 방지로 정적 검사 룰 4종과 규정 문서 항목을 함께 넣었다.
8.4 KiB
Wishlist API 레퍼런스
소유: module
sirsoft-ecommerce· 생성:php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Wishlist 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
GET /api/modules/sirsoft-ecommerce/wishlist
- 라우트명:
api.modules.sirsoft-ecommerce.wishlist.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\WishlistController@index - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
요청 예시
GET /api/modules/sirsoft-ecommerce/wishlist?page=1&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드 + data.pagination.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 2 |
기본 키 (내부 식별자) |
| product_id | integer | 1732 |
product 식별자 (연관 리소스 참조) |
| created_at | string | 2026-07-31T12:45:03.000000Z |
생성 일시 |
| product | object | {"id":1732,"name":{"ko":"면 손수건 3매입 #1","en":"Cotton Handk… |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "찜 목록을 불러왔습니다.",
"data": {
"data": [
{
"id": 2,
"product_id": 1732,
"created_at": "2026-07-31T12:45:03.000000Z",
"product": {
"id": 1732,
"name": {
"ko": "면 손수건 3매입 #1",
"en": "Cotton Handkerchief 3pcs #1"
},
"name_localized": "면 손수건 3매입 #1",
"product_code": "CJTFHBL8SLRQ8ILM",
"sku": "HK-0001",
"...": "(32개 키 생략, 총 37개)"
}
},
{
"id": 1,
"product_id": 1733,
"created_at": "2026-07-31T12:44:43.000000Z",
"product": {
"id": 1733,
"name": {
"ko": "기본 양말 5족 #2",
"en": "Basic Socks 5 Pairs #2"
},
"name_localized": "기본 양말 5족 #2",
"product_code": "S0SO3A6SJFYLAKSF",
"sku": "SK-0002",
"...": "(32개 키 생략, 총 37개)"
}
},
"... (총 25건 중 2건 표시)"
],
"pagination": {
"current_page": 1,
"last_page": 2,
"per_page": 25,
"total": 45,
"from": 1,
"...": "(2개 키 생략, 총 7개)"
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 422 | Unprocessable Entity | page < 1, per_page 가 1~100 범위를 벗어나거나 정수가 아닌 경우 |
요청 파라미터
| 이름 | 타입 | 필수 | 기본값 | 용도 |
|---|---|---|---|---|
page |
integer | - | 1 | 페이지 번호 (최소 1) |
per_page |
integer | - | 20 | 페이지당 건수 (1~100). 범위를 벗어나면 422 |
설명 로그인한 회원의 찜(위시리스트) 목록을 페이지네이션으로 조회합니다. auth:sanctum 인증이 필요하며, WishlistController@index가 ProductWishlistService::getByUser()로 본인 찜 목록만 가져와 WishlistCollection으로 반환합니다. 페이지네이션 파라미터는 WishlistListRequest 가 검증하며 per_page 는 기본 20건, 허용 범위 1~100건입니다(범위를 벗어나면 422). 소프트 삭제된 상품의 찜 행은 목록에서 제외되므로 total 은 찜 테이블의 행 수보다 작을 수 있습니다. 마이페이지의 찜 목록 화면에서 사용합니다.
POST /api/modules/sirsoft-ecommerce/wishlist/toggle
- 라우트명:
api.modules.sirsoft-ecommerce.wishlist.toggle - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\WishlistController@toggle - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| product_id | body | integer | 예 | — | product 식별자 |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
sirsoft-ecommerce.wishlist.toggle_validation_rules).
요청 예시
POST /api/modules/sirsoft-ecommerce/wishlist/toggle HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"product_id": 1
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 특정 상품(product_id)의 찜 상태를 토글합니다. auth:sanctum 인증이 필요하며, WishlistController@toggle이 ProductWishlistService::toggle()을 호출해 이미 찜한 상품이면 제거하고 아니면 추가한 뒤 added 불리언을 반환합니다. 상품 상세/목록의 찜 하트 버튼이 이 하나의 엔드포인트로 추가·제거를 모두 처리합니다. 응답의 added 값으로 현재 찜 여부를 즉시 갱신할 수 있습니다.
DELETE /api/modules/sirsoft-ecommerce/wishlist/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.wishlist.destroy - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\WishlistController@destroy - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
DELETE /api/modules/sirsoft-ecommerce/wishlist/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 찜 목록에서 특정 찜 항목(id)을 삭제합니다. auth:sanctum 인증이 필요하며, WishlistController@destroy가 ProductWishlistService::destroy()로 본인 소유 찜만 삭제합니다. 상품 ID가 아니라 찜 레코드 ID로 삭제하며, 해당 항목이 본인 것이 아니거나 존재하지 않으면 404를 반환합니다. 상품 상세의 하트 토글과 달리 마이페이지 찜 목록에서 특정 항목을 명시적으로 제거할 때 사용합니다.