Files
clean-architecture-frontend…/docs/architecture/static-delivery.md
T
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.

고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
  README, starter-experience, static-delivery, compatibility,
  backend-api-and-server-state-contract, manual-checklist,
  adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
  참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
  적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
  1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
  지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
  measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
  안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
  위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
  and scripts only where verify:documentation checks them"을 더했다. 검사기가
  읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
  기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
  같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
  커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
  검사기와 같은 규칙을 두 곳에 두게 된다.

위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
  백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
  아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal

Refs: 1105/14-03
2026-11-06 02:59:02 +09:00

63 lines
3.2 KiB
Markdown

# Static asset and runtime-config delivery
> **정본 안내 (non-authoritative for runtime capability decisions)**
>
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
> Service Worker, offline command와 Background Sync의 구현 결정은
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](./2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
This Mermaid view is a repository-local implementation projection. The
`PASS_SCOPED` reviewer evidence applies only to the canonical static-delivery
draw.io scope recorded in `review-ledger.json`.
```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
```
In this repository the workflow deploys nothing. The upload, pointer switch
and smoke steps above belong to the project's provider adapter, which fills the
`deployment` job between `promotion` and `production_gate`. After it has
deployed the promoted release, FE-GATE-019 probes the live headers and checks
that the host serves that release; while the slot is empty FE-GATE-019 is
`UNVERIFIED` (reviews 13-05, 1101/13-01,
[`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
Serve the app over HTTP/2 or later. The entry preloads every initial
JavaScript file in parallel (`initialJsFiles` in
`config/performance/budgets.json` bounds how many; the current count is
`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per
host, and the first screen on Fast 3G came about one second later than with the
initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under
100 ms, so the template keeps the chunks split. A product that can only serve
HTTP/1.1 groups its initial chunks in `vite.config.ts` and measures again
whenever the shell changes ("초기 청크 수와 HTTP/1.1" in
[`performance-evidence.md`](../operations/performance-evidence.md), review
1101/14.4).
Serve JavaScript compressed (gzip, brotli or zstd). The bundle budget counts
gzip bytes; uncompressed, the initial JavaScript is about three times larger.
Both premises are declared in `config/hosting/cache-policy.json`
(`transport.alpnProtocols`, `hashedAsset.contentEncodings`), and the live probe
of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). The
nginx example in
[`release-cache-rollback.md`](../operations/release-cache-rollback.md) turns
both on.