# 開発ガイド (Development Guide)

## 1. ディレクトリ構成

| パス | 内容 |
|------|------|
| `src/frontend/` | UI（Vanilla JS / CSS）。React/Vite は未使用。 |
| `src/backend/` | Rust / Tauri / Axum。MCP サーバー・LSA・埋め込みエンジン。 |
| `tests/` | テスト一式（原則ルート直下に集約）。API/MCP は `test_mcp_client.mjs`、E2E は `tests/e2e/`。Rust の結合テスト**ファイル**だけは Cargo の都合で `src/backend/tests/` に配置。詳細は `tests/README.md`。 |
| `docs/specification/` | 本仕様書群。 |
| `.agent/rules/` | AI エージェント用プロジェクト運用ルール。 |
| `tools/` | 開発用スクリプト。計測（count_loc, nesting_depth）、Mermaid 構文チェック（check-mermaid）、起動・テスト用など。 |

- **Mermaid 構文チェック**: Markdown 内の mermaid コードブロックを検証するには `npm run check-mermaid` を実行する。対象は `docs/` と `journals/`（引数でファイル指定も可）。要 `@mermaid-js/mermaid-cli`（mmdc）。

## 2. ビルド・起動

### 開発時

- **Community**: `npm run dev`（F5 などでそのまま起動できる）。起動時に LSA/HNSW 学習あり。
- **Community（速い起動）**: `npm run dev:fast`。`TELOS_SKIP_BOOT_TRAIN=1` で起動時学習をスキップ。検索が必要なら UI の「RE-INDEX」を実行。
- **Pro**: `npm run dev:pro` または `npm run dev:fast:pro`。`embedding_model/` に ONNX モデルと vocab を配置すること。

### 本番ビルド（2 エディション）

**ルール: 配布ビルド（`build:community` / `build:pro`）の前に、Community 版・Pro 版の全テストを実行し、すべて成功していること。**

- **必須テスト**（順に実行し、いずれも exit 0 であること）:
  1. `npm run test:rust`（Community 単体）
  2. `npm run test:rust:pro`（Pro 単体）
  3. `npm run test:e2e`（Community E2E）
  4. `npm run test:e2e:pro`（Pro E2E。embedding モデル要）
- **一括実行**: `npm run test:all` で上記 1〜4 を順に実行する。失敗したら配布ビルドを行わない。

- **Community**: `npm run build:community`  
  - 設定: `src/backend/tauri.community.conf.json`（productName: TelosDB-Community、vec0.dll のみ同梱）
- **Pro**: `npm run build:pro`  
  - 設定: `src/backend/tauri.pro.conf.json`（productName: TelosDB-Pro、埋め込みモデル等を含む）

それぞれ別名のインストーラ（例: `TelosDB-Community_*.exe`, `TelosDB-Pro_*.exe`）が生成されます。

### Cargo feature

- デフォルト: Community（LSA）。`cargo build` で LSA のみ。
- Pro: `cargo build --no-default-features --features pro`。埋め込み・HNSW 等の Pro 用コードが含まれる。

## 3. バックエンド開発

- **DB**（`src/backend/src/db/`）: sqlite-vec（vec0）でベクトル、FTS5 で全文検索。次元は Community 50 / Pro 768。  
  - 件数・アイテム取得は `get_document_count`・`get_item_content_with_doc`・`get_document_id_by_path` 等のラップ関数を利用。FTS 同期は `heal_items_fts`。
- **MCP**（`src/backend/src/mcp/`）:  
  - ルーティングは `mod.rs` の `create_mcp_app(state)`。起動は `build_app_state` で状態を組み立てたあと `run_server` で LSA/HNSW 同期 → listen。  
  - ツール定義は `tools/registry.rs` の `tool_list()`。新規ツール追加時は registry と `tools::dispatch_tool` の match の両方に追加する。  
  - 検索時のクエリベクトルは `tools/search.rs` の `get_query_vector(state, text)` で取得（LSA/埋め込みの切り替えはここで完結）。
- **LSA**: `utils/lsa.rs` で SVD による 50 次元ベクトル化（Community）。
- **埋め込み**: Pro は `utils/embedding_pro.rs`。ONNX（tract または ort）で 768 次元。詳細は **07_embedding_tract.md**。

## 4. フロントエンド開発

- **通信**: Tauri の `invoke` / `listen` でバックエンドと非同期通信。MCP は 3001 で別接続。
- **UI**: Vanilla CSS。デザイン方針は **06_ui_design_spec.md**。

## 5. テスト・検証

- ゴール・KPI: **08_embedding_tract_goals_and_kpi.md**
- 検証手順: **09_embedding_tract_implementation_and_tests.md**
- UI テスト方針: **12_ui_testing_options.md**
- **E2E**: `npm run test:e2e` はバイナリが既にあればビルドをスキップする。永遠に待たないようにするには `npm run test:e2e:timed`（既定 8 分で打ち切り）を使う。打ち切り時はコンソール出力をログとして確認する。
- **失敗しているスペックだけ回す**: 全件 E2E で失敗したスペックが分かったら、そのファイルだけを繰り返し実行してパッチ当てする。例: `npm run test:e2e:spec -- --spec tests/e2e/specs/screenshot-docs-modal.spec.js`。複数指定する場合は `--spec` を複数並べるか、`--spec "tests/e2e/specs/foo.spec.js" "tests/e2e/specs/bar.spec.js"` のようにする。
- **E2E（1 回・打ち切り付き）**: `npm run test:e2e:timed` で 1 回だけ実行（既定 8 分で打ち切り）。リトライはしない。失敗したら原因を直してから再実行する。

## 6. デバッグ

- **不具合時は質問より先にログを確認する**。アプリ起動失敗・MCP が応答しない・E2E タイムアウト・indexing が終わらない等は、ターミナル・tauri-driver・バックエンドの標準出力・標準エラーおよび `log::info!` 等を読んでから原因を判断する。
- **ログをファイルに残す**: `npm run dev:log` で起動すると標準出力・標準エラーが `tmp/dev.log` に追記される。不具合再現後に `tmp/dev.log` を開いて確認する。
