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 확인 리뷰
331 lines
34 KiB
Markdown
331 lines
34 KiB
Markdown
# round9 L1 — fe-react 렌즈 + SRP (전체 리뷰)
|
|
|
|
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 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.md` 4·4.1·4.2·6·6.1절, `docs/manual/02-decision-tables.md` 3·4절, `docs/manual/01-add-a-feature.md` 7·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`를 읽었다. tree `75cc3752`(= `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)다.
|
|
- 패치(새 파일):
|
|
|
|
```diff
|
|
--- /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회 호출). 나머지 통과.
|
|
- 패치(템플릿에 경우 추가):
|
|
|
|
```diff
|
|
--- 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 증거다.
|
|
- 패치(새 파일):
|
|
|
|
```diff
|
|
--- /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)만 남긴다.
|
|
- 패치:
|
|
|
|
```diff
|
|
--- 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`(클라이언트 트래픽 예산)가 kind `NETWORK_UNREACHABLE`로 보인다(`feature-http-binding.ts:509-516`) — code가 `OVERLOADED_BEFORE_SEND`로 남고 effect `NOT_STARTED`, action `retry`가 맞다. 문구 차이는 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` — 백엔드 page `size` 상한 100 안이다.
|