Phase B実行指示書: RAG AIアドバイザー アーキテクチャ改善¶

🎯 Phase B 開始条件確認¶

✅ Phase A完了状況¶

• API基盤: task2-api コンテナ正常稼働
• 基本機能: /api/health, /api/embeddings/batch 正常動作
• 統合環境: Redmine + RAG API完全統合 (nginx-proxy設定完了)
• Git管理: コミットID 066d791 でコード保護済み

✅ 実行環境準備¶

• VPS-ROOT: Ubuntu 24.04.2 LTS @ 85.131.243.51
• 作業端末: Windows 160.251.155.93 (ito@minisform-ai)
• Docker環境: task2-service/ 配下で全コンテナ稼働中
• アクセス経路: SSH鍵認証準備済み

---

📋 Phase B実行手順¶

🏗️ Step 1: 開発環境セットアップ (15分)¶

1.1 作業開始¶

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

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

# Phase B ブランチ作成
git checkout -b feature/phase-b-refactoring
echo "Phase B開始: $(date)" >> DEVELOPMENT.log

1.2 依存関係追加¶

# package.json 更新
cd app/api
npm install --save-dev jest @types/jest supertest
npm install winston joi express-async-errors

---

🏛️ Step 2: 基底アーキテクチャ実装 (2時間)¶

2.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', statusCode = 200) {
        res.status(statusCode).json({
            status: 'success',
            message,
            data,
            timestamp: new Date().toISOString()
        });
    }
    
    handleError(res, error) {
        this.logger.error('Controller Error:', error);
        
        const statusCode = error.statusCode || 500;
        const message = error.message || 'Internal Server Error';
        
        res.status(statusCode).json({
            status: 'error',
            message,
            timestamp: new Date().toISOString(),
            ...(process.env.NODE_ENV === 'development' && { stack: error.stack })
        });
    }
}

module.exports = BaseController;

2.2 ServiceContainer (DI) 実装¶

// app/api/config/ServiceContainer.js
const winston = require('winston');

class ServiceContainer {
    constructor() {
        this.services = new Map();
        this.singletons = new Map();
        this.setupDefaultServices();
    }
    
    register(name, factory, singleton = false) {
        this.services.set(name, { factory, singleton });
        return this;
    }
    
    get(name) {
        const service = this.services.get(name);
        if (!service) {
            throw new Error(`Service '${name}' not found`);
        }
        
        if (service.singleton) {
            if (!this.singletons.has(name)) {
                this.singletons.set(name, service.factory(this));
            }
            return this.singletons.get(name);
        }
        
        return service.factory(this);
    }
    
    setupDefaultServices() {
        // Logger
        this.register('logger', () => {
            return winston.createLogger({
                level: process.env.LOG_LEVEL || 'info',
                format: winston.format.combine(
                    winston.format.timestamp(),
                    winston.format.json()
                ),
                transports: [
                    new winston.transports.Console(),
                    new winston.transports.File({ filename: 'logs/app.log' })
                ]
            });
        }, true);
        
        // Database service
        this.register('database', () => {
            const { Pool } = require('pg');
            return new Pool({
                host: process.env.DB_HOST || 'task2-vector-db',
                port: process.env.DB_PORT || 5432,
                database: process.env.DB_NAME || 'rag_db',
                user: process.env.DB_USER || 'postgres',
                password: process.env.DB_PASSWORD || 'postgres123'
            });
        }, true);
    }
}

module.exports = ServiceContainer;

---

🔧 Step 3: コアサービス層実装 (2時間)¶

