From a750858dfe027efc915eb416d56fcca4bfa605fd Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sat, 8 Aug 2026 13:35:30 +0900 Subject: [PATCH] fix: preserve idempotency keys across command retries (AEG-V16-022) Create one immutable request per user intent so retries forward the same key; preserve concurrency conflict handling and execution evidence. --- ...G-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md | 20 +++++++++++++ .../CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv | 1 + .../crud/tests/useOptimisticCommand.spec.ts | 30 +++++++++++++++++++ .../src/shared/crud/useOptimisticCommand.js | 9 ++++-- .../src/shared/crud/useOptimisticCommand.ts | 11 ++++--- 5 files changed, 64 insertions(+), 7 deletions(-) create mode 100644 docs/CURRENT/AEG-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md create mode 100644 frontend/src/shared/crud/tests/useOptimisticCommand.spec.ts diff --git a/docs/CURRENT/AEG-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md b/docs/CURRENT/AEG-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md new file mode 100644 index 00000000..cb2adcce --- /dev/null +++ b/docs/CURRENT/AEG-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md @@ -0,0 +1,20 @@ +# AEG-V16-022 — Optimistic command hook + +## Scope + +- **WBS / Requirement / UI / Test:** AEG-V16-022 / REQ-V16-FEC-06 / UI-V16-FEC-06 / T-V16-FEC-06 +- **Classification:** shared command-boundary correctness fix; no API, DB, policy, or provider change. + +## Source / Assumption / Unknown / Decision Required + +- **Source:** `AGENTS.md` idempotency rule, `frontend/src/shared/commands/idempotency.*`, and `useOptimisticCommand.*`. +- **Assumption:** the caller creates one request per user intent and reuses that request for retry. Server idempotency remains the authoritative side-effect protection. +- **Unknown:** no CRUD screen currently consumes this hook; integration evidence remains a later screen-slice responsibility. +- **Decision Required:** predecessor AEG-V16-021 has no concrete consumer yet; this implementation does not claim its acceptance evidence. + +## Execution evidence + +- `createRequest()` freezes a request with an idempotency key once; `run()` forwards that exact key on every retry. +- `If-Match`, 409/412 conflict state, correlation capture, and pending reset are preserved. +- `frontend: pnpm test -- --run src/shared/crud/tests/useOptimisticCommand.spec.ts`: 1 file / 2 tests passed. +- `frontend: pnpm typecheck`: passed before JS companion synchronization; the later JS-only synchronization is covered by the passing runtime test. diff --git a/docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv b/docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv index 547d7e22..ed8e80c1 100644 --- a/docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv +++ b/docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv @@ -12,6 +12,7 @@ AEG-V16-015,S0,VS-00,Adapter rollback runbook,IN_PROGRESS,TBD,"docs/CURRENT/ui-p AEG-V16-018,S6,Cross,DataContextHeader,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-018_DATA_CONTEXT_HEADER_SLICE_NOTE.md; frontend/src/shared/ui/components/KsDataContextHeader.vue; frontend/src/shared/ui/components/tests/KsDataContextHeader.spec.ts","FE Lead","2026-08-08: Made projectionVersion and watermark required so stale/rebuildable read-model context cannot be omitted; added visible and accessible stale state plus VersionSet propagation tests. Actual evidence: targeted Vitest 2/2 PASS, frontend typecheck PASS, production build PASS. Build emitted unrelated tracked .js drift, excluded from this Slice. COMPLETED is blocked pending predecessor AEG-V16-017 acceptance and UX/a11y evidence." AEG-V16-019,S6,Cross,CommandBar,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-019_COMMAND_BAR_SLICE_NOTE.md; frontend/src/shared/ui/components/KsCommandBar.vue; frontend/src/shared/ui/components/tests/KsCommandBar.spec.ts","FE Lead","2026-08-08: Command boundary now suppresses disabled/busy execute events and exposes aggregate busy state. Actual evidence: targeted Vitest 1/1 PASS; frontend typecheck PASS. COMPLETED is blocked pending predecessor AEG-V16-018 acceptance and UX/a11y evidence." AEG-V16-020,S6,Cross,CRUD Resource v2,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-020_CRUD_RESOURCE_V2_SLICE_NOTE.md; contracts/ui/crud-resource.v2.json; frontend/src/shared/crud/resourceDefinition.ts; frontend/src/shared/crud/tests/resourceDefinition.spec.ts","FE Lead","2026-08-08: Hardened runtime resource-definition checks for schema versions, permission policy, concurrency/idempotency modes, and sensitive grid columns. Actual evidence: resource definition Vitest 3/3 PASS; frontend typecheck PASS. COMPLETED is blocked pending predecessor AEG-V16-019 acceptance and UX/a11y evidence." +AEG-V16-022,S6,Cross,Optimistic command hook,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-022_OPTIMISTIC_COMMAND_SLICE_NOTE.md; frontend/src/shared/crud/useOptimisticCommand.ts; frontend/src/shared/crud/tests/useOptimisticCommand.spec.ts","FE Lead","2026-08-08: Request creation now freezes one Idempotency-Key per user intent and retries reuse it; 409/412 conflict state remains explicit. Actual evidence: targeted Vitest 2/2 PASS; frontend typecheck PASS. COMPLETED is blocked pending actual CRUD-screen integration and predecessor evidence." AEG-X-008,S0,Cross,OpenAPI artifact 고도화,COMPLETED,2026-08-04,.gitea/workflows/openapi-gate.yml + docs/api/openapi.json,BE/FE Architect,"✅ OpenAPI diff gate implemented: CI/CD automation detects breaking changes (3 checks: parameter removal, status code removal, field removal), blocks merge without approval, auto-comments on PR" AEG-VS-00-01,S0,VS-00,정책·범위·실패상태 계약 확정,COMPLETED,2026-08-06,"docs/CURRENT/SLICE_SPECS/VS-00-SLICE_SPEC.md + commit e7913db",PM/Architect,"✅ SLICE_SPEC produced: VS-00-SLICE_SPEC.md (state transitions, RBAC, governance gates, DQ rules, compliance). Commit e7913db. 249/253 tests PASS." AEG-VS-00-02,S0,VS-00,데이터 시점·스키마·정합성 계약,COMPLETED,2026-08-06,"contracts/data/platform-data-contract.v1.json + commit e7913db",Data Architect/DBA,"✅ DATA_CONTRACT v1.0 produced: PIT envelope (published_at/correlation_id/revision), 5 table schemas, DQ rules/lineage, GDPR/PCI-DSS compliance. JSON schema + validation. 249/253 tests PASS." diff --git a/frontend/src/shared/crud/tests/useOptimisticCommand.spec.ts b/frontend/src/shared/crud/tests/useOptimisticCommand.spec.ts new file mode 100644 index 00000000..373fb673 --- /dev/null +++ b/frontend/src/shared/crud/tests/useOptimisticCommand.spec.ts @@ -0,0 +1,30 @@ +import { describe, expect, it } from 'vitest' +import { useOptimisticCommand } from '../useOptimisticCommand' + +describe('useOptimisticCommand', () => { + it('reuses one idempotency key when an intent is retried', async () => { + const keys: string[] = [] + const command = useOptimisticCommand(async (_request, headers) => { + keys.push(headers['Idempotency-Key']) + return { data: { accepted: true } } + }) + const request = command.createRequest({ name: 'update' }, 'etag-1') + + await command.run(request) + await command.run(request) + + expect(keys).toHaveLength(2) + expect(keys[0]).toBe(request.idempotencyKey) + expect(keys[1]).toBe(request.idempotencyKey) + }) + + it('surfaces a 412 conflict and clears pending state', async () => { + const command = useOptimisticCommand(async () => { + throw { response: { status: 412 } } + }) + + await expect(command.run(command.createRequest({ name: 'update' }))).rejects.toEqual({ response: { status: 412 } }) + expect(command.conflict.value).toBe(true) + expect(command.pending.value).toBe(false) + }) +}) diff --git a/frontend/src/shared/crud/useOptimisticCommand.js b/frontend/src/shared/crud/useOptimisticCommand.js index bd393481..7c2bb15a 100644 --- a/frontend/src/shared/crud/useOptimisticCommand.js +++ b/frontend/src/shared/crud/useOptimisticCommand.js @@ -1,5 +1,5 @@ import { ref } from 'vue'; -import { createIdempotencyKey } from '../commands/idempotency'; +import { createIdempotentCommand } from '../commands/idempotency'; export function useOptimisticCommand(execute) { const pending = ref(false); const conflict = ref(false); @@ -10,7 +10,7 @@ export function useOptimisticCommand(execute) { pending.value = true; conflict.value = false; try { - const headers = { 'Idempotency-Key': createIdempotencyKey() }; + const headers = { 'Idempotency-Key': request.idempotencyKey }; if (request.etag) headers['If-Match'] = request.etag; const response = await execute(request, headers); @@ -27,5 +27,8 @@ export function useOptimisticCommand(execute) { pending.value = false; } } - return { pending, conflict, lastCorrelationId, run }; + function createRequest(payload, etag) { + return Object.freeze({ ...createIdempotentCommand(payload), etag }); + } + return { pending, conflict, lastCorrelationId, createRequest, run }; } diff --git a/frontend/src/shared/crud/useOptimisticCommand.ts b/frontend/src/shared/crud/useOptimisticCommand.ts index d43cf821..1fe8f86b 100644 --- a/frontend/src/shared/crud/useOptimisticCommand.ts +++ b/frontend/src/shared/crud/useOptimisticCommand.ts @@ -1,6 +1,6 @@ import { ref } from 'vue' -import { createIdempotencyKey } from '../commands/idempotency' -export interface OptimisticCommandRequest { payload: T; etag?: string } +import { createIdempotentCommand, type IdempotentCommand } from '../commands/idempotency' +export interface OptimisticCommandRequest extends IdempotentCommand { etag?: string } export interface OptimisticCommandResponse { data: TResult; etag?: string; correlationId?: string } export function useOptimisticCommand(execute: (request: OptimisticCommandRequest, headers: Record) => Promise>) { const pending = ref(false); const conflict = ref(false); const lastCorrelationId = ref() @@ -8,7 +8,7 @@ export function useOptimisticCommand(execute: (request: Optim if (pending.value) throw new Error('Command is already in progress') pending.value=true; conflict.value=false try { - const headers: Record = { 'Idempotency-Key': createIdempotencyKey() } + const headers: Record = { 'Idempotency-Key': request.idempotencyKey } if (request.etag) headers['If-Match']=request.etag const response=await execute(request,headers); lastCorrelationId.value=response.correlationId; return response } catch (error: unknown) { @@ -17,5 +17,8 @@ export function useOptimisticCommand(execute: (request: Optim throw error } finally { pending.value=false } } - return { pending, conflict, lastCorrelationId, run } + function createRequest(payload: TPayload, etag?: string): OptimisticCommandRequest { + return Object.freeze({ ...createIdempotentCommand(payload), etag }) + } + return { pending, conflict, lastCorrelationId, createRequest, run } }