fix(core): api:docgen 재생성이 문서를 손실·열화시키는 결함 수정

재생성이 사람이 채운 서술과 이전 실측 결과를 지우고, 코드가 바뀌지 않은 문서까지 매 실행마다 흔들던 결함 5건을 고쳤다. - 중첩 객체 파라미터가 문서에서 통째로 누락되던 문제: 배열 요소(items.*.id)를 상위로 대표시키려던 스킵 조건이 점(.) 포함 여부만 봐서, 와일드카드가 없는 중첩 객체 필드(refund_bank.*, general.*, content.* 등 17개 엔드포인트 수백 개) 까지 함께 버렸다. 와일드카드가 있을 때만 스킵하도록 좁혔다. - 사람이 보강한 에러 응답 표가 자동 추론 초안에 덮여 사라지던 문제: 상태코드 키 단위로 병합한다. - 실측 실패가 이전에 관측해 둔 응답 예시를 지우던 문제: 실측 성패는 호출 시점 데이터 유무에 좌우되므로(DELETE /checkout 은 대상이 없으면 404), 실패는 "새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다. - 실측 예시값·응답 예시 JSON 이 DB 상태를 그대로 반영해 비멱등하던 문제: 값이 아니라 스펙(필드 집합·타입)이 바뀐 경우에만 갱신한다. nullable 이 null 로 관측된 것은 타입 변경이 아니므로 기존 값을 유지한다. - 요청 예시 path 파라미터가 실측 성패에 따라 흔들리던 문제: placeholder 로 고정. 결과: 문서 63개 전수 대조에서 손실 0(서술·표 셀·응답 예시), 전 scope 연속 재생성 시 diff 0(멱등).
2026-08-06 13:54:35 +09:00
1 parent 3f2674f1a7
commit 403154167a
@@ -335,6 +335,10 @@ HTTP/1.1 200
 }
 ```

+**응답 예시**
+
+<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
+
 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
@@ -8,8 +8,8 @@

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

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

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

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -159,7 +159,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/board-types/2 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/board-types/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -167,11 +167,11 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -202,7 +202,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/admin/board-types/2 HTTP/1.1
+PUT /api/modules/sirsoft-board/admin/board-types/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -215,11 +215,11 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -227,8 +227,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.boards.create`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -8,8 +8,8 @@

 ```text
 1. 이 문서는 실제 API 호출로 실측한 Board 엔드포인트 레퍼런스입니다
-2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
-3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
+2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
+3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
 4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
 5. 설명(TODO) 칸은 사람이 채웁니다
 ```
@@ -54,7 +54,7 @@ FULLTEXT 연산자를 제거한 뒤 검색하며, 연산자만 입력한 경우
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments HTTP/1.1
+POST /api/modules/sirsoft-board/admin/board/{slug}/attachments HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -82,11 +82,11 @@ Content-Disposition: form-data; name="temp_key"

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -94,8 +94,8 @@ Content-Disposition: form-data; name="temp_key"
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.attachments.upload`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -120,7 +120,7 @@ Content-Disposition: form-data; name="temp_key"
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/download/apidocsmpl1 HTTP/1.1
+GET /api/modules/sirsoft-board/admin/board/{slug}/attachments/download/{hash} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -128,11 +128,11 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -165,7 +165,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/reorder HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/board/{slug}/attachments/reorder HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -180,11 +180,11 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -192,8 +192,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.attachments.upload`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -216,7 +216,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/board/{slug}/attachments/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -224,9 +224,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -270,7 +268,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts HTTP/1.1
+GET /api/modules/sirsoft-board/admin/board/{slug}/posts HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -437,7 +435,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts HTTP/1.1
+POST /api/modules/sirsoft-board/admin/board/{slug}/posts HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -445,11 +443,11 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -457,8 +455,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -480,7 +478,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/form-data HTTP/1.1
+GET /api/modules/sirsoft-board/admin/board/{slug}/posts/form-data HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -550,7 +548,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/form-meta HTTP/1.1
+GET /api/modules/sirsoft-board/admin/board/{slug}/posts/form-meta HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -675,7 +673,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -834,7 +832,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
+GET /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1094,7 +1092,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
+PUT /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1223,8 +1221,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1248,7 +1246,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/blind HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{id}/blind HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1389,8 +1387,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1414,7 +1412,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/restore HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{id}/restore HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1427,7 +1425,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -1439,8 +1437,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1465,7 +1463,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments HTTP/1.1
+POST /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1473,11 +1471,11 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -1485,8 +1483,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1510,7 +1508,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1518,9 +1516,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -1568,7 +1564,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
+PUT /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1576,11 +1572,11 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -1588,8 +1584,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1614,7 +1610,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1/blind HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id}/blind HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1716,8 +1712,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1741,7 +1737,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1/restore HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id}/restore HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1749,7 +1745,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -8,8 +8,8 @@

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

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -614,7 +614,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/boards/slug/apidoc-sample-board HTTP/1.1
+GET /api/modules/sirsoft-board/admin/boards/slug/{slug} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -780,7 +780,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/boards/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/boards/{board} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -834,7 +834,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/boards/1 HTTP/1.1
+GET /api/modules/sirsoft-board/admin/boards/{board} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1166,7 +1166,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/admin/boards/1 HTTP/1.1
+PUT /api/modules/sirsoft-board/admin/boards/{board} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1229,7 +1229,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -1241,8 +1241,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.boards.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1264,7 +1264,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/admin/boards/1/add-to-menu HTTP/1.1
+POST /api/modules/sirsoft-board/admin/boards/{board}/add-to-menu HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1466,9 +1466,18 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `1` | 기본 키 (내부 식별자) |
+| board_slug | string | `gallery` | <!-- TODO: 설명 --> |
+| board_name | string | `갤러리` | <!-- TODO: 설명 --> |
+| title | string | `일반 게시글 (이미지 있음)` | 제목 |
+| excerpt | string | `이미지가 첨부된 일반 게시글입니다. 정상적으로 표시됩니다.` | <!-- TODO: 설명 --> |
+| author | object | `{"id":1,"name":"관리자","email":"heuristing@gmail.com","is_g…` | 작성자 사용자 객체 (uuid/name — author 관계 파생) |
+| view_count | integer | `258` | view 개수 (집계) |
+| comment_count | integer | `2` | comment 개수 (집계) |
+| created_at | string | `2026-07-07 09:34:50` | 생성 일시 |
+| created_at_formatted | string | `07-10` | `created_at` 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |

 **응답 예시**

@@ -1719,7 +1728,7 @@ _대표 에러 없음 (공개 조회). <!-- TODO: 도메인 특이 에러가 있
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2013,7 +2022,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/attachment/apidocsmpl1 HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/attachment/{hash} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2021,11 +2030,11 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -2055,7 +2064,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/attachment/apidocsmpl1/preview HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/attachment/{hash}/preview HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2063,11 +2072,11 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -2101,7 +2110,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/attachments HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/attachments HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2129,19 +2138,19 @@ Content-Disposition: form-data; name="temp_key"

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.attachments.upload`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -2166,7 +2175,7 @@ Content-Disposition: form-data; name="temp_key"
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/boards/apidoc-sample-board/attachments/reorder HTTP/1.1
+PATCH /api/modules/sirsoft-board/boards/{slug}/attachments/reorder HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2181,19 +2190,19 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.attachments.upload`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -2216,7 +2225,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/boards/apidoc-sample-board/attachments/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/boards/{slug}/attachments/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2224,9 +2233,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -2272,7 +2279,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/comments/1/reports HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/comments/{commentId}/reports HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -2286,19 +2293,19 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

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

 <!-- @generated:end -->

@@ -2321,7 +2328,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/comments/1/verify-password HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/comments/{commentId}/verify-password HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2329,11 +2336,11 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -2362,7 +2369,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2533,7 +2540,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/posts HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/posts HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2541,19 +2548,19 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.posts.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -2575,7 +2582,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/form-data HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts/form-data HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2644,7 +2651,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/form-meta HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts/form-meta HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2768,7 +2775,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/boards/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2776,9 +2783,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -2822,7 +2827,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1 HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3077,7 +3082,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1 HTTP/1.1
+PUT /api/modules/sirsoft-board/boards/{slug}/posts/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3255,6 +3260,7 @@ HTTP/1.1 200
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.posts.write| sirsoft-board.{slug}.manager`)이 없는 경우 |
 | 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -3277,7 +3283,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/navigation HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts/{id}/navigation HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3338,7 +3344,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/verify-password HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/posts/{id}/verify-password HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3351,19 +3357,19 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-400 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.posts.read`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -3387,7 +3393,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/verify-password-for-modify HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/posts/{id}/verify-password-for-modify HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3400,19 +3406,19 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-400 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.posts.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -3435,7 +3441,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/comments HTTP/1.1
+GET /api/modules/sirsoft-board/boards/{slug}/posts/{postId}/comments HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3547,7 +3553,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/comments HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/posts/{postId}/comments HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3555,19 +3561,19 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.comments.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -3591,7 +3597,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/boards/{slug}/posts/{postId}/comments/{commentId} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3599,9 +3605,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -3648,7 +3652,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
+PUT /api/modules/sirsoft-board/boards/{slug}/posts/{postId}/comments/{commentId} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -3656,11 +3660,11 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -3669,6 +3673,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 | 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.comments.write| sirsoft-board.{slug}.manager`)이 없는 경우 |
 | 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -3693,7 +3698,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-board/boards/apidoc-sample-board/posts/1/reports HTTP/1.1
+POST /api/modules/sirsoft-board/boards/{slug}/posts/{postId}/reports HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -3707,19 +3712,19 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

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

 <!-- @generated:end -->

@@ -8,8 +8,8 @@

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

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

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

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -268,7 +268,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -302,7 +302,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-board/admin/reports/1 HTTP/1.1
+DELETE /api/modules/sirsoft-board/admin/reports/{report} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -310,9 +310,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -356,7 +354,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/reports/1 HTTP/1.1
+GET /api/modules/sirsoft-board/admin/reports/{report} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -486,7 +484,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/admin/reports/1/reporters?per_page=1&page=1 HTTP/1.1
+GET /api/modules/sirsoft-board/admin/reports/{report}/reporters?per_page=1&page=1 HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -536,8 +534,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.reports.view`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -561,7 +559,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-board/admin/reports/1/status HTTP/1.1
+PATCH /api/modules/sirsoft-board/admin/reports/{report}/status HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -575,11 +573,11 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -587,8 +585,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-board.reports.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -8,8 +8,8 @@

 ```text
 1. 이 문서는 실제 API 호출로 실측한 Settings 엔드포인트 레퍼런스입니다
-2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
-3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
+2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
+3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
 4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
 5. 설명(TODO) 칸은 사람이 채웁니다
 ```