3.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 = 'text-embedding-3-small') {
        this.logger.info(`Generating single embedding for text length: ${text.length}`);
        
        if (typeof text !== 'string' || !text.trim()) {
            throw new Error('Text must be a non-empty string');
        }
        
        try {
            const embedding = await this.openaiService.createEmbedding(text, model);
            await this.vectorService.store(text, embedding);
            
            return {
                text: text.substring(0, 100) + (text.length > 100 ? '...' : ''),
                embedding,
                model,
                dimensions: embedding.length
            };
        } catch (error) {
            this.logger.error('Single embedding generation failed:', error);
            throw error;
        }
    }
    
    async generateBatch(texts, model = 'text-embedding-3-small') {
        this.logger.info(`Generating batch embeddings for ${texts.length} texts`);
        
        if (!Array.isArray(texts) || texts.length === 0) {
            throw new Error('Texts must be a non-empty array');
        }
        
        const results = [];
        for (const text of texts) {
            try {
                const result = await this.generateSingle(text, model);
                results.push(result);
            } catch (error) {
                this.logger.warn(`Failed to process text: ${text.substring(0, 50)}`, error);
                results.push({
                    text: text.substring(0, 100),
                    error: error.message
                });
            }
        }
        
        return {
            results,
            processed: results.filter(r => !r.error).length,
            failed: results.filter(r => r.error).length,
            total: texts.length
        };
    }
    
    async processDocument(document, options = {}) {
        const { chunkSize = 1000, overlap = 200 } = options;
        
        this.logger.info(`Processing document: ${document.title || 'Untitled'}`);
        
        const chunks = this.chunkText(document.content, chunkSize, overlap);
        const embeddings = await this.generateBatch(chunks);
        
        return {
            document: {
                title: document.title,
                chunks: chunks.length
            },
            embeddings: embeddings.results,
            metadata: {
                chunkSize,
                overlap,
                processedAt: new Date().toISOString()
            }
        };
    }
    
    chunkText(text, chunkSize, overlap) {
        const chunks = [];
        let start = 0;
        
        while (start < text.length) {
            const end = Math.min(start + chunkSize, text.length);
            chunks.push(text.substring(start, end));
            start = end - overlap;
            
            if (start >= text.length) break;
        }
        
        return chunks;
    }
}

module.exports = EmbeddingService;

3.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) {
        const { title, content, metadata = {} } = documentData;
        
        this.logger.info(`Creating document: ${title}`);
        
        try {
            // Document作成
            const result = await this.database.query(
                'INSERT INTO documents (title, content, metadata, created_at) VALUES ($1, $2, $3, NOW()) RETURNING *',
                [title, content, JSON.stringify(metadata)]
            );
            
            const document = result.rows[0];
            
            // 埋め込みベクトル生成
            const embeddingResult = await this.embeddingService.processDocument({
                id: document.id,
                title,
                content
            });
            
            return {
                document,
                embeddings: embeddingResult
            };
        } catch (error) {
            this.logger.error('Document creation failed:', error);
            throw error;
        }
    }
    
    async update(id, updateData) {
        this.logger.info(`Updating document: ${id}`);
        
        const { title, content, metadata } = updateData;
        const setClause = [];
        const values = [];
        let paramIndex = 1;
        
        if (title) {
            setClause.push(`title = $${paramIndex++}`);
            values.push(title);
        }
        if (content) {
            setClause.push(`content = $${paramIndex++}`);
            values.push(content);
        }
        if (metadata) {
            setClause.push(`metadata = $${paramIndex++}`);
            values.push(JSON.stringify(metadata));
        }
        
        setClause.push(`updated_at = NOW()`);
        values.push(id);
        
        const result = await this.database.query(
            `UPDATE documents SET ${setClause.join(', ')} WHERE id = $${paramIndex} RETURNING *`,
            values
        );
        
        return result.rows[0];
    }
    
    async delete(id) {
        this.logger.info(`Deleting document: ${id}`);
        
        // 関連する埋め込みベクトルも削除
        await this.database.query('DELETE FROM embeddings WHERE document_id = $1', [id]);
        await this.database.query('DELETE FROM documents WHERE id = $1', [id]);
        
        return { deleted: true, id };
    }
    
    async search(query, options = {}) {
        const { limit = 10, offset = 0, includeEmbeddings = false } = options;
        
        this.logger.info(`Searching documents: ${query}`);
        
        // ベクトル検索実行
        const searchResults = await this.searchService.search(query, { limit, offset });
        
        if (includeEmbeddings) {
            return searchResults;
        }
        
        // ドキュメント情報のみ返す
        return {
            query,
            results: searchResults.results.map(r => ({
                document: r.document,
                score: r.score
            })),
            total: searchResults.total
        };
    }
}

module.exports = DocumentService;

---

🛡️ Step 4: ミドルウェア実装 (1.5時間)¶

4.1 ValidationMiddleware¶

// app/api/src/middleware/validation/ValidationMiddleware.js
const Joi = require('joi');

class ValidationMiddleware {
    static validateEmbeddingRequest() {
        const schema = Joi.object({
            text: Joi.string().min(1).max(10000).required(),
            model: Joi.string().valid('text-embedding-3-small', 'text-embedding-3-large').optional()
        });
        
        return (req, res, next) => {
            const { error } = schema.validate(req.body);
            if (error) {
                return res.status(400).json({
                    status: 'error',
                    message: 'Validation failed',
                    details: error.details.map(d => d.message)
                });
            }
            next();
        };
    }
    
