Journal: 20260223-0013-テーブル構造の正規化とドキュメント・チャンクの分離

1. 作業実施の理由

Issue-2に基づき、データベースの正規化を行うため。従来の設計では、1つのドキュメントを複数チャンクに分割した際、itemsテーブルにチャンクごとに同じpath情報が保持され、データの冗長性と管理上の不都合が生じていた。

2. 指示（背景、観点、意図を含む）

• 背景: 意味検索の精度向上のためチャンク分割を導入したが、メタデータとデータが混在していた。
• 観点: 1ドキュメント対Nチャンクの関係をデータベース上で明示的に管理する。
• 意図: 削除時にドキュメント単位で一括操作を可能にし、かつ検索結果で正しいソースを表示できるようにする。

3. 指示事項とその対応

• ドキュメントテーブルの作成: documentsテーブルを新設し、pathを一意に管理。
• アイテムテーブルの変更: document_idとchunk_indexを追加し、冗長なpathを削除。
• MCPツールの修正: add_item_textやsearch_textを新スキーマに合わせてリファクタリング。
• 型不整合の修正 (AI自律修正): axum::response::ResponseとOption<Value>の不整合を、JsonRpcResponseの活用により解決。

4. 作業詳細

AIエージェントは以下の手順で作業を実施した。

1. src/backend/src/db.rs のスキーマ定義を更新し、documentsテーブルの追加とitemsテーブルの正規化を行った。
2. src/backend/src/mcp.rs の各ツールロジックをリファクタリングした。特に add_item_text では、ドキュメントの存在確認と既存チャンクのクリーンアップを含めて再実装した。
3. 開発中に遭遇した型不整合エラー（Axumの戻り型とMCP内部ロジックの不一致）を検知し、適切なレスポンス変換ロジックを組み込むことで自律的に解決した。
4. 仕様書（03_database_specification.md）のER図と解説を更新した。

5. AI視点での結果

リファクタリングにより、データベース構造がクリーンになり、将来的なドキュメント管理（一括削除や管理画面での表示など）が容易になった。また、コンパイルエラーの修正過程で、AxumハンドラとMCPツールロジックの境界をより正確に把握し、堅牢なエラーレスポンスの実装が行えた。

graph TD
    A[Add Item Request] --> B{Find Document?}
    B -- No --> C[Create Document Record]
    B -- Yes --> D[Wipe Old Chunks]
    C --> E[Loop: Split Content]
    D --> E
    E --> F[Generate LSA Vector]
    F --> G[Save Chunk to items]
    G --> H[Update HNSW Index]