# 機能設計書 14-テキストノード

## 概要

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

### 本機能の処理概要

テキストノードは、ワークフロー内でテキストデータを格納・管理する機能である。ユーザーが入力したテキストや、外部から取得したテキストデータを保持し、接続された後続ノード（テキスト生成ノード、データクエリノード等）へ入力として提供する。

**業務上の目的・背景**：AIワークフローにおいて、静的なテキスト情報（プロンプトテンプレート、設定値、定型文等）を管理し、再利用可能な形で保持する必要がある。テキストノードは、そのようなテキストデータの一元管理を可能にし、ワークフローの可読性と保守性を向上させる。

**機能の利用シーン**：
- AIモデルへのプロンプトテンプレートを定義する場合
- 固定のテキスト入力をワークフローに組み込む場合
- 複数のノードで共通のテキストを参照する場合
- データクエリノードへのパラメータ値を提供する場合

**主要な処理内容**：
1. テキストデータの保持（プレーンテキストまたはJSON形式リッチテキスト）
2. 出力ポートを通じた後続ノードへのテキスト提供
3. ワークフロー保存時のテキストデータ永続化

**関連システム・外部連携**：
- テキストエディタUI（リッチテキスト編集）
- テキスト生成ノードへのプロンプト入力
- データクエリノードへのパラメータ提供

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | テキストノードの追加・編集、テキスト入力 |

## 機能種別

データ格納 / 変数管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "text" | Yes | ノードコンテンツタイプ | リテラル値 |
| text | string | Yes | テキストデータ | 任意の文字列（JSON形式リッチテキスト可） |

### 入力データソース

- **ノードプロパティパネル**: UIからのテキスト入力
- **リッチテキストエディタ**: ProseMirror/TipTap形式のJSON構造

## 出力仕様

### 出力データ

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

### 出力先

- 接続された後続ノードへのテキストデータ提供
- テキスト生成ノードのプロンプト入力
- データクエリノードのパラメータ値

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createTextNode）
   └─ デフォルトで空文字列のtextを設定
   └─ 出力ポート（accessor: "text"）を生成

2. テキスト編集
   └─ UIからのテキスト入力
   └─ プレーンテキストまたはリッチテキスト形式で保存

3. ワークフロー実行時
   └─ 接続されたノードがテキスト値を参照
   └─ JSON形式の場合はプレーンテキストに変換
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[空テキストで初期化]
    B --> C[出力ポート生成]
    C --> D{テキスト編集}
    D -->|入力| E[テキスト更新]
    E --> F[ワークスペース保存]
    F --> D
    D -->|実行| G[接続ノードからの参照]
    G --> H{JSON形式?}
    H -->|Yes| I[プレーンテキスト変換]
    H -->|No| J[そのまま使用]
    I --> K[値提供]
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト空文字 | 新規作成時、text = ""で初期化 | createTextNode実行時 |
| BR-002 | JSON変換 | isJsonContent判定がtrueの場合、jsonContentToPlainTextで変換 | テキスト参照時 |
| BR-003 | 出力ポート固定 | accessor = "text"の出力ポートを1つ持つ | ノード生成時 |

### 計算ロジック

特になし（データ格納ノードのため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし（ワークスペース保存で永続化） |

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

テキストノード単体でのDB操作はない。ワークスペース更新機能（No.3）と連携して動作する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 特になし |

### リトライ仕様

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

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

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

## パフォーマンス要件

特になし（データ格納ノードのため）

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

- テキストデータはワークスペースの一部として保存される
- 機密情報を含む場合はシークレット管理機能の利用を推奨

## 備考

- テキストノードのクローン時、テキスト内容はそのままコピーされる
- リッチテキスト形式はProseMirror/TipTapのJSON構造に準拠

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | text.ts | `packages/protocol/src/node/variables/text.ts` | TextContentのスキーマ定義、textプロパティ |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | TextNode型、isTextNode判定関数 |

**読解のコツ**: TextContentはtype: "text"とtextプロパティのみを持つシンプルな構造。

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

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

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

**主要処理フロー**:
- **462-496行目**: textVariableFactoryImplのcreate/clone実装
- **999-1001行目**: createTextNode関数のエクスポート

#### Step 3: テキスト変換ユーティリティを理解する

リッチテキストからプレーンテキストへの変換を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | text-editor-utils | `packages/text-editor-utils/src/` | isJsonContent、jsonContentToPlainText関数 |

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

```
createTextNode (node-factories.ts)
    │
    └─ TextNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ content.type: "text"
           ├─ content.text: ""
           ├─ inputs: []
           └─ outputs: [{accessor: "text"}]

テキスト参照時
    │
    ├─ isJsonContent判定
    │      └─ JSON形式かどうかチェック
    │
    └─ jsonContentToPlainText
           └─ リッチテキストをプレーンテキストに変換
```

### データフロー図

```
[ノード生成]                    [編集]                    [参照時]

createTextNode ──▶ 空TextNode ──▶ テキスト入力
                                       │
                                       ▼
                              ┌────────┴────────┐
                              │                 │
                              ▼                 ▼
                        プレーンテキスト    リッチテキスト(JSON)
                              │                 │
                              ▼                 ▼
                        そのまま保存     JSON文字列として保存
                              │                 │
                              └────────┬────────┘
                                       │
                                       ▼
                              [接続ノードから参照]
                                       │
                              ┌────────┴────────┐
                              │                 │
                              ▼                 ▼
                          isJsonContent = false  isJsonContent = true
                              │                 │
                              ▼                 ▼
                          そのまま使用   jsonContentToPlainText
                              │                 │
                              └────────┬────────┘
                                       │
                                       ▼
                                  テキスト値提供
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| text.ts | `packages/protocol/src/node/variables/text.ts` | ソース | TextContentスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | TextNode型、isTextNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| text-editor-utils | `packages/text-editor-utils/src/` | ソース | テキスト変換ユーティリティ |
