15 KiB
변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 README.md의 "Updating a copied project" 절에 있다.
- 버전은 git 태그
vX.Y.Z로 식별한다. 태그 사이의 변경을 여기 적는다. - [보안] 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다.
- [계약] 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트).
- 표시가 없으면 템플릿 안에서 끝나는 수정이다.
- 괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다.
- 커밋 해시는 브랜치
fix/maturity-review-2026-09-25기준이다. 병합 방식에 따라main에서는 해시가 다를 수 있으니 ID로 찾는다(git log --grep '03-03').
0.2.0 — 태그 v0.2.0 (2026-09-27)
2026-09-25 성숙도 리뷰(docs/reviews/2026-09-25-maturity-review/) 수정 묶음이다.
기준은 main 4626b73이다. package.json의 version은 0.2.0이다.
보안·계약 변경
먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 x-correlation-id 헤더를 하나 보낸다. 다른 origin API는 preflight Access-Control-Allow-Headers에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 Access-Control-Expose-Headers에도 넣는다 (03-03) |
src/adapters/http/http-execution-v3.ts, src/adapters/http/feature-http-binding.ts, src/bootstrap/runtime-adapters.ts, docs/operations/api-contract-and-server-state-recovery.md |
c5da3cf, f0a6495 |
| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (03-01, 08-03) | src/presentation/adapters/query/application-query.ts, src/presentation/forms/use-app-form.ts, src/presentation/components/async-surface.tsx |
dfb1b9e |
| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(classifyStatus, 선택 필드). 재로그인이 먼저다 (03-02) |
src/adapters/http/http-effect-certainty.ts, src/adapters/http/http-execution-v3.ts, src/contracts/errors.ts, src/contracts/external-contract-runtime.ts |
2afee67 |
| [계약] | 422 problem body의 필드 오류(path, code)를 폼까지 전달한다 (03-04) |
src/adapters/http/feature-http-binding.ts, src/features/reference-feature/contracts/reference-schemas.ts |
479acd5 |
| [계약] | 텔레메트리 수집기 이벤트마다 build_id, release_id가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (13-11, 03-05) |
src/adapters/telemetry/telemetry-collector.ts, src/bootstrap/runtime-adapters.ts |
43e47f4, e14c613 |
| [보안] | 번들이 읽지 않는 VITE_* 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, ENV_REGISTRY에 없는 VITE_* 이름은 빌드를 멈춘다 (13-06) |
src/contracts/env.ts, vite.config.ts, eslint.config.ts |
2ec59ad |
| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (05-03, 05-04) | src/adapters/platform/indexeddb-connection.ts, src/adapters/storage/indexeddb/indexeddb-runtime.ts, src/adapters/storage/opfs/opfs-byte-store-adapter.ts, src/application/ports/browser-file-storage/ |
3e37fbf, 6ab564f |
| [계약] | RELEASE_TARGET이 APP_PROFILE과 다르면 배포 승인이 거절된다 (12-02, 13-01) |
scripts/check-release-admission.ts, .gitea/workflows/quality-gates.yml |
239b22a |
| [계약] | 설정·매니페스트 URL이 VITE_ROUTER_BASE_PATH를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (13-07) |
scripts/generate-runtime-config.ts, src/contracts/env.ts, vite.config.ts |
e215c84 |
| [계약] | VITE_PRODUCT_FEATURES는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (09-02) |
scripts/generate-product-feature-index.ts, src/contracts/product-features.ts |
a8111f7 |
| [계약] | src/features/<id>/에 feature-module.ts도 NOT_INSTALLED 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 --feature=<id>를 받는다 (09-07, 14-03) |
scripts/generate-product-feature-index.ts, scripts/test-sample-removal.ts, config/contracts/registry-governance.json, docs/architecture/starter-experience.md |
ad0e83c |
| [계약] | 기능 루트·context·app 파일은 src/adapters를 import할 수 없다. presentation은 app·context를 import할 수 없다(app-router.tsx 예외) (12-03) |
scripts/check-architecture.ts, .dependency-cruiser.json, docs/architecture/layers.md |
f8b6a36 |
| [계약] | CI 계약의 게이트 수·해시가 config/ci/contract-baseline.json으로 옮겨졌다. 게이트를 바꾸면 update:ci-contract-baseline로 갱신한다 (14-02) |
config/ci/contract-baseline.json, scripts/check-ci-contract.ts |
0114b1e |
| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 config/ci/ungated-tests.json에 이유가 있어야 한다 (12-04, 09-11, 11-03) |
config/ci/gates.json, config/ci/ungated-tests.json, scripts/lib/ungated-tests.ts |
840de45, 45ee231 |
| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 UNVERIFIED(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (08-06, 11-01, 13-03, 13-05) |
config/ci/gates.json, .gitea/workflows/quality-gates.yml, scripts/drill-runbook.ts, docs/operations/ci-quality-gates.md |
7298275, 7f889a6, a263d8c |
| [계약] | engineStrict, saveExact를 pnpm-workspace.yaml로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (13-09) |
pnpm-workspace.yaml, .npmrc |
a5dc851 |
| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (08-01) | src/presentation/forms/form-contracts.ts, src/presentation/forms/use-app-form.ts, src/presentation/forms/form-components.tsx |
9894a70 |
| [계약] | browser-transfer 포트: upload() 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 resourceId를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 |
src/application/ports/browser-transfer/, src/adapters/browser-transfer/ |
648fe4e, 7b2cefb, 5a6665a, 426b6b8 외 |
| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 INCOMPATIBLE, 빈 receipt는 없음으로 본다 (05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 |
src/application/ports/browser-file-storage/, src/adapters/storage/ |
7f45afa, 47cf040, 8fc816e 외 |
| [계약] | 외부 세션 owner의 readSubject()와 SessionGateway.getSubject()가 필수가 됐다. readSubject가 없는 owner는 integration-failed로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 |
src/adapters/auth/external-session-adapter.ts, src/application/ports/, docs/architecture/starter-experience.md |
c6300e9 |
| [보안] | 운영 CSP(unsafe-eval 없음) 아래에서 zod가 eval을 시험하지 않는다. src/의 코드는 zod를 src/contracts/zod.ts로만 가져온다(dependency-cruiser 규칙) (13-08, F-7) |
src/contracts/zod.ts, .dependency-cruiser.json, tests/e2e/production-csp.spec.ts |
9dc95ca |
| [계약] | 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (07-02, 13-10) | src/contracts/compatibility.ts, scripts/check-registries.ts, config/contracts/ |
17d617a |
| [계약] | 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 @deprecated와 제거 조건을 붙였다 (07-04, 07-07) |
src/contracts/errors.ts, src/contracts/ |
aff5f43, 9e616d3 |
| [계약] | staging·production 빌드는 VITE_BUILD_ID가 없으면 실패한다 (13-15, F-6) |
scripts/generate-runtime-config.ts, src/contracts/env.ts |
063375e |
| [계약] | Service Worker 빌드가 public/config.json 대신 프로필에서 만든 dist/config.json을 읽고, APP_ENV가 APP_PROFILE과 다르면 빌드를 멈춘다 (06-10, F-8) |
vite.service-worker.config.ts, scripts/lib/service-worker-build-input.ts |
cefb0b2 |
| [계약] | Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. REMOVE_REGISTRATION은 스스로 등록을 해지하는 worker를 배포한다 (06-02, 06-06, 06-03) |
src/adapters/web-push/, scripts/lib/self-unregistering-service-worker.ts, docs/runbooks/ |
e6c683e, 996a959, 9f2305a |
| [계약] | realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE Retry-After를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 |
src/adapters/realtime/, config/recipes/frontend-capability-recipes.json |
bcad7b0, 02d3fdf, 7e37660, 2c5e268 외 |
| [계약] | browser-files 포트: 같은 턴의 abort는 ABORTED, 닫은 선택 창은 DISMISSED, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 |
src/adapters/browser-file-storage/, src/adapters/cache-storage/ |
c9be8d6, d76653b, 0b41cb3, 55c0bf5 외 |
| [계약] | 샘플 상세 경로가 /examples/reference-resources/items/:resourceId로 옮겨졌다. ID가 new·status인 항목도 상세가 열린다 (08-13) |
src/features/reference-feature/contracts/reference-feature-contract.ts, config/contracts/registry-change-evidence.json |
d7b81c6 |
| [계약] | tsconfig.base.json에 noUnusedLocals를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 check:types에서 실패한다 (12-12) |
tsconfig.base.json |
49413af |
그 밖의 수정
-
부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (09-03, 09-04, 09-10).
src/bootstrap/,src/presentation/boundaries/boot-error-shell.tsx -
부트:
FEATURE_OVERRIDES의 모르는 키를 진단으로 남긴다 (09-09).src/bootstrap/runtime-adapters.ts,scripts/check-release-admission.ts -
빌드:
dist파일을 다른 사용자도 읽을 수 있게 한다 (13-02).scripts/lib/dist-permissions.ts -
공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (13-12, 13-04).
scripts/lib/vite-module-inventory.ts,scripts/verify-exact-promotion-bundle.ts -
아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (12-05~12-11).
scripts/check-architecture.ts -
기능 조립:
needs검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (09-01, 09-05, 09-06, 09-08, 09-12, 00-02).src/features/,src/bootstrap/runtime-adapters.ts -
테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (13-08, 01-04, 05-08, 10-03)
-
샘플 제거:
test:sample-removal이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (14-01, 14-08, 00-01, 10-01).scripts/test-sample-removal.ts,scripts/lib/removal-fixture.ts -
문서: README에 런타임 프로필·배포 변수·우선순위를 적고
verify:documentation이 변수 목록을 검사한다 (13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (13-13, 13-14, 03-06, 03-08). -
화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (07-01, 08-02, 08-04, 08-07~08-12, F-10).
src/presentation/,src/presentation/i18n/ -
접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (08-05, 11-02).
tests/e2e/accessibility.spec.ts -
계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (07-03, 07-05, 07-06, 09-07, F-3).
tests/unit/,src/contracts/ -
Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (06-01, 06-04, 06-05, 06-07~06-09).
src/adapters/web-push/,src/adapters/service-worker/,src/bootstrap/ -
테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (10-02, 10-04
10-07, 11-0411-08, F-2).tests/,scripts/scale/,scripts/lib/lab-performance.ts -
테스트 fixture가 공유
node_modules를 다시 쓰지 않고, 임시 폴더를 지운다 (F-4, F-12, 00-03).scripts/lib/removal-fixture.ts,tests/unit/ -
문서: 손으로 적은 게이트 수와 LOC를 지우고
verify:documentation의 검사 범위를 적었다 (14-07)
알려진 제한
- Playwright spec은 chromium·firefox·webkit에서 확인했다. WebKit에서만 난 실패 1건(구 탭 청크 복구 spec의 콘솔 문구 허용 목록)은
b1a36ab로 고쳤다. - 사용자 몫(SPEC "범위 밖" U-1~U-5, F-11)은 이 버전에 들어 있지 않다.
0.1.0 — main 4626b73 (2026-09-24)
태그가 없는 main이고 package.json 버전은 0.1.0이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | src/adapters/http/http-contract-bridge.ts, src/adapters/auth/external-session-adapter.ts |
5e62b7e |
| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | src/contracts/api-operations.ts |
f26fd18 |
| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | src/platform/telemetry/redact-telemetry.ts |
4e0745c |