Spaces:

chibafes-dev
/

circle-search-26-api

Sleeping

ktsn-ud commited on Dec 11, 2025

Commit

e6ef038

1 Parent(s): 8eb78dc

Add detailed documentation on search algorithms and their mathematical foundations in Japanese

- Introduced a new document explaining the mathematical background of search algorithms used in the project.
- Covered key topics including BM25F, TF-IDF, word vectors, cosine similarity, and score integration methods.
- Provided examples and explanations tailored for students interested in the mathematical aspects of algorithms.

Files changed (8) hide show

docs/api_spec.md +0 -299
docs/db_connection.md +0 -23
docs/project_overview.md +0 -224
docs/project_schema_change_points.md +0 -40
docs/システムガイド.md +961 -0
docs/基礎知識.md +547 -0
docs/改善提案.md +825 -0
docs/検索アルゴリズム詳説.md +520 -0

docs/api_spec.md DELETED Viewed

@@ -1,299 +0,0 @@
-# フロントエンド向け API 仕様書
-本ドキュメントはフロントエンドから本APIを利用するための仕様書です。認証ヘッダ、各エンドポイントの入出力、エラー応答、注意点をまとめています。
-ベースURLはデプロイ環境に依存します（例: 同一オリジンの `/api/...` または環境変数 `FASTAPI_URL` で指定）。バージョン付けは現状ありません。
----
-## 目次
-- [認証](#認証)
-- [エンドポイント一覧](#エンドポイント一覧)
-- [スキーマ定義](#スキーマ定義)
-- [リクエスト/レスポンス例](#リクエストレスポンス例)
-- [エラーとステータスコード](#エラーとステータスコード)
-- [実装メモ（フロントエンド）](#実装メモフロントエンド)
-- [クライアント例](#クライアント例)
-- [環境変数の例（フロントエンド側）](#環境変数の例フロントエンド側)
----
-## 認証
-本番（HF Spaces・プライベート）では二段階の認証が必要です。
-- レイヤ1: HF Spaces へのアクセス（プライベート用）
-  - ヘッダ: `Authorization: Bearer <API_ACCESS_KEY>`
-  - 値の例: 環境変数 `API_ACCESS_KEY`（フロントのサーバーサイドに設定）
-  - 失敗時: `401 Unauthorized`（またはプラットフォーム側のエラー）
-- レイヤ2: アプリ内APIキー
-  - ヘッダ: `X-API-KEY: <API_SECRET_KEY>`（ヘッダ名は大小無視: `X-API-Key` でも可）
-  - 値の例: 環境変数 `API_SECRET_KEY`（README 参照）
-  - 対象: `/api/projects`, `/api/details`, `/api/search`
-  - 失敗時: `403 Forbidden`（キー不正または未設定）
-推奨: ブラウザから直接APIを呼ばず、Next.js等のサーバーサイド（API Routes や server actions）から呼び出してください。クライアントに秘密鍵を露出しないためです。
----
-## エンドポイント一覧
-1) ヘルスチェック（認証不要）
-- メソッド/URL: `GET /api/health`
-- リクエスト: なし
-- レスポンス: `200 OK`
-  - 本文: `{ "status": "ok" }`
-2) 企画一覧（圧縮レスポンス）
-- メソッド/URL: `GET /api/projects`
-- ヘッダ:
-  - `Authorization: Bearer <API_ACCESS_KEY>`
-  - `X-API-KEY: <API_SECRET_KEY>`
-- レスポンス: `200 OK`
-  - ヘッダ: `Content-Encoding: gzip`, `Content-Type: application/json`
-  - 本文: `ProjectSummary[]`（ブラウザは自動で解凍します）
-3) 企画詳細
-- メソッド/URL: `GET /api/details?projectId=<ID>`
-- ヘッダ:
-  - `Authorization: Bearer <API_ACCESS_KEY>`
-  - `X-API-KEY: <API_SECRET_KEY>`
-- クエリ: `projectId`（必須）
-- レスポンス:
-  - 成功: `200 OK` 本文: `ProjectDetail`
-  - 失敗: `404 Not Found`（存在しないID）
-4) 検索
-- メソッド/URL: `POST /api/search`
-- ヘッダ:
-  - `Authorization: Bearer <API_ACCESS_KEY>`
-  - `X-API-KEY: <API_SECRET_KEY>`
-- ボディ(JSON): `{ "query": string, "debug": boolean (省略可, 既定:false) }`
-- レスポンス:
-  - 成功: `200 OK`
-    - `debug=false` のとき: `ProjectIds`
-    - `debug=true` のとき: `SearchDebugResponse`
-  - 失敗: `400 Bad Request`（`query` が空）
----
-## スキーマ定義
-型はすべて JSON オブジェクト（配列含む）です。文字列は UTF-8。日付型はありません。
-共通: `category` の値は次のいずれかです。
-`"パフォーマンス" | "飲食" | "物販" | "展示" | "参加型" | "音楽" | "その他"`
-1) ProjectSummary（企画一覧用）
-- `projectId`: string（例: "62000A"）
-- `circleName`: string（団体名）
-- `name`: string（企画名）
-- `category`: string（上記のいずれか）
-- `day1`: boolean
-- `day2`: boolean
-- `day3`: boolean
-- `location`: string
-- `description`: string
-- `prComment`: string
-- `note`: string | null
-- `imageName`: string
-2) ProjectDetail（企画詳細用）
-- `projectId`, `circleName`, `name`, `category`, `day1`, `day2`, `day3`, `location`, `description`, `prComment`, `note`, `imageName`: ProjectSummary と同じ
-- 追加フィールド:
-  - `prCommentLong`: string | null
-  - `optionalImageName1`〜`optionalImageName5`: string | null
-  - `urlX`, `urlInstagram`, `urlOfficialWebsite`, `urlYoutube`, `urlOther`: string | null
-3) ProjectIds（検索の通常応答）
-- `projectIds`: string[]（スコアの高い順）
-4) SearchDebugResponse（`debug=true` のとき）
-- `projectIds`: string[]（最終並べ替え順）
-- `scores`: { `projectId`: string, `score`: number }[]（最終スコア）
-- `details`: { 下記 }[]（内部スコアの内訳）
-  - `projectId`: string
-  - `bm25`: number（単語一致の強さ）
-  - `ws_filter_topk`: number（意味類似: ふるい落とし段階）
-  - `ws_rerank_pairavg`: number | null（意味類似: 最終並べ替えに使用）
-  - `org_boost`: number（団体名/読みの一致による加点）
-  - `fused_filter`: number（フィルタ段階���合成スコア）
-  - `fused_final`: number（最終合成スコア = 並べ替え基準）
----
-## リクエスト/レスポンス例
-1) 企画一覧
-```
-GET /api/projects
-Authorization: Bearer <API_ACCESS_KEY>
-X-API-KEY: <API_SECRET_KEY>
-200 OK
-Content-Encoding: gzip
-Content-Type: application/json
-[
-  {
-    "projectId": "62000A",
-    "circleName": "〇〇サークル",
-    "name": "△△展示",
-    "category": "展示",
-    "day1": true,
-    "day2": false,
-    "day3": true,
-    "location": "1号館",
-    "description": "…",
-    "prComment": "…",
-    "note": null,
-    "imageName": "image.jpg"
-  }
-]
-```
-2) 企画詳細
-```
-GET /api/details?projectId=62000A
-Authorization: Bearer <API_ACCESS_KEY>
-X-API-KEY: <API_SECRET_KEY>
-200 OK
-{
-  "projectId": "62000A",
-  "circleName": "〇〇サークル",
-  "name": "△△展示",
-  "category": "展示",
-  "day1": true,
-  "day2": false,
-  "day3": true,
-  "location": "1号館",
-  "description": "…",
-  "prComment": "…",
-  "prCommentLong": null,
-  "note": null,
-  "imageName": "image.jpg",
-  "optionalImageName1": null,
-  "optionalImageName2": null,
-  "optionalImageName3": null,
-  "optionalImageName4": null,
-  "optionalImageName5": null,
-  "urlX": null,
-  "urlInstagram": null,
-  "urlOfficialWebsite": null,
-  "urlYoutube": null,
-  "urlOther": null
-}
-```
-3) 検索（通常）
-```
-POST /api/search
-Authorization: Bearer <API_ACCESS_KEY>
-X-API-KEY: <API_SECRET_KEY>
-Content-Type: application/json
-{
-  "query": "焼きそば",
-  "debug": false
-}
-200 OK
-{
-  "projectIds": ["62000A", "62000B", "62000C"]
-}
-```
-4) 検索（デバッグ付き）
-```
-POST /api/search
-Authorization: Bearer <API_ACCESS_KEY>
-X-API-KEY: <API_SECRET_KEY>
-Content-Type: application/json
-{
-  "query": "吹奏楽",
-  "debug": true
-}
-200 OK
-{
-  "projectIds": ["62010A", "62003C"],
-  "scores": [
-    {"projectId": "62010A", "score": 0.83},
-    {"projectId": "62003C", "score": 0.78}
-  ],
-  "details": [
-    {
-      "projectId": "62010A",
-      "bm25": 0.62,
-      "ws_filter_topk": 0.55,
-      "ws_rerank_pairavg": 0.57,
-      "org_boost": 0.70,
-      "fused_filter": 0.59,
-      "fused_final": 1.32
-    }
-  ]
-}
-```
----
-## エラーとステータスコード
-- `400 Bad Request`: `query` が空（検索）
-- `401 Unauthorized`: HF Spaces のプライベートアクセス認証に失敗
-- `403 Forbidden`: アプリ内APIキー認証に失敗（`X-API-KEY`）
-- `404 Not Found`: 企画が見つからない（詳細）
-- `422 Unprocessable Entity`: リクエスト形式が不正（必須フィールド欠落など、FastAPI標準）
----
-## 実装メモ（フロントエンド）
-- 圧縮レスポンス: `/api/projects` は `Content-Encoding: gzip`。ブラウザの `fetch` は自動解凍します。低レベルHTTPクライアントを使う場合は自動解凍設定を確認してください。
-- 認証ヘッダ: すべての保護エンドポイントに `X-API-KEY` を付けてください。
-- デバッグ検索: チューニング時のみ利用を推奨。ユーザー向けUIでは通常 `debug=false`。
-- 並び順: 検索結果はスコアの高い順です。`projectIds` の順序をそのまま利用してください。
----
-## クライアント例
-1) fetch（ブラウザ）
-```js
-// 検索
-const res = await fetch(`${process.env.FASTAPI_URL}/api/search`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    // レイヤ1: HF Spaces（プライベート）
-    'Authorization': `Bearer ${process.env.API_ACCESS_KEY}`,
-    // レイヤ2: アプリ内APIキー
-    'X-API-Key': process.env.API_SECRET_KEY,
-  },
-  body: JSON.stringify({ query: '唐揚げ', debug: false }),
-});
-const data = await res.json();
-console.log(data.projectIds);
-```
-2) curl
-```bash
-curl -X POST \
-  -H "Authorization: Bearer $API_ACCESS_KEY" \
-  -H "X-API-KEY: $API_SECRET_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"query":"焼きそば"}' \
-  "$FASTAPI_URL/api/search"
-```
----
-## 環境変数の例（フロントエンド側）
-- `FASTAPI_URL`: バックエンドのベースURL（例: `https://<space-name>.<org>.hf.space`）
-- `API_SECRET_KEY`: アプリ内APIキー（バックエンド側 `.env` の `API_SECRET_KEY` と一致させる）
-- `API_ACCESS_KEY`: HF Spaces のプライベートアクセス用トークン（Bearer で送る）

docs/db_connection.md DELETED Viewed

@@ -1,23 +0,0 @@
-# MySQL 接続ガイド
-## 環境変数
-- `DATABASE_URL`: MySQL の DSN。例: `mysql://user:password@db.example.com:3306/chibafes?charset=utf8mb4`
-- `SSL_ROOT_CERT`: 公式 CA 証明書のパス。サーバ証明書の検証を行う場合に指定します。
-- `DB_POOL_MIN_SIZE` / `DB_POOL_MAX_SIZE`: コネクションプールの初期 / 最大コネクション数。既定値は `1 / 5`。
-- `DB_CONNECT_TIMEOUT`: 接続タイムアウト秒数。未設定時は PyMySQL の既定値を利用します。
-- `DB_CHARSET`: DSN に指定が無い場合の既定文字コード。標準は `utf8mb4`。
-> パスワードに特殊文字が含まれる場合は、`urllib.parse.quote_plus` で URL エンコードした値を使用してください。
-## 接続オプション
-- DSN のクエリ文字列で `charset`, `autocommit`, `connect_timeout` など PyMySQL の接続パラメータを上書きできます。
-- `SSL_ROOT_CERT` を指定すると `ssl={"ca": ...}` が PyMySQL に渡されます。証明書ファイルは Secrets Manager や環境変数経由で提供し、リポジトリに含めないでください。
-## PyMySQL の利用
-- `app/db/session.py` では PyMySQL を利用したシンプルなコネクションプールを実装しています。読み取り用途のため、コネクションはオートコミットで取得します。
-- 追加で書き込み処理を実装する場合は、必要に応じてトランザクション管理やリトライ戦略を検討してください。
-## 動作確認
-1. `export DATABASE_URL="..."` と必要な環境変数をセット。
-2. `python -c "from app.db.session import get_connection;\nwith get_connection() as conn: print(conn.host)"`
-3. エラーなくホスト名が表示されれば接続成功です。

docs/project_overview.md DELETED Viewed

