冪等キーは「処理結果」と一緒に、同じトランザクションで保存する

CREATE TABLE idempotency_keys (
  key           text PRIMARY KEY,
  request_hash  text NOT NULL,      -- 同じキーで別の内容が来たら拒否するため
  status_code   int,
  response_body jsonb,
  created_at    timestamptz NOT NULL DEFAULT now()
);

BEGIN;
-- 1. キーを確保。既にあれば 0 行になる
INSERT INTO idempotency_keys (key, request_hash)
VALUES ($1, $2)
ON CONFLICT (key) DO NOTHING;

-- 0 行だったら: 既存の行を読んで、保存済みのレスポンスをそのまま返す
--   （request_hash が違えば 422 など、response_body がまだ空なら処理中として 409）

-- 2. 副作用（同じ DB の中の書き込み）
INSERT INTO orders (...) VALUES (...);

-- 3. 返すレスポンスをキーの行に書く
UPDATE idempotency_keys
SET status_code = 201, response_body = $3
WHERE key = $1;
COMMIT;