Files
clean-architecture-frontend…/SPEC.md
T
DongHyeonkaandClaude Opus 5.5 ea0f01ff05 docs: plan fixes for src review critical and required findings
SPEC.md lists the 47 requirements (R-0, R-1.1..R-9.3) and decisions D-1..D-7.
tasks/plan.md and tasks/todo.md break them into 50 tasks across 9 lanes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 11:48:19 +09:00

10 KiB
Raw Blame History

SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정

목적

docs/reviews/2026-09-24-src-full-review.md의 긴급 1건 + 필수 46건을 고친다. 권장·사소 항목은 이번 범위가 아니다.

각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 무엇이 되면 완료인지와 방향이 여러 개인 항목의 결정만 적는다.

범위 밖

  • 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다.
  • src/ 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다.
  • 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다.

공통 완료 기준 (모든 요구사항)

  1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다.
  2. corepack pnpm check:architecture, check:types:app, check:types:test, lint, test:unit, test:component이 통과한다.
  3. adapter 파일을 추가하거나 이동하면 docs/reviews/adapters/INVENTORY.md를 함께 고치고 check:adapter-inventory가 통과한다.
  4. adapter 간 공용 로직은 src/adapters/platform/(kernel)으로, 공유 어휘는 src/contracts/로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
  5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다.

요구사항

R-0 빌드 기반 (긴급)

  • 깨끗한 체크아웃(src/.generated/ 없음)에서 dev, build, check:architecture, check:types:app, test:unit, test:component, verify:documentation이 사전 수동 명령 없이 동작한다.
  • CI 게이트도 같은 조건에서 통과한다.

R-1 browser-transfer

  • R-1.1 dispose()가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 CLOSED가 된다.
  • R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다.
  • R-1.3 동시성 정책 검증은 partSize × maxConcurrency × copyFactor를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 실제 worker 수를 요청한다.
  • R-1.4 크기나 part 수 한도 초과는 LIMIT_EXCEEDED로 보고된다.

R-2 browser-files / cache-storage / cross-context

  • R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 deliver()는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다.
  • R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 NEXT다.
  • R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 DEGRADED로 보고된다.
  • R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. window 함수를 그대로 주입해도 동작한다.
  • R-2.5 기본 cache 정책이 Vary: Accept-Encoding 응답을 받아들인다. content-type이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다.

R-3 http / query-cache / auth

  • R-3.1 경로 값 .과 ..는 V3와 V2 모두에서 PATH_VALUE_INVALID(V2는 PATH_PARAMETER_INVALID)로 거부된다.
  • R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 onUnauthenticated()를 부르지 않는다. 서버 401만 부른다. [고위험: 인증·캐시]
  • R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(ENVELOPE_MISMATCH)로 매핑되지 않는다.
  • R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. [고위험: 인증]
  • R-3.5 feature 바인딩에서 mapSuccess/mapProblem이 던지면 MAPPING_CONTRACT_VIOLATION Result로 반환되고 effect가 보존된다.

R-4 realtime

  • R-4.1 await quiescence 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다.
  • R-4.2 retryable:true인 PROVIDER_UNAVAILABLE/RATE_LIMITED는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두).
  • R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다.
  • R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록).

R-5 storage

  • R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. [고위험: 삭제]
  • R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). [고위험: 삭제]
  • R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다.
  • R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. [고위험: 삭제]
  • R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 chunkSizeBytes로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. [고위험: 데이터 판독]

R-6 service-worker / web-push

  • R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 registration.waiting이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다.
  • R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다.
  • R-6.3 앱이 reloadRequired/updateWaiting을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다.
  • R-6.4 첫 방문에서 설치 중인 워커는 ACTIVE로 보고되지 않는다.
  • R-6.5 JavaScript MIME 동의어를 허용한다. content-encoding이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다.
  • R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 respondWith를 부른다.
  • R-6.7 reconcile에서 서버가 ABSENT이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. [고위험: 동의]

R-7 contracts

  • R-7.1 멱등 키는 ^[\x21-\x7E]{1,256}$만 허용한다. 이 버그를 고정한 기존 테스트도 고친다.
  • R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다.
  • R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다.
  • R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. semantics/replayPolicy는 enum으로 검증된다. [고위험: CSRF]
  • R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다.

R-8 presentation

  • R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다.
  • R-8.2 WebKit(Importing a module script failed)과 Vite CSS preload 실패가 청크 실패로 인식된다.
  • R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다.
  • R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다.
  • R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다.
  • R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다.
  • R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 recoverChunk를 거친다.
  • R-8.8 enabled:false 쿼리는 로딩으로 표시되지 않는다.

R-9 bootstrap / platform

  • R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다.
  • R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다.
  • R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 pwd, pass, auth, otp, pin 계열을 추가한다. [고위험: 보안]

결정 (방향이 여러 개였던 항목의 기본값)

ID 결정 이유
D-1 (R-0) 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. 6f6c48e가 앱별 생성(PRODUCT_APP_ID)을 의도했으므로 gitignore를 유지한다.
D-2 (R-1.3) 기본 maxConcurrency를 실제 동작값에 맞춘다. 메모리 한도(maxInFlightBytes)는 올리지 않는다. 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다.
D-3 (R-5.3) lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다.
D-4 (R-2.3) 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다.
D-5 (R-8.3) 로케일 저장은 테마와 같은 preferences 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. 이미 있는 테마 패턴을 재사용한다.
D-6 (R-9.2) 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 occurrences로 보낸다. 기존 이벤트 스키마(occurrences)를 그대로 쓴다.
D-7 (R-6.3) previous 캐시 fallback은 hashed URL에만 적용한다. hashed URL은 같은 URL이면 같은 내용이라 안전하다.