Server Actions & Routes 技術規約

Next.js のサーバーサイド通信において、一貫性・セキュリティ・開発効率を担保するためのルールです。

1. 使い分けの基準

基本的には Server Actions を第一選択 とし、Route Handlers は特殊なケースに限定します。

2. Server Actions 実装ルール

• ファイルレベルの宣言: ファイルの先頭に必ず 'use server'; を記述します。関数レベルでの宣言は避け、.actions.ts ファイルに集約してください。
• 命名規則: ファイル名は必ず [feature].actions.ts とします。
• バリデーション: 入力引数は zod スキーマを使用して parse または safeParse し、型安全を保証します。
• クライアント用インポート: 既存の一部実装（例: chat.actions.ts）では、名前衝突回避や明示性のために export const MyActionSA = MyAction; のようなエイリアスを定義している場合がありますが、新規実装において必須ではありません。

3. セキュリティ & 認証

• 認証の必須化: 認証が必要な全てのアクション/ルートにおいて、処理の先頭で認証チェックを実施します。
  • Server Actions: 引数の liffAccessToken を authMiddleware に渡して検証。
  • Route Handlers: ヘッダー（Bearer）または Cookie からトークンを取得し、ensureAuthenticated 等の共通ロジックで検証。
• 特権操作の制限: viewMode (閲覧モード) が有効な場合、データの「書き込み」や「管理者操作」を拒否し、VIEW_MODE_ERROR_MESSAGE を返却する必要があります。
• エラーハンドリング:
  • Server Actions では、ユーザーフレンドリーなエラーメッセージを含むオブジェクトを返却します。
  • Route Handlers では、適切な HTTP ステータスコード（401, 403, 429 等）と JSON データを返却します。
• 情報のカプセル化: 内部 ID や不必要な機密情報（API キー等）をクライアントに返さないよう、専用のレスポンス型（例: ChatResponse）を定義して返却データをフィルタリングします。

4. 実装のアンチパターン

• app/api/ 内の route.ts に 'use server'; を記述する（不要かつ誤解を招く）。
• クライアントから直接 prisma や supabase (Service Role) を呼び出すコードを Server Actions 外に書く。
• 認証チェックなしで Service Role による DB 操作を行う（重大なセキュリティリスク）。

セルフレビュー項目

• その機能は Server Action で実装可能か？（SSE 等が必要ないなら Action を選択）
• 経路に応じた適切な共通認証ロジックで検証を行っているか？
• viewMode の際に破壊的操作が制限されているか？
• zod で入力値を検証しているか？