@@ -363,10 +363,36 @@ HTTP/1.1 200
 | notifications | body | array | 아니오 | — | 알림 채널 설정. `channels` 배열의 각 항목에 채널 식별자(id), 활성화 여부(is_active), 정렬 순서(sort_order)를 담아 저장합니다. |
 | basic_defaults | body | array | 아니오 | — | 기본 설정 카테고리 값. 게시판 타입·페이지당 글 수·정렬·댓글/답글·길이 제한·파일 업로드·기본 권한 등 basic_defaults 하위 키를 저장합니다. `basic_defaults.allowed_extensions` 는 `basic_defaults.use_file_upload` 가 `true` 일 때만 최소 1개가 필수이며, `false`/`null` 이면 검증에서 제외되어 빈 배열도 허용됩니다. `min_title_length`·`min_comment_length`·`new_display_hours` 의 하한은 `config('sirsoft-board.limits')` 선언을 따르며 `0` 을 허용합니다. |
 | report_policy | body | array | 아니오 | — | 신고 정책 카테고리 값. 자동 숨김 임계치/대상, 일일 신고 한도, 거부 누적 제한, 관리자·작성자 신고 알림 설정을 저장합니다. |
+| report_policy.auto_hide_threshold | body | integer | 아니오 | min 0, max 100 | <!-- TODO: 용도 --> |
+| report_policy.auto_hide_target | body | string | 아니오 | `post`, `comment`, `both` | <!-- TODO: 용도 --> |
+| report_policy.daily_report_limit | body | integer | 아니오 | min 0, max 100 | <!-- TODO: 용도 --> |
+| report_policy.rejection_limit_count | body | integer | 아니오 | min 0, max 50 | <!-- TODO: 용도 --> |
+| report_policy.rejection_limit_days | body | integer | 아니오 | min 1, max 365 | <!-- TODO: 용도 --> |
+| report_policy.notify_admin_on_report | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| report_policy.notify_admin_on_report_scope | body | string | 아니오 | `per_case`, `per_report` | <!-- TODO: 용도 --> |
+| report_policy.notify_admin_on_report_channels | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| report_policy.notify_author_on_report_action | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| report_policy.notify_author_on_report_action_channels | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | report_permissions | body | array | 아니오 | — | 신고 관리 권한 역할. `view_roles`(조회 역할)와 `manage_roles`(관리 역할)의 역할 식별자 배열이며, 포함 시 설정 저장과 별개로 DB 권한 역할이 동기화됩니다. |
+| report_permissions.view_roles | body | array | 아니오 | min 1 | <!-- TODO: 용도 --> |
+| report_permissions.manage_roles | body | array | 아니오 | min 1 | <!-- TODO: 용도 --> |
 | display | body | array | 아니오 | — | 표시 설정 카테고리 값. 날짜 표시 형식(date_display_format: standard/relative) 등을 저장합니다. |
+| display.date_display_format | body | string | 아니오 | `standard`, `relative` | <!-- TODO: 용도 --> |
 | spam_security | body | array | 아니오 | — | 스팸·보안 카테고리 값. 글·댓글·신고 작성 쿨다운 시간(초)과 조회수 캐시 TTL을 저장합니다. |
+| spam_security.post_cooldown_seconds | body | integer | 아니오 | min 0, max 3600 | <!-- TODO: 용도 --> |
+| spam_security.comment_cooldown_seconds | body | integer | 아니오 | min 0, max 3600 | <!-- TODO: 용도 --> |
+| spam_security.report_cooldown_seconds | body | integer | 아니오 | min 0, max 3600 | <!-- TODO: 용도 --> |
+| spam_security.view_count_cache_ttl | body | integer | 아니오 | min 60, max 604800 | <!-- TODO: 용도 --> |
 | seo | body | array | 아니오 | — | SEO 설정 카테고리 값. 게시판 목록/개별/글 상세 페이지의 메타 제목·설명 템플릿과 각 페이지 SEO 활성화 여부를 저장합니다. |
+| seo.meta_boards_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_boards_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.meta_board_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_board_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.meta_post_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_post_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.seo_boards | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| seo.seo_board | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| seo.seo_post_detail | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |

 **요청 예시**

@@ -382,24 +408,95 @@ Content-Type: application/json
    "notifications": [
        "예시값"
    ],
+    "notifications.channels": [
+        "예시값"
+    ],
    "basic_defaults": [
        "예시값"
    ],
+    "basic_defaults.type": "예시값",
+    "basic_defaults.per_page": 1,
+    "basic_defaults.per_page_mobile": 1,
+    "basic_defaults.order_by": "created_at",
+    "basic_defaults.order_direction": "ASC",
+    "basic_defaults.secret_mode": "disabled",
+    "basic_defaults.use_comment": true,
+    "basic_defaults.use_reply": true,
+    "basic_defaults.max_reply_depth": 1,
+    "basic_defaults.max_comment_depth": 1,
+    "basic_defaults.comment_order": "ASC",
+    "basic_defaults.show_view_count": true,
+    "basic_defaults.use_report": true,
+    "basic_defaults.min_title_length": 1,
+    "basic_defaults.max_title_length": 1,
+    "basic_defaults.min_content_length": 1,
+    "basic_defaults.max_content_length": 1,
+    "basic_defaults.min_comment_length": 1,
+    "basic_defaults.max_comment_length": 1,
+    "basic_defaults.use_file_upload": true,
+    "basic_defaults.max_file_size": 1,
+    "basic_defaults.max_file_count": 1,
+    "basic_defaults.blocked_keywords": [
+        "예시값"
+    ],
+    "basic_defaults.allowed_extensions": [
+        "예시값"
+    ],
+    "basic_defaults.notify_admin_on_post": true,
+    "basic_defaults.notify_author": true,
+    "basic_defaults.new_display_hours": 1,
+    "basic_defaults.default_board_permissions": [
+        "예시값"
+    ],
    "report_policy": [
        "예시값"
    ],
+    "report_policy.auto_hide_threshold": 1,
+    "report_policy.auto_hide_target": "post",
+    "report_policy.daily_report_limit": 1,
+    "report_policy.rejection_limit_count": 1,
+    "report_policy.rejection_limit_days": 1,
+    "report_policy.notify_admin_on_report": true,
+    "report_policy.notify_admin_on_report_scope": "per_case",
+    "report_policy.notify_admin_on_report_channels": [
+        "예시값"
+    ],
+    "report_policy.notify_author_on_report_action": true,
+    "report_policy.notify_author_on_report_action_channels": [
+        "예시값"
+    ],
    "report_permissions": [
        "예시값"
    ],
+    "report_permissions.view_roles": [
+        "예시값"
+    ],
+    "report_permissions.manage_roles": [
+        "예시값"
+    ],
    "display": [
        "예시값"
    ],
+    "display.date_display_format": "standard",
    "spam_security": [
        "예시값"
    ],
+    "spam_security.post_cooldown_seconds": 1,
+    "spam_security.comment_cooldown_seconds": 1,
+    "spam_security.report_cooldown_seconds": 1,
+    "spam_security.view_count_cache_ttl": 1,
    "seo": [
        "예시값"
-    ]
+    ],
+    "seo.meta_boards_title": "예시 제목",
+    "seo.meta_boards_description": "예시 내용입니다.",
+    "seo.meta_board_title": "예시 제목",
+    "seo.meta_board_description": "예시 내용입니다.",
+    "seo.meta_post_title": "예시 제목",
+    "seo.meta_post_description": "예시 내용입니다.",
+    "seo.seo_boards": true,
+    "seo.seo_board": true,
+    "seo.seo_post_detail": true
 }
 ```

@@ -719,7 +816,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -759,7 +856,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -8,8 +8,8 @@

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

 ```http
-GET /api/modules/sirsoft-board/users/a234c2b1-cde8-437f-b28b-23323be2b98d/posts HTTP/1.1
+GET /api/modules/sirsoft-board/users/{user}/posts HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -147,7 +147,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-board/users/a234c2b1-cde8-437f-b28b-23323be2b98d/posts/stats HTTP/1.1
+GET /api/modules/sirsoft-board/users/{user}/posts/stats HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -356,8 +356,8 @@ Content-Type: application/json
 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -306,8 +306,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.brands.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -651,8 +651,8 @@ Content-Type: application/json

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -700,8 +700,8 @@ Content-Type: application/json

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -251,6 +251,8 @@ Content-Type: application/json
 | temp_key | body | string | 아니오 | max 64 | 사전 업로드한 임시 이미지를 이 카테고리에 연결하기 위한 FileUploader temp_key |
 | collection | body | string | 아니오 | max 100 | 첨부 컬렉션 그룹명 (첨부를 용도별로 묶는 키, 미지정 시 default) |
 | alt_text | body | array | 아니오 | — | 이미지 대체 텍스트 (접근성/이미지 미표시 시 대체 문구) |
+| alt_text.ko | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| alt_text.en | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |

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

@@ -279,6 +281,14 @@ Content-Disposition: form-data; name="collection"
 ------G7ExampleBoundary
 Content-Disposition: form-data; name="alt_text"