@@ -1,224 +0,0 @@
-# プロジェクトの全体像と調整ガイド
-このドキュメントは、千葉大祭の「企画情報の提供＆検索システム」の中身を、初学者向けにやさしく説明したものです。環境構築の手順は README.md にあるので、ここでは仕組みと調整のポイントに絞ります。
----
-## 目次
-- [1. 全体像（何をしているか）](#1-全体像何をしているか)
-- [2. ディレクトリと主な役割](#2-ディレクトリと主な役割)
-- [3. 検索システムの仕組み（やさしく解説）](#3-検索システムの仕組みやさしく解説)
-- [4. パラメータ解説（どこをどう調整する？）](#4-パラメータ解説どこをどう調整する)
-  - [4.1 search_model.json（主なもの）](#41-search_modeljson主なもの)
-  - [4.2 files.json（主なもの）](#42-filesjson主なもの)
-- [5. データ作成パイプライン（いつ何を再実行？）](#5-データ作成パイプラインいつ何を再実行)
-- [6. API の使い方（超概要）](#6-api-の使い方超概要)
-- [7. よくある調整手順の例](#7-よくある調整手順の例)
-- [8. ちょっとした注意点とチェックリスト](#8-ちょっとした注意点とチェックリスト)
-- [9. 用語ミニ辞典](#9-用語ミニ辞典)
----
-## 1. 全体像（何をしているか）
-- 企画情報（団体名・企画名・説明など）を CSV から取り込み、検索しやすい形に整えます。
-- Web API（FastAPI）を通じて、検索キーワードから「関係が強い企画」を並べて返します。
-- 検索は「単語の一致（BM25F）」と「意味の近さ（単語ベクトル）」を組み合わせ、必要なら同義語も広げます。
-主な流れは次の通りです。
-1) データ作成スクリプトで各種ファイルを生成（後述の scripts/ 参照）
-2) API 起動時に検索用のデータを読み込み（`api/main.py` → `api/search/engine.py`）
-3) リクエストで受け取ったキーワードを分かち書き（SudachiPy）→ 同義語で拡張 → スコアリング → 上位を返す
----
-## 2. ディレクトリと主な役割
-- `api/`
-  - `main.py`: FastAPI のエントリポイント。エンジン初期化、エンドポイント(`/api/search` など)定義。
-  - `search/engine.py`: 検索の本体。トークン化、同義語展開、BM25F、意味類似スコア、並び替え等。
-- `scripts/`（データ作成パイプライン）
-  - `build_all.py`: 0→6 の全ステップを順番に実行するランナー。
-  - `0_download_data.py`: 単語ベクトル（fastText）のダウンロード。
-  - `1_build_dict.py`: Sudachi のユーザー辞書をビルド（任意だが推奨）。
-  - `2_create_projects_data.py`: CSV から `projects.json` を生成。
-  - `3_build_synonyms_from_sudachi.py`: 同義語辞書（Sudachi公式＋カスタム）から、コーパスにある語だけを抜き出してキャッシュ化。
-  - `4_prepare_bm25f_meta.py`: BM25F の IDF や平均長を計算して `bm25_meta.json` に保存。
-  - `5_prepare_tf_token.py`: 各文書のフィールド別 TF/長さを `tf_token.json` に保存。
-  - `6_build_word_embeddings.py`: コーパス語彙に対応する fastText ベクトルを抽出して保存。
-- `config/`
-  - `search_model.json`: 検索のふるまい（同義語の有無、重み、しきい値など）の設定。
-  - `files.json`: 各種入力・出力ファイルのパス定義。
-- `schemas/`
-  - `projects.py`: API レスポンスのデータ形（一覧・詳細・検索結果の ID 群）。
-  - `tf_token.py`: 検索前処理で使う中間データの形（TF/長さなど）。
-- `utils/`
-  - `json.py`: 設定ファイルから値を取得、JSON の安全書き出しなど。
-  - `io.py`: 行ストリーム読み込みなどの小物。
-  - `text_process.py`: 見えない制御文字の除去など。
-- その他
-  - `resources/`: 入力素材（CSV、同義語辞書、ストップワード、ユーザー辞書、ベクトル等）。
-  - `Dockerfile`: コンテナ実行向けの定義（概要のみ把握でOK）。
-  - `.github/workflows/deploy_to_hf_space.yaml`: Hugging Face Spaces へのデプロイ用ワークフロー（概要のみ把握でOK）。
----
-## 3. 検索システムの仕組み（やさしく解説）
-検索は「単語での一致」と「意味の近さ」をミックスして、必要なら「団体名などの前方一致」も加点して並び順を決めます。
-1) トークン化（単語に分ける）
-   - SudachiPy を使い、名詞・動詞・形容詞などの重要品詞だけを対象にします。
-   - ストップワード（よく出るが意味が薄い語）や禁止語は除外します。
-2) 同義語の拡張（必要に応じて）
-   - 例：「大学祭」→「学園祭」も一緒に検索する、のようにキーワードを広げます。
-   - Sudachi の同義語辞書＋プロジェクト内語彙にあるものだけを採用。出しすぎないように上限を設けます。
-3) BM25F で「単語一致の強さ」を計算
-   - BM25 は「その単語がどれくらい珍しいか（IDF）」や「どれくらい繰り返し出るか（TF）」をもとにスコア化します。
-   - F は Field の F。タイトルは重要、長文は少し抑えめ…といった「フィールドごとの重み」を付けられます。
-4) 単語ベクトルで「意味の近さ」を計算
-   - fastText などの単語ベクトルを使い、「言い換え」でも近さを捉えます。
-   - 資料がない単語は、fastText の subword 機能で「なんとなくの方向」を推測して補います（OOV対応）。
-   - まずフィルタ用に top-k 集約でざっくり類似度を出し、最終並べ替え時に平均方式でもう一度なめらかに評価します。
-5) 団体名などへのブースト（加点）
-   - 入力文字列が「団体名」や「読み」に完全一致／前方一致／部分一致した場合、加点して上に来やすくします。
-6) 閾値と上限で絞る → 並べ替え
-   - 弱すぎる候補は捨て、最大件数までに絞って、合成スコアの高い順に返します。
----
-## 4. パラメータ解説（どこをどう調整する？）
-調整の中心は `config/search_model.json` と `config/files.json` です。まずは `search_model.json` から。
-### 4.1 search_model.json（主なもの）
-- 同義語関連（`synonyms`）
-  - `enable`: 同義語を使うか。誤ヒットが増えたら false も検討。
-  - `sources.sudachi`: Sudachi の同義語辞書を使うか。
-  - `sources.custom_json`: 追加入力のパス（`resources/synonyms_custom.json`）。独自の言い換えを足せます。
-  - `limits.max_expansions_per_term`: 1語あたり何個まで広げるか。多いほど網羅的、誤ヒットも増えやすい。
-  - `limits.max_query_variants`: 全体の拡張上限。過剰拡張を防ぐ安全弁。
-  - `limits.min_char_len`: これ未満の短い語は拡張しない。
-  - `banlist`: 拡張・検索対象から外す語（例: 「部」「会」など一般的すぎる語）。
-- BM25F（`bm25f`）
-  - `k1`/`b`: BM25 の基本パラメータ。通常は標準値（例: 1.2/0.75）から大きく動かさない。
-  - `field_weights`: フィールドごとの重要度。`name` を上げるとタイトル一致が強くなります。
-- 意味類似（`word_sim`）
-  - `enable`: 有効化するか。無関係の表現で拾いすぎるなら false を検討。
-  - `alpha`: BM25 と意味類似の混ぜ具合。1.0 に近いほど BM25 寄り、0.0 に近いほど意味寄り。
-  - `topk_k`: フィルタ段階で使う「上位 k 個」をどれだけ拾うか。小さいと厳しめ。
-  - `rerank`: 最終並べ替えに使う類似度の計算方式。`pair_avg` はなめらかで扱いやすい。
-- サブワード（`query_subword`）
-  - `enable`: fastText の subword で未知語を補うか。
-  - `oov_weight`: 未知語ベクトルの重み（小さいほど控えめに採用）。
-- 団体名ブースト（`circleName.boost`）
-  - `exact`/`prefix`/`substring`: それぞれ完全一致／前方一致／部分一致の加点量。
-  - `min_len`: 短すぎる入力で過剰加点しないための最小文字数。
-- フィルタ（`filter`）
-  - `min_results`/`max_results`: 返す件数の下限／上限。
-  - `bm25_min`/`word_sim_min`/`fused_min`: それぞれ BM25・意味類似・合成スコアでの最低ライン。
-  - `fused_rel_top_ratio`: 「トップのスコアに対する割合」で足切りする係数。0.5 ならトップの半分未満を落とすイメージ。
-調整のコツ（例）
-- 「タイトル一致をもっと強く」→ `bm25f.field_weights.name` を上げる。
-- 「言い換えも拾いたいが誤ヒットが増える」→ `word_sim.alpha` を少し上げる（BM25寄りに）。
-- 「似ている語で広がりすぎる」→ `synonyms.enable=false` か `limits` を厳しめに。
-- 「団体名の指名検索を最優先に」→ `circleName.boost.exact` を上げる。
-- 「全体的に弱い」→ `filter.fused_min` を下げるか、`fused_rel_top_ratio` を下げて緩める。
-### 4.2 files.json（主なもの）
-- `sudachi.*`: Sudachi の設定（設定 JSON、ユーザー辞書、同義語、ストップワード、同義語キャッシュの保存先）。
-- `projects.*`: 入力 CSV と、出力される `projects.json` の場所。
-- `bm25.*`: BM25 のメタ情報（IDF/平均長）と `tf_token.json` の場所。
-- `embeddings.*`: fastText の `.vec` / `.bin` と、抽出した語彙・ベクトルの保存先。
-パスを変えると生成物の出力先も変わるので、変更後は該当ステップを作り直してください。
----
-## 5. データ作成パイプライン（いつ何を再実行？）
-全自動は `python scripts/build_all.py` ですが、調整時は必要な所だけを再実行すると速いです。
-- CSV を更新したら → `2`、`3`、`4`、`5`（+ `6` も必要なら）
-- `synonyms_custom.json` を更新したら → `3`
-- `search_model.json` の品詞や `target_fields` を変えたら → `3`、`4`、`5`（+ `6`）
-- `field_weights` やフィルタ閾値だけ変えた → 再ビルド不要（API 再起動のみ）
-- fastText を入れ替えた → `6`
-各ステップの要約
-- 0: fastText のダウンロード（大容量。最初だけ）
-- 1: ユーザー辞書ビルド（任意。固有名詞を強くしたいときに）
-- 2: CSV → `projects.json`
-- 3: 同義語キャッシュ生成
-- 4: BM25F メタ情報（IDF/平均長）
-- 5: フィールド別 TF/長さ
-- 6: 語彙ベクトル抽出（`.vec` がある場合）
----
-## 6. API の使い方（超概要）
-- `GET /api/health`: ヘルスチェック。
-- `GET /api/projects`: 企画一覧（圧縮返却）。
-- `GET /api/details?projectId=...`: 個別企画の詳細。
-- `POST /api/search`（本文: `{ "query": "...", "debug": false }`）: 関連が高い順の `projectIds` を返す。`debug=true` で内部スコアの簡易情報も返却。
-- ヘッダ `X-API-KEY` が必要（キー名のみ言及。値は README 参照）。
----
-## 7. よくある調整手順の例
-例1: 「タイトル一致を最優先にしたい」
-1) `config/search_model.json` の `bm25f.field_weights.name` を少し上げる（例: 2.0 → 2.5）。
-2) API を再起動して挙動を確認。
-例2: 「言い換えの拾いすぎを抑えたい」
-1) `synonyms.enable` を false にする、または `limits.max_expansions_per_term` を下げる。
-2) 適宜 `word_sim.alpha` を上げて BM25 寄りに。
-3) 必要に応じて `scripts/3_build_synonyms_from_sudachi.py` を再実行。
-例3: 「“団体名”の指名検索をもっと強く」
-1) `circleName.boost.exact` や `prefix` を上げる。
-2) 極端になりすぎたら `filter` の閾値で下支え。
----
-## 8. ちょっとした注意点とチェックリスト
-- Sudachi の対象品詞（`target_pos_l1`）や対象フィールド（`target_fields`）を変えると、多くの中間データを作り直す必要があります（3,4,5,6）。
-- `.bin`（fastText Subword）は OOV 補助用、`.vec` は語彙ベクトル抽出用です。両方あると最もリッチに動きます。
-- デバッグ時は `POST /api/search` で `debug=true` を使うと、BM25/類似/ブースト/合成の内訳が見られます。
-- 値は README の .env を参照（ここではキー名のみ）。例: `API_SECRET_KEY`, `HF_TOKEN`, `HF_EMBEDDINGS_REPO_ID`。
----
-## 9. 用語ミニ辞典
-- BM25/BM25F: 単語の一致度をスコア化する仕組み。F はフィールド重み付きの拡張版。
-- IDF: 珍しい単語ほど高い値（差別力がある）。
-- fastText: 単語をベクトルにする技術。未知語も subword で推測可能。
-- OOV: 語彙外（Out-Of-Vocabulary）。手元の語彙にない単語のこと。
----
-困ったら、まずは `config/search_model.json` を少しずつ調整して、効果を `debug=true` で確認するのがおすすめです。

docs/project_schema_change_points.md DELETED Viewed

@@ -1,40 +0,0 @@
-# Project Schema / Data Source Migration – Change Points
-## Background
-- `schemas/projects.py` now defines DB-backed models whose core fields are `description` (企画内容), `prSummary` (PRコメント), `prDetail` (PRコメント詳細) together with `notes`, `images`, and `urls`.
-- Batch scripts under `scripts/` must keep generating search assets from the database export (`projects.json`) instead of the legacy CSV.
-- The API layer (`app/main.py`) serves the DB-derived models directly, while the search engine (`app/search/engine.py`) consumes the statically generated artefacts.
-## Config (`config/files.json`)
-- Remove the unused `projects.original_csv` entry and expose an explicit `projects.output_json` mapping so scripts resolve the generated JSON path without relying on hard-coded fallbacks.
-## Batch Scripts (`scripts/`)
-### `scripts/2_create_projects_data.py`
-- Lines `20-32` call `ProjectsRepository.list_projects()` and then pass the resulting Pydantic models straight into `json_dumps`; convert them to serialisable dictionaries via `model_dump(mode="json")` (or equivalent) before writing.
-- Ensure `ProjectsRepository` and `app/repositories/query.sql` surface `prSummary`, `prDetail`, and `notes` so the exported JSON aligns with `schemas.projects.Project`.
-### `scripts/3_build_synonyms_from_sudachi.py`
-- The loader at `scripts/3_build_synonyms_from_sudachi.py:65-112` instantiates `Project` objects and iterates `target_fields`. Verify that the regenerated `projects.json` exposes `name`, `circleName`, `circleNameKana`, `description`, `prSummary`, and `prDetail`; missing keys will degrade vocabulary extraction for synonyms.
-### `scripts/4_prepare_bm25f_meta.py`
-- The token loop at `scripts/4_prepare_bm25f_meta.py:52-104` depends on the same field names. Confirm that `projects.json` no longer contains legacy keys such as `organization`/`title`, otherwise IDF statistics will be incorrect.
-### `scripts/5_prepare_tf_token.py`
-- Update the `tf_token.Fields` construction at `scripts/5_prepare_tf_token.py:108-115` to use `name`, `circleName`, `circleNameKana`, `description`, `prSummary`, and `prDetail`. This keeps the TF schema consistent with the updated models.
-- Continue serialising with `model_dump()` at `scripts/5_prepare_tf_token.py:117-127` once the field names match.
-### `scripts/7_prepare_circle_names.py`
-- The mapper at `scripts/7_prepare_circle_names.py:68-74` still relies on `Project.organization` / `Project.reading`. Replace these with `circleName` / `circleNameKana` so the generated circle name and substring assets remain accurate.
-## API Layer (`app/main.py`)
-- `app/main.py:94-105` currently dumps `ProjectSummary` instances directly. Convert to `model_dump()` (or `jsonable_encoder`) before gzipping to avoid serialisation errors.
-- `ProjectSummary.image` should pick the `Image` entry whose `order == 0`. If multiple images share `order == 0`, use the *last* one encountered to mirror repository behaviour.
-- Ensure the summary payload exposes `notes` (renamed from `note`) and the PR fields `prSummary` / `prDetail` as returned by the repository.
-## Search Engine (`app/search/engine.py`)
-- In `SearchEngine.initialize` (`app/search/engine.py:164-175`) ensure kana norms are stored directly in `self.reading_norms` so substring boosts continue to consider kana values during scoring.
-- Debug responses at `app/search/engine.py:643-645` reference `organization` / `title`; switch these to `circleName` / `name` so diagnostics stay meaningful with the new schema.
-- Rebuild all search assets (`projects.json`, `tf_token.json`, `bm25_meta.json`, `substring_index.json`) after applying the script updates above.
-## Open Questions / Follow-ups
-1. None – requirements above clarify the PR field names, notes rename, image selection rule, and config key addition.

docs/システムガイド.md ADDED Viewed

	@@ -0,0 +1,961 @@

