Merge lane M: template product and documentation fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# 변경 이력
|
||||
|
||||
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
|
||||
가져오는 방법은 `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 — 진행 중
|
||||
|
||||
2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다.
|
||||
기준은 `main` `4626b73`이다. 통합이 끝나면 태그 `v0.2.0`을 붙이고 이 절을 확정한다.
|
||||
`package.json`의 `version`은 아직 `0.1.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` 외 |
|
||||
|
||||
### 그 밖의 수정
|
||||
|
||||
- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (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).
|
||||
|
||||
### 진행 중 (아직 통합되지 않음)
|
||||
|
||||
아래 레인은 별도 브랜치에서 작업 중이다. 통합되면 위 두 절로 옮긴다.
|
||||
|
||||
- 레인 B — browser-files·Cache Storage (02-01~02-09)
|
||||
- 레인 D — realtime (04-01~04-08)
|
||||
- 레인 F — Service Worker·Web Push (06-01~06-10). 푸시 구독 해지와 SW 빌드 설정이 바뀐다
|
||||
- 레인 G — contracts 호환성 규칙과 FE-GATE-014 (07-02~07-07, 13-10)
|
||||
- 레인 H — presentation 문구·접근성·라우트 (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02)
|
||||
- 레인 J — 테스트 체계 (10-02, 10-04~10-07, 11-04~11-08)
|
||||
- 레인 M — 이 변경 이력, 문서 색인(`docs/README.md`), README 지원 범위 표, `public/config.json` 동기화 검사 (14-04~14-06, 13-15 후속)
|
||||
- 통합 뒤 — `noUnusedLocals`, 문서 수치 현행화 (12-12, 14-07)
|
||||
|
||||
## 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` |
|
||||
@@ -33,8 +33,8 @@ build` writes `dist/config.json` from the selected profile
|
||||
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
|
||||
profile for `corepack pnpm dev`; the build replaces it, so settings put there
|
||||
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
|
||||
`BUILD_ID: local-build` and `RELEASE_ID: local-release`; nothing checks that
|
||||
yet.
|
||||
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
|
||||
`tests/unit/deployment-admission.test.ts` fails when the two differ.
|
||||
|
||||
Build and deploy variables, lowest precedence first:
|
||||
|
||||
@@ -91,6 +91,46 @@ owner described in
|
||||
The client route policy is user experience only; server authorization remains
|
||||
authoritative.
|
||||
|
||||
## Support scope
|
||||
|
||||
Four tiers. The status words on the right are the ones the catalogs and
|
||||
design documents use; the next table maps them.
|
||||
|
||||
| Tier | What it covers | Status words |
|
||||
| --- | --- | --- |
|
||||
| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and the removable reference feature. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
|
||||
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
|
||||
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed | `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
|
||||
|
||||
The rows come from
|
||||
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
|
||||
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
|
||||
and
|
||||
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
|
||||
|
||||
| Status word | Where it appears | Meaning | Tier |
|
||||
| --- | --- | --- | --- |
|
||||
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
|
||||
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
|
||||
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
|
||||
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features/<id>/NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) |
|
||||
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
|
||||
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
|
||||
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
|
||||
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
|
||||
|
||||
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
|
||||
verdicts on evidence, not support tiers.
|
||||
|
||||
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
|
||||
iOS 16.4. That is the higher of Vite 8's default JavaScript target
|
||||
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
|
||||
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
|
||||
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
|
||||
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
|
||||
versions inside the target range and real mobile browsers are not tested.
|
||||
|
||||
## Architecture
|
||||
|
||||
This repository is a **Frontend Application Foundation**: a starter/composition
|
||||
@@ -144,6 +184,29 @@ project-owned integrations. They are target designs and review findings; a
|
||||
capability is not treated as implemented until its branch acceptance criteria
|
||||
and executable gates pass.
|
||||
|
||||
## Documentation
|
||||
|
||||
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
|
||||
target designs and work history.
|
||||
|
||||
### Files you can delete after copying
|
||||
|
||||
These record how the template was built. Nothing in the build or the gates
|
||||
reads them, except the one file noted below.
|
||||
|
||||
| Path | Contents |
|
||||
| --- | --- |
|
||||
| `docs/superpowers/` | past plans and specs |
|
||||
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
|
||||
| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round |
|
||||
| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own |
|
||||
|
||||
The reference feature is not in this list: deleting its directory alone
|
||||
leaves tests, policy entries and CI scripts behind that fail the gates.
|
||||
`scripts/test-sample-removal.ts` removes it from a copy of
|
||||
the repository and lists everything that has to go with it (its header comment
|
||||
and `SAMPLE_EXTRAS`); do the same in your project and run the gates.
|
||||
|
||||
## Verification
|
||||
|
||||
Common local checks:
|
||||
@@ -247,3 +310,43 @@ ignored by Git while `.gitkeep` files preserve the taxonomy.
|
||||
|
||||
Operational details are in `docs/operations/`, with incident procedures in
|
||||
`docs/runbooks/`.
|
||||
|
||||
## Updating a copied project
|
||||
|
||||
Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists
|
||||
the changes between tags, marks security fixes **[보안]** and contract changes
|
||||
**[계약]** (backend, deployment, CI or feature code must change too), and names
|
||||
the affected paths.
|
||||
|
||||
Record where you started. Right after copying, commit a one-line
|
||||
`.template-origin` file at the root of your project with the template tag (or
|
||||
commit) you copied and the date, for example `v0.2.0 2026-09-26`.
|
||||
|
||||
Take a template fix with Git. `cherry-pick` works even when your repository
|
||||
does not share the template's history, because it merges against the picked
|
||||
commit's parent:
|
||||
|
||||
```bash
|
||||
git remote add template <template repository URL>
|
||||
git fetch template --tags
|
||||
git log --oneline <your origin>..template/main # what changed since you copied
|
||||
git cherry-pick -x <commit> # one fix; -x records its origin
|
||||
```
|
||||
|
||||
When the files have moved or diverged too far for a clean pick, read the
|
||||
change as a diff and apply it by hand:
|
||||
|
||||
```bash
|
||||
git diff <commit>^ <commit> -- <paths from CHANGELOG>
|
||||
```
|
||||
|
||||
Afterwards run the local merge gates from "CI and evidence", apply the
|
||||
backend or deployment change a **[계약]** row names, and update
|
||||
`.template-origin` once you have caught up to a tag. `git revert` undoes a pick.
|
||||
|
||||
Defects: if a problem reproduces on an unmodified checkout of your
|
||||
`.template-origin` commit, it is a template defect. Report it on the template
|
||||
repository with that commit and the reproduction; the template maintainer
|
||||
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
|
||||
your changes to reproduce belongs to your project, and applying a template fix
|
||||
to your copy is your project's job.
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# 문서 색인
|
||||
|
||||
`docs/`의 문서를 세 묶음으로 나눈다.
|
||||
|
||||
```text
|
||||
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
|
||||
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
|
||||
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
|
||||
```
|
||||
|
||||
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
|
||||
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
|
||||
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
|
||||
|
||||
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
|
||||
|
||||
## 1. 현재 계약
|
||||
|
||||
처음 읽을 입구 문서 6개다.
|
||||
|
||||
| 문서 | 정하는 것 |
|
||||
|---|---|
|
||||
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
|
||||
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
|
||||
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
|
||||
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
|
||||
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
|
||||
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
|
||||
|
||||
입구 문서가 가리키는 세부 규칙:
|
||||
|
||||
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
|
||||
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
|
||||
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
|
||||
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
|
||||
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
|
||||
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
|
||||
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
||||
|
||||
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
|
||||
|
||||
| 파일 | 읽는 명령 |
|
||||
|---|---|
|
||||
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
|
||||
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
|
||||
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` |
|
||||
|
||||
## 2. 목표 설계
|
||||
|
||||
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
|
||||
|
||||
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
|
||||
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
|
||||
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
|
||||
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
|
||||
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
|
||||
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
|
||||
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
|
||||
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
|
||||
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
|
||||
|
||||
## 3. 작업 이력·리뷰
|
||||
|
||||
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
|
||||
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
|
||||
"Files you can delete after copying" 절에 있다.
|
||||
|
||||
| 경로 | 내용 |
|
||||
|---|---|
|
||||
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
|
||||
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다 |
|
||||
| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |
|
||||
@@ -244,18 +244,16 @@ try {
|
||||
|
||||
// Runtime profiles are product configuration. Once the feature is physically
|
||||
// removed, its override key must disappear too or the built config still
|
||||
// advertises a source capability that no longer exists.
|
||||
for (const profile of [
|
||||
"local",
|
||||
"development",
|
||||
"staging",
|
||||
"production",
|
||||
] as const) {
|
||||
const profilePath = path.join(
|
||||
fixtureRoot,
|
||||
"config/runtime",
|
||||
`${profile}.json`,
|
||||
);
|
||||
// advertises a source capability that no longer exists. public/config.json
|
||||
// is the local profile `dev` serves and has to stay equal to it (F-5).
|
||||
for (const configPath of [
|
||||
"config/runtime/local.json",
|
||||
"config/runtime/development.json",
|
||||
"config/runtime/staging.json",
|
||||
"config/runtime/production.json",
|
||||
"public/config.json",
|
||||
]) {
|
||||
const profilePath = path.join(fixtureRoot, configPath);
|
||||
const runtimeConfig = JSON.parse(
|
||||
await readFile(profilePath, "utf8"),
|
||||
) as {
|
||||
|
||||
@@ -204,6 +204,13 @@ describe("runtime config profiles", () => {
|
||||
).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
// F-5 (13-15). `corepack pnpm dev` serves public/config.json while every
|
||||
// build writes the local profile instead, so the two copies must not drift.
|
||||
it("keeps public/config.json equal to what a local build writes", async () => {
|
||||
const served: unknown = JSON.parse(await readFile("public/config.json", "utf8"));
|
||||
expect(served).toEqual(await generateRuntimeConfig("local", {}));
|
||||
});
|
||||
|
||||
// 13-01: the build profile and the admission target are two repository
|
||||
// variables. A staging profile left in place for a production release has to
|
||||
// stop the release, whatever the built document happens to say.
|
||||
|
||||
Reference in New Issue
Block a user