Files
clean-architecture-frontend…/docs/architecture/static-delivery.md
T
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다.
- capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」,
  「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture
  (tests/fixtures/indexeddb-consumer)다.
- static-delivery: initialJavascript.files가 「예시 feature 기준」이라고
  한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고
  적는다.
- .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다.
- runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어
  원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다.
- ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다.
  4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds").
- 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로
  문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다.

고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다.
Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를
쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부
title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과
날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다.

위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로).
cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을
비교하는 시험은 없다.

검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json,
layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은
desktop에서 돌린다.
2026-11-12 09:40:51 +09:00

63 lines
3.7 KiB
Markdown

# 정적 자산과 runtime 설정 전달
> **정본 안내 (runtime capability 결정의 정본이 아니다)**
>
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
> Service Worker, offline command와 Background Sync의 구현 결정은
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`에 적힌 정본 static-delivery
draw.io 범위에만 적용된다.
```mermaid
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`](../operations/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`](../operations/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`](../operations/release-cache-rollback.md#운영-환경이-지켜야-할-조건)의
「운영 환경이 지켜야 할 조건」에 있다.