# 機能設計書 19-データストアノード

## 概要

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

### 本機能の処理概要

データストアノードは、ワークフロー内で外部データベースへの接続情報を管理する機能である。PostgreSQL等のデータストアへの参照を保持し、接続されたデータクエリノード（No.11）で実際のクエリ実行を可能にするためのコンテキストを提供する。

**業務上の目的・背景**：AIワークフローにおいて、外部データベースのデータを参照して処理を行うケースが増加している。データストアノードは、そのようなデータベース接続の設定を管理し、セキュアな接続情報の保持とデータクエリノードとの連携を実現する。

**機能の利用シーン**：
- PostgreSQLデータベースからデータを取得してAI処理を行う場合
- 業務データベースの情報を基にAI分析を行う場合
- データクエリノードと組み合わせてデータ駆動型ワークフローを構築する場合

**主要な処理内容**：
1. データストアID（外部設定済みデータストア）への参照保持
2. unconfigured/configured状態の管理
3. 出力ポート（Schema、Source）を通じたデータクエリノードへの接続情報提供

**関連システム・外部連携**：
- データクエリノード（No.11）との連携
- データストア管理機能（No.70-73）
- 外部PostgreSQLデータベース

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | データストアノードの追加・編集 |
| 33 | データストア設定画面 | 設定画面 | データストア接続設定 |

## 機能種別

設定定義 / 外部接続管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "dataStore" | Yes | ノードコンテンツタイプ | リテラル値 |
| state | DataStoreState | Yes | 設定状態 | configured/unconfigured |

### DataStoreState構造

#### Configured状態

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| status | "configured" | Yes | 設定済み状態 |
| dataStoreId | DataStoreId | Yes | データストアID（ds-で始まる） |

#### Unconfigured状態

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| status | "unconfigured" | Yes | 未設定状態 |

### 入力データソース

- **設定画面**: データストア選択

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| outputs | Output[] | 出力ポート配列（2要素） |
| outputs[0].id | OutputId | 出力ポートID |
| outputs[0].label | "Schema" | スキーマ情報出力 |
| outputs[0].accessor | "schema" | アクセサー名 |
| outputs[1].id | OutputId | 出力ポートID |
| outputs[1].label | "Source" | ソース情報出力 |
| outputs[1].accessor | "source" | アクセサー名 |

### 出力先

- 接続されたデータクエリノードへのデータストア参照提供

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createDataStoreNode）
   └─ status: "unconfigured"で初期化
   └─ 出力ポート（Schema、Source）を生成

2. データストア設定
   └─ 設定画面でデータストア選択
   └─ status: "configured"へ遷移
   └─ dataStoreIdを設定

3. ワークフロー実行時
   └─ データクエリノードがdataStoreIdを参照
   └─ データストア設定からの接続情報取得
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[status: unconfigured]
    B --> C[出力ポート生成]
    C --> D{データストア設定}
    D -->|設定画面| E[データストア選択]
    E --> F[status: configured]
    F --> G[dataStoreId設定]
    G --> H[ワークスペース保存]
    H --> I[データクエリノードから参照]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 状態管理 | unconfigured状態ではdataStoreIdを持たない | 状態に応じて |
| BR-002 | クローン時リセット | ノードクローン時はunconfigured状態にリセット | cloneNode実行時 |
| BR-003 | デフォルト名 | ノード名は"Data Store" | ノード生成時 |
| BR-004 | 複数出力 | Schema出力とSource出力の2つを持つ | ノード生成時 |

### 計算ロジック

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

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし |

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

データストアノード単体でのDB操作はない。データストア管理機能と連携して動作する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | unconfigured状態でクエリ実行 | データクエリノード側でエラー処理 |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- データストアIDのみを保持し、接続文字列等の機密情報はシークレット管理機能で管理
- 実際の接続はデータクエリノード実行時に行われる

## 備考

- DataStoreId: "ds-"で始まるID
- データストア設定はワークスペースレベルで管理される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | data-store.ts | `packages/protocol/src/node/variables/data-store.ts` | DataStoreContent、DataStoreStateのスキーマ定義 |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | DataStoreNode型、isDataStoreNode判定関数 |
| 1-3 | data-store/index.ts | `packages/protocol/src/data-store/index.ts` | DataStoreId、DataStoreスキーマ定義 |

**読解のコツ**: DataStoreStateはstatus（configured/unconfigured）によって異なるプロパティを持つdiscriminatedUnion型。

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

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

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

**主要処理フロー**:
- **629-674行目**: dataStoreFactoryImplのcreate/clone実装
- **1027-1029行目**: createDataStoreNode関数のエクスポート

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

```
createDataStoreNode (node-factories.ts)
    │
    └─ DataStoreNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ name: "Data Store"
           ├─ content.type: "dataStore"
           ├─ content.state.status: "unconfigured"
           ├─ inputs: []
           └─ outputs: [{accessor: "schema"}, {accessor: "source"}]
```

### データフロー図

```
[ノード生成]                    [設定]                    [利用]

createDataStoreNode ──▶ unconfigured ──▶ 設定画面で設定
       │                                        │
       ▼                                        ▼
state.status: unconfigured ◀────── configured
       │                                │
       ▼                                ▼
dataStoreId: なし              dataStoreId: ds-xxx
       │                                │
       └────────────────┬───────────────┘
                        │
                        ▼
                 データクエリノードから参照
                        │
                        ▼
          dataStoreIdで接続設定取得
                        │
                        ▼
                 クエリ実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| data-store.ts | `packages/protocol/src/node/variables/data-store.ts` | ソース | DataStoreContentスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | DataStoreNode型、isDataStoreNode関数 |
| data-store/index.ts | `packages/protocol/src/data-store/index.ts` | ソース | DataStoreId、DataStoreスキーマ定義 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| create-data-store.ts | `packages/giselle/src/data-stores/create-data-store.ts` | ソース | データストア作成処理 |
| get-data-store.ts | `packages/giselle/src/data-stores/get-data-store.ts` | ソース | データストア取得処理 |