+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.ko"
+
+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.en"
+
 예시값
 ------G7ExampleBoundary--
 ```
@@ -578,6 +588,8 @@ HTTP/1.1 200
 | temp_key | body | string | 아니오 | max 64 | 사전 업로드한 임시 이미지를 이 카테고리에 연결하기 위한 FileUploader temp_key |
 | collection | body | string | 아니오 | max 100 | 첨부 컬렉션 그룹명 (첨부를 용도별로 묶는 키, 미지정 시 default) |
 | alt_text | body | array | 아니오 | — | 이미지 대체 텍스트 (접근성/이미지 미표시 시 대체 문구) |
+| alt_text.ko | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| alt_text.en | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |

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

@@ -606,6 +618,14 @@ Content-Disposition: form-data; name="collection"
 ------G7ExampleBoundary
 Content-Disposition: form-data; name="alt_text"

+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.ko"
+
+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.en"
+
 예시값
 ------G7ExampleBoundary--
 ```
@@ -624,8 +644,8 @@ Content-Disposition: form-data; name="alt_text"
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.categories.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -735,8 +755,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.categories.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -8,7 +8,7 @@

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

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/active?type=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
+DELETE /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -234,6 +234,303 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| reason_id | integer | `8` | reason 식별자 (연관 리소스 참조) |
+
+**응답 예시**
+
+```http
+HTTP/1.1 200
+```
+
+```json
+{
+    "success": true,
+    "message": "클래임 사유가 삭제되었습니다.",
+    "data": {
+        "reason_id": 8
+    }
+}
+```
+
+**에러 응답**
+
+| 상태코드 | 의미 | 발생 조건 |
+| --- | --- | --- |
+| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
+| 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.settings.update`)이 없는 경우 |
+| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+
+<!-- @generated:end -->
+
+**설명** 관리자가 클래임 사유 1건을 삭제합니다. `permission:sirsoft-ecommerce.settings.update` 권한이 필요하며, 대상이 없으면 404 를 반환하고 존재하면 `ClaimReasonService::deleteReason()`이 삭제합니다. 이미 사용 중인 사유 등 삭제 불가 상황에서는 서비스가 던진 예외 메시지를 그대로 사용해 400 으로 응답하므로, 관리자에게 삭제 실패 사유가 노출됩니다.
+
+
+### GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
+<!-- @generated:start:api.modules.sirsoft-ecommerce.admin.claim-reasons.show -->
+- **라우트명**: `api.modules.sirsoft-ecommerce.admin.claim-reasons.show`
+- **컨트롤러**: `Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@show`
+- **인증/권한**: `auth:sanctum` + `permission:sirsoft-ecommerce.settings.read`
+
+**요청 파라미터**
+
+| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
+| --- | --- | --- | --- | --- | --- |
+| id | path | string | 예 | — | 대상 리소스의 식별자 |
+
+**요청 예시**
+
+```http
+GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
+Host: api.example.com
+Accept: application/json
+Authorization: Bearer {YOUR_TOKEN}
+```
+
+**응답 필드** (`data` 내부)
+
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `8` | 기본 키 (내부 식별자) |
+| type | string | `refund` | 사유 유형 (refund, exchange, return 등) |
+| code | string | `apidoc_sample` | 고유 코드 (order_mistake 등) |
+| name | object | `{"ko":"API 문서 샘플 사유","en":"API Doc Sample Reason"}` | 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
+| localized_name | string | `API 문서 샘플 사유` | `name` 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
+| fault_type | string | `customer` | 귀책 구분 (customer, seller, carrier) |
+| fault_type_label | string | `고객 귀책` | `fault_type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| is_user_selectable | boolean | `true` | user selectable 여부 |
+| is_active | boolean | `true` | active 여부 |
+| sort_order | integer | `0` | 표시 정렬 순서 값 (작을수록 우선) |
+| created_at | string | `2026-07-08 10:44:49` | 생성 일시 |
+| updated_at | string | `2026-07-08 10:44:49` | 최종 수정 일시 |
+| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
+
+**응답 예시**
+
+```http
+HTTP/1.1 200
+```
+
+```json
+{
+    "success": true,
+    "message": "클래임 사유 정보를 조회했습니다.",
+    "data": {
+        "id": 8,
+        "type": "refund",
+        "code": "apidoc_sample",
+        "name": {
+            "ko": "API 문서 샘플 사유",
+            "en": "API Doc Sample Reason"
+        },
+        "localized_name": "API 문서 샘플 사유",
+        "fault_type": "customer",
+        "fault_type_label": "고객 귀책",
+        "is_user_selectable": true,
+        "is_active": true,
+        "sort_order": 0,
+        "created_at": "2026-07-08 10:44:49",
+        "updated_at": "2026-07-08 10:44:49",
+        "abilities": {
+            "can_create": true,
+            "can_update": true,
+            "can_delete": true
+        }
+    }
+}
+```
+
+**에러 응답**
+
+| 상태코드 | 의미 | 발생 조건 |
+| --- | --- | --- |
+| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
+| 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.settings.read`)이 없는 경우 |
+| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+
+<!-- @generated:end -->
+
+**설명** 관리자가 클래임 사유 1건의 상세 정보를 조회합니다. `permission:sirsoft-ecommerce.settings.read` 권한이 필요하며, `ClaimReasonService::getReason()`이 대상을 조회해 `ClaimReasonResource`로 반환합니다. 사유 편집 폼을 열 때 기존 값(다국어 사유명·코드·귀책 구분·활성/노출 설정 등)을 채우는 용도로 사용되며, 해당 사유가 없으면 404 를 반환합니다.
+
+
+### PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
+<!-- @generated:start:api.modules.sirsoft-ecommerce.admin.claim-reasons.update -->
+- **라우트명**: `api.modules.sirsoft-ecommerce.admin.claim-reasons.update`
+- **컨트롤러**: `Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@update`
+- **인증/권한**: `auth:sanctum` + `permission:sirsoft-ecommerce.settings.update`
+
+**요청 파라미터**
+
+| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
+| --- | --- | --- | --- | --- | --- |
+| id | path | string | 예 | — | 대상 리소스의 식별자 |
+| type | body | string | 예 | — | 클래임 사유 유형 (ClaimReasonTypeEnum — 현재 `refund`(환불/취소)) |
+| code | body | string | 예 | max 50 | 사유 식별 코드 (영문 소문자/숫자/`_`, 같은 type 내에서 고유) |
+| name | body | array | 예 | — | 대상의 이름/명칭 |
+| fault_type | body | string | 예 | — | 귀책 구분 (ClaimReasonFaultTypeEnum — `customer`(고객)/`seller`(판매자)/`carrier`(배송사)) |
+| is_user_selectable | body | boolean | 아니오 | — | user selectable 여부 |
+| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
+| sort_order | body | integer | 아니오 | min 0 | 표시 정렬 순서 값 (작을수록 우선) |
+
+**요청 예시**
+
+```http
+PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
+Host: api.example.com
+Accept: application/json
+Authorization: Bearer {YOUR_TOKEN}
+Content-Type: application/json
+
+{
+    "type": "예시값",
+    "code": "예시값",
+    "name": [
+        "예시 이름"
+    ],
+    "fault_type": "예시값",
+    "is_user_selectable": true,
+    "is_active": true,
+    "sort_order": 1
+}
+```
+
+**응답 필드** (`data` 내부)
+
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
+
+**응답 예시**
+
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
+
+**에러 응답**
+
+| 상태코드 | 의미 | 발생 조건 |
+| --- | --- | --- |
+| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
+| 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.settings.update`)이 없는 경우 |
+| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
+
+<!-- @generated:end -->
+
+**설명** 관리자가 기존 클래임 사유를 수정합니다. `permission:sirsoft-ecommerce.settings.update` 권한이 필요하고 대상은 경로 `id` 로 지정하며, 생성과 동일한 필드(유형·코드·다국어 사유명·귀책 구분·노출/활성/정렬)를 받아 `ClaimReasonService::updateReason()`이 갱신하고 갱신된 사유를 반환합니다. 대상이 없거나 갱신 실패 시 400 오류로 응답합니다.
+
+
+### PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status
+<!-- @generated:start:api.modules.sirsoft-ecommerce.admin.claim-reasons.toggle-status -->
+- **라우트명**: `api.modules.sirsoft-ecommerce.admin.claim-reasons.toggle-status`
+- **컨트롤러**: `Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@toggleStatus`
+- **인증/권한**: `auth:sanctum` + `permission:sirsoft-ecommerce.settings.update`
+
+**요청 파라미터**
+
+| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
+| --- | --- | --- | --- | --- | --- |
+| id | path | string | 예 | — | 대상 리소스의 식별자 |
+
+**요청 예시**
+
+```http
+PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status HTTP/1.1
+Host: api.example.com
+Accept: application/json
+Authorization: Bearer {YOUR_TOKEN}
+```
+
+**응답 필드** (`data` 내부)
+
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `8` | 기본 키 (내부 식별자) |
+| type | string | `refund` | 사유 유형 (refund, exchange, return 등) |
+| code | string | `apidoc_sample` | 고유 코드 (order_mistake 등) |
+| name | object | `{"ko":"API 문서 샘플 사유","en":"API Doc Sample Reason"}` | 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
+| localized_name | string | `API 문서 샘플 사유` | `name` 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
+| fault_type | string | `customer` | 귀책 구분 (customer, seller, carrier) |
+| fault_type_label | string | `고객 귀책` | `fault_type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| is_user_selectable | boolean | `true` | user selectable 여부 |
+| is_active | boolean | `false` | active 여부 |
+| sort_order | integer | `0` | 표시 정렬 순서 값 (작을수록 우선) |
+| created_at | string | `2026-07-08 10:44:49` | 생성 일시 |
+| updated_at | string | `2026-07-08 15:00:18` | 최종 수정 일시 |
+| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
+
+**응답 예시**
+
+```http
+HTTP/1.1 200
+```
+
+```json
+{
+    "success": true,
+    "message": "클래임 사유 상태가 변경되었습니다.",
+    "data": {
+        "id": 8,
+        "type": "refund",
+        "code": "apidoc_sample",
+        "name": {
+            "ko": "API 문서 샘플 사유",
+            "en": "API Doc Sample Reason"
+        },
+        "localized_name": "API 문서 샘플 사유",
+        "fault_type": "customer",
+        "fault_type_label": "고객 귀책",
+        "is_user_selectable": true,
+        "is_active": false,
+        "sort_order": 0,
+        "created_at": "2026-07-08 10:44:49",
+        "updated_at": "2026-07-08 15:00:18",
+        "abilities": {
+            "can_create": true,
+            "can_update": true,
+            "can_delete": true
+        }
+    }
+}
+```
+
+**에러 응답**
+
+| 상태코드 | 의미 | 발생 조건 |
+| --- | --- | --- |
+| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
+| 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.settings.update`)이 없는 경우 |
+| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+
+<!-- @generated:end -->
+
+**설명** 관리자가 클래임 사유의 활성 상태를 켜고 끄는 토글을 수행합니다. `permission:sirsoft-ecommerce.settings.update` 권한이 필요하며, `ClaimReasonService::toggleStatus()`가 대상 사유의 `is_active` 값을 반전시켜 저장하고 갱신된 사유를 반환합니다. 사유를 삭제하지 않고 일시적으로 회원 선택지에서 감추거나 다시 노출할 때 사용합니다.
+
+
+### GET /api/modules/sirsoft-ecommerce/user/claim-reasons
+<!-- @generated:start:api.modules.sirsoft-ecommerce.user.claim-reasons.index -->
+- **라우트명**: `api.modules.sirsoft-ecommerce.user.claim-reasons.index`
+- **컨트롤러**: `Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@userSelectableReasons`
+- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근) + `permission:sirsoft-ecommerce.user-orders.cancel`
+
+**요청 파라미터**
+
+_요청 파라미터 없음._
+
+**요청 예시**
+
+```http
+GET /api/modules/sirsoft-ecommerce/user/claim-reasons HTTP/1.1
+Host: api.example.com
+Accept: application/json
+Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
+```
+
+**응답 필드** (`data` 내부)
+
 _목록 응답: `data.data[]` 배열 항목의 필드._

 | 필드 | 타입 | 실측 예시값 | 용도/설명 |
