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(멱등).

docs/backend/api-documentation.md

@@ -123,12 +123,29 @@ README.md "API 레퍼런스"  또는  AGENTS.md "API 레퍼런스 진입점" 표
 | --- | --- |
 | 파라미터 표 `용도` 셀 | 행 키(이름+위치)로 대조. 기존 값이 TODO 스텁이 아니면 유지 |
 | 응답 필드 표 `용도/설명` 셀 | 행 키(필드)로 대조. 기존 값이 TODO 스텁이 아니면 유지 |
+| 응답 필드 표 `실측 예시값` 열 | 같은 필드의 타입이 그대로면 기존 값 유지. 타입이 바뀌면(스펙 변경) 새 실측값 채택. 기존에 없던 신규 필드는 새 값 사용 |
 | 응답 필드 본문 (실측 실패로 마커만 남은 자리) | 사람이 채웠으면 유지 |
 | 응답 예시 본문 | 실측 산출물에는 `<!-- @probed -->` 출처 마커가 붙는다. 마커가 없으면 사람 작성분으로 보고 유지 |
+| 응답 예시 JSON (양쪽 다 실측 산출물) | 응답의 **키 구조**가 같으면 기존 예시 유지. 필드 집합이 달라지면 새 실측 예시 채택 |
+| 응답 예시·응답 필드 (이번 실측이 실패) | 기존이 실측 산출물이면 그대로 유지 (마커로 덮지 않는다) |
+| 에러 응답 표 | 상태코드 키 단위 병합. 사람이 추가한 행(도메인 특이 에러)은 살리고, 자동 추론에만 있는 상태코드는 편입. 같은 상태코드는 기존 행 우선 |
 
 `@probed` 마커가 필요한 이유: 실측은 1회 호출이 관측한 표본 하나뿐이라, 사람이 코드를 읽고 쓴 사실
 (성공 케이스와 엣지 케이스를 함께 제시하는 등)보다 좁다. 실측 결과는 기본값이지 덮어쓰기 권한이 아니다.
 
+**재생성은 멱등해야 한다.** 실측값은 호출 시점 DB 상태가 낳은 표본이라, 그대로 반영하면 코드가 하나도
+바뀌지 않은 문서까지 재실행마다 diff 가 난다(`id` 예시값, `updated_at`, `cache_version` 등). 그래서
+값이 아니라 **스펙**(필드 집합·타입)이 바뀐 경우에만 갱신한다. 같은 이유로 요청 예시의 path 파라미터는
+실측 치환값(`/brands/1`)이 아니라 라우트 정의의 placeholder(`/brands/{brand}`)로 고정한다 — 실측
+성패에 따라 예시가 흔들리지 않아야 한다.
+
+실측 실패(`실측 제외: ...`)는 "새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
+실측 성패는 호출 시점 데이터 유무에 좌우된다(예: `DELETE /checkout` 은 삭제할 체크아웃이 없으면 404).
+따라서 실측 실패가 기존 실측 결과를 지우지 않는다.
+
+nullable 필드는 표본에 값이 있느냐에 따라 관측 타입이 흔들린다(`loggable_type` 이 string ↔ null).
+`null` 관측은 타입 변경이 아니라 "이번 표본에 값이 없었다" 는 뜻이므로, 기존에 관측한 실제 값을 유지한다.
+
 에러 응답 표는 라우트 메타에서 대표 상태코드를 자동 추론한다: 인증 필수(`auth:sanctum`)→401,
 `admin`/`permission:` 요구→403, FormRequest 검증 규칙 존재→422, path 파라미터 존재→404.
 `optional.sanctum`(선택 인증)은 401 을 유발하지 않는다. 도메인 특이 에러(409·429 등)는 사람이 보강한다.