@fuzionx/framework 0.1.70 → 0.1.72

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

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@fuzionx/player": "^0.1.70",
+    "@fuzionx/player": "^0.1.72",
     "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);
                     }
                 }
             }
@@ -830,7 +852,18 @@ export default class Application {
             })
             .catch((err) => {
                 console.error(`[FX] Unhandled controller error: ${ctx.method} ${ctx.path}`, err);
-                this._handleContextError(err, ctx);
+                try {
+                    this._handleContextError(err, ctx);
+                } catch (handlerErr) {
+                    // 에러 핸들링 자체 실패 → 최소한의 500 응답 보장
+                    console.error(`[FX] Error handler failed:`, handlerErr);
+                    try {
+                        ctx._statusCode = 500;
+                        ctx._body = JSON.stringify({ error: { message: err.message, status: 500 } });
+                        ctx._headers['Content-Type'] = 'application/json';
+                        ctx._sent = true;
+                    } catch { /* ctx 조작도 실패하면 포기 */ }
+                }                
                 this._sendContextResponse(rawReq.requestId, ctx);
             });
 
@@ -950,6 +983,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)
      *
@@ -1201,20 +1262,29 @@ export default class Application {
 
     /**
      * Context 에러 핸들링 — ctx에 에러 응답 설정
+     *
+     * 커스텀 에러 핸들러(useError)는 부가 작업(알림 등)용으로,
+     * 기본 에러 응답 설정(ErrorHandler.handle)은 항상 실행된다.
+     *
      * @param {Error} err - 발생한 에러
      * @param {object} ctx - Context 인스턴스
      * @private
      */
     _handleContextError(err, ctx) {
-        // 커스텀 에러 핸들러 체크 (useError로 등록)
+        // 커스텀 에러 핸들러 실행 (fire-and-forget — 알림, 로깅 등 부가 작업)
         for (const { path: ePath, handler } of this._errorHandlers) {
             if (!ePath || ctx.path?.startsWith(ePath)) {
                 try {
-                    handler(err, ctx);
-                    return;
-                } catch { /* 커스텀 핸들러 실패 시 기본으로 */ }
+                    const result = handler(err, ctx);
+                    // async 핸들러 → 에러 무시 (알림 실패가 응답에 영향 X)
+                    if (result && typeof result.then === 'function') {
+                        result.catch(() => {});
+                    }
+                } catch { /* 커스텀 핸들러 sync 에러 무시 */ }
             }
         }
+
+        // 기본 에러 응답 설정 (항상 실행 — ctx에 status/body 세팅)
         this._errorHandler.handle(err, ctx);
 
         // 'error' 이벤트 발행 — 앱 레벨에서 ErrorLog 기록용 (fire-and-forget)

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

@@ -34,8 +34,14 @@ export default class ErrorHandler {
             this.logger(`[${status}] ${ctx.method} ${ctx.path} — ${err.message}`);
         }
 
-        // JSON 응답 요청이면 JSON으로
-        const wantsJson = ctx.get('accept')?.includes('application/json')
+        // JSON 응답 판단 — 요청 헤더 기반 (경로 하드코딩 X)
+        //   1. Accept 헤더에 application/json 포함 (SPA fetch/axios 기본)
+        //   2. Content-Type이 JSON (JSON 요청 본문)
+        //   3. X-Requested-With: XMLHttpRequest (AJAX 요청)
+        //   4. /api 경로 (fallback — 헤더 없는 경우 대비)
+        const accept = ctx.get('accept') || '';
+        const wantsJson = accept.includes('application/json')
+            || (!accept.includes('text/html') && ctx.get('x-requested-with') === 'XMLHttpRequest')
             || ctx.is('json')
             || ctx.path?.startsWith('/api');
 
@@ -117,22 +123,134 @@ export default class ErrorHandler {
             } catch {}
         }
 
-        // 3. 프레임워크 내장 에러 페이지 (XSS 방지)
+        // 3. 프레임워크 내장 에러 페이지 (모던 디자인 — XSS 방지)
         const esc = (s) => String(s)
             .replace(/&/g, '&amp;').replace(/</g, '&lt;')
             .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