    static validateBatchEmbeddingRequest() {
        const schema = Joi.object({
            texts: Joi.array().items(Joi.string().min(1).max(10000)).min(1).max(100).required(),
            model: Joi.string().valid('text-embedding-3-small', 'text-embedding-3-large').optional()
        });
        
        return (req, res, next) => {
            const { error } = schema.validate(req.body);
            if (error) {
                return res.status(400).json({
                    status: 'error',
                    message: 'Validation failed',
                    details: error.details.map(d => d.message)
                });
            }
            next();
        };
    }
    
    static validateDocumentRequest() {
        const schema = Joi.object({
            title: Joi.string().min(1).max(255).required(),
            content: Joi.string().min(1).max(100000).required(),
            metadata: Joi.object().optional()
        });
        
        return (req, res, next) => {
            const { error } = schema.validate(req.body);
            if (error) {
                return res.status(400).json({
                    status: 'error',
                    message: 'Validation failed',
                    details: error.details.map(d => d.message)
                });
            }
            next();
        };
    }
}

module.exports = ValidationMiddleware;

4.2 ErrorMiddleware¶

// app/api/src/middleware/error/ErrorMiddleware.js
class ErrorMiddleware {
    static handleApiError(err, req, res, next) {
        // Async エラーハンドリング
        const logger = req.container?.get('logger') || console;
        
        logger.error('API Error:', {
            error: err.message,
            stack: err.stack,
            url: req.url,
            method: req.method,
            ip: req.ip
        });
        
        // レスポンス送信済みチェック
        if (res.headersSent) {
            return next(err);
        }
        
        // エラータイプ別処理
        if (err.name === 'ValidationError') {
            return res.status(400).json({
                status: 'error',
                message: 'Validation failed',
                details: err.details || err.message
            });
        }
        
        if (err.name === 'UnauthorizedError') {
            return res.status(401).json({
                status: 'error',
                message: 'Unauthorized access'
            });
        }
        
        // デフォルトエラー
        const statusCode = err.statusCode || 500;
        res.status(statusCode).json({
            status: 'error',
            message: err.message || 'Internal Server Error',
            timestamp: new Date().toISOString(),
            ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
        });
    }
    
    static handle404(req, res, next) {
        res.status(404).json({
            status: 'error',
            message: 'Endpoint not found',
            path: req.path,
            timestamp: new Date().toISOString()
        });
    }
    
    static asyncWrapper(fn) {
        return (req, res, next) => {
            Promise.resolve(fn(req, res, next)).catch(next);
        };
    }
}

module.exports = ErrorMiddleware;

---

🔄 Step 5: コントローラーリファクタリング (2時間)¶

5.1 EmbeddingsController改善¶

// app/api/src/controllers/embeddings/EmbeddingsController.js
const BaseController = require('../base/BaseController');
const ValidationMiddleware = require('../../middleware/validation/ValidationMiddleware');
const ErrorMiddleware = require('../../middleware/error/ErrorMiddleware');

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;
            
            const result = await this.embeddingService.generateSingle(text, model);
            
            return {
                embedding: result,
                metadata: {
                    requestedAt: new Date().toISOString(),
                    processingTime: '< 1s' // TODO: 実際の処理時間計測
                }
            };
        });
    }
    
    async generateBatchEmbeddings(req, res) {
        await this.handleRequest(req, res, async () => {
            const { texts, model } = req.body;
            
            const startTime = Date.now();
            const result = await this.embeddingService.generateBatch(texts, model);
            const processingTime = Date.now() - startTime;
            
            return {
                batchResult: result,
                metadata: {
                    requestedAt: new Date().toISOString(),
                    processingTime: `${processingTime}ms`,
                    averagePerText: `${Math.round(processingTime / texts.length)}ms`
                }
            };
        });
    }
    
    async processDocument(req, res) {
        await this.handleRequest(req, res, async () => {
            const document = req.body;
            const options = {
                chunkSize: req.query.chunkSize ? parseInt(req.query.chunkSize) : 1000,
                overlap: req.query.overlap ? parseInt(req.query.overlap) : 200
            };
            
            const result = await this.embeddingService.processDocument(document, options);
            
            return result;
        });
    }
    
    async getStats(req, res) {
        await this.handleRequest(req, res, async () => {
            // TODO: 統計情報取得実装
            return {
                totalEmbeddings: 0,
                totalDocuments: 0,
                averageProcessingTime: '0ms',
                lastProcessed: null
            };
        });
    }
    
    // ルート設定
    static setupRoutes(router, container) {
        const controller = new EmbeddingsController(container);
        
        router.post('/single', 
            ValidationMiddleware.validateEmbeddingRequest(),
            ErrorMiddleware.asyncWrapper(controller.generateEmbedding.bind(controller))
        );
        
        router.post('/batch',
            ValidationMiddleware.validateBatchEmbeddingRequest(), 
            ErrorMiddleware.asyncWrapper(controller.generateBatchEmbeddings.bind(controller))
        );
        
        router.post('/document',
            ValidationMiddleware.validateDocumentRequest(),
            ErrorMiddleware.asyncWrapper(controller.processDocument.bind(controller))
        );
        
        router.get('/stats',
            ErrorMiddleware.asyncWrapper(controller.getStats.bind(controller))
        );
        
        return router;
    }
}

