# 機能設計書 71-データストア取得

## 概要

本ドキュメントは、Giselleワークフローシステムにおけるデータストア取得機能の設計を記述する。この機能は、指定されたIDに基づいてデータストア（外部PostgreSQLデータベース接続）の設定情報を取得する。

### 本機能の処理概要

**業務上の目的・背景**：ワークフロー内のデータクエリノードが外部データベースにアクセスするためには、事前に設定されたデータストア接続情報が必要となる。この機能は、データストアIDを指定することで、対応する接続設定（プロバイダ種別、接続文字列シークレットID等）を取得し、クエリ実行時に必要な情報を提供する役割を担う。

**機能の利用シーン**：データクエリノードの実行時に、接続対象となるデータストアの設定を取得する場面で利用される。また、データストア設定画面において、既存の設定内容を表示・編集する際にも利用される。

**主要な処理内容**：
1. 入力されたデータストアIDからストレージパスを生成
2. ストレージ上にデータストア設定ファイルが存在するか確認
3. 存在する場合はJSONファイルを読み込み、DataStoreスキーマでバリデーション
4. バリデーション済みのDataStoreオブジェクトを返却

**関連システム・外部連携**：GiselleStorageを介したファイルストレージ（ローカルファイルシステムまたはクラウドストレージ）との連携を行う。

**権限による制御**：本機能自体には直接的な権限チェックは含まれないが、呼び出し元のAPI層でワークスペースへのアクセス権限が確認される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 33 | データストア設定画面 | 主機能 | データストア情報の取得と表示 |

## 機能種別

データ取得処理（Read操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselleの実行コンテキスト（ストレージアクセス等を含む） | - |
| dataStoreId | DataStoreId | Yes | 取得対象のデータストアID | `ds-`プレフィックス形式の文字列 |

### 入力データソース

- ストレージ（GiselleStorage）から `data-stores/{dataStoreId}/data-store.json` パスのJSONファイルを読み込む

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DataStore | DataStore \| undefined | データストア設定オブジェクト（存在しない場合はundefined） |
| DataStore.id | DataStoreId | データストアの一意識別子 |
| DataStore.provider | DataStoreProvider | プロバイダ種別（例: "postgres"） |
| DataStore.configuration | Record<string, unknown> | プロバイダ固有の設定（connectionStringSecretId等） |

### 出力先

呼び出し元関数への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. ストレージパス生成
   └─ dataStorePath(dataStoreId)を呼び出し、"data-stores/{id}/data-store.json"形式のパスを生成

2. ファイル存在確認
   └─ context.storage.exists(path)で対象ファイルの存在をチェック

3. 存在しない場合の処理
   └─ undefinedを返却して終了

4. JSONファイル読み込み
   └─ context.storage.getJson({path, schema: DataStore})でファイルを読み込み・バリデーション

5. DataStoreオブジェクト返却
   └─ バリデーション済みのDataStoreを呼び出し元に返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ストレージパス生成]
    B --> C{ファイル存在確認}
    C -->|存在しない| D[undefined返却]
    C -->|存在する| E[JSONファイル読み込み]
    E --> F[DataStoreスキーマでバリデーション]
    F --> G[DataStoreオブジェクト返却]
    D --> H[終了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 存在確認優先 | ファイル読み込み前に必ず存在確認を行う | 常時 |
| BR-02 | スキーマバリデーション | 読み込んだJSONは必ずDataStoreスキーマで検証する | ファイルが存在する場合 |
| BR-03 | 未存在時の安全な返却 | データストアが存在しない場合はundefinedを返却しエラーとしない | ファイルが存在しない場合 |

### 計算ロジック

該当なし

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

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

本機能はデータベースを直接操作しない。ストレージ（ファイルシステムまたはオブジェクトストレージ）からの読み取りのみを行う。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

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

該当なし（ストレージファイルアクセスのみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | ストレージアクセスに失敗した場合 | ストレージ設定・接続を確認 |
| - | スキーマバリデーションエラー | JSONファイルがDataStoreスキーマに適合しない場合 | データストアファイルの形式を確認 |

### リトライ仕様

ストレージアクセスエラーの場合、GiselleStorageの実装に依存したリトライが行われる可能性がある。本関数自体にはリトライロジックは含まれない。

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

本機能は読み取り専用のためトランザクション管理は不要。

## パフォーマンス要件

- 単一JSONファイルの読み込みのため、通常100ms以内に完了すること
- ストレージがリモートの場合はネットワークレイテンシに依存

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

- データストア設定には接続文字列のシークレットIDが含まれるが、実際の接続文字列は暗号化されたシークレットとして別途管理される
- 本機能は設定メタデータのみを返却し、機密情報の直接的な露出はない
- 呼び出し元でワークスペースへのアクセス権限確認が必要

## 備考

- DataStoreIdは`ds-`プレフィックスで始まるブランド型として定義されている
- プロバイダ種別は現時点で`postgres`のみがサポートされている

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/protocol/src/data-store/index.ts` | DataStoreId、DataStoreの型定義とZodスキーマ |

**読解のコツ**: `createIdGenerator`による`ds-`プレフィックスのID生成パターン、Zodスキーマによる型定義とバリデーションの統合パターンを理解する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | get-data-store.ts | `packages/giselle/src/data-stores/get-data-store.ts` | メイン関数の全体構造 |

**主要処理フロー**:
1. **5-11行目**: 関数シグネチャ - context（GiselleContext）とdataStoreIdを受け取る
2. **12行目**: dataStorePath関数でストレージパスを生成
3. **14-17行目**: ファイル存在確認、存在しない場合はundefinedを返却
4. **19-23行目**: getJsonでファイル読み込みとスキーマバリデーション
5. **24行目**: DataStoreオブジェクトを返却

#### Step 3: ストレージパス生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | paths.ts | `packages/giselle/src/data-stores/paths.ts` | パス生成ロジック |

**主要処理フロー**:
- **3-5行目**: `data-stores/{dataStoreId}/data-store.json`形式のパス生成

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

```
getDataStore()
    │
    ├─ dataStorePath(dataStoreId)
    │      └─ パス文字列を生成
    │
    ├─ context.storage.exists(path)
    │      └─ ファイル存在確認
    │
    └─ context.storage.getJson({path, schema})
           └─ JSONファイル読み込み＋バリデーション
```

### データフロー図

```
[入力]               [処理]                    [出力]

dataStoreId ───▶ dataStorePath() ───▶ ストレージパス
                                              │
                                              ▼
                           context.storage.exists()
                                              │
                               ┌──────────────┴──────────────┐
                               │                              │
                          [存在しない]                    [存在する]
                               │                              │
                               ▼                              ▼
                          undefined              context.storage.getJson()
                                                              │
                                                              ▼
                                                    DataStoreオブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-data-store.ts | `packages/giselle/src/data-stores/get-data-store.ts` | ソース | メイン関数 |
| paths.ts | `packages/giselle/src/data-stores/paths.ts` | ソース | ストレージパス生成 |
| index.ts | `packages/protocol/src/data-store/index.ts` | ソース | DataStore型定義 |
| types.ts | `packages/giselle/src/types/index.ts` | ソース | GiselleContext型定義 |
