# 画面設計書 32-ドキュメントVector Store設定画面

## 概要

ドキュメントをベクターストアとして管理するための設定画面。チームがアップロードしたドキュメントをベクトル化し、AIワークフロー内でDocument Vector Storeノードとして利用可能にする。

### 本画面の処理概要

**業務上の目的・背景**：AIワークフローで組織固有のドキュメント（マニュアル、FAQ、製品仕様書など）を活用するためには、事前にドキュメントデータをベクトル化してベクターストアに格納する必要がある。本画面は、そのドキュメントベクターストアの作成・管理を行うためのインターフェースを提供する。これにより、ワークフローエディタでDocument Vector Storeノードを利用してナレッジベースの検索が可能になる。

**画面へのアクセス方法**：設定画面 > チーム設定 > Vector Stores から「Document」タブを選択してアクセスする。URLは `/settings/team/vector-stores/document`。

**主要な操作・処理内容**：
1. ベクターストアの作成：「New Vector Store」ボタンからダイアログを開き、名前と埋め込みモデルを設定して新規ベクターストアを作成する
2. ベクターストア一覧の表示：作成済みのベクターストアをカード形式で表示し、各ストアの情報を確認できる
3. ベクターストアの編集：各ストアのアクションメニューから名前や埋め込みモデルの設定を更新できる
4. ベクターストアの削除：不要になったベクターストアを削除する
5. 公式ベクターストアの利用：Giselle公式が提供する公式ベクターストア（読み取り専用）も利用可能

**画面遷移**：
- 前画面：GitHub Vector Store設定画面（/settings/team/vector-stores）
- 関連画面：チーム設定画面（/settings/team）

**権限による表示制御**：
- プランによる制限：Free プランでは Document Vector Stores が利用不可（ロック状態で表示）
- Pro/Team プランでは利用可能だが、プランごとに最大ストア数の制限がある

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 79 | クエリサービス | 主機能 | ドキュメントのベクターストア設定と管理 |
| 78 | インジェストパイプライン | 補助機能 | ドキュメントデータのベクトルストアへの取り込み処理 |
| 76 | チャンク分割 | 補助機能 | ドキュメントの検索用チャンク分割処理 |
| 77 | 埋め込み生成 | 補助機能 | テキストのベクトル埋め込み変換処理 |

## 画面種別

一覧・登録・編集・削除

## URL/ルーティング

`/settings/team/vector-stores/document`

## 入出力項目

### ベクターストア作成ダイアログ

| 項目名 | 入出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| Name | 入力 | string | 必須 | ベクターストアの名前（例：Product Docs） |
| Embedding Models | 入力 | number[] | 必須 | 埋め込み生成に使用するモデル（複数選択可） |

### ベクターストア編集ダイアログ

| 項目名 | 入出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| Name | 入力 | string | 必須 | ベクターストアの名前 |
| Embedding Models | 入力 | number[] | 必須 | 埋め込みモデル（複数選択可） |

## 表示項目

### ベクターストア一覧

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ストア名 | string | ベクターストアの名前 |
| ID | string | ベクターストアの一意識別子（dvs_xxx形式） |
| 埋め込みプロファイル | object[] | 設定されている埋め込みモデル情報 |
| 使用状況 | string | 現在の使用数 / 最大数の形式で表示 |

### 公式ベクターストアセクション

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ストア名 | string | Giselle公式が提供するベクターストア |
| 状態 | string | 読み取り専用 |

## イベント仕様

### 1-ベクターストア作成ボタン押下

「New Vector Store」ボタン押下でダイアログが開き、フォーム入力後に「Create」ボタンでベクターストアを作成する。

1. 入力値のバリデーション（名前必須、埋め込みモデル最低1つ）
2. `createDocumentVectorStore` Server Action を呼び出し
3. プランのクォータ確認（最大ストア数に達していないか）
4. `document_vector_stores` テーブルにレコード挿入
5. `document_embedding_profiles` テーブルに埋め込みプロファイル挿入
6. 成功時：ダイアログを閉じ、一覧を更新（revalidatePath）
7. 失敗時：エラーメッセージを表示

