# 機能設計書 12-アプリエントリーノード

## 概要

本ドキュメントは、Giselleワークフローエンジンにおけるアプリエントリーノード（AppEntryNode）の機能設計を記述する。アプリエントリーノードは、公開アプリケーションのエントリーポイントを定義し、外部からの入力パラメータを受け取るための操作ノードである。

### 本機能の処理概要

アプリエントリーノードは、ワークフローをアプリケーションとして公開する際のエントリーポイントを定義する機能である。ユーザーがアプリを実行する際に必要なパラメータ（テキスト入力、ファイル入力等）を定義し、それらを後続のノードで利用可能な形式で出力する。

**業務上の目的・背景**：Giselleで作成したワークフローを、エンドユーザーが利用可能なアプリケーションとして公開するためには、明確な入力インターフェースが必要となる。アプリエントリーノードは、この入力インターフェースを定義し、外部API呼び出しやステージ実行からの入力を受け付ける役割を担う。

**機能の利用シーン**：
- ワークフローをWeb APIとして公開し、外部システムから呼び出す場合
- ワークフローをプレイグラウンドで実行テストする場合
- GitHubトリガーと連携したアプリを構築する場合
- エンドユーザー向けのアプリケーションインターフェースを定義する場合

**主要な処理内容**：
1. アプリパラメータ（名前、説明、アイコン、入力パラメータリスト）の定義
2. パラメータごとの型（text、multiline-text、number、files）の指定
3. パラメータの必須/任意設定
4. アプリ保存時の設定確定（unconfigured → configured状態への遷移）
5. 出力ポートを通じた入力値の後続ノードへの伝播

**関連システム・外部連携**：
- アプリ管理機能（save-app、get-app）との連携
- 終了ノード（EndNode）との組み合わせによるアプリフロー定義
- 外部API（HTTP経由）からの入力受け付け

**権限による制御**：アプリの公開・設定変更はワークスペースの編集権限を持つユーザーのみ可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | アプリエントリーノードの追加・編集、パラメータ設定 |
| 18 | プレイグラウンド画面 | 結果表示画面 | アプリの実行テスト、パラメータ入力 |

## 機能種別

設定定義 / データ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | アプリ名 | 空文字列でないこと |
| description | string | Yes | アプリの説明 | - |
| iconName | string | Yes | アイコン名 | 空文字列でないこと |
| parameters | AppParameter[] | Yes | 入力パラメータ配列 | 配列形式 |
| parameters[].id | AppParameterId | Yes | パラメータID | appprm-で始まる形式 |
| parameters[].name | string | Yes | パラメータ名 | 空文字列でないこと |
| parameters[].type | AppParameterType | Yes | パラメータ型 | text/multiline-text/number/files |
| parameters[].required | boolean | Yes | 必須フラグ | - |

### 入力データソース

- **ノードプロパティパネル**: UIからの設定入力
- **外部API呼び出し時**: HTTPリクエストボディからのパラメータ値
- **プレイグラウンド実行時**: ダイアログからのユーザー入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| outputs | Output[] | パラメータごとの出力ポート |
| outputs[].id | OutputId | 出力ポートID |
| outputs[].label | string | パラメータ名（表示用） |
| outputs[].accessor | AppParameterId | パラメータIDをアクセサーとして使用 |

### 出力先

- 接続された後続ノード（テキスト生成ノード、アクションノード等）への入力提供
- タスク実行時のGenerationContextInputとして利用

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createAppEntryNode）
   └─ デフォルトのDraftApp設定を生成
   └─ デフォルトパラメータ（Input (Text)、Input (File)）を設定
   └─ 出力ポートをパラメータに基づいて生成

2. パラメータ編集
   └─ UIからパラメータの追加・削除・編集
   └─ 出力ポートの動的更新

3. アプリ保存（save-app呼び出し時）
   └─ status: "unconfigured" → "configured"へ遷移
   └─ appIdの割り当て
   └─ draftAppの設定を確定