@@ -545,8 +545,8 @@ Content-Type: application/json
 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -42,7 +42,7 @@ _단건 응답: `data` 객체의 필드._

 | 필드 | 타입 | 실측 예시값 | 용도/설명 |
 | --- | --- | --- | --- |
-| preferred_currency | null | `null` | 회원이 저장한 선호 결제 통화 코드 (미설정 시 `null`) |
+| preferred_currency | string | `KRW` | 회원이 저장한 선호 결제 통화 코드 (미설정 시 `null`) |

 **응답 예시**

@@ -731,8 +731,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.shipping-policies.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -8,7 +8,7 @@

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

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -283,8 +283,8 @@ HTTP/1.1 200

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -339,8 +339,8 @@ Content-Type: application/json

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -449,8 +449,8 @@ Content-Type: application/json

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -142,8 +142,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.inquiries.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -191,8 +191,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.inquiries.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

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

 <!-- @generated:end -->

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

 <!-- @generated:end -->

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

 <!-- @generated:end -->

@@ -383,8 +383,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.mileage.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -149,6 +149,12 @@ Content-Type: application/json
 | --- | --- | --- | --- | --- | --- |
 | ids | body | array | 예 | min 1 | 대상 리소스 식별자 배열 (대량 작업 대상) |
 | bulk_changes | body | array | 아니오 | — | 옵션 일괄 변경 조건 (`price_adjustment`/`stock_quantity` 각각 method+value, 설정된 필드가 개별 수정보다 우선 적용) |
+| bulk_changes.price_adjustment | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| bulk_changes.price_adjustment.method | body | string | 아니오 | `set`, `add`, `percent` | <!-- TODO: 용도 --> |
+| bulk_changes.price_adjustment.value | body | number | 아니오 | — | <!-- TODO: 용도 --> |
+| bulk_changes.stock_quantity | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| bulk_changes.stock_quantity.method | body | string | 아니오 | `set`, `add`, `subtract` | <!-- TODO: 용도 --> |
+| bulk_changes.stock_quantity.value | body | integer | 아니오 | min 0 | <!-- TODO: 용도 --> |
 | items | body | array | 아니오 | — | 처리 대상 항목 배열 |

 > 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`sirsoft-ecommerce.option.bulk_update_validation_rules`).
@@ -169,6 +175,16 @@ Content-Type: application/json
    "bulk_changes": [
        "예시값"
    ],
+    "bulk_changes.price_adjustment": [
+        "예시값"
+    ],
+    "bulk_changes.price_adjustment.method": "set",
+    "bulk_changes.price_adjustment.value": 1,
+    "bulk_changes.stock_quantity": [
+        "예시값"
+    ],
+    "bulk_changes.stock_quantity.method": "set",
+    "bulk_changes.stock_quantity.value": 1,
    "items": [
        "예시값"
    ]
@@ -8,7 +8,7 @@

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

 ```http
-DELETE /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
+DELETE /api/modules/sirsoft-ecommerce/admin/orders/{order} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -405,7 +405,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/orders/{order} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -591,7 +591,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
+PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -630,8 +630,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -662,7 +662,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1316/cancel HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cancel HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -676,7 +676,10 @@ Content-Type: application/json
        "예시값"
    ],
    "cancel_pg": true,
-    "refund_priority": "pg_first"
+    "refund_priority": "pg_first",
+    "refund_bank.bank_code": "예시값",
+    "refund_bank.account_number": "예시값",
+    "refund_bank.holder": "예시값"
 }
 ```

@@ -694,8 +697,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -717,7 +720,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt HTTP/1.1
+DELETE /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -784,7 +787,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -859,8 +862,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -913,7 +916,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt/reissue HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt/reissue HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1002,7 +1005,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316/confirm-deposit HTTP/1.1
+PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order}/confirm-deposit HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1029,8 +1032,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1054,7 +1057,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1316/estimate-refund HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/estimate-refund HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1082,8 +1085,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1107,7 +1110,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/orders/1316/logs?per_page=1&sort_order=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/orders/{order}/logs?per_page=1&sort_order=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1292,8 +1295,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.read`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1319,7 +1322,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316/options/bulk-status HTTP/1.1
+PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order}/options/bulk-status HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1349,8 +1352,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1374,7 +1377,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1316/reset-guest-lookup-password HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/reset-guest-lookup-password HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1388,11 +1391,25 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
+
+
+<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- @probed -->
+
+```http
+HTTP/1.1 200
+```
+
+```json
+{
+    "success": true,
+    "message": "비회원 조회 비밀번호가 재설정되었습니다.",
+    "data": null
+}
+```

 **에러 응답**

@@ -1400,8 +1417,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1425,7 +1442,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/admin/orders/1316/send-email HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/send-email HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1451,8 +1468,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.orders.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1500,8 +1517,8 @@ Content-Type: application/json

 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1645,6 +1662,11 @@ HTTP/1.1 200
 | expected_total_amount | body | number | 예 | min 0 | 프론트가 계산한 예상 결제금액 (서버 재계산값과 대조해 금액 위변조 검증) |
 | shipping_memo | body | string | 아니오 | max 500 | 배송 요청사항 메모 |
 | depositor_name | body | string | 아니오 | max 50 | depositor 이름 (식별자) |
+| dbank.bank_code | body | string | 아니오 | max 10 | <!-- TODO: 용도 --> |
+| dbank.bank_name | body | string | 아니오 | max 50 | dbank.bank 이름 (식별자) |
+| dbank.account_number | body | string | 아니오 | max 50 | <!-- TODO: 용도 --> |
+| dbank.account_holder | body | string | 아니오 | max 50 | <!-- TODO: 용도 --> |
+| dbank.due_days | body | integer | 아니오 | min 1, max 30 | <!-- TODO: 용도 --> |
 | save_shipping_address | body | boolean | 아니오 | — | 회원 주소록에 이번 배송지 저장 여부 (회원 주문 한정) |
 | cash_receipt_requested | body | boolean | 아니오 | — | 현금영수증 신청 여부 (true 면 아래 3개 필드가 필수) |
 | cash_receipt_type | body | string | 아니오 | — | 발급 용도 (`income` 소득공제 / `expense` 지출증빙) |
@@ -1653,6 +1675,7 @@ HTTP/1.1 200
 | refund_bank.bank_code | body | string | 아니오 | max 10 | 환불 계좌 은행코드 (세 필드는 전부 입력하거나 전부 비워야 함) |
 | refund_bank.account_number | body | string | 아니오 | max 50 | 환불 계좌번호 |
 | refund_bank.holder | body | string | 아니오 | max 50 | 환불 계좌 예금주 |
+| orderer.email | body | email | 예 | max 255 | <!-- TODO: 용도 --> |
 | guest_lookup_password | body | string | 예 | min 8, max 255 | 비회원 주문 조회 비밀번호 (비회원만 필수, 8자 이상 · 해시로 저장) |
 | guest_lookup_password_confirmation | body | string | 예 | — | 조회 비밀번호 확인 (guest_lookup_password 와 일치해야 함) |

@@ -1668,15 +1691,39 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 Content-Type: application/json

 {
+    "orderer.name": "예시 이름",
+    "orderer.phone": "010-1234-5678",
+    "shipping.recipient_name": "예시 이름",
+    "shipping.recipient_phone": "010-1234-5678",
+    "shipping.recipient_tel": "예시값",
+    "shipping.country_code": "KR",
+    "shipping.zipcode": "06234",
+    "shipping.address": "서울특별시 강남구 테헤란로 1",
+    "shipping.address_detail": "서울특별시 강남구 테헤란로 1",
+    "shipping.address_type_code": "R",
+    "shipping.address_line_1": "서울특별시 강남구 테헤란로 1",
+    "shipping.address_line_2": "서울특별시 강남구 테헤란로 1",
+    "shipping.intl_city": "예시값",
+    "shipping.intl_state": "예시값",
+    "shipping.intl_postal_code": "06234",
    "payment_method": "예시값",
    "expected_total_amount": 1,
    "shipping_memo": "예시값",
    "depositor_name": "예시 이름",
+    "dbank.bank_code": "예시값",
+    "dbank.bank_name": "예시 이름",
+    "dbank.account_number": "예시값",
+    "dbank.account_holder": "예시값",
+    "dbank.due_days": 1,
    "save_shipping_address": true,
    "cash_receipt_requested": true,
    "cash_receipt_type": "예시값",
    "cash_receipt_identifier_type": "example-key",
    "cash_receipt_identifier": "example-key",
+    "refund_bank.bank_code": "예시값",
+    "refund_bank.account_number": "예시값",
+    "refund_bank.holder": "예시값",
+    "orderer.email": "user@example.com",
    "guest_lookup_password": "Password123!",
    "guest_lookup_password_confirmation": "Password123!"
 }
@@ -1909,8 +1956,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-orders.cancel`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

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

 <!-- @generated:end -->