module.exports = EmbeddingsController;

---

🧪 Step 6: テスト環境構築 (1.5時間)¶

6.1 Jest設定¶

// app/api/jest.config.js
module.exports = {
    testEnvironment: 'node',
    coverageDirectory: 'coverage',
    collectCoverageFrom: [
        'src/**/*.js',
        '!src/**/*.test.js',
        '!src/db/migrations/**'
    ],
    testMatch: [
        '**/tests/**/*.test.js',
        '**/src/**/*.test.js'
    ],
    setupFilesAfterEnv: ['<rootDir>/tests/setup.js']
};

6.2 テストセットアップ¶

// app/api/tests/setup.js
const ServiceContainer = require('../config/ServiceContainer');

// テスト用のモック設定
global.testContainer = new ServiceContainer();

// モックサービス登録
global.testContainer.register('logger', () => ({
    info: jest.fn(),
    error: jest.fn(),
    warn: jest.fn()
}), true);

global.testContainer.register('database', () => ({
    query: jest.fn()
}), true);

beforeEach(() => {
    jest.clearAllMocks();
});

6.3 サンプルテスト¶

// app/api/tests/services/EmbeddingService.test.js
const EmbeddingService = require('../../src/services/core/EmbeddingService');

describe('EmbeddingService', () => {
    let embeddingService;
    let mockOpenaiService;
    let mockVectorService;
    let mockLogger;
    
    beforeEach(() => {
        mockOpenaiService = {
            createEmbedding: jest.fn()
        };
        mockVectorService = {
            store: jest.fn()
        };
        mockLogger = global.testContainer.get('logger');
        
        embeddingService = new EmbeddingService(
            mockOpenaiService,
            mockVectorService,
            mockLogger
        );
    });
    
    describe('generateSingle', () => {
        test('should generate single embedding successfully', async () => {
            const text = 'Test text for embedding';
            const mockEmbedding = [0.1, 0.2, 0.3];
            
            mockOpenaiService.createEmbedding.mockResolvedValue(mockEmbedding);
            mockVectorService.store.mockResolvedValue(true);
            
            const result = await embeddingService.generateSingle(text);
            
            expect(result).toHaveProperty('embedding', mockEmbedding);
            expect(result).toHaveProperty('text');
            expect(result).toHaveProperty('model');
            expect(result).toHaveProperty('dimensions', 3);
            
            expect(mockOpenaiService.createEmbedding).toHaveBeenCalledWith(text, 'text-embedding-3-small');
            expect(mockVectorService.store).toHaveBeenCalledWith(text, mockEmbedding);
        });
        
        test('should throw error for empty text', async () => {
            await expect(embeddingService.generateSingle('')).rejects.toThrow('Text must be a non-empty string');
        });
        
        test('should throw error for non-string input', async () => {
            await expect(embeddingService.generateSingle(123)).rejects.toThrow('Text must be a non-empty string');
        });
    });
    
    describe('generateBatch', () => {
        test('should process multiple texts successfully', async () => {
            const texts = ['Text 1', 'Text 2'];
            const mockEmbedding = [0.1, 0.2, 0.3];
            
            mockOpenaiService.createEmbedding.mockResolvedValue(mockEmbedding);
            mockVectorService.store.mockResolvedValue(true);
            
            const result = await embeddingService.generateBatch(texts);
            
            expect(result.total).toBe(2);
            expect(result.processed).toBe(2);
            expect(result.failed).toBe(0);
            expect(result.results).toHaveLength(2);
        });
    });
});

---

📊 Phase B 成功指標¶

必須達成条件¶

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

動作確認項目¶

# API動作確認
curl -k https://task2.call2arm.com/api/health
curl -k https://task2.call2arm.com/api/embeddings/batch -X POST -H "Content-Type: application/json" -d '{"texts":["test1","test2"]}'

# テスト実行
cd app/api
npm test
npm run test:coverage

# Redmine統合確認
curl -k "https://task2.call2arm.com/api/users/current.json?key=feb66d81a5f4ff9c585ce30fce2ac06e0554aec6"

---

⏱️ 実行スケジュール¶

総所要時間: 8-9時間

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

---

🔄 完了条件¶

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

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