Journal: 20260223-0013-テーブル構造の正規化とドキュメント・チャンクの分離 (Table Structure Normalization and Document-Chunk Separation)

日本語 (Japanese)

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ツールロジックの境界をより正確に把握し、堅牢なエラーレスポンスの実装が行えた。

English

1. Reason for Work

To perform database normalization based on Issue-2. In the previous design, when a single document was split into multiple chunks, the same path information was held for each chunk in the items table, resulting in data redundancy and management inconveniences.

2. Instructions (Background, Perspective, Intent)

• Background: Chunking was introduced to improve the accuracy of semantic search, but metadata and data were mixed.
• Perspective: Explicitly manage the 1-document-to-N-chunks relationship in the database.
• Intent: Enable batch operations on a per-document basis during deletion and ensure that the correct source is displayed in search results.

3. Points and Responses

• Document Table Creation: Created a new documents table to manage path uniquely.
• Item Table Modification: Added document_id and chunk_index, and removed the redundant path.
• MCP Tool Refactoring: Refactored add_item_text and search_text to fit the new schema.
• Type Mismatch Fix (AI Autonomous Fix): Resolved the mismatch between axum::response::Response and Option<Value> by utilizing JsonRpcResponse.

4. Work Details

The AI agent carried out the work in the following steps:

1. Updated the schema definition in src/backend/src/db.rs, adding the documents table and normalizing the items table.
2. Refactored the tool logic in src/backend/src/mcp.rs. Specifically, add_item_text was re-implemented to include document existence checks and cleanup of existing chunks.
3. Detected type mismatch errors (discrepancy between Axum return types and MCP internal logic) encountered during development and resolved them autonomously by incorporating appropriate response conversion logic.
4. Updated the ER diagram and explanations in the specification document (03_database_specification.md).

5. Results from AI Perspective

The refactoring cleaned up the database structure and simplified future document management (such as bulk deletion or display in a management screen). Additionally, during the process of fixing compilation errors, the boundaries between Axum handlers and MCP tool logic were grasped more accurately, enabling the implementation of robust error responses.

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]