# 機能設計書 15-ファイルノード

## 概要

本ドキュメントは、Giselleワークフローエンジンにおけるファイルノード（FileNode）の機能設計を記述する。ファイルノードは、ファイルデータ（PDF、テキスト、画像）を保持し、他のノードへ提供するための変数ノードである。

### 本機能の処理概要

ファイルノードは、ワークフロー内でファイルデータを管理する機能である。ユーザーがアップロードしたファイル（PDF、テキスト、画像）を保持し、接続された後続ノード（テキスト生成ノード等）へ入力として提供する。ファイルはカテゴリ別に管理され、状態管理（アップロード中、アップロード完了、失敗等）も行われる。

**業務上の目的・背景**：AIワークフローにおいて、ファイル（PDFドキュメント、テキストファイル、画像ファイル等）を入力として処理するケースが多い。ファイルノードは、そのようなファイルベースの入力を一元管理し、AIモデルへの入力として適切に提供する役割を担う。

**機能の利用シーン**：
- PDFドキュメントをAIに分析させる場合
- 画像ファイルをビジョンモデルで処理する場合
- テキストファイルの内容をワークフローで利用する場合
- 複数ファイルをバッチ処理する場合

**主要な処理内容**：
1. ファイルカテゴリ（pdf、text、image）の指定
2. ファイルのアップロードと状態管理
3. ファイルコピー機能（ワークスペースコピー時）
4. ファイル内容のテキスト抽出
5. 出力ポートを通じた後続ノードへのファイルデータ提供

**関連システム・外部連携**：
- ファイルアップロード機能（No.63）
- ファイルコピー機能（No.64）
- ファイルテキスト取得機能（No.66）
- ストレージ機能

**権限による制御**：特になし（ワークスペース編集権限に依存）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | ファイルノードの追加・編集、ファイルアップロード |

## 機能種別

データ格納 / ファイル管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "file" | Yes | ノードコンテンツタイプ | リテラル値 |
| category | FileCategory | Yes | ファイルカテゴリ | pdf/text/image |
| files | FileData[] | Yes | ファイルデータ配列 | 配列形式 |

### ファイルデータ構造

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| id | FileId | Yes | ファイルID（fl-で始まる） |
| name | string | Yes | ファイル名 |
| type | string | Yes | MIMEタイプ |
| size | number | Yes | ファイルサイズ（バイト） |
| status | string | Yes | 状態（uploading/uploaded/failed/pending-copy/copying） |
| uploadedAt | number | 条件付き | アップロード完了時刻（uploadedステータス時） |
| errorMessage | string | 条件付き | エラーメッセージ（failedステータス時） |
| originalFileIdForCopy | FileId | 条件付き | コピー元ファイルID（コピー時） |
| providerOptions | object | 条件付き | プロバイダー固有オプション（OpenAI fileId等） |

### 入力データソース

- **ファイルアップロード**: ドラッグ&ドロップまたはファイル選択
- **ファイルコピー**: ワークスペースコピー時の自動処理

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| outputs | Output[] | 出力ポート配列（1要素） |
| outputs[0].id | OutputId | 出力ポートID |
| outputs[0].label | "Output" | 表示ラベル |
| outputs[0].accessor | "text" | アクセサー名 |

### 出力先

- 接続された後続ノードへのファイルデータ提供
- テキスト生成ノードへの添付ファイル
- 画像生成モデルへの画像入力

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createFileNode）
   └─ カテゴリ（pdf/text/image）を指定
   └─ 空のfiles配列で初期化
   └─ 出力ポート（accessor: "text"）を生成

2. ファイルアップロード
   └─ status: "uploading"でFileData追加
   └─ ストレージへアップロード
   └─ 成功: status: "uploaded"、uploadedAt設定
   └─ 失敗: status: "failed"、errorMessage設定

3. ノードクローン時（ファイルコピー）
   └─ status: "pending-copy"でFileData生成
   └─ originalFileIdForCopy設定
   └─ コピー処理実行
   └─ status: "copying" → "uploaded"

4. ワークフロー実行時
   └─ ファイルテキスト取得（PDF、テキストファイル）
   └─ 画像データ取得（画像ファイル）
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[カテゴリ選択]
    B --> C[空ファイル配列で初期化]
    C --> D{ファイル追加}
    D -->|アップロード| E[status: uploading]
    E --> F{アップロード結果}
    F -->|成功| G[status: uploaded]
    F -->|失敗| H[status: failed]
    D -->|クローン| I[status: pending-copy]
    I --> J[status: copying]
    J --> K{コピー結果}
    K -->|成功| G
    K -->|失敗| H
    G --> L[ワークスペース保存]
    H --> L
    L --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | カテゴリ固定 | ノード生成時に指定されたカテゴリは変更不可 | ノード生成後 |