+# 千葉大祭 企画情報検索システム - 完全ガイド
+**作成日**: 2025年12月11日
+**対象**: 大学1～2年生向けのシステム解説
+**言語**: 日本語
+---
+## 目次
+1. [全体像](#1-全体像)
+2. [システムアーキテクチャ](#2-システムアーキテクチャ)
+3. [ディレクトリ構成と役割](#3-ディレクトリ構成と役割)
+4. [検索システムの仕組み](#4-検索システムの仕組み)
+5. [設定ファイルとカスタマイズ](#5-設定ファイルとカスタマイズ)
+6. [データの流れと更新方法](#6-データの流れと更新方法)
+7. [APIの使い方](#7-apiの使い方)
+8. [開発・デプロイ](#8-開発デプロイ)
+9. [トラブルシューティング](#9-トラブルシューティング)
+---
+## 1. 全体像
+### 何をするシステムか
+このシステムは、千葉大祭に出店する団体の「企画情報」を効率よく提供・検索するためのものです。
+**具体的な機能：**
+- **企画データの管理**: 団体名、企画名、説明、写真などを一元管理
+- **高度な検索**: キーワードから関連する企画を「正確に」「素早く」見つける
+- **API提供**: Web・モバイルアプリなどのフロントエンドに情報を提供
+### なぜ「高度な検索」が必要か
+単純なキーワード完全一致だけでは、ユーザーの満足度が低いです。例えば：
+- ユーザーが「学園祭」と検索 → 「大学祭」という企画も関連しているはず
+- ユーザーが「ラーメン」と検索 → 「そば」なども同じくらい検索対象にしたい
+- ユーザーが「カレー 販売」と検索 → どちらかのキーワードだけでなく、両方関連する企画を上位に
+このシステムは、以下の手法を組み合わせて、こうした「意味的に関連した」企画を見つけ出します：
+1. **BM25F**: 単語の出現頻度と珍しさから「単語一致の強さ」を計算
+2. **単語ベクトル**: 単語の「意味的な近さ」を計算
+3. **同義語展開**: 「学園祭」と「大学祭」など言い換えを自動認識
+4. **団体名マッチング**: 入力が団体名に該当すれば優先的に表示
+---
+## 2. システムアーキテクチャ
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     フロントエンド（Web/App）                   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+                    ┌─────────────────────┐
+                    │  FastAPI サーバー   │
+                    │  (app/main.py)      │
+                    └─────────────────────┘
+                      ↓                  ↓
+            ┌──────────────────┐  ┌──────────────────┐
+            │  検索エンジン    │  │ MySQLデータベース  │
+            │ (search/engine) │  │  (企画データ)     │
+            └──────────────────┘  └──────────────────┘
+                      ↓
+       ┌────────────────────────────────────┐
+       │   静的アセット（JSONファイル等）     │
+       │  - projects.json (企画データ)       │
+       │  - bm25_meta.json (検索用統計)     │
+       │  - synonyms_cache.json (同義語)   │
+       │  - word_vectors.npz (単語ベクトル) │
+       └────────────────────────────────────┘
+```
+**データの流れ：**
+1. **初期化時**（サーバー起動）
+   - MySQLから最新の企画データを取得
+   - 検索用の各種アセット（JSON、ベクトルなど）をメモリに読み込み
+   - 検索エンジンを初期化
+2. **検索時**（ユーザーがキーワード入力）
+   - キーワードを形態素解析（単語に分割）
+   - BM25F + 単語ベクトル で各企画のスコアを計算
+   - スコアの高い順に結果を返す
+3. **企画データ更新時**
+   - MySQLの企画情報を更新
+   - スクリプトで検索用アセットを再生成
+   - サーバーを再起動
+---
+## 3. ディレクトリ構成と役割
+```
+chibafes-website-api-v2/
+├── app/                           # メインアプリケーション
+│   ├── main.py                    # FastAPI エントリポイント
+│   ├── search/
+│   │   └── engine.py              # 検索エンジン実装
+│   ├── repositories/
+│   │   ├── projects_repository.py # DB連携（データ取得）
+│   │   └── query.sql              # SQL クエリ
+│   ├── services/
+│   │   └── projects_service.py    # ビジネスロジック
+│   ├── db/
+│   │   └── session.py             # DB接続管理
+│   └── api/
+│       └── routers/               # API エンドポイント定義
+│
+├── scripts/                       # データ生成パイプライン
+│   ├── build_all.py               # 全ステップを実行（推奨）
+│   ├── 0_download_data.py         # fastText ベクトルをダウンロード
+│   ├── 1_build_dict.py            # Sudachi ユーザー辞書を構築
+│   ├── 2_create_projects_data.py  # DB → projects.json
+│   ├── 3_build_synonyms_from_sudachi.py # 同義語キャッシュ生成
+│   ├── 4_prepare_bm25f_meta.py    # BM25F統計を計算
+│   ├── 5_prepare_tf_token.py      # TF/トークン情報を保存
+│   ├── 6_build_word_embeddings.py # 単語ベクトルを抽出
+│   └── 7_prepare_circle_names.py  # 団体名インデックスを生成
+│
+├── config/                        # 設定ファイル
+│   ├── search_model.json          # 検索挙動の詳細設定
+│   └── files.json                 # ファイルパスマッピング
+│
+├── schemas/                       # データモデル定義
+│   └── projects.py                # Project, ProjectSummary 等
+│
+├── resources/                     # 入力素材
+│   ├── stopwords.json             # ストップワード（検索対象外の語）
+│   ├── synonyms_custom.json       # カスタム同義語辞書
+│   ├── user_dict.csv              # Sudachi ユーザー辞書
+│   └── embeddings/                # 単語ベクトル（fastText）
+│
+├── data/generated/                # 自動生成されるファイル
+│   ├── projects.json              # 企画データ（検索用）
+│   ├── bm25_meta.json             # BM25F用統計
+│   ├── tf_token.json              # TF/トークン情報
+│   ├── synonyms_cache.json        # 処理済み同義語
+│   ├── word_vocab.json            # 単語→インデックスの対応表
+│   ├── word_vectors.npz           # 単語ベクトル行列
+│   ├── circle_names.json          # 団体名インデックス
+│   └── substring_index.json       # 部分文字列マッチ用インデックス
+│
+├── utils/                         # ユーティリティ
+│   ├── json.py                    # JSON操作
+│   ├── io.py                      # ファイルI/O
+│   ├── logger.py                  # ログ出力
+│   └── text_process.py            # テキスト前処理
+│
+└── docs/                          # ドキュメント
+    └── *.md                       # このファイルを含む説明書
+```
+### 主要ファイルの役割
+#### `app/main.py` - APIサーバーのエントリポイント
+FastAPIで、フロントエンドからのリクエストを受け取り、検索結果やデータを返します。
+**主なエンドポイント：**
+- `GET /api/health`: サーバーの状態確認
+- `GET /api/projects`: 全企画の一覧を取得
+- `GET /api/details?projectId=xxx`: 特定の企画の詳細を取得
+- `POST /api/search`: キーワード検索を実行
+#### `app/search/engine.py` - 検索エンジンの核
+BM25F、単語ベクトル、同義語など各種手法を組み合わせて検索スコアを計算します。
+**主な処理：**
+- トークン化：キーワードを単語に分割
+- 同義語展開：「学園祭」→「大学祭」なども検索対象に
+- BM25F計算：単語の出現パターンからスコア化
+- ベクトル類似度：意味的な近さを計算
+- スコア融合：複数の指標を組み合わせて最終スコアを算出
+#### `config/search_model.json` - 検索の挙動を制御
+検索エンジンの細かな動作を調整するための設定ファイルです。後述の「カスタマイズ」で詳しく説明します。
+---
+## 4. 検索システムの仕組み
+### 全体フロー
+```
+ユーザーの入力 "カレー 販売"
+          ↓
+    ┌──────────────────┐
+    │ トークン化（形態素解析）│  → ["カレー", "販売"]
+    └──────────────────┘
+          ↓
+    ┌──────────────────┐
+    │  同義語を展開       │  → ["カレー", "販売", "食事", "販売"]
+    └──────────────────┘
+          ↓
+    ┌─────────────��───────────────┐
+    │ 各企画に対して3つのスコアを計算  │
+    │ 1. BM25F (単語一致度)        │
+    │ 2. 単語ベクトル類似度         │
+    │ 3. 団体名マッチングボーナス    │
+    └─────────────────────────────┘
+          ↓
+    ┌──────────────────┐
+    │  スコア統合        │  → 複数指標を1つのスコアに
+    └──────────────────┘
+          ↓
+    ┌──────────────────┐
+    │ 閾値フィルタ       │  → 低すぎるスコアを除外
+    └──────────────────┘
+          ↓
+    ┌──────────────────┐
+    │  ソート＆返却      │  → スコア順に上位30件を返す
+    └──────────────────┘
+```
+### 4.1 トークン化（形態素解析）
+**概念：** テキストを「意味を持つ最小単位」に分割します。
+例：
+```
+入力："カレー販売団体の美味しい食事"
+↓
+トークン化：["カレー", "販売", "団体", "美味しい", "食事"]
+（助詞「の」などは除外）
+```
+**実装：** SudachiPyという形態素解析エンジンを使用します。これは日本語を高精度に分析できます。
+**カスタマイズ方法：**
+- `resources/stopwords.json`: 除外する語を指定（例：「のが」など）
+- `resources/user_dict.csv`: 新しい単語を登録（例：ニッチなサークル名など）
+---
+### 4.2 同義語展開
+**概念：** 異なる表現でも同じ意味の語を自動的に広げます。
+例：
+```
+入力語："大学祭"
+↓
+同義語展開：["大学祭", "学園祭", "キャンパスフェスタ"]
+（すべてのバリエーションで検索）
+```
+**メリット：** ユーザーがどのバリエーションで入力しても、関連企画が見つかります。
+**データソース：** 2つの辞書から同義語を取得
+1. **Sudachi公式辞書**: 標準的な同義語（無料）
+2. **カスタム同義語** (`resources/synonyms_custom.json`): プロジェクト固有の同義語を手動追加
+**カスタマイズ方法：**
+```json
+// resources/synonyms_custom.json の例
+{
+  "カレー": ["食事", "飲食"],
+  "ステージ": ["舞台", "パフォーマンス"],
+  "学園祭": ["大学祭", "キャンパスフェスタ"]
+}
+```
+---
+### 4.3 BM25F - 単語一致の強さを計算
+**概念：** 単語がどれくらい「珍しいか」「繰り返し出ているか」から検索スコアを計算します。
+**簡単な説明：**
+1. **IDF（珍しさスコア）**: 多くの企画に出現する語は価値が低く、少ない企画にしか出現しない語は価値が高い
+   - 例：「食べ物」は多くの企画に出現→低い価値
+   - 例：「生ビール」は少ない企画にしか出現→高い価値
+2. **TF（繰り返し度）**: ある企画の中で、その単語がどれくらい繰り返し出ているか
+   - 例：「カレー」という企画説明に「カレー」という単語が5回出現→高いTF
+3. **フィールド重み**: 企画名に出現する単語と、長い説明文に出現する単語では重要度が異なる
+   - 例：企画名 (重み 2.0) > 説明文 (重み 1.0)
+**実装の詳細は「検索アルゴリズム詳説」を参照**
+---
+### 4.4 単語ベクトル - 意味的な近さを計算
+**概念：** 単語を「多次元空間の点」として表現し、距離の近さで「意味の似ている度」を計算します。
+例：
+```
+      ← 意味が似ている →
+"カレー" と "スープ" は空間上で近い
+"カレー" と "プログラミング" は空間上で遠い
+```
+**メリット：**
+- 「カレー」で検索 → 「ラーメン」「そば」なども関連として見つかる
+- 同義語辞書に登録していない言い換えでも対応
+**実装：** fastTextという機械学習モデルを使用。このモデルは、大量の日本語テキストから事前に学習済みです。
+**カスタマイズ方法：**
+実装難度が高いため、通常はカスタマイズ不要です。スコアウエイトは設定ファイルで調整できます（後述）。
+---
+### 4.5 団体名マッチング - 直接一致の加点
+**概念：** ユーザーの入力が「団体名」や「団体名の読み仮名」に合致した場合、スコアを加算します。
+例：
+```
+入力："写真部"
+↓
+団体名が「写真部」に完全一致 → +1.0点
+```
+**3段階の加点ルール：**
+- **完全一致** (例：入力 "写真部" = 団体名 "写真部") → 加点: 1.0
+- **前方一致** (例：入力 "写真" = 団体名 "写真部" の前半) → 加点: 0.7
+- **部分一���** (例：入力 "写" = 団体名 "写真部" に含む) → 加点: 0.5
+**カスタマイズ方法：** `config/search_model.json` の `circleName.boost` で調整可能（後述）
+---
+### 4.6 スコア統合と閾値フィルタリング
+**概念：** 複数の指標（BM25F、ベクトル類似度、団体名加点）を1つのスコアに統合します。
+**統合式（概略）：**
+```
+最終スコア = α × BM25F + (1-α) × 単語ベクトル類似度 + 団体名加点
+```
+ここで α はウェイト（デフォルト 0.5 = 両者を同じ重要度とみなす）
+**フィルタリング：** スコアが一定以下の企画は結果から除外します。ノイズ除去と計算効率化のため。
+---
+## 5. 設定ファイルとカスタマイズ
+### 5.1 `config/search_model.json` - 検索挙動の詳細設定
+このファイルを編集して、検索の細かな動作を調整できます。
+```json
+{
+  "target_pos_l1": [
+    "名詞",
+    "動詞",
+    "形容詞",
+    "形容動詞語幹"
+  ],
+  "target_fields": [
+    "name",
+    "circleName",
+    "circleNameKana",
+    "description",
+    "prSummary",
+    "prDetail"
+  ],
+  "synonyms": {
+    "enable": true,
+    "limits": {
+      "max_expansions_per_term": 4,
+      "max_query_variants": 5,
+      "min_char_len": 2
+    }
+  },
+  "bm25f": {
+    "k1": 1.2,
+    "b": 0.75,
+    "field_weights": {
+      "name": 2.0,
+      "circleName": 1.5,
+      "circleNameKana": 0.6,
+      "description": 1.0,
+      "prSummary": 1.0,
+      "prDetail": 0.8
+    }
+  },
+  "word_sim": {
+    "enable": true,
+    "alpha": 0.5,
+    "topk_k": 3
+  },
+  "circleName": {
+    "boost": {
+      "exact": 1.0,
+      "prefix": 0.7,
+      "substring": 0.5,
+      "min_len": 2
+    }
+  },
+  "filter": {
+    "min_results": 10,
+    "max_results": 30,
+    "bm25_min": 0.15,
+    "word_sim_min": 0.40,
+    "fused_min": 0.15,
+    "fused_rel_top_ratio": 0.50
+  }
+}
+```
+**各項目の意味と調整方法：**
+| 項目 | 説明 | 調整例 |
+|------|------|--------|
+| `target_pos_l1` | トークン化時に対象とする品詞 | 「助詞」を追加したい場合は配列に追加 |
+| `target_fields` | 検索対象にするフィールド | `prDetail`を除きたい場合は削除 |
+| `synonyms.enable` | 同義語展開の有無 | `false`で無効化 |
+| `synonyms.limits.max_expansions_per_term` | 1つの単語から展開する同義語の最大数 | 値を大きくするほど多くの同義語を使用 |
+| `bm25f.field_weights` | 各フィールドの重要度 | 企画名（name）を重視したい場合、値を大きく（例：3.0） |
+| `word_sim.alpha` | BM25FとベクトルのウェイトMIX | 0.5 = 両者を同じ重要度。BM25Fを重視したい場合は0.7に |
+| `circleName.boost.exact` | 団体名完全一致の加点 | 団体名マッチを重視したい場合は2.0に |
+| `filter.max_results` | 返す結果の最大件数 | 結果を少なくしたい場合は20に減らす |
+| `filter.fused_min` | スコアの下限（閾値） | 値を上げるとフィルタリングが厳しくなる |
+**変更手順：**
+1. `config/search_model.json` をテキストエディタで開く
+2. 該当の値を修正（JSONの形式を崩さないよう注意）
+3. サーバーを再起動
+4. `/api/search` でデバッグ情報を確認 (`debug=true` パラメータ)
+---
+### 5.2 `config/files.json` - ファイルパスマッピング
+各種アセット（JSON、ベクトルなど）の保存場所を指定します。通常は変更不要ですが、ファイルの移動が必要な場合に編集します。
+```json
+{
+  "sudachi": {
+    "sudachi_config": "scripts/sudachi.json",
+    "stopwords": "resources/stopwords.json"
+  },
+  "projects": {
+    "projects_json": "data/generated/projects.json"
+  },
+  "bm25": {
+    "bm25_meta": "data/generated/bm25_meta.json",
+    "tf_token": "data/generated/tf_token.json"
+  },
+  "embeddings": {
+    "fasttext_bin": "resources/embeddings/cc.ja.300.bin",
+    "word_vocab": "data/generated/word_vocab.json",
+    "word_vectors": "data/generated/word_vectors.npz"
+  }
+}
+```
+---
+### 5.3 `resources/synonyms_custom.json` - カスタム同義語
+プロジェクト固有の同義語を手動で登録します。
+**編集例：**
+```json
+{
+  "カレー": ["食事", "飲食"],
+  "ステージ": ["舞台", "パフォーマンス"],
+  "学園祭": ["大学祭"],
+  "AI": ["人工知能", "機械学習"]
+}
+```
+**変更手順：**
+1. `resources/synonyms_custom.json` を編集
+2. スクリプト `scripts/build_all.py` を実行して、同義語キャッシュを再生成
+3. サーバーを再起動
+---
+### 5.4 `resources/stopwords.json` - ストップワード
+検索対象から除外する語（あまり意味がない頻出語）を登録します。
+**デフォルト例：**
+```json
+[
+  "の",
+  "が",
+  "を",
+  "に",
+  "で",
+  "は",
+  "から",
+  "まで"
+]
+```
+**変更方法：**
+同様���ファイルを編集 → スクリプト実行 → サーバー再起動
+---
+## 6. データの流れと更新方法
+### 6.1 システム起動時の流れ
+```
+1. サーバー起動 (app/main.py)
+   ↓
+2. 検索エンジン初期化 (engine.initialize())
+   ├─ config/search_model.json を読み込み
+   ├─ config/files.json からファイルパスを取得
+   ├─ data/generated/*.json を読み込み（企画データ、BM25F統計など）
+   ├─ resources/embeddings/ から単語ベクトルを読み込み
+   └─ Sudachi形態素解析器を初期化
+   ↓
+3. サーバー起動完了
+   フロントエンドからのリクエスト受付開始
+```
+### 6.2 企画データの更新フロー
+**状況：** MySQLの企画データが更新された
+**手順：**
+```
+1. MySQLのデータを確認
+   ↓
+2. スクリプト実行: python scripts/build_all.py
+   ├─ Step 0: fastText ベクトルをダウンロード（初回のみ）
+   ├─ Step 1: Sudachi ユーザー辞書を構築（オプション）
+   ├─ Step 2: DB → projects.json 生成
+   ├─ Step 3: 同義語キャッシュを生成
+   ├─ Step 4: BM25F統計を計算
+   ├─ Step 5: TF/トークン情報を保存
+   ├─ Step 6: 単語ベクトルを抽出
+   └─ Step 7: 団体名インデックスを生成
+   ↓
+3. サーバーを再起動
+   ↓
+4. フロントエンドで新しい企画データが見える
+```
+**詳細：**
+#### Step 2: `scripts/2_create_projects_data.py` - DB → JSON変換
+```
+MySQL から企画データを取得
+  → ProjectRepository.list_projects()
+  → 各種テキスト（説明文など）を更新情報から最新版を抽出
+  → projects.json に出力
+```
+このステップ以降のデータは、すべてこの `projects.json` から生成されます。
+#### Step 3: `scripts/3_build_synonyms_from_sudachi.py` - 同義語キャッシュ
+```
+projects.json の全テキストをトークン化
+  → 出現語彙を収集
+  → Sudachi同義語辞書 + custom synonyms.json から該当するもののみ抽出
+  → synonyms_cache.json に保存
+```
+目的：実際のコーパスに出現しない同義語は使わない（ノイズ削減）
+#### Step 4-5: `scripts/4_prepare_bm25f_meta.py` と `scripts/5_prepare_tf_token.py` - BM25F統計
+```
+projects.json をトークン化
+  → IDF（珍しさスコア）を計算
+  → 各フィールドの平均トークン数を計算
+  → bm25_meta.json に保存
+各企画ごとのTF（単語の出現数）を計算
+  → tf_token.json に保存
+```
+#### Step 6: `scripts/6_build_word_embeddings.py` - 単語ベクトル抽出
+```
+tf_token.json から語彙リストを取得
+  → fastText ベクトルから該当する単語のベクトルを抽出
+  → word_vocab.json と word_vectors.npz に保存
+```
+### 6.3 各ステップの実行時間（目安）
+| ステップ | 処理内容 | 実行時間 |
+|---------|---------|---------|
+| 0 | fastText ダウンロード | 初回のみ数分 |
+| 1 | Sudachi辞書構築 | 1-2分 |
+| 2 | DB→JSON | 数秒 |
+| 3 | 同義語キャッシュ | 10-30秒 |
+| 4 | BM25F統計 | 1-2分 |
+| 5 | TF/トークン | 1-2分 |
+| 6 | 単語ベクトル | 1-2分 |
+| 7 | 団体名インデックス | 数秒 |
+**全ステップ実行** → 合計約5-10分
+---
+## 7. APIの使い方
+### 7.1 ヘルスチェック
+```bash
+curl "http://localhost:7860/api/health"
+```
+レスポンス：
+```json
+{
+  "status": "ok"
+}
+```
+### 7.2 企画一覧取得
+```bash
+curl -H "X-API-KEY: YOUR_SECRET_KEY" \
+     "http://localhost:7860/api/projects"
+```
+**認証方法：**
+- ヘッダ `X-API-KEY` に `API_SECRET_KEY` 環境変数の値を指定
+- 環境変数は `.env` ファイルに保存（リポジトリには含めない）
+**レスポンス（gzip圧縮）：**
+```json
+[
+  {
+    "projectId": "62000A",
+    "circleName": "写真部",
+    "name": "写真展覧会",
+    "projectType": "テント企画",
+    "category": "展示",
+    "day1": true,
+    "day2": true,
+    "day3": false,
+    "location": "第1キャンパス A-1",
+    "description": "写真部による年間作品展...",
+    "prSummary": "写真の美しさを...",
+    "remark": null,
+    "image": {
+      "filename": "photo1.jpg",
+      "extension": "jpg",
+      "order": 0
+    }
+  },
+  ...
+]
+```
+### 7.3 企画詳細取得
+```bash
+curl -H "X-API-KEY: YOUR_SECRET_KEY" \
+     "http://localhost:7860/api/details?projectId=62000A"
+```
+レスポンス：
+```json
+{
+  "projectId": "62000A",
+  "circleName": "写真部",
+  "name": "写真展覧会",
+  ...
+  "prDetail": "詳細なPR文が入ります...",
+  "images": [
+    {
+      "filename": "photo1.jpg",
+      "extension": "jpg",
+      "order": 0
+    },
+    {
+      "filename": "photo2.jpg",
+      "extension": "jpg",
+      "order": 1
+    }
+  ],
+  "socialMedia": [
+    {
+      "service": "Instagram",
+      "url": "https://instagram.com/..."
+    }
+  ]
+}
+```
+### 7.4 検索
+```bash
+curl -X POST -H "X-API-KEY: YOUR_SECRET_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"query": "カレー"}' \
+     "http://localhost:7860/api/search"
+```
+**レスポンス（通常モード）:**
+```json
+{
+  "projectIds": ["12345A", "67890B", "11111C"]
+}
+```
+### 7.5 検索（デバッグモード）
+```bash
+curl -X POST -H "X-API-KEY: YOUR_SECRET_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"query": "カレー", "debug": true}' \
+     "http://localhost:7860/api/search"
+```
+**レスポンス（デバッグモード）:**
+```json
+{
+  "projectIds": ["12345A", "67890B"],
+  "scores": [
+    {
+      "projectId": "12345A",
+      "score": 2.15
+    },
+    {
+      "projectId": "67890B",
+      "score": 1.83
+    }
+  ],
+  "details": [
+    {
+      "projectId": "12345A",
+      "circleName": "飲食部A",
+      "name": "カレー販売",
+      "bm25": 0.85,
+      "ws_filter_topk": 0.72,
+      "ws_rerank_pairavg": 0.75,
+      "org_boost": 0.0,
+      "matched_substring": false,
+      "fused_filter": 0.78,
+      "fused_final": 2.15
+    },
+    {}
+  ]
+}
+```
+**デバッグ情報の各項目：**
+- `bm25`: BM25Fスコア（単語一致度）
+- `ws_filter_topk`: 単語ベクトル類似度（フィルタリング用、top-k方式）
+- `ws_rerank_pairavg`: 単語ベクトル類似度（リランキング用、pair-average方式）
+- `org_boost`: 団体名マッチングボーナス
+- `matched_substring`: 部分文字列マッチングで団体名に合致したか
+- `fused_filter`: フィルタリング段階での統合スコア
+- `fused_final`: 最終統合スコア
+### 7.6 データ更新エンドポイント
+```bash
+curl -X POST -H "X-API-KEY: YOUR_SECRET_KEY" \
+     -H "Content-Type: application/json" \
+     "http://localhost:7860/tasks/update"
+```
+**用途：** MySQLの企画データが更新された時に、このエンドポイントを呼び出すと、検索用アセット（`data/generated/` 配下のファイル）が自動的に再生成されます。
+**レスポンス:**
+```json
+{
+  "message": "Data update completed."
+}
+```
+**注意：** このエンドポイントは認証が必要で、実行に数分かかる場合があります。サーバーのCPU使用率が高くなる可能性があります。
+---
+## 補足：開発時のデバッグ方法
+### デバッグモードの活用
+スコアリングロジックをチューニングする際は、必ずデバッグモードを使用してください。各スコアの詳細が表示されるため、改善点を特定しやすくなります。
+```bash
+# テスト検索
+curl -X POST -H "X-API-KEY: key" \
+     -H "Content-Type: application/json" \
+     -d '{"query": "テスト", "debug": true}' \
+     "http://localhost:7860/api/search" | jq '.details[0]'
+```
+各スコアが期待通りの値になっているか確認してください。異常な値が見つかった場合は、設定ファイルを見直すか、ロジックを確認します。
+---
+## 8. 開発・デプロイ
+### 8.1 ローカル開発環境の構築
+**前提条件：**
+- Python 3.11以上
+- MySQL（ローカルまたはリモート）
+- pip または conda
+**手順：**
+```bash
+# 1. リポジトリをクローン
+git clone https://github.com/chibafes-dev/chibafes-website-api-v2.git
+cd chibafes-website-api-v2
+# 2. Pythonの仮想環境を作成
+python3.11 -m venv venv
+source venv/bin/activate  # macOS/Linux
+# or
+venv\Scripts\activate  # Windows
+# 3. 依存パッケージをインストール
+pip install -r requirements.txt
+# 4. .env ファイルを作成（セキュリティ情報は社内ツールから取得）
+# DATABASE_URL=mysql://user:pass@host:3306/db
+# API_SECRET_KEY=...
+# HF_TOKEN=...
+# 5. データ生成スクリプトを実行
+python scripts/build_all.py
+# 6. サーバーを起動
+python -m uvicorn app.main:app --reload --port 7860
+```
+### 8.2 Docker でのデプロイ
+```bash
+# ビルド
+docker build -t chibafes-api:latest .
+# 実行
+docker run -e DATABASE_URL="..." \
+           -e API_SECRET_KEY="..." \
+           -p 7860:7860 \
+           chibafes-api:latest
+```
+---
+## 9. トラブルシューティング
+### 問題: サーバー起動後、検索結果が出ない
+**原因候補：**
+1. `data/generated/` のファイルが不足している
+2. MySQLのデータが空である
+3. 設定ファイルのパスが間違っている
+**対処：**
+```bash
+# Step 1: ファイルの確認
+ls -la data/generated/
+# Step 2: スクリプトを再実行
+python scripts/build_all.py
+# Step 3: サーバーログを確認
+# 「Initializing search engine」から始まるログをチェック
+```
+### 問題: 検索結果のスコアがおかしい
+**対処：**
+1. デバッグモードで詳細情報を確認
+   ```bash
+   curl -X POST -d '{"query": "テスト", "debug": true}' ...
+   ```
+2. `config/search_model.json` ��確認
+   - `filter.fused_min` が高すぎないか
+   - `word_sim.alpha` のウェイトは適切か
+3. 検索用アセットを再生成
+   ```bash
+   python scripts/build_all.py
+   ```
+### 問題: 特定の単語が検索されない
+**原因候補：**
+1. ストップワードに指定されている
+2. 品詞が `target_pos_l1` に含まれていない
+3. 未知語で、Sudachiで正しく分析されていない
+**対処：**
+1. `resources/stopwords.json` を確認
+2. `config/search_model.json` の `target_pos_l1` を確認
+3. `resources/user_dict.csv` に未知語を登録
+### 問題: パフォーマンスが悪い（検索が遅い）
+**対処：**
+1. `filter.max_results` を減らす
+2. `word_sim.topk_k` を小さくする
+3. `config/search_model.json` の `synonyms.limits.max_expansions_per_term` を減らす
+---
+## 付録：よくある調整例
+### 企画名をもっと重視したい
+```json
+{
+  "bm25f": {
+    "field_weights": {
+      "name": 3.0,        // ← 2.0 から 3.0 に変更
+      "circleName": 1.5,
+      "description": 1.0,
+      ...
+    }
+  }
+}
+```
+### 同義語を使いたくない
+```json
+{
+  "synonyms": {
+    "enable": false     // ← true から false に変更
+  }
+}
+```
+### 単語ベクトルよりもBM25Fを重視
+```json
+{
+  "word_sim": {
+    "alpha": 0.7        // ← 0.5 から 0.7 に変更
+  }
+}
+```
+（alphaが大きいほどBM25Fのウェイトが大きくなる）
+### 結果を増やしたい
+```json
+{
+  "filter": {
+    "max_results": 50,  // ← 30 から 50 に変更
+    "fused_min": 0.10   // ← 0.15 から 0.10 に（閾値を下げる）
+  }
+}
+```
+---
+## さらに学びたい方へ
+- **基礎知識の補足**: `基礎知識.md` を参照（Python、FastAPI、MySQLの基本など）
+- **検索アルゴリズムの数学的詳説**: `検索アルゴリズム詳説.md` を参照（BM25F、TF-IDF、コサイン類似度など）

docs/基礎知識.md ADDED Viewed

	@@ -0,0 +1,547 @@

+# 基礎知識：このプロジェクトで使われているツール・概念の入門
+**作成日**: 2025年12月11日
+**対象**: 大学1～2年生向けの背景知識解説
+**言語**: 日本語
+---
+このドキュメントは、本ガイド（「システムガイド.md」）を読むにあたって、必要な背景知識を提供するものです。すでに以下の内容に詳しい方は、スキップしても構いません。
+## 目次
+1. [Pythonの基本](#1-pythonの基本)
+2. [FastAPI](#2-fastapi)
+3. [MySQLとデータベース](#3-mysqlとデータベース)
+4. [JSON形式](#4-json形式)
+5. [環境変数](#5-環境変数)
+6. [Docker](#6-docker)
+7. [Git・バージョン管理](#7-gitバージョン管理)
+---
+## 1. Pythonの基本
+### Pythonとは
+**Pythonは、初心者にも使いやすい「プログラミング言語」です。**
+プログラミング言語 = コンピュータに「何をするか」を指示する言葉
+例えば：
+```python
+# 単純な足し算
+result = 3 + 5
+print(result)  # 8 と表示
+```
+Pythonは以下の理由で、このプロジェクトで選ばれています：
+- **読みやすい**: 日本語に近い構文で、初心者でも分かりやすい
+- **データ処理が得意**: 検索システムのように大量データを扱う時に便利
+- **ライブラリが豊富**: 必要な機能が既に用意されていることが多い
+### このプロジェクトで使われるPythonの機能
+#### 1.1 リスト（複数のデータをまとめて保存）
+```python
+# 企画のIDを複数保存
+projects = ["62000A", "12345B", "67890C"]
+# 最初の企画を取得
+first = projects[0]  # "62000A"
+# 全企画をループで処理
+for project_id in projects:
+    print(project_id)
+```
+#### 1.2 辞書（キーと値のペア）
+```python
+# 企画情報を辞書で保存
+project = {
+    "projectId": "62000A",
+    "circleName": "写真部",
+    "name": "写真展覧会"
+}
+# 値を取得
+print(project["circleName"])  # "写真部" と表示
+```
+#### 1.3 関数（処理をまとめて再利用）
+```python
+def greet(name):
+    """名前を受け取って、挨拶を返す関数"""
+    return f"こんにちは、{name}さん！"
+result = greet("太郎")
+print(result)  # "こんにちは、太郎さん！" と表示
+```
+#### 1.4 クラス（データと処理を組み合わせる）
+```python
+class Project:
+    """企画情報を管理するクラス"""
+    def __init__(self, name, description):
+        self.name = name
+        self.description = description
+    def get_info(self):
+        return f"{self.name}: {self.description}"
+# インスタンスを作成（実例を作る）
+p1 = Project("写真展覧会", "写真部による年間作品展")
+print(p1.get_info())
+```
+### 仮想環境とは
+Pythonでプロジェクトを開発する時、**複数のバージョン・複数の依存パッケージが混在しないように**「仮想環境」を作ります。
+例えば：
+- プロジェクトA: Pythonバージョン3.11、FastAPI 0.95
+- プロジェクトB: Pythonバージョン3.10、FastAPI 0.90
+各プロジェクトを独立した「仮想環境」で実行すれば、干渉しません。
+**作成方法：**
+```bash
+python3.11 -m venv venv
+source venv/bin/activate  # 仮想環境を有効化
+```
+---
+## 2. FastAPI
+### FastAPIとは
+**FastAPIは、Pythonで「Web API」を簡単に作るためのフレームワークです。**
+Web API = ネットワーク経由で、別のコンピュータが呼び出して使えるプログラム
+このプロジェクトの例：
+```
+フロントエンド（Web画面） ── HTTP通信 ──> FastAPI サーバー
+                      <── JSON返却 ──
+```
+### エンドポイント（APIの「入口」）
+APIには複数の「入口」があります。これを「エンドポイント」と呼びます。
+```python
+from fastapi import FastAPI
+app = FastAPI()
+@app.get("/api/health")
+def health_check():
+    """サーバーが動いているか確認するエンドポイント"""
+    return {"status": "ok"}
+@app.post("/api/search")
+def search(query: str):
+    """キーワードで企画を検索するエンドポイント"""
+    return {"results": [...]}
+```
+**アクセス方法：**
+```bash
+# GET リクエスト
+curl "http://localhost:7860/api/health"
+# POST リクエスト（データを送信）
+curl -X POST -H "Content-Type: application/json" \
+     -d '{"query": "カレー"}' \
+     "http://localhost:7860/api/search"
+```
+### HTTPメソッドの種類
+| メソッド | 用途 | 例 |
+|---------|------|-----|
+| `GET` | データを取得（参照のみ） | `/api/projects` - 全企画を取得 |
+| `POST` | 新しいデータを送信 | `/api/search` - 検索を実行 |
+| `PUT` | データを更新 | `/api/projects/123` - 企画を更新 |
+| `DELETE` | データを削除 | `/api/projects/123` - 企画を削除 |
+このプロジェクトは主に `GET` と `POST` を使っています。
+### 認証（セキュリティ）
+このプロジェクトでは、APIキーで保護されています。
+**概念：** 誰でもアクセスできるのではなく、正しいキーを持っている人だけがアクセスできる
+```python
+from fastapi import Security, HTTPException
+from fastapi.security import APIKeyHeader
+api_key_header = APIKeyHeader(name="X-API-KEY")
+def get_api_key(key: str = Security(api_key_header)):
+    if key != os.getenv("API_SECRET_KEY"):
+        raise HTTPException(status_code=403, detail="Invalid key")
+    return key
+```
+**使用方法：**
+```bash
+curl -H "X-API-KEY: your_secret_key" \
+     "http://localhost:7860/api/search"
+```
+---
+## 3. MySQLとデータベース
+### データベースとは
+**データベースは、大量のデータを効率よく保存・取得するためのシステムです。**
+例えば、千葉大祭の企画情報：
+- 企画数：数十～数百件
+- 各企画の情報：名前、説明、団体、日程など（10項目以上）
+- 合計：数千以上のデータポイント
+こを普通のテキストファイルで管理すると、検索や更新が非常に遅くなります。
+### MySQLの構造
+```
+┌─────────────────────────────────────┐
+│          MySQL データベース           │
+│  (chibafes)                         │
+├─────────────────────────────────────┤
+│ テーブル: circle_projects           │
+├─────────────────────────────────────┤
+│ カラム（列）: projectId, circleName, │
+│ name, description, prSummary, ...    │
+├─────────────────────────────────────┤
+│ 行1: 62000A, 写真部, 写真展覧会, ...  │
+│ 行2: 12345B, 映画研究会, 映画上映会, ... │
+│ 行3: ...                            │
+└─────────────────────────────────────┘
+```
+**テーブル = Excelのスプレッドシートのようなもの**
+- **列（カラム）** = 属性（例：企画ID、名前など）
+- **行（レコード）** = 1つのデータ（例：1つの企画）
+### SQLとは
+SQL（Structured Query Language）= データベースを操作する言葉
+**例：**
+```sql
+-- 企画一覧を取得
+SELECT projectId, name, circleName FROM circle_projects;
+-- 特定の企画を検索
+SELECT * FROM circle_projects WHERE name LIKE '%カレー%';
+-- データを追加
+INSERT INTO circle_projects (projectId, name) VALUES ('99999Z', '新企画');
+```
+このプロジェクトでは、`app/repositories/query.sql` にクエリが保存されています。
+### このプロジェクトでの使用方法
+```python
+# 1. DB接続を取得
+with get_connection() as conn:
+    # 2. クエリを実行
+    with conn.cursor() as cur:
+        cur.execute("SELECT * FROM circle_projects")
+        # 3. 結果を取得
+        rows = cur.fetchall()
+```
+---
+## 4. JSON形式
+### JSONとは
+**JSON（JavaScript Object Notation）は、データを構造化して表現する標準的な形式です。**
+Web APIの「やり取り」に最も使われています。
+### JSONの構成要素
+```json
+{
+  "projectId": "62000A",
+  "circleName": "写真部",
+  "tags": ["展示", "アート"],
+  "isActive": true,
+  "prDetail": null
+}
+```
+| 要素 | 説明 | 例 |
+|------|------|-----|
+| キー | データの名前 | `"projectId"` |
+| 値 | データの内容 | `"62000A"` |
+| 文字列 | テキスト（ダブルクォートで囲む） | `"写真部"` |
+| 数値 | 整数・小数 | `123` `45.6` |
+| 真偽値 | true/false | `true` |
+| 配列 | 複数のデータを順序付きで保存 | `["A", "B", "C"]` |
+| オブジェクト | キーと値をまとめた構造 | `{ "key": "value" }` |
+| null | 空・データなし | `null` |
+### JSONファイルの例
+`data/generated/projects.json` の一部：
+```json
+[
+  {
+    "projectId": "62000A",
+    "circleName": "写真部",
+    "name": "写真展覧会",
+    "description": "写真部による年間作品展示...",
+    "images": [
+      {
+        "filename": "photo1.jpg",
+        "order": 0
+      }
+    ]
+  },
+  {
+    "projectId": "12345B",
+    "circleName": "映画研究会",
+    "name": "映画上映会",
+    ...
+  }
+]
+```
+### Pythonでの読み書き
+```python
+import json
+# JSON ファイルを読む
+with open("data.json", "r", encoding="utf-8") as f:
+    data = json.load(f)  # JSONをPythonの辞書に変換
+# 値を取得
+print(data[0]["circleName"])  # "写真部"
+# Pythonの辞書を JSON に変換して書き出す
+with open("output.json", "w", encoding="utf-8") as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+```
+---
+## 5. 環境変数
+### 環境変数とは
+**環境変数は、プログラムの「設定値」をプログラムの外部に置く仕組みです。**
+なぜ必要か：
+- **セキュリティ**: パスワードやAPIキーをコードに直書きしない
+- **柔軟性**: 環境ごと（ローカル/本番）で異なる設定を簡単に変更できる
+- **バージョン管理**: センシティブな情報をGitにコミットしない
+### 設定方法
+#### 方法1: `.env` ファイル
+```bash
+# .env ファイル（リポジトリに含めない）
+DATABASE_URL=mysql://user:password@localhost:3306/chibafes
+API_SECRET_KEY=super_secret_key_here
+HF_TOKEN=hf_xxxxxxxxxxxxxx
+```
+```python
+# Python で読み込み
+from dotenv import load_dotenv
+import os
+load_dotenv()
+db_url = os.getenv("DATABASE_URL")
+api_key = os.getenv("API_SECRET_KEY")
+```
+#### 方法2: コマンドラインで設定
+```bash
+# Linuxの場合
+export DATABASE_URL="mysql://..."
+export API_SECRET_KEY="..."
+# または、プログラム実行時に指定
+API_SECRET_KEY="..." python app/main.py
+```
+#### 方法3: Docker/コンテナで設定
+```bash
+docker run -e DATABASE_URL="..." \
+           -e API_SECRET_KEY="..." \
+           myapp:latest
+```
+### このプロジェクトで必要な環境変数
+| 変数名 | 説明 | 例 |
+|--------|------|-----|
+| `DATABASE_URL` | MySQL接続情報 | `mysql://user:pass@host/db` |
+| `API_SECRET_KEY` | APIキー認証用 | `super_secret_123` |
+| `HF_TOKEN` | Hugging Face API用 | `hf_xxx...` |
+| `POSTHOG_PROJECT_API_KEY` | ログ分析用（オプション） | `phc_xxx...` |
+---
+## 6. Docker
+### Dockerとは
+**Dockerは、アプリケーションを「箱詰め」にして、どの環境でも同じに実行するための仕組みです。**
+**メリット：**
+- **再現性**: 開発者のPC、サーバー、他人のPCでも同じ環境で動作
+- **簡潔性**: 複雑な依存関係のインストール不要
+- **スケーラビリティ**: 複数の箱を並べて、負荷分散できる
+### Dockerイメージとコンテナ
+```
+Dockerfile（設計図）
+    ↓
+docker build
+    ↓
+イメージ（青写真）
+    ↓
+docker run
+    ↓
+コンテナ（実行中の箱）
+```
+**例：**
+```dockerfile
+# Dockerfile - イメージの設計図
+FROM python:3.11
+WORKDIR /app
+COPY . .
+RUN pip install -r requirements.txt
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]
+```
+```bash
+# イメージを構築
+docker build -t chibafes-api:latest .
+# コンテナを実行
+docker run -p 7860:7860 chibafes-api:latest
+```
+### このプロジェクトでのDocker使用
+プロジェクトルートにある `Dockerfile` が、このシステムの配置方法を定義しています。
+**本番環境（Hugging Face Spaces）では、このDockerイメージが使われます。**
+---
+## 7. Git・バージョン管理
+### Gitとは
+**Gitは、ソースコードの変更履歴を記録・管理するシステムです。**
+**なぜ必要か：**
+- **履歴管理**: いつ誰が何を変更したかが記録される
+- **協働開発**: 複数人が同じプロジェクトで作業できる
+- **ロールバック**: 間違った変更を取り消せる
+### 基本的なGitコマンド
+```bash
+# 変更をステージング（記録対象に追加）
+git add filename.py
+# 変更をコミット（履歴に記録）
+git commit -m "検索ロジックを改善"
+# リモート（サーバー）にアップロード
+git push
+# 他人の変更を取得
+git pull
+# 現在のステータス確認
+git status
+# 変更履歴を確認
+git log
+```
+### ブランチ
+**ブランチは、並行して複数の開発を進める仕組みです。**
+```
+main（本番用）
+  ├── develop（開発用）
+  │   ├── feature/search-improvement（新機能）
+  │   └── bugfix/api-error（バグ修正）
+  └── ...
+```
+**ワークフロー例：**
+```bash
+# メインから新しいブランチを作成
+git checkout -b feature/my-feature
+# 変更を加える
+# ...
+# 変更をコミット
+git commit -m "新機能を追加"
+# リモートに反映
+git push origin feature/my-feature
+# Pull Request を作成 → 他のメンバーがレビュー → マージ
+```
+### このプロジェクトのバージョン管理
+```
+GitHub リポジトリ: chibafes-dev/chibafes-website-api-v2
+ブランチ: main（本番用）, develop（開発用）
+```
+**セキュリティ注意：**
+- `.env` や API キーは `.gitignore` に登録し、Git に含めない
+- 秘密情報は GitHub Secrets に保存
+---
+## まとめ
+このドキュメントで説明した概念：
+| 概念 | 役割 | このプロジェクトでの使用 |
+|------|------|------------------------|
+| Python | プログラミング言語 | 全体のコード |
+| FastAPI | Web API フレームワーク | `/api/...` エンドポイント |
+| MySQL | データベース | 企画情報を保存 |
+| JSON | データ形式 | API のやり取り、設定ファイル |
+| 環境変数 | 設定管理 | DB接続情報、APIキー等 |
+| Docker | 環境仮想化 | 本番環境へのデプロイ |
+| Git | バージョン管理 | ソースコード管理 |
+各項目の詳細は、同梱の「システムガイド.md」を参照してください。

docs/改善提案.md ADDED Viewed

	@@ -0,0 +1,825 @@

+# コードベース改善提案書
+**作成日**: 2025年12月11日
+**対象システム**: ChibaFes Website API v2
+**対象読者**: 技術リーダー、アーキテクト、開発チーム
+**スコープ**: 検索ロジック、コード品質、致命的欠陥の検出
+---
+## 概要
+本ドキュメントでは、現在のコードベースの包括的な分析を行い、改善が有効な領域を特定しました。以下の3つのカテゴリに分類しています。
+1. **致命的欠陥・セキュリティ問題**: 即座に対応すべき問題
+2. **検索ロジック改善**: 精度や効率の向上につながる改善
+3. **コード品質改善**: 保守性、リーダビリティ、テスト容易性の向上
+---
+## 1. 致命的欠陥・セキュリティ問題
+### 1.1 コネクションプール管理の例外ハンドリング不足
+**ファイル**: `app/db/session.py`
+**重要度**: 🔴 高
+**現在の実装**:
+```python
+def acquire(self) -> Connection:
+    while True:
+        try:
+            conn = self._available.get_nowait()
+        except Empty:
+            with self._lock:
+                if self._total_created < self._max_size:
+                    conn = self._create_connection()
+                    self._total_created += 1
+                    return conn
+            conn = self._available.get()
+        if conn.open:
+            conn.ping(reconnect=True)  # ← 例外ハンドリングがない
+            conn.autocommit(True)
+            return conn
+        self._discard_connection(conn)
+```
+**具体的な欠陥**:
+1. `ping(reconnect=True)` が例外を発生させた場合、呼び出し元の `get_connection()` でキャッチされず、500エラーが発生する可能性があります。
+2. 接続失敗時に不要なスタックトレースが出力されます。
+3. コネクションプール内のコネクションが「壊れた状態」のままになる可能性があります。
+**推奨改善**:
+```python
+def acquire(self) -> Connection:
+    while True:
+        try:
+            conn = self._available.get_nowait()
+        except Empty:
+            with self._lock:
+                if self._total_created < self._max_size:
+                    conn = self._create_connection()
+                    self._total_created += 1
+                    return conn
+            conn = self._available.get()
+        if conn.open:
+            try:
+                conn.ping(reconnect=True)
+                conn.autocommit(True)
+                return conn
+            except Exception as e:
+                log.warning(f"Stale connection detected and discarded: {e}")
+                self._discard_connection(conn)
+### 1.2 APIキー認証のロジック明確化
+**ファイル**: `app/main.py`
+**重要度**: 🟠 中（機能的には正しいが可読性が低い）
+**現在の実装**:
+```python
+API_SECRET_KEY = os.getenv("API_SECRET_KEY")
+async def get_api_key(key: str = Security(api_key_header)):
+    if not API_SECRET_KEY or key != API_SECRET_KEY:
+        raise HTTPException(status_code=403, detail="Could not validate credentials.")
+    return key
+```
+**具体的な問題**:
+1. `not API_SECRET_KEY` と `key != API_SECRET_KEY` の組み合わせが、コードの意図を曖昧にしています。
+2. セキュリティコードレビューで指摘される可能性が高い（ベストプラクティスに準拠していない）。
+3. 環境変数が未設定の場合、初期化時ではなく、リクエスト時に発見される（デバッグが困難）。
+**実装は機能的には正しい**（すべてのシナリオで期待通り動作）が、可読性と保守性が低い状態です。
+**推奨改善**:
+```python
+API_SECRET_KEY = os.getenv("API_SECRET_KEY")
+if not API_SECRET_KEY:
+    raise RuntimeError("API_SECRET_KEY environment variable is not set")
+async def get_api_key(key: str = Security(api_key_header)):
+    if key != API_SECRET_KEY:
+        raise HTTPException(status_code=403, detail="Invalid API key")
+    return key
+```
+**改善効果**:
+- 初期化時の明示的なチェック（起動時にエラーが分かる）
+- 認証ロジックの単純化（`if key != API_SECRET_KEY` のみに）
+- セキュリティベストプラクティスに準拠
+**影響範囲**: 認証が必要なすべてのエンドポイント（`/api/projects`, `/api/search`, `/tasks/update` など）
+```python
+API_SECRET_KEY = os.getenv("API_SECRET_KEY")
+if not API_SECRET_KEY:
+    raise RuntimeError("API_SECRET_KEY environment variable is not set")
+async def get_api_key(key: str = Security(api_key_header)):
+    if key != API_SECRET_KEY:
+        raise HTTPException(status_code=403, detail="Invalid API key")
+    return key
+```
+**影響範囲**: 認証が必要なすべてのエンドポイント（`/api/projects`, `/api/search`, `/tasks/update` など）
+---
+### 1.3 例外ハンドリングの不完全性
+**ファイ��**: `app/repositories/projects_repository.py` 他
+**重要度**: 🟠 中
+**問題内容**:
+```python
+def _transform_row(self, row: Dict[str, Any]) -> Project:
+    def _resolve_text_from_updates(updates_key: str) -> str | None:
+        updates = sorted(
+            _coerce_dict_list(row.get(updates_key)),
+            key=lambda item: str(item.get("createdAt") or ""),
+            reverse=True,
+        )
+        # ... 複数の try-except なし処理
+        for update in updates:
+            status = update.get("updateStatus")
+            normalized_status = (
+                status.strip().upper() if isinstance(status, str) else None  # ← AttributeError可能性
+            )
+```
+**具体的な欠陥**:
+1. `status.strip()` で `AttributeError` が発生する可能性（万が一 `status` が予期しない型の場合）
+2. JSON パース失敗時の黙殺（`except json.JSONDecodeError: return []`）が想定外のデータを見落とさせる可能性
+**推奨改善**:
+```python
+def _resolve_text_from_updates(updates_key: str) -> str | None:
+    try:
+        updates = sorted(
+            _coerce_dict_list(row.get(updates_key)),
+            key=lambda item: str(item.get("createdAt") or ""),
+            reverse=True,
+        )
+    except Exception as e:
+        log.warning(f"Failed to sort updates for {updates_key}: {e}")
+        return None
+    for update in updates:
+        try:
+            status = update.get("updateStatus")
+            if not isinstance(status, str):
+                continue
+            normalized_status = status.strip().upper()
+            # ...
+        except Exception as e:
+            log.warning(f"Error processing update: {e}")
+            continue
+```
+**影響範囲**: プロジェクト詳細データの取得時に予期しないエラーで API がクラッシュする可能性
+---
+## 2. 検索ロジック改善
+### 2.1 検索フィルタリング戦略の複雑性と曖昧性
+**ファイル**: `app/search/engine.py` (lines 540-615)
+**重要度**: 🟠 中
+**問題内容**:
+現在の検索フィルタリングロジックは2段階で実施されています：
+```python
+# Stage 1: Filtering
+fused_cut = max(self.cfg.fused_min, top * self.cfg.fused_rel_top_ratio)
+keep = (
+    (bm25 >= self.cfg.bm25_min)
+    | (ws_filter >= self.cfg.word_sim_min)
+    | (score_with_boost >= self.cfg.fused_min)
+) & (score_with_boost >= fused_cut)
+# Stage 2: Fallback (結果が0の場合)
+if not selected_idx_set:
+    keep2 = (
+        (bm25 >= self.cfg.bm25_min)
+        | (ws_filter >= self.cfg.word_sim_min)
+        | (score_with_boost >= self.cfg.fused_min)
+    )
+```
+**具体的な問題**:
+1. **論理的矛盾**: `keep2` は `keep` とほぼ同じで、`fused_cut` チェックがないだけです。この相違を明確に文書化する必要があります。
+2. **ハードコードされた戦略**: Fallback 戦略が1段階のみで、より段階的なエスカレーションが考慮されていません。
+3. **テスト不可**: この複雑な条件分岐のカバレッジテストが困難です。
+**推奨改善**:
+```python
+class FilterStrategy(Enum):
+    STRICT = 1      # 厳密: fused_cut を適用
+    MODERATE = 2    # 中程度: fused_min のみ
+    RELAXED = 3     # 緩和: 個別スコアのみ
+def _apply_filter(
+    self,
+    bm25: np.ndarray,
+    ws_filter: np.ndarray,
+    score_with_boost: np.ndarray,
+    strategy: FilterStrategy = FilterStrategy.STRICT,
+) -> np.ndarray:
+    """フィルタリング戦略を統一的に適用"""
+    if strategy == FilterStrategy.STRICT:
+        top = float(np.max(score_with_boost)) if score_with_boost.size > 0 else 0.0
+        fused_cut = max(
+            self.cfg.fused_min,
+            top * self.cfg.fused_rel_top_ratio if top > 0 else 0.0
+        )
+        return (
+            (bm25 >= self.cfg.bm25_min)
+            | (ws_filter >= self.cfg.word_sim_min)
+            | (score_with_boost >= self.cfg.fused_min)
+        ) & (score_with_boost >= fused_cut)
+    elif strategy == FilterStrategy.MODERATE:
+        return (
+            (bm25 >= self.cfg.bm25_min)
+            | (ws_filter >= self.cfg.word_sim_min)
+            | (score_with_boost >= self.cfg.fused_min)
+        )
+    elif strategy == FilterStrategy.RELAXED:
+        return (bm25 > 0) | (ws_filter > 0) | (score_with_boost > 0)
+    return np.zeros_like(score_with_boost, dtype=bool)
+# 使用例
+selected_idx = self._select_results(keep, order, selected_idx_set, substring_idx_set)
+if not selected_idx and len(order) > 0:
+    log.info("Fallback: Relaxing filter strategy")
+    keep_moderate = self._apply_filter(bm25, ws_filter, score_with_boost, FilterStrategy.MODERATE)
+    selected_idx = self._select_results(keep_moderate, order, selected_idx_set, substring_idx_set)
+```
+**改善効果**:
+- テスト容易性向上
+- ロジックの意図が明確化
+- 新しいフィルタリング戦略の追加が容易に
+---
+### 2.2 ��ブストリングマッチと BM25F の重複チェック
+**ファイル**: `app/search/engine.py` (lines 500-530)
+**重要度**: 🟡 中
+**問題内容**:
+```python
+substring_hits = self._substring_match_project_ids(query)  # クエリのサブストリングマッチ
+# ...
+keep = (
+    (bm25 >= self.cfg.bm25_min)
+    | (ws_filter >= self.cfg.word_sim_min)
+    | (score_with_boost >= self.cfg.fused_min)
+) & (score_with_boost >= fused_cut)
+if substring_idx_set:
+    keep = keep | substring_mask  # ← サブストリング結果を別途追加
+```
+**具体的な問題**:
+1. **冗長性**: サブストリングマッチでヒットしたプロジェクトは、既に BM25F でスコアリングされています。これらを別途 `substring_mask` で強制包含するのは、スコアリングの一貫性を損なう可能性があります。
+2. **順序への影響**: 名前一致のプロジェクトが、スコアに関係なく結果に混在します。
+3. **重複**: 実際には、サブストリングマッチのプロジェクトは多くの場合 `keep` に既に含まれている可能性が高いです。
+**推奨改善**:
+```python
+def _search(self, query: str, debug: bool = False):
+    # ...
+    # サブストリングマッチをスコアブースト として活用
+    substring_hits = self._substring_match_project_ids(query)
+    substring_boost = np.zeros((len(self.projects),), dtype=np.float32)
+    if substring_hits:
+        for pid in substring_hits:
+            idx = self.project_idx.get(pid)
+            if idx is not None:
+                # サブストリングマッチは固定ボーナス（例: 0.3）を追加
+                substring_boost[idx] = 0.3  # 設定可能にしてもよい
+    # 最終スコアにサブストリングボーナスを統合
+    final_scores = fused_rerank + boost + substring_boost
+    # フィルタリングは統一的に
+    keep = (
+        (bm25 >= self.cfg.bm25_min)
+        | (ws_filter >= self.cfg.word_sim_min)
+        | (score_with_boost >= self.cfg.fused_min)
+    ) & (score_with_boost >= fused_cut)
+    # サブストリングマッチは結果にボーナスを与えるが、絶対条件ではない
+    # （スコアベースのランキングを保証する）
+```
+**改善効果**:
+- スコアリングの一貫性向上
+- サブストリングマッチと通常検索の相互作用が明確に
+- デバッグ情報が直感的に
+---
+### 2.3 IDF 重み付けが不完全な実装
+**ファイル**: `app/search/engine.py` (lines 370-450, top-k pooling)
+**重要度**: 🟡 中
+**問題内容**:
+```python
+def _word_sim_scores_topk(self, terms: List[str]) -> Optional[np.ndarray]:
+    # Query term vectors with IDF weighting
+    vecs = []
+    weights = []
+    for t in terms:
+        v, oov = self._get_token_vector(t)
+        if v is None:
+            continue
+        w = float(self.idf.get(t, 0.0))
+        if oov:
+            w *= float(self.cfg.query_subword_oov_weight)  # OOV: 0.5 倍など
+        if w <= 0:
+            continue
+        vecs.append(v)
+        weights.append(w)
+    # ...
+    M = Vd @ Vq.T  # Td x Tq
+    if Wq.size:
+        M = M * Wq[None, :]  # ← IDF 重み付けだが正規化なし
+```
+**具体的な問題**:
+1. **重み付けの不正規化**: `M = M * Wq` で単純に乗算していますが、これにより：
+   - 一般的な単語のクエリは高い IDF ウェイトを持ち、相互影響を高めます
+   - マイナーな単語は低い IDF で、その寄与度が小さくなります
+   - この非対称性は意図的なのか、バグなのか不明確です
+2. **スコア解釈の困難さ**: IDF で加重されたスコアは、元のコサイン類似度 `[0, 1]` の範囲を逸脱します。
+**推奨改善**:
+```python
+def _word_sim_scores_topk(self, terms: List[str]) -> Optional[np.ndarray]:
+    # ...
+    vecs = []
+    weights = []
+    for t in terms:
+        v, oov = self._get_token_vector(t)
+        if v is None:
+            continue
+        w = float(self.idf.get(t, 0.0))
+        if oov:
+            w *= float(self.cfg.query_subword_oov_weight)
+        if w <= 0:
+            continue
+        vecs.append(v)
+        weights.append(w)
+    if not vecs:
+        return None
+    V = np.stack(vecs).astype(np.float32)
+    W = np.asarray(weights, dtype=np.float32)
+    # IDF 重み付けベクトルの正規化オプション
+    W_normalized = W / (np.sum(W) + 1e-8)  # または L2 正規化も検討
+    # ...
+    if Wq.size:
+        M = M * Wq_normalized[None, :]  # 正規化された重みを使用
+```
+**改善効果**:
+- スコアの解釈が直感的に
+- 異なる長さのクエリでの挙動が一貫的に
+- デバッグが容易に
+---
+### 2.4 ペアアベレッジモードのデフォルト値の妥当性
+**ファイル**: `app/search/engine.py` (lines 477-500)
+**重要度**: 🟡 低～中
+**問題内容**:
+```python
+def _word_sim_scores_pairavg(self, terms: List[str]) -> Optional[np.ndarray]:
+    # Build query term vectors (no weighting for pair-avg, simple mean over all pairs)
+    vecs = []
+    for t in terms:
+        v, _ = self._get_token_vector(t)  # ← OOV フラグを無視！
+        if v is None:
+            continue
+        vecs.append(v)
+```
+**具体的な問題**:
+1. **OOV ベクトルが同等に扱われる**: fastText から生成されたサブワードベクトルと、学習済みベクトルが同じウェイトで扱われます。
+2. **IDF 重み付けが完全に無視される**: これは意図的な設計なのか、実装ミスなのか不明確です。
+3. **設定オプションなし**: ペアアベレッジのウェイト戦略をコンフィグで調整できません。
+**推奨改善**:
+```python
+# search_model.json に以下を追加
+"word_sim": {
+    "enable": true,
+    "alpha": 0.5,
+    "topk_k": 3,
+    "rerank": "pair_avg",
+    "pairavg_weighting": "none"  # none | idf | oov_penalty
+}
+def _word_sim_scores_pairavg(self, terms: List[str]) -> Optional[np.ndarray]:
+    weighting_mode = self.cfg.word_sim_pairavg_weighting
+    vecs = []
+    weights = []
+    for t in terms:
+        v, oov = self._get_token_vector(t)
+        if v is None:
+            continue
+        if weighting_mode == "idf":
+            w = float(self.idf.get(t, 0.0))
+        elif weighting_mode == "oov_penalty":
+            w = 0.5 if oov else 1.0
+        else:
+            w = 1.0
+        vecs.append(v)
+        weights.append(w)
+    if not vecs:
+        return None
+    Vq = np.stack(vecs).astype(np.float32)
+    W = np.asarray(weights, dtype=np.float32)
+    # ... 後続処理
+```
+**改善効果**:
+- OOV ベクトルの扱いが一貫的に
+- テスト可能な設定オプションが増加
+- より柔軟な検索戦略が可能に
+---
+## 3. コード品質改善
+### 3.1 設定管理の分散化
+**ファイル**: `config/search_model.json`, `app/search/engine.py`
+**重要度**: 🟡 中
+**問題内容**:
+```python
+# app/search/engine.py で SearchConfig を動的に構築
+self.cfg = SearchConfig(
+    target_pos_l1=search("target_pos_l1"),
+    target_fields=search("target_fields"),
+    # ... 20+ フィールド
+    fused_rel_top_ratio=float(search("filter.fused_rel_top_ratio", 0.5)),
+)
+```
+**具体的な問題**:
+1. **マジックナンバーが散在**: デフォルト値がコード内にハードコード（例：`0.5`）されており、統一的に管理されていません。
+2. **設定の完全性チェックなし**: JSON から値が欠落している場合のハンドリングが不一貫（時には例外、時にはデフォルト）です。
+3. **型安全性なし**: すべての値を手動で `float()` や `int()` で変換しており、型エラーの可能性があります。
+**推奨改善**:
+```python
+# schemas/search_config.py を新規作成
+from pydantic import BaseModel, Field
+class BM25Config(BaseModel):
+    k1: float = Field(default=1.5, ge=0)
+    b: float = Field(default=0.75, ge=0, le=1)
+    field_weights: Dict[str, float] = Field(default_factory=dict)
+class WordSimConfig(BaseModel):
+    enable: bool = True
+    alpha: float = Field(default=0.5, ge=0, le=1)
+    topk_k: int = Field(default=3, ge=1)
+    rerank: str = "pair_avg"  # or "topk"
+    pairavg_weighting: str = "none"  # idf, oov_penalty, none
+class FilterConfig(BaseModel):
+    min_results: int = Field(default=20, ge=1)
+    max_results: int = Field(default=50, ge=1)
+    bm25_min: float = Field(default=0.1, ge=0)
+    word_sim_min: float = Field(default=0.35, ge=0, le=1)
+    fused_min: float = Field(default=0.12, ge=0)
+    fused_rel_top_ratio: float = Field(default=0.5, ge=0, le=1)
+class SearchConfig(BaseModel):
+    target_pos_l1: List[str]
+    target_fields: List[str]
+    bm25f: BM25Config
+    word_sim: WordSimConfig
+    synonyms: Dict[str, Any]
+    filter: FilterConfig
+    # ... その他
+# 使用時
+config = SearchConfig.model_validate_json(open("config/search_model.json").read())
+```
+**改善効果**:
+- 設定の型安全性が保証される
+- バリデーション が自動化される
+- デフォルト値が一元管理される
+---
+### 3.2 テスト戦略の欠如
+**ファイル**: リポジトリ全体（テストファイルなし）
+**重要度**: 🟡 中
+**問題内容**:
+```
+テストファイルが見当たりません。以下のコンポーネントのテストが必須です：
+- SearchEngine の各スコアリング関数
+- ProjectsRepository のデータ変換ロジック
+- APIエンドポイントの動作
+- フィルタリング戦略
+```
+**推奨改善**:
+```python
+# tests/test_search_engine.py
+import pytest
+import numpy as np
+from app.search.engine import SearchEngine
+class TestBM25FScores:
+    def setup_method(self):
+        self.engine = SearchEngine()
+        self.engine.initialize()
+    def test_bm25f_scores_empty_terms(self):
+        scores = self.engine._bm25f_scores([])
+        assert np.all(scores == 0.0)
+    def test_bm25f_scores_single_term(self):
+        scores = self.engine._bm25f_scores(["テスト"])
+        assert scores.shape == (len(self.engine.projects),)
+        assert np.all(scores >= 0.0)
+    def test_bm25f_idempotence(self):
+        scores1 = self.engine._bm25f_scores(["テスト", "企画"])
+        scores2 = self.engine._bm25f_scores(["テスト", "企画"])
+        np.testing.assert_array_equal(scores1, scores2)
+class TestFilterStrategies:
+    def test_filter_strategy_consistency(self):
+        # STRICT > MODERATE > RELAXED
+        # つまり、同じ結果セットで RELAXED の方が多くマッチする
+        pass
+# tests/test_api.py
+import pytest
+from fastapi.testclient import TestClient
+from app.main import app
+client = TestClient(app)
+def test_health_check():
+    response = client.get("/api/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"
+def test_search_without_api_key():
+    response = client.post("/api/search", json={"query": "test"})
+    assert response.status_code == 403
+def test_search_with_api_key():
+    response = client.post(
+        "/api/search",
+        json={"query": "test"},
+        headers={"X-API-KEY": "test-key"}  # テスト用キー
+    )
+    assert response.status_code in (200, 400)  # 検索は成功、クエリが空なら 400
+```
+**改善効果**:
+- リグレッション防止
+- リファクタリング時の信頼度向上
+- 動作の仕様書として機能
+---
+### 3.3 ロギングの戦略的活用不足
+**ファイル**: `app/search/engine.py`, `app/main.py` 他
+**重要度**: 🟡 低～中
+**問題内容**:
+```python
+# ロギングが少なく、デバッグが困難
+def _bm25f_scores(self, terms: List[str]) -> np.ndarray:
+    # ... 長いアルゴリズム処理
+    # ログなし
+    return scores
+# 一方で不要なログがある
+log.info(f"Project summaries fetched: {len(summaries_payload)} items")
+```
+**具体的な問題**:
+1. **パフォーマンスデバッグの困難さ**: どの処理が遅いのか不明確
+2. **エラー追跡の困難さ**: 検索がなぜ失敗したのか、スコアが低いのか不明確
+3. **本番環境の可視性低下**: PostHog でログを追跡していますが、内部的なキャッシュ状態などが見えません
+**推奨改善**:
+```python
+import logging
+from dataclasses import dataclass
+from typing import Optional
+@dataclass
+class SearchMetrics:
+    query: str
+    terms_count: int
+    documents_count: int
+    bm25_max: float
+    ws_filter_max: float
+    final_results_count: int
+    fallback_applied: bool
+    elapsed_ms: float
+class SearchEngine:
+    def search(self, query: str, debug: bool = False) -> ...:
+        import time
+        start = time.time()
+        terms = self._tokenize(query)
+        log.debug(f"Query tokenized: {len(terms)} terms from '{query}'")
+        # ... スコアリング処理
+        bm25 = self._bm25f_scores(terms)
+        log.debug(f"BM25F scores: min={bm25.min():.3f}, max={bm25.max():.3f}, "
+                  f"mean={bm25.mean():.3f}")
+        # ... 検索処理続行
+        # メトリクス記録
+        metrics = SearchMetrics(
+            query=query,
+            terms_count=len(terms),
+            documents_count=len(self.projects),
+            bm25_max=float(bm25.max()),
+            ws_filter_max=float(ws_filter.max()) if ws_filter is not None else 0.0,
+            final_results_count=len(pairs),
+            fallback_applied=fallback_was_applied,
+            elapsed_ms=(time.time() - start) * 1000,
+        )
+        log.info(f"Search completed: {len(pairs)} results in {metrics.elapsed_ms:.1f}ms")
+        if posthog and GET_LOGS:
+            posthog.capture(event="search_metrics", properties=vars(metrics))
+        return pairs
+```
+**改善効果**:
+- パフォーマンス最適化の根拠が得られる
+- 検索品質の測定が可能に
+- ユーザー行動の詳細な分析が可能に
+---
+### 3.4 型注釈の不完全性
+**ファイル**: `app/search/engine.py` 他
+**重要度**: 🟡 低
+**問題内容**:
+```python
+def _bm25f_scores(self, terms: List[str]) -> np.ndarray:
+    # np.ndarray の形状や dtype が未指定
+    pass
+def search(
+    self,
+    query: str,
+    debug: bool = False,
+) -> List[Tuple[str, float]] | Tuple[List[Tuple[str, float]], Dict[str, Any]]:
+    # Union 型が複雑で読みにくい
+    pass
+```
+**推奨改善**:
+```python
+from typing import TypeAlias, overload
+import numpy as np
+from numpy.typing import NDArray
+ScoreArray: TypeAlias = NDArray[np.float32]
+SearchResult: TypeAlias = List[Tuple[str, float]]
+DebugInfo: TypeAlias = Dict[str, Any]
+class SearchEngine:
+    def _bm25f_scores(self, terms: List[str]) -> ScoreArray:
+        """
+        BM25F スコアを計算
+        Returns:
+            Shape (n_documents,) の float32 配列
+        """
+        return np.zeros((len(self.tf_token_docs),), dtype=np.float32)
+    @overload
+    def search(self, query: str, debug: bool = False) -> SearchResult:
+        ...
+    @overload
+    def search(self, query: str, debug: bool = True) -> Tuple[SearchResult, DebugInfo]:
+        ...
+    def search(self, query: str, debug: bool = False):
+        # ...
+        if debug:
+            return pairs, debug_info
+        return pairs
+```
+**改善効果**:
+- IDE のオートコンプリート精度向上
+- 型チェッカー（mypy）による自動検証可能に
+- ドキュメント性が向上
+---
+## 4. 推奨実装優先度
+### フェーズ 1（即座 - 数時間）
+1. ✅ コネクションプール管理の例外ハンドリング追加
+2. ✅ APIキー認証のロジック明確化（環境変数チェック）
+### フェーズ 2（短期：1-2週間）
+1. 例外ハンドリングの強化（ロギング付き）
+2. フィルタリング戦略の統一（FilterStrategy 導入）
+3. 設定管理の Pydantic 化
+### フェーズ 3（中期：1-2ヶ月）
+1. テストスイートの構築（pytest）
+2. IDF 重み付けの正規化処理
+3. サブストリングマッチの統合改善
+### フェーズ 4（長期：随時）
+1. 型注釈の完全化
+2. パフォーマンス最適化（ベクトル計算の GPU 化など）
+3. 検索ロジックの A/B テスト環境構築
+---
+## 5. まとめ
+本コードベースは**機能的には堅牢**ですが、以下の領域で改善が有効です：
+| カテゴリ | 優先度 | 影響度 | 実装時間 |
+|---------|--------|--------|---------|
+| セキュリティ・堅牢性 | 🔴 高 | 高い | 数時間 |
+| エラーハンドリング | 🟠 中 | 中程度 | 1-2日 |
+| 検索ロジック（フィルタリング） | 🟡 中 | 中程度 | 1週間 |
+| テスト戦略 | 🟡 中 | 高い（長期） | 2週間+ |
+| ロギング | 🟡 低～中 | 低～中 | 3-5日 |
+| 型安全性 | 🟡 低 | 低い | 1-2日 |
+**即座に対応すべき項目**は**フェーズ 1** の 2 つです。これらを解決することで、API のセキュリティと安定性が大幅に向上します。
+### 実装推奨工程
+1. **Phase 1 実装**（本日中）
+   - コネクション例外ハンドリング追加
+   - API_SECRET_KEY チェック追加
+   - デプロイして検証
+2. **Phase 2 実装**（1-2週間以内）
+   - 例外ハンドリング強化
+   - フィルタリング戦略統一
+3. **Phase 3 以降**（優先度と人員に応じて）
+   - テストスイート構築
+   - 検索ロジック最適化

docs/検索アルゴリズム詳説.md ADDED Viewed

	@@ -0,0 +1,520 @@

+# 検索アルゴリズム詳説：数学的理解
+**作成日**: 2025年12月11日
+**対象**: アルゴリズムの数学的背景に興味のある学生
+**言語**: 日本語
+**前提知識**: 「システムガイド.md」を読了していること
+---
+このドキュメントは、このプロジェクトで使われている検索アルゴリズムの数学的な背景を説明するものです。「システムガイド.md」の「4. 検索システムの仕組み」で紹介した概念を、より厳密に解説します。
+数学が得意でない方は、概念的な説明だけを読んで、数式は参考程度で構いません。
+## 目次
+1. [BM25F（単語一致の強さ）](#1-bm25f単語一致の強さ)
+2. [TF-IDF](#2-tf-idf)
+3. [単語ベクトルとコサイン類似度](#3-単語ベクトルとコサイン類似度)
+4. [このプロジェクトでのスコア統合](#4-このプロジェクトでのスコア統合)
+---
+## 1. BM25F（単語一致の強さ）
+### 概要
+BM25Fは、情報検索の分野で最も実績のあるスコアリング関数です。Fは「Field」を意味し、複数のフィールド（企画名、説明文など）を扱う場合に拡張されています。
+### BM25 の基本形
+$$\text{BM25}(q, d) = \sum_{i=1}^{|q|} \text{IDF}(q_i) \cdot \frac{(k_1 + 1) \cdot \text{TF}(q_i, d)}{k_1 \cdot (1 - b + b \cdot |d| / \text{avgdl}) + \text{TF}(q_i, d)}$$
+テキスト形式：
+```
+BM25(q, d) = Σ_{i=1}^{|q|} IDF(q_i) · (k1 + 1) · TF(q_i, d) / (k1 · (1 - b + b · |d| / avgdl) + TF(q_i, d))
+```
+各記号の意味：
+- $q$ = クエリ（検索語）
+- $d$ = 文書（企画データ）
+- $q_i$ = クエリの i 番目の単語
+- $|q|$ = クエリの単語数
+- $TF(q_i, d)$ = 単語 $q_i$ がドキュメント $d$ に出現した回数
+- $|d|$ = 文書の長さ（単語数）
+- $avgdl$ = 全文書の平均長さ
+- $k1$, $b$ = ハイパーパラメータ
+- $IDF(q_i)$ = 逆文書頻度
+### IDF（Inverse Document Frequency）
+```
+IDF(w) = log( (N - df(w) + 0.5) / (df(w) + 0.5) )
+```
+- $N$ = 全文書数
+- $df(w)$ = 単語 $w$ が出現する文書の数
+**直感的な意味：**
+- $df(w)$ が小さい（珍しい単語）→ IDF が大きい → スコアへの寄与が大きい
+- $df(w)$ が大きい（よくある単語）→ IDF が小さい → スコアへの寄与が小さい
+**例：**
+企画が100個あるとき
+- 「食べ物」は80個の企画に出現 → $df = 80$ → IDF = $\log(20.5/80.5) \approx -1.37$ (低い)
+- 「生ビール」は3個の企画に出現 → $df = 3$ → IDF = $\log(97.5/3.5) \approx 3.43$ (高い)
+### BM25F への拡張（複数フィールド対応）
+複数のフィールド（企画名、説明文など）がある場合、各フィールドごとに TF を計算してから、重みを付けます。
+$$\text{BM25F}(q, d) = \sum_{i=1}^{|q|} \text{IDF}(q_i) \cdot \frac{\sum_{f} w_f \cdot (k_1 + 1) \cdot \text{TF}_f(q_i, d)}{\sum_{f} w_f \cdot (\text{TF}_f(q_i, d) + k_1 \cdot (1 - b + b \cdot \text{len}_f / \text{avglen}_f))}$$
+**注意:** このプロジェクトの実装では、分子と分母にそれぞれフィールドごとの加重合計を計算してから、統合スコアを求めます。これは複数フィールドの BM25 における一般的なアプローチです。
+テキスト形式：
+```
+BM25F(q, d) = Σ_{i=1}^{|q|} IDF(q_i) ·
+              (Σ_f w_f · TF_f · (k1 + 1)) /
+              (Σ_f w_f · (TF_f + k1 · (1 - b + b · len_f / avglen_f)))
+```
+- $f$ = フィールド（例：name, description）
+- $w_f$ = フィールド $f$ の重み（例：name は 2.0、description は 1.0）
+- $TF_f(q_i, d)$ = 単語 $q_i$ がフィールド $f$ に出現した回数
+- $len_f$ = フィールド $f$ の長さ
+- $avglen_f$ = フィールド $f$ の全文書平均長さ
+### パラメータの意味と調整
+#### $k1$（デフォルト 1.2）
+TFの影響度を制御します。
+- $k1$ が大きい → TF の差がスコアに大きく反映（繰り返しが重要）
+- $k1$ が小さい → TF の差がスコアに反映されにくい
+#### $b$（デフォルト 0.75）
+文書長さの正規化度合いを制御します。
+- $b = 0$ → 文書長さを無視
+- $b = 1$ → 文書長さを完全に考慮
+- $b = 0.75$ → 中程度に考慮（推奨値）
+**例：** 企画説明が極端に長い場合、$b$ を小さくすると、長さの影響を減らせます。
+#### フィールド重み
+```json
+{
+  "name": 2.0,
+  "circleName": 1.5,
+  "description": 1.0
+}
+```
+企画名に出現する単語は、説明文に出現する単語の2倍の価値があるということです。
+### このプロジェクトの設定値
+```json
+{
+  "bm25f": {
+    "k1": 1.2,
+    "b": 0.75,
+    "field_weights": {
+      "name": 2.0,
+      "circleName": 1.5,
+      "circleNameKana": 0.6,
+      "description": 1.0,
+      "prSummary": 1.0,
+      "prDetail": 0.8
+    }
+  }
+}
+```
+---
+## 2. TF-IDF
+### 概要
+TF-IDF は、単語の重要度を計算する最も基本的な手法です。
+```
+TF-IDF(w, d) = TF(w, d) · IDF(w)
+```
+### TF（Term Frequency）
+単語 $w$ がドキュメント $d$ に出現した回数。通常は正規化されます。
+#### 単純な TF
+```
+TF(w, d) = 単語 w が d に出現した回数
+```
+#### 正規化 TF
+```
+TF(w, d) = (単語 w が d に出現した回数) / (d の総単語数)
+```
+#### 対数正規化 TF（BM25で使用）
+```
+TF(w, d) = log(1 + (単語 w が d に出現した回数))
+```
+**利点：** 出現回数が多いほどスコアが上がるが、100回と101回の差は1回と2回ほど大きくない（飽和性）
+### IDF（Inverse Document Frequency）
+前述の「1. BM25F」を参照。
+### TF-IDF の解釈
+```
+TF-IDF = 「その単語がその文書にどれだけ重要か」
+        = 「珍しく」かつ「繰り返し出現する」単語ほど重要
+```
+**例：**
+クエリ：「カレー 販売」、 企画A：「カレー販売｜カレーはインドの料理です。当団体が作るカレーは...（以下詳細）」
+- 「カレー」: TF(カレー, A) 高い、IDF(カレー) 中程度 → TF-IDF 高い
+- 「販売」: TF(販売, A) 低い、IDF(販売) 高い → TF-IDF 中程度
+- 「料理」: TF(料理, A) 中程度、IDF(料理) 中程度 → TF-IDF 中程度
+---
+## 3. 単語ベクトルとコサイン類似度
+### 単語ベクトルとは
+単語を「意味を反映した高次元ベクトル」として表現する手法です。
+```
+"カレー" → [0.12, -0.34, 0.67, ..., 0.23]  (例：300次元)
+"ラーメン" → [0.11, -0.35, 0.68, ..., 0.24]
+```
+**重要な性質：** 意味が近い単語のベクトルは、空間上で近い位置にあります。
+### fastText
+このプロジェクトで使われているfastTextは、以下の特徴を持っています：
+1. **事前学習済み**: 大量の日本語テキストから学習済みのベクトルを使用
+2. **部分語情報を活用**: 未知語（コーパスに出現しない単語）でも推測できる
+3. **300次元**: 各単語は300次元のベクトルで表現
+### コサイン類似度
+2つのベクトルの「角度」から、意味的な近さを計算します。
+```
+cos_sim(v1, v2) = (v1 · v2) / (||v1|| · ||v2||)
+```
+- $v_1 \cdot v_2$ = 内積（ドット積）
+- $||v_1||$ = ベクトル $v_1$ のノルム（長さ）
+### 内積の計算
+```
+v1 = [a1, a2, ..., an]
+v2 = [b1, b2, ..., bn]
+v1 · v2 = a1*b1 + a2*b2 + ... + an*bn
+```
+### ノルム（ベクトルの長さ）
+```
+||v|| = sqrt(a1^2 + a2^2 + ... + an^2)
+```
+### コサイン類似度の範囲
+```
+-1 ≤ cos_sim(v1, v2) ≤ 1
+```
+- 1に近い → 同じ方向（意味が非常に近い）
+- 0に近い → 直交（無関係）
+- -1に近い → 反対方向（反対の意味）
+**例：**
+```
+cos_sim("カレー", "スープ") ≈ 0.85  （近い）
+cos_sim("カレー", "本棚") ≈ 0.10   （遠い）
+```
+### Python での計算
+```python
+import numpy as np
+# ベクトルを正規化（長さを1にする）
+v1 = np.array([0.12, -0.34, 0.67])
+v2 = np.array([0.11, -0.35, 0.68])
+# L2 正規化
+v1_norm = v1 / np.linalg.norm(v1)
+v2_norm = v2 / np.linalg.norm(v2)
+# コサイン類似度 = 内積（正規化済み）
+cos_sim = np.dot(v1_norm, v2_norm)
+print(cos_sim)  # 例: 0.9995
+```
+### このプロジェクトでのベクトル類似度計算
+2つのモード：
+#### Mode 1: Top-k Pooling（フィルタリング用）
+クエリの各単語とドキュメント内の各単語のペアについて、コサイン類似度を計算し、高い上位k個を抽出して平均を取ります。
+**実装の詳細：**
+1. クエリの各単語ベクトルに対して、IDF による重み付けを行います
+2. ドキュメント内のすべての単語について、クエリの各単語とのコサイン類似度を計算（行列計算）
+3. 計算結果の行列 M（サイズ: ドキュメント単語数 × クエリ単語数）について、IDF重みを乗算
+4. 負の値を0に截断（ ReLU）
+5. 全要素から top-k を抽出し、その平均を取る
+$$\text{sim}_{\text{topk}}(q, d) = \text{mean}(\text{top-k}(\cos\text{-sim}(q_i, d_j) \cdot w_i \text{ for all } i, j))$$
+**目的：** 高速なフィルタリング（クイックスクリーニング）
+#### Mode 2: Pair-Average（リランキング用）
+クエリの全単語とドキュメント内の全単語のペアについて、コサイン類似度を計算し、全体の平均を取ります。
+**実装の詳細：**
+1. クエリの各単語ベクトルを集める（重み付けなし）
+2. ドキュメント内のすべての単語について、クエリの各単語とのコサイン類似度を計算（行列計算）
+3. 計算結果の行列 M（サイズ: ドキュメント単語数 × クエリ単語数）に��いて、負の値を0に截断（ ReLU）
+4. 全要素の平均を取る
+$$\text{sim}_{\text{pair\_avg}}(q, d) = \text{mean}(\cos\text{-sim}(q_i, d_j) \text{ for all pairs } (i, j))$$
+**目的：** より精密なスコアリング
+---
+## 4. このプロジェクトでのスコア統合
+### 複数スコアの融合
+このプロジェクトでは、複数の指標を組み合わせて、最終的なスコアを計算します。
+```
+最終スコア = α × BM25F + (1 - α) × ベクトル類似度 + 団体名ボーナス
+```
+### パラメータ
+```json
+{
+  "word_sim": {
+    "alpha": 0.5
+  }
+}
+```
+- $\alpha = 0.5$ の場合、BM25F と ベクトル類似度を同じ重要度で扱う
+- $\alpha = 0.7$ の場合、BM25F を重視
+### スコア正規化の考慮
+BM25F と ベクトル類似度のスケールが異なるため、実装では工夫がされています：
+1. **フィルタリング段階**（候補を絞る）
+   - Top-k モードでベクトル類似度を素早く計算
+   - BM25F の最小閾値を設定
+2. **リランキング段階**（最終順序を決める）
+   - Pair-average モードでより正確なベクトル類似度を計算
+   - BM25F と統合
+### 団体名ボーナス
+入力文字列が団体名に合致した場合、スコアを加算します。複数の条件が満たされた場合、それぞれのボーナスが加算されます。
+```
+団体名ボーナス = (完全一致 ? exact_boost : 0) + (前方一致 ? prefix_boost : 0) + (部分一致 ? substring_boost : 0)
+```
+デフォルト値：
+- 完全一致: +1.0
+- 前方一致: +0.7
+- 部分一致: +0.5
+**例：**
+- 入力 "写真部" = 団体名 "写真部" → 完全一致のボーナス +1.0
+- 入力 "写" = 団体名 "写真部" → 部分一致のボーナス +0.5
+- 入力 "写真" = 団体名 "写真部" → 前方一致のボーナス +0.7
+**注意：** 複数条件が同時に満たされることはありません。最も強い条件（完全一致 > 前方一致 > 部分一致）のみが適用されます。
+### 最終的なフィルタリング戦略
+```
+keep = (BM25F >= min_bm25)
+    OR (ベクトル類似度 >= min_sim)
+    OR (統合スコア >= min_fused)
+```
+いずれかの条件を満たすものを結果として返します。
+---
+## 計算例
+このセクションは、実装の複雑さを反映するため、簡略化した例を示します。実際の計算はより複雑です。
+### 設定
+- クエリ: 「カレー」
+- 企画数: 100個
+- 「カレー」が出現する企画: 5個（df = 5）
+- α（BM25F vs ベクトル重み）: 0.5
+### Step 1: トークン化と同義語展開
+```
+入力: "カレー"
+↓ トークン化
+tokens = ["カレー"]
+↓ 同義語展開（有効な場合）
+expanded_terms = ["カレー", "食事"]
+```
+### Step 2: IDF 計算
+```
+N = 100（全企画数）
+df("カレー") = 5（5個の企画に出現）
+IDF("カレー") = log((100 - 5 + 0.5) / (5 + 0.5))
+              = log(95.5 / 5.5)
+              ≈ log(17.36)
+              ≈ 2.85
+```
+### Step 3: 特定の企画Aに対するスコア計算
+企画A: 「カレー販売 - 当団体は美味しいカレーを販売します。カレーはインドの料理です。」
+#### BM25F スコア
+フィールド別の TF：
+- name: "カレー販売" → TF("カレー") = 1
+- description: "カレー...カレーは..." → TF("カレー") = 2
+各フィールドの長さと平均：
+- name の長さ: 6（文字列ベース）、平均: 5
+- description の長さ: 25、平均: 20
+パラメータ: k1=1.2, b=0.75
+BM25F スコア計算（簡略化）：
+```
+num_name = 2.0 * 1 * (1.2 + 1) = 4.4
+denom_name = 2.0 * (1 + 1.2 * (1 - 0.75 + 0.75 * 6/5)) = 4.08
+→ name部分スコア = 4.4 / 4.08 ≈ 1.08
+num_desc = 1.0 * 2 * 2.2 = 4.4
+denom_desc = 1.0 * (2 + 1.2 * (1 - 0.75 + 0.75 * 25/20)) = 4.35
+→ desc部分スコア = 4.4 / 4.35 ≈ 1.01
+BM25F = IDF("カレー") * (1.08 + 1.01) ≈ 2.85 * 2.09 ≈ 5.96
+```
+#### ベクトル類似度（Top-k）
+```
+cos_sim("カレー", "カレー") = 1.0
+cos_sim("カレー", "販売") = 0.65
+cos_sim("カレー", "料理") = 0.82
+...（他の単語）
+top-3: [1.0, 0.82, 0.65] → mean = 0.82
+```
+#### スコア統合（フィルタリング段階）
+```
+α = 0.5
+fused_filter = 0.5 * 5.96 + 0.5 * 0.82 = 3.39
+```
+#### 団体名ボーナス
+```
+query_normalized = "カレー"
+circleName_normalized = "飲食部カレー販売班"
+完全一致: "カレー" != "飲食部カレー販売班" → false
+前方一致: "飲食部カレー販売班".startswith("カレー") → false
+部分一致: "カレー" in "飲食部カレー販売班" → true
+org_boost = 0.5
+```
+#### 最終スコア（フィルタリング段階）
+```
+score_with_boost = fused_filter + org_boost = 3.39 + 0.5 = 3.89
+```
+### Step 4: リランキング（Pair-Average）
+フィルタリングを通った企画については、Pair-Average モードでより正確なベクトル類似度を再計算し、最終順序を決定します。
+```
+sim_pair_avg = mean of all (cos_sim(qi, dj))
+final_score = 0.5 * BM25F + 0.5 * sim_pair_avg + org_boost
+```
+---
+## 参考資料・式の出典
+1. **BM25F**: Zaragoza et al. (2004). "Relevance weighting for query independent evidence"
+2. **fastText**: Bojanowski et al. (2017). "Enriching Word Vectors with Subword Information"
+3. **コサイン類似度**: 情報検索の標準的な手法
+---
+## よくある質問
+### Q: なぜBM25FとベクトルのMIXが必要か
+**A:**
+- **BM25F**は「正確性」が高い（クエリに含まれる単語の頻度をよく反映）
+- **ベクトル類似度**は「リコール」が高い（クエリの意図に近い企画も見つかる）
+- 両者を組み合わせることで、正確性と再現性のバランスを取ります。
+### Q: αを大きくしたら何が変わるか
+**A:**
+- **α = 1.0**: BM25Fのみを使用（単語一致重視、保守的）
+- **α = 0.5**: BM25FとベクトルMIX（バランス型、推奨）
+- **α = 0.0**: ベクトルのみを使用（意味重視、広い検索）
+### Q: なぜ700次元ではなく300次元か
+**A:** このプロジェクトで使用しているfastTextの日本語事前学習モデル（`cc.ja.300.bin`）が300次元です。より高い次元のモデルもありますが、以下の理由から300次元が採用されています：
+- **標準的な選択**: fastTextの推奨モデルであり、多くのプロジェクトで使用されている
+- **計算効率**: 高次元になるほど、行列演算（内積計算）にかかるコストが増加
+- **精度とのバランス**: 300次元で既に十分な表現力がある
+- **メモリ効率**: ベクトル行列をメモリに保持する際のサイズ
+### Q: Top-kの「k」は何か
+**A:** このプロジェクトでは k=3 です。つまり、クエリ語×ドキュメント語の全ペアから、最も類似度の高い3ペアを選んで平均を取ります。
+---
+本ドキュメントでわかりづらい点や、さらに詳しく知りたいことがあれば、「システムガイド.md」の関連セクションを参照してください。