diff --git a/README.md b/README.md index 43178c84..9d80e44b 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ See `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/layers.md`, and `docs/architecture/starter-experience.md`. The removable vertical slice is -under `src/features/reference-feature`; its domain, application input, HTTP +the reference sample, src/features/reference-feature; its domain, application input, HTTP binding, contracts, route runtime, and presentation own their contributions. The central installed catalogs only aggregate selected contributions. The generic starter routes continue to typecheck, test, and build after that diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 8dad35c9..93cb5e97 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -72,5 +72,5 @@ What the automated run scans: calls answer an empty list there. - The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that - state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the + state is on screen (tests/e2e/reference-form.spec.ts, removed with the sample). diff --git a/docs/architecture/scale-architecture.md b/docs/architecture/scale-architecture.md index bba6bf92..aa4fad13 100644 --- a/docs/architecture/scale-architecture.md +++ b/docs/architecture/scale-architecture.md @@ -210,7 +210,7 @@ src/ The exact path layout may adapt to current repository conventions, but ownership boundaries are mandatory. -> 2026-11-03 현재: 위 그림의 최상위 `domain/` 폴더는 없다. domain 계층은 기능 안(`src/features/reference-feature/domain`)에만 있다. `src/platform`에는 `execution`·`release`·`routing`도 있다. +> 2026-11-03 현재: 위 그림의 최상위 `domain/` 폴더는 없다. domain 계층은 기능 안(`src/features//domain`)에만 있다. `src/platform`에는 `execution`·`release`·`routing`도 있다. > 색인은 생성기가 git이 무시하는 `src/.generated/`에 쓴다. 조립 코드는 `src/bootstrap/`에 있고 `compose-product.ts`라는 파일은 없다. 실제 폴더 목록의 정본은 [`layers.md`](layers.md)다. ## 5. Module Ownership diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 0a4512dc..d7911b4a 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -131,7 +131,8 @@ selected app. Every build and check script runs it first; run it yourself with invalidation, topic versions and the external `contractPackages` the release manifest is checked against at boot), its message catalogs, and `loadRuntime`, which imports `feature-runtime.ts` dynamically. - `src/features/reference-feature/feature-module.ts` is the complete example. + The reference sample's feature-module.ts (src/features/reference-feature, + while it is installed) is the complete example. 2. Create `src/features//feature-runtime.ts` with `defineFeatureRuntime`: the API contract (operations, schema metadata, runtime schemas, mappers), the adapter contributions @@ -140,7 +141,8 @@ selected app. Every build and check script runs it first; run it yourself with it (`application.features.load`) when one of the feature's routes is entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip - (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). + (tests/unit/feature-shape-growth.test.ts, which goes with the reference + sample, bounds one feature at 1 KiB). An HTTP API is written once, as its contract contribution descriptor: it executes, and `check:registries` governs the FE-REG-API row projected from it (`projectApiOperationRows` in `src/contracts/api-operations.ts`). @@ -151,7 +153,7 @@ selected app. Every build and check script runs it first; run it yourself with `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context loads this file only when its route root is visited - (`src/features/reference-feature/context-routes.ts`). Each handle's + (the reference sample's context-routes.ts shows one). Each handle's `routeId` must be a route of a feature contract in the same context; the context refuses the routes when they load, naming the route, context and features (`src/contexts/bounded-context-module.ts`). diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 2d172d24..5d1337b2 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -25,7 +25,7 @@ reader that accepts it must ship before any writer sends it. | `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` | | Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` | | HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` | -| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` | +| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in the reference sample's contracts/reference-schemas.ts | | Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` | | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` | | Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 8382286d..3e8cc92b 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -5,7 +5,7 @@ - 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature `로 만든다. - 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다. -참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. +참조 기능(src/features/reference-feature/)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. 그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다. 생성 명령은 이 문제를 미리 피한 파일을 쓴다. @@ -117,7 +117,7 @@ corepack pnpm create:feature invoice-feature - 명령 자체가 거부한다. ID 형식, 기존 기능·context와 겹침, 라우트·경로·chunk·문구 키 충돌, topic 충돌, 패키지 신원 형식. - 생성기가 거부한다. 선언 헤더가 리터럴이 아님, 없는 context, 예산 초과. - 이때 명령은 만든 파일을 모두 지우고 `the feature index generator rejected the feature, nothing was kept:`로 끝난다. -- **못 잡음**: `--context reference-context`로 참조 context에 넣으면 참조 기능 테스트 `tests/features/reference-feature/installed-context-routing.test.ts`가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. 참조 context에는 넣지 않는다. +- **못 잡음**: `--context reference-context`로 참조 context에 넣으면 참조 기능 테스트 tests/features/reference-feature/installed-context-routing.test.ts가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. 참조 context에는 넣지 않는다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design` @@ -137,7 +137,7 @@ corepack pnpm create:feature invoice-feature - 있으면 `domain/.ts`에 둔다. - 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다). -- 예제: `src/features/reference-feature/domain/` +- 예제(참조 기능): src/features/reference-feature/domain/ - 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다. - 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다. - 서버가 정한 제한이면 `contracts/-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. @@ -216,7 +216,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 2. problem 스키마를 problem details 모양으로 바꾼다. 3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. -참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. +참조 기능(src/features/reference-feature/)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. **입력과 스키마 메타데이터** @@ -341,7 +341,7 @@ projectRequest: (input) => Object.freeze({ - 참조 기능은 생성 operation에 목록 route(`REFERENCE_RESOURCE_LIST`)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다. - `needs`에는 실제로 쓰는 것만 적는다. - 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. [03 문서](03-outside-feature-folder.md)를 본다. -- 문제 응답 매핑 예제: `src/features/reference-feature/adapters/reference-http-gateway.ts` +- 문제 응답 매핑 예제(참조 기능): src/features/reference-feature/adapters/reference-http-gateway.ts ③ **잡는 검사 / 못 잡는 것** @@ -384,8 +384,8 @@ projectRequest: (input) => Object.freeze({ ② **기준** - 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. -- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제: `src/features/reference-feature/context-routes.ts`. - - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 생성된 판은 파라미터가 없어서 넘기지 않는다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제: `src/features/reference-feature/presentation/reference-routes.ts`. +- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): src/features/reference-feature/context-routes.ts. + - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 생성된 판은 파라미터가 없어서 넘기지 않는다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): src/features/reference-feature/presentation/reference-routes.ts. - 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다. - 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다. - `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`). @@ -443,7 +443,7 @@ projectRequest: (input) => Object.freeze({ - 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다. - `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고). - `KEYED` 쓰기는 `requiresIdempotencyKey: true`, `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다. - - 예제: `src/features/reference-feature/presentation/use-reference-feature.ts`의 생성 뮤테이션 정책. + - 예제(참조 기능): src/features/reference-feature/presentation/use-reference-feature.ts의 생성 뮤테이션 정책. ③ **잡는 검사 / 못 잡는 것** @@ -472,7 +472,7 @@ projectRequest: (input) => Object.freeze({ - 화면 문구는 모두 catalog에서 가져온다(`message(key)`). - 링크는 6단계의 URL 함수로 만든다. -- 결과 불명 화면 예제: `src/features/reference-feature/presentation/reference-resource-form-page.tsx` +- 결과 불명 화면 예제(참조 기능): src/features/reference-feature/presentation/reference-resource-form-page.tsx ③ **잡는 검사 / 못 잡는 것** @@ -564,7 +564,7 @@ projectRequest: (input) => Object.freeze({ expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." }); ``` - - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트. + - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): tests/features/reference-feature/reference-production-vertical.test.tsx의 504 재전송 테스트. - 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/` - CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 96fe6213..be27717d 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -166,7 +166,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다. -**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`). 예제: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`의 `CREATE_EFFECT`. +**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`). 예제(참조 기능): src/features/reference-feature/contracts/reference-feature-contract-contribution.ts의 `CREATE_EFFECT`. **틀리면** diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index 5e26a4bb..5321f33e 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -134,6 +134,6 @@ corepack pnpm generate:feature-index ## 알려진 한계 -- `--context reference-context`로 참조 context에 넣으면 `tests/features/reference-feature/installed-context-routing.test.ts`가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. +- `--context reference-context`로 참조 context에 넣으면 참조 기능 테스트 tests/features/reference-feature/installed-context-routing.test.ts가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. - 드릴은 `check:bundle`(FE-GATE-012), 브라우저 테스트(`test:a11y`, `test:e2e`)를 돌리지 않는다. - 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 `--context`로 기존 context를 고른다. diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index c8e49e09..7bb3f1d1 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -3,7 +3,7 @@ 기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다. - **정의**: 플랫폼(기능 밖)에서 패턴을 제공하는 파일. -- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `참조 기능`은 `src/features/reference-feature/`다. +- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `참조 기능`은 src/features/reference-feature/다. 참조 기능은 지울 수 있으므로 그 경로는 백틱 없이 적는다. 백틱 경로는 문서 검사(`verify:documentation`)가 존재를 확인한다. - 예제가 없는 패턴은 **없음**이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다. 참조 기능은 예제일 뿐이다. 복사해 이름을 바꾸지 않는다. 모양을 보고 생성 뼈대에 옮긴다. @@ -13,12 +13,12 @@ | 패턴 | 정의 | 예제 | 검사 | |---|---|---|---| | 기능 모듈 등록 | `src/features/feature-module.ts` (`defineFeatureModule`, `defineFeatureRuntime`), 생성기 | 생성 뼈대 `feature-module.ts`, `feature-runtime.ts` | 생성기, 기능 ID와 계약 `featureId` 일치 | -| context 소속 선언 | `src/contexts/bounded-context-module.ts` | `src/contexts/reference-context/context-module.ts` | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | +| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 src/contexts/reference-context/context-module.ts | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | | context 전용 레이아웃 | `docs/architecture/starter-experience.md` "Product home and layouts" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` | | 앱 홈 대신하기 | `src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` | 없음 (기능 예제) | 조립 (두 기능이 `APP_HOME`을 선언하면 실패) | | 조립 기여(`needs`) | `src/features/feature-adapter-contribution.ts` | 생성 뼈대 `adapters/create--feature-input.ts` | 조립 (없는 capability, 다른 기능의 input) | | 제품 capability | `src/bootstrap/product-composition.ts`, `src/bootstrap/product-composition-contract.ts` | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `check:types` | -| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | `tests/component/product-feature-switch.test.tsx` | +| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 tests/component/product-feature-switch.test.tsx | ## 라우트 diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 6bf1c888..10371362 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -22,7 +22,7 @@ Performance evidence is deliberately split by measurement context: | 초기 JS 예산 | 204,800 gzip bytes(200 KiB) | | 템플릿 기준선(2026-11-01, 커밋 `298201f`) | 202,509~202,522 gzip bytes, 16개 파일. local 프로필, `VITE_BUILD_ID`가 `local-build`일 때와 CI 모양(`gitea--`)일 때다. 빌드 ID가 번들에 들어가므로 빌드마다 수십~수백 바이트 다르다 | | 여유 | 약 2,280 bytes(1.1%) | -| 기능 하나를 더할 때 | 참조 기능 모양 복사본 하나에 약 +650~750 bytes(`298201f` 측정, 상한은 `tests/unit/feature-shape-growth.test.ts`의 1 KiB). 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다 | +| 기능 하나를 더할 때 | 참조 기능 모양 복사본 하나에 약 +650~750 bytes(`298201f` 측정, 상한은 참조 기능과 함께 지워지는 tests/unit/feature-shape-growth.test.ts의 1 KiB). 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다 | | lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 lazy JS는 17개, 합계 28,204 bytes이고 가장 큰 것은 `use-reference-feature` 8,386 bytes다 | 청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈 diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index dab5ac93..f9b3e88c 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -18,6 +18,8 @@ import { pruneRemovalFixtureCiContract, pruneScriptOrchestration, regenerateRemovalFixtureWorkflow, + REMOVAL_FIXTURE_COPY_TARGETS, + REMOVAL_FIXTURE_DOCUMENT_TARGETS, renderRemovalJunit, requireRemovalFixtureEnvironment, runRemovalFixtureCheck, @@ -201,7 +203,14 @@ function outcome(name: string, findings: readonly string[], label: string): Remo } try { - await prepareRemovalFixture(fixtureRoot); + // 1103/14-04. The documents come too: removing a feature must leave them + // valid, and the fixture used to leave them out with the tests that read + // them, so a manual naming the sample's files passed here and then failed + // FE-GATE-017 in the product that removed it. + await prepareRemovalFixture(fixtureRoot, [ + ...REMOVAL_FIXTURE_COPY_TARGETS, + ...REMOVAL_FIXTURE_DOCUMENT_TARGETS, + ]); for (const excludedFixtureTest of [ "tests/unit/ci-workflow-generation.test.ts", "tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap", @@ -395,6 +404,13 @@ try { } const gateChecks = (prefix: string): RemovalCheck[] => [ check(`${prefix}typecheck`, "check:types"), + // 1103/14-04 (FOLLOW-UP 09-07). Merge and documentation gates the drill + // did not run: the documents, lint, screen text and design tokens can + // name or use what the removal deleted. + check(`${prefix}lint`, "lint"), + check(`${prefix}documentation`, "verify:documentation"), + check(`${prefix}i18n`, "check:i18n"), + check(`${prefix}design-system`, "check:design-system"), check(`${prefix}architecture`, "check:architecture"), check(`${prefix}registries`, "check:registries"), check(`${prefix}unit-integration`, "test:all"),