name	server-actions-and-routes
description	Next.js App Router における Server Actions と Route Handlers の使い分け、セキュリティ、および実装規約。
metadata	[object Object]

Server Actions & Routes 技術規約

Name: server-actions-and-routes
Author: shoma-endo

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

1. 使い分けの基準

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

通信方式	推奨される用途	配置パス / 命名
Server Actions	CRUD操作、フォーム送信、状態変更。クライアントからの一般的なリクエストに優先使用。	`src/server/actions/*.actions.ts`
Route Handlers	SSE (ストリーミング)、外部 Webhook、Cron ジョブ、特定の HTTP メソッド/ヘッダーが必要な場合。	`app/api/**/route.ts`

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

認証の必須化: 認証が必要な全てのアクション/ルートにおいて、処理の先頭で認証チェックを実施します。
- 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）を定義して返却データをフィルタリングします。