Files
clean-architecture-frontend…/docs
DongHyeonka 112c870fe3 fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).

고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.

버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
  NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
  같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
  APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
  틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
  변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
  목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
  응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
  요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
  만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.

위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
  contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
  적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
  고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
  백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
  (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
  템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
  Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
  참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
  referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
  code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
  (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
  이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
  "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
  확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
  run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
  두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.

검증
- RED(수정 전): reference-production-vertical "keeps the key when the
  resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
  분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
  (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
  카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
  tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
  제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
  PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
  읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
  check:ci 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 19:09:47 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md verify:documentation (FE-GATE-017)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다