Files
Gnuboard7/modules/_bundled/sirsoft-ecommerce/docs/api/inquiries.md
T
HeuJung b5c0ec1178 fix(core,ecommerce,board,page,admin_basic,basic): 목록 응답의 하위 컬렉션 전량 직렬화 해소
관리자 상품목록을 한 페이지 여는 것만으로 그 페이지 모든 상품의 옵션이 응답에 실렸다.
같은 패턴을 저장소 전역에서 찾아 14개 목록 엔드포인트를 함께 정리했다.

근본 원인은 둘이다. Resource 가 whenLoaded 로 방어하는데 Repository 가 목록 쿼리에서
관계를 무조건 로드해 가드가 항상 참이 되는 가짜 가드, 그리고 toListArray 경량 표현을
정의해 두고도 컬렉션이 toArray 를 부르는 목록/상세 미분리다. 둘 다 응답만 보면
정상이라 오류도 경고도 없이 페이로드만 불어난다.

목록은 화면이 실제로 그리는 것만 싣는다. 개수·합계는 PHP 컬렉션 연산이 아니라 DB
집계로, 대표 1건이 필요한 곳은 관계 자체를 oldestOfMany 로 좁힌다. eager load 의
limit(1) 은 부모별이 아니라 배치 쿼리 전체에 걸려 첫 행만 값을 갖게 되므로 쓸 수 없다.

뺀 값에는 대체 경로를 먼저 만들었다. 상품 옵션은 행을 펼칠 때 배치로 불러오고(상품 수와
무관하게 쿼리 상수), 종전 동작이 필요한 호출자를 위해 ?with_options=1 등 opt-in 을 남겼다.
배송정책 국가설정과 리뷰 첨부 이미지는 소비처를 실측한 결과 화면이 실제로 그리고 있어
제거하지 않았다 — 그 소비 사실을 회귀 테스트로 고정했다.

재발 방지로 정적 검사 룰 4종과 규정 문서 항목을 함께 넣었다.
2026-08-05 21:20:05 +09:00

25 KiB

Inquiries API 레퍼런스

소유: module sirsoft-ecommerce · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.


TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Inquiries 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

DELETE /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}

  • 라우트명: api.modules.sirsoft-ecommerce.admin.inquiries.destroy
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ProductInquiryController@destroy
  • 인증/권한: auth:sanctum + permission:sirsoft-ecommerce.inquiries.delete

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자

요청 예시

DELETE /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-ecommerce.inquiries.delete)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 관리자가 상품 1:1 문의 1건을 삭제합니다. sirsoft-ecommerce.inquiries.delete 권한이 필요하며, ProductInquiryService::deleteInquiry() 가 해당 문의를 제거하고 {deleted: true} 를 반환합니다. 문의가 존재하지 않는 등 삭제 불가 상황에서는 서비스가 RuntimeException 을 던져 422 로 응답합니다. 관리자 문의 관리 화면에서 부적절하거나 중복된 문의를 정리할 때 사용합니다.

DELETE /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.admin.inquiries.reply.destroy
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ProductInquiryController@destroyReply
  • 인증/권한: auth:sanctum + permission:sirsoft-ecommerce.inquiries.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자

요청 예시

DELETE /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-ecommerce.inquiries.update)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 관리자가 문의에 등록된 답변을 삭제합니다. sirsoft-ecommerce.inquiries.update 권한이 필요하며, ProductInquiryService::deleteReply() 가 답변을 제거하고 문의를 미답변 상태로 되돌린 뒤 {deleted: true} 를 반환합니다. 문의 자체는 유지되며, 잘못 등록한 답변을 회수할 때 사용합니다.

POST /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.admin.inquiries.reply
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ProductInquiryController@reply
  • 인증/권한: auth:sanctum + permission:sirsoft-ecommerce.inquiries.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자
content body string 예 min 1, max 5000 본문 내용

요청 예시

POST /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-ecommerce.inquiries.update)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 관리자가 상품 문의에 답변을 등록합니다. sirsoft-ecommerce.inquiries.update 권한이 필요하며, ProductInquiryService::createReply() 가 content(1~5000자)로 답변을 저장하고 문의를 답변완료 상태로 전환한 뒤 {id, is_answered} 를 201 로 반환합니다. 이미 답변이 있는 등 등록 불가 상황에서는 RuntimeException 이 던져져 422 로 응답합니다. 관리자가 고객 문의에 응대할 때 사용합니다.

PUT /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.admin.inquiries.reply.update
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ProductInquiryController@updateReply
  • 인증/권한: auth:sanctum + permission:sirsoft-ecommerce.inquiries.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자
content body string 예 min 1, max 5000 본문 내용

요청 예시

