#実装フェーズ・TODOリスト

---

#Phase 1: 環境構築・プロジェクト基盤

目標: DBはDockerで、AIコンポーネント（Ollama・FastAPI・Frontend）はホストで直接起動できる状態を作る

• モノレポディレクトリ構成作成
  • /backend, /frontend, /scripts フォルダ作成
  • 各サブディレクトリ（app/api, app/models, app/rag 等）作成
• docker-compose.yml 作成（DBのみ）
  • postgres サービス（PostgreSQL 16、named volume必須）
  • chromadb サービス（ChromaDBサーバーモード、named volume必須）
  • ollama サービス → ホスト直接起動のためDocker不要
  • backend サービス → ホスト直接起動のためDocker不要
  • frontend サービス → ホスト直接起動のためDocker不要
• .env.example 作成（全環境変数の雛形・パスワード等は空白）
• backend/requirements.txt 定義
  • fastapi, uvicorn[standard], sqlalchemy, alembic, python-jose[cryptography], passlib[bcrypt]
  • pydantic-settings
  • llama-index, llama-index-llms-ollama, llama-index-embeddings-huggingface
  • chromadb, sentence-transformers
  • sudachipy, sudachidict-core（日本語トークナイザ）
  • PyMuPDF, python-docx, openpyxl, python-multipart, python-magic
  • slowapi（レート制限）
  • pytest, httpx, pytest-asyncio, pytest-cov, pytest-dotenv
• React + TypeScript + Vite プロジェクト初期化（frontend/）
• Ollama macOS インストール・設定
  • ollama pull gemma3:27b（推奨・~17GB）
  • ollama pull gemma3:12b（速度優先フォールバック・~8GB）
• scripts/start-dev.sh 起動スクリプト作成
• テスト環境構築（docker-compose.test.yml・.env.test）
• macOSスリープ無効化設定（sudo systemsetup -setsleepdisable on）

---

#Phase 2: データベース設計

目標: PostgreSQL スキーマと Alembic マイグレーションが動く状態

• backend/app/database.py 作成（SQLAlchemy エンジン・セッション）
• backend/app/config.py 作成（pydantic-settings + 起動時バリデーション）
• SQLAlchemy モデル実装（users, categories, documents, document_versions, chat_sessions, chat_messages, audit_logs）
• インデックス設計（GINインデックス・複合インデックス等）
• Alembic 初期設定・マイグレーション作成・適用
• 初期データ投入スクリプト作成（admin ユーザー、サンプルカテゴリ）

---

#Phase 3: 認証API

目標: HttpOnly Cookie による JWT 認証とロール制御が動く状態

• core/security.py 実装（bcrypt・JWT発行・HttpOnly Cookie）
• core/dependencies.py 実装（require_admin / require_employee）
• api/auth.py エンドポイント実装（login/logout/refresh/me/reset-password）
• api/health.py 実装（全コンポーネント疎通確認）
• main.py にルーター登録・CORS設定・グローバルエラーハンドラー
• レート制限設定（slowapi：POST /chat に 10req/min/ユーザー）
• テスト作成（ログイン・ロール別アクセス制御・Refresh Token）

---

#Phase 4: ドキュメント管理API

目標: 管理者がドキュメントを登録・更新・バージョン管理できる状態

• api/categories.py 実装
• ファイルテキスト抽出モジュール（python-magic + PyMuPDF + python-docx + openpyxl）
• api/documents.py 実装（CRUD + バージョン管理 + 非同期Ingestion起動）
• api/users.py 実装（admin限定）
• Pydantic スキーマ定義
• テスト作成（CRUD・ファイルアップロード・バージョン管理）

---

#Phase 5: RAGパイプライン構築

目標: PDF をアップロードすると ChromaDB に登録され、日本語で精度良く検索できる状態

• Embedding設定（必須・最重要）
  • intfloat/multilingual-e5-large 読み込み・revisionをconfig固定
  • Ingestion時: f"passage: {chunk.text}" / Retrieval時: f"query: {user_question}"
• Ingestion（rag/ingestion.py）
  • SentenceSplitter（chunk_size=512, overlap=50）
  • 単一コレクション company_documents + メタデータ付与
  • PostgreSQL content_tsv を SudachiPy でトークナイズして更新
