# 機能設計書 90-Next.js統合

## 概要

本ドキュメントは、Giselleプラットフォームにおけるnext.jsアプリケーションへの統合機能の設計を定義する。NextGiselle関数は、Next.js App Routerとシームレスに統合するためのHTTPハンドラーを提供し、Giselle APIエンドポイントの作成を簡素化する。

### 本機能の処理概要

**業務上の目的・背景**：GiselleをNext.jsアプリケーションに統合する際、ルートハンドラーの設定、リクエストの処理、レスポンスの生成などの定型的なコードが必要となる。NextGiselle関数は、これらの処理を抽象化し、最小限の設定でGiselle APIを公開できるようにする。また、Vercel環境での最適化（after関数、x-vercel-idヘッダー等）も組み込まれている。

**機能の利用シーン**：
- Next.js App RouterでGiselle APIエンドポイントを作成する場合
- GitHub Webhookを受信してワークフローを起動する場合
- 生成された画像をHTTP経由で配信する場合

**主要な処理内容**：
1. NextGiselle関数でGiselleインスタンスとHTTPハンドラーを生成
2. createHttpHandler関数でリクエスト処理ロジックを構築
3. ルーティング（jsonRoutes、formDataRoutes、generated-images、github-webhook）
4. Vercel環境検出とリクエストコンテキスト管理
5. after関数によるバックグラウンド処理（テレメトリフラッシュ等）

**関連システム・外部連携**：
- Next.js App Router
- Vercel serverless functions
- GitHub Webhook

**権限による制御**：各APIルートはバックエンド側の認証・認可に従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| なし | - | - | バックエンドAPIのため直接的な画面関連なし |

## 機能種別

フレームワーク統合 / HTTPハンドラー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| basePath | string | Yes | APIベースパス（例: "/api/giselle"） | - |
| storage | GiselleStorage | Yes | ストレージ設定 | - |
| vault | Vault | Yes | シークレット暗号化設定 | - |
| llmProviders | LanguageModelProvider[] | No | 言語モデルプロバイダー | - |
| integrationConfigs | object | No | 外部連携設定（GitHub等） | - |
| callbacks | GiselleCallbacks | No | コールバック関数 | - |
| telemetry | TelemetrySettings | No | テレメトリ設定 | - |
| useAfterFunction | boolean | No | after関数使用フラグ | - |
| onRequest | function | No | リクエストごとのコンテキスト更新関数 | - |

### 入力データソース

- Next.js route.ts ファイルでの設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ...giselle | Giselle | Giselleインスタンスの全メソッド |
| handlers.GET | function | GET HTTPハンドラー |
| handlers.POST | function | POST HTTPハンドラー |

### 出力先

- Next.js App Router エクスポート

## 処理フロー

### 処理シーケンス

```
1. NextGiselle関数呼び出し
   └─ 設定オブジェクトを受け取る
2. Giselleインスタンス生成
   └─ Giselle({...config, waitUntil: after})
3. HTTPハンドラー生成
   └─ createHttpHandler({giselle, config})
4. リクエスト受信
   └─ handlers.GET または handlers.POST
5. コンテキスト設定
   └─ onRequest関数があれば実行
6. ルーティング
   └─ パスに基づいて処理を分岐
7. レスポンス返却
   └─ JSON、バイナリ、またはステータスコード
```

### フローチャート

