diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index e13b7b4e..c1353836 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -374,7 +374,8 @@ projectRequest: (input) => Object.freeze({ - `presentation/-feature-runtime.ts`: 지연 로드 페이지 표. `moduleId`는 계약과 같아야 한다. - `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다. - `presentation/-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다. -- 문구 `route..title`, `route..navigation` (ko-KR, en-US). +- 문구 `route..title`, `route..navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다. + - 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다. - 기능 폴더 밖: `artifacts/tests/a11y-manual/.md`(pending 기록). 생성 명령이 만든다. ① **정할 것** @@ -473,7 +474,7 @@ projectRequest: (input) => Object.freeze({ - topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다. - 뮤테이션 정책의 operation ID를 `commandMutationIdentity`로 받으면 descriptor 상수 이름의 오타는 `check:types`가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때 `commandMutationIdentity: is a GET; a mutation binds a write operation`으로 throw한다. - **못 잡음**: 뮤테이션 정책에 operation ID를 문자열로 직접 적은 것. 타입이 `string`이라 오타가 통과하고, 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). `commandMutationIdentity`를 쓴다. -- **못 잡음**: `bindQuery`의 `operationId` 오타. 타입이 `string`이라 operation과 묶이지 않는다. +- `bindQuery`의 `owner`·`operationId`, 뮤테이션 정책의 `owner`는 적지 않는다. 읽는 곳이 없어 `@deprecated` 선택 칸이 됐고, 다음 릴리스에서 지운다. 요청 기록의 operation ID는 descriptor의 것이다. - **못 잡음**: `definitionId` 중복. 유일성 검사가 없다. ④ **쓸 스킬**: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다. diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index 99a34e4c..96724a2c 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -93,7 +93,7 @@ const search = (q: string) => | 패턴 | 정의 | 예제 | 검사 | |---|---|---|---| -| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use--items.ts` | profile ID (실행 때). `operationId`는 `string`이라 묶이지 않음 | +| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use--items.ts` | profile ID (실행 때). `owner`·`operationId`는 읽는 곳이 없는 `@deprecated` 칸이라 적지 않는다 | | 무효화 topic | `src/contracts/query-invalidation.ts` | 생성 뼈대 계약 `invalidation` | 조립(중복, 고아 topic) | | 멱등 키 쓰기 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 정책(`src/contracts/server-state.ts`의 `commandMutationIdentity`로 operation ID와 키 여부를 descriptor에서 받는다) | 참조 기능 생성 명령(`use-reference-feature.ts`, `reference-feature-contract-contribution.ts`) | 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름), 기능 테스트 | | 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect` | 참조 기능 `presentation/reference-resource-form-page.tsx` | 기능 테스트만 | diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index b035bbf1..12a7f7e3 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -880,7 +880,7 @@ export function ${camel}RouteUrl( `; } -function renderUseItems({ names, operationId }: Shape): string { +function renderUseItems({ names }: Shape): string { const { base, pascal, upper } = names; return `import { bindQuery, type QueryResultMeasure } from "../../../contracts/server-state.ts"; import { useApplicationQuery } from "../../../presentation/adapters/query/application-query.ts"; @@ -916,9 +916,7 @@ export function use${pascal}Items() { { definitionId: "${base}-item-list-v1", definitionVersion: 1, - owner: ${upper}_FEATURE_ID, namespace: ${upper}_ITEM_QUERY_NAMESPACE, - operationId: "${operationId}", profileId: "LIST_STANDARD", measureResult: measureItems, execute: (_input: typeof NO_INPUT, { signal }) => input.listItems({ signal }), diff --git a/src/contracts/server-state.ts b/src/contracts/server-state.ts index d5acfcc4..4ff400be 100644 --- a/src/contracts/server-state.ts +++ b/src/contracts/server-state.ts @@ -174,8 +174,14 @@ type QueryDefinitionNamespace = export type QueryDefinition = Readonly<{ definitionId: string; definitionVersion: number; - owner: string; - operationId: string; + /** + * @deprecated 1103/16-06. Never read: the bound query does not carry it, + * and the HTTP execution records the descriptor's own operation id. Leave + * it out; it is removed in a later release. + */ + owner?: string; + /** @deprecated 1103/16-06. Never read, like `owner`. */ + operationId?: string; profileId: ServerStateProfileId; /** * 03-01. `"NONE"` declares a query no save invalidates (a static lookup). @@ -298,7 +304,11 @@ export type BoundMutation = Readonly<{ definitionVersion: number; operationId: string; requiresIdempotencyKey: boolean; - owner: string; + /** + * @deprecated 1103/16-06. The mutation coordinator never reads it. Leave + * it out; it is removed in a later release. + */ + owner?: string; duplicatePolicy: MutationDuplicatePolicy; scope: CacheScopeSnapshot; execute( diff --git a/src/features/reference-feature/presentation/use-reference-feature.ts b/src/features/reference-feature/presentation/use-reference-feature.ts index 3a92f496..e455765b 100644 --- a/src/features/reference-feature/presentation/use-reference-feature.ts +++ b/src/features/reference-feature/presentation/use-reference-feature.ts @@ -58,7 +58,6 @@ const REFERENCE_CREATE_MUTATION_POLICY = Object.freeze({ // 1103/16-05. The operation id and the key requirement are the // descriptor's, so a misspelt id cannot pass the type check. ...commandMutationIdentity(CREATE_REFERENCE_RESOURCE_CONTRACT), - owner: REFERENCE_FEATURE_ID, duplicatePolicy: "REJECT_WHILE_ACTIVE" as const, invalidate: Object.freeze([REFERENCE_RESOURCE_INVALIDATION_TOPIC]), }); @@ -89,9 +88,7 @@ export function useReferenceDetail(resourceId: string) { { definitionId: "reference-resource-detail-v1", definitionVersion: 1, - owner: REFERENCE_FEATURE_ID, namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE, - operationId: "GET_REFERENCE_RESOURCE", profileId: "DETAIL_STANDARD", measureResult: measureResourceView, execute: (selectedResourceId: string, { signal }) => @@ -123,9 +120,7 @@ export function useReferenceFeature() { { definitionId: "reference-resource-list-v1", definitionVersion: 1, - owner: REFERENCE_FEATURE_ID, namespace: REFERENCE_RESOURCE_QUERY_NAMESPACE, - operationId: "LIST_REFERENCE_RESOURCES", profileId: "LIST_STANDARD", measureResult: measureResourceList, execute: (selectedFilters: ReferenceListFilters, { signal }) => diff --git a/tests/component/application-query-scope-fence.test.tsx b/tests/component/application-query-scope-fence.test.tsx index 6da1a06f..6a75ffee 100644 --- a/tests/component/application-query-scope-fence.test.tsx +++ b/tests/component/application-query-scope-fence.test.tsx @@ -55,6 +55,37 @@ describe("scope-bound query commit fence", () => { ); }); + // 1103/16-06. `owner` and `operationId` were required and nothing read + // them: the bound query never carried them. A definition leaves them out. + it("binds the same query without the owner and operation id it never read", () => { + const scope = scopeSnapshot(); + const bound = bindQuery( + { + definitionId: "resource-detail-v1", + definitionVersion: 1, + namespace: "resource", + namespaceVersion: 1, + profileId: "DETAIL_STANDARD" as const, + measureResult: measureOne, + execute: async () => ({ ok: true as const, value: "value" }), + }, + "resource-1", + scope, + ); + + expect(bound.queryKey).toEqual([ + "query", + 2, + "resource", + 1, + "scope-fingerprint-0001", + 1, + "scope-identity-token-0001", + ]); + expect(Object.keys(bound)).not.toContain("owner"); + expect(Object.keys(bound)).not.toContain("operationId"); + }); + it("discards a successful result whose scope was fenced during execution", async () => { const client = queryClient(); const scope = scopeSnapshot();