4. タスク実行時
   └─ GenerationContextInputからパラメータ値を取得
   └─ 出力ポートを通じて後続ノードへ値を伝播
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[DraftApp初期化]
    B --> C[デフォルトパラメータ設定]
    C --> D[出力ポート生成]
    D --> E{パラメータ編集}
    E -->|追加| F[パラメータ追加]
    E -->|削除| G[パラメータ削除]
    E -->|編集| H[パラメータ更新]
    F --> I[出力ポート更新]
    G --> I
    H --> I
    I --> E
    E -->|保存| J{アプリ保存}
    J --> K[status: configured]
    K --> L[AppId割り当て]
    L --> M[保存完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトパラメータ | 新規作成時、"Input (Text)"（multiline-text、必須）と"Input (File)"（files、任意）をデフォルト設定 | createAppEntryNode実行時 |
| BR-002 | 状態管理 | unconfigured状態ではdraftApp情報を保持、configured状態ではappIdを保持 | ノードの状態に応じて |
| BR-003 | 出力ポート同期 | パラメータの追加・削除に応じて出力ポートを動的に更新 | パラメータ変更時 |
| BR-004 | クローン時リセット | ノードクローン時はunconfigured状態にリセットされる | cloneNode実行時 |

### 計算ロジック

特になし（設定定義ノードのため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし（アプリ保存時にApp情報が保存される） |

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

アプリエントリーノード単体でのDB操作はない。アプリ保存機能（No.60）と連携して動作する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | unconfigured状態でタスク実行 | "Start node is unconfigured" エラーを返却 |
| - | Error | starterNodeがAppEntryNodeでない | "starterNode must be an start node" エラーを返却 |

### リトライ仕様

本機能はリトライ機構を持たない。

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

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

## パフォーマンス要件

特になし（設定定義ノードのため）

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

- パラメータ値はタスク実行コンテキストに含まれ、ストレージに保存される
- ファイルパラメータは適切なファイル管理機能を通じて処理される

## 備考

- アプリエントリーノードと終了ノード（EndNode）を組み合わせることで、ConnectedApp（state: "connected"）として保存可能
- 終了ノードがない場合はDisconnectedApp（state: "disconnected"）として保存される

---

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

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

### 推奨読解順序

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

まず、アプリエントリーノードとアプリのスキーマ定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | app-entry.ts | `packages/protocol/src/node/operations/app-entry.ts` | AppEntryContent、DraftApp、状態管理（unconfigured/configured） |
| 1-2 | app.ts | `packages/protocol/src/app/app.ts` | App、AppParameter、ConnectedApp/DisconnectedAppの定義 |
| 1-3 | operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | AppEntryNode型、isAppEntryNode判定関数 |

**読解のコツ**: z.discriminatedUnionによる状態管理パターンに注目。statusフィールドでunconfigured/configuredを判別する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | node-factories.ts | `packages/node-registry/src/node-factories.ts` | appEntryFactoryImpl、createDefaultDraftApp関数 |

**主要処理フロー**:
- **134-154行目**: createDefaultDraftApp関数でデフォルトパラメータを定義
- **748-804行目**: appEntryFactoryImplのcreate/clone実装
- **1039-1041行目**: createAppEntryNode関数のエクスポート

#### Step 3: タスク実行時の利用を理解する

タスク作成時にアプリエントリーノードがどのように処理されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-task.ts | `packages/giselle/src/tasks/create-task.ts` | starterNodeの判定、AppEntryNode利用時のフロー |

**主要処理フロー**:
- **124-126行目**: starterNodeとしてTriggerNodeまたはAppEntryNodeを検出
- **128-133行目**: unconfigured状態のチェックとエラー処理
- **278-289行目**: api/stage起点時のstarter設定

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

```
createAppEntryNode (node-factories.ts)
    │
    └─ createDefaultDraftApp
           ├─ AppParameterId.generate()
           └─ デフォルトパラメータ設定

createTask (create-task.ts)
    │
    ├─ isAppEntryNode チェック
    │
    └─ TaskStarter設定
           └─ type: "app", appId
```

### データフロー図

```
[ノード作成]                    [アプリ保存]                    [タスク実行]

createAppEntryNode ──▶ DraftApp設定 ──▶ save-app ──▶ App保存
       │                                    │
       ▼                                    ▼
  OutputPort生成                    status: configured
       │                                    │
       ▼                                    ▼
パラメータ定義 ◀─────────────────── AppId割り当て
       │
       ▼
[タスク実行時]
       │
GenerationContextInput ──▶ パラメータ値取得 ──▶ 後続ノードへ出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| app-entry.ts | `packages/protocol/src/node/operations/app-entry.ts` | ソース | AppEntryContentスキーマ定義 |
| app.ts | `packages/protocol/src/app/app.ts` | ソース | App、AppParameterスキーマ定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | AppEntryNode型、isAppEntryNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| create-task.ts | `packages/giselle/src/tasks/create-task.ts` | ソース | タスク作成時のAppEntryNode処理 |
| save-app.ts | `packages/giselle/src/apps/save-app.ts` | ソース | アプリ保存処理 |
| app-entry-input-dialog | `internal-packages/workflow-designer-ui/src/app/app-entry-input-dialog/` | ソース | パラメータ入力ダイアログUI |