```mermaid
flowchart TD
    A[NextGiselle 設定] --> B[Giselleインスタンス生成]
    B --> C[createHttpHandler生成]
    C --> D[handlers.GET/POST エクスポート]
    D --> E[HTTPリクエスト受信]
    E --> F{onRequest?}
    F -->|Yes| G[コンテキスト更新]
    F -->|No| H[ルーティング]
    G --> H
    H --> I{パス判定}
    I -->|generated-images| J[画像配信]
    I -->|github-webhook| K[Webhook処理]
    I -->|jsonRoutes| L[JSON API処理]
    I -->|formDataRoutes| M[FormData処理]
    J --> N[Response]
    K --> N
    L --> N
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-90-01 | after関数使用 | Vercel環境ではafter関数を使用 | process.env.VERCEL === "1" |
| BR-90-02 | リクエストID | Vercel環境ではx-vercel-idヘッダーを使用 | Vercel環境 |
| BR-90-03 | Webhook検証 | GitHub Webhookは署名検証必須 | github-webhookルート |
| BR-90-04 | パス検証 | 無効なパスはエラー | 常時 |

### 計算ロジック

特になし。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | 統合レイヤーのためデータベース直接操作なし |

### テーブル別操作詳細

データベース操作は各ルートハンドラー内で行われる。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | Bad Request | Zodバリデーションエラー | リクエストパラメータを確認 |
| 401 | Unauthorized | GitHub Webhook署名検証失敗 | Webhook秘密鍵を確認 |
| 500 | Internal Server Error | 予期しないエラー | サーバーログを確認 |

### リトライ仕様

リトライはクライアント側で実装。

## トランザクション仕様

トランザクション管理は各ルートハンドラー内で行われる。

## パフォーマンス要件

- HTTPハンドラー初期化: < 10ms
- リクエスト処理オーバーヘッド: < 5ms
- after関数による非同期処理でレスポンス時間短縮

## セキュリティ考慮事項

- GitHub Webhook署名検証
- ZodによるリクエストボディのバリデーションJSON/FormDataの適切なパース
- HTTPS経由でのリクエストのみ受け付け（Vercel環境）

## 備考

- NextGiselle関数はGiselleの全メソッドとHTTPハンドラーを返却
- Vercel環境では自動的にafter関数が使用される
- requestContextStoreでリクエストコンテキストを管理

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

NextGiselleConfig型と関連するインターフェースを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | next-giselle-engine.ts | `packages/nextjs/src/next-giselle-engine.ts` | NextGiselleConfig型定義（21-29行目） |
| 1-2 | context.ts | `packages/nextjs/src/context.ts` | RequestContext型定義（3-5行目） |

**読解のコツ**: NextGiselleConfigはGiselleConfigを拡張し、basePath、useAfterFunction、onRequestを追加。

#### Step 2: エントリーポイントを理解する

NextGiselle関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | next-giselle-engine.ts | `packages/nextjs/src/next-giselle-engine.ts` | NextGiselle関数（189-202行目） |

**主要処理フロー**:
- **190行目**: Giselle({...config, waitUntil: after})でインスタンス生成
- **191-194行目**: createHttpHandlerでHTTPハンドラー生成
- **195-201行目**: giselleメソッドとhandlersを返却

#### Step 3: HTTPハンドラー実装を理解する

createHttpHandler関数の詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | next-giselle-engine.ts | `packages/nextjs/src/next-giselle-engine.ts` | createHttpHandler関数（53-186行目） |

**主要処理フロー**:
- **60-70行目**: onRequest関数によるコンテキスト更新
- **72-84行目**: Vercel環境検出とリクエストコンテキスト設定
- **85行目**: requestContextStore.run()でコンテキスト管理
- **90-108行目**: generated-imagesパスのハンドリング
- **110-118行目**: パスセグメント解析
- **126-135行目**: after関数によるバックグラウンド処理
- **137-152行目**: jsonRoutesのハンドリング
- **154-159行目**: formDataRoutesのハンドリング
- **161-182行目**: github-webhookのハンドリング

### プログラム呼び出し階層図

```
route.ts (Next.js)
    │
    └─ NextGiselle(config)
           │
           ├─ Giselle(config)
           │
           └─ createHttpHandler()
                  │
                  ├─ httpHandler (GET/POST)
                  │      │
                  │      ├─ requestContextStore.run()
                  │      │
                  │      ├─ generated-images handling
                  │      │
                  │      ├─ jsonRoutes[path](giselle)
                  │      │
                  │      ├─ formDataRoutes[path](giselle)
                  │      │
                  │      └─ github-webhook handling
                  │
                  └─ handlers.GET / handlers.POST
```

### データフロー図

```
[Next.js App Router]

route.ts
       │
       ▼
NextGiselle(config) ───▶ { ...giselle, handlers }
       │
       ▼
HTTP Request ───────────▶ httpHandler
       │
       ▼
requestContextStore ───▶ Context設定
       │
       ▼
Router Path解析 ────────▶ ルート分岐
       │
       ├─ /generations/{id}/generated-images/{file}
       │
       ├─ /jsonRoute (createTask, getWorkspace, etc.)
       │
       ├─ /formDataRoute (uploadFile)
       │
       └─ /github-webhook
              │
              ▼
HTTP Response ◀────────── 処理結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| next-giselle-engine.ts | `packages/nextjs/src/next-giselle-engine.ts` | ソース | NextGiselle関数とcreateHttpHandler |
| context.ts | `packages/nextjs/src/context.ts` | ソース | RequestContextとrequestContextStore |
| index.ts | `packages/nextjs/src/index.ts` | ソース | パッケージエクスポート |
| router.ts | `packages/http/src/router.ts` | ソース | jsonRoutesとformDataRoutes定義 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | Giselle本体 |
