frontend-quality-gates / merge / static checks (pull_request) Successful in 3m30s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m48s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m28s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
main 5250ff95 전체를 분야 렌즈 아홉(React, 구조·공통 계약, 시험·QA,
UX·디자인 시스템, 접근성, 성능·빌드, 보안, 가드레일·문서, 나머지
adapter)과 지난 발견 재판정 둘로 나눠 리뷰했다. 새 발견은 반박 검증을
거쳐 80건이다(High 0, P1 1: 1112/08-02 템플릿 시험의 고정 기능 ID).
지난 리뷰가 연 118행은 고쳐짐 33, 일부 35, 남음 46, 재발 2다.
리뷰 README 하나와 영역 기록 열다섯을 docs/reviews/2026-11-round9-*.md
파일 묶음으로 둔다. 영역 기록은 서브에이전트가 쓴 원문이고, 작업 폴더
절대 경로만 줄였다. 리뷰 중 코드는 고치지 않았다.
위험·한계: 실행 증거는 desktop에 CI env를 준 실행이다(실제 runner
미검증). 실험 X-GD02·X-GD02b와 수정 라운드는 README 16절에 이어 적는다.
결정이 필요한 12건(R9-D1~D12)은 권하는 안과 함께 7절에 있다.
검증: scripts/verify.sh docs(노트북) 통과. 게이트 실행 결과는 README
11.1절(merge 13/14 rc=0, FE-GATE-013은 호스트 제약 조건 충족,
documentation rc=0).
Refs: round9 확인 리뷰
34 KiB
34 KiB
round9 L1 — fe-react 렌즈 + SRP (전체 리뷰)
round9 리뷰(2026-11-12, 대상 main
5250ff95)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를(작업 폴더)로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(1112/NN-MM)와의 대응은 README 15절이다.
대상: 5250ff95(tree 75cc3752). 읽기만 했다. repo 파일을 고치지 않았다. 실행은 하지 않았다(실험 요청 4절).
0. 결론
- 판정: 고칠 것 있음. 새 High 0, 새 P1 0.
- 발견 6건: Medium·P2 1(구조적 위험, SRP), Low·P3 5(확인된 결함 4, 구조적 위험 1).
- 결과 불명 쓰기의 재전송 입구(재전송 버튼, 같은 입력 재저장, 실행기 재시도, poll, 업로드)는 이번에 새로 열린 곳을 찾지 못했다. NEVER는 같은 입력을
UNKNOWN_EFFECT_PENDING으로 막고, KEYED는 같은 키를 쓰고, 1106/03-01 수정(재전송의 쓰기 전 거절은 결과 불명 유지)도 코드에 있다. - 가장 큰 것은 R-01이다. 결과 불명 상태를 코디네이터와 폼이 따로 갖고, 둘을 맞추는 판정은 생성된 작성 페이지 사본에 있다. 플랫폼에서 고친 것(1105/08-02, 1105/08-04, 1106/08-02)이 이미 생성한 기능으로 전파되지 않는다. R-02는 그 구조에서 나온 증상이다.
1. 범위
읽은 경로
- 바뀐 곳 먼저(
git diff --stat bbde570 5250ff95): 참조 샘플 기능 3개 삭제(reference-feature,platform-examples-feature,local-draft-feature). 이제 기능 React 코드는 생성 명령 템플릿이 전부다.application-query.ts(1106/03-01·03-03 수정),use-app-form.ts(1106/03-01·08-01),errors.ts(isRefusedOnEveryAttempt),backend-envelope.ts·fileserver-upload.ts(traceId). src/presentation/adapters/query/전 파일(7).src/presentation/forms/전 파일(5),src/presentation/pages/2.src/adapters/query-cache/:server-state-scope-runtime.ts,tanstack-cache-coordinator.ts,tanstack-query-cache.ts전체, 나머지는 훑음(소비자 없는 확장 지점).src/adapters/http/:backend-envelope.ts·feature-http-binding.ts·platform-error-mapping.ts전체,http-execution-v3.ts는 실행 루프·재시도 판정·결과 helper(517-1180, 1854-1934),fileserver-upload.ts는 재시도·effect 부분.src/contracts/errors.ts전체,server-state.ts(bind·mutation 정책),query-keys.ts(identity registry),diagnostics.ts(safeErrorKind).src/application/:view-models/async-state.ts,policies/bounded-polling.ts,create-application.ts(일부).- 경계:
src/presentation/components/async-surface.tsx,boundaries/render-error-boundary.tsx,chunk-recovery-boundary.tsx,routes/app-router.tsx(경계 연결부),routes/route-input.tsx. - 생성 템플릿:
scripts/create-feature.ts(feature API, gateway, routes,use-<base>-items, 목록 페이지, 입력 테스트),scripts/create-feature-write-slice.ts(descriptor, gateway 조각,use-<base>-item,use-<base>-create, 폼, 상세·작성 페이지, 작성 페이지 테스트). - 계약 문서:
docs/architecture/backend-api-and-server-state-contract.md4·4.1·4.2·6·6.1절,docs/manual/02-decision-tables.md3·4절,docs/manual/01-add-a-feature.md7·8단계,src/{application,features,presentation,adapters,contracts}/AGENTS.md,docs/work/reference/{review-criteria,decisions,defect-patterns}.md, 테스트 전략 설계 7.1·7.2절, CHANGELOG 196·287행. - 짝 백엔드:
scripts/new-feature.sh이름 변환(앞 60행)만. 프론트namesOf와 code 이름 규칙이 같음을 확인했다.
쓴 스킬과 그 기준으로 본 것
fe-react함정 1(재전송 입구 다섯), 2(status+code 판정), 3(commandMutationIdentity), 4(서버 상태 위치), 5(TanStack 직접 import), 6(라우트 codec), 7(effect), 8(REJECT_WHILE_ACTIVE), 9(409·필드 문구), 10(오류 경계 reset), 12(브라우저 저장소). 체크리스트 「상태」(파생 값), 「데이터」(abort를 telemetry 실패로 세지 않음, 무효화 범위, rollback), 「렌더」(key, 정리).- SRP: 한 모듈·hook·컴포넌트가 바뀌는 이유가 둘 이상인 곳, 같은 판정이 여러 곳에 있는 곳. R-01, R-06이 여기서 나왔다.
확인 못 한 것
- 실행 없음. 모든 발견은 E1이다. 4절 실험으로 E2를 만든다.
- 게이트: desktop
/tmp/claude-gates/r9fe-base/summary.txt를 읽었다. tree75cc3752(=5250ff95의 tree, 스냅샷 커밋b693d36f)에서 FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(결정 D8 대상인지 로그는 안 봤다), FE-GATE-020은 읽을 때 진행 중이었다. 이 결과는 발견들을 반박하지 않는다(발견마다 그 경로를 보는 테스트가 없음을 확인했다). - 화면으로만 아는 것: R-02·R-05의 실제 화면 흐름.
verify-app으로 열 곳은--with-create --keyed로 만든 기능의 작성 라우트(저장 중 목록으로 갔다 돌아옴 → 이름 입력 → 「같은 요청으로 다시 보내기」), 목록 라우트(배경 재조회 실패 → 「다시 시도」 중 표시). http-execution-v3.ts의admitResponse·admitProblem(1248-1800)은 지난 라운드들이 깊게 본 곳이라 훑기만 했다.
2. 발견
R-01 결과 불명 화면의 판정이 코디네이터·폼·생성 페이지 사본 세 곳에 나뉘어 있다
| 칸 | 내용 |
|---|---|
| 성격 | 구조적 위험 (SRP) |
| 관련 관점 | 3, 4, 5, 22, 23, 25 |
| 심각도·우선순위 | Medium·P2. 지금 템플릿 출력은 맞게 동작한다. 그러나 이 판정의 결함은 지난 두 라운드에 세 번 났고(1105/08-02, 1105/08-04, 1106/08-02), 고칠 때마다 이미 생성한 기능은 옛 판정을 그대로 갖는다. --with-create로 만든 모든 기능이 복제한다 |
| 통제 | M1 — CHANGELOG가 "이미 생성한 기능은 바뀌지 않는다. … mounted ref를 손으로 옮긴다"고 적는다(CHANGELOG.md:196). 옮겼는지 보는 검사는 없다. 생성 기능을 새 판정으로 올리는 절차 문서도 없다(docs/manual, docs/work, docs/operations에서 0건) |
| 증거 | E1 |
| 근거 | (1) 코디네이터가 결과 불명을 소유한다: 채널의 UNKNOWN admission(src/presentation/adapters/query/application-query.ts:310-321, :623-633). (2) 폼이 결과 불명을 따로 갖는다: unknownSubmissionRef와 result: "effect-unknown"(src/presentation/forms/use-app-form.ts:114, :304-310). 재전송 결과도 폼이 다시 판정한다: resendLeftUnknown(use-app-form.ts:522-530)은 코디네이터의 resendLeavesUnknown(application-query.ts:643-646)을 결과에서 거꾸로 추론한 사본이다. 둘은 이미 다르다: 폼은 action === "reauth"를 빼고(:527), 코디네이터는 replayed와 scope를 본다(:644-645). 401 재전송 뒤 코디네이터는 UNKNOWN을 쥐는데 폼은 unknownSubmissionRef를 비운다(use-app-form.ts:297-303). (3) 둘을 맞추는 규칙은 생성된 페이지 사본에 있다: effectUnknown·blocked·otherSaveRunning(scripts/create-feature-write-slice.ts:674-679), 저장 중 이탈 가드를 !form.pending으로 끔(:680), 마운트된 동안만 이동(:639-656), 확인 → settleApplied → 목록(:736-741), 재전송 → openSaved가 applyOutcome보다 먼저 이동(:744), feedback 고르기(:724-750). 폼이 진짜 상태를 모르니 페이지가 mutation.state.indicator로 막는다. src/application/AGENTS.md는 "결과 불명 쓰기의 재전송 판정은 한 곳에 둔다"고 적는다 |
| 발생 조건 | 플랫폼이 이 판정을 다시 고친다(지난 세 번처럼). 또는 제품이 생성 페이지를 손보면서 세 조각 중 하나를 빠뜨린다 |
| 영향 | 다운스트림 기능은 고쳐진 결함(예: 1106/08-02 저장이 떠난 사용자를 상세로 끌고 감)을 조용히 갖고 있다. 기능 수만큼 손 이식 비용이 든다. 폼과 코디네이터가 엇갈리는 상태(재마운트, 재인증)는 페이지가 매번 따로 맞춘다. R-02가 그 엇갈림에서 나온 결함이다 |
| 최소 개선 방향 | 결과 불명 상태의 소유자를 코디네이터 하나로 둔다. 폼은 코디네이터 상태를 읽는다(useAppForm에 mutation controller를 넘기거나, src/presentation/forms/에 useMutationForm(mutation, formOptions) 같은 platform hook을 둔다). 그 hook이 막기·피드백 고르기·마운트된 동안만 이동·확인·재전송 뒤 정리를 가진다. 생성 페이지는 그 hook과 필드·문구만 갖는다. 이미 생성한 기능의 이행 안내를 CHANGELOG [계약]에 한 번 적는다 |
| 완료 기준 | 생성된 <base>-create-page.tsx에 mutation.state.indicator 비교, useRef(false) 마운트 표시, form.resendUnknown·settleApplied 직접 호출이 없다. use-app-form.ts에 resendLeftUnknown 같은 재전송 결과 재판정이 없다. 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 platform hook 시험(tests/component/)으로 옮겨져 통과한다 |
| RED 시험 아이디어 | platform 시험: 같은 mutation 정의를 쓰는 폼 두 개(기능 둘)를 그리고, 하나에서 결과 불명을 만든 뒤 내렸다 다시 그린다. 두 폼이 같은 hook으로 같은 막기·피드백을 보이는지 본다. 지금은 hook이 없어 쓸 수 없고, 생성 페이지 사본을 grep하는 정적 시험(mutation.state.indicator가 생성 출력에 있으면 실패)이 지금 실패한다 |
| 결정의 근거·대안 | 대안 A: 지금처럼 사본을 두고 CHANGELOG로 이식 안내(비용: 기능 수 × 수정 수). 대안 B: 위 platform hook(비용: 폼 API 추가, 생성 출력 변경. 생성 기능 이행 한 번). 대안 C: 폼에 코디네이터 상태만 주입하고 페이지 판정은 남김(절반). B를 권한다. 소유자 결정이 필요하면 결정 대기로 둔다(공개 API 추가) |
R-02 재마운트한 폼에서 재전송하면 보낸 적 없는 화면 값을 제출 값으로 쓴다
| 칸 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 23, 28 |
| 심각도·우선순위 | Low·P3. 쓰기는 맞다(원래 요청을 같은 키로 보낸다). 잃는 것은 사용자가 재마운트 뒤 입력한, 보낸 적 없는 값이다. 템플릿이 그리는 경로(KEYED 작성 페이지)에서 닿는다 |
| 통제 | M1 — 같은 상황의 다른 출구(settleApplied)에는 규칙이 구현돼 있다(use-app-form.ts:236-246). 재전송 출구에는 없다. 이 경로의 시험 없음(tests/component/form-foundation.test.tsx의 재전송 시험은 재마운트를 다루지 않는다) |
| 증거 | E1 |
| 근거 | resendUnknown이 const submittedValues = unknownSubmissionRef.current ?? values;(src/presentation/forms/use-app-form.ts:425, 주석 :424 "After a remount the form no longer holds the submitted values"). 성공이면 applyOutcome(outcome, submittedValues) → settleSuccessfulValues(화면 값)(:437, :261-263) → 기본 resetOnSuccess면 값과 기준값을 기본값으로 되돌리고, 아니면 화면 값을 기준값으로 삼아 dirty를 끈다(:218-229). 재전송이 결과 불명으로 남으면 unknownSubmissionRef.current = submittedValues(화면 값)(:430-435). 그 뒤 「변경됨으로 확인」은 settleApplied가 그 값을 제출 값으로 보고 같은 정리를 한다(:235, :248). 반대로 settleApplied의 재마운트 분기는 "The values on screen were never sent, so they and the dirty state stay as they are"(:237-241). CHANGELOG도 "화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다"고 약속한다(CHANGELOG.md:196) |
| 발생 조건 | KEYED 작성 페이지에서 저장 중 떠났다 돌아온다(채널이 UNKNOWN을 유지, application-query.ts:982-995). 폼은 새로 마운트되어 unknownSubmissionRef가 비어 있다. 사용자가 필드에 입력한 뒤 「같은 요청으로 다시 보내기」를 누른다. 또는 재전송이 429·503 RATE_LIMIT_*로 결과 불명에 남은 뒤 「변경됨으로 확인」을 누른다 |
| 영향 | 보낸 적 없는 입력이 지워지거나 깨끗한 값으로 표시되고, 이탈 확인 없이 사라진다. 생성 페이지는 재전송 성공 때 pending 중에 상세로 이동하므로(scripts/create-feature-write-slice.ts:680, :744) 가드도 없다 |
| 최소 개선 방향 | 재전송 경로도 unknownSubmissionRef.current가 없으면 화면 값을 제출 값으로 쓰지 않는다. 성공이면 settleApplied의 재마운트 분기와 같은 처리(결과만 success, 값·기준값 유지). 결과 불명에 남으면 unknownSubmissionRef에 화면 값을 넣지 않고 "제출 값 모름" 표시를 따로 둔다. R-01을 고치면 이 분기는 hook 하나로 모인다 |
| 완료 기준 | 재마운트 뒤 재전송 성공·재전송 결과 불명→확인 두 경우 모두 화면 값과 dirty가 그대로다. 아래 RED 시험 통과 |
| RED 시험 아이디어 | 실험 X-L1-01(4절). 새 폼(unknownSubmissionRef 없음)에 값을 입력하고 resendUnknown(async () => ({ ok: true, value }))를 부른다. 지금은 값이 ""로 되고 dirty=false다. 고친 뒤 값 유지, dirty=true |
| 선택 비교 칸 | 적용 제외 — 이미 정한 규칙(settleApplied 재마운트 분기)을 다른 출구에 맞추는 일이다 |
R-03 생성 기능의 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보낸다
| 칸 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 8, 24 |
| 심각도·우선순위 | Low·P3. 사용자 피해 없음. 생성 기능 전부가 복제하는 기본값이다 |
| 통제 | M2 — 호출자 abort(REQUEST_ABORTED)만 빼는 코드와 시험이 있다. fence abort는 없다 |
| 증거 | E1 |
| 근거 | 생성된 create<Base>FeatureInput의 reported가 result.error.kind !== "REQUEST_ABORTED"일 때 <base>.list.failed 등을 warning으로 보낸다(scripts/create-feature.ts:940-948). scope fence로 끊긴 요청은 REQUEST_ABORTED가 아니라 SCOPE_GENERATION_CHANGED다: 전송 중 fence → TRANSPORT_FAILURE ABORTED_BY_SCOPE(src/adapters/http/http-execution-v3.ts:720-732), 응답 뒤 fence → CONTRACT_VIOLATION SCOPE_FENCED(:1854-1858). 바인딩이 둘 다 SCOPE_GENERATION_CHANGED로 바꾼다(src/adapters/http/feature-http-binding.ts:509-516, :557-558). 생성 입력 시험은 호출자 abort만 본다(scripts/create-feature.ts:1271-1281). 테스트 전략은 "aborted request는 terminal error나 telemetry failure로 오분류되지 않는다"(docs/design/2026-07-26-frontend-platform-testing-strategy-design.md 7.1절), 렌즈 체크리스트도 같다 |
| 발생 조건 | 목록·상세 GET이나 작성이 진행 중일 때 로그아웃·계정 전환·subject 없는 재알림으로 scope가 fence된다(src/adapters/query-cache/server-state-scope-runtime.ts:120-147) |
| 영향 | 로그아웃마다 진행 중 요청 수만큼 <base>.*.failed warning이 쌓여 실패율 지표가 부풀고, 진짜 실패와 섞인다 |
| 최소 개선 방향 | abort 판정을 한 곳에 둔다: src/contracts/errors.ts에 isAbortFailure(failure)(REQUEST_ABORTED, SCOPE_GENERATION_CHANGED)를 두고 템플릿의 reported가 그것을 쓴다(템플릿마다 kind를 손으로 적지 않는다). 생성 입력 시험에 fence 경우를 더한다. 이미 생성한 기능 이행은 R-01과 같은 문제다 |
| 완료 기준 | 생성 입력 시험에 SCOPE_GENERATION_CHANGED 실패가 emit을 부르지 않는 경우가 있고 통과한다 |
| RED 시험 아이디어 | 실험 X-L1-02. 생성 입력 시험 템플릿에 fence 경우를 더해 생성·실행하면 지금 실패한다 |
| 선택 비교 칸 | 적용 제외 — 계약 문서의 abort 규칙을 생성 코드에 맞추는 일이다 |
R-04 query·mutation 실패 진단이 원인을 버린다
| 칸 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 24, 6 |
| 심각도·우선순위 | Low·P3. 진단 품질 |
| 통제 | 미확인(이 동작을 보는 시험을 찾지 못함. tests/unit/query-cache.test.ts는 createQueryCacheAdapter만 본다) |
| 증거 | E1 |
| 근거 | (1) 운영 QueryClient(src/bootstrap/runtime-adapters.ts:388)의 QueryCache·MutationCache onError가 모든 실패를 cache.operation.failed(warn)로 남긴다(src/adapters/query-cache/tanstack-query-cache.ts:39-44, :24-35). useApplicationQuery·useApplicationMutation은 실패한 결과마다 ApplicationQueryError를 던진다(src/presentation/adapters/query/application-query.ts:167, :478). 이 오류는 kind가 없고(failure.kind만 있다, :54-62) safeErrorKind는 kind 다음 name을 읽으므로(src/contracts/diagnostics.ts:241-266) 모든 기록이 error_kind: APPLICATION_QUERY_ERROR다. 404, 필드 거절, 결과 불명, scope fence로 끊긴 mutation(REQUEST_ABORTED·SCOPE_GENERATION_CHANGED)이 모두 "cache 작업 실패" 한 가지로 남는다. (2) 예상 밖 throw를 정규화할 때 정의 이름을 버린다: operationId: "APPLICATION_QUERY"(application-query.ts:173-177, 같은 함수가 :127·:137에서는 queryDefinitionId를 씀), "APPLICATION_MUTATION"(:702-705, :759-763, 같은 함수가 :510-513에서는 definitionId를 씀) |
| 발생 조건 | 실패한 query·mutation 전부(1). execute·낙관적 update·무효화 설치 누락이 던질 때(2) |
| 영향 | 진단에서 실패 종류를 가를 수 없고, 사용자 입력 거절과 abort가 warn "cache operation failed"로 세어진다(결함 패턴 C6). 예상 밖 throw는 어느 정의에서 났는지 모른다 |
| 최소 개선 방향 | (1) onError는 ApplicationQueryError(서버·실행기 답)를 cache 실패로 세지 않거나, 센다면 failure.kind를 싣고 abort kind는 뺀다. (2) 두 리터럴을 queryDefinitionId·definitionId로 바꾼다 |
| 완료 기준 | 필드 거절·abort로 끝난 mutation 뒤 cache.operation.failed 기록이 없다(또는 kind가 실린다). 예상 밖 throw 실패의 operationId가 정의 ID다 |
| RED 시험 아이디어 | 실험 X-L1-03 |
| 선택 비교 칸 | 적용 제외 — 진단 누락 수정 |
R-05 useApplicationQuery가 파생 값(stale 실패)을 effect로 state에 복사하고, 다시 시도의 초기화가 바로 덮인다
| 칸 | 내용 |
|---|---|
| 성격 | 확인된 결함(렌즈 위반은 코드로 확인, 화면 깜빡임은 미검증) |
| 관련 관점 | 1, 5 |
| 심각도·우선순위 | Low·P3 |
| 통제 | 미확인 — 최종 상태만 보는 시험이 있다(tests/component/application-query-bridge.test.tsx:15-49). 다시 시도 중 표시는 시험이 없다 |
| 증거 | E1 |
| 근거 | staleFailure를 useState로 두고 effect에서 query.isError && hasData면 true, 성공이면 false로 쓴다(src/presentation/adapters/query/application-query.ts:103, :185-191). TanStack v5는 data가 있으면 재조회 중에도 status: "error"를 유지하므로 이 값은 렌더 중 계산과 같다. retry가 setStaleFailure(false) 뒤 refetch하지만(:193-196) refetch가 isFetching을 바꾸면 effect가 다시 돌아 true로 되돌린다(:186-187). deriveAsyncState는 stale-degraded를 refreshing보다 먼저 고른다(src/application/view-models/async-state.ts:118-129). 렌즈: "파생할 수 있는 값을 state에 복사하지 않고 렌더 중에 계산한다", "effect는 외부 시스템 동기화에만" |
| 발생 조건 | 데이터가 있는 query의 배경 재조회 실패 → 「다시 시도」 |
| 영향 | 매 전이마다 렌더가 한 번 더 돈다. 다시 시도 중에 "갱신 중"이 아니라 "오래된 데이터 + 다시 시도" 버튼이 다시 보인다(추론). retry의 초기화는 사실상 죽은 코드다 |
| 최소 개선 방향 | const staleFailure = query.isError && hasData로 렌더 중에 계산하고 effect·state를 지운다. 다시 시도 중에 refreshing을 보이려면 isStale: staleFailure && !query.isFetching처럼 같은 줄에서 정한다(보일 상태는 fe-ux가 정한다) |
| 완료 기준 | 이 hook에 setStaleFailure·그 effect가 없다. 다시 시도 중 indicator를 단언하는 시험이 통과한다 |
| RED 시험 아이디어 | 실험 X-L1-04 |
| 선택 비교 칸 | 적용 제외 — 렌즈 기준 위반 정리 |
R-06 "모든 시도가 받는 거절" 판정이 기능 mapProblem이 바꿀 수 있는 failure.code를 읽는다
| 칸 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 17, 22, 23 |
| 심각도·우선순위 | Low·P3. 기능 작성자가 mapProblem에서 code를 바꿔야 닿는다. 템플릿과 매뉴얼 예시는 code를 그대로 넘긴다 |
| 통제 | M2 — 판정은 한 함수다(src/contracts/errors.ts:273-279). 입력이 백엔드 code라는 보장은 없다 |
| 증거 | E1 |
| 근거 | isRefusedOnEveryAttempt는 failure.code와 failure.httpStatus로 짝 백엔드 표(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)를 본다(errors.ts:256-279). 그런데 PROBLEM 실패의 code는 기능 mapProblem이 준 값이 먼저다(src/adapters/http/feature-http-binding.ts:340-341, :447-450). effect는 실행기가 백엔드 code로 정한다(src/adapters/http/backend-envelope.ts:363-374). 주석은 kind를 읽지 않는 이유를 "a feature's mapProblem sets it"이라고 적지만(errors.ts:270-271) code도 같은 곳에서 정해진다. Envelope 없는 백엔드(매뉴얼 02 4절 예)의 code에도 짝 백엔드 표가 그대로 적용된다 |
| 발생 조건 | (a) 기능이 선언한 쓰기 전 거절 code(예: WORKLOG_INVALID)를 mapProblem에서 code: "VALIDATION_FAILED"로 바꾼다 → 결과 불명 요청의 재전송이 그 답을 받으면 요청을 정리한다. 결정 D10 보완은 "기능이 선언한 code는 결과 불명을 풀지 않는다"(docs/architecture/backend-api-and-server-state-contract.md 6.1절). (b) 반대로 백엔드 400 VALIDATION_FAILED를 기능 code로 바꾸면 재전송 거절이 결과 불명을 풀지 못해 폼이 "나중에 다시 보내기"에 머문다 |
| 영향 | (a) 정리된 뒤 다음 저장이 새 키로 나간다. 첫 시도가 적용됐다면 중복이 생길 수 있다(결함 패턴 C2와 같은 모양, 조건이 좁다). (b) 사용자가 고칠 수 있는 입력 오류에서 막힌다 |
| 최소 개선 방향 | 판정 입력을 백엔드 답에서 고정한다. 바인딩이 Envelope operation의 outcome.problem.code와 status로 "모든 시도가 받는 거절" 여부를 계산해 AppFailure에 따로 싣고(예: refusal: "EVERY_ATTEMPT"), isRefusedOnEveryAttempt는 그 칸만 읽는다. Envelope 없는 operation은 싣지 않는다(안전한 쪽) |
| 완료 기준 | mapProblem이 code를 바꿔도 (a)·(b) 모두 결정 D10 보완대로 동작한다 |
| RED 시험 아이디어 | 통합 시험(tests/integration/): 실제 실행기 + 바인딩 + useApplicationMutation. KEYED Envelope create에 refusedBeforeWrite: ["WORKLOG_INVALID"], mapProblem이 그 code를 { kind: "VALIDATION_REJECTED", code: "VALIDATION_FAILED" }로 바꾼다. 첫 요청 응답 유실 → 재전송이 400 WORKLOG_INVALID → 지금은 indicator === null(정리됨), 고친 뒤 mutation-effect-unknown. (실험으로는 요청하지 않는다. 시험 작성이 필요하다) |
| 선택 비교 칸 | 대안: 바인딩이 mapProblem의 code가 플랫폼 표의 code와 겹치면 거절하는 조립 검사(더 단순, 그러나 (b)는 못 막는다). 위 안을 권한다 |
3. 넘길 것
- → fe-ux: R-05에서 다시 시도 중에 보일 상태(
refreshing인지stale-degraded유지인지)를 정한다. R-01 hook을 만들 때 재인증 실패 뒤(코디네이터는 결과 불명, 폼은reauth-required) 생성 작성 페이지가 sign-in 버튼 없는 상태만 보이고 결과 불명 버튼은 필드를 고쳐야 다시 나오는 흐름을 볼 것(scripts/create-feature-write-slice.ts:724-730,use-app-form.ts:297-303). 매뉴얼 8단계가 "onRetry만 넘긴다"고 적어 둔 범위라 이 렌즈의 결함으로 올리지 않았다. - → fe-testing: 생성 작성 페이지 시험이 1초 고정 대기로 "상세로 가지 않음"을 단언한다(
scripts/create-feature-write-slice.ts:984-990). 부정 단언이라 대기가 필요하지만 시간 가정 시험(결함 패턴 T3)인지 판정이 필요하다. - → fe-structure:
src/presentation/pages/home-page.tsx:31-47과src/presentation/examples/platform-overview-page.tsx:396-412의 릴리스 요약 effect가 같은 사본이다(아직 갈라지지 않음). 한 hook으로 모을지. - → 총괄: desktop 게이트 summary는 FE-GATE-020이 진행 중이었고 013 rc=1이다. D8 조건(
parts뒤 명령 rc=0)은 확인하지 않았다.
4. 실험 요청
모두 desktop, 작업 폴더 되돌림 필요. env 없음(기본), 시간 상한 각 5분.
X-L1-01 (R-02) 재마운트 뒤 재전송이 화면 값을 지우는지
- 명령:
scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/r9-l1-form-resend-remount.test.tsx - 기대: 지금 실패(값
"",dirty=false). 실패가 R-02의 증거(E2)다. - 패치(새 파일):
--- /dev/null
+++ b/tests/component/r9-l1-form-resend-remount.test.tsx
@@ -0,0 +1,27 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from "@testing-library/react";
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+
+import { useAppForm } from "../../src/presentation/forms/index.ts";
+
+describe("r9 L1 probe", () => {
+ it("keeps values a remounted form never sent when its resend succeeds", async () => {
+ const hook = renderHook(() =>
+ useAppForm({
+ schema: z.object({ name: z.string() }).strict(),
+ defaultValues: { name: "" },
+ allowedServerFields: ["name"],
+ mapToCommand: (values: { name: string }) => values,
+ submit: async () => ({ ok: true as const, value: "unused" }),
+ }),
+ );
+ act(() => hook.result.current.setValue("name", "typed after remount"));
+ await act(() =>
+ hook.result.current.resendUnknown(async () => ({ ok: true as const, value: "saved" })),
+ );
+ expect(hook.result.current.values.name).toBe("typed after remount");
+ expect(hook.result.current.dirty).toBe(true);
+ });
+});
X-L1-02 (R-03) 생성 입력이 fence abort를 telemetry로 보내는지
- 명령:
scripts/verify.sh exec -- sh -c 'corepack pnpm create:feature typecheck-probe-fence && node scripts/run-vitest.ts run tests/features/typecheck-probe-fence/typecheck-probe-fence-feature-input.test.ts' - 기대: 새 경우 1건 실패(emit 1회 호출). 나머지 통과.
- 패치(템플릿에 경우 추가):
--- a/scripts/create-feature.ts
+++ b/scripts/create-feature.ts
@@ -1280,5 +1280,17 @@ function renderInputTest({ names, operationId }: Shape): string {
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
expect(emit).not.toHaveBeenCalled();
});
+
+ it("does not report a load the session fence aborted", async () => {
+ const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0, { code: "ABORTED_BY_SCOPE" });
+ const emit = vi.fn<TelemetryPort["emit"]>();
+ const input = create${pascal}FeatureInput(
+ gatewayListing(async () => ({ ok: false, error: failure })),
+ { telemetry: { emit } },
+ );
+
+ await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
+ expect(emit).not.toHaveBeenCalled();
+ });
});
`;
}
X-L1-03 (R-04) 실패한 mutation이 cache.operation.failed를 남기는지
- 명령:
scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/r9-l1-query-cache-diagnostics.test.ts - 기대: 지금 실패(기록 1건,
error_kind: APPLICATION_QUERY_ERROR). 기록 내용이 R-04 증거다. - 패치(새 파일):
--- /dev/null
+++ b/tests/unit/r9-l1-query-cache-diagnostics.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { createQueryClient } from "../../src/adapters/query-cache/index.ts";
+
+describe("r9 L1 probe", () => {
+ it("does not count a refused save as a cache operation failure", async () => {
+ const records: unknown[] = [];
+ const client = createQueryClient({
+ diagnostics: { record: (event: unknown) => void records.push(event) } as never,
+ });
+ const answer = Object.assign(new Error("VALIDATION_REJECTED"), {
+ name: "ApplicationQueryError",
+ failure: { kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" },
+ });
+ await client
+ .getMutationCache()
+ .build(client, { mutationFn: async () => { throw answer; } })
+ .execute(undefined)
+ .catch(() => undefined);
+ console.log(JSON.stringify(records));
+ expect(records).toEqual([]);
+ });
+});
(createQueryClient가 배럴에 없으면 ../../src/adapters/query-cache/tanstack-query-cache.ts에서 가져온다.)
X-L1-04 (R-05) 다시 시도 중 indicator
- 명령:
scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/application-query-bridge.test.tsx - 기대: 새 경우가 지금 실패(다시 시도 중
stale-degraded). 통과하면 R-05의 화면 영향 부분을 지우고 렌즈 위반(파생 state)만 남긴다. - 패치:
--- a/tests/component/application-query-bridge.test.tsx
+++ b/tests/component/application-query-bridge.test.tsx
@@ -49,6 +49,40 @@ describe("application query inbound bridge", () => {
expect(execute).toHaveBeenCalledTimes(3);
});
+ it("r9 L1 probe: does not show the stale failure again while its retry runs", async () => {
+ const client = queryClient();
+ let release: ((value: ApplicationResult<string[]>) => void) | undefined;
+ let calls = 0;
+ const execute = vi.fn(() => {
+ calls += 1;
+ if (calls === 1) return Promise.resolve({ ok: true as const, value: ["first"] });
+ if (calls === 2) {
+ return Promise.resolve({
+ ok: false as const,
+ error: createFailure("SERVER_FAILURE", "LIST", 0),
+ });
+ }
+ return new Promise<ApplicationResult<string[]>>((resolve) => {
+ release = resolve;
+ });
+ });
+ const hook = renderHook(
+ () => useApplicationQuery({ queryKey: ["resource", "r9-retry"], execute }),
+ { wrapper: wrapper(client) },
+ );
+ await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
+ await act(() => hook.result.current.retry());
+ await waitFor(() => expect(hook.result.current.state.indicator).toBe("stale-degraded"));
+ act(() => {
+ void hook.result.current.retry();
+ });
+ await waitFor(() => expect(execute).toHaveBeenCalledTimes(3));
+ await act(async () => {
+ await Promise.resolve();
+ });
+ expect(hook.result.current.state.indicator).not.toBe("stale-degraded");
+ act(() => release?.({ ok: true, value: ["recovered"] }));
+ await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
+ });
+
it("coalesces repeated manual retries while stale data is refetching", async () => {
5. 결함 아님으로 판정한 의심
- 생성 목록·상세 페이지가
onAction을 넘기지 않아 401·403·404에 버튼이 없다 — 매뉴얼 8단계가 그렇게 정하고use-<base>-failure-action조각을 준다(docs/manual/01-add-a-feature.md:588-619). - scope fence가 결과 불명 admission을 버려 재로그인 뒤 새 키가 된다(
application-query.ts:964-978) — 런북 6.3-7에 적힌 한계(docs/operations/api-contract-and-server-state-recovery.md:280)이고 지난 라운드들이 판정했다. useApplicationMutation의 LEGACY 실행 분기 — 1101 결정 08-03(테스트 4건 때문에 유지)이다.- KEYED 재전송이 기능 선언 code(
<FEATURE>_INVALID)로 거절되면 "나중에 다시 보내기"에 머문다 — 결정 D10 보완("기능이 선언한 code는 결과 불명을 풀지 않는다")대로다. bindQuery가 렌더마다 identity binding을 새로 만들어useApplicationQuery의 lease effect가 렌더마다 돈다(application-query.ts:104-107) — 외부 자원 lease 동기화라 effect 용도가 맞고, 정리 순서상 row가 0으로 내려간 채 다른 intern을 만나지 않는다(query-keys.ts:247-299).- 첫 렌더에 결과 불명 채널이 아직 없어
submit이UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED를 낼 수 있다(application-query.ts:391-411,:556-574) — 채널은 마운트 effect에서 잡히고, 클릭은 그 뒤에 처리된다. 실제로 닿는 순서를 보이지 못했다. - 결과 불명 재전송 대기
setTimeout이 unmount에 취소되지 않는다(application-query.ts:689-695) — 사용자가 시작한 재전송이고, 대기 뒤mutationFn이 scope를 다시 본다(:439-448). mutation은 취소가 안전할 때만 취소한다는 렌즈 기준에 맞다. RenderErrorBoundary의 custom fallback 함수가reset을 받지 않는다(src/presentation/boundaries/render-error-boundary.tsx:62-66) — 라우터의 fallback은RENDER_FAILURE의 registry action(reload-once)대로 사용자 reload를 주고,resetKey(경로+검색값)가 라우트 이동 때 reset한다(src/presentation/routes/app-router.tsx:409-418). 사용자 버튼이라 "제한 없는 reload" 금지에도 해당하지 않는다.OVERLOADED_BEFORE_SEND(클라이언트 트래픽 예산)가 kindNETWORK_UNREACHABLE로 보인다(feature-http-binding.ts:509-516) — code가OVERLOADED_BEFORE_SEND로 남고 effectNOT_STARTED, actionretry가 맞다. 문구 차이는 fe-ux 몫이다.HomePage가 릴리스 요약을 effect + setState로 읽는다(home-page.tsx:34-47) — 백엔드 서버 상태가 아니라 부팅 때 읽은 릴리스 manifest이고 정리(active플래그)가 있다.- 짝 백엔드 code 이름 규칙(
<FEATURE>_INVALID) — 백엔드new-feature.sh:56의 upper snake와 프론트namesOf(scripts/create-feature.ts:142-157)가 같은 결과를 낸다(PascalCase ↔ kebab). REFUSALS_OF_EVERY_ATTEMPT가REFUSED_BEFORE_WRITE의 손 사본이다 —tests/unit/backend-envelope.test.ts:186-230가 부분집합 관계를 대조한다(구조적 위험은 통제됨).- 생성 목록
measureItems의itemCount와LIST_STANDARD.maxResultItems: 200— 백엔드 pagesize상한 100 안이다.