@fuzionx/framework 0.1.43 → 0.1.45

package/lib/core/Application.js

@@ -1,1006 +1,1006 @@
-/**
- * Application — 서비스 컨테이너 + 부트스트랩 오케스트레이터 + Bridge 어댑터
- *
- * @fuzionx/core의 FuzionXApp을 내부적으로 사용하여 Bridge 서버 시작.
- * rawReq → Context 변환 → 미들웨어 체인 → 컨트롤러 → toResponse().
- *
- * @see docs/framework/00-overview.md
- * @see docs/framework/04-bootstrap-lifecycle.md
- */
-import path from 'node:path';
-import { promises as fs } from 'node:fs';
-import cluster from 'node:cluster';
-import Config from './Config.js';
-import Context from './Context.js';
-import Router from '../http/Router.js';
-import ModelRegistry from '../database/ModelRegistry.js';
-import ErrorHandler from '../http/ErrorHandler.js';
-import AutoLoader from './AutoLoader.js';
-import Logger from '../helpers/Logger.js';
-import I18nHelper from '../helpers/I18nHelper.js';
-import CryptoHelper from '../helpers/CryptoHelper.js';
-import HashHelper from '../helpers/HashHelper.js';
-import MediaHelper from '../helpers/MediaHelper.js';
-import FileHelper from '../helpers/FileHelper.js';
-import View from '../view/View.js';
-import OpenAPI from '../view/OpenAPI.js';
-import Scheduler from '../schedule/Scheduler.js';
-import Queue from '../schedule/Queue.js';
-import Storage from '../services/Storage.js';
-import ConnectionManager from '../database/ConnectionManager.js';
-import SqlModel from '../database/SqlModel.js';
-import MongoModel from '../database/MongoModel.js';
-import WorkerPool from '../schedule/WorkerPool.js';
-
-// Bridge: lazy-load (테스트 환경에서 native 바인딩 없을 수 있음)
-let FuzionXApp;
-try {
-    const core = await import('@fuzionx/core');
-    FuzionXApp = core.FuzionXApp || core.RuxyApp;
-} catch (e) {
-    console.error('[fuzionx-framework] ⚠️  @fuzionx/core 로드 실패 — Bridge 없이 테스트 모드로 실행됩니다:',
-        e.message);
-}
-
-export default class Application {
-    /**
-     * @param {object} [opts]
-     * @param {object} [opts.config] - 이미 파싱된 설정 객체 또는 Config 인스턴스
-     * @param {string} [opts.configPath] - YAML 설정 파일 경로
-     * @param {string} [opts.baseDir='.'] - 프로젝트 루트 경로
-     * @param {object} [opts.bridge] - @fuzionx/core bridge 인스턴스 (선택)
-     */
-    constructor(opts = {}) {
-        // Config
-        if (opts.config instanceof Config) {
-            this.config = opts.config;
-        } else {
-            this.config = new Config(opts.config || {});
-        }
-
-        // 프로젝트 루트 (반드시 절대경로 — ESM import 호환)
-        this.baseDir = path.resolve(opts.baseDir || process.cwd());
-        this.configPath = opts.configPath || null;
-
-        // configPath 지정 시 YAML 파일에서 database/app/themes 등 로드
-        if (this.configPath) {
-            this.config.loadYaml(path.resolve(this.baseDir, this.configPath));
-        }
-
-        // Bridge 참조 (listen() 시 FuzionXApp 생성)
-        this._bridge = null;
-        this._coreApp = null;
-
-        // DI 컨테이너
-        this._services = new Map();
-        this._factories = new Map();
-
-        // 이벤트 핸들러
-        this._eventHandlers = new Map();
-        this._errorHandlers = [];
-
-        // 멀티앱 레지스트리 (도메인→앱 라우팅)
-        this._appRegistry = new Map();
-
-        // 글로벌 미들웨어
-        this._globalMiddleware = [];
-
-        // 프레임워크 컴포넌트
-        this.db = new ModelRegistry();
-        this.logger = new Logger({
-            level: this.config.get('bridge.logging.level', 'info'),
-            bridge: this._bridge,
-            json: this.config.get('bridge.logging.json', false),
-        });
-        this.crypto = new CryptoHelper(this._bridge);
-        this.hash = new HashHelper(this._bridge);
-        this.media = new MediaHelper(this._bridge);
-        this.file = new FileHelper(this._bridge);
-        this.ws = null;
-        this.i18n = new I18nHelper({
-            defaultLocale: this.config.get('app.i18n.default_locale', 'ko'),
-            fallback: this.config.get('app.i18n.fallback', 'en'),
-            dir: this.config.get('app.i18n.dir', './locales'),
-            bridge: this._bridge,
-        });
-        this.storage = null;
-        this._scheduler = null;
-        this._queue = null;
-        this._wsHandlers = new Map();
-
-        // DB 연결 매니저
-        this._connectionManager = new ConnectionManager();
-
-        // Worker 매니저 — shared/workers 기준
-        this._workerPool = new WorkerPool(this, {
-            workersDir: path.resolve(this.baseDir, 'shared/workers'),
-        });
-
-        /** @type {WorkerPool} public worker 접근 */
-        this.worker = this._workerPool;
-
-        // 에러 핸들러
-        this._errorHandler = new ErrorHandler({
-            isDev: this.config.get('app.environment', 'development') === 'development',
-            logger: (...args) => this.logger.error(...args),
-        });
-
-        // 라이프사이클 상태
-        this._booted = false;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  DI — 서비스 컨테이너
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    register(name, factory) {
-        this._factories.set(name, factory);
-    }
-
-    make(name) {
-        if (this._services.has(name)) return this._services.get(name);
-        const factory = this._factories.get(name);
-        if (!factory) throw new Error(`Service '${name}' is not registered`);
-        const instance = factory(this);
-        this._services.set(name, instance);
-        return instance;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  라우터 접근
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 앱별 라우터 인스턴스
-     * @param {string} [appName] - 앱 이름 (미지정 시 첫 번째 앱)
-     */
-    getRouter(appName) {
-        const name = appName || this._getDefaultAppName();
-        return this._appRegistry.get(name)?.router || null;
-    }
-
-    /**
-     * 라우트 파일 로드 (특정 앱에)
-     * @param {Function} routeCallback - (r: RouteGroup) => void
-     * @param {string} [appName]
-     */
-    routes(routeCallback, appName) {
-        const name = appName || this._getDefaultAppName();
-        const entry = this._appRegistry.get(name);
-        if (entry?.router) entry.router.load(routeCallback);
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  미들웨어
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 글로벌 미들웨어 등록
-     * @param {Function} fn - (ctx, next) => void
-     */
-    use(fn) {
-        this._globalMiddleware.push(fn);
-        return this;
-    }
-
-    /**
-     * 이름으로 미들웨어 인스턴스 조회
-     * @param {string} name - 'auth', 'csrf' 등
-     * @returns {Function} - (ctx, next) => void
-     */
-    /**
-     * @param {string} name - 미들웨어 이름 (e.g. 'auth', 'role:admin')
-     * @param {string} [appName] - 앱 이름 (앱별 미들웨어 우선 탐색)
-     */
-    resolveMiddleware(name, appName) {
-        // 캐시 히트 → zero-allocation (M-1)
-        const cacheKey = appName ? `${appName}:${name}` : name;
-        if (this._mwFnCache?.has(cacheKey)) return this._mwFnCache.get(cacheKey);
-
-        // 파라미터화: 'role:admin' → name='role', params=['admin']
-        const [mwName, ...params] = name.split(':');
-
-        // 앱별 미들웨어 우선 탐색 → 없으면 무시
-        let MwClass = null;
-        if (appName) {
-            const appEntry = this._appRegistry.get(appName);
-            MwClass = appEntry?.middlewareRegistry?.get(mwName) || null;
-        }
-        if (!MwClass) return null;
-
-        const instance = new MwClass(this);
-        const fn = (ctx, next) => instance.handle(ctx, next, ...params);
-
-        // 캐시 저장
-        if (!this._mwFnCache) this._mwFnCache = new Map();
-        this._mwFnCache.set(cacheKey, fn);
-        return fn;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  이벤트 시스템
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    on(event, handler) {
-        if (!this._eventHandlers.has(event)) {
-            this._eventHandlers.set(event, []);
-        }
-        this._eventHandlers.get(event).push(handler);
-    }
-
-    async emit(event, data, opts) {
-        const handlers = this._eventHandlers.get(event);
-        if (!handlers) return;
-        const meta = { remote: false, server: this.config.get('app.name', 'fuzionx'), timestamp: Date.now() };
-        for (const handler of handlers) {
-            try { await handler(data, meta); } catch (err) {
-                this.logger.error(`Event '${event}' handler error:`, err);
-            }
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  에러 핸들러
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    useError(pathOrHandler, handler) {
-        if (typeof pathOrHandler === 'function') {
-            this._errorHandlers.push({ path: null, handler: pathOrHandler });
-        } else {
-            this._errorHandlers.push({ path: pathOrHandler, handler });
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  큐 디스패치
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    dispatch(taskOrName, data, opts) {
-        if (this._queue) this._queue.dispatch(taskOrName, data, opts);
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  부트스트랩
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    async boot() {
-        if (this._booted) return;
-
-        // 0. Bridge 초기화 — boot 로직 전에 bridge 확보
-        //    Helper(crypto/hash/media/file/i18n/logger/view)가 boot 중 bridge 필요
-        if (FuzionXApp && !this._coreApp) {
-            this._coreApp = new FuzionXApp({
-                config: this.configPath
-                    ? path.resolve(this.baseDir, this.configPath)
-                    : undefined,
-            });
-            this._bridge = this._coreApp._bridge;
-            this._propagateBridge();
-        }
-
-        // 1. .env 로드 (17-config.md)
-        this.config.loadEnv(this.baseDir);
-        // .env 로드 후 캐시 클리어 (새로운 환경변수 반영)
-        this.config._cache?.clear();
-
-        await this.emit('booting');
-
-        // 2. i18n 로드 (04-bootstrap-lifecycle.md)
-        await this.i18n.load();
-
-        // 3. Scheduler / Queue / Storage 초기화
-        this._scheduler = new Scheduler(this);
-        this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
-        this.storage = new Storage({
-            driver: this.config.get('storage.driver', 'local'),
-            basePath: path.resolve(this.baseDir, this.config.get('storage.path', './storage')),
-            fileHelper: this.file,
-        });
-
-        // 4. Phase 1: 공유 리소스 로드 (database/models, shared/events,jobs,workers)
-        const sharedLoader = new AutoLoader(this, this.baseDir, { mode: 'shared' });
-        await sharedLoader.load();
-
-        // 5. Phase 2: 앱별 리소스 로드 (app/{name}/controllers,routes,services,middleware,ws,views)
-        const appNames = this._getAppNames();
-        for (const name of appNames) {
-            const appDir = path.resolve(this.baseDir, 'app', name);
-            const appEntry = {
-                name,
-                router: new Router(),
-                controllers: new Map(),
-                controllerCache: new Map(),
-                middlewareRegistry: new Map(),
-                wsHandlers: new Map(),
-                view: new View({
-                    viewsPath: path.resolve(appDir, 'views'),
-                    theme: this.config.get('app.themes.default', 'default'),
-                    bridge: this._bridge,
-                }),
-            };
-            const appLoader = new AutoLoader(this, appDir, { mode: 'app', appContext: appEntry });
-            await appLoader.load();
-            this._appRegistry.set(name, appEntry);
-        }
-
-        // 6. DB 연결 매니저 초기화 (database 섹션이 있을 때만)
-        const dbConfig = this.config.get('database');
-        if (dbConfig) {
-            if (!dbConfig.connections) {
-                const connections = {};
-                for (const [key, val] of Object.entries(dbConfig)) {
-                    if (key !== 'default' && typeof val === 'object' && val !== null) {
-                        connections[key] = val;
-                    }
-                }
-                if (Object.keys(connections).length > 0) {
-                    dbConfig.connections = connections;
-                    if (!dbConfig.default) dbConfig.default = Object.keys(connections)[0];
-                }
-            }
-            if (dbConfig.connections) {
-                this._connectionManager.configure(dbConfig);
-                SqlModel.setConnectionManager(this._connectionManager);
-                MongoModel.setConnectionManager(this._connectionManager);
-            }
-        }
-
-        // 7. OpenAPI / Swagger UI 라우트 등록 (모든 앱의 라우트 통합)
-        this._registerDocsRoutes();
-
-        this._booted = true;
-
-        // hostname → appName 매핑 사전 계산 (매 요청 O(1) 조회)
-        this._hostAppMap = new Map();
-        const appsConfig = this.config.get('apps') || {};
-        for (const [hostname, appName] of Object.entries(appsConfig)) {
-            this._hostAppMap.set(hostname, appName);
-        }
-
-        await this.emit('booted');
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Multi-App 도메인 라우팅
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * config.apps에서 유니크 앱 이름 목록 추출
-     * @returns {string[]}
-     */
-    _getAppNames() {
-        const appsConfig = this.config.get('apps') || {};
-        return [...new Set(Object.values(appsConfig))];
-    }
-
-    /**
-     * 기본 앱 이름 (config.apps의 첫 번째 항목 값)
-     * @returns {string}
-     */
-    _getDefaultAppName() {
-        const appsConfig = this.config.get('apps') || {};
-        const values = Object.values(appsConfig);
-        return values[0] || 'fuzionx';
-    }
-
-    /**
-     * 호스트 → 앱 이름 결정
-     * reverse proxy 경유 시 X-Forwarded-Host 우선 사용.
-     * @param {string} host - 요청 Host 헤더 (port 포함 가능)
-     * @param {object} [headers] - 전체 요청 헤더 (proxy 지원)
-     * @returns {string} 앱 이름
-     */
-    _resolveApp(host, headers) {
-        // reverse proxy: X-Forwarded-Host > X-Original-Host > Host
-        const forwardedHost = headers?.['x-forwarded-host'] || headers?.['X-Forwarded-Host']
-            || headers?.['x-original-host'] || headers?.['X-Original-Host'];
-        const rawHost = forwardedHost || host || '';
-        const hostname = rawHost.split(':')[0]; // 포트 제거
-
-        // 사전 계산된 Map O(1) 조회
-        const mapped = this._hostAppMap?.get(hostname);
-        if (mapped) return mapped;
-
-        // 매칭 없으면 기본 앱
-        return this._getDefaultAppName();
-    }
-
-    /**
-     * Bridge 참조를 모든 Helper 인스턴스에 전파
-     * @private
-     */
-    _propagateBridge() {
-        if (!this._bridge) return;
-        // View는 앱별 → boot()에서 생성 시 bridge 주입됨
-        if (this.logger) this.logger._bridge = this._bridge;
-        if (this.crypto) this.crypto._bridge = this._bridge;
-        if (this.hash) this.hash._bridge = this._bridge;
-        if (this.media) this.media._bridge = this._bridge;
-        if (this.file) this.file._bridge = this._bridge;
-        if (this.i18n) this.i18n._bridge = this._bridge;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  서버 시작 — Bridge 연결
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * Bridge 서버 시작
-     * FuzionXApp과 연동하여 rawReq를 Context로 변환.
-     * @param {number} [port]
-     * @param {Function} [callback]
-     */
-    async listen(port, callback) {
-        if (typeof port === 'function') { callback = port; port = undefined; }
-        port = port ?? this.config.get('bridge.server.port') ?? this.config.get('bridge.port', 3000);
-
-        if (!this._booted) await this.boot();
-
-        // PID 파일 생성 (primary만)
-        if (!cluster.isWorker) {
-            await this._checkPort(port);
-            const pidPath = path.join(this.baseDir, 'fuzionx.pid');
-            await fs.writeFile(pidPath, String(process.pid));
-        }
-
-        // process.title 설정 (ps에서 보이는 프로세스 이름)
-        const appName = this.config.get('app.name', 'fuzionx');
-        if (cluster.isWorker) {
-            process.title = `${appName}-worker-${cluster.worker.id}`;
-        } else {
-            process.title = `${appName}-primary`;
-        }
-
-        await this.emit('ready');
-
-        // Bridge 연동 — _coreApp은 boot()에서 이미 생성됨
-        if (this._coreApp) {
-            // boot()에서 port 없이 생성됐으므로 port 설정
-            this._coreApp._port = port;
-
-            // WS proxy 연결 (WsHandler에서 this.app.ws 사용)
-            if (!this.ws) this.ws = this._coreApp.ws;
-
-            this._registerBridgeRoutes(this._coreApp);
-
-            // WsHandler → Bridge WS 이벤트 연결
-            this._registerWsHandlers(this._coreApp);
-
-            this._coreApp.listen(port, callback);
-            // Bridge가 자체 graceful shutdown 처리 → Framework 중복 등록 불필요
-        } else {
-            // Bridge 미설치 (테스트 환경)
-            this._initControllers();
-            if (callback) callback();
-            this._setupGracefulShutdown();
-        }
-
-        await this.emit('listening');
-
-        // Scheduler 시작 — primary 프로세스에서만 (워커 중복 실행 방지)
-        // fuzionx 상위 레이어가 cluster.fork()로 워커를 생성하므로
-        // cluster.isPrimary로 단일 프로세스 보장
-        if (this._scheduler && this._scheduler._jobs.length > 0 && !cluster.isWorker) {
-            this._scheduler.start();
-        }
-
-        return this;
-    }
-
-    /**
-     * 포트 사용 여부 확인 — 이미 바인딩된 포트면 명확한 에러
-     * @param {number} port
-     * @private
-     */
-    async _checkPort(port) {
-        const net = await import('node:net');
-        return new Promise((resolve) => {
-            const tester = net.createServer()
-                .once('error', (err) => {
-                    if (err.code === 'EADDRINUSE') {
-                        console.error(
-                            `\n❌ 포트 ${port}이(가) 이미 사용 중입니다.\n` +
-                            `   다른 FuzionX 인스턴스가 실행 중인지 확인하세요.\n` +
-                            `   확인: lsof -i :${port}\n` +
-                            `   종료: fuser -k ${port}/tcp\n`
-                        );
-                        process.exit(1);
-                    } else {
-                        console.error(`❌ 포트 ${port} 확인 실패:`, err.message);
-                        process.exit(1);
-                    }
-                })
-                .once('listening', () => {
-                    tester.close(() => resolve());
-                })
-                .listen(port, '0.0.0.0');
-        });
-    }
-
-    /**
-     * OpenAPI / Swagger UI 라우트 등록 (21-openapi.md)
-     *
-     * app.docs.enabled = true 시 활성화.
-     * 라우트: GET /docs, GET /docs/openapi.json, GET /docs/openapi.yaml
-     * @private
-     */
-    _registerDocsRoutes() {
-        const docsConfig = this.config.get('app.docs');
-        if (!docsConfig || docsConfig.enabled === false) return;
-
-        const docsPath = docsConfig.path || '/docs';
-
-        // 모든 앱의 라우트 통합
-        const allRoutes = [];
-        for (const [, appEntry] of this._appRegistry) {
-            allRoutes.push(...appEntry.router.getRoutes());
-        }
-
-        // OpenAPI spec 빌드 (1회, 캐싱)
-        this._openapi = new OpenAPI({
-            title: docsConfig.title || this.config.get('app.name', 'FuzionX') + ' API',
-            version: docsConfig.version || '1.0.0',
-            description: docsConfig.description || '',
-            servers: docsConfig.servers || [],
-        });
-        this._openapi.build(allRoutes);
-
-        // docs 라우트는 기본 앱의 라우터에 등록
-        const defaultAppName = this._getDefaultAppName();
-        const defaultApp = this._appRegistry.get(defaultAppName);
-        if (!defaultApp) return;
-
-        // JSON spec
-        defaultApp.router.get(`${docsPath}/openapi.json`, (ctx) => {
-            ctx.json(this._openapi.toJSON());
-        });
-
-        // YAML spec
-        defaultApp.router.get(`${docsPath}/openapi.yaml`, (ctx) => {
-            ctx.setHeader('Content-Type', 'text/yaml; charset=utf-8');
-            ctx.send(this._openapi.toYAML());
-        });
-
-        // Swagger UI HTML (CDN — 외부 의존 없음)
-        defaultApp.router.get(docsPath, (ctx) => {
-            const specUrl = `${docsPath}/openapi.json`;
-            const title = docsConfig.title || 'API Docs';
-            ctx.html(Application._swaggerHtml(title, specUrl));
-        });
-
-        this.logger.info(`[docs] Swagger UI → ${docsPath}`);
-    }
-
-    /**
-     * Swagger UI HTML 생성 (CDN 기반)
-     * @private
-     */
-    static _swaggerHtml(title, specUrl) {
-        return `<!DOCTYPE html>
-<html lang="ko">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title}</title>
-  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
-  <style>
-    body { margin: 0; background: #fafafa; }
-    .topbar { display: none; }
-  </style>
-</head>
-<body>
-  <div id="swagger-ui"></div>
-  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-  <script>
-    SwaggerUIBundle({
-      url: '${specUrl}',
-      dom_id: '#swagger-ui',
-      deepLinking: true,
-      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
-      layout: 'BaseLayout',
-    });
-  </script>
-</body>
-</html>`;
-    }
-
-    /**
-     * 앱별 싱글톤 컨트롤러 초기화
-     * @private
-     */
-    _initControllers() {
-        for (const [, appEntry] of this._appRegistry) {
-            for (const route of appEntry.router.getRoutes()) {
-                const handler = route.handler;
-                if (handler?.__handler__ && handler.controller) {
-                    const CtrlClass = handler.controller;
-                    if (!appEntry.controllerCache.has(CtrlClass)) {
-                        appEntry.controllerCache.set(CtrlClass, new CtrlClass(this));
-                    }
-                }
-            }
-        }
-    }
-
-    /**
-     * 프레임워크 라우트 → Bridge 라우트 변환 (Host 기반 앱 디스패치)
-     *
-     * 동일 path에 여러 앱이 라우트를 가질 수 있으므로,
-     * 각 method+path 당 하나의 Bridge 핸들러를 등록하고
-     * 런타임에 Host 헤더로 앱을 결정한다.
-     *
-     * @private
-     */
-    _registerBridgeRoutes(coreApp) {
-        this._initControllers();
-
-        // 디스패치 테이블: "METHOD:path" → Map<appName, { route, middlewareFns }>
-        const dispatch = new Map();
-
-        for (const [appName, appEntry] of this._appRegistry) {
-            for (const route of appEntry.router.getRoutes()) {
-                const key = `${route.method}:${route.path}`;
-                if (!dispatch.has(key)) dispatch.set(key, new Map());
-
-                // 미들웨어 체인 사전 구성
-                const middlewareFns = [...this._globalMiddleware];
-                if (route.middleware?.length) {
-                    for (const mw of route.middleware) {
-                        // 함수면 직접 사용 (built-in: auth(), cors() 등)
-                        // 문자열이면 resolveMiddleware로 클래스 기반 조회
-                        if (typeof mw === 'function') {
-                            middlewareFns.push(mw);
-                        } else if (typeof mw === 'string') {
-                            const fn = this.resolveMiddleware(mw, appName);
-                            if (fn) middlewareFns.push(fn);
-                        }
-                    }
-                }
-
-                dispatch.get(key).set(appName, { route, middlewareFns });
-            }
-        }
-
-        // 유니크 path별 하나의 Bridge 핸들러 등록
-        for (const [key, appMap] of dispatch) {
-            const [method, routePath] = [key.split(':')[0].toLowerCase(), key.slice(key.indexOf(':') + 1)];
-            if (typeof coreApp[method] !== 'function') continue;
-
-            const bridgeHandler = this._createDispatchHandler(appMap);
-            coreApp[method](routePath, bridgeHandler);
-        }
-    }
-
-    /**
-     * WsHandler → Bridge WS 이벤트 연결 (모든 앱의 핸들러)
-     * @private
-     */
-    _registerWsHandlers(coreApp) {
-        if (!coreApp.ws) return;
-
-        for (const [, appEntry] of this._appRegistry) {
-            if (!appEntry.wsHandlers || appEntry.wsHandlers.size === 0) continue;
-
-            for (const [namespace, HandlerClass] of appEntry.wsHandlers) {
-                const eventMap = HandlerClass.buildEventMap();
-                const wsNs = coreApp.ws(namespace);
-
-                // 싱글톤 인스턴스
-                const inst = new HandlerClass(this);
-
-                wsNs.on('connect', (socket) => {
-                    this.logger.debug(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
-                    inst.onConnect(socket);
-                });
-
-                wsNs.on('message', (socket, rawMessage) => {
-                    let parsed;
-                    try { parsed = typeof rawMessage === 'string' ? JSON.parse(rawMessage) : rawMessage; }
-                    catch { parsed = { type: 'message', data: rawMessage }; }
-                    const eventType = parsed.type || 'message';
-                    const eventData = parsed.data || parsed;
-                    this.logger.debug(`[WS] msg: ${namespace} type=${eventType} sid=${socket.sessionId}`);
-                    const entry = eventMap.get(eventType);
-                    if (entry) {
-                        const result = entry.handler.call(inst, socket, eventData);
-                        if (result && typeof result.then === 'function') {
-                            result.then(r => { if (r) socket.send(JSON.stringify(r)); })
-                                  .catch(e => console.error(`[WS] error: ${eventType}`, e));
-                        } else if (result) {
-                            socket.send(JSON.stringify(result));
-                        }
-                    } else {
-                        inst.onEvent(socket, eventType, eventData);
-                    }
-                });
-
-                wsNs.on('disconnect', (socket) => {
-                    this.logger.debug(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
-                    inst.onDisconnect(socket);
-                });
-
-                this.logger.info(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
-            }
-        }
-    }
-
-    /**
-     * Host 기반 디스패치 핸들러 생성
-     *
-     * 동일 path에 대해 Host 헤더로 앱을 결정하고
-     * 해당 앱의 route + middleware 체인을 실행.
-     *
-     * @param {Map<string, {route, middlewareFns}>} appMap - appName → {route, middlewareFns}
-     * @returns {Function} Bridge 핸들러
-     * @private
-     */
-    _createDispatchHandler(appMap) {
-        return (req, res) => {
-            // Host 헤더에서 앱 결정 (reverse proxy: X-Forwarded-Host 우선)
-            const host = req.headers?.host || req.headers?.Host || '';
-            const appName = this._resolveApp(host, req.headers);
-
-            // 해당 앱의 route+middleware 찾기 (없으면 기본 앱)
-            let entry = appMap.get(appName);
-            if (!entry) {
-                // 매칭 앱에 이 경로가 없으면 기본 앱 시도
-                const defaultApp = this._getDefaultAppName();
-                entry = appMap.get(defaultApp);
-            }
-            if (!entry) {
-                // 어떤 앱에도 없으면 첫 번째 앱
-                entry = appMap.values().next().value;
-            }
-
-            const { route, middlewareFns } = entry;
-
-            // rawReq → Context
-            const ctx = new Context({
-                method: req.method,
-                url: req.url,
-                path: req.path,
-                query: req.query,
-                params: req.params,
-                headers: req.headers,
-                body: req.body || req.json,
-                remoteIp: req.ip,
-                handlerId: req.handlerId,
-                requestId: req.requestId,
-                sessionId: req.sessionId,
-                session: req.session?._data || {},
-                files: req.files || null,
-                formFields: req.formFields || null,
-            }, this);
-
-            ctx.appName = appName;
-
-            // async 체인 실행 → sendAsyncResponse
-            const promise = this._executeChain(middlewareFns, route, ctx);
-
-            promise.then(() => {
-                const response = ctx.toResponse();
-                const contentType = response.headers?.['Content-Type'] || 'application/json';
-                const headerParts = [];
-                if (response.headers) {
-                    for (const [k, v] of Object.entries(response.headers)) {
-                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
-                    }
-                }
-                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
-                try {
-                    this._coreApp._bridge.sendAsyncResponse(
-                        req.requestId, response.status,
-                        response.body || '', contentType, extraHeaders,
-                    );
-                } catch (e) {
-                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
-                }
-            }).catch((err) => {
-                console.error('[fuzionx] Handler error:', err.message || err);
-                try {
-                    this._coreApp._bridge.sendAsyncResponse(
-                        req.requestId, 500,
-                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
-                        'application/json', '',
-                    );
-                } catch (e) {
-                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
-                }
-            });
-
-            return { async: true };
-        };
-    }
-
-    /**
-     * 단일 라우트의 Bridge 핸들러 생성 (앱별)
-     * rawReq → Context → middleware → controller → toResponse
-     * @deprecated _createDispatchHandler를 사용하세요. 이 메서드는 테스트 호환용으로만 유지됩니다.
-     * @param {object} route
-     * @param {string} appName - 이 라우트가 속한 앱
-     * @private
-     */
-    _createBridgeHandler(route, appName) {
-        // 미들웨어 체인 사전 구성
-        const middlewareFns = [];
-
-        // 글로벌 미들웨어
-        middlewareFns.push(...this._globalMiddleware);
-
-        // 앱별 라우트 미들웨어 (이름 → 인스턴스 변환)
-        if (route.middleware?.length) {
-            for (const mwName of route.middleware) {
-                const fn = this.resolveMiddleware(mwName, appName);
-                if (fn) middlewareFns.push(fn);
-            }
-        }
-
-        return (req, res) => {
-            // rawReq → Context 변환
-            const ctx = new Context({
-                method: req.method,
-                url: req.url,
-                path: req.path,
-                query: req.query,
-                params: req.params,
-                headers: req.headers,
-                body: req.body || req.json,
-                remoteIp: req.ip,
-                handlerId: req.handlerId,
-                requestId: req.requestId,
-                sessionId: req.sessionId,
-                session: req.session?._data || {},
-                files: req.files || null,
-                formFields: req.formFields || null,
-            }, this);
-
-            // 앱 이름 주입
-            ctx.appName = appName;
-
-            // Framework → async 체인 실행 후 직접 sendAsyncResponse
-            const promise = this._executeChain(middlewareFns, route, ctx);
-
-            promise.then(() => {
-                const response = ctx.toResponse();
-                const contentType = response.headers?.['Content-Type'] || 'application/json';
-                const headerParts = [];
-                if (response.headers) {
-                    for (const [k, v] of Object.entries(response.headers)) {
-                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
-                    }
-                }
-                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
-                try {
-                    this._coreApp._bridge.sendAsyncResponse(
-                        req.requestId, response.status,
-                        response.body || '', contentType, extraHeaders,
-                    );
-                } catch (e) {
-                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
-                }
-            }).catch((err) => {
-                console.error('[fuzionx] Handler error:', err.message || err);
-                try {
-                    this._coreApp._bridge.sendAsyncResponse(
-                        req.requestId, 500,
-                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
-                        'application/json', '',
-                    );
-                } catch (e) {
-                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
-                }
-            });
-
-            return { async: true };
-        };
-    }
-
-    /**
-     * 미들웨어 체인 + 핸들러 실행
-     * @private
-     */
-    async _executeChain(middlewareFns, route, ctx) {
-        let idx = 0;
-
-        const next = async () => {
-            if (ctx._sent) return;
-            if (idx < middlewareFns.length) {
-                const fn = middlewareFns[idx++];
-                await fn(ctx, next);
-                return;
-            }
-
-            // 미들웨어 완료 → 핸들러 실행
-            await this._executeHandler(route.handler, ctx);
-        };
-
-        try {
-            await next();
-        } catch (err) {
-            // 커스텀 에러 핸들러 체크 (useError로 등록)
-            let handled = false;
-            for (const { path: ePath, handler } of this._errorHandlers) {
-                if (!ePath || ctx.path?.startsWith(ePath)) {
-                    try {
-                        await handler(err, ctx);
-                        handled = true;
-                        break;
-                    } catch { /* 커스텀 핸들러 실패 시 기본으로 */ }
-                }
-            }
-            if (!handled) this._errorHandler.handle(err, ctx);
-        }
-        // 응답은 _createBridgeHandler의 .then()에서 sendAsyncResponse로 전송
-    }
-
-    /**
-     * 핸들러 실행 (싱글톤 컨트롤러 or 일반 함수)
-     * @private
-     */
-    async _executeHandler(handler, ctx) {
-        if (handler?.__handler__) {
-            // 앱별 싱글톤 컨트롤러 메서드 참조
-            const appEntry = this._appRegistry.get(ctx.appName);
-            const instance = appEntry?.controllerCache?.get(handler.controller);
-            if (instance && typeof instance[handler.method] === 'function') {
-                await instance[handler.method](ctx);
-                return;
-            }
-        }
-
-        // 일반 함수 핸들러
-        if (typeof handler === 'function') {
-            await handler(ctx);
-        }
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Graceful Shutdown
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    _setupGracefulShutdown() {
-        let shutdownCalled = false;
-
-        const shutdown = async (signal) => {
-            if (shutdownCalled) return;
-            shutdownCalled = true;
-
-            this.logger.info(`[fuzionx] ${signal} received — shutting down`);
-            await this.emit('shutting-down', { signal });
-
-            // 1. 스케줄러 정지 (04-bootstrap-lifecycle.md)
-            if (this._scheduler) this._scheduler.stop();
-
-            // 2. 큐 drain — 처리 중 Task 완료 대기 (doc 04 순서 3)
-            if (this._queue && this._queue.pending > 0) {
-                this.logger.info(`[fuzionx] Draining queue (${this._queue.pending} pending)...`);
-                const drainTimeout = this.config.get('app.shutdown_timeout', 30000);
-                const start = Date.now();
-                while (this._queue.pending > 0 && (Date.now() - start) < drainTimeout) {
-                    await new Promise(r => setTimeout(r, 100));
-                }
-            }
-
-            // 3. DB 연결 해제 (ConnectionManager)
-            if (this._connectionManager) {
-                try { await this._connectionManager.closeAll(); } catch {}
-            }
-
-            // 3-1. Worker 종료
-            if (this._workerPool) {
-                try { await this._workerPool.terminate(); } catch {}
-            }
-
-            // 4. Bridge 서버 정지
-            if (this._coreApp?._bridge) {
-                try { this._coreApp._bridge.stopFusionServer(); } catch {}
-            }
-
-            await this.emit('shutdown');
-            setTimeout(() => process.exit(0), 2000);
-        };
-
-        process.once('SIGTERM', () => shutdown('SIGTERM'));
-        process.once('SIGINT', () => shutdown('SIGINT'));
-    }
-}
+/**
+ * Application — 서비스 컨테이너 + 부트스트랩 오케스트레이터 + Bridge 어댑터
+ *
+ * @fuzionx/core의 FuzionXApp을 내부적으로 사용하여 Bridge 서버 시작.
+ * rawReq → Context 변환 → 미들웨어 체인 → 컨트롤러 → toResponse().
+ *
+ * @see docs/framework/00-overview.md
+ * @see docs/framework/04-bootstrap-lifecycle.md
+ */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import cluster from 'node:cluster';
+import Config from './Config.js';
+import Context from './Context.js';
+import Router from '../http/Router.js';
+import ModelRegistry from '../database/ModelRegistry.js';
+import ErrorHandler from '../http/ErrorHandler.js';
+import AutoLoader from './AutoLoader.js';
+import Logger from '../helpers/Logger.js';
+import I18nHelper from '../helpers/I18nHelper.js';
+import CryptoHelper from '../helpers/CryptoHelper.js';
+import HashHelper from '../helpers/HashHelper.js';
+import MediaHelper from '../helpers/MediaHelper.js';
+import FileHelper from '../helpers/FileHelper.js';
+import View from '../view/View.js';
+import OpenAPI from '../view/OpenAPI.js';
+import Scheduler from '../schedule/Scheduler.js';
+import Queue from '../schedule/Queue.js';
+import Storage from '../services/Storage.js';
+import ConnectionManager from '../database/ConnectionManager.js';
+import SqlModel from '../database/SqlModel.js';
+import MongoModel from '../database/MongoModel.js';
+import WorkerPool from '../schedule/WorkerPool.js';
+
+// Bridge: lazy-load (테스트 환경에서 native 바인딩 없을 수 있음)
+let FuzionXApp;
+try {
+    const core = await import('@fuzionx/core');
+    FuzionXApp = core.FuzionXApp || core.RuxyApp;
+} catch (e) {
+    console.error('[fuzionx-framework] ⚠️  @fuzionx/core 로드 실패 — Bridge 없이 테스트 모드로 실행됩니다:',
+        e.message);
+}
+
+export default class Application {
+    /**
+     * @param {object} [opts]
+     * @param {object} [opts.config] - 이미 파싱된 설정 객체 또는 Config 인스턴스
+     * @param {string} [opts.configPath] - YAML 설정 파일 경로
+     * @param {string} [opts.baseDir='.'] - 프로젝트 루트 경로
+     * @param {object} [opts.bridge] - @fuzionx/core bridge 인스턴스 (선택)
+     */
+    constructor(opts = {}) {
+        // Config
+        if (opts.config instanceof Config) {
+            this.config = opts.config;
+        } else {
+            this.config = new Config(opts.config || {});
+        }
+
+        // 프로젝트 루트 (반드시 절대경로 — ESM import 호환)
+        this.baseDir = path.resolve(opts.baseDir || process.cwd());
+        this.configPath = opts.configPath || null;
+
+        // configPath 지정 시 YAML 파일에서 database/app/themes 등 로드
+        if (this.configPath) {
+            this.config.loadYaml(path.resolve(this.baseDir, this.configPath));
+        }
+
+        // Bridge 참조 (listen() 시 FuzionXApp 생성)
+        this._bridge = null;
+        this._coreApp = null;
+
+        // DI 컨테이너
+        this._services = new Map();
+        this._factories = new Map();
+
+        // 이벤트 핸들러
+        this._eventHandlers = new Map();
+        this._errorHandlers = [];
+
+        // 멀티앱 레지스트리 (도메인→앱 라우팅)
+        this._appRegistry = new Map();
+
+        // 글로벌 미들웨어
+        this._globalMiddleware = [];
+
+        // 프레임워크 컴포넌트
+        this.db = new ModelRegistry();
+        this.logger = new Logger({
+            level: this.config.get('bridge.logging.level', 'info'),
+            bridge: this._bridge,
+            json: this.config.get('bridge.logging.json', false),
+        });
+        this.crypto = new CryptoHelper(this._bridge);
+        this.hash = new HashHelper(this._bridge);
+        this.media = new MediaHelper(this._bridge);
+        this.file = new FileHelper(this._bridge);
+        this.ws = null;
+        this.i18n = new I18nHelper({
+            defaultLocale: this.config.get('app.i18n.default_locale', 'ko'),
+            fallback: this.config.get('app.i18n.fallback', 'en'),
+            dir: this.config.get('app.i18n.dir', './locales'),
+            bridge: this._bridge,
+        });
+        this.storage = null;
+        this._scheduler = null;
+        this._queue = null;
+        this._wsHandlers = new Map();
+
+        // DB 연결 매니저
+        this._connectionManager = new ConnectionManager();
+
+        // Worker 매니저 — shared/workers 기준
+        this._workerPool = new WorkerPool(this, {
+            workersDir: path.resolve(this.baseDir, 'shared/workers'),
+        });
+
+        /** @type {WorkerPool} public worker 접근 */
+        this.worker = this._workerPool;
+
+        // 에러 핸들러
+        this._errorHandler = new ErrorHandler({
+            isDev: this.config.get('app.environment', 'development') === 'development',
+            logger: (...args) => this.logger.error(...args),
+        });
+
+        // 라이프사이클 상태
+        this._booted = false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  DI — 서비스 컨테이너
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    register(name, factory) {
+        this._factories.set(name, factory);
+    }
+
+    make(name) {
+        if (this._services.has(name)) return this._services.get(name);
+        const factory = this._factories.get(name);
+        if (!factory) throw new Error(`Service '${name}' is not registered`);
+        const instance = factory(this);
+        this._services.set(name, instance);
+        return instance;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  라우터 접근
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 앱별 라우터 인스턴스
+     * @param {string} [appName] - 앱 이름 (미지정 시 첫 번째 앱)
+     */
+    getRouter(appName) {
+        const name = appName || this._getDefaultAppName();
+        return this._appRegistry.get(name)?.router || null;
+    }
+
+    /**
+     * 라우트 파일 로드 (특정 앱에)
+     * @param {Function} routeCallback - (r: RouteGroup) => void
+     * @param {string} [appName]
+     */
+    routes(routeCallback, appName) {
+        const name = appName || this._getDefaultAppName();
+        const entry = this._appRegistry.get(name);
+        if (entry?.router) entry.router.load(routeCallback);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  미들웨어
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 글로벌 미들웨어 등록
+     * @param {Function} fn - (ctx, next) => void
+     */
+    use(fn) {
+        this._globalMiddleware.push(fn);
+        return this;
+    }
+
+    /**
+     * 이름으로 미들웨어 인스턴스 조회
+     * @param {string} name - 'auth', 'csrf' 등
+     * @returns {Function} - (ctx, next) => void
+     */
+    /**
+     * @param {string} name - 미들웨어 이름 (e.g. 'auth', 'role:admin')
+     * @param {string} [appName] - 앱 이름 (앱별 미들웨어 우선 탐색)
+     */
+    resolveMiddleware(name, appName) {
+        // 캐시 히트 → zero-allocation (M-1)
+        const cacheKey = appName ? `${appName}:${name}` : name;
+        if (this._mwFnCache?.has(cacheKey)) return this._mwFnCache.get(cacheKey);
+
+        // 파라미터화: 'role:admin' → name='role', params=['admin']
+        const [mwName, ...params] = name.split(':');
+
+        // 앱별 미들웨어 우선 탐색 → 없으면 무시
+        let MwClass = null;
+        if (appName) {
+            const appEntry = this._appRegistry.get(appName);
+            MwClass = appEntry?.middlewareRegistry?.get(mwName) || null;
+        }
+        if (!MwClass) return null;
+
+        const instance = new MwClass(this);
+        const fn = (ctx, next) => instance.handle(ctx, next, ...params);
+
+        // 캐시 저장
+        if (!this._mwFnCache) this._mwFnCache = new Map();
+        this._mwFnCache.set(cacheKey, fn);
+        return fn;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  이벤트 시스템
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    on(event, handler) {
+        if (!this._eventHandlers.has(event)) {
+            this._eventHandlers.set(event, []);
+        }
+        this._eventHandlers.get(event).push(handler);
+    }
+
+    async emit(event, data, opts) {
+        const handlers = this._eventHandlers.get(event);
+        if (!handlers) return;
+        const meta = { remote: false, server: this.config.get('app.name', 'fuzionx'), timestamp: Date.now() };
+        for (const handler of handlers) {
+            try { await handler(data, meta); } catch (err) {
+                this.logger.error(`Event '${event}' handler error:`, err);
+            }
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  에러 핸들러
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    useError(pathOrHandler, handler) {
+        if (typeof pathOrHandler === 'function') {
+            this._errorHandlers.push({ path: null, handler: pathOrHandler });
+        } else {
+            this._errorHandlers.push({ path: pathOrHandler, handler });
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  큐 디스패치
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    dispatch(taskOrName, data, opts) {
+        if (this._queue) this._queue.dispatch(taskOrName, data, opts);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  부트스트랩
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    async boot() {
+        if (this._booted) return;
+
+        // 0. Bridge 초기화 — boot 로직 전에 bridge 확보
+        //    Helper(crypto/hash/media/file/i18n/logger/view)가 boot 중 bridge 필요
+        if (FuzionXApp && !this._coreApp) {
+            this._coreApp = new FuzionXApp({
+                config: this.configPath
+                    ? path.resolve(this.baseDir, this.configPath)
+                    : undefined,
+            });
+            this._bridge = this._coreApp._bridge;
+            this._propagateBridge();
+        }
+
+        // 1. .env 로드 (17-config.md)
+        this.config.loadEnv(this.baseDir);
+        // .env 로드 후 캐시 클리어 (새로운 환경변수 반영)
+        this.config._cache?.clear();
+
+        await this.emit('booting');
+
+        // 2. i18n 로드 (04-bootstrap-lifecycle.md)
+        await this.i18n.load();
+
+        // 3. Scheduler / Queue / Storage 초기화
+        this._scheduler = new Scheduler(this);
+        this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
+        this.storage = new Storage({
+            driver: this.config.get('storage.driver', 'local'),
+            basePath: path.resolve(this.baseDir, this.config.get('storage.path', './storage')),
+            fileHelper: this.file,
+        });
+
+        // 4. Phase 1: 공유 리소스 로드 (database/models, shared/events,jobs,workers)
+        const sharedLoader = new AutoLoader(this, this.baseDir, { mode: 'shared' });
+        await sharedLoader.load();
+
+        // 5. Phase 2: 앱별 리소스 로드 (app/{name}/controllers,routes,services,middleware,ws,views)
+        const appNames = this._getAppNames();
+        for (const name of appNames) {
+            const appDir = path.resolve(this.baseDir, 'app', name);
+            const appEntry = {
+                name,
+                router: new Router(),
+                controllers: new Map(),
+                controllerCache: new Map(),
+                middlewareRegistry: new Map(),
+                wsHandlers: new Map(),
+                view: new View({
+                    viewsPath: path.resolve(appDir, 'views'),
+                    theme: this.config.get('app.themes.default', 'default'),
+                    bridge: this._bridge,
+                }),
+            };
+            const appLoader = new AutoLoader(this, appDir, { mode: 'app', appContext: appEntry });
+            await appLoader.load();
+            this._appRegistry.set(name, appEntry);
+        }
+
+        // 6. DB 연결 매니저 초기화 (database 섹션이 있을 때만)
+        const dbConfig = this.config.get('database');
+        if (dbConfig) {
+            if (!dbConfig.connections) {
+                const connections = {};
+                for (const [key, val] of Object.entries(dbConfig)) {
+                    if (key !== 'default' && typeof val === 'object' && val !== null) {
+                        connections[key] = val;
+                    }
+                }
+                if (Object.keys(connections).length > 0) {
+                    dbConfig.connections = connections;
+                    if (!dbConfig.default) dbConfig.default = Object.keys(connections)[0];
+                }
+            }
+            if (dbConfig.connections) {
+                this._connectionManager.configure(dbConfig);
+                SqlModel.setConnectionManager(this._connectionManager);
+                MongoModel.setConnectionManager(this._connectionManager);
+            }
+        }
+
+        // 7. OpenAPI / Swagger UI 라우트 등록 (모든 앱의 라우트 통합)
+        this._registerDocsRoutes();
+
+        this._booted = true;
+
+        // hostname → appName 매핑 사전 계산 (매 요청 O(1) 조회)
+        this._hostAppMap = new Map();
+        const appsConfig = this.config.get('apps') || {};
+        for (const [hostname, appName] of Object.entries(appsConfig)) {
+            this._hostAppMap.set(hostname, appName);
+        }
+
+        await this.emit('booted');
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Multi-App 도메인 라우팅
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * config.apps에서 유니크 앱 이름 목록 추출
+     * @returns {string[]}
+     */
+    _getAppNames() {
+        const appsConfig = this.config.get('apps') || {};
+        return [...new Set(Object.values(appsConfig))];
+    }
+
+    /**
+     * 기본 앱 이름 (config.apps의 첫 번째 항목 값)
+     * @returns {string}
+     */
+    _getDefaultAppName() {
+        const appsConfig = this.config.get('apps') || {};
+        const values = Object.values(appsConfig);
+        return values[0] || 'fuzionx';
+    }
+
+    /**
+     * 호스트 → 앱 이름 결정
+     * reverse proxy 경유 시 X-Forwarded-Host 우선 사용.
+     * @param {string} host - 요청 Host 헤더 (port 포함 가능)
+     * @param {object} [headers] - 전체 요청 헤더 (proxy 지원)
+     * @returns {string} 앱 이름
+     */
+    _resolveApp(host, headers) {
+        // reverse proxy: X-Forwarded-Host > X-Original-Host > Host
+        const forwardedHost = headers?.['x-forwarded-host'] || headers?.['X-Forwarded-Host']
+            || headers?.['x-original-host'] || headers?.['X-Original-Host'];
+        const rawHost = forwardedHost || host || '';
+        const hostname = rawHost.split(':')[0]; // 포트 제거
+
+        // 사전 계산된 Map O(1) 조회
+        const mapped = this._hostAppMap?.get(hostname);
+        if (mapped) return mapped;
+
+        // 매칭 없으면 기본 앱
+        return this._getDefaultAppName();
+    }
+
+    /**
+     * Bridge 참조를 모든 Helper 인스턴스에 전파
+     * @private
+     */
+    _propagateBridge() {
+        if (!this._bridge) return;
+        // View는 앱별 → boot()에서 생성 시 bridge 주입됨
+        if (this.logger) this.logger._bridge = this._bridge;
+        if (this.crypto) this.crypto._bridge = this._bridge;
+        if (this.hash) this.hash._bridge = this._bridge;
+        if (this.media) this.media._bridge = this._bridge;
+        if (this.file) this.file._bridge = this._bridge;
+        if (this.i18n) this.i18n._bridge = this._bridge;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  서버 시작 — Bridge 연결
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * Bridge 서버 시작
+     * FuzionXApp과 연동하여 rawReq를 Context로 변환.
+     * @param {number} [port]
+     * @param {Function} [callback]
+     */
+    async listen(port, callback) {
+        if (typeof port === 'function') { callback = port; port = undefined; }
+        port = port ?? this.config.get('bridge.server.port') ?? this.config.get('bridge.port', 3000);
+
+        if (!this._booted) await this.boot();
+
+        // PID 파일 생성 (primary만)
+        if (!cluster.isWorker) {
+            await this._checkPort(port);
+            const pidPath = path.join(this.baseDir, 'fuzionx.pid');
+            await fs.writeFile(pidPath, String(process.pid));
+        }
+
+        // process.title 설정 (ps에서 보이는 프로세스 이름)
+        const appName = this.config.get('app.name', 'fuzionx');
+        if (cluster.isWorker) {
+            process.title = `${appName}-worker-${cluster.worker.id}`;
+        } else {
+            process.title = `${appName}-primary`;
+        }
+
+        await this.emit('ready');
+
+        // Bridge 연동 — _coreApp은 boot()에서 이미 생성됨
+        if (this._coreApp) {
+            // boot()에서 port 없이 생성됐으므로 port 설정
+            this._coreApp._port = port;
+
+            // WS proxy 연결 (WsHandler에서 this.app.ws 사용)
+            if (!this.ws) this.ws = this._coreApp.ws;
+
+            this._registerBridgeRoutes(this._coreApp);
+
+            // WsHandler → Bridge WS 이벤트 연결
+            this._registerWsHandlers(this._coreApp);
+
+            this._coreApp.listen(port, callback);
+            // Bridge가 자체 graceful shutdown 처리 → Framework 중복 등록 불필요
+        } else {
+            // Bridge 미설치 (테스트 환경)
+            this._initControllers();
+            if (callback) callback();
+            this._setupGracefulShutdown();
+        }
+
+        await this.emit('listening');
+
+        // Scheduler 시작 — primary 프로세스에서만 (워커 중복 실행 방지)
+        // fuzionx 상위 레이어가 cluster.fork()로 워커를 생성하므로
+        // cluster.isPrimary로 단일 프로세스 보장
+        if (this._scheduler && this._scheduler._jobs.length > 0 && !cluster.isWorker) {
+            this._scheduler.start();
+        }
+
+        return this;
+    }
+
+    /**
+     * 포트 사용 여부 확인 — 이미 바인딩된 포트면 명확한 에러
+     * @param {number} port
+     * @private
+     */
+    async _checkPort(port) {
+        const net = await import('node:net');
+        return new Promise((resolve) => {
+            const tester = net.createServer()
+                .once('error', (err) => {
+                    if (err.code === 'EADDRINUSE') {
+                        console.error(
+                            `\n❌ 포트 ${port}이(가) 이미 사용 중입니다.\n` +
+                            `   다른 FuzionX 인스턴스가 실행 중인지 확인하세요.\n` +
+                            `   확인: lsof -i :${port}\n` +
+                            `   종료: fuser -k ${port}/tcp\n`
+                        );
+                        process.exit(1);
+                    } else {
+                        console.error(`❌ 포트 ${port} 확인 실패:`, err.message);
+                        process.exit(1);
+                    }
+                })
+                .once('listening', () => {
+                    tester.close(() => resolve());
+                })
+                .listen(port, '0.0.0.0');
+        });
+    }
+
+    /**
+     * OpenAPI / Swagger UI 라우트 등록 (21-openapi.md)
+     *
+     * app.docs.enabled = true 시 활성화.
+     * 라우트: GET /docs, GET /docs/openapi.json, GET /docs/openapi.yaml
+     * @private
+     */
+    _registerDocsRoutes() {
+        const docsConfig = this.config.get('app.docs');
+        if (!docsConfig || docsConfig.enabled === false) return;
+
+        const docsPath = docsConfig.path || '/docs';
+
+        // 모든 앱의 라우트 통합
+        const allRoutes = [];
+        for (const [, appEntry] of this._appRegistry) {
+            allRoutes.push(...appEntry.router.getRoutes());
+        }
+
+        // OpenAPI spec 빌드 (1회, 캐싱)
+        this._openapi = new OpenAPI({
+            title: docsConfig.title || this.config.get('app.name', 'FuzionX') + ' API',
+            version: docsConfig.version || '1.0.0',
+            description: docsConfig.description || '',
+            servers: docsConfig.servers || [],
+        });
+        this._openapi.build(allRoutes);
+
+        // docs 라우트는 기본 앱의 라우터에 등록
+        const defaultAppName = this._getDefaultAppName();
+        const defaultApp = this._appRegistry.get(defaultAppName);
+        if (!defaultApp) return;
+
+        // JSON spec
+        defaultApp.router.get(`${docsPath}/openapi.json`, (ctx) => {
+            ctx.json(this._openapi.toJSON());
+        });
+
+        // YAML spec
+        defaultApp.router.get(`${docsPath}/openapi.yaml`, (ctx) => {
+            ctx.setHeader('Content-Type', 'text/yaml; charset=utf-8');
+            ctx.send(this._openapi.toYAML());
+        });
+
+        // Swagger UI HTML (CDN — 외부 의존 없음)
+        defaultApp.router.get(docsPath, (ctx) => {
+            const specUrl = `${docsPath}/openapi.json`;
+            const title = docsConfig.title || 'API Docs';
+            ctx.html(Application._swaggerHtml(title, specUrl));
+        });
+
+        this.logger.info(`[docs] Swagger UI → ${docsPath}`);
+    }
+
+    /**
+     * Swagger UI HTML 생성 (CDN 기반)
+     * @private
+     */
+    static _swaggerHtml(title, specUrl) {
+        return `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <style>
+    body { margin: 0; background: #fafafa; }
+    .topbar { display: none; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '${specUrl}',
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+      layout: 'BaseLayout',
+    });
+  </script>
+</body>
+</html>`;
+    }
+
+    /**
+     * 앱별 싱글톤 컨트롤러 초기화
+     * @private
+     */
+    _initControllers() {
+        for (const [, appEntry] of this._appRegistry) {
+            for (const route of appEntry.router.getRoutes()) {
+                const handler = route.handler;
+                if (handler?.__handler__ && handler.controller) {
+                    const CtrlClass = handler.controller;
+                    if (!appEntry.controllerCache.has(CtrlClass)) {
+                        appEntry.controllerCache.set(CtrlClass, new CtrlClass(this));
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 프레임워크 라우트 → Bridge 라우트 변환 (Host 기반 앱 디스패치)
+     *
+     * 동일 path에 여러 앱이 라우트를 가질 수 있으므로,
+     * 각 method+path 당 하나의 Bridge 핸들러를 등록하고
+     * 런타임에 Host 헤더로 앱을 결정한다.
+     *
+     * @private
+     */
+    _registerBridgeRoutes(coreApp) {
+        this._initControllers();
+
+        // 디스패치 테이블: "METHOD:path" → Map<appName, { route, middlewareFns }>
+        const dispatch = new Map();
+
+        for (const [appName, appEntry] of this._appRegistry) {
+            for (const route of appEntry.router.getRoutes()) {
+                const key = `${route.method}:${route.path}`;
+                if (!dispatch.has(key)) dispatch.set(key, new Map());
+
+                // 미들웨어 체인 사전 구성
+                const middlewareFns = [...this._globalMiddleware];
+                if (route.middleware?.length) {
+                    for (const mw of route.middleware) {
+                        // 함수면 직접 사용 (built-in: auth(), cors() 등)
+                        // 문자열이면 resolveMiddleware로 클래스 기반 조회
+                        if (typeof mw === 'function') {
+                            middlewareFns.push(mw);
+                        } else if (typeof mw === 'string') {
+                            const fn = this.resolveMiddleware(mw, appName);
+                            if (fn) middlewareFns.push(fn);
+                        }
+                    }
+                }
+
+                dispatch.get(key).set(appName, { route, middlewareFns });
+            }
+        }
+
+        // 유니크 path별 하나의 Bridge 핸들러 등록
+        for (const [key, appMap] of dispatch) {
+            const [method, routePath] = [key.split(':')[0].toLowerCase(), key.slice(key.indexOf(':') + 1)];
+            if (typeof coreApp[method] !== 'function') continue;
+
+            const bridgeHandler = this._createDispatchHandler(appMap);
+            coreApp[method](routePath, bridgeHandler);
+        }
+    }
+
+    /**
+     * WsHandler → Bridge WS 이벤트 연결 (모든 앱의 핸들러)
+     * @private
+     */
+    _registerWsHandlers(coreApp) {
+        if (!coreApp.ws) return;
+
+        for (const [, appEntry] of this._appRegistry) {
+            if (!appEntry.wsHandlers || appEntry.wsHandlers.size === 0) continue;
+
+            for (const [namespace, HandlerClass] of appEntry.wsHandlers) {
+                const eventMap = HandlerClass.buildEventMap();
+                const wsNs = coreApp.ws(namespace);
+
+                // 싱글톤 인스턴스
+                const inst = new HandlerClass(this);
+
+                wsNs.on('connect', (socket) => {
+                    this.logger.debug(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
+                    inst.onConnect(socket);
+                });
+
+                wsNs.on('message', (socket, rawMessage) => {
+                    let parsed;
+                    try { parsed = typeof rawMessage === 'string' ? JSON.parse(rawMessage) : rawMessage; }
+                    catch { parsed = { type: 'message', data: rawMessage }; }
+                    const eventType = parsed.type || 'message';
+                    const eventData = parsed.data || parsed;
+                    this.logger.debug(`[WS] msg: ${namespace} type=${eventType} sid=${socket.sessionId}`);
+                    const entry = eventMap.get(eventType);
+                    if (entry) {
+                        const result = entry.handler.call(inst, socket, eventData);
+                        if (result && typeof result.then === 'function') {
+                            result.then(r => { if (r) socket.send(JSON.stringify(r)); })
+                                  .catch(e => console.error(`[WS] error: ${eventType}`, e));
+                        } else if (result) {
+                            socket.send(JSON.stringify(result));
+                        }
+                    } else {
+                        inst.onEvent(socket, eventType, eventData);
+                    }
+                });
+
+                wsNs.on('disconnect', (socket) => {
+                    this.logger.debug(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
+                    inst.onDisconnect(socket);
+                });
+
+                this.logger.info(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
+            }
+        }
+    }
+
+    /**
+     * Host 기반 디스패치 핸들러 생성
+     *
+     * 동일 path에 대해 Host 헤더로 앱을 결정하고
+     * 해당 앱의 route + middleware 체인을 실행.
+     *
+     * @param {Map<string, {route, middlewareFns}>} appMap - appName → {route, middlewareFns}
+     * @returns {Function} Bridge 핸들러
+     * @private
+     */
+    _createDispatchHandler(appMap) {
+        return (req, res) => {
+            // Host 헤더에서 앱 결정 (reverse proxy: X-Forwarded-Host 우선)
+            const host = req.headers?.host || req.headers?.Host || '';
+            const appName = this._resolveApp(host, req.headers);
+
+            // 해당 앱의 route+middleware 찾기 (없으면 기본 앱)
+            let entry = appMap.get(appName);
+            if (!entry) {
+                // 매칭 앱에 이 경로가 없으면 기본 앱 시도
+                const defaultApp = this._getDefaultAppName();
+                entry = appMap.get(defaultApp);
+            }
+            if (!entry) {
+                // 어떤 앱에도 없으면 첫 번째 앱
+                entry = appMap.values().next().value;
+            }
+
+            const { route, middlewareFns } = entry;
+
+            // rawReq → Context
+            const ctx = new Context({
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                query: req.query,
+                params: req.params,
+                headers: req.headers,
+                body: req.body || req.json,
+                remoteIp: req.ip,
+                handlerId: req.handlerId,
+                requestId: req.requestId,
+                sessionId: req.sessionId,
+                session: req.session?._data || {},
+                files: req.files || null,
+                formFields: req.formFields || null,
+            }, this);
+
+            ctx.appName = appName;
+
+            // async 체인 실행 → sendAsyncResponse
+            const promise = this._executeChain(middlewareFns, route, ctx);
+
+            promise.then(() => {
+                const response = ctx.toResponse();
+                const contentType = response.headers?.['Content-Type'] || 'application/json';
+                const headerParts = [];
+                if (response.headers) {
+                    for (const [k, v] of Object.entries(response.headers)) {
+                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
+                    }
+                }
+                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, response.status,
+                        response.body || '', contentType, extraHeaders,
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+                }
+            }).catch((err) => {
+                console.error('[fuzionx] Handler error:', err.message || err);
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, 500,
+                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
+                        'application/json', '',
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
+                }
+            });
+
+            return { async: true };
+        };
+    }
+
+    /**
+     * 단일 라우트의 Bridge 핸들러 생성 (앱별)
+     * rawReq → Context → middleware → controller → toResponse
+     * @deprecated _createDispatchHandler를 사용하세요. 이 메서드는 테스트 호환용으로만 유지됩니다.
+     * @param {object} route
+     * @param {string} appName - 이 라우트가 속한 앱
+     * @private
+     */
+    _createBridgeHandler(route, appName) {
+        // 미들웨어 체인 사전 구성
+        const middlewareFns = [];
+
+        // 글로벌 미들웨어
+        middlewareFns.push(...this._globalMiddleware);
+
+        // 앱별 라우트 미들웨어 (이름 → 인스턴스 변환)
+        if (route.middleware?.length) {
+            for (const mwName of route.middleware) {
+                const fn = this.resolveMiddleware(mwName, appName);
+                if (fn) middlewareFns.push(fn);
+            }
+        }
+
+        return (req, res) => {
+            // rawReq → Context 변환
+            const ctx = new Context({
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                query: req.query,
+                params: req.params,
+                headers: req.headers,
+                body: req.body || req.json,
+                remoteIp: req.ip,
+                handlerId: req.handlerId,
+                requestId: req.requestId,
+                sessionId: req.sessionId,
+                session: req.session?._data || {},
+                files: req.files || null,
+                formFields: req.formFields || null,
+            }, this);
+
+            // 앱 이름 주입
+            ctx.appName = appName;
+
+            // Framework → async 체인 실행 후 직접 sendAsyncResponse
+            const promise = this._executeChain(middlewareFns, route, ctx);
+
+            promise.then(() => {
+                const response = ctx.toResponse();
+                const contentType = response.headers?.['Content-Type'] || 'application/json';
+                const headerParts = [];
+                if (response.headers) {
+                    for (const [k, v] of Object.entries(response.headers)) {
+                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
+                    }
+                }
+                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, response.status,
+                        response.body || '', contentType, extraHeaders,
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+                }
+            }).catch((err) => {
+                console.error('[fuzionx] Handler error:', err.message || err);
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, 500,
+                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
+                        'application/json', '',
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
+                }
+            });
+
+            return { async: true };
+        };
+    }
+
+    /**
+     * 미들웨어 체인 + 핸들러 실행
+     * @private
+     */
+    async _executeChain(middlewareFns, route, ctx) {
+        let idx = 0;
+
+        const next = async () => {
+            if (ctx._sent) return;
+            if (idx < middlewareFns.length) {
+                const fn = middlewareFns[idx++];
+                await fn(ctx, next);
+                return;
+            }
+
+            // 미들웨어 완료 → 핸들러 실행
+            await this._executeHandler(route.handler, ctx);
+        };
+
+        try {
+            await next();
+        } catch (err) {
+            // 커스텀 에러 핸들러 체크 (useError로 등록)
+            let handled = false;
+            for (const { path: ePath, handler } of this._errorHandlers) {
+                if (!ePath || ctx.path?.startsWith(ePath)) {
+                    try {
+                        await handler(err, ctx);
+                        handled = true;
+                        break;
+                    } catch { /* 커스텀 핸들러 실패 시 기본으로 */ }
+                }
+            }
+            if (!handled) this._errorHandler.handle(err, ctx);
+        }
+        // 응답은 _createBridgeHandler의 .then()에서 sendAsyncResponse로 전송
+    }
+
+    /**
+     * 핸들러 실행 (싱글톤 컨트롤러 or 일반 함수)
+     * @private
+     */
+    async _executeHandler(handler, ctx) {
+        if (handler?.__handler__) {
+            // 앱별 싱글톤 컨트롤러 메서드 참조
+            const appEntry = this._appRegistry.get(ctx.appName);
+            const instance = appEntry?.controllerCache?.get(handler.controller);
+            if (instance && typeof instance[handler.method] === 'function') {
+                await instance[handler.method](ctx);
+                return;
+            }
+        }
+
+        // 일반 함수 핸들러
+        if (typeof handler === 'function') {
+            await handler(ctx);
+        }
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Graceful Shutdown
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    _setupGracefulShutdown() {
+        let shutdownCalled = false;
+
+        const shutdown = async (signal) => {
+            if (shutdownCalled) return;
+            shutdownCalled = true;
+
+            this.logger.info(`[fuzionx] ${signal} received — shutting down`);
+            await this.emit('shutting-down', { signal });
+
+            // 1. 스케줄러 정지 (04-bootstrap-lifecycle.md)
+            if (this._scheduler) this._scheduler.stop();
+
+            // 2. 큐 drain — 처리 중 Task 완료 대기 (doc 04 순서 3)
+            if (this._queue && this._queue.pending > 0) {
+                this.logger.info(`[fuzionx] Draining queue (${this._queue.pending} pending)...`);
+                const drainTimeout = this.config.get('app.shutdown_timeout', 30000);
+                const start = Date.now();
+                while (this._queue.pending > 0 && (Date.now() - start) < drainTimeout) {
+                    await new Promise(r => setTimeout(r, 100));
+                }
+            }
+
+            // 3. DB 연결 해제 (ConnectionManager)
+            if (this._connectionManager) {
+                try { await this._connectionManager.closeAll(); } catch {}
+            }
+
+            // 3-1. Worker 종료
+            if (this._workerPool) {
+                try { await this._workerPool.terminate(); } catch {}
+            }
+
+            // 4. Bridge 서버 정지
+            if (this._coreApp?._bridge) {
+                try { this._coreApp._bridge.stopFusionServer(); } catch {}
+            }
+
+            await this.emit('shutdown');
+            setTimeout(() => process.exit(0), 2000);
+        };
+
+        process.once('SIGTERM', () => shutdown('SIGTERM'));
+        process.once('SIGINT', () => shutdown('SIGINT'));
+    }
+}