refactor(server-state): 아무도 읽지 않는 쿼리·뮤테이션 정의 칸을 선택 칸으로 둔다
문제 QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다. bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능 작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로 적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②). 고른 방법 세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는 채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다. 매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title· navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다. 버린 대안 - 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과 다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다. - 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의 operation ID를 싣는다. 같은 값을 두 번 싣는다. 위험·한계 - 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면 FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와 test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은 파일이라 이번에는 문서로만 적었다. 검증 - RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner· operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과. - tests/features/reference-feature, tests/unit/create-feature.test.ts, scope-fence 129건 통과. check:types(app·node·test), lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
This commit is contained in:
@@ -374,7 +374,8 @@ projectRequest: (input) => Object.freeze({
|
||||
- `presentation/<base>-feature-runtime.ts`: 지연 로드 페이지 표. `moduleId`는 계약과 같아야 한다.
|
||||
- `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다.
|
||||
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
|
||||
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US).
|
||||
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.
|
||||
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
|
||||
- 기능 폴더 밖: `artifacts/tests/a11y-manual/<ROUTE_ID>.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: <operationId> 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 결정표로 판단한다.
|
||||
|
||||
@@ -93,7 +93,7 @@ const search = (q: string) =>
|
||||
|
||||
| 패턴 | 정의 | 예제 | 검사 |
|
||||
|---|---|---|---|
|
||||
| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use-<base>-items.ts` | profile ID (실행 때). `operationId`는 `string`이라 묶이지 않음 |
|
||||
| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use-<base>-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` | 기능 테스트만 |
|
||||
|
||||
@@ -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 }),
|
||||
|
||||
@@ -174,8 +174,14 @@ type QueryDefinitionNamespace =
|
||||
export type QueryDefinition<Input, Value> = 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<Input, Value> = 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(
|
||||
|
||||
@@ -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 }) =>
|
||||
|
||||
@@ -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();
|
||||
|
||||
Reference in New Issue
Block a user