• SudachiPy 日本語トークナイザ実装
• Hybrid Search（rag/retrieval.py）
  • Vector Search（ChromaDB top_k=10）+ PostgreSQL全文検索（top_k=10）
  • RRF（Reciprocal Rank Fusion）でスコア統合
• Reranker（hotchpotch/japanese-reranker-cross-encoder-large-v1、上位10→3件）
• Generation（rag/generation.py）（Mermaid ON/OFF・許可リスト検証）
• テスト作成（精度評価スクリプト・Phase 9向けベースライン取得）

---

#Phase 6: チャットAPI

目標: 質問を投げると RAG 経由で回答 + Mermaid 図が返ってくる状態

• api/chat.py 実装（POST /chat + セッション管理）
• 会話履歴の保存（chat_sessions + chat_messages）
• エラーハンドリング（Ollamaオフライン・検索0件・タイムアウト）
• レスポンス速度測定・P50/P95 ベースライン記録
• テスト作成（Ollamaモック使用）

---

#Phase 7: 管理者画面フロントエンド

目標: ブラウザから管理者操作が全て完結する状態

• 共通基盤（axios設定・Zustand・React Router・TailwindCSS・ErrorBoundary）
• ログイン画面 /login
• パスワード変更画面 /change-password
• ダッシュボード /admin（統計カード・Ingestion失敗アラート）
• ドキュメント一覧 /admin/documents（検索・フィルタ・ステータスバッジ）
• ドキュメント登録・編集（Drag&Drop・バージョン履歴・再Ingestionボタン）
• カテゴリ管理 /admin/categories
• ユーザー管理 /admin/users（パスワードリセット・ロール変更）
• テスト作成（Vitest・主要コンポーネント）

---

#Phase 8: 社員チャット画面フロントエンド

目標: 社員が自然な会話でチャットし、Mermaid 図が安全に表示される状態

• チャット画面 /chat（メッセージ一覧・入力・ローディング・カテゴリフィルタ・Mermaidトグル）
• Mermaid.jsセキュリティ設定（securityLevel: 'strict' + DOMPurify）
• MessageBubble コンポーネント（react-markdown + Mermaid図 + 引用元）
• 会話履歴サイドバー（セッション一覧・新しい会話ボタン）
• エラー表示（サーバーエラー・レート制限・規約未記載）
• テスト作成（Mermaid XSSペイロード無効化テスト）

---

#Phase 9: 品質向上・精度チューニング

目標: 実運用に耐える回答精度・安定性を実現する

• Embedding prefix 付与の効果計測（prefix なしとの比較）
• SudachiPy 辞書モード調整（A / B / C 比較）
• chunk_size・overlap の最適化
• Hybrid Search RRF ウェイト実験（0.3/0.7 → 0.5/0.5 → 0.7/0.3）
• Embedding 結果のオンメモリキャッシュ（TTL: 1時間）
• Streaming レスポンス（StreamingResponse）の検討・実装
• チャット API の P50/P95 レイテンシ計測
• 精度評価レポート作成（就業規則・福利厚生・ハラスメント防止規程テスト）

---

#Phase 10: パッケージ化・リリース準備

目標: 他社環境に docker-compose up 一発でインストールできる状態

• 全設定の環境変数化の最終確認
• 本番マルチワーカー時のモデル共有設計
  • Gunicorn --preload でモデルをfork前にロード・Copy-on-Writeで共有
  • 本番2〜4ワーカー時のメモリ消費計測（上限48GB中余裕13GB確認）
• docker-compose.prod.yml 作成（Nginx + Gunicorn + バックアップコンテナ）
• オフライン環境対応（Ollamaモデル・HFキャッシュ事前コピー手順）
• README.md 作成（macOS向けセットアップ手順・Mac Studio固有設定）
• 管理者向けオペレーションマニュアル作成
• セキュリティ最終チェック（CORS・Nginx・Mermaid・ファイルアップロード・レート制限）
• CHANGELOG.md 作成（v1.0.0）
• 将来のロードマップ記載
  • v1.1〜v1.2: 管理者承認型FAQ機能
  • v1.5以降: セマンティックキャッシュ（pgvector + バージョン対応無効化）

---