Files
clean-architecture-frontend…/docs/architecture/static-delivery.md
T
DongHyeonka af10cae9a6 docs(architecture): 현재 계약 문서와 매뉴얼의 영어 부분을 한국어로 옮긴다
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
  자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
  (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
  docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
  바꾼다(number 검사)

위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.

검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
2026-11-08 21:57:47 +09:00

3.7 KiB

정적 자산과 runtime 설정 전달

정본 안내 (runtime capability 결정의 정본이 아니다)

Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker, Service Worker, offline command와 Background Sync의 구현 결정은 프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계가 정본이다. 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.

이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다. PASS_SCOPED 리뷰 증거는 review-ledger.json에 적힌 정본 static-delivery draw.io 범위에만 적용된다.

sequenceDiagram
  participant CI
  participant ImmutableRelease
  participant ActivePointer
  participant Browser
  CI->>ImmutableRelease: upload hashed assets
  CI->>ImmutableRelease: upload release manifest
  CI->>ImmutableRelease: upload runtime config
  CI->>ImmutableRelease: probe asset reachability
  CI->>ActivePointer: atomically switch HTML
  Browser->>ActivePointer: fetch revalidated HTML
  Browser->>ImmutableRelease: fetch no-store config and manifest
  Browser->>ImmutableRelease: fetch immutable hashed assets
  CI->>Browser: boot, route, API, and reload-loop smoke

이 repo에서 workflow는 아무것도 배포하지 않는다. 위의 업로드, pointer 전환, smoke 단계는 프로젝트의 provider adapter가 맡는다. 그 adapter가 promotion과 production_gate 사이의 deployment job을 채운다. adapter가 promotion된 release를 배포하고 나면, FE-GATE-019가 실제 응답 header를 검사하고 host가 그 release를 서빙하는지 확인한다. 그 자리가 비어 있는 동안 FE-GATE-019는 UNVERIFIED다(리뷰 13-05, 1101/13-01, release-cache-rollback.md).

rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음이 서로 맞는지 확인한 뒤에만 active pointer를 바꾼다.

앱은 HTTP/2 이상으로 서빙한다. 진입점은 모든 초기 JavaScript 파일을 병렬로 미리 불러온다(preload). 몇 개까지 허용할지는 config/performance/budgets.json의 initialJsFiles가 정한다. 지금 개수는 config/scale/feature-shape-ceilings.json의 initialJavascript.files이고, 이 값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라 파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약 1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서 템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은 vite.config.ts에서 초기 chunk를 묶는다. 그리고 shell이 바뀔 때마다 다시 잰다(performance-evidence.md의 「초기 청크 수와 HTTP/1.1」, 리뷰 1101/14.4).

JavaScript는 압축해서(gzip, brotli, zstd 중 하나) 서빙한다. 번들 budget은 gzip 바이트를 센다. 압축하지 않으면 초기 JavaScript가 약 세 배 커진다. 두 전제는 config/hosting/cache-policy.json에 선언되어 있다 (transport.alpnProtocols, hashedAsset.contentEncodings). FE-GATE-019의 실제 host 검사(live probe)는 이 전제를 지키지 않는 host를 실패시킨다(리뷰 1103/13-02). host가 지켜야 할 조건 전부와 각 조건을 무엇이 검사하는지는 release-cache-rollback.md의 「운영 환경이 지켜야 할 조건」에 있다.