system_adminの操作だけ外部キー制約違反(23503)で500になった

結論

監査ログの actor 参照を1本のテーブルへの外部キーにすると、そのテーブルに存在しない種類の管理者が操作した瞬間だけ失敗します。

症状

運営側の管理者（system_admin）が広告の削除を操作すると、HTTP 500 が返ります。本番ではエラーメッセージがマスクされ、digest 付きの汎用エラーだけが見えます。

同じ画面から広告を新規作成すると、500 にはなりません。代わりに「他の操作と競合しました。最新の内容を読み込み直してください」という、事実と違うメッセージが返ります。作成そのものは失敗しているのに、見た目は正常に握りつぶされています。

削除は落ちて気づかれ、作成は落ちても気づかれない。2つの操作が同じ原因で壊れているのに、症状が対称になっていませんでした。

原因

このシステムには、テナント側の学校管理者（school_admin）と、全校を横断する運営側の管理者（system_admin）という、別のテーブルで管理された2種類の管理者ロールがあります。

監査ログには誰が操作したかを記録する列があり、users(id) への外部キーが付いています。学校管理者は users テーブルの行なので、この参照は素直に効きます。しかし system_admin は users とは別のテーブルで管理されていて、users には存在しません。

削除・作成どちらの Server Action も、監査ログへ書き込む際に操作者の uid をそのまま actor 参照へ渡していました。学校管理者が操作すれば users に実在する行を指すので通りますが、system_admin が操作すると、存在しない users の行を指すことになり、insert の時点で外部キー制約違反（PostgreSQL のエラーコード 23503）になります。

この違反そのものは、作成・削除のどちらの操作でも同じ理由で起きていました。差が出たのは、その先の例外処理です。

• 作成側は制約違反を捕まえて「競合しました」というメッセージに変換する処理がすでにあったため、外部キー違反でもそのメッセージのまま返っていました。原因が制約違反である点は合っていても、実際に起きているのは他ユーザーとの競合ではなく、この参照設計そのものの不整合です。
• 削除側には制約違反を捕まえる処理が無く、例外がそのまま再スローされていました。本番環境ではエラー詳細がマスクされるため、operator にはただの HTTP 500 だけが見えます。

既存のユニットテストは DB 接続をモックしていました。system_admin の uid を渡すコード自体は実行されてテストは通ります。しかし外部キー制約は実データベースに書き込んで初めて発火するものなので、モック越しのテストでは検証できていませんでした。CI は緑のまま、この不整合は見逃され続けていました。

さらに、作成側の失敗は表面化しにくい形でした。テスト用の広告データはこの画面とは別の投入方法で作られており、system_admin 自身がこの画面から新規作成を試す機会もほとんどありません。「競合しました」という、もっともらしいエラーメッセージが返ることも、実害として認識されない一因でした。

直す

監査ログの actor 参照を、操作者が system_admin のときは null にするよう変更しました。

const isSystemAdmin = params.actor.role === "system_admin";
const actorRef = isSystemAdmin ? null : params.actor.uid;

操作者を特定する情報自体は消さず、外部キーの無い別カラム（actorIdentityUid）に保持します。users への参照が要る集計・結合には使えなくなりますが、「誰が操作したか」を追う手段は残ります。

削除側の例外処理には、作成側とまったく同じ制約違反の判定を追加しました。これで、同じ原因の失敗が経路によって「500」だったり「競合」だったりする非対称は無くなり、どちらも同じ意味のあるメッセージを返します。

回帰テストでは、system_admin が操作したときに actor 参照が null になり、本人の識別情報は別カラムに残ることを固定しました。あわせて、外部キーの対象外である別のテーブル（ads の created_by など）については、過剰に null 化していないことも確認しています。直すべきは「別テーブルで管理されたロールを users への外部キーで参照している箇所」だけで、それ以外まで一律に緩める必要はありません。

再発しない形にする

この事故が教えているのは、「外部キー制約違反」というエラーコードは同じでも、どの参照が違反しているかによって正しい対処が変わるということです。作成側の例外処理は、制約違反を一括りに「競合」として扱っていたために、原因が違う2つの23503を区別できていませんでした。

再発防止としてやったのは2つです。1つは、上で書いた通り、system_admin を users への外部キーに乗せないという設計そのものの修正です。もう1つは、削除・作成の両方で同じ判定関数（isConstraintViolation）を使い、経路によって例外処理の有無が変わらないようにしたことです。片方だけ直すと、いずれ同じ非対称が別の操作で再現します。

テナントに閉じたロールと、テナントを横断するロールを同じ監査ログで扱う設計そのものは、他の運営系の書き込みにも共通してありえます。同種の箇所は、同じ方針（監査ログの参照が users を前提にしていないか）で洗い出す必要があります。

監査ログの actor 設計については、RLS policy が actor_user_id=NULL を許してしまう別の事故 も書いています。あちらは NULL を許したことが問題で、今回は NULL にすることが解決策でした。同じ列でも、何を守ろうとしているかによって答えが逆になります。