@fuzionx/framework 0.1.69 → 0.1.71

package/cli/templates/make/app-spa/views/default/spa/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@fuzionx/player": "^0.1.69",
+    "@fuzionx/player": "^0.1.71",
     "pinia": "^3.0.4",
     "vue": "^3.5.0",
     "vue-router": "^4.5.0"

package/lib/core/Application.js

@@ -32,6 +32,7 @@ import CacheManager from '../cache/CacheManager.js';
 import SqlModel from '../database/SqlModel.js';
 import MongoModel from '../database/MongoModel.js';
 import WorkerPool from '../schedule/WorkerPool.js';
+import TelegramManager from '../utilities/TelegramManager.js';
 
 // Bridge: lazy-load (테스트 환경에서 native 바인딩 없을 수 있음)
 let FuzionXApp;
@@ -109,6 +110,8 @@ export default class Application {
         this._scheduler = null;
         this._queue = null;
         this._wsHandlers = new Map();
+        
+        this.telegram = null;
 
         // DB 연결 매니저
         this._connectionManager = new ConnectionManager();
@@ -139,10 +142,20 @@ export default class Application {
         this._factories.set(name, factory);
     }
 
-    make(name) {
+    /**
+     * 서비스 인스턴스 생성/조회 (Singleton)
+     *
+     * @param {string} name - 서비스 이름 (e.g. 'AuthService' 또는 'frontend:AuthService')
+     * @param {boolean} [silent=false] - true이면 미등록 시 에러 대신 null 반환
+     * @returns {*} 서비스 인스턴스 또는 null (silent=true 시)
+     */
+    make(name, silent = false) {
         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`);
+        if (!factory) {
+            if (silent) return null;
+            throw new Error(`Service '${name}' is not registered`);
+        }
         const instance = factory(this);
         this._services.set(name, instance);
         return instance;
@@ -285,9 +298,16 @@ export default class Application {
         // 2. i18n 로드 (04-bootstrap-lifecycle.md)
         await this.i18n.load();
 
-        // 3. Scheduler / Queue / Storage / Cache 초기화
+        // 3. Scheduler / Queue / Telegram / Storage / Cache 초기화
         this._scheduler = new Scheduler(this);
         this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
+        
+        // 텔레그램 매니저 로드 (Queue 기반이므로 _queue 설정 직후 구성)
+        const telegramConfig = this.config.get('app.telegram');
+        if (telegramConfig && telegramConfig.enabled !== false) {
+            this.telegram = new TelegramManager(this, telegramConfig);
+        }
+
         this.storage = new Storage({
             driver: this.config.get('storage.driver', 'local'),
             basePath: path.resolve(this.baseDir, this.config.get('storage.path', './storage')),
@@ -646,7 +666,9 @@ export default class Application {
                 if (handler?.__handler__ && handler.controller) {
                     const CtrlClass = handler.controller;
                     if (!appEntry.controllerCache.has(CtrlClass)) {
-                        appEntry.controllerCache.set(CtrlClass, new CtrlClass(this));
+                        const instance = new CtrlClass(this);
+                        instance._appName = appEntry.name; // 앱별 서비스 격리를 위한 네임스페이스 주입
+                        appEntry.controllerCache.set(CtrlClass, instance);
                     }
                 }
             }
@@ -813,6 +835,7 @@ export default class Application {
                 chainResult = this._executeSyncChain(middlewareFns, ctx, resolvedHandler);
             }
         } catch (err) {
+            console.error(`[FX] Unhandled controller error: ${ctx.method} ${ctx.path}`, err);
             this._handleContextError(err, ctx);
             return ctx._toFusionResponse();
         }
@@ -828,6 +851,7 @@ export default class Application {
                 this._sendContextResponse(rawReq.requestId, ctx);
             })
             .catch((err) => {
+                console.error(`[FX] Unhandled controller error: ${ctx.method} ${ctx.path}`, err);
                 this._handleContextError(err, ctx);
                 this._sendContextResponse(rawReq.requestId, ctx);
             });
@@ -948,6 +972,34 @@ export default class Application {
         }
     }
 
+    /**
+     * WS 핸들러 수동 등록 — shared/ws 핸들러를 앱별 레지스트리에 추가
+     *
+     * boot() 이후, listen() 이전에 호출.
+     * listen() 내부의 _registerWsHandlers()가 등록된 핸들러를 Bridge에 연결.
+     *
+     * @example
+     *   await app.boot();
+     *   import NotificationHandler from './shared/ws/NotificationHandler.js';
+     *   app.registerWsHandler(NotificationHandler);          // 기본 앱에 등록
+     *   app.registerWsHandler(NotificationHandler, 'frontend'); // 특정 앱에 등록
+     *   await app.listen();
+     *
+     * @param {typeof import('./WsHandler.js').default} HandlerClass - WsHandler 서브클래스
+     * @param {string} [appName] - 등록할 앱 이름 (미지정 시 첫 번째 앱)
+     */
+    registerWsHandler(HandlerClass, appName) {
+        const name = appName || this._getDefaultAppName();
+        const appEntry = this._appRegistry.get(name);
+        if (!appEntry) {
+            this.logger.warn(`[WS] registerWsHandler: 앱 '${name}'을(를) 찾을 수 없습니다.`);
+            return;
+        }
+        const ns = HandlerClass.namespace || '/';
+        appEntry.wsHandlers.set(ns, HandlerClass);
+        this.logger.debug(`[WS] 수동 등록: ${ns} → 앱 '${name}'`);
+    }
+
     /**
      * Host 기반 디스패치 핸들러 생성 (최적화 v2)
      *
@@ -1214,6 +1266,17 @@ export default class Application {
             }
         }
         this._errorHandler.handle(err, ctx);
+
+        // 'error' 이벤트 발행 — 앱 레벨에서 ErrorLog 기록용 (fire-and-forget)
+        this.emit('error', {
+            error: err,
+            method: ctx.method,
+            path: ctx.path,
+            appName: ctx.appName,
+            user: ctx.user || null,
+            ip: ctx.ip,
+            userAgent: ctx.get?.('user-agent') || '',
+        }).catch(() => {});
     }
 
     /**

package/lib/core/AutoLoader.js

@@ -144,7 +144,13 @@ export default class AutoLoader {
         }
     }
 
-    /** services/*.js → DI register (앱별 네임스페이스) */
+    /**
+     * services/*.js → DI register (앱별 네임스페이스)
+     *
+     * 앱 모드에서는 'appName:ServiceName' 키로 앱별 격리 등록 +
+     * 'ServiceName' 키로 글로벌 등록 (backward compatibility).
+     * 동일 이름 서비스가 여러 앱에 존재하면 앱별 키로 격리됨.
+     */
     async loadServices() {
         const files = await scanDir(path.join(this.baseDir, 'services'));
         for (const file of files) {
@@ -152,7 +158,21 @@ export default class AutoLoader {
             const ServiceClass = mod.default;
             if (!ServiceClass) continue;
             const name = extractName(file, 'Service');
-            this.app.register(`${name}Service`, (app) => new ServiceClass(app));
+            const globalKey = `${name}Service`;
+            const appName = this._appContext?.name;
+
+            /** 앱별 scoped 등록 (e.g. 'frontend:AuthService') */
+            if (appName) {
+                const scopedKey = `${appName}:${globalKey}`;
+                this.app.register(scopedKey, (app) => {
+                    const instance = new ServiceClass(app);
+                    instance._appName = appName; // 서비스 내에서 다른 서비스 호출 시에도 앱 격리 유지
+                    return instance;
+                });
+            }
+
+            /** 글로벌 등록 (마지막 앱이 덮어씀 — backward compatibility) */
+            this.app.register(globalKey, (app) => new ServiceClass(app));
         }
     }
 

package/lib/core/Base.js

@@ -19,14 +19,32 @@ export default class Base {
         this.config = app.config;
         /** @type {object} Logger */
         this.logger = app.logger;
+        /**
+         * 앱 네임스페이스 — 서비스 resolve 시 앱별 격리에 사용
+         * Controller/Service 생성 시 주입됨.
+         * @type {string|null}
+         */
+        this._appName = null;
     }
 
     /**
-     * 서비스 조회 (DI)
-     * @param {string} name
+     * 서비스 조회 (DI) — 앱별 네임스페이스 자동 적용
+     *
+     * resolve 순서:
+     *   1. _appName이 있으면 'appName:ServiceName' 우선 조회
+     *   2. fallback으로 글로벌 'ServiceName' 조회
+     *
+     * 이 패턴으로 동일 이름의 서비스가 backend/frontend에 각각 존재해도
+     * 앱 코드에서는 this.service('AuthService')로 호출 가능.
+     *
+     * @param {string} name - 서비스 이름 (e.g. 'AuthService')
      * @returns {*}
      */
     service(name) {
+        if (this._appName) {
+            const scoped = this.app.make(`${this._appName}:${name}`, true);
+            if (scoped) return scoped;
+        }
         return this.app.make(name);
     }
 

package/lib/http/ErrorHandler.js

@@ -27,9 +27,11 @@ export default class ErrorHandler {
     handle(err, ctx) {
         const status = err.status || 500;
 
-        // 500 에러는 로깅
+        // 모든 에러 로깅: 500+ → error, 400+ → warn
         if (status >= 500) {
             this.logger(err);
+        } else if (status >= 400) {
+            this.logger(`[${status}] ${ctx.method} ${ctx.path} — ${err.message}`);
         }
 
         // JSON 응답 요청이면 JSON으로

package/lib/realtime/RoomManager.js

@@ -67,6 +67,19 @@ export default class RoomManager {
         return this._rooms.has(room) && this._rooms.get(room).size > 0;
     }
 
+    /**
+     * 소켓이 속한 룸 목록 조회
+     * @param {string} socketId
+     * @returns {string[]}
+     */
+    roomsOf(socketId) {
+        const result = [];
+        for (const [room, members] of this._rooms) {
+            if (members.has(socketId)) result.push(room);
+        }
+        return result;
+    }
+
     /**
      * 전체 룸 목록
      * @returns {string[]}

package/lib/schedule/TelegramTask.js

@@ -0,0 +1,80 @@
+import Task from './Task.js';
+
+/**
+ * TelegramTask - 텔레그램 메시지 발송을 위한 비동기 백그라운드 큐 작업
+ * 
+ * I/O 바운드 작업으로, 메인 스레드의 블로킹을 방지하고
+ * 텔레그램 API의 Rate-Limit(429) 응답에 대비하여 자동 재시도 기능을 제공합니다.
+ */
+export default class TelegramTask extends Task {
+    /** @type {string} 큐의 고유 이름 */
+    static queue = 'telegram';
+
+    /** @type {number} 실패 시 최대 재시도 횟수 */
+    static retries = 3;
+
+    /** @type {number} 실패 시 다음 재시도 대기 시간 (밀리초) - 텔레그램 속도 제한 방어 */
+    static retryDelay = 3000;
+
+    /** @type {number} API 호출 제한 시간 (밀리초) */
+    static timeout = 10000;
+
+    /**
+     * 작업의 실행 본문
+     * 
+     * @param {Object} data 디스패치 될 때 넘어온 데이터
+     * @param {string} data.botToken 봇의 인증 토큰
+     * @param {string} data.chatId 수신 대상 채팅/채널 ID
+     * @param {string} data.text 발송할 메시지 내용
+     * @param {string} [data.parseMode='HTML'] 파싱 모드 (HTML, MarkdownV2 등)
+     * @returns {Promise<void>}
+     */
+    async handle(data) {
+        const { botToken, chatId, text, parseMode = 'HTML' } = data;
+
+        if (!botToken || !chatId || !text) {
+            throw new Error('텔레그램 발송 누락 데이터: botToken, chatId 또는 text가 없습니다.');
+        }
+
+        const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+        
+        try {
+            // Node.js 환경의 전역 fetch (v18+)
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    text: text,
+                    parse_mode: parseMode,
+                }),
+            });
+
+            if (!response.ok) {
+                // Rate-Limit 이나 서버 에러의 경우, 이 에러가 throw 되어 Queue.js 의 catch 블록으로 이동, 재시도 됨
+                const errorText = await response.text();
+                throw new Error(`텔레그램 API 에러 (${response.status}): ${errorText}`);
+            }
+        } catch (error) {
+            // 네트워크 연결 실패 등 예기치 않은 오류 시 재시도를 위해 상위로 에러 던지기
+            throw error;
+        }
+    }
+
+    /**
+     * 모든 재시도 소진 후 최종적으로 실패했을 때 호출되는 훅
+     * 
+     * @param {Object} data 
+     * @param {Error} error 
+     */
+    async failed(data, error) {
+        // Application 객체(this.app)를 통해 코어 로거에 치명적 에러 기록
+        if (this.app && this.app.logger) {
+            this.app.logger.error(`[TelegramTask] 메시지 발송 최종 실패 (대상 채널: ${data.chatId}):`, error.message);
+        } else {
+            console.error(`[TelegramTask] 메시지 발송 최종 실패:`, error.message);
+        }
+    }
+}

package/lib/services/Storage.js

@@ -147,7 +147,8 @@ export default class Storage {
             // AWS S3 기본 URL
             return `https://${this._s3.bucket}.s3.${this._s3.region || 'us-east-1'}.amazonaws.com/${filePath}`;
         }
-        return `/storage/${filePath}`;
+        // return `/storage/${filePath}`;
+        return filePath;
     }
 
     // ── S3 호환 스토리지 구현 (@aws-sdk/client-s3) ──

package/lib/utilities/TelegramManager.js

@@ -0,0 +1,120 @@
+import TelegramTask from '../schedule/TelegramTask.js';
+
+/**
+ * TelegramBot - 개별 텔레그램 봇의 인스턴스를 래핑합니다.
+ * 백그라운드 큐 시스템에 전송 요청을 위임하여 병목을 방지합니다.
+ */
+class TelegramBot {
+    /**
+     * @param {import('../core/Application.js').default} app 프레임워크 애플리케이션 인스턴스
+     * @param {string} token 봇 API 인증 토큰
+     * @param {string} chatId 수신 채팅/채널 ID
+     */
+    constructor(app, token, chatId) {
+        this.app = app;
+        this.token = token;
+        this.chatId = chatId;
+    }
+
+    /**
+     * 비동기로 텔레그램 메시지를 발송 (Queue에 적재)
+     * 
+     * @param {string} text 보낼 메시지 내용
+     * @param {Object} [options] 전송 옵션
+     * @param {string} [options.parseMode='HTML'] 파싱 포맷 (HTML, MarkdownV2 등)
+     */
+    sendMessage(text, options = {}) {
+        const parseMode = options.parseMode || 'HTML';
+        if (this.app._queue) {
+            this.app._queue.dispatch('TelegramTask', {
+                botToken: this.token,
+                chatId: this.chatId,
+                text: text,
+                parseMode: parseMode
+            });
+        } else {
+            this.app.logger.warn('[TelegramBot] 앱 큐(Queue) 시스템이 비활성화 되어 있어 메시지가 전송되지 않았습니다.');
+        }
+    }
+
+    /**
+     * HTML 파싱을 지원하는 전송 헬퍼 메서드
+     * @param {string} html 
+     */
+    sendHtml(html) {
+        return this.sendMessage(html, { parseMode: 'HTML' });
+    }
+
+    /**
+     * MarkdownV2 파싱을 지원하는 전송 헬퍼 메서드
+     * @param {string} markdown 
+     */
+    sendMarkdown(markdown) {
+        return this.sendMessage(markdown, { parseMode: 'MarkdownV2' });
+    }
+}
+
+/**
+ * TelegramManager - yaml 설정에 등록된 복수 개의 텔레그램 봇 인스턴스를 관리합니다.
+ * 프레임워크 코어 컨테이너에 의해 싱글톤으로 유지됩니다.
+ */
+export default class TelegramManager {
+    /**
+     * @param {import('../core/Application.js').default} app 
+     * @param {Object} config fuzionx.yaml 의 app.telegram 설정 객체
+     */
+    constructor(app, config) {
+        this.app = app;
+        this.config = config || {};
+        this._bots = new Map();
+
+        this._initialize();
+    }
+
+    /**
+     * 큐에 환경을 구성하고 봇 목록을 구성합니다.
+     * @private
+     */
+    _initialize() {
+        // 백그라운드 워커에 텔레그램 전송 작업을 담당할 클래스 명세 등록
+        if (this.app._queue) {
+            this.app._queue.register('TelegramTask', TelegramTask);
+        }
+
+        // yaml 설정 파일 기반 봇 초기화
+        const botsConfig = this.config.bots || {};
+        for (const [name, info] of Object.entries(botsConfig)) {
+            if (info.token && info.chat_id) {
+                // 숫자로 된 채널 ID도 문자열로 변환하여 보존 처리
+                const chatIdStr = String(info.chat_id);
+                this._bots.set(name, new TelegramBot(this.app, info.token, chatIdStr));
+            } else {
+                this.app.logger.warn(`[TelegramManager] '${name}' 봇 설정 오류: token 또는 chat_id가 확인되지 않습니다.`);
+            }
+        }
+    }
+
+    /**
+     * 등록된 특정 이름의 봇 인스턴스를 가져옵니다.
+     * @param {string} name 봇의 고유 명칭 (예: 'system', 'billing')
+     * @returns {TelegramBot|null} 봇 인스턴스 또는 null
+     */
+    get(name) {
+        return this._bots.get(name) || null;
+    }
+
+    /**
+     * 원하는 대상 봇에게 체인 없이 한 번에 직접 메시지를 보냅니다.
+     * @param {string} name 발송할 봇 명칭
+     * @param {string} text 메시지 내용
+     * @param {Object} [options] 파싱 모드 등 옵션 (get(name) 이후 sendMessage 와 동일)
+     */
+    send(name, text, options) {
+        const bot = this.get(name);
+        if (bot) {
+            bot.sendMessage(text, options);
+        } else {
+            this.app.logger.warn(`[TelegramManager] 설정 파일에 명명된 봇 '${name}'을 찾을 수 없습니다.`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1028.0",
-    "@fuzionx/core": "^0.1.69",
+    "@fuzionx/core": "^0.1.71",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",