@@ -2140,8 +2187,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-orders.cancel`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

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

 <!-- @generated:end -->

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

 <!-- @generated:end -->

@@ -366,8 +366,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.product-common-infos.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -318,8 +318,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.product-labels.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -430,8 +430,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.product-notice-templates.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -550,8 +550,16 @@ Content-Type: application/json
 | --- | --- | --- | --- | --- | --- |
 | ids | body | array | 예 | min 1 | 대상 리소스 식별자 배열 (대량 작업 대상) |
 | bulk_changes | body | array | 아니오 | — | 상품 조건 기반 일괄 변경값 (지정 시 ids 전체에 sales_status/display_status 일괄 적용) |
+| bulk_changes.sales_status | body | string | 아니오 | — | <!-- TODO: 용도 --> |
+| bulk_changes.display_status | body | string | 아니오 | — | <!-- TODO: 용도 --> |
 | items | body | array | 아니오 | — | 처리 대상 항목 배열 |
 | option_bulk_changes | body | array | 아니오 | — | 옵션 조건 기반 일괄 변경값 (price_adjustment/stock_quantity 를 method+value 로 일괄 조정) |
+| option_bulk_changes.price_adjustment | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| option_bulk_changes.price_adjustment.method | body | string | 아니오 | `set`, `add`, `percent` | <!-- TODO: 용도 --> |
+| option_bulk_changes.price_adjustment.value | body | number | 아니오 | — | <!-- TODO: 용도 --> |
+| option_bulk_changes.stock_quantity | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| option_bulk_changes.stock_quantity.method | body | string | 아니오 | `set`, `add`, `subtract` | <!-- TODO: 용도 --> |
+| option_bulk_changes.stock_quantity.value | body | integer | 아니오 | min 0 | <!-- TODO: 용도 --> |
 | option_items | body | array | 아니오 | — | 옵션 개별 인라인 수정 배열 (각 항목: product_id·option_id + 수정할 옵션 필드) |

 > 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`sirsoft-ecommerce.product.bulk_update_validation_rules`).
@@ -572,12 +580,24 @@ Content-Type: application/json
    "bulk_changes": [
        "예시값"
    ],
+    "bulk_changes.sales_status": "예시값",
+    "bulk_changes.display_status": "예시값",
    "items": [
        "예시값"
    ],
    "option_bulk_changes": [
        "예시값"
    ],
+    "option_bulk_changes.price_adjustment": [
+        "예시값"
+    ],
+    "option_bulk_changes.price_adjustment.method": "set",
+    "option_bulk_changes.price_adjustment.value": 1,
+    "option_bulk_changes.stock_quantity": [
+        "예시값"
+    ],
+    "option_bulk_changes.stock_quantity.method": "set",
+    "option_bulk_changes.stock_quantity.value": 1,
    "option_items": [
        "예시값"
    ]
@@ -794,8 +814,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.products.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -855,6 +875,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | temp_key | body | string | 아니오 | max 64 | 임시 업로드 세션 키 (같은 상품의 여러 이미지를 한 세션으로 묶음, 생략 시 서버가 UUID 자동 발급) |
 | collection | body | string | 아니오 | — | 첨부 컬렉션 그룹명 (첨부를 용도별로 묶는 키, 미지정 시 default) |
 | alt_text | body | array | 아니오 | — | 이미지 대체 텍스트 (접근성/이미지 미표시 시 대체 문구) |
+| alt_text.ko | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| alt_text.en | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |

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

@@ -883,6 +905,14 @@ Content-Disposition: form-data; name="collection"
 ------G7ExampleBoundary
 Content-Disposition: form-data; name="alt_text"

+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.ko"
+
+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.en"
+
 예시값
 ------G7ExampleBoundary--
 ```
@@ -1104,6 +1134,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | temp_key | body | string | 아니오 | max 64 | 임시 업로드 세션 키 (같은 상품의 여러 이미지를 한 세션으로 묶음, 생략 시 서버가 UUID 자동 발급) |
 | collection | body | string | 아니오 | — | 첨부 컬렉션 그룹명 (첨부를 용도별로 묶는 키, 미지정 시 default) |
 | alt_text | body | array | 아니오 | — | 이미지 대체 텍스트 (접근성/이미지 미표시 시 대체 문구) |
+| alt_text.ko | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| alt_text.en | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |

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

@@ -1132,6 +1164,14 @@ Content-Disposition: form-data; name="collection"
 ------G7ExampleBoundary
 Content-Disposition: form-data; name="alt_text"

