# 機能設計書 17-ベクトルストアノード

## 概要

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

### 本機能の処理概要

ベクトルストアノードは、ワークフロー内でベクトルストアへの参照を管理する機能である。GitHubリポジトリまたはドキュメントベースのベクトルストアを参照し、接続されたクエリノードで類似検索を実行するためのコンテキストを提供する。

**業務上の目的・背景**：RAG（Retrieval-Augmented Generation）ベースのAIワークフローにおいて、ベクトルストアは知識ベースとして重要な役割を果たす。ベクトルストアノードは、そのようなベクトルストアへの接続を管理し、クエリノードとの連携を可能にする。

**機能の利用シーン**：
- GitHubリポジトリのコード/Issue/Pull Requestを検索する場合
- ドキュメントコレクションから類似文書を検索する場合
- RAGベースのAIアシスタントを構築する場合

**主要な処理内容**：
1. ベクトルストアソース（github/document）の選択
2. ソース固有の設定（リポジトリ情報、ドキュメントストアID等）
3. 埋め込みプロファイルの指定（オプション）
4. unconfigured/configured状態の管理
5. クエリノードへの接続とコンテキスト提供

**関連システム・外部連携**：
- クエリノード（No.10）との連携
- RAG機能（No.76-80）
- GitHubリポジトリ
- ドキュメントベクトルストア

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | ベクトルストアノードの追加・編集 |
| 31 | GitHub Vector Store設定画面 | 設定画面 | GitHubリポジトリのベクターストア設定 |
| 32 | ドキュメントVector Store設定画面 | 設定画面 | ドキュメントのベクターストア設定 |

## 機能種別

設定定義 / 外部参照管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "vectorStore" | Yes | ノードコンテンツタイプ | リテラル値 |
| source | VectorStoreSource | Yes | ソース設定 | github/document |

### GitHubVectorStoreSource（provider: "github"）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| provider | "github" | Yes | プロバイダー識別子 |
| state.status | "configured" / "unconfigured" | Yes | 設定状態 |
| state.owner | string | configured時 | リポジトリオーナー |
| state.repo | string | configured時 | リポジトリ名 |
| state.contentType | "blob" / "pull_request" / "issue" | configured時 | コンテンツタイプ |
| state.embeddingProfileId | number | オプション | 埋め込みプロファイルID |

### DocumentVectorStoreSource（provider: "document"）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| provider | "document" | Yes | プロバイダー識別子 |
| state.status | "configured" / "unconfigured" | Yes | 設定状態 |
| state.documentVectorStoreId | string | configured時 | ドキュメントストアID |
| state.embeddingProfileId | number | オプション | 埋め込みプロファイルID |

### 入力データソース

- **設定画面**: GitHubリポジトリ選択またはドキュメントストア選択

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createVectorStoreNode / createGitHubVectorStoreNode / createDocumentVectorStoreNode）
   └─ プロバイダー（github/document）を指定
   └─ status: "unconfigured"で初期化
   └─ 出力ポート（accessor: "source"）を生成

2. ベクトルストア設定
   └─ 設定画面でソース選択
   └─ status: "configured"へ遷移
   └─ ソース固有の設定を保存

3. ワークフロー実行時
   └─ クエリノードがベクトルストア参照を利用
   └─ 類似検索を実行
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[プロバイダー選択]
    B --> C{プロバイダー}
    C -->|github| D[GitHubノード生成]
    C -->|document| E[ドキュメントノード生成]
    D --> F[status: unconfigured]
    E --> F
    F --> G{設定}
    G -->|GitHub設定| H[owner/repo/contentType設定]
    G -->|ドキュメント設定| I[documentVectorStoreId設定]
    H --> J[status: configured]
    I --> J
    J --> K[ワークスペース保存]
    K --> L[クエリノードから参照]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | プロバイダー固定 | ノード生成時に指定されたプロバイダーは変更不可 | ノード生成後 |
| BR-002 | 状態管理 | unconfigured状態ではソース固有設定を持たない | 状態に応じて |
| BR-003 | クローン時リセット | ノードクローン時はunconfigured状態にリセット | cloneNode実行時 |
| BR-004 | デフォルト名 | GitHubは"GitHub Docs"、ドキュメントは"Documents" | ノード生成時 |

### 計算ロジック

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

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

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

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

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

ベクトルストアノード単体でのDB操作はない。ワークスペース更新機能と連携して動作する。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- GitHubリポジトリへのアクセスはGitHub連携設定に依存
- プライベートリポジトリへのアクセスにはGitHub Appインストールが必要

## 備考

- VectorStoreProvider: "github" | "document"
- GitHubコンテンツタイプ: "blob" | "pull_request" | "issue"
- 埋め込みプロファイルはオプションで、デフォルトプロファイルが使用される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | vector-store.ts | `packages/protocol/src/node/variables/vector-store.ts` | VectorStoreContent、GitHubVectorStoreSource、DocumentVectorStoreSourceのスキーマ定義 |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | VectorStoreNode型、isVectorStoreNode判定関数 |

**読解のコツ**: z.discriminatedUnionによるプロバイダー判別パターンと、状態管理（configured/unconfigured）のネストに注目。

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

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

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

**主要処理フロー**:
- **578-627行目**: vectorStoreFactoryImplのcreate/clone実装
- **1013-1025行目**: createVectorStoreNode、createGitHubVectorStoreNode、createDocumentVectorStoreNode関数

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

```
createVectorStoreNode (node-factories.ts)
    │
    └─ VectorStoreNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ name: vectorStoreNodeDefaultName(provider)
           ├─ content.type: "vectorStore"
           ├─ content.source.provider: github/document
           ├─ content.source.state.status: "unconfigured"
           ├─ inputs: []
           └─ outputs: [{accessor: "source"}]
```

### データフロー図

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

createVectorStoreNode ──▶ unconfigured ──▶ 設定画面で設定
       │                                        │
       ▼                                        ▼
provider選択 ◀─────────────────────── configured
       │                                        │
       ▼                                        ▼
source.state: unconfigured      source.state: configured
       │                              │
       └──────────────┬───────────────┘
                      │
                      ▼
               クエリノードから参照
                      │
                      ▼
                類似検索実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| vector-store.ts | `packages/protocol/src/node/variables/vector-store.ts` | ソース | VectorStoreContentスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | VectorStoreNode型、isVectorStoreNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| node-default-name.ts | `packages/node-registry/src/node-default-name.ts` | ソース | vectorStoreNodeDefaultName関数 |
| query-service | `packages/rag/src/query-service/` | ソース | ベクトルストアクエリ実行 |