PUT /api/modules/sirsoft-ecommerce/admin/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-ecommerce.inquiries.update)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 관리자가 문의에 이미 등록된 답변 내용을 수정합니다. sirsoft-ecommerce.inquiries.update 권한이 필요하며, ProductInquiryService::updateReply() 가 content(1~5000자)로 기존 답변을 갱신하고 {id} 를 반환합니다. 답변이 없는 문의 등 수정 불가 상황에서는 RuntimeException 이 던져져 422 로 응답합니다. 오탈자 정정 등 답변 내용을 고칠 때 사용합니다.

GET /api/modules/sirsoft-ecommerce/user/inquiries

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.index
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@index
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
page query integer 아니오 min 1 조회할 페이지 번호 (1부터 시작)
per_page query integer 아니오 min 1, max 100 페이지당 항목 수
search query string 아니오 max 100 검색어 (지정한 검색 대상 필드에서 부분 일치)
is_answered query boolean 아니오 — answered 여부

요청 예시

GET /api/modules/sirsoft-ecommerce/user/inquiries?page=1&per_page=1&search=%EC%98%88%EC%8B%9C%EA%B0%92&is_answered=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
items array [{"id":19,"product_id":1732,"product":{"id":1732,"product… 내 문의 항목 배열 (각 항목: id, product 요약, product_name, is_answered, 게시판 연동 시 title/category/content/is_secret/reply/attachments)
meta object {"current_page":1,"per_page":25,"total":39,"last_page":2,… 페이지네이션 메타 (current_page/per_page/total/last_page/from/to, 문의 게시판 연동 여부 inquiry_available, abilities 답변·삭제 권한, board_settings)

응답 예시

HTTP/1.1 200
{
    "success": true,
    "message": "문의 목록을 조회했습니다.",
    "data": {
        "items": [
            {
                "id": 19,
                "product_id": 1732,
                "product": {
                    "id": 1732,
                    "product_code": "CJTFHBL8SLRQ8ILM",
                    "name": "면 손수건 3매입 #1",
                    "thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/7df7761cdf16",
                    "url": "/shop/products/CJTFHBL8SLRQ8ILM"
                },
                "product_name": "면 손수건 3매입 #1",
                "is_answered": true,
                "...": "(9개 키 생략, 총 14개)"
            },
            {
                "id": 20,
                "product_id": 1732,
                "product": {
                    "id": 1732,
                    "product_code": "CJTFHBL8SLRQ8ILM",
                    "name": "면 손수건 3매입 #1",
                    "thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/7df7761cdf16",
                    "url": "/shop/products/CJTFHBL8SLRQ8ILM"
                },
                "product_name": "면 손수건 3매입 #1",
                "is_answered": true,
                "...": "(9개 키 생략, 총 14개)"
            },
            {
                "id": 21,
                "product_id": 1732,
                "product": {
                    "id": 1732,
                    "product_code": "CJTFHBL8SLRQ8ILM",
                    "name": "면 손수건 3매입 #1",
                    "thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/7df7761cdf16",
                    "url": "/shop/products/CJTFHBL8SLRQ8ILM"
                },
                "product_name": "면 손수건 3매입 #1",
                "is_answered": false,
                "...": "(9개 키 생략, 총 14개)"
            },
            {
                "id": 22,
                "product_id": 1732,
                "product": {
                    "id": 1732,
                    "product_code": "CJTFHBL8SLRQ8ILM",
                    "name": "면 손수건 3매입 #1",
                    "thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/7df7761cdf16",
                    "url": "/shop/products/CJTFHBL8SLRQ8ILM"
                },
                "product_name": "면 손수건 3매입 #1",
                "is_answered": true,
                "...": "(9개 키 생략, 총 14개)"
            },
            {
                "id": 23,
                "product_id": 1732,
                "product": {
                    "id": 1732,
                    "product_code": "CJTFHBL8SLRQ8ILM",
                    "name": "면 손수건 3매입 #1",
                    "thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/7df7761cdf16",
                    "url": "/shop/products/CJTFHBL8SLRQ8ILM"
                },
                "product_name": "면 손수건 3매입 #1",
                "is_answered": false,
                "...": "(9개 키 생략, 총 14개)"
            },
            "... (총 25건 중 5건 표시)"
        ],
        "meta": {
            "current_page": 1,
            "per_page": 25,
            "total": 39,
            "last_page": 2,
            "from": 1,
            "...": "(4개 키 생략, 총 9개)"
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

요청 파라미터

이름 타입 필수 기본값 용도
page integer - 1 페이지 번호 (최소 1)
per_page integer - 10 페이지당 건수 (1~100). 범위를 벗어나면 422
search string - - 검색어 — 상품명(product_name_snapshot 의 로케일별 값) 대상. 문의 제목·본문은 검색하지 않음
is_answered boolean - - 답변 여부 (0 답변대기 / 1 답변완료)

설명 로그인 회원이 마이페이지에서 자신이 작성한 상품 문의 목록을 조회합니다. auth:sanctum 인증만 요구하며, ProductInquiryService::getUserInquiries() 가 로그인 사용자(Auth::id())의 문의를 search(검색어)·is_answered(답변 여부) 필터와 per_page(기본 10, 허용 1~100)로 페이지네이션해 items(문의 배열)와 meta(페이지 정보)로 반환합니다. 마이페이지 문의 내역 화면을 채우는 데 사용합니다.

DELETE /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.destroy
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@destroy
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자

요청 예시

DELETE /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 로그인 회원이 자신이 작성한 문의를 삭제합니다. auth:sanctum 인증이 필요하며, 컨트롤러가 문의를 조회해 없으면 404, inquiry->user_id 가 로그인 사용자와 다르면 403 을 반환한 뒤 ProductInquiryService::deleteInquiry() 로 삭제하고 {deleted: true} 를 반환합니다. 마이페이지에서 본인 문의를 취소/삭제할 때 사용합니다.

PUT /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.update
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@update
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자
title body string 아니오 min 2, max 200 제목
category body string 아니오 — 문의 분류 (게시판 설정 기반 유형 슬러그, 연동 게시판 Post 로 저장)
content body string 예 min 10, max 10000 본문 내용
is_secret body boolean 아니오 — secret 여부

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (sirsoft-ecommerce.inquiry.update_validation_rules).

요청 예시

PUT /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "title": "예시 제목",
    "category": "예시값",
    "content": "예시 내용입니다.",
    "is_secret": true
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 로그인 회원이 자신이 작성한 문의 내용을 수정합니다. auth:sanctum 인증이 필요하며, 컨트롤러가 문의를 조회해 없으면 404, inquiry->user_id 가 로그인 사용자와 다르면 403 을 반환한 뒤 ProductInquiryService::updateInquiry() 로 제목·분류·본문·비밀글 여부를 갱신하고 {id} 를 반환합니다. content 는 필수이며, 마이페이지에서 아직 답변되지 않은 본인 문의를 고칠 때 사용합니다.

DELETE /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.reply.destroy
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@destroyReply
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자

요청 예시

DELETE /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 사용자 표면에서 문의 답변 권한을 가진 회원이 문의 답변을 삭제합니다. auth:sanctum 인증에 더해 컨트롤러가 PermissionHelper::check('sirsoft-ecommerce.inquiries.update') 로 답변 권한을 확인(없으면 403)한 뒤 ProductInquiryService::deleteReply() 로 답변을 제거하고 {deleted: true} 를 반환합니다. 답변 권한을 위임받은 사용자(예: 상담원 역할)가 사용자 화면에서 답변을 회수할 때 사용합니다.

POST /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.reply
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@reply
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자
content body string 예 min 1, max 5000 본문 내용

요청 예시

POST /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 사용자 표면에서 문의 답변 권한을 가진 회원이 문의에 답변을 등록합니다. auth:sanctum 인증에 더해 컨트롤러가 PermissionHelper::check('sirsoft-ecommerce.inquiries.update') 로 답변 권한을 확인(없으면 403)한 뒤 ProductInquiryService::createReply() 가 content(1~5000자)로 답변을 저장하고 문의를 답변완료로 전환해 {id, is_answered} 를 201 로 반환합니다. 관리자 화면이 아닌 사용자 프론트에서 답변을 처리하는 상담원 역할에 사용합니다.

PUT /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply

  • 라우트명: api.modules.sirsoft-ecommerce.user.inquiries.reply.update
  • 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\ProductInquiryController@updateReply
  • 인증/권한: auth:sanctum

요청 파라미터

이름 위치 타입 필수 허용값 용도
inquiryId path string 예 — 대상 inquiry의 식별자
content body string 예 min 1, max 5000 본문 내용

요청 예시

PUT /api/modules/sirsoft-ecommerce/user/inquiries/{inquiryId}/reply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "content": "예시 내용입니다."
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명 사용자 표면에서 문의 답변 권한을 가진 회원이 기존 문의 답변을 수정합니다. auth:sanctum 인증에 더해 컨트롤러가 PermissionHelper::check('sirsoft-ecommerce.inquiries.update') 로 답변 권한을 확인(없으면 403)한 뒤 ProductInquiryService::updateReply() 가 content(1~5000자)로 답변을 갱신하고 {id} 를 반환합니다. 사용자 프론트에서 답변을 처리하는 상담원 역할이 답변 내용을 정정할 때 사용합니다.