RAG AIアドバイザー Phase B: コア機能リファクタリング＆アーキテクチャ改善¶

🎯 Phase B 目標¶

Phase A完了状態からのアーキテクチャ改善と機能拡張

• モジュラーアーキテクチャの実装
• 依存性注入システムの構築
• 単体テスト環境の整備
• エラーハンドリングの標準化

---

📋 Phase B 実行内容¶

🏗️ Step 1: 基底アーキテクチャ実装（2時間）¶

1.1 BaseController実装¶

// app/api/src/controllers/base/BaseController.js
class BaseController {
  constructor(container) {
    this.container = container;
    this.logger = container.get('logger');
  }
  
  async handleRequest(req, res, handler) {
    try {
      const result = await handler();
      this.sendSuccess(res, result);
    } catch (error) {
      this.handleError(res, error);
    }
  }
  
  sendSuccess(res, data, message = 'Success') { /* 実装 */ }
  handleError(res, error) { /* 実装 */ }
}

1.2 ServiceContainer実装¶

// app/api/config/ServiceContainer.js
class ServiceContainer {
  constructor() {
    this.services = new Map();
    this.singletons = new Map();
  }
  
  register(name, factory, singleton = false) { /* 実装 */ }
  get(name) { /* 実装 */ }
  createLogger() { /* 実装 */ }
  createDatabaseService() { /* 実装 */ }
}

🔧 Step 2: コアサービス層実装（2時間）¶

2.1 EmbeddingService¶

// app/api/src/services/core/EmbeddingService.js
class EmbeddingService {
  constructor(openaiService, vectorService, logger) {
    this.openaiService = openaiService;
    this.vectorService = vectorService;
    this.logger = logger;
  }
  
  async generateSingle(text, model) { /* 実装 */ }
  async generateBatch(texts, model) { /* 実装 */ }
  async processDocument(document, options) { /* 実装 */ }
}

2.2 DocumentService¶

// app/api/src/services/core/DocumentService.js
class DocumentService {
  constructor(database, embeddingService, searchService, logger) {
    this.database = database;
    this.embeddingService = embeddingService;
    this.searchService = searchService;
    this.logger = logger;
  }
  
  async create(documentData) { /* 実装 */ }
  async update(id, updateData) { /* 実装 */ }
  async delete(id) { /* 実装 */ }
  async search(query, options) { /* 実装 */ }
}

🛡️ Step 3: ミドルウェア実装（1.5時間）¶

3.1 ValidationMiddleware¶

// app/api/src/middleware/validation/ValidationMiddleware.js
class ValidationMiddleware {
  static validateEmbeddingRequest() { /* 実装 */ }
  static validateDocumentRequest() { /* 実装 */ }
  static validateSearchRequest() { /* 実装 */ }
}

3.2 ErrorMiddleware¶

// app/api/src/middleware/error/ErrorMiddleware.js
class ErrorMiddleware {
  static handleApiError(err, req, res, next) { /* 実装 */ }
  static handle404(req, res, next) { /* 実装 */ }
  static handleValidationError(err, req, res, next) { /* 実装 */ }
}

🔄 Step 4: コントローラーリファクタリング（2時間）¶

4.1 EmbeddingsController改善¶

// app/api/src/controllers/embeddings/EmbeddingsController.js
class EmbeddingsController extends BaseController {
  constructor(container) {
    super(container);
    this.embeddingService = container.get('embeddingService');
  }
  
  async generateEmbedding(req, res) {
    await this.handleRequest(req, res, async () => {
      const { text, model } = req.body;
      return await this.embeddingService.generateSingle(text, model);
    });
  }
  
  async generateBatchEmbeddings(req, res) { /* 実装 */ }
  async processDocument(req, res) { /* 実装 */ }
  async getStats(req, res) { /* 実装 */ }
}

🧪 Step 5: テスト環境構築（1.5時間）¶

5.1 Jestセットアップ¶

// package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "@types/jest": "^29.5.5",
    "supertest": "^6.3.3"
  }
}

5.2 単体テスト実装¶

// app/api/tests/services/EmbeddingService.test.js
describe('EmbeddingService', () => {
  let embeddingService;
  let mockOpenaiService;
  let mockVectorService;
  
  beforeEach(() => { /* セットアップ */ });
  
  describe('generateSingle', () => {
    test('should generate single embedding', async () => { /* テスト */ });
    test('should handle errors gracefully', async () => { /* テスト */ });
  });
});

---

📊 成功指標¶

必須達成条件¶

• ✅ BaseController実装完了
• ✅ ServiceContainer DI動作確認
• ✅ EmbeddingService正常動作
• ✅ ミドルウェア統合完了
• ✅ リファクタリング後API動作確認
• ✅ 単体テスト80%以上カバレッジ

品質確認項目¶

• ✅ コードの可読性向上
• ✅ エラーハンドリング統一
• ✅ ログ出力標準化
• ✅ テスト実行成功
• ✅ 既存機能の互換性維持

---

🛠️ 実行手順¶

Phase B開始コマンド¶

# VPS接続
ssh root@85.131.243.51
cd /var/docker/task2-service

# 現状確認
docker ps | grep task2-api
curl -k https://task2.call2arm.com/api/health

# Phase B開始
git checkout -b phase-b-refactoring

開発フロー¶

1. 基底クラス実装 → 動作確認
2. サービス層実装 → 統合テスト
3. ミドルウェア実装 → エラーハンドリング確認
4. リファクタリング → 既存機能保持確認
5. テスト実装 → カバレッジ確認

---

⏱️ スケジュール¶

総所要時間: 8-9時間

フェーズ	所要時間	内容
Step 1	2時間	基底アーキテクチャ
Step 2	2時間	コアサービス層
Step 3	1.5時間	ミドルウェア
Step 4	2時間	リファクタリング
Step 5	1.5時間	テスト環境

---

🔄 Phase C 準備事項¶

Phase B完了時に以下を準備：

• AI統合準備: Claude/ChatGPT APIクライアント
• 検索機能準備: 高度な検索ロジック
• UI統合準備: フロントエンド連携API
• キャッシュ戦略: Redis活用最適化

---

📝 完了条件¶

1. 全テスト合格: npm test で全テスト成功
2. API動作確認: 既存エンドポイント正常動作
3. コードカバレッジ: 80%以上達成
4. ドキュメント更新: README.md更新
5. Git管理: feature/phase-b ブランチコミット

---

Phase B完了により、RAG AIアドバイザーのアーキテクチャが堅牢化され、Phase C以降の高度な機能実装の基盤が完成します。