Redmineの設定

🎯 目的¶

現在のRAG AIアドバイザー開発において、ホットフィックスの繰り返しにより設計が不透明になった状況を解決し、堅牢で保守性の高いアーキテクチャを再構築する。

📋 現状の課題¶

技術的問題¶

• tiktoken Uint8Array問題: 文字列変換の根本的解決が必要
• Docker ボリュームマウント不整合: ファイル修正がコンテナに反映されない
• モジュール依存関係エラー: generateBatchEmbeddings等のメソッド解決失敗

設計的問題¶

• 責任境界の不明確: Controller/Service/Repositoryの役割分担曖昧
• エラーハンドリング不統一: 各層でのエラー処理が一貫していない
• テスタビリティ不足: 単体テスト実行が困難な構造

🔍 レビュー実行計画¶

Phase 1: 現状分析 (45分)¶

1.1 アーキテクチャ分析¶

• 現在のディレクトリ構造とモジュール構成の可視化
• データフロー（リクエスト → コントローラ → サービス → DB）の整理
• 依存関係マップの作成（正常/問題のある依存関係の特定）

1.2 問題点の根本原因特定¶

• tiktoken問題の技術的根本原因分析
• Docker設定とファイルマウントの設定確認
• モジュール設計の不整合箇所の特定

1.3 設計負債の可視化¶

• 一時的修正（ホットフィックス）の蓄積箇所の洗い出し
• テスト不可能なコードの特定
• 責任境界が不明確なモジュールのリスト化

Phase 2: 理想アーキテクチャ設計 (60分)¶

2.1 レイヤー分離設計¶

src/
├── api/                 # プレゼンテーション層
│   ├── controllers/     # リクエスト処理
│   ├── middlewares/     # 横断的関心事
│   └── routes/          # ルーティング
├── services/            # ビジネスロジック層
│   ├── embedding/       # 埋め込み生成サービス
│   ├── search/          # ベクトル検索サービス
│   └── openai/          # OpenAI統合サービス
├── repositories/        # データアクセス層
├── models/             # ドメインモデル
├── config/             # 設定管理
└── utils/              # ユーティリティ

2.2 依存性注入とテスタビリティ¶

• 各モジュールの単体テスト可能性確保
• モック・スタブでの外部依存切り離し
• 設定の外部化（環境変数、設定ファイル）

2.3 エラーハンドリングとログ設計¶

• 統一的なエラーハンドリング戦略
• 構造化ログとトレーサビリティ
• 運用監視の観点

Phase 3: 実装戦略 (30分)¶

3.1 段階的移行戦略¶

• 既存システムを停止させない移行手順
• 最小限の機能で動作検証
• 段階的な機能追加計画

3.2 技術的決定事項¶

• tiktoken問題の根本解決案
• Docker設定の最適化
• テスト戦略（単体/統合/E2E）

📄 成果物¶

1. RAG AIアドバイザー アーキテクチャ仕様書 v2.0¶

## 1. システム概要
- ビジネス要件と技術要件
- 非機能要件（性能、信頼性、保守性）

## 2. アーキテクチャ設計
- レイヤー構成図
- モジュール依存関係図  
- データフロー図

## 3. API設計
- RESTful API仕様
- エラーレスポンス統一仕様
- 認証・認可設計

## 4. データベース設計
- ER図（正規化済み）
- インデックス戦略
- パフォーマンス考慮事項

2. 実装ガイドライン¶

• ディレクトリ構造定義
• コーディング規約（TypeScript導入検討）
• Docker構成最適化

3. システム移行計画¶

Phase 1: 基盤整備 (2時間)¶

• 新アーキテクチャでの最小機能実装
• 基本的なE2Eテスト作成
• CI/CD パイプライン構築

Phase 2: 機能移行 (3時間)¶

• 埋め込み生成機能の移行
• ベクトル検索機能の移行
• 統合テスト実行

Phase 3: 本番移行 (1時間)¶

• データ移行
• 本番デプロイ
• 動作確認

4. テスト戦略書¶

• 単体テスト戦略
• 統合テスト戦略
• E2Eテスト戦略

🎯 成功基準¶

• 技術的: 2時間以内でPhase 1機能が動作
• 保守性: 新機能追加が1日以内で完了可能
• 品質: テストカバレッジ80%以上達成

🔗 関連チケット¶

• #256: RAG AIアドバイザー - Phase 1 デバッグ: tiktoken Uint8Array 問題

📋 次のアクション¶

このチケット完了後、新しい会話セッションで以下を実行：

1. アーキテクチャレビューの実施
2. 設計ドキュメントの作成
3. 移行計画の策定
4. 実装開始