| BR-002 | 状態遷移 | uploading→uploaded/failed、pending-copy→copying→uploaded/failed | 状態変更時 |
| BR-003 | 推移的クローン | クローン時、既にクローンされたファイルはoriginalFileIdForCopyを保持 | 二重クローン時 |
| BR-004 | プロバイダーオプション | OpenAI等のプロバイダー固有のfileIdを保持可能 | アップロード完了時 |

### 計算ロジック

特になし（ファイル管理ノードのため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし（ストレージ機能と連携） |

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

ファイルノード単体でのDB操作はない。ストレージ機能と連携してファイルを管理する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイルアップロードエラー | アップロード失敗時 | status: "failed"、errorMessage設定 |
| - | ファイルコピーエラー | コピー失敗時 | status: "failed"、errorMessage設定 |

### リトライ仕様

ファイルアップロード/コピーの失敗時は、UIから再実行可能。

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

本ノード単体でのトランザクション制御はない。

## パフォーマンス要件

- ファイルサイズ制限はストレージ機能に依存

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

- ファイルはワークスペース単位で管理される
- ファイルアクセスはワークスペースアクセス権限に依存

## 備考

- FileCategory: "pdf" | "text" | "image"
- ファイルステータス: "uploading" | "uploaded" | "failed" | "pending-copy" | "copying"

---

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

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

### 推奨読解順序

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

まず、ファイルノードのスキーマ定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | file.ts | `packages/protocol/src/node/variables/file.ts` | FileContent、FileData、各状態のスキーマ定義 |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | FileNode型、isFileNode判定関数 |

**読解のコツ**: FileDataは状態（status）によって異なるプロパティを持つunion型。各状態のスキーマを理解することが重要。

#### Step 2: ノード生成ファクトリを理解する

ノードがどのように生成されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | node-factories.ts | `packages/node-registry/src/node-factories.ts` | fileVariableFactoryImplの実装 |

**主要処理フロー**:
- **498-547行目**: fileVariableFactoryImplのcreate/clone実装
- **517-530行目**: クローン時のpending-copyファイル生成
- **1003-1005行目**: createFileNode関数のエクスポート

#### Step 3: ファイル操作を理解する

ファイルの状態遷移関数を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | file.ts | `packages/protocol/src/node/variables/file.ts` | createUploadingFileData、createUploadedFileData等の関数 |

**主要処理フロー**:
- **19-29行目**: createUploadingFileData - アップロード開始時のデータ生成
- **44-56行目**: createUploadedFileData - アップロード完了時のデータ更新
- **64-73行目**: createFailedFileData - エラー時のデータ更新
- **81-92行目**: createPendingCopyFileData - コピー待機時のデータ生成
- **100-107行目**: createCopyingFileData - コピー開始時のデータ更新

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

```
createFileNode (node-factories.ts)
    │
    └─ FileNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ content.type: "file"
           ├─ content.category: pdf/text/image
           ├─ content.files: []
           ├─ inputs: []
           └─ outputs: [{accessor: "text"}]

ファイルアップロード時
    │
    ├─ createUploadingFileData
    │      └─ status: "uploading"
    │
    └─ アップロード完了/失敗
           ├─ createUploadedFileData (成功時)
           └─ createFailedFileData (失敗時)

ノードクローン時
    │
    ├─ createPendingCopyFileData
    │      └─ status: "pending-copy"
    │
    └─ createCopyingFileData
           └─ status: "copying"
```

### データフロー図

```
[ノード生成]                    [アップロード]                    [クローン]

createFileNode ──▶ 空FileNode    ファイル選択      オリジナルノード
       │                             │                    │
       ▼                             ▼                    ▼
category設定 ◀─────────── createUploadingFileData  createPendingCopyFileData
       │                             │                    │
       ▼                             ▼                    ▼
files: [] ◀──────────────── ストレージ保存      createCopyingFileData
                                     │                    │
                            ┌────────┴────────┐           │
                            │                 │           ▼
                            ▼                 ▼     ストレージコピー
               createUploadedFileData   createFailedFileData
                            │                 │           │
                            └────────┬────────┘           │
                                     │                    │
                                     ▼                    ▼
                               files配列に追加 ◀──────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| file.ts | `packages/protocol/src/node/variables/file.ts` | ソース | FileContent、FileDataスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | FileNode型、isFileNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| upload-file.ts | `packages/giselle/src/files/upload-file.ts` | ソース | ファイルアップロード処理 |
| copy-file.ts | `packages/giselle/src/files/copy-file.ts` | ソース | ファイルコピー処理 |
| get-file-text.ts | `packages/giselle/src/files/get-file-text.ts` | ソース | ファイルテキスト取得 |