+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.ko"
+
+예시값
+------G7ExampleBoundary
+Content-Disposition: form-data; name="alt_text.en"
+
 예시값
 ------G7ExampleBoundary--
 ```
@@ -1150,8 +1190,8 @@ Content-Disposition: form-data; name="alt_text"
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.products.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1216,7 +1256,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-ecommerce/admin/products/1732 HTTP/1.1
+DELETE /api/modules/sirsoft-ecommerce/admin/products/{product} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1300,7 +1340,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-ecommerce/admin/products/1732 HTTP/1.1
+PUT /api/modules/sirsoft-ecommerce/admin/products/{product} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1390,8 +1430,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.products.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -1413,7 +1453,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/products/1732/can-delete HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/products/{product}/can-delete HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1494,7 +1534,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/products/1732/copy?copy_images=1&copy_options=1&copy_categories=1&copy_sales_info=1&copy_description=1&copy_notice=1&copy_common_info=1&copy_other_info=1&copy_shipping=1&copy_seo=1&copy_identification=1 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/products/{product}/copy HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1598,7 +1638,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/products/1732/form HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/products/{product}/form HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -1643,7 +1683,7 @@ _단건 응답: `data` 객체의 필드._
 | purchase_restriction | string | `none` | 구매 제한: none(없음), restricted(제한) |
 | allowed_roles | array | `[]` | 구매 허용 역할 ID 배열 |
 | meta_title | null | `null` | SEO 제목 (다국어 JSON) |
-| meta_description | null | `null` | SEO 설명 (다국어 JSON) |
+| meta_description | object | `{"ko":"면 손수건 3매입 #1 의 직접 입력 SEO 설명입니다.","en":"Custom SEO …` | SEO 설명 (다국어 JSON) |
 | seo_tags | array | `[]` | SEO 태그 목록 (메타 키워드 등 검색엔진 노출용 태그) |
 | seo_sync_title | boolean | `true` | SEO 제목 동기화 여부 (1: 상품명으로 자동 채움, 0: 직접 입력 보존) |
 | seo_sync_description | boolean | `true` | SEO 설명 동기화 여부 (1: 상품 설명으로 자동 채움, 0: 직접 입력 보존) |
@@ -1706,7 +1746,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/admin/products/1732/logs?per_page=1&sort_order=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/admin/products/{product}/logs HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -2391,7 +2431,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/products/1732 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/products/{product} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2439,7 +2479,7 @@ _단건 응답: `data` 객체의 필드._
 | images | array | `[{"id":7,"hash":"7df7761cdf16","original_filename":"produ…` | 상품 이미지 목록 (각 항목: hash·url·alt_text·is_thumbnail·sort_order 등, images 관계 로드 시) |
 | thumbnail_url | string | `/api/modules/sirsoft-ecommerce/produc…` | thumbnail URL |
 | meta_title | null | `null` | SEO 제목 (다국어 JSON) |
-| meta_description | null | `null` | SEO 설명 (다국어 JSON) |
+| meta_description | object | `{"ko":"면 손수건 3매입 #1 의 직접 입력 SEO 설명입니다.","en":"Custom SEO …` | SEO 설명 (다국어 JSON) |
 | meta_keywords | null | `null` | SEO 키워드 (배열) |
 | has_options | boolean | `true` | options 여부 |
 | option_groups | array | `[{"name":{"ko":"색상","en":"Color"},"name_localized":"색상","…` | 옵션 그룹 정의: [{name: "색상", values: ["빨강", "파랑"]}] |
@@ -2500,7 +2540,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/products/1732/downloadable-coupons HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/products/{product}/downloadable-coupons HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2674,7 +2714,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/products/1732/inquiries?page=1&per_page=1&exclude_secret=1 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/products/{product}/inquiries HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2797,7 +2837,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-ecommerce/products/1732/inquiries HTTP/1.1
+POST /api/modules/sirsoft-ecommerce/products/{product}/inquiries HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2825,8 +2865,8 @@ Content-Type: application/json
 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-products.read`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -2856,7 +2896,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-ecommerce/products/1732/reviews?sort=created_at_desc&photo_only=0&page=1&per_page=1&rating=1&option_filters=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
+GET /api/modules/sirsoft-ecommerce/products/{product}/reviews?sort=created_at_desc&photo_only=0&page=1&per_page=1&rating=1&option_filters=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
@@ -2974,8 +3014,8 @@ HTTP/1.1 200
 | 상태코드 | 의미 | 발생 조건 |
 | --- | --- | --- |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-products.read`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -514,8 +514,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.promotion-coupon.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -565,8 +565,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.promotion-coupon.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -613,8 +613,8 @@ Authorization: Bearer {YOUR_TOKEN}
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.promotion-coupon.read`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -65,7 +65,7 @@ _목록 응답: `data.data[]` 배열 항목의 필드._
 | user_id | string | `a231747f-e82e-4cf2-9ae1-a261849dce40` | user 식별자 (연관 리소스 참조) |
 | user | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 작성자 정보 (uuid·name·email, `user` 관계 로드 시) |
 | product | object | `{"id":320,"name":"API 문서 샘플 상품","thumbnail_url":null}` | 리뷰 대상 상품 정보 (id·현지화 상품명·썸네일 URL) |
-| option_snapshot | null | `null` | 주문 시점 옵션 스냅샷 (옵션명 보존용) |
+| option_snapshot | string | `{"id":104,"option_code":"FWACBAVCBKCD…` | 주문 시점 옵션 스냅샷 (옵션명 보존용) |
 | option_snapshot_label | string | `` | `option_snapshot` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
 | rating | integer | `5` | 별점 (1~5) |
 | content | string | `Molestiae repellendus accusantium omn…` | 리뷰 내용 |
@@ -79,12 +79,12 @@ _목록 응답: `data.data[]` 배열 항목의 필드._
 | has_reply | boolean | `false` | reply 여부 |
 | has_reply_label | string | `미답변` | `has_reply` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
 | has_reply_badge_color | string | `gray` | 답변 여부 뱃지 색상 (답변완료=green / 미답변=gray) |
-| reply_content | null | `null` | 판매자 답변 내용 (없으면 null) |
+| reply_content | string | `소중한 리뷰 감사드립니다! 항상 최선을 다하겠습니다.` | 판매자 답변 내용 (없으면 null) |
 | reply_content_mode | string | `text` | 답변 콘텐츠 모드: text / html |
-| reply_admin_uuid | null | `null` | 답변 작성 관리자 UUID (`replyAdmin` 관계 로드 시) |
-| reply_admin | null | `null` | 답변 작성 관리자 정보 (uuid·name·email, `replyAdmin` 관계 로드 시) |
-| replied_at | null | `null` | replied 일시 |
-| reply_updated_at | null | `null` | reply updated 일시 |
+| reply_admin_uuid | string | `a2397737-f8da-4451-a9c0-2616e7cd2002` | 답변 작성 관리자 UUID (`replyAdmin` 관계 로드 시) |
+| reply_admin | object | `{"uuid":"a2397737-f8da-4451-a9c0-2616e7cd2002","name":"관리…` | 답변 작성 관리자 정보 (uuid·name·email, `replyAdmin` 관계 로드 시) |
+| replied_at | string | `2026-07-06 19:08:45` | replied 일시 |
+| reply_updated_at | string | `2026-07-07 19:08:45` | reply updated 일시 |
 | created_at | string | `2026-07-07 14:47:31` | 생성 일시 |
 | updated_at | string | `2026-07-07 14:47:31` | 최종 수정 일시 |
 | abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
@@ -273,7 +273,39 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `99` | 기본 키 (내부 식별자) |
+| product_id | integer | `320` | 상품 ID |
+| order_option_id | integer | `859` | 주문 옵션 ID |
+| user_id | string | `a231747f-e82e-4cf2-9ae1-a261849dce40` | 작성자 ID |
+| user | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 작성자 정보 (uuid·name·email, `user` 관계 로드 시) |
+| product | object | `{"id":320,"name":"API 문서 샘플 상품","thumbnail_url":null}` | 리뷰 대상 상품 정보 (id·현지화 상품명·썸네일 URL) |
+| option_snapshot | string | `{"id":104,"option_code":"FWACBAVCBKCD…` | 주문 시점 옵션 스냅샷 (옵션명 보존용) |
+| option_snapshot_label | string | `` | `option_snapshot` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| rating | integer | `5` | 별점 (1~5) |
+| content | string | `Molestiae repellendus accusantium omn…` | 리뷰 내용 |
+| content_mode | string | `text` | 콘텐츠 모드: text / html |
+| status | string | `visible` | 리뷰 상태: visible / hidden |
+| status_label | string | `전시중` | 상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
+| status_badge_color | string | `blue` | 상태 뱃지 색상 (visible=blue / hidden=gray) |
+| images | array | `[]` | 첨부 이미지 목록 (이미지 리소스 배열, `images` 관계 로드 시) |
+| image_count | integer | `0` | image 개수 (집계) |
+| orderOption | object | `{"id":859,"order_id":455,"order_number":"ORD-20260707-000…` | 리뷰가 연결된 주문 옵션 정보 (주문 ID·주문번호·수량·주문일) |
+| has_reply | boolean | `false` | reply 여부 |
+| has_reply_label | string | `미답변` | `has_reply` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| has_reply_badge_color | string | `gray` | 답변 여부 뱃지 색상 (답변완료=green / 미답변=gray) |
+| reply_content | null | `null` | 판매자 답변 내용 |
+| reply_content_mode | string | `text` | 답변 콘텐츠 모드: text / html |
+| reply_admin_uuid | null | `null` | 답변 작성 관리자 UUID (`replyAdmin` 관계 로드 시) |
+| reply_admin | null | `null` | 답변 작성 관리자 정보 (uuid·name·email, `replyAdmin` 관계 로드 시) |
+| replied_at | null | `null` | replied 일시 |
+| reply_updated_at | null | `null` | reply updated 일시 |
+| created_at | string | `2026-07-07 14:47:31` | 생성 일시 |
+| updated_at | string | `2026-07-07 14:47:31` | 최종 수정 일시 |
+| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |

 **응답 예시**

@@ -315,7 +347,33 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `1` | 기본 키 (내부 식별자) |
+| product_id | integer | `1` | product 식별자 (연관 리소스 참조) |
+| order_option_id | integer | `1` | order option 식별자 (연관 리소스 참조) |
+| user_id | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | user 식별자 (연관 리소스 참조) |
+| user | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"AP…` | 대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
+| option_snapshot | string | `{"id":104,"option_code":"FWACBAVCBKCD…` | 주문 시점 옵션 스냅샷 (옵션명 보존용) |
+| option_snapshot_label | string | `` | `option_snapshot` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| rating | integer | `5` | 별점 (1~5) |
+| content | string | `Alias quas iusto dolorem eum eveniet …` | 본문 내용 |
+| content_mode | string | `text` | 콘텐츠 모드: text / html |
+| status | string | `visible` | 상태 값 (도메인별 상태 집합 — 사람이 읽는 라벨은 status_label, UI 변형은 status_variant 참조) |
+| status_label | string | `전시중` | 상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
+| status_badge_color | string | `blue` | 상태 뱃지 색상 (visible=blue / hidden=gray) |
+| has_reply | boolean | `false` | reply 여부 |
+| has_reply_label | string | `미답변` | `has_reply` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| has_reply_badge_color | string | `gray` | 답변 여부 뱃지 색상 (답변완료=green / 미답변=gray) |
+| reply_content | null | `null` | 판매자 답변 내용 |
+| reply_content_mode | string | `text` | 답변 콘텐츠 모드: text / html |
+| replied_at | null | `null` | replied 일시 |
+| reply_updated_at | null | `null` | reply updated 일시 |
+| created_at | string | `2026-07-08 10:44:49` | 생성 일시 |
+| updated_at | string | `2026-07-08 10:44:49` | 최종 수정 일시 |
+| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |

 **응답 예시**

@@ -367,7 +425,33 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| id | integer | `1` | 기본 키 (내부 식별자) |
+| product_id | integer | `1` | product 식별자 (연관 리소스 참조) |
+| order_option_id | integer | `1` | order option 식별자 (연관 리소스 참조) |
+| user_id | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | user 식별자 (연관 리소스 참조) |
+| user | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"AP…` | 대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
+| option_snapshot | string | `{"id":104,"option_code":"FWACBAVCBKCD…` | 주문 시점 옵션 스냅샷 (옵션명 보존용) |
+| option_snapshot_label | string | `` | `option_snapshot` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| rating | integer | `5` | 별점 (1~5) |
+| content | string | `Alias quas iusto dolorem eum eveniet …` | 본문 내용 |
+| content_mode | string | `text` | 콘텐츠 모드: text / html |
+| status | string | `visible` | 상태 값 (도메인별 상태 집합 — 사람이 읽는 라벨은 status_label, UI 변형은 status_variant 참조) |
+| status_label | string | `전시중` | 상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
+| status_badge_color | string | `blue` | 상태 뱃지 색상 (visible=blue / hidden=gray) |
+| has_reply | boolean | `true` | reply 여부 |
+| has_reply_label | string | `답변완료` | `has_reply` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
+| has_reply_badge_color | string | `green` | 답변 여부 뱃지 색상 (답변완료=green / 미답변=gray) |
+| reply_content | string | `실측 예시값` | 판매자 답변 내용 |
+| reply_content_mode | string | `text` | 답변 콘텐츠 모드: text / html |
+| replied_at | string | `2026-07-08 15:00:32` | replied 일시 |
+| reply_updated_at | null | `null` | reply updated 일시 |
+| created_at | string | `2026-07-08 10:44:49` | 생성 일시 |
+| updated_at | string | `2026-07-08 15:00:32` | 최종 수정 일시 |
+| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |

 **응답 예시**

@@ -379,8 +463,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.reviews.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -430,8 +514,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.reviews.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -622,8 +706,8 @@ Content-Type: application/octet-stream
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-reviews.write`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -654,11 +738,29 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
+_단건 응답: `data` 객체의 필드._
+
+| 필드 | 타입 | 실측 예시값 | 용도/설명 |
+| --- | --- | --- | --- |
+| deleted | boolean | `true` | 삭제 처리 성공 여부 (true 이면 리뷰와 첨부 이미지가 제거됨) |

 **응답 예시**

-<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
+<!-- @probed -->
+
+```http
+HTTP/1.1 200
+```
+
+```json
+{
+    "success": true,
+    "message": "리뷰 이미지가 삭제되었습니다.",
+    "data": {
+        "deleted": true
+    }
+}
+```

 **에러 응답**

@@ -8,7 +8,7 @@

 ```text
 1. 이 문서는 실제 API 호출로 실측한 Settings 엔드포인트 레퍼런스입니다
-2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
+2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
 3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
 4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
 5. 설명(TODO) 칸은 사람이 채웁니다
@@ -422,15 +422,90 @@ HTTP/1.1 200
 | --- | --- | --- | --- | --- | --- |
 | _tab | body | string | 아니오 | `basic_info`, `language_currency`, `seo`, `order_settings`, `claim`, `shipping`, `review_settings`, `notification_definitions`, `notifications`, `inquiry`, `mileage` | 저장할 설정 탭(카테고리) 지정 (탭별 부분 저장 식별용) |
 | notifications | body | array | 아니오 | — | 알림 채널 설정 배열 (채널 ID·활성 여부·정렬 순서) |
+| notifications.channels | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | basic_info | body | array | 아니오 | — | 쇼핑몰 기본 정보 섹션 (쇼핑몰명·라우트 경로·상호·사업자번호·주소·연락처 등) |
+| basic_info.shop_name | body | string | 아니오 | max 255 | basic info.shop 이름 (식별자) |
+| basic_info.route_path | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
+| basic_info.no_route | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| basic_info.company_name | body | string | 아니오 | max 255 | basic info.company 이름 (식별자) |
+| basic_info.business_number_1 | body | string | 아니오 | max 3 | <!-- TODO: 용도 --> |
+| basic_info.business_number_2 | body | string | 아니오 | max 2 | <!-- TODO: 용도 --> |
+| basic_info.business_number_3 | body | string | 아니오 | max 5 | <!-- TODO: 용도 --> |
+| basic_info.ceo_name | body | string | 아니오 | max 100 | basic info.ceo 이름 (식별자) |
+| basic_info.business_type | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
+| basic_info.business_category | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| basic_info.zipcode | body | string | 아니오 | max 10 | <!-- TODO: 용도 --> |
+| basic_info.base_address | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| basic_info.detail_address | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| basic_info.phone_1 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.phone_2 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.phone_3 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.fax_1 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.fax_2 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.fax_3 | body | string | 아니오 | max 4 | <!-- TODO: 용도 --> |
+| basic_info.email_id | body | string | 아니오 | max 100 | basic info.email 식별자 |
+| basic_info.email_domain | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
+| basic_info.privacy_officer | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
+| basic_info.privacy_officer_email | body | email | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| basic_info.mail_order_number | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
+| basic_info.telecom_number | body | string | 아니오 | max 100 | <!-- TODO: 용도 --> |
 | language_currency | body | array | 아니오 | — | 통화 설정 섹션 (기본 통화·통화 목록: 코드·다국어명·환율·반올림 규칙·통화별 로케일) |
+| language_currency.default_currency | body | string | 아니오 | max 10 | <!-- TODO: 용도 --> |
+| language_currency.currencies | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | seo | body | array | 아니오 | — | SEO 메타 설정 섹션 (페이지 유형별 메타 타이틀/설명·SEO 활성 토글) |
+| seo.meta_category_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_category_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.meta_search_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_search_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.meta_product_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_product_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.meta_shop_index_title | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo.meta_shop_index_description | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| seo.seo_category | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| seo.seo_search_result | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| seo.seo_product_detail | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| seo.seo_shop_index | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
 | inquiry | body | array | 아니오 | — | 문의 연동 설정 섹션 (문의 게시판 slug) |
+| inquiry.board_slug | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
 | order_settings | body | array | 아니오 | — | 주문/결제 설정 섹션 (기본 PG·결제수단·은행/무통장 계좌·자동취소·장바구니 만료 등) |
+| order_settings.default_pg_provider | body | string | 아니오 | max 50 | <!-- TODO: 용도 --> |
+| order_settings.cash_receipt_provider | body | string | 아니오 | max 50 | <!-- TODO: 용도 --> |
+| order_settings.cash_receipt_self_issue | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.shipping_fee_tax_policy | body | string | 아니오 | `proportional`, `taxable`, `follow_main_item` | <!-- TODO: 용도 --> |
+| order_settings.payment_methods | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.banks | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.bank_accounts | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.auto_cancel_expired | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.auto_cancel_days | body | integer | 아니오 | min 0, max 30 | <!-- TODO: 용도 --> |
+| order_settings.cart_expiry_days | body | integer | 아니오 | min 1, max 365 | <!-- TODO: 용도 --> |
+| order_settings.stock_restore_on_cancel | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| order_settings.confirmable_statuses | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | claim | body | array | 아니오 | — | 클레임 설정 섹션 (환불 사유 목록, DB 동기화 대상으로 분리 저장) |
+| claim.refund_reasons | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | review_settings | body | array | 아니오 | — | 리뷰 정책 섹션 (작성 기한일·이미지 최대 개수·이미지 최대 용량 MB) |
+| review_settings.write_deadline_days | body | integer | 아니오 | min 1, max 365 | <!-- TODO: 용도 --> |
+| review_settings.max_images | body | integer | 아니오 | min 0, max 20 | <!-- TODO: 용도 --> |
+| review_settings.max_image_size_mb | body | integer | 아니오 | min 1, max 50 | <!-- TODO: 용도 --> |
 | mileage | body | array | 아니오 | — | 마일리지 설정 섹션 (사용 여부·기본 적립률·적립 트리거·통화별 규칙·소멸/소멸 알림) |
+| mileage.enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| mileage.default_earn_rate | body | number | 아니오 | min 0, max 100 | <!-- TODO: 용도 --> |
+| mileage.earn_trigger | body | string | 아니오 | `delivered`, `confirmed` | <!-- TODO: 용도 --> |
+| mileage.earn_delay_days | body | integer | 아니오 | min 0, max 365 | <!-- TODO: 용도 --> |
+| mileage.currency_rules | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| mileage.expiry_enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| mileage.expiry_days | body | integer | 아니오 | min 1, max 3650 | <!-- TODO: 용도 --> |
+| mileage.expiry_notification_enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| mileage.expiry_notification_days_before | body | integer | 아니오 | min 1, max 365 | <!-- TODO: 용도 --> |
 | shipping | body | array | 아니오 | — | 배송 설정 섹션 (기본 국가·배송 가능 국가·무료배송·배송사(carriers)·배송유형(types) — carriers/types는 DB 동기화 대상으로 분리 저장) |
+| shipping.default_country | body | string | 아니오 | max 10 | <!-- TODO: 용도 --> |
+| shipping.available_countries | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| shipping.international_shipping_enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| shipping.free_shipping_threshold | body | integer | 아니오 | min 0 | <!-- TODO: 용도 --> |
+| shipping.free_shipping_enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| shipping.address_validation_enabled | body | boolean | 아니오 | — | <!-- TODO: 용도 --> |
+| shipping.address_api_provider | body | string | 아니오 | max 50 | <!-- TODO: 용도 --> |
+| shipping.carriers | body | array | 아니오 | — | <!-- TODO: 용도 --> |
+| shipping.types | body | array | 아니오 | — | <!-- TODO: 용도 --> |

 **요청 예시**

@@ -446,32 +521,129 @@ Content-Type: application/json
    "notifications": [
        "예시값"
    ],
+    "notifications.channels": [
+        "예시값"
+    ],
    "basic_info": [
        "예시값"
    ],
+    "basic_info.shop_name": "예시 이름",
+    "basic_info.route_path": "예시값",
+    "basic_info.no_route": true,
+    "basic_info.company_name": "예시 이름",
+    "basic_info.business_number_1": "예시값",
+    "basic_info.business_number_2": "예시값",
+    "basic_info.business_number_3": "예시값",
+    "basic_info.ceo_name": "예시 이름",
+    "basic_info.business_type": "예시값",
+    "basic_info.business_category": "예시값",
+    "basic_info.zipcode": "06234",
+    "basic_info.base_address": "서울특별시 강남구 테헤란로 1",
+    "basic_info.detail_address": "서울특별시 강남구 테헤란로 1",
+    "basic_info.phone_1": "010-1234-5678",
+    "basic_info.phone_2": "010-1234-5678",
+    "basic_info.phone_3": "010-1234-5678",
+    "basic_info.fax_1": "예시값",
+    "basic_info.fax_2": "예시값",
+    "basic_info.fax_3": "예시값",
+    "basic_info.email_id": "user@example.com",
+    "basic_info.email_domain": "user@example.com",
+    "basic_info.privacy_officer": "예시값",
+    "basic_info.privacy_officer_email": "user@example.com",
+    "basic_info.mail_order_number": "예시값",
+    "basic_info.telecom_number": "예시값",
    "language_currency": [
        "예시값"
    ],
+    "language_currency.default_currency": "예시값",
+    "language_currency.currencies": [
+        "예시값"
+    ],
    "seo": [
        "예시값"
    ],
+    "seo.meta_category_title": "예시 제목",
+    "seo.meta_category_description": "예시 내용입니다.",
+    "seo.meta_search_title": "예시 제목",
+    "seo.meta_search_description": "예시 내용입니다.",
+    "seo.meta_product_title": "예시 제목",
+    "seo.meta_product_description": "예시 내용입니다.",
+    "seo.meta_shop_index_title": "예시 제목",
+    "seo.meta_shop_index_description": "예시 내용입니다.",
+    "seo.seo_category": true,
+    "seo.seo_search_result": true,
+    "seo.seo_product_detail": true,
+    "seo.seo_shop_index": true,
    "inquiry": [
        "예시값"
    ],
+    "inquiry.board_slug": "example-key",
    "order_settings": [
        "예시값"
    ],
+    "order_settings.default_pg_provider": "예시값",
+    "order_settings.cash_receipt_provider": "예시값",
+    "order_settings.cash_receipt_self_issue": true,
+    "order_settings.shipping_fee_tax_policy": "proportional",
+    "order_settings.payment_methods": [
+        "예시값"
+    ],
+    "order_settings.banks": [
+        "예시값"
+    ],
+    "order_settings.bank_accounts": [
+        "예시값"
+    ],
+    "order_settings.auto_cancel_expired": true,
+    "order_settings.auto_cancel_days": 1,
+    "order_settings.cart_expiry_days": 1,
+    "order_settings.stock_restore_on_cancel": true,
+    "order_settings.confirmable_statuses": [
+        "예시값"
+    ],
    "claim": [
        "예시값"
    ],
+    "claim.refund_reasons": [
+        "예시값"
+    ],
    "review_settings": [
        "예시값"
    ],
+    "review_settings.write_deadline_days": 1,
+    "review_settings.max_images": 1,
+    "review_settings.max_image_size_mb": 1,
    "mileage": [
        "예시값"
    ],
+    "mileage.enabled": true,
+    "mileage.default_earn_rate": 1,
+    "mileage.earn_trigger": "delivered",
+    "mileage.earn_delay_days": 1,
+    "mileage.currency_rules": [
+        "예시값"
+    ],
+    "mileage.expiry_enabled": true,
+    "mileage.expiry_days": 1,
+    "mileage.expiry_notification_enabled": true,
+    "mileage.expiry_notification_days_before": 1,
    "shipping": [
        "예시값"
+    ],
+    "shipping.default_country": "KR",
+    "shipping.available_countries": [
+        "KR"
+    ],
+    "shipping.international_shipping_enabled": true,
+    "shipping.free_shipping_threshold": 1,
+    "shipping.free_shipping_enabled": true,
+    "shipping.address_validation_enabled": true,
+    "shipping.address_api_provider": "서울특별시 강남구 테헤란로 1",
+    "shipping.carriers": [
+        "예시값"
+    ],
+    "shipping.types": [
+        "예시값"
    ]
 }
 ```
@@ -489,8 +489,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.settings.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -506,7 +506,17 @@ Content-Type: application/json
 | endpoint | body | string | 예 | max 500 | 테스트로 호출할 외부 배송비 계산 API 엔드포인트 URL. 내부 네트워크 주소(사설 IP·루프백·`localhost`·`*.internal` 등)와 userinfo(`https://a@b/`) 위장 주소는 422 로 거부됩니다 — 이 주소는 쇼핑몰 서버가 대신 호출하므로 내부망 접근을 막기 위함(SSRF). 사내 배송비 계산 서버를 쓰려면 코어 환경설정의 `security.allow_internal_outbound_urls` 를 켜세요 |
 | request_fields | body | array | 아니오 | — | 요청에 실어 보낼 필드명 목록 (후보 SSoT ShippingApiRequestField 5종) |
 | config | body | array | 아니오 | — | API 호출 고급 설정 (HTTP 메서드·인증방식·필드 매핑·응답 형식/경로 등) |
+| config.http_method | body | string | 아니오 | — | <!-- TODO: 용도 --> |
+| config.auth_type | body | string | 아니오 | — | <!-- TODO: 용도 --> |
+| config.auth_token | body | string | 아니오 | max 1000 | <!-- TODO: 용도 --> |
+| config.auth_header_name | body | string | 아니오 | max 100 | config.auth header 이름 (식별자) |
+| config.response_type | body | string | 아니오 | — | <!-- TODO: 용도 --> |
+| config.response_path | body | string | 아니오 | max 200 | <!-- TODO: 용도 --> |
+| config.field_map | body | array | 아니오 | — | <!-- TODO: 용도 --> |
 | sample | body | array | 아니오 | — | 테스트 계산에 사용할 샘플 주문 데이터 (무게/금액/수량 등) |
+| sample.group_total | body | number | 아니오 | min 0 | <!-- TODO: 용도 --> |
+| sample.total_quantity | body | integer | 아니오 | min 0 | <!-- TODO: 용도 --> |
+| sample.country_code | body | string | 아니오 | max 10 | <!-- TODO: 용도 --> |

 **요청 예시**

@@ -525,9 +535,21 @@ Content-Type: application/json
    "config": [
        "예시값"
    ],
+    "config.http_method": "예시값",
+    "config.auth_type": "예시값",
+    "config.auth_token": "{YOUR_TOKEN}",
+    "config.auth_header_name": "예시 이름",
+    "config.response_type": "예시값",
+    "config.response_path": "예시값",
+    "config.field_map": [
+        "예시값"
+    ],
    "sample": [
        "예시값"
-    ]
+    ],
+    "sample.group_total": 1,
+    "sample.total_quantity": 1,
+    "sample.country_code": "KR"
 }
 ```

@@ -691,8 +713,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.shipping-policies.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -33,7 +33,7 @@
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-ecommerce/admin/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4/currency HTTP/1.1
+PATCH /api/modules/sirsoft-ecommerce/admin/users/{user}/currency HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -58,8 +58,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-currency.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -82,7 +82,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-ecommerce/admin/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4/shipping-country HTTP/1.1
+PATCH /api/modules/sirsoft-ecommerce/admin/users/{user}/shipping-country HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -123,8 +123,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-ecommerce.user-shipping-country.manage`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -8,8 +8,8 @@

 ```text
 1. 이 문서는 실제 API 호출로 실측한 Attachments 엔드포인트 레퍼런스입니다
-2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
-3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
+2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
+3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
 4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
 5. 설명(TODO) 칸은 사람이 채웁니다
 ```
