エラーハンドリング & メッセージ設計（SSoT）

エラーハンドリング & メッセージ設計（SSoT）

このスキルは、Network Boundary を跨ぐエラーの扱いと、ユーザー向けメッセージの一元管理を徹底するための規約です。 アプリ全体のエラーメッセージは src/​domain/​errors/​error-messages.ts を単一の正解 (SSoT) とします。

1. 基本方針（必須）

• 例外をそのままクライアントに渡さない
  Server Action から Error.message を直接表示しない。Network Boundary を跨いだ Error は production で秘匿される。
• Server Action は「表示可能なエラー」を値として返す
  例外は Result 形式（success / failure）に畳み込み、message は 安全に表示できる文言に限定する。
• 表示メッセージは必ず ERROR_MESSAGES を経由
  直接の日本語文字列を散在させない。
• 内部詳細はログに集約
  スタックトレースや技術情報はサーバー側でログ化し、ユーザー表示には出さない。

2. 推奨パターン

2.1 Server Action の戻り値

• 返却は ServerActionResult<T> を基本形とする（src/​lib/​async-handler.ts）。
• 成功時は { success: true, data?: T }（削除系などは data 省略可）。
• 失敗時は { success: false, error: string } とし、error は ERROR_MESSAGES から生成する。
• 必要に応じて needsReauth / requiresSubscription などの追加フィールドを許容する。
• 参考: ServerActionResult の型定義

export interface ServerActionResult<T> {
  success: boolean;
  data?: T;
  error?: string;
}

2.2 クライアント側の共通ハンドリング

• 取得/更新の実行は handleAsyncAction で統一する（src/​lib/​async-handler.ts）。
• onSuccess / setLoading / setMessage で UI 状態とメッセージを集中管理する。
• 参考: 実装例（src/​hooks/​useGscSetup.ts と同型の最小パターン）

await handleAsyncAction(fetchGscStatus, {
  onSuccess: data => setStatus(data as GscConnectionStatus),
  setLoading: setIsSyncingStatus,
  setMessage: setAlertMessage,
  defaultErrorMessage: ERROR_MESSAGES.GSC.STATUS_FETCH_FAILED,
});

2.3 メッセージ管理

• 表示メッセージは ERROR_MESSAGES を唯一の参照元とする。
• Server Action 側で文言を確定し、クライアントは result.error を表示するだけに留める。

2.4 例外の扱い（Server Action 側）

• 例外は try/​catch で捕捉し、{ success: false, error } に畳み込む。
• 技術的詳細はログに集約し、ユーザー向けには安全な文言のみ返す。

3. 実装ルール（必須）

1. メッセージ追加は src/​domain/​errors/​error-messages.ts に集約
2. Server Action は Error を throw せず { success: false, error } を返す
3. クライアントは result.error を表示するだけに留める
4. handleAsyncAction を使い UI 状態とメッセージ処理を統一する

4. アンチパターン

• Client Component で Error.message を直接表示する
• Server Action で例外をそのまま throw する
• メッセージ文字列を任意のファイルに直接書く
• handleAsyncAction を使わずに各所でエラーハンドリングを分散させる

5. セルフレビュー項目

• ERROR_MESSAGES に追加した文言が他用途で重複しないか
• Server Action の返却が ServerActionResult の形に沿っているか
• Network Boundary 越しに Error.message を使っていないか
• handleAsyncAction で UI 側の処理が統一されているか