문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.
| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |
고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
(tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
src/contracts/api-operations.ts:9,25-27,112-125,142-190,
src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
(boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
src/adapters/http/request-builder.ts:129-135(V2만 읽음),
src/contracts/external-contract-runtime.ts:33,
src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
(src/adapters/http/feature-http-binding.ts:272-273,
src/adapters/http/http-execution-v3.ts:248-254,653-655,
src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
(src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
(실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
(http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
(src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
(src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
(http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
(reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.
남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).
검증:
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
request:start는 msw 타입에서 확인