### 2-ベクターストア編集ボタン押下

ストアのアクションメニューから「Edit」を選択して設定を変更する。

1. 編集ダイアログを開く
2. 名前と埋め込みプロファイルを変更
3. `updateDocumentVectorStore` Server Action を呼び出し
4. `document_vector_stores` テーブルを更新
5. `document_embedding_profiles` テーブルを差し替え
6. 一覧を更新（revalidatePath）

### 3-ベクターストア削除ボタン押下

ストアのアクションメニューから「Delete」を選択してベクターストアを削除する。

1. 確認ダイアログを表示
2. `deleteDocumentVectorStore` Server Action を呼び出し
3. `document_vector_store_sources` からソース情報を取得
4. `document_embedding_profiles` からプロファイルを削除
5. `document_vector_stores` テーブルからレコード削除
6. Supabase Storage から関連ファイルを削除（バックグラウンド）
7. 一覧を更新（revalidatePath）

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ベクターストア作成 | document_vector_stores | INSERT | ベクターストアの新規作成 |
| ベクターストア作成 | document_embedding_profiles | INSERT | 埋め込みプロファイルの関連付け |
| ベクターストア編集 | document_vector_stores | UPDATE | ベクターストア名の更新 |
| ベクターストア編集 | document_embedding_profiles | DELETE/INSERT | プロファイルの差し替え |
| ベクターストア削除 | document_vector_store_sources | DELETE | ソース情報の削除 |
| ベクターストア削除 | document_embedding_profiles | DELETE | プロファイルの削除 |
| ベクターストア削除 | document_vector_stores | DELETE | ベクターストアの削除 |

### テーブル別更新項目詳細

#### document_vector_stores

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | `dvs_${cuid2}` | 一意のベクターストアID |
| INSERT | team_db_id | 現在のチームのDB ID | チームとの関連付け |
| INSERT | name | ユーザー入力値 | ベクターストア名 |
| UPDATE | name | ユーザー入力値 | ベクターストア名の更新 |

#### document_embedding_profiles

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | document_vector_store_db_id | 親ストアのDB ID | 外部キー |
| INSERT | embedding_profile_id | 選択された埋め込みプロファイルID | 1:OpenAI Smallなど |
| INSERT | created_at | 現在日時 | 作成日時 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| 成功 | （ダイアログクローズ） | ベクターストア作成/編集成功時 |
| エラー | Name is required | 名前未入力時 |
| エラー | Select at least one embedding profile | 埋め込みモデル未選択時 |
| エラー | Document Vector Stores are not included in your plan. | Freeプランで作成試行時 |
| エラー | You've reached the maximum number of Document Vector Stores included in your plan. | クォータ超過時 |
| エラー | Vector store not found | 存在しないストアへの操作時 |
| エラー | Failed to create vector store. Please try again. | 作成処理の一般エラー |
| エラー | Failed to update vector store. Please try again. | 更新処理の一般エラー |
| エラー | Failed to delete vector store. Please try again. | 削除処理の一般エラー |
| 情報 | No document vector stores yet. | ベクターストア未作成時の空状態表示 |
| 警告 | Document Vector Stores are not included in the {plan} plan | Freeプランでのロック表示 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| プラン制限 | DocumentVectorStoreLockedCard を表示し、プランアップグレードを促す |
| クォータ超過 | 作成ボタンを無効化し、ツールチップで理由を表示 |
| ストア未検出 | エラーメッセージ「Vector store not found」を表示 |
| ストレージ削除失敗 | エラーをログに記録するが、DB削除は成功として扱う |

## 備考

- 埋め込みプロファイルは最低1つ選択する必要がある
- Cohereプロバイダーのプロファイルは選択不可（selectableProfilesでフィルタリング）
- 公式ベクターストアは読み取り専用で、設定変更や削除はできない
- ストレージの削除は `after()` を使用してバックグラウンドで実行される

---

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

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

### 推奨読解順序

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

まず、プログラム間で受け渡されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/types.ts` | ActionResult, DocumentVectorStoreUpdateInput などの型定義 |
| 1-2 | queries.ts | `apps/studio.giselles.ai/lib/vector-stores/document/queries.ts` | DocumentVectorStoreWithProfiles 型定義 |

**読解のコツ**: TypeScriptの型定義を先に理解することで、データの流れが把握しやすくなる。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document/page.tsx` | Server Component としてのページレンダリング |

**主要処理フロー**:
1. **行16-20**: ベクターストア一覧、公式ストア、チーム情報を並列取得
2. **行21-30**: クォータ計算と作成可否の判定
3. **行32-50**: DocumentVectorStoreCreateDialog と DocumentVectorStoreList のレンダリング

#### Step 3: データ取得層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/data.ts` | getDocumentVectorStores, getOfficialDocumentVectorStores のエクスポート |
| 3-2 | queries.ts | `apps/studio.giselles.ai/lib/vector-stores/document/queries.ts` | 実際のDB取得ロジック |

#### Step 4: Server Actions を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | actions.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/actions.ts` | createDocumentVectorStore, updateDocumentVectorStore, deleteDocumentVectorStore |

**主要処理フロー**:
- **行607-626**: validateDocumentEmbeddingProfileIds - 埋め込みプロファイルの検証
- **行628-712**: createDocumentVectorStore - ベクターストアの作成
- **行714-788**: updateDocumentVectorStore - ベクターストアの更新
- **行790-903**: deleteDocumentVectorStore - ベクターストアの削除（ストレージクリーンアップ含む）

#### Step 5: UIコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | document-store-create-dialog.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document-store-create-dialog.tsx` | 作成ダイアログのUI実装 |
| 5-2 | document-vector-store-list.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document-vector-store-list.tsx` | ストア一覧の表示コンポーネント |
| 5-3 | document-vector-store-item.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document/document-vector-store-item.tsx` | 個別ストアカードの表示 |

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

```
DocumentVectorStorePage (document/page.tsx)
    │
    ├─ getDocumentVectorStores() ────────────────────────▶ ベクターストア一覧取得
    │      └─ DB Query (documentVectorStores + documentEmbeddingProfiles)
    │
    ├─ getOfficialDocumentVectorStores() ────────────────▶ 公式ストア取得
    │
    ├─ fetchCurrentTeam() ───────────────────────────────▶ チーム情報取得
    │
    └─ getDocumentVectorStoreQuota() ────────────────────▶ クォータ計算
```

### データフロー図

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

User Input                      ┌─────────────────────┐
(name/embeddingProfiles) ───▶   │ createDocument      │
                                │ VectorStore()       │ ─────────▶ DB Insert
                                └─────────────────────┘             (document_vector_stores,
                                        │                            document_embedding_profiles)
                                        ▼
                                ┌─────────────────────┐
                                │ validateDocument    │
                                │ EmbeddingProfileIds │ ─────────▶ 検証結果
                                └─────────────────────┘

DB Records                      ┌─────────────────────┐
(document_vector_stores) ───▶   │ getDocument         │
                                │ VectorStores()      │ ─────────▶ DocumentVectorStoreWithProfiles[]
                                └─────────────────────┘
                                        │
                                        ▼
                                ┌─────────────────────┐
                                │ DocumentVector      │ ─────────▶ 画面表示
                                │ StoreList           │
                                └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document/page.tsx` | ソース | ページのエントリーポイント |
| actions.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/actions.ts` | ソース | Server Actions |
| data.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/data.ts` | ソース | データ取得関数のエクスポート |
| types.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/types.ts` | ソース | 型定義 |
| document-store-create-dialog.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document-store-create-dialog.tsx` | ソース | 作成ダイアログコンポーネント |
| document-vector-store-list.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document-vector-store-list.tsx` | ソース | ストア一覧コンポーネント |
| document-vector-store-item.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document/document-vector-store-item.tsx` | ソース | 個別ストアカードコンポーネント |
| document-vector-store-item-readonly.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document/document-vector-store-item-readonly.tsx` | ソース | 公式ストア用読み取り専用コンポーネント |
| document-embedding-profiles.ts | `apps/studio.giselles.ai/app/(main)/settings/team/vector-stores/document-embedding-profiles.ts` | ソース | 埋め込みプロファイルの定義 |