-        const title = status >= 500 ? 'Server Error' : esc(err.message);
+        // 상태 코드별 제목/이모지/색상 분기
+        const statusMap = {
+            400: { emoji: '⚠️', label: 'Bad Request', desc: '잘못된 요청입니다.', color: '#f59e0b' },
+            401: { emoji: '🔒', label: 'Unauthorized', desc: '인증이 필요합니다.', color: '#6366f1' },
+            403: { emoji: '🚫', label: 'Forbidden', desc: '접근 권한이 없습니다.', color: '#ef4444' },
+            404: { emoji: '🔍', label: 'Not Found', desc: '요청한 페이지를 찾을 수 없습니다.', color: '#8b5cf6' },
+            500: { emoji: '💥', label: 'Server Error', desc: '서버에서 오류가 발생했습니다.', color: '#ef4444' },
+            502: { emoji: '🌐', label: 'Bad Gateway', desc: '게이트웨이 오류가 발생했습니다.', color: '#f97316' },
+            503: { emoji: '🔧', label: 'Service Unavailable', desc: '서비스를 일시적으로 이용할 수 없습니다.', color: '#f59e0b' },
+        };
+        const info = statusMap[status] || {
+            emoji: status >= 500 ? '💥' : '⚠️',
+            label: status >= 500 ? 'Server Error' : 'Error',
+            desc: esc(err.message),
+            color: status >= 500 ? '#ef4444' : '#f59e0b',
+        };
+
+        // 개발 모드: 스택 트레이스 블록
+        const stackBlock = this.isDev && err.stack
+            ? `<details class="stack" open>
+                <summary>Stack Trace</summary>
+                <pre>${esc(err.stack)}</pre>
+               </details>` : '';
+
+        // 개발 모드: 요청 정보
+        const reqBlock = this.isDev
+            ? `<div class="req-info">
+                <span class="method">${esc(ctx.method)}</span>
+                <span class="path">${esc(ctx.url)}</span>
+               </div>` : '';
 
         ctx.status(status).html(
-            `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${status}</title>` +
-            `<style>body{font-family:system-ui,-apple-system,sans-serif;max-width:600px;margin:80px auto;` +
-            `padding:0 20px;color:#333}h1{color:#e74c3c;}pre{background:#f5f5f5;padding:16px;border-radius:8px;` +
-            `overflow-x:auto;font-size:13px;}</style></head>` +
-            `<body><h1>${status} — ${title}</h1>` +
-            `<p>요청: ${esc(ctx.method)} ${esc(ctx.url)}</p>` +
-            `${this.isDev && err.stack ? `<pre>${esc(err.stack)}</pre>` : ''}` +
-            `</body></html>`
+            `<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${status} — ${esc(info.label)}</title>
+<style>
+  *{margin:0;padding:0;box-sizing:border-box}
+  :root{--bg:#0f0f11;--card:#18181b;--border:#27272a;--text:#fafafa;--sub:#a1a1aa;--accent:${info.color}}
+  @media(prefers-color-scheme:light){
+    :root{--bg:#f8f9fa;--card:#fff;--border:#e5e7eb;--text:#18181b;--sub:#71717a}
+  }
+  body{
+    font-family:'Inter',system-ui,-apple-system,'Segoe UI',sans-serif;
+    background:var(--bg);color:var(--text);
+    min-height:100vh;display:flex;align-items:center;justify-content:center;
+    padding:20px;
+  }
+  .container{
+    max-width:520px;width:100%;text-align:center;
+  }
+  .status-code{
+    font-size:120px;font-weight:800;line-height:1;
+    background:linear-gradient(135deg,var(--accent),color-mix(in srgb,var(--accent) 60%,#fff));
+    -webkit-background-clip:text;-webkit-text-fill-color:transparent;
+    background-clip:text;
+    letter-spacing:-4px;margin-bottom:8px;
+    animation:fadeIn .5s ease-out;
+  }
+  .emoji{font-size:48px;margin-bottom:16px;display:block;animation:bounce .6s ease-out}
+  .card{
+    background:var(--card);border:1px solid var(--border);
+    border-radius:16px;padding:40px 32px;
+    box-shadow:0 4px 24px rgba(0,0,0,.12);
+    animation:slideUp .4s ease-out;
+  }
+  h1{font-size:18px;font-weight:600;margin-bottom:8px;color:var(--text)}
+  .desc{color:var(--sub);font-size:14px;line-height:1.6;margin-bottom:24px}
+  .home-btn{
+    display:inline-flex;align-items:center;gap:6px;
+    padding:10px 24px;border-radius:8px;font-size:14px;font-weight:500;
+    background:var(--accent);color:#fff;
+    text-decoration:none;transition:all .2s;
+    border:none;cursor:pointer;
+  }
+  .home-btn:hover{opacity:.85;transform:translateY(-1px)}
+  .req-info{
+    margin-top:20px;padding:10px 16px;
+    background:color-mix(in srgb,var(--bg) 80%,var(--card));
+    border-radius:8px;font-size:12px;font-family:'Menlo','Consolas',monospace;
+    color:var(--sub);display:flex;gap:8px;justify-content:center;align-items:center;
+  }
+  .method{
+    background:var(--accent);color:#fff;padding:2px 8px;border-radius:4px;
+    font-weight:600;font-size:11px;
+  }
+  .stack{
+    margin-top:20px;text-align:left;
+  }
+  .stack summary{
+    font-size:12px;color:var(--sub);cursor:pointer;margin-bottom:8px;
+    font-weight:500;
+  }
+  .stack pre{
+    background:color-mix(in srgb,var(--bg) 80%,var(--card));
+    border:1px solid var(--border);border-radius:8px;
+    padding:16px;font-size:11px;line-height:1.5;
+    overflow-x:auto;color:var(--sub);font-family:'Menlo','Consolas',monospace;
+    max-height:300px;overflow-y:auto;
+  }
+  .footer{margin-top:32px;font-size:11px;color:var(--sub)}
+  @keyframes fadeIn{from{opacity:0;transform:scale(.9)}to{opacity:1;transform:scale(1)}}
+  @keyframes slideUp{from{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}}
+  @keyframes bounce{0%{transform:scale(0)}50%{transform:scale(1.2)}100%{transform:scale(1)}}
+</style>
+</head>
+<body>
+<div class="container">
+  <div class="card">
+    <span class="emoji">${info.emoji}</span>
+    <div class="status-code">${status}</div>
+    <h1>${esc(info.label)}</h1>
+    <p class="desc">${esc(info.desc)}</p>
+    <a href="/" class="home-btn">← 홈으로</a>
+    ${reqBlock}
+    ${stackBlock}
+  </div>
+  <p class="footer">FuzionX Framework</p>
+</div>
+</body>
+</html>`
         );
     }
 }

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/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.70",
+  "version": "0.1.72",
   "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.70",
+    "@fuzionx/core": "^0.1.72",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",