# 埋め込み改修：ゴールとテスト KPI

製品概要・アーキテクチャは **01_system_overview.md**・**02_architecture_design.md** を参照。本文書は改修ゴールとテスト KPI の定義のみ。

## 1. 改修のゴール（Goals）

### 1.1 主ゴール

| # | ゴール | 達成条件 |
|---|--------|----------|
| G1 | **エディション分離の成立** | Community 版と Pro 版が同一リポジトリから、ビルドフラグのみで別バイナリとしてビルド・配布できる。一方の実装が他方のバイナリに含まれない。 |
| G2 | **Pro 版の起動・検索の成立** | Pro 版が起動し、検索 API（FTS ＋ 埋め込み可能時はベクトル）が動作する。埋め込みモデル未ロード時も FTS のみで検索可能である。 |
| G3 | **モデルのプロジェクト内組み込み** | 埋め込みモデル（ONNX ＋ vocab）をプロジェクト内 `embedding_model/` に置き、開発・配布ビルドの両方で同じパス解決で参照できる。 |
| G4 | **GUI のエディション対応** | 起動中のエディションに応じて、ヘッダー表示・RE-INDEX 文言・ステータスが切り替わる。 |
| G5 | **検索の健全性** | 既存 DB や 1 文字クエリでも、FTS または LIKE フォールバックで検索結果が返る。items_fts と items の不整合は起動時・手動 heal で解消できる。 |
| G6 | **テスト・運用の自動化** | ヘッドレス起動と test-and-heal（heal → MCP テスト）が Pro/Community で実行可能。継続実行オプションで回し続けられる。 |
| G7 | **埋め込みモデルの確実なロード（テスト利用可能）** | Pro 起動時に埋め込みモデルがロード成功し、ベクトル化・近似近傍検索の動作確認とテストが行える状態にする。tract の最適化スキップや代替 ONNX などで Cast ノード問題を回避する。 |

### 1.2 副次ゴール（既知の制約内）

| # | ゴール | 備考 |
|---|--------|------|
| G8 | **既存機能の非劣化** | Community 版の LSA 学習・HNSW・検索・追加・更新は従来どおり動作する。 |

---

## 2. テストにおける KPI（Key Performance Indicators）

### 2.1 ビルド・起動

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K1 | Community ビルド成功 | `cargo build`（または `tauri build`）が警告のみで完了する | `cargo build --manifest-path src/backend/Cargo.toml` |
| K2 | Pro ビルド成功 | `cargo build --no-default-features --features pro` が警告のみで完了する | 上記 + feature pro |
| K3 | Community 起動 | ウィンドウが開き、ログに `[BOOT] Edition: community` が出る | 手動 or launch「Community で起動」 |
| K4 | Pro 起動 | ウィンドウが開き、ログに `[BOOT] Edition: pro` が出る | 手動 or launch「Pro で起動」 |
| K5 | ヘッドレス起動 | `TELOS_HEADLESS=1` でウィンドウ非表示のまま MCP が 3001 で待ち受ける | `npm run test:headless` が MCP 待機まで完了 |

### 2.2 API・検索

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K6 | MCP ツール一覧 | `POST /messages` で `tools/list` が 10 件前後のツールを返す | `tests/test_mcp_client.mjs` の tools/list 成功 |
| K7 | 検索が 200 を返す | `search_text` が JSON-RPC として成功し、`content` 配列が返る（0 件でも可） | test_mcp_client の search_text が例外にならない |
| K8 | Heal API | `GET /heal` が 200 で `{ "synced": n }` を返す | test-and-heal 内の heal 呼び出し成功 |
| K9 | エディション API | `GET /edition` が `community` または `pro` を返す | 起動したバイナリの feature と一致 |

### 2.3 データ整合・ヒール

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K10 | 起動時 FTS 同期 | items に存在し items_fts に無い行が起動時に挿入される | 既存 DB で検索が 0 件だったケースが heal 後または再起動で解消 |
| K11 | 手動 Heal 効果 | `GET /heal` 実行後、不足していた FTS 行が検索に反映される | heal 前後で同一クエリのヒット件数が増える（不足があった場合） |

### 2.4 回帰・非劣化

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K12 | Community 検索 | LSA 学習完了後、検索がベクトル＋FTS で結果を返す | Community 起動 → 文書追加 → 検索でヒット |
| K13 | Rust 単体テスト | 既存の `cargo test` が通る | `npm run test:rust`（db, lsa, mcp の tests） |

### 2.5 運用・CI 寄り

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K14 | test-and-heal 1 回成功 | `npm run test-and-heal:pro` が exit 0 で終わる | スクリプト実行。MCP 未起動時はヘッドレスで Pro 起動 → heal → test |
| K15 | 継続実行の安定性 | `test-and-heal:pro:continuous` が複数サイクル（例: 2 回）heal → test を繰り返す | 手動で 2 サイクル以上実行し、いずれも test が完了する |

### 2.6 Pro 埋め込み・ベクトル化・ANN（G7 達成のための KPI）

| KPI | 指標 | 合格基準 | 測定方法 |
|-----|------|----------|----------|
| K16 | 埋め込みモデルロード成功 | Pro 起動時に `embedding_model` が Some となり、ログにモデル読み込み成功が出る（またはエラーが出ない） | Pro 起動 → ログ確認。または GET /model_name で pro/sonoisa 系の名前が返る |
| K17 | ベクトル化: vec_items 投入 | add_item_text で 1 件追加後、vec_items に 1 行・768 次元が入る | DB: `SELECT COUNT(*), vec_to_json(embedding) FROM vec_items` で確認 |
| K18 | 起動時 HNSW 構築（Pro） | vec_items にデータがある状態で Pro 再起動後、HNSW が構築される | ログに `[BOOT] Pro HNSW: inserting N items (768d)...` および `index built.` |
| K19 | ANN 検索でベクトルヒット | 追加した文書に意味的に近いクエリで search_text を実行し、その文書が結果に含まれ類似度が付与される | MCP search_text で content 配列に該当文書が含まれる。optional: 複数文書で類似度順が妥当 |

---

## 3. まとめ

- **ゴール**: エディション分離・Pro 起動・モデル組み込み・GUI 対応・検索健全性・テスト自動化・**埋め込み確実ロード（G7）** を主目標とし、既存機能の非劣化（G8）を副次目標とする。
- **KPI**: ビルド/起動（K1–K5）、API/検索（K6–K9）、データ整合/ヒール（K10–K11）、回帰（K12–K13）、運用（K14–K15）、**Pro 埋め込み・ベクトル化・ANN（K16–K19）** の 19 項目を合格基準とし、CI または手順に沿ったテストで測定する。
