45e8cb774c5dd4e052f72cd4bc2fe3694472ac74
91
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
e632b230e3 |
docs: 옮긴 문서를 가리키는 링크와 경로를 새 위치로 고친다
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을 가리킨다. 고른 방법: 기계적으로 바꾼다. - 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고, 대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다. 옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은 링크 대상뿐이다(백엔드 1단계와 같은 예외). - 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`, `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과 CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와 review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토 작업 공간의 출처 표시라 그대로 둔다. 위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는 없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다. 검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록, CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시 쓴다) 밖에서 0건. |
||
|
|
e3c8db48ae |
chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로 템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다. 참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록 7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트 참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은 비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을 하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다. 기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로 옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플 경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다. 레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약 기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능 539B, context 4B)을 다시 받았다. 위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은 수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에 공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는 플랫폼 코드에 남았다. 검증(desktop): check:types, lint, check:architecture, check:registries, check:ci, verify:documentation, test:unit, test:component, test:contract, test:integration, test:recipes, test:coverage(Risk coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual, test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76 checks), test:sample-removal SKIP, build, check:bundle. |
||
|
|
b41990cdd5 |
fix(query): 재전송 거절의 결과 불명 해제를 짝 백엔드 표 code로만 정한다
문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를 보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는 선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고 (scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와 상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이 선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과 불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로 남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지 않았다(최종 리뷰 FR-01). 고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일 때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400 IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind 줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는 상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400 VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다. 테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED + 선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다. 참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과 불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이 다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과 불명과 확인 버튼이 남는 테스트를 더했다. 버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지 폼과 훅에 알리지 않는다). 위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송 뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1 X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/features/reference-feature/reference-page.test.tsx tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용 Refs: 1106/03-01 (final review FR-01) |
||
|
|
80e7f1d63a |
fix(query): 같은 요청이 매번 받는 거절로 끝난 재전송은 결과 불명을 푼다
문제: 1106/03-01( |
||
|
|
815ea58e80 |
fix(query): IDEMPOTENT 쓰기는 결과 불명 뒤에도 다시 보낼 수 있게 한다
문제: 0929/03-03의 두 가드(재전송 버튼 canResend, 같은 입력 재제출 거절)가 intent의 키 유무로만 가른다. 뮤테이션 정책은 키 여부만 실어서 훅이 NEVER와 IDEMPOTENT를 가를 수 없다. 그래서 IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)도 결과 불명 뒤 재전송 버튼이 없고 같은 입력 저장이 UNKNOWN_EFFECT_PENDING으로 거절된다. 출구는 사실을 모르는 "변경됨으로 확인"이나 새로고침뿐이다. 매뉴얼은 IDEMPOTENT를 "여러 번 적용해도 결과가 같다"로 적고, 실행기도 보낸 뒤에 다시 보낸다. 고른 방법(리뷰 03-03 대안 (a)): commandMutationIdentity가 resendSafe (KEYED 또는 IDEMPOTENT)를 함께 준다. BoundMutation에 선택 칸 resendSafe를 더했다(추가만). 훅은 admission마다 resendable(키가 있거나 정책이 resendSafe)을 적고, 두 가드가 키 대신 그 값을 본다. 칸이 없는 손으로 쓴 정책은 지금처럼 키 유무로 간다. NEVER의 재전송 금지와 같은 입력 거절은 그대로다. 매뉴얼 01·02와 런북 6.3-4에 IDEMPOTENT 행을 적었다. 버린 대안: 문서만 고치기(회복 경로가 그대로 불편하다), IDEMPOTENT에도 키를 붙이기(백엔드가 키를 읽지 않으면 의미가 없고 실행기가 UNEXPECTED_IDEMPOTENCY_KEY로 거절한다). 위험·한계: commandMutationIdentity의 반환 객체에 칸이 하나 늘었다. 그 값을 toEqual로 비교하던 테스트는 칸을 더해야 한다(이 repo는 1곳을 고쳤다). IDEMPOTENT로 잘못 선언한 쓰기(백엔드가 실제로는 중복을 막지 못함)는 이제 결과 불명 뒤 사용자가 다시 보낼 수 있다. 선언의 정확성은 기능 작성자 몫이다(02 결정표 3절). 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다. CHANGELOG 행은 문서 담당이 적는다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/unit/command-mutation-identity.test.ts Refs: 1106/03-03 |
||
|
|
25685871f1 |
fix(query): 쓰기 전에 거절된 같은 키 재전송 뒤에도 결과 불명과 키를 지킨다
문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전
거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패
(NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서
결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로
나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는
그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에
새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2).
고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)):
- 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그
intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와
같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신
markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외
(.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은
결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의
성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다.
- 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서
unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구
하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를
formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로
저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이
그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를
받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로
미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다.
버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가
남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성
기능만 덮는다).
위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시
보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은
입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를
보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금
늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에
적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1.
Refs: 1106/03-01
|
||
|
|
b8d53c9aae |
chore(review): 1105 성능·구조 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘. - 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가 `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해 빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`, `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다. 1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로 옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에 `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면 `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고, 임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로 실패한다. - `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정 브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01 |
||
|
|
45c9c4dc48 |
chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나. - 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`· `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에 옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에 두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the answers from the backend table rows at the pin"이 "is both copied and listed in notCopied"로 실패한다. - pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*` 둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다. - `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게 푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts Refs: 1105/03-02, 1105/07-01 |
||
|
|
57c34ea626 | chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 | ||
|
|
12d97d7469 |
feat(forms): 기능이 백엔드 거절 code에 자기 문구를 붙인다
문제 refusedBeforeWrite로 선언한 업무 거절은 이제 결과 불명이 아니고 다시 저장된다. 그런데 거절 이유가 사용자 말로 보이지 않는다. 선언한 400은 kind UNKNOWN_CLIENT_FAILURE라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이고, 409는 kind CONFLICT라 "다른 변경과 충돌했습니다."다. 고칠 수 있는 입력인데 지원 문의로 보낸다. mapProblem으로 필드 오류를 만들어도 문구는 플랫폼 표에서 issue code로만 고르므로(표에 없는 DUPLICATE는 "입력값을 확인해 주세요.") 기능이 *_ALREADY_EXISTS 같은 거절에 자기 문구를 붙일 자리가 없다(리뷰 08-R1 A1~A3). conflict 결과에서는 form.failure가 null이라 페이지가 code를 읽어 따로 그릴 수도 없다. 고른 방법 useAppForm에 refusalMessages 옵션을 더한다. 실패 code별로 기능 catalog의 메시지 키와(선택) 필드를 적는다. 적용 안 됨(effect NOT_APPLIED)으로 끝난 실패의 code가 있으면 그 문구를 필드 오류로(필드가 없거나 allowedServerFields 밖이면 오류 요약으로) 보이고 결과를 validation-error로 둔다. 필드면 그 필드로 포커스를 옮긴다. 키는 렌더 때 번역한다(다른 폼 오류와 같다). Object.hasOwn으로 자기 키만 읽는다(1103/08-03). 재로그인(action reauth)이 먼저다. 결과 불명은 code와 상관없이 결과 불명이다. 매뉴얼 02 4절에 적었다. 버린 대안 - 플랫폼 문구 표(form-contracts.ts)에 code를 더한다: 기능 code를 템플릿 파일에 적게 된다. - mapProblem이 문구까지 돌려주게 한다: 어댑터가 presentation 메시지 키를 알게 된다. - 지난 리뷰 5.3절 (B)(useAppForm이 코디네이터 상태를 받아 결과를 하나로 낸다): 더 넓은 구조 변경이라 이 커밋에서 하지 않았다. 위험·한계 - 1103/03-01 남은 부분 중 이 커밋은 "이유 문구와 기능 문구 자리"만 고친다. KEYED 결과 불명의 같은 키 재전송이 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받아도 재전송 버튼이 남는 것(08-R1 A5)은 결정 대기로 남긴다. 백엔드 §2는 이 답에 "같은 키 재전송은 안전하다, 첫 시도가 늦게 끝났으면 그 결과를 재생한다"고 적고 답 표 사본도 sameKeyResend: true다. 버튼을 거두면 그 회복 길도 닫힌다. 고르는 사람: 프론트 템플릿 담당(frontend-platform). 선택지: (a) RECOVERY_REQUIRED 뒤 재전송을 거두고 "목록에서 확인" 안내를 둔다(AppFailure에 답의 원인을 싣는 계약 추가 필요), (b) 백엔드가 KEYED 작업 안의 업무 예외(트랜잭션 롤백)를 "효과 없음" 으로 기록해 같은 키 재전송이 다시 실행되게 한다(백엔드 변경), (c) 지금대로 둔다 (재전송은 안전하고, 참조 폼은 목록 새로 보기 링크가 있다). - 선언하지 않은 code는 지금처럼 결과 불명이고 "변경됨으로 확인"이 남는다(완료 기준의 설계). 참조 기능과 생성기는 이 옵션을 쓰지 않는다. 생성기는 이미 <FEATURE>_INVALID를 필드 오류로 보인다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx Refs: 1103/03-01 |
||
|
|
683ccfb56b |
fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제 0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다. - useApplicationMutation의 submit은 같은 canonical input의 결과 불명 admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면 서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과 두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은 항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이 두 번째 POST를 보냈고 keys=[null,null]). - AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을 그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을 그린다(실험 X3). 고른 방법 - submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면 보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를 돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다. KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트 하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다. - AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다. 코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect). - 기존 async-surface 테스트 "renders unknown mutation effects with confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이 수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다. - 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다. 버린 대안 FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다. "같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로 충분하다. 위험·한계 - 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를 넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다. - 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다 (런북 6.3-7의 한계 그대로). 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/component/async-surface.test.tsx tests/component/application-query.test.tsx Refs: 0929/03-03 |
||
|
|
138c195fcd |
fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지 릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로 바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래 section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift 16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는 hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느 게이트도 보지 않는다. 고른 방법: - 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합 다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다." / "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도 한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미 `main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던 대기가 값이 채워진 뒤로 유지된다. - lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값, context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls 임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다. - 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는 빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면 lab 판정이 실패한다. 버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기 포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 — CLS 정의와 달라져 field 값과 비교할 수 없다. 위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초) 늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은 shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은 lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어 "런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면 문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에 새 칸을 필수로 더했다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx tests/unit/performance-budgets.test.ts corepack pnpm build && corepack pnpm test:performance -- --runs=5 (lab.json metrics.targetDeepLinkCls가 0인지) Refs: 1105/15-01 |
||
|
|
48c1ab7ab6 |
fix(server-state)!: 손으로 적은 뮤테이션 operation ID를 타입 검사에서 막는다
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만 BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를 문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고, 저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로 거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다. 고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로 바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을 직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열 그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice 생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다. 템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts (commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로 바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다. 버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행 때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림 분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게 적재되는 계약 전체를 타입으로 모을 곳이 없다. 위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에 operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가 실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든 객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌 뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가 없다. 검증: desktop batch에서 확인. corepack pnpm check:types:test tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모 커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다. node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx BREAKING CHANGE: BoundMutation.operationId는 string이 아니라 MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)` 로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환 타입도 operationId가 MutationOperationId다. Refs: 1103/16-05 |
||
|
|
fdc1db9471 |
feat(bootstrap): 제품이 SW blockers·observe를 composeProduct로 넘긴다
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.
고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
벌 생긴다.
위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
(`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation
Refs: 1103/09-05
|
||
|
|
41f8801d64 |
chore(review): 1103 기능 생성기·기능 패턴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-07 09-06 16-01 16-04~16-07 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/reference/create-feature.md # docs/manual/reference/patterns.md # scripts/create-feature.ts # scripts/test-feature-scaffold.ts |
||
|
|
fbd8f7d148 |
chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/02-decision-tables.md # docs/manual/reference/patterns.md |
||
|
|
83f4dd5f8e |
chore(review): 1103 예제 화면·시각·접근성 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-04 15-01 12-01 11-01 16-03 11-02 # Conflicts: # docs/architecture/frontend-application-foundation.md # docs/architecture/starter-experience.md # docs/manual/03-outside-feature-folder.md # tests/unit/runtime-adapters.test.ts |
||
|
|
68f94f5e93 |
refactor(server-state): 아무도 읽지 않는 쿼리·뮤테이션 정의 칸을 선택 칸으로 둔다
문제 QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다. bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능 작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로 적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②). 고른 방법 세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는 채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다. 매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title· navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다. 버린 대안 - 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과 다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다. - 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의 operation ID를 싣는다. 같은 값을 두 번 싣는다. 위험·한계 - 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면 FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와 test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은 파일이라 이번에는 문서로만 적었다. 검증 - RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner· operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과. - tests/features/reference-feature, tests/unit/create-feature.test.ts, scope-fence 129건 통과. check:types(app·node·test), lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06 |
||
|
|
b96d61d8f7 |
feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
|
||
|
|
d549ceb330 |
perf(examples): 플랫폼 구성 화면이 제목을 먼저 그리고 실행부 표만 기다린다
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다.
|
||
|
|
6088f6e533 |
chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
c17b3a05d6 |
chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
1b1d972acd |
test(boot): 예상 밖 부팅 실패 테스트가 바꾼 전역 reportError를 되돌린다
문제 tests/component/boot-unexpected-failure.test.tsx는 vi.stubGlobal로 reportError를 바꾸고 되돌리지 않는다. 설정에 unstubGlobals가 없어서 그 stub이 같은 파일의 다음 테스트에 남는다. 고른 방법 - 이 파일에 afterEach(vi.unstubAllGlobals)를 둔다. 전역 설정 (unstubGlobals: true)은 다른 파일의 동작까지 바꾸므로 고르지 않았다. 검증 - 파일 2건 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md (2절 boot-unexpected-failure stubGlobal) |
||
|
|
2017ef76ff |
fix(query): 키 없는 결과 불명 요청에는 재전송을 주지 않는다
문제 resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만 본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의 결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고, 서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험 X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가 NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의 기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도 이 버튼을 숨기는 장치가 없다. 고른 방법 - application-query.ts canResend: head가 UNKNOWN이고 intent에 idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는 거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다. - AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고, 훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면 onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존 페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다. - KEYED는 지금처럼 같은 키로 재전송한다. 버린 대안 - 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존 배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다). - AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다. 위험·한계 - 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다. "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정). - 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은 결과 불명 동안 제출을 막는다. - hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다. 검증 - RED: application-mutation-admission 2건(NEVER: canResend false·resend null· execute 1회, KEYED: canResend true), async-surface 2건 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출. - check:types, lint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03 Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1 |
||
|
|
1e8b3d049f |
feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제 Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고 나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다. 짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400 <FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를 띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험 X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데 400·409·422는 정할 자리가 없다. 고른 방법 (결정 D2 ①) - CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[]. 표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code 목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다. - 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만, code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다 (409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다). - 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립 없이 실행기를 부르는 경로의 fail-close다. - 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로 두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다. - 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지, <FEATURE>_INVALID 예와 거부 문구를 적었다. 버린 대안 - 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도 나온다. - 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는 분류기가 키 보호를 푼다. - 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로 중복이 생긴다. - 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②). 위험·한계 - 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가 중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드 코드에서 던지는 곳을 확인한 code만 적으라고 한다. - 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이 이어 받는다. - 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다. 검증 - RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3, envelope 통합 3, form-foundation 1). - GREEN: tests/unit·integration·component·features·contract·runtime-schema 253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable, 저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면 effect-unknown, 저장 꺼짐, fetch 1회. - 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록 복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도 계속 검출. - check:types, lint, check:registries, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01 Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01 |
||
|
|
613c1cfd0c |
fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다
문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.
고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.
버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.
위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.
검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
|
||
|
|
5d0f8454c6 |
test(http): Envelope 판정 경계와 처리 중 409 무재전송을 고정한다
문제 Envelope 실패 판정 표(backend-envelope.ts)와 실행기의 실패 Envelope 처리는 커버리지가 100%인데 경계 다섯 곳이 테스트에 걸리지 않는다. 표의 code를 다른 status로 보내는 행, 표 밖 422, 게이트웨이 408·425, 응답 한도보다 크고 64 KiB보다 작은 실패 본문, JSON이 아닌 실패 본문이 없다. 그래서 변이 H14(=M6, status 대조 제거)·H45(표 밖 422를 분류기로)·H15 (408·425 제거)·H23(실패 한도를 64 KiB 고정)·H10b(실패 media type 검사 제거)가 살아남았다. 처리 중 409를 자동 재전송하게 바꾼 변이 M7도 살아남았다. Envelope 표 테스트는 재시도 예산이 0이라 재전송을 볼 수 없었다. 같은 문서의 이월 항목 둘도 그대로다. 결과 불명 동안 입력 identity를 잡는 네 줄(M1, 0929/03-06)과 반사 correlation 문법 검사(M3, 1101/03-06)를 지워도 테스트가 통과한다. 고른 방법 - tests/unit/backend-envelope.test.ts: envelopeFailureEffect· idempotencyRefusalReason·envelopeFailureReading을 status × code 표로 직접 부른다. - envelope 통합 테스트: LENIENT 묶음에 422 INTEGRITY_MISMATCH 한 행, 한도를 넘는 실패 Envelope와 text/plain 실패 본문(네이티브 Response), retryBudget 1인 KEYED가 409 IDEMPOTENT_IN_FLIGHT에 한 번만 보내는 행. - 결과 불명 입력이 두 칸짜리 identity 레지스트리에서 밀려나지 않는지, 문법 밖 반사 id가 보낸 id로 바뀌는지를 각각 한 건씩 더한다. 위험·한계 테스트만 더했다. 동작은 바꾸지 않았다. 검증 - 변이 8종(H14·H45·H15·H23·H10b·M7·M1·M3)을 하나씩 넣고 관련 테스트를 돌렸다. 모두 새 테스트에서 실패하고, 되돌리면 통과한다. - check:types, lint 통과. 바뀐 4파일 83건 통과. Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-02 Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-08 |
||
|
|
d7c6cb4fd2 |
fix(auth): 세션 복구가 no-session이면 로그인 버튼을 보인다
문제: useSessionAction이 recover()의 결과를 버린다. owner가 "no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와 셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가 지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면 코드를 읽고 추론해야 했다. 고른 방법: 두 가지를 함께 한다. - SessionState·SessionGateway.recover·ExternalSessionOwner에 전이 계약을 적는다. restored면 authenticated, no-session이면 unauthenticated(또는 integration-failed), reject면 상태 유지. - SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데 owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에 unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을 보인다. 버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만 보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독 알림을 새로 만들어야 해서 scope fence와 얽힌다. 위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다. application·scope fence는 owner의 상태를 그대로 본다. 검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패 확인), router·app-shell·route-status-surfaces·auth-session-adapter 테스트 통과, check:types, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11 |
||
|
|
4282a541d0 |
fix(forms): 필드 code 문구를 표의 자기 키로만 찾는다 (1103/08-03)
문제
validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는
Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty·
__proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다.
그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다.
고른 방법
같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼
Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은
타입 선언과 다른 표의 관용이 갈려 버렸다.
위험·한계
짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다.
검증
- RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과.
- form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03
|
||
|
|
e40684b4e1 |
chore(review): 리뷰 기준으로 두 작업 브랜치를 합친다
문제 2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에 나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED 재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두 브랜치를 합친 상태를 리뷰 기준으로 골랐다. 고른 방법 새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는 건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다. - 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가 없어진 이쪽을 택했다. - 6절: 거절 판정 위치는 backend-envelope.ts 표다. - 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다. 위험·한계 - 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는 사용자가 정한다. 검증 - check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다. |
||
|
|
048f490ada |
refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
|
||
|
|
7c8cb19e94 |
fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
`NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
`route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
`invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
붙어서 지금은 닿지 않는 값이다.
이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.
고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.
버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
`route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.
위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
`route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
않았다.
검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
`"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
`"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
(`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
|
||
|
|
27f45233f9 |
test(layouts): 모든 레이아웃의 skip link와 main 하나를 실행으로 검사한다 (1101/14.4)
문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).
고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
`loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
`loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.
버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.
위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
`AppShell`만 돈다.
검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
("expected to have a length of 1 but got +0"). AppShell skip link href를
`#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
PASS_SCOPED.
|
||
|
|
326120867c |
fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제 계약 문서 6.1절( |
||
|
|
8a09c90379 |
fix(forms): 짝 백엔드 필드 검증 code마다 문구를 보인다 (1101/14.4)
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.
고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.
버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
(check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
목록은 테스트에 SHA와 함께 적었다.
위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
청크에 있다.
검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
"Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
|
||
|
|
7ee1df56f1 |
test(component): UI 갤러리 화면의 검증·상태 전환을 component 테스트로 막는다 (1101/14.4)
문제: `src/presentation/examples/ui-gallery-page.tsx`는 component 커버리지가 0%였다. e2e(`tests/e2e/ui-gallery.spec.ts`, 폼 검증과 모달 포커스 2건)와 시각 회귀만 이 화면을 봤다. 화면이 primitive에 연결한 규칙(공백 이름 거절, 알림 줄 문구, 알림 숨김·다시 표시, 모달 확인만 알림 줄을 바꿈, 메뉴의 toast)은 게이트 안 단위 실행에서 아무도 확인하지 않았다. 고른 방법: `tests/component/starter-ui-gallery-page.test.tsx` 9건. 화면을 LocaleProvider만으로 그리고 사용자 동작(user-event)으로 확인한다. 섹션 5개와 토큰 7개 렌더, 버튼 3개의 알림 문구, 빈 이름·공백 이름 거절과 trim한 이름 수락, controlled 입력 6종, 알림 숨김·복원, 모달의 취소·닫기·확인, 메뉴 두 항목, 수동 탭 활성화, tooltip 설명. 파일 이름은 starter 화면 테스트 규칙 (`docs/architecture/starter-experience.md`, `starter-*.test.tsx`)을 따라 화면을 지울 때 같이 지운다. 버린 대안: 스냅샷 테스트. 문구가 바뀔 때마다 깨지고 동작은 확인하지 않는다. 앱 라우터(`/examples/ui`)로 띄우기. 라우팅은 router 테스트가 보고, 이 화면은 provider가 locale 하나만 필요하다. 화면 코드는 고치지 않았다. 위험·한계: primitive 자체 동작(포커스 트랩, Esc, 화살표 이동)은 각 primitive 테스트와 e2e가 보고 여기서는 다시 세지 않는다. jsdom이라 실제 레이아웃과 `showModal()`의 top layer는 확인하지 않는다(e2e 몫). 검증: - 커버리지(`node scripts/run-vitest.ts run tests/component --coverage --coverage.include=src/presentation/examples/ui-gallery-page.tsx`): 전 lines 0/38, functions 0/19, branches 0/8 후 lines 38/38, functions 19/19, branches 8/8 (100%) - 일부러 화면을 깨 봄(되돌림): fieldError의 trim 제거, 알림 onDismiss 무효화, 메뉴 "상태 확인" onSelect 무효화 → 9건 중 3건 실패 - tests/component 전체 38파일 253건 통과 - `npx eslint` 새 파일, `npx tsc --project tsconfig.test.json --noEmit` 통과 |
||
|
|
64e98ee2fa |
fix(http): V2 검증 거절을 적용 안 됨으로 보고 고친 값을 다시 저장하게 한다 (백엔드 1101/02-01)
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).
고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.
근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
끌어낸 것이다.
버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
남아 같은 입력을 다시 저장하면 같은 키가 나간다.
위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.
검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
"saves the corrected value after a server 422 field error"는 수정 전에도
통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
tests/unit·contract·runtime-schema·integration·component·features·platform
3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
통과.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
|
||
|
|
02e35d2b38 |
fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.
고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).
버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
(type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
않는다. 짝 백엔드 wire를 읽는 곳은 V2다.
위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.
검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
"reads the field details as validation issues" 실패(kind
UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
component·features·platform 283 files 중 282 통과, 3394 tests 통과.
실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
|
||
|
|
47fec5c27c |
fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
한 번 더 받는다.
고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
긴 Retry-After를 다 기다리게 하지 않는다.
버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
Retry-After를 지키는 것이다.
위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).
검증
- RED: 4행 실패.
- tests/features/reference-feature/reference-production-vertical.test.tsx
처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
- tests/component/application-mutation-admission.test.tsx 재전송이
retryAfterMs 300을 기다리지 않음
- tests/features/reference-feature/reference-http-problem-mapping.test.ts
retryAfterMs 없음
- tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
capability, tests/integration/http-client·http-diagnostics, tests/unit/
http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
|
||
|
|
8b7c6ebf6c |
perf(contracts): 검증 생략 목록을 부팅 경로 밖에서 만든다 (1101/07-03)
문제 - 93180f6(합친 커밋 |
||
|
|
ca161878f2 |
feat(routes): 기능이 홈을 대신하고 context가 자기 레이아웃을 선언한다 (1101/09-03)
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(
|
||
|
|
5d064b8ace |
test(features): 기능을 더해도 기능 밖 테스트와 시나리오 하네스가 깨지지 않게 한다 (16-02)
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).
방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.
위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
않았다.
검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
|
||
|
|
d3ddc8957f |
feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제 - zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의 reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은 복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을 structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다. - RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도 검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이 타입·이름·조립 결과 어디에도 남지 않는다. 고른 방법 (C: 공유 어댑터 + 생략 표시) - zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과 tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은 참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code 문자열). tests/helpers도 이제 성공 값을 복사한다. - unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에 둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다. zod가 필요 없어서 검증기 프로토콜 옆에 뒀다. - composeContractContributions가 이 표시가 붙은 검증기를 unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로 내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두 본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다. - 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약" 표를 둔다. 목록이 비면 그리지 않는다. 버린 대안 - (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다. - (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의 자체 검증기까지 막아 §4 설계와 충돌한다. 위험·한계 - 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을 통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을 만들어 그 길로 생략한 것만 드러낸다. - 공개 계약 추가: RuntimeValidator에 선택 필드 2개, ComposedContractContributions에 필드 1개, 새 export zodValidator· unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다. ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야 한다(repo 안에는 없다). - 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다. 플랫폼 개요 청크 4,625 → 4,750 B. - 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는 돌리지 않았다. - tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는 그대로 둔다(16-01이 그 파일을 넓힌다). 검증 - RED(수정 전): zod-validator.test.ts "Cannot find module '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와 starter-platform-overview-page.test.tsx "unvalidatedPayload is not a function". 3파일 모두 실패. - GREEN: 같은 3파일 33건 통과. - 회귀: tests/unit·contract·component·runtime-schema·features·platform 268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는 security-followup-archive 제외), tests/architecture 7파일 33건 통과. tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일 eslint 0. check-registries PASS(compatibility=none), verify-documentation PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신 exec stub) 383 모듈 PASS. - 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능 폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용. src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립· 플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과. Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3 |
||
|
|
ca74caa2a8 |
test(component): 플랫폼 화면 테스트를 테스트 전용 페이지로 옮긴다 (0929/10-02)
문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).
방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.
위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).
검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
|
||
|
|
d6e4e51688 |
fix(contexts): 계약에 없는 라우트 핸들을 라우트 적재 때 막는다 (09-06)
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.
고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
(tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(
|
||
|
|
1fa5f3e237 |
fix(query)!: 제품 mutation 훅이 raw 입력을 받지 않게 한다 (1101/08-03)
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.
고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
온 이전 응답은 버려진 client에 쓰인다. 이 동작을
server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.
위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.
검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
"error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
통과(옮긴 테스트 포함). tests/unit·component·features·contract·
runtime-schema·architecture·scripts·integration(security-followup-
archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
(바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
raw 호출이 있어 harness와 함께 동기화해야 한다.
BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03
|
||
|
|
e54fbf2014 |
feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.
고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.
위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).
검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
reference-page 3. 예: "Unable to find an element with the text: 지원
참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
59 files 336 tests 통과. e2e reference-save·reference-form·
reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
check-i18n, check-design-system 통과.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
|
||
|
|
b9a8a1a6c2 |
test(presentation): 건너뛰기 링크·로딩 발표·사이드바 이름을 테스트로 지킨다 (08-09)
문제: 접근성 기본 장치 일부를 지키는 테스트가 없었다. 리뷰 변이 중 M3(건너뛰기 링크 대상을 #content로), M4(LoadingSurface의 aria-live 제거), M5(상태 화면 제목을 <p>로), M6(사이드바 aria-label 제거)가 component 211개를 모두 통과했다. e2e의 axe는 WCAG 태그만 돌려 best-practice인 skip-link 규칙이 빠지고, 건너뛰기 링크를 누르는 e2e도 없었다. 고른 방법: 리뷰의 최소 개선 방향 그대로 단언을 더했다. - app-shell.test.tsx: 건너뛰기 링크 href가 main의 id와 같고, 이름 있는 complementary 안에 주요 탐색이 있다. - async-surface.test.tsx: LoadingSurface가 aria-busy와 aria-live="polite"를 가진다. - accessibility.spec.ts: 건너뛰기 링크 Enter 뒤 포커스가 main 안에 있다. - M5는 08-05 커밋의 제목 수준 테스트가 이미 잡는다. 버린 대안: axe에 best-practice 태그를 켜기 — 이번 범위 밖의 위반까지 한꺼번에 게이트가 된다. 위험·한계: 사이드바 이름 "사이드바"는 위치를 말하는 이름이라 리뷰가 관찰로 남겼다. 테스트는 지금 이름을 고정하므로 이름을 바꾸면 테스트도 같이 바꾼다. M3 변이 빌드에서 e2e는 공용 실행 잠금이 길게 잡혀 돌리지 못했다(component 테스트가 M3를 잡는다). 검증(테스트만 추가라 RED는 변이로 확인): - M3: app-shell landmarks 테스트 실패(1 failed | 221 passed) - M4: loading surface 테스트 실패(1 failed | 221 passed) - M5(state-surfaces.tsx 제목을 <p>로): 08-05 테스트 2건 실패 - M6: app-shell landmarks 테스트 실패(1 failed | 221 passed) - 변이 없음: tests/component 222/222, 새 e2e chromium·firefox·webkit 3/3. tsc test 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-09 |
||
|
|
dda153b25e |
feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의 제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의 상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서 h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다. 상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다. 고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에 headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와 AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서 뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다. 갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다. 상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만 했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목 수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop 계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은 VD-05 재수출 경로를 건드려 이번 범위에서 뺐다. 위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태 h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더 제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언). 검증: - RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected [ <h2></h2> ] to have a length of +0 but got 1"). - GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복 통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과, eslint 통과. e2e accessibility·typography·reference-form·reference-save chromium 27/27. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05 |
||
|
|
d0f3993b60 |
fix(presentation): 검색값만 바뀌면 포커스·스크롤·진단을 건드리지 않는다 (08-02)
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로 썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로 튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다. 이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈) navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고 권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2). 고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1 (B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만 하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지 번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다. 버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런 라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에 더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라 React 19의 useEffectEvent보다 의도가 덜 드러난다. 위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가 준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적 확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다. 검증: - RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가 <main id="main-content">에 있었고 route.changed가 필터 테스트 1→3, 링크 테스트 1→2로 늘었다. - GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과. tsc(app, test) 통과, eslint(바꾼 파일) 통과, verify-documentation-readiness PASS_SCOPED. - check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02 |