diff --git a/docs/architecture/frontend-platform-capability-review.md b/docs/architecture/frontend-platform-capability-review.md index 12281e55..965f5b7a 100644 --- a/docs/architecture/frontend-platform-capability-review.md +++ b/docs/architecture/frontend-platform-capability-review.md @@ -88,7 +88,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실 | logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 | | telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 | | 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 | -| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 19개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 | +| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 20개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 | | UI 회귀 검증 | 준비됨 | dev-only Storybook interaction/axe와 pinned Chromium visual baseline 4종 | cloud review와 다중 OS/device는 프로젝트 선택 | | 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 | | registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 | diff --git a/docs/architecture/frontend-platform-implementation-roadmap.md b/docs/architecture/frontend-platform-implementation-roadmap.md index 1049d05a..da4d17ac 100644 --- a/docs/architecture/frontend-platform-implementation-roadmap.md +++ b/docs/architecture/frontend-platform-implementation-roadmap.md @@ -852,7 +852,7 @@ owner와 만료 시한이 있는 quarantine만 허용한다. `behavior-change`, 제거/type/path/contract 변경은 `breaking`으로 계산한다. breaking에는 version, migration, compatibility window, rollback과 owner를 요구하며 digest 변조와 누락 fixture가 실제로 실패한다. -- API operation별 19개 shared MSW scenario catalog와 strict unhandled-request +- API operation별 20개 shared MSW scenario catalog와 strict unhandled-request server를 제공하고 reference vertical integration이 공통 envelope/handler를 사용한다. - 기본 Playwright는 `build` + `preview`의 실제 `dist`를 Chromium, Firefox, diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md index 866bdec4..921906d1 100644 --- a/docs/testing/frontend-platform-testing-strategy.md +++ b/docs/testing/frontend-platform-testing-strategy.md @@ -141,7 +141,7 @@ rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한 #### Shared MSW와 결정성 operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/ -403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict +403/404/409(충돌·처리 중)/422/429/retry/terminal을 포함한 20개 scenario catalog와 strict unhandled-request server(`tests/mocks/server.ts`의 `onUnhandledRequest: "error"`)를 공유한다. browser test는 공용 fixture (`tests/support/browser/strict-browser-test.ts`)가 console error/warning, @@ -746,7 +746,8 @@ tests/factories/ | `unauthenticated-401` | 401. 명령은 적용되지 않음(`NOT_APPLIED`) | | `forbidden-403` | 권한 없음 | | `not-found-404` | 리소스 없음 | -| `conflict-409` | mutation conflict | +| `conflict-409` | mutation conflict. 계약에 적힌 충돌 code라 명령은 적용되지 않음(`NOT_APPLIED`) | +| `in-flight-409` | 같은 멱등 키의 앞선 요청이 아직 처리 중(`IDEMPOTENT_IN_FLIGHT`). 명령은 결과 불명(`MAYBE_APPLIED`)이라 다음 전송도 같은 키 | | `validation-422` | 승인된 field/global error | | `rate-limited-429` | Retry-After 포함 | | `server-retry-success` | bounded retry 뒤 성공 | diff --git a/scripts/run-http-scenario-evidence.ts b/scripts/run-http-scenario-evidence.ts index eca38509..d2e7cdb3 100644 --- a/scripts/run-http-scenario-evidence.ts +++ b/scripts/run-http-scenario-evidence.ts @@ -45,7 +45,7 @@ if ( } process.stdout.write( - "HTTP scenario evidence: PASS (stale receipt removed, 54 executed, missing-ID fixture rejected)\n", + "HTTP scenario evidence: PASS (stale receipt removed, 57 executed, missing-ID fixture rejected)\n", ); function run(script: string) { diff --git a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts index 589c20cc..47b77fa6 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts @@ -30,6 +30,18 @@ const PROBLEM_VALIDATOR = zodValidator( referenceProblemSchema, ); +/** + * 0929/03-01. A 409 does not by itself mean "refused": a resend with the same + * key can meet the first attempt still running (the paired backend answers + * `409 IDEMPOTENT_IN_FLIGHT`). Only the conflict codes this fixture declares + * are `NOT_APPLIED`; any other 409 stays `MAYBE_APPLIED`, so the coordinator + * keeps the intent and the next send reuses the key. Answering `NOT_APPLIED` + * there would let the next save mint a new key and create the resource twice. + */ +const CREATE_NOT_APPLIED_CONFLICT_CODES: ReadonlySet = new Set([ + "CONFLICT", +]); + /** * Fixture-side classifier standing in for the package-provided pure bounded * classifier. A status the fixture does not describe stays `MAYBE_APPLIED`. @@ -38,8 +50,14 @@ const CREATE_EFFECT: CommandEffectDescriptor = Object.freeze({ successEffect: "APPLIED_CONFIRMED" as const, classifyProblem({ status, + problem, }: Readonly<{ status: number; problem: ReferenceProblem }>) { - if (status === 400 || status === 409 || status === 422) { + if (status === 400 || status === 422) return "NOT_APPLIED"; + if ( + status === 409 && + problem.code !== undefined && + CREATE_NOT_APPLIED_CONFLICT_CODES.has(problem.code) + ) { return "NOT_APPLIED"; } return "MAYBE_APPLIED"; diff --git a/tests/features/reference-feature/reference-http-problem-mapping.test.ts b/tests/features/reference-feature/reference-http-problem-mapping.test.ts index a42506fb..972e68a2 100644 --- a/tests/features/reference-feature/reference-http-problem-mapping.test.ts +++ b/tests/features/reference-feature/reference-http-problem-mapping.test.ts @@ -8,6 +8,7 @@ import { createReferenceHttpGateway, REFERENCE_HTTP_OPERATIONS, } from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts"; +import { CREATE_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; function executorReturning( outcome: Readonly>, @@ -133,3 +134,35 @@ describe("reference HTTP business problem mapping", () => { }); }); }); + +describe("reference create problem effect classification (0929/03-01)", () => { + const classify = (status: number, code?: string) => + CREATE_REFERENCE_RESOURCE_CONTRACT.contract.commandEffect.classifyProblem({ + status, + problem: Object.freeze({ + type: "https://api.test/problems/reference", + title: "Reference problem", + status, + ...(code === undefined ? {} : { code }), + }), + }); + + it.each([ + // The first attempt with this key still runs: the key must stay bound. + { status: 409, code: "IDEMPOTENT_IN_FLIGHT", effect: "MAYBE_APPLIED" }, + // An undeclared 409 may hide a running attempt: safe side. + { status: 409, code: "SOMETHING_NEW", effect: "MAYBE_APPLIED" }, + { status: 409, code: undefined, effect: "MAYBE_APPLIED" }, + // The fixture's declared semantic conflict is the only refused 409. + { status: 409, code: "CONFLICT", effect: "NOT_APPLIED" }, + { status: 400, code: undefined, effect: "NOT_APPLIED" }, + { status: 422, code: "VALIDATION_REJECTED", effect: "NOT_APPLIED" }, + { status: 404, code: "NOT_FOUND", effect: "MAYBE_APPLIED" }, + { status: 503, code: "SERVER_FAILURE", effect: "MAYBE_APPLIED" }, + ] as const)( + "classifies status $status code $code as $effect", + ({ status, code, effect }) => { + expect(classify(status, code)).toBe(effect); + }, + ); +}); diff --git a/tests/features/reference-feature/reference-production-vertical.test.tsx b/tests/features/reference-feature/reference-production-vertical.test.tsx index 6b789d57..05ec65d4 100644 --- a/tests/features/reference-feature/reference-production-vertical.test.tsx +++ b/tests/features/reference-feature/reference-production-vertical.test.tsx @@ -1,6 +1,6 @@ // @vitest-environment jsdom -import { render, screen } from "@testing-library/react"; +import { render, screen, waitFor } from "@testing-library/react"; import userEvent from "@testing-library/user-event"; import { http, HttpResponse } from "msw"; import { @@ -166,6 +166,93 @@ describe("reference feature production vertical path", () => { expect(idempotencyKeys[1]).toBe(idempotencyKeys[0]); }); + it("keeps the key when the resend meets the first attempt still in flight (0929/03-01)", async () => { + const user = userEvent.setup(); + const idempotencyKeys: (string | null)[] = []; + // A server that deduplicates by key: one receipt per created resource. + const receipts = new Map>(); + let firstAttemptRunning = true; + mockApi.server.use( + http.post("https://api.test/api/reference-resources", async ({ request }) => { + const key = request.headers.get("idempotency-key") ?? ""; + idempotencyKeys.push(key); + const receipt = receipts.get(key); + if (receipt) { + if (firstAttemptRunning) { + // The paired backend answers a same-key request while the first + // attempt still runs with 409 IDEMPOTENT_IN_FLIGHT. + firstAttemptRunning = false; + return HttpResponse.json( + { + type: "https://api.test/problems/idempotent_in_flight", + title: "IDEMPOTENT_IN_FLIGHT", + status: 409, + code: "IDEMPOTENT_IN_FLIGHT", + }, + { + status: 409, + headers: { "content-type": "application/problem+json" }, + }, + ); + } + return HttpResponse.json(receipt, { status: 201 }); + } + const body = (await request.json()) as { name: string }; + const resource = { + id: `reference-created-${receipts.size + 1}`, + name: body.name, + createdAt: "2026-07-26T00:00:00.000Z", + }; + receipts.set(key, resource); + // The first attempt reaches the server; only its response is lost. + if (receipts.size === 1) return new HttpResponse(null, { status: 504 }); + return HttpResponse.json(resource, { status: 201 }); + }), + ); + const composition = await createRuntimeComposition({ + fetcher: absoluteFetch, + host: {}, + }); + window.history.pushState({}, "", "/examples/reference-resources/new"); + render(); + + await user.click( + await screen.findByRole("button", { name: "로그인 시작" }), + ); + await user.type( + await screen.findByRole("textbox", { name: /새 항목 이름/ }), + "Slow write", + ); + await user.click(screen.getByRole("button", { name: "저장" })); + await user.click( + await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" }), + ); + await waitFor(() => expect(idempotencyKeys).toHaveLength(2)); + + // After the 409 the user takes the next step the screen offers. + const next = await waitFor(() => { + const resend = screen.queryByRole("button", { + name: "같은 요청으로 다시 보내기", + }); + if (resend) return resend; + const save = screen.getByRole("button", { name: "저장" }); + expect(save).toBeEnabled(); + return save; + }); + const shownAfterInFlight = { + unknown: screen.queryByText("변경 결과를 확인할 수 없습니다.") !== null, + conflict: screen.queryAllByText(/충돌/).length > 0, + }; + await user.click(next); + await waitFor(() => expect(idempotencyKeys).toHaveLength(3)); + + const [first] = idempotencyKeys; + expect(idempotencyKeys).toEqual([first, first, first]); + expect(receipts.size).toBe(1); + expect(shownAfterInFlight).toEqual({ unknown: true, conflict: false }); + expect(await screen.findByText("저장했습니다.")).toBeVisible(); + }); + it.each([ // The demo session treats a server 401 as signed out; the route guard // then asks for sign-in and the form is gone. diff --git a/tests/integration/http-scenario-catalog.test.ts b/tests/integration/http-scenario-catalog.test.ts index 04309bcd..84461f19 100644 --- a/tests/integration/http-scenario-catalog.test.ts +++ b/tests/integration/http-scenario-catalog.test.ts @@ -361,17 +361,17 @@ async function executeScenario( } describe("HTTP scenario catalog execution evidence", () => { - it("declares exactly the 54 behaviorally distinct operation scenarios", () => { + it("declares exactly the 57 behaviorally distinct operation scenarios", () => { const executionIds = Object.entries(OPERATION_SCENARIO_CATALOG).flatMap( ([operationId, scenarioIds]) => scenarioIds.map((scenarioId) => `${operationId}::${scenarioId}`), ); - expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(19); - expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(18); - expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(17); - expect(executionIds).toHaveLength(54); - expect(new Set(executionIds)).toHaveLength(54); + expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(20); + expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(19); + expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(18); + expect(executionIds).toHaveLength(57); + expect(new Set(executionIds)).toHaveLength(57); expect(executionIds).toEqual(HTTP_SCENARIO_EXECUTION_IDS); }); @@ -410,7 +410,7 @@ describe("HTTP scenario catalog execution evidence", () => { HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION, HTTP_SCENARIO_EXPECTATIONS, ), - catalogTotal: 54, + catalogTotal: 57, executedIds: sortedRows.map((row) => row.executionId), rows: sortedRows, }, diff --git a/tests/mocks/handlers/reference-resources.ts b/tests/mocks/handlers/reference-resources.ts index 48c960c3..53c0b076 100644 --- a/tests/mocks/handlers/reference-resources.ts +++ b/tests/mocks/handlers/reference-resources.ts @@ -81,6 +81,11 @@ async function scenarioResponse( if (scenario === "conflict-409") { return HttpResponse.json(problem(409, "CONFLICT"), { status: 409 }); } + if (scenario === "in-flight-409") { + return HttpResponse.json(problem(409, "IDEMPOTENT_IN_FLIGHT"), { + status: 409, + }); + } if (scenario === "validation-422") { return HttpResponse.json( problem(422, "VALIDATION_REJECTED"), diff --git a/tests/mocks/scenarios/catalog.ts b/tests/mocks/scenarios/catalog.ts index 8ab7ba87..1804fcb7 100644 --- a/tests/mocks/scenarios/catalog.ts +++ b/tests/mocks/scenarios/catalog.ts @@ -30,6 +30,7 @@ export const HTTP_SCENARIO_IDS = Object.freeze([ "forbidden-403", "not-found-404", "conflict-409", + "in-flight-409", "validation-422", "rate-limited-429", "server-retry-success", @@ -271,6 +272,21 @@ function expectationFor( ), ]; break; + case "in-flight-409": + // 0929/03-01. The same key is still running: the command stays unknown. + statuses = [409]; + kind = "PROBLEM"; + detail = "409"; + outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED"; + observer = command ? "MAYBE_APPLIED" : "NOT_STARTED"; + bodies = [ + attemptBody( + "FULLY_READ_WITHIN_BOUND", + jsonBytes(problem(409, "IDEMPOTENT_IN_FLIGHT")), + 65_536, + ), + ]; + break; case "validation-422": statuses = [422]; kind = "PROBLEM";