# ナレッジベースの強化機能設計

## 🎯 機能概要

今回の開発には、以下の3つのコア機能が含まれます：

1. **ナレッジベースのグループ化** - グループを作成し、ドキュメントを複数のグループに所属させ、検索時にグループを指定可能にします。
2. **検索履歴** - 対話プロセス全体を保存し、過去の会話の閲覧や再開を可能にします。
3. **PDF プレビュー** - すべてのファイルを PDF 形式に変換し、オンラインでプレビューできるようにします。

## 🗄️ データベース設計

### 新規テーブル構造

```sql
-- ナレッジベースグループ管理テーブル
CREATE TABLE knowledge_groups (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  color TEXT DEFAULT '#3B82F6', -- グループの色分けID
  user_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- ドキュメント・グループ関連付けテーブル (多対多)
CREATE TABLE knowledge_base_groups (
  knowledge_base_id TEXT NOT NULL,
  group_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (knowledge_base_id, group_id),
  FOREIGN KEY (knowledge_base_id) REFERENCES knowledge_base(id) ON DELETE CASCADE,
  FOREIGN KEY (group_id) REFERENCES knowledge_groups(id) ON DELETE CASCADE
);

-- 検索履歴テーブル
CREATE TABLE search_history (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  title TEXT NOT NULL, -- 対話タイトル (質問の先頭50文字)
  selected_groups TEXT, -- JSON配列: ["group1", "group2"] または null(すべて)
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 対話メッセージテーブル
CREATE TABLE chat_messages (
  id TEXT PRIMARY KEY,
  search_history_id TEXT NOT NULL,
  role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
  content TEXT NOT NULL,
  sources TEXT, -- JSON配列: 引用ソース情報
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (search_history_id) REFERENCES search_history(id) ON DELETE CASCADE
);
```

### 既存テーブルの修正

```sql
-- knowledge_base テーブルに PDF パスフィールドを追加
ALTER TABLE knowledge_base ADD COLUMN pdf_path TEXT;
```

## 🔌 API エンドポイント設計

### ナレッジベースグループ API

```typescript
// ユーザーの全グループを取得
GET /api/knowledge-groups
Response: {
  groups: Array<{
    id: string;
    name: string;
    description?: string;
    color: string;
    fileCount: number; // 含まれるファイル数
    createdAt: string;
  }>
}

// グループの作成
POST /api/knowledge-groups
Body: { name: string; description?: string; color?: string }
Response: { id: string; name: string; description?: string; color: string }

// グループの更新
PUT /api/knowledge-groups/:id
Body: { name?: string; description?: string; color?: string }

// グループの削除
DELETE /api/knowledge-groups/:id

// グループ内のファイルを取得
GET /api/knowledge-groups/:id/files
Response: { files: KnowledgeBase[] }

// ファイルをグループに追加
POST /api/knowledge-bases/:fileId/groups
Body: { groupIds: string[] }

// グループからファイルを削除
DELETE /api/knowledge-bases/:fileId/groups/:groupId
```

### 検索履歴 API

```typescript
// 検索履歴の取得 (ページネーション)
GET /api/search-history?page=1&limit=20
Response: {
  histories: Array<{
    id: string;
    title: string;
    selectedGroups: string[] | null;
    messageCount: number;
    lastMessageAt: string;
    createdAt: string;
  }>;
  total: number;
  page: number;
  limit: number;
}

// 対話詳細の取得
GET /api/search-history/:id
Response: {
  id: string;
  title: string;
  selectedGroups: string[] | null;
  messages: Array<{
    id: string;
    role: 'user' | 'assistant';
    content: string;
    sources?: Array<{
      fileName: string;
      content: string;
      score: number;
      chunkIndex: number;
    }>;
    createdAt: string;
  }>;
}

// 新しい対話の作成
POST /api/search-history
Body: { 
  title: string; 
  selectedGroups?: string[]; 
  firstMessage: string;
}
Response: { id: string }

// 対話の削除
DELETE /api/search-history/:id

// 対話の継続 (既存のチャットインターフェースを拡張し、historyId パラメータを追加)
POST /api/chat/stream
Body: {
  message: string;
  history: ChatMessage[];
  userLanguage?: string;
  selectedGroups?: string[]; // 新規：選択されたグループ
  historyId?: string; // 新規：対話履歴ID
}
```

### PDF プレビュー API

```typescript
// ファイルの PDF プレビューを取得
GET /api/knowledge-bases/:id/pdf
Response: PDF ファイルストリーム、または PDF URL へのリダイレクト

// PDF ステータスの確認
GET /api/knowledge-bases/:id/pdf-status
Response: {
  status: 'pending' | 'converting' | 'ready' | 'failed';
  pdfPath?: string;
  error?: string;
}
```

## 🎨 フロントエンドコンポーネント設計

### 1. ナレッジベースグループコンポーネント

```typescript
// グループマネージャー
interface GroupManagerProps {
  groups: KnowledgeGroup[];
  onCreateGroup: (group: CreateGroupData) => void;
  onUpdateGroup: (id: string, data: UpdateGroupData) => void;
  onDeleteGroup: (id: string) => void;
}

// グループセレクター (検索時の選択用)
interface GroupSelectorProps {
  groups: KnowledgeGroup[];
  selectedGroups: string[];
  onSelectionChange: (groupIds: string[]) => void;
  showSelectAll?: boolean;
}

// ファイルグループタグ
interface FileGroupTagsProps {
  fileId: string;
  groups: KnowledgeGroup[];
  assignedGroups: string[];
  onGroupsChange: (groupIds: string[]) => void;
}
```

### 2. 検索履歴コンポーネント

```typescript
// 履歴リスト
interface SearchHistoryListProps {
  histories: SearchHistoryItem[];
  onSelectHistory: (historyId: string) => void;
  onDeleteHistory: (historyId: string) => void;
  onLoadMore: () => void;
  hasMore: boolean;
}

// 履歴対話ビューアー
interface HistoryViewerProps {
  historyId: string;
  onContinueChat: (historyId: string) => void;
  onClose: () => void;
}
```

### 3. PDF プレビューコンポーネント

```typescript
// PDF プレビューアー
interface PDFPreviewProps {
  fileId: string;
  fileName: string;
  onClose: () => void;
}

// PDF プレビューボタン
interface PDFPreviewButtonProps {
  fileId: string;
  fileName: string;
  status: 'pending' | 'converting' | 'ready' | 'failed';
}
```

## 🔄 ビジネスフロー設計

### ナレッジベースグループ化フロー

```
1. ユーザーがグループを作成 → knowledge_groups テーブルに保存
2. ファイルアップロード時 → グループを選択可能 → knowledge_base_groups テーブルに関連付けを保存
3. 検索時 → グループを選択 → Elasticsearch のクエリ範囲をフィルタリング
4. ファイル管理 → ファイルの所属グループを編集可能
```

### 検索履歴フロー

```
1. ユーザーがチャットを開始 → search_history データを生成
2. 各メッセージ → chat_messages テーブルに保存
3. 履歴の確認 → 履歴リストをページネーションでロード
4. 履歴をクリック → 対話内容全体をロード
5. 対話の継続 → 既存の履歴をベースに新しいメッセージを追加
```

### PDF プレビューフロー

```
1. ファイルアップロード → PDF かどうかを確認
2. PDF 以外の場合 → LibreOffice を呼び出して PDF に変換
3. PDF パスを knowledge_base.pdf_path に保存
4. フロントエンドからプレビューをリクエスト → PDF ファイルストリームを返却
5. HTML の <embed> または <iframe> を使用して PDF を表示
```

## 🛠️ 技術実装のポイント

### 1. ES クエリ最適化 (グループフィルタリング)

```typescript
// ElasticsearchService.hybridSearch を修正
async hybridSearch(
  queryVector: number[],
  queryText: string,
  userId: string,
  topK: number = 10,
  threshold: number = 0.6,
  selectedGroups?: string[] // 新規パラメータ
): Promise<any[]> {
  
  // グループフィルタリング条件を構築
  const groupFilter = selectedGroups?.length 
    ? { terms: { "knowledge_base_id": await this.getFileIdsByGroups(selectedGroups, userId) } }
    : undefined;

  // ES クエリにフィルタ条件を追加
  const query = {
    bool: {
      must: [/* 既存のクエリ条件 */],
      filter: [
        { term: { user_id: userId } },
        ...(groupFilter ? [groupFilter] : [])
      ]
    }
  };
}
```

### 2. PDF 変換サービスの統合

```typescript
// KnowledgeBaseService に PDF 変換を追加
async ensurePDFExists(kb: KnowledgeBase): Promise<string> {
  if (kb.pdfPath && await fs.pathExists(kb.pdfPath)) {
    return kb.pdfPath;
  }

  if (kb.mimetype === 'application/pdf') {
    // 既に PDF なので、元のファイルをそのまま使用
    kb.pdfPath = kb.storagePath;
  } else {
    // LibreOffice を呼び出して変換
    const pdfPath = await this.libreOfficeService.convertToPDF(kb.storagePath);
    kb.pdfPath = pdfPath;
  }

  await this.knowledgeBaseRepository.save(kb);
  return kb.pdfPath;
}
```

### 3. チャット履歴の保存

```typescript
// ChatService.streamChat メソッドを修正
async *streamChat(
  message: string,
  history: ChatMessage[],
  userId: string,
  modelConfig: ModelConfig,
  userLanguage: string = 'zh',
  selectedEmbeddingId?: string,
  selectedGroups?: string[], // 新規
  historyId?: string // 新規
): AsyncGenerator<{ type: 'content' | 'sources'; data: any }> {
  
  // historyId がない場合は、新しい対話履歴を作成
  if (!historyId) {
    historyId = await this.createSearchHistory(userId, message, selectedGroups);
  }

  // ユーザーメッセージを保存
  await this.saveChatMessage(historyId, 'user', message);

  // ... 既存のロジック ...

  // AI の回答を保存
  await this.saveChatMessage(historyId, 'assistant', fullResponse, sources);
}
```

## 📱 UI/UX 設計のポイント

### 1. グループ管理インターフェース

- サイドバーにグループリストを表示
- グループへのファイルのドラッグ＆ドロップに対応
- グループの色分け表示
- グループ内のファイル数を表示

### 2. 検索インターフェースの強化

- チャット入力欄の上にグループセレクターを追加
- 複数グループの選択と状態表示に対応
- 「全グループ」オプション

### 3. 履歴管理インターフェース

- 左側に履歴リスト、右側に対話内容を表示
- 履歴にはタイトル、時間、メッセージ数を表示
- 履歴の削除と対話の再開をサポート

### 4. PDF プレビュー

- モーダル形式で PDF を表示
- フルスクリーン表示をサポート
- 読み込み状態の表示とエラー処理

## 🚀 開発計画

### ✅ フェーズ1: データベースとバックエンド API (完了)

1. ✅ データベースのマイグレーションスクリプト
2. ✅ グループ管理 API
3. ✅ 履歴管理 API
4. ✅ PDF プレビュー API
5. ✅ チャットサービスの強化 (グループフィルタリングと履歴保存)
6. ✅ Elasticsearch のグループフィルタリング機能

### 🔄 フェーズ2: フロントエンドコンポーネント開発 (進行中)

1. ⏳ グループ管理コンポーネント (基本機能は実装済み。アクセス方法を最適化予定)
2. ⏳ 履歴管理コンポーネント (基本機能は実装済み)
3. ⏳ PDF プレビューコンポーネント (基本機能は実装済み)
4. ✅ **UI の刷新と設定の統合**: ヘッダーとサイドバーを整理し、設定の入り口を統一。新機能のためのスペースを確保。

### ⏳ フェーズ3: 統合とテスト (待機中)

1. ⏳ 機能の統合
2. ⏳ エンドツーエンド (E2E) テスト
3. ⏳ パフォーマンスの最適化

---

## ✅ 完了済みのバックエンド開発

### データベース設計

- ✅ 4つの新しいテーブルを作成：`knowledge_groups`、`knowledge_base_groups`、`search_history`、`chat_messages`
- ✅ `knowledge_base` テーブルに `pdf_path` フィールドを追加
- ✅ 完全なデータベースマイグレーションスクリプトを作成

### エンティティとサービス

- ✅ `KnowledgeGroup` エンティティとサービス (多対多関係をサポート)
- ✅ `SearchHistory` および `ChatMessage` エンティティとサービス
- ✅ `KnowledgeBase` エンティティを更新し、グループ関係と PDF パスを追加

### API エンドポイント

- ✅ ナレッジベースグループ管理 : `GET/POST/PUT/DELETE /api/knowledge-groups`
- ✅ ファイル・グループ関連付け : `POST/DELETE /api/knowledge-bases/:id/groups`
- ✅ 検索履歴管理 : `GET/POST/DELETE /api/search-history`
- ✅ PDF プレビュー : `GET /api/knowledge-bases/:id/pdf` および `GET /api/knowledge-bases/:id/pdf-status`

### チャット機能の強化

- ✅ グループフィルタリング検索をサポート (`selectedGroups` パラメータ)
- ✅ 対話履歴の自動生成と保存
- ✅ 対話の再開をサポート (`historyId` パラメータ)
- ✅ Elasticsearch によるグループフィルタリングクエリ

### テストと検証

- ✅ 自動テストスクリプト `test-enhancements.sh` を作成
- ✅ すべての API エンドポイントが実装され、テスト可能

**バックエンド開発ステータス**: ✅ **完了** (約 95%)

**次のステップ**: フロントエンドコンポーネントの開発を開始

---

**予想開発期間**: 5〜8日  
**優先度**: グループ化機能 > PDF プレビュー > 履歴管理