@@ -63,7 +63,7 @@ Content-Disposition: form-data; name="temp_key"

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -114,7 +114,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -156,7 +156,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -8,8 +8,8 @@

 ```text
 1. 이 문서는 실제 API 호출로 실측한 Pages 엔드포인트 레퍼런스입니다
-2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
-3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
+2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
+3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
 4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
 5. 설명(TODO) 칸은 사람이 채웁니다
 ```
@@ -158,6 +158,9 @@ HTTP/1.1 200
 | content_mode | body | string | 아니오 | `html`, `text` | 본문 편집 모드. `html` 은 리치 에디터 HTML, `text` 는 평문으로 저장·렌더링됩니다 (미지정 시 `html`) |
 | published | body | boolean | 아니오 | — | 발행 여부 (발행된 항목만 필터) |
 | seo_meta | body | array | 아니오 | — | SEO 메타 정보 맵. 하위 키 `title`(max 255)·`description`(max 500)·`keywords`(max 500)를 담습니다 |
+| seo_meta.title | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| seo_meta.description | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo_meta.keywords | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
 | temp_key | body | string | 아니오 | max 64 | 저장 전 첨부 업로드 시 발급받은 임시 키. 생성된 페이지에 임시 첨부를 귀속시키는 데 사용합니다 |

 **요청 예시**
@@ -180,13 +183,16 @@ Content-Type: application/json
    "seo_meta": [
        "예시값"
    ],
+    "seo_meta.title": "예시 제목",
+    "seo_meta.description": "예시 내용입니다.",
+    "seo_meta.keywords": "예시값",
    "temp_key": "예시값"
 }
 ```

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -237,7 +243,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -286,7 +292,7 @@ Content-Type: application/json

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -320,7 +326,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-DELETE /api/modules/sirsoft-page/admin/pages/10 HTTP/1.1
+DELETE /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -328,9 +334,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-
-
-<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -374,7 +378,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-page/admin/pages/10 HTTP/1.1
+GET /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -498,12 +502,15 @@ HTTP/1.1 200
 | content_mode | body | string | 아니오 | `html`, `text` | 본문 편집 모드. `html` 은 리치 에디터 HTML, `text` 는 평문으로 저장·렌더링됩니다 (미지정 시 `html`) |
 | published | body | boolean | 아니오 | — | 발행 여부 (발행된 항목만 필터) |
 | seo_meta | body | array | 아니오 | — | SEO 메타 정보 맵. 하위 키 `title`(max 255)·`description`(max 500)·`keywords`(max 500)를 담습니다 |
+| seo_meta.title | body | string | 아니오 | max 255 | <!-- TODO: 용도 --> |
+| seo_meta.description | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
+| seo_meta.keywords | body | string | 아니오 | max 500 | <!-- TODO: 용도 --> |
 | temp_key | body | string | 아니오 | max 64 | 저장 전 첨부 업로드 시 발급받은 임시 키. 새로 업로드한 첨부를 이 페이지에 귀속시키는 데 사용합니다 |

 **요청 예시**

 ```http
-PUT /api/modules/sirsoft-page/admin/pages/10 HTTP/1.1
+PUT /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -520,17 +527,20 @@ Content-Type: application/json
    "seo_meta": [
        "예시값"
    ],
+    "seo_meta.title": "예시 제목",
+    "seo_meta.description": "예시 내용입니다.",
+    "seo_meta.keywords": "예시값",
    "temp_key": "예시값"
 }
 ```

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

-<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
+<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->

 **에러 응답**

@@ -538,8 +548,8 @@ Content-Type: application/json
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -562,7 +572,7 @@ Content-Type: application/json
 **요청 예시**

 ```http
-PATCH /api/modules/sirsoft-page/admin/pages/10/publish HTTP/1.1
+PATCH /api/modules/sirsoft-page/admin/pages/{page}/publish HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -641,8 +651,8 @@ HTTP/1.1 200
 | --- | --- | --- |
 | 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
 | 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없는 경우 |
-| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
 | 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
+| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |

 <!-- @generated:end -->

@@ -664,7 +674,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-page/admin/pages/10/versions HTTP/1.1
+GET /api/modules/sirsoft-page/admin/pages/{page}/versions HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -771,7 +781,7 @@ HTTP/1.1 200
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-page/admin/pages/10/versions/{versionId} HTTP/1.1
+GET /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -814,7 +824,7 @@ Authorization: Bearer {YOUR_TOKEN}
 **요청 예시**

 ```http
-POST /api/modules/sirsoft-page/admin/pages/10/versions/{versionId}/restore HTTP/1.1
+POST /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId}/restore HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}
@@ -822,7 +832,7 @@ Authorization: Bearer {YOUR_TOKEN}

 **응답 필드** (`data` 내부)

-<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
+<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->

 **응답 예시**

@@ -936,7 +946,7 @@ Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생
 **요청 예시**

 ```http
-GET /api/modules/sirsoft-page/pages/terms HTTP/1.1
+GET /api/modules/sirsoft-page/pages/{slug} HTTP/1.1
 Host: api.example.com
 Accept: application/json
 Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)