Add Q-requirements for every recommended/minor review finding plus the round-1 follow-ups (SW fetch scope, bundle budget), decisions D-11..D-16, and tasks T51-T115 across the same nine lanes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
123 lines
9.3 KiB
Markdown
123 lines
9.3 KiB
Markdown
# Implementation Plan: src 리뷰 긴급·필수 항목 수정
|
||
|
||
## Overview
|
||
|
||
`SPEC.md`의 요구사항 47개(R-0 + R-1.1 ~ R-9.3)를 작업 50개로 나눠 고친다. R-3.2, R-6.3, R-8.3은 각각 두 작업으로 쪼갰다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 전체 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록과 완료 조건은 `tasks/todo.md`에 있다.
|
||
|
||
- 브랜치: `fix/src-review-2026-09-24`
|
||
- 기준 커밋: `b04d570`
|
||
|
||
## Architecture Decisions
|
||
|
||
- 결정 D-1 ~ D-7은 `SPEC.md` "결정" 표를 따른다.
|
||
- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
|
||
- 공개 포트는 추가만 한다. 기존 시그니처는 깨지 않는다.
|
||
- 버그를 정상 동작으로 고정한 기존 테스트는 같은 커밋에서 고친다. 해당 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`, `tests/unit/release-mismatch-recovery.test.ts:64` 부근, `tests/platform/telemetry/telemetry-pipeline.test.ts:93`.
|
||
|
||
## 실행 방식
|
||
|
||
1. **Phase 0 (순차):** T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다.
|
||
2. **Phase 1 (병렬 레인 9개):** 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 `fix/src-review-2026-09-24` HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다.
|
||
3. **통합 (순차):** 레인 브랜치를 하나씩 `fix/src-review-2026-09-24`에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트).
|
||
4. **최종 체크포인트:** 전체 게이트, `build`, 깨끗한 체크아웃 재현(`src/.generated` 삭제 후 게이트)을 확인한다.
|
||
|
||
| 레인 | 영역 | 작업 |
|
||
|---|---|---|
|
||
| A | browser-transfer | T02–T05 |
|
||
| B | browser-files / cache / cross-context | T06–T10 |
|
||
| C | http / query-cache / auth | T11–T16 |
|
||
| D | realtime | T17–T20 |
|
||
| E | storage | T21–T25 |
|
||
| F | service-worker / web-push | T26–T33 |
|
||
| G | contracts | T34–T38 |
|
||
| H | presentation | T39–T47 |
|
||
| I | bootstrap / platform | T48–T50 |
|
||
|
||
레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 `docs/reviews/adapters/INVENTORY.md`(adapter 파일 추가 시)와 `src/bootstrap/`(H의 T45와 I)이다. 통합 단계에서 해결한다.
|
||
|
||
## Task List (요약 — 상세는 tasks/todo.md)
|
||
|
||
### Phase 0: 기반
|
||
- [x] T01 R-0 깨끗한 체크아웃에서 게이트 동작
|
||
|
||
### Checkpoint 0
|
||
- [x] `src/.generated` 삭제 후 arch/types/lint/unit/component/verify:documentation 통과
|
||
|
||
### Phase 1: 레인 A–I (병렬)
|
||
- [x] 레인 A: T02–T05
|
||
- [x] 레인 B: T06–T10
|
||
- [x] 레인 C: T11–T16 (고위험 T12, T13, T15 포함)
|
||
- [x] 레인 D: T17–T20
|
||
- [x] 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함)
|
||
- [x] 레인 F: T26–T33 (고위험 T33 포함)
|
||
- [x] 레인 G: T34–T38 (고위험 T37 포함)
|
||
- [x] 레인 H: T39–T47
|
||
- [x] 레인 I: T48–T50 (고위험 T50 포함)
|
||
|
||
### Checkpoint 레인별 (통합할 때마다)
|
||
- [x] check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과
|
||
- [x] adapter 파일을 바꿨으면 check:adapter-inventory 통과
|
||
|
||
### Checkpoint 최종
|
||
- [x] 위 게이트 + `corepack pnpm build` 통과
|
||
- [x] 깨끗한 체크아웃 재현 통과
|
||
- [x] 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크)
|
||
|
||
## 고위험 작업 (계획 승인 = 이 작업들의 사전 승인)
|
||
|
||
| 작업 | 이유 | 안전장치 |
|
||
|---|---|---|
|
||
| T12, T13 (R-3.2) | 세션·캐시 fence 동작이 바뀜 | 상태가 실제로 바뀌면 여전히 fence됨을 테스트로 고정 |
|
||
| T15 (R-3.4) | 자격증명 헤더 검증 | 기존 정상 토큰 통과 테스트 유지 |
|
||
| T21, T22, T24 (R-5.1, R-5.2, R-5.4) | 삭제 경로 | 참조 중 청크와 다른 파티션 행은 절대 지우지 않음을 테스트로 고정 |
|
||
| T25 (R-5.5) | 저장 데이터 판독 규칙 | 기존 manifest 객체가 정책 변경 뒤에도 읽힘을 테스트로 고정 |
|
||
| T33 (R-6.7) | 푸시 동의 | 크래시 복구(local ACTIVE) 재등록은 유지됨을 테스트로 고정 |
|
||
| T37 (R-7.4) | CSRF 규칙 강화 | 설치된 기존 operation이 모두 통과함을 확인 |
|
||
| T50 (R-9.3) | 리댁션 | 정상 텔레메트리 값(enum, id)이 가려지지 않음을 테스트로 고정 |
|
||
|
||
모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다.
|
||
|
||
## Risks and Mitigations
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|---|---|---|
|
||
| worktree마다 `node_modules`가 없음 | Med | 레인 시작 시 `corepack pnpm install --frozen-lockfile --prefer-offline` |
|
||
| 레인 9개가 동시에 테스트를 돌려 느려짐 | Low | 레인 안에서는 관련 테스트만, 커밋 전에만 전체 unit/component |
|
||
| INVENTORY.md 병합 충돌 | Low | 통합 단계에서 수동 병합 후 `check:adapter-inventory` |
|
||
| 브라우저에서만 재현되는 항목(T06, T09, T26, T29, T31, T32, T44) | Med | fake로 조건을 재현. 실제 브라우저 확인은 "미검증"으로 최종 보고 |
|
||
| T20 성능 요구(10배)는 CI에서 측정하기 불안정 | Low | 정확성 테스트는 자동, 성능은 벤치 스크립트 수동 측정값을 커밋 메시지에 기록 |
|
||
| R-0 방식이 pnpm pre/post 훅에 의존하면 환경마다 다름 | Med | 훅에 의존하지 않고 진입점에서 명시적으로 생성 |
|
||
|
||
## 결과 (2026-09-24)
|
||
|
||
50개 작업을 모두 커밋했다. 레인 9개를 병합할 때마다 전체 게이트를 돌렸다.
|
||
|
||
깨끗한 체크아웃(`src/.generated` 삭제) 기준 최종 게이트 결과:
|
||
- 통과: check:architecture, check:types, lint, test:runtime-schema(53), test:unit(1890), test:contract(12), test:component(149), test:integration(104), test:recipes(17), test:reference-feature(56), test:platform(245), check:release-coherence(46), check:adapter-inventory, check:registries, check:ci, verify:documentation, build
|
||
- Playwright: test:e2e는 Chromium·Firefox 전부 통과, test:browser-capabilities도 Chromium·Firefox 전부 통과. WebKit은 이 머신에 시스템 의존성이 없어 실행 자체가 안 됨(`playwright install-deps` 필요)
|
||
|
||
계획 밖에서 추가로 한 일:
|
||
- R-0 1차 수정이 진입점 36개를 놓쳤다. 여기에는 CI 게이트 실행기 `ci:gate`와 `check:ci`가 포함된다. 가드 테스트가 import를 따라가 검사하도록 바꾸고 누락분을 채웠다(`7dfb89f`).
|
||
- `check:adapter-inventory`가 기준 브랜치에서도 실패하고 있었다(6f6c48e에서 추가한 파일 2개가 인벤토리에 없음). 행을 추가했다(`2fb07c8`).
|
||
|
||
## Open Questions (사용자 결정 필요)
|
||
|
||
1. **번들 예산**: `check:optional-recipes`가 기준 커밋부터 실패하고 있었다. 기준 커밋 대비 file-transfer는 99바이트 줄었고, realtime은 초과폭이 9바이트에서 139바이트로 늘었다. offline-indexeddb는 이번 수정으로 예산을 56바이트 새로 넘었다. 예산을 올릴지, 코드를 줄일지 결정이 필요하다.
|
||
2. **T29(R-6.3b) vs T32(R-6.6)**: fetch를 manifest URL로만 가로채도록 좁혔기 때문에, 이전 캐시 fallback은 현재 manifest에 있는 URL에만 적용된다. 리뷰의 원래 시나리오(옛 빌드 lazy chunk)는 여전히 네트워크로만 간다. 가로채는 범위를 "same-origin GET + 해시 파일명"으로 넓힐지 결정이 필요하다.
|
||
3. **T12(R-3.2a)**: 기존 owner는 subject를 제공하지 않는다. 그래서 인증 상태에서 인증 상태로 오는 알림(토큰 갱신 등)은 owner가 `readSubject`를 구현하기 전까지 여전히 캐시를 비운다. fail-closed 기본값이다.
|
||
4. **T41(R-8.8)**: disabled 쿼리는 이제 `empty`("데이터가 없습니다")로 보인다. 의존 쿼리에 이 화면이 맞지 않다면 `idle` 상태를 따로 만들어야 한다.
|
||
5. **T20(R-4.4)**: 250KB 벤치에서 ASCII는 36~80배 빨라졌지만 멀티바이트 위주 입력은 약 5배에 그쳤다. 10배 목표는 ASCII만 달성했다.
|
||
6. **T14(R-3.3)**: V2 client(`client.ts`)는 바꾸지 않았다. V2에서 HTML 바디 502는 여전히 CONTENT_TYPE_MISMATCH이고 재시도하지 않는다.
|
||
|
||
실제 브라우저에서 따로 확인해야 하는 항목: SW 두 빌드 간 업데이트 순서(T26~T30), 실제 서버의 MIME·gzip 응답(T31), 네이티브 file picker 호출(T09), `Cache.match`와 Vary(T10), 멀티 탭 OPFS 경합(T22), 모바일 드로어 포커스(T44), Safari 청크 오류 메시지(T40). WebKit 계열은 전부 미검증이다.
|
||
|
||
---
|
||
|
||
# 2차 라운드 계획
|
||
|
||
- 브랜치: `fix/src-review-round2` (main `9bef702`에서 분기)
|
||
- 범위: `SPEC.md` 2차 라운드 절, 작업 T51–T115 (`tasks/todo.md`)
|
||
- 실행 방식: 1차와 같다. 레인 A–I를 병렬 worktree에서 진행하고, 레인마다 cherry-pick한 뒤 전체 게이트를 돌린다. 마지막 T115(번들 예산)는 통합 단계에서 한다.
|
||
- 레인 사이 공유 파일: `http/retry-policy.ts`(C는 retryKinds, D는 Retry-After 파서), `http/client.ts`(C, 그리고 G의 한 줄), `web-push/push-codec.ts`(D는 중복 키 스캔, F는 나머지), `INVENTORY.md`. 충돌이 나면 통합 단계에서 해결한다.
|
||
- 최종 확인: 1차와 같은 게이트 목록 + `check:optional-recipes` + Playwright(Chromium/Firefox).
|