@fuzionx/framework 0.1.75 → 0.1.76

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

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

package/lib/core/Application.js

@@ -12,6 +12,7 @@ import { promises as fs } from 'node:fs';
 import cluster from 'node:cluster';
 import Config from './Config.js';
 import Context, { createContext, createContextFromReq } from './Context.js';
+import { ServiceError } from './AppError.js';
 import Router from '../http/Router.js';
 import ModelRegistry from '../database/ModelRegistry.js';
 import ErrorHandler from '../http/ErrorHandler.js';
@@ -709,6 +710,14 @@ export default class Application {
 
                 // 미들웨어 체인 사전 구성 (부트 시 1회)
                 const middlewareFns = [...this._globalMiddleware];
+
+                // route.validate 옵션 → Validation 미들웨어를 라우트별 미들웨어 *앞*에 삽입
+                // (글로벌 미들웨어 이후, 라우트 미들웨어 이전 — 입력 정규화는 인증/권한 검사보다 늦게,
+                //  핸들러 진입 직전에 — 이 순서를 따르도록 라우트 미들웨어 앞에 둠)
+                if (route.validate) {
+                    middlewareFns.push(this._createValidateMiddleware(route.validate));
+                }
+
                 if (route.middleware?.length) {
                     for (const mw of route.middleware) {
                         if (typeof mw === 'function') {
@@ -783,8 +792,12 @@ export default class Application {
     _handleRawRequest(rawReq) {
         const dispatch = this._rawDispatch[rawReq.handlerId];
         if (!dispatch) {
-            // handlerId 미등록 → 404
-            return { status: 404, body: '{"error":"Not Found"}', headers: { 'Content-Type': 'application/json' } };
+            // 라우트 미매칭 → ErrorHandler 합류 (Accept 협상)
+            return this._buildErrorResponse(
+                rawReq,
+                this._getDefaultAppName(),
+                new ServiceError('Not Found', 404),
+            );
         }
 
         // ── 도메인 검증 (모든 요청에 대해 수행) ──
@@ -794,11 +807,11 @@ export default class Application {
         // 미등록 도메인 → 403 차단
         if (!resolvedAppName) {
             const reqHost = rawReq.headers?.host || 'unknown';
-            return {
-                status: 403,
-                body: JSON.stringify({ error: 'Forbidden', message: `도메인 '${reqHost}'은(는) 등록되지 않았습니다.` }),
-                headers: { 'Content-Type': 'application/json; charset=utf-8' },
-            };
+            return this._buildErrorResponse(
+                rawReq,
+                this._getDefaultAppName(),
+                new ServiceError(`도메인 '${reqHost}'은(는) 등록되지 않았습니다.`, 403),
+            );
         }
 
         // ── 앱 결정 (단일 앱: O(0), 멀티앱: Host 기반) ──
@@ -810,11 +823,11 @@ export default class Application {
             appName = resolvedAppName;
             entry = dispatch.appMap.get(appName);
             if (!entry) {
-                return {
-                    status: 403,
-                    body: JSON.stringify({ error: 'Forbidden', message: `앱 '${appName}'을(를) 찾을 수 없습니다.` }),
-                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
-                };
+                return this._buildErrorResponse(
+                    rawReq,
+                    appName,
+                    new ServiceError(`앱 '${appName}'을(를) 찾을 수 없습니다.`, 403),
+                );
             }
         }
 
@@ -826,6 +839,8 @@ export default class Application {
         ctx.appName = appName;
 
         // ── Sync-first 실행 ──
+        // 핸들러/미들웨어 throw → _handleContextError 가 ErrorHandler 로깅까지 책임지므로
+        // 여기서는 별도 console 출력 없이 ctx 응답만 만든다 (중복 로그 방지).
         let chainResult;
         try {
             if (middlewareFns.length === 0) {
@@ -835,7 +850,6 @@ 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();
         }
@@ -851,12 +865,11 @@ export default class Application {
                 this._sendContextResponse(rawReq.requestId, ctx);
             })
             .catch((err) => {
-                console.error(`[FX] Unhandled controller error: ${ctx.method} ${ctx.path}`, err);
                 try {
                     this._handleContextError(err, ctx);
                 } catch (handlerErr) {
-                    // 에러 핸들링 자체 실패 → 최소한의 500 응답 보장
-                    console.error(`[FX] Error handler failed:`, handlerErr);
+                    // 에러 핸들링 자체 실패 → 최소한의 500 응답 보장 (logger도 실패 가능성 → console 유지)
+                    this.logger?.error?.('[FX] ErrorHandler 자체 실패:', handlerErr);
                     try {
                         ctx._statusCode = 500;
                         ctx._body = JSON.stringify({ error: { message: err.message, status: 500 } });
@@ -937,6 +950,11 @@ export default class Application {
     _registerWsHandlers(coreApp) {
         if (!coreApp.ws) return;
 
+        // WS connect/message/disconnect 추적 로그는 채팅 트래픽 등에서 폭주하므로
+        // bridge.logging.ws_trace 옵션이 명시적으로 true일 때만 출력.
+        const wsTrace = !!this.config.get('bridge.logging.ws_trace', false);
+        const logger = this.logger;
+
         for (const [, appEntry] of this._appRegistry) {
             if (!appEntry.wsHandlers || appEntry.wsHandlers.size === 0) continue;
 
@@ -948,7 +966,7 @@ export default class Application {
                 const inst = new HandlerClass(this);
 
                 wsNs.on('connect', (socket) => {
-                    this.logger.debug(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
+                    if (wsTrace) logger.debug(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
                     inst.onConnect(socket);
                 });
 
@@ -958,13 +976,13 @@ export default class Application {
                     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}`);
+                    if (wsTrace) 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));
+                                  .catch(e => logger.error(`[WS] error: ${eventType}`, e));
                         } else if (result) {
                             socket.send(JSON.stringify(result));
                         }
@@ -974,14 +992,20 @@ export default class Application {
                 });
 
                 wsNs.on('disconnect', (socket) => {
-                    this.logger.debug(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
+                    if (wsTrace) logger.debug(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
                     inst.onDisconnect(socket);
                 });
 
                 // 원격 메타데이터 변경 이벤트 (Hub METADATA_UPDATE → onRemoteMetadataUpdate)
-                wsNs.on('metadata_update', (socket, key, value) => {
-                    inst.onRemoteMetadataUpdate(socket, key, value);
-                });
+                // core가 이 이벤트를 지원하지 않으면 (옛 버전) 조용히 건너뛴다 — 부팅 실패 방지.
+                // Hub 멀티서버 메타데이터 동기화 기능을 쓰지 않으면 영향 없음.
+                try {
+                    wsNs.on('metadata_update', (socket, key, value) => {
+                        inst.onRemoteMetadataUpdate(socket, key, value);
+                    });
+                } catch (e) {
+                    logger.debug(`[WS] '${namespace}' metadata_update 미지원 — 건너뜀 (${e.message})`);
+                }
 
                 this.logger.info(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
             }
@@ -1265,6 +1289,85 @@ export default class Application {
         }
     }
 
+    /**
+     * route.validate 옵션 → 미들웨어로 변환.
+     *
+     * 미들웨어 체인에서 실행되며, ValidationError 발생 시 _handleContextError 경로를 탐.
+     * Validation 인스턴스(Joi 기반)는 lazy 생성 — 첫 호출 시에만 joi import.
+     * Joi가 사용자 프로젝트에 설치되지 않은 경우 검증을 건너뛰고 경고를 1회 출력한다.
+     *
+     * @param {object} validateOpts - { body?, query?, params? } Joi 스키마 또는 간단문법 객체
+     * @returns {Function} async 미들웨어 (ctx, next) => Promise<void>
+     * @private
+     */
+    _createValidateMiddleware(validateOpts) {
+        return async (ctx, next) => {
+            const runner = await this._getValidationRunner();
+            if (!runner) {
+                // Joi 없음 → 검증 건너뜀 (경고는 _getValidationRunner에서 1회만 출력)
+                return next();
+            }
+            const result = runner.run(ctx, validateOpts);
+            // 검증된 데이터(stripUnknown 포함)를 ctx에 반영
+            if (result.body !== undefined) ctx.body = result.body;
+            if (result.query !== undefined) ctx.query = result.query;
+            if (result.params !== undefined) ctx.params = result.params;
+            await next();
+        };
+    }
+
+    /**
+     * Validation 러너 lazy 가져오기 — Joi import + 인스턴스 캐싱.
+     *
+     * @returns {Promise<import('../http/Validation.js').default|null>}
+     * @private
+     */
+    async _getValidationRunner() {
+        if (this._validationRunner !== undefined) return this._validationRunner;
+        try {
+            const joiMod = await import('joi');
+            const Joi = joiMod.default || joiMod;
+            const Validation = (await import('../http/Validation.js')).default;
+            this._validationRunner = new Validation(Joi);
+        } catch (e) {
+            // joi 미설치 → 검증 건너뜀. 경고는 1회.
+            this.logger.warn(
+                `[Validation] joi가 설치되지 않아 route.validate 옵션이 무시됩니다 — ${e.message}`,
+            );
+            this._validationRunner = null;
+        }
+        return this._validationRunner;
+    }
+
+    /**
+     * 디스패치 이전(라우트 미매칭/도메인 거부 등) 발생한 에러용 응답 생성기.
+     *
+     * 미들웨어 체인 없이 즉시 ErrorHandler로 흘려서 Accept 협상을 통과시킴.
+     * 동기 경로이므로 Fusion 응답을 그대로 반환한다.
+     *
+     * @param {object} rawReq - Bridge 원시 요청
+     * @param {string} appName - 응답에 적용할 앱 이름(테마/뷰 lookup용)
+     * @param {Error} err - ServiceError 또는 일반 Error
+     * @returns {object} Fusion 응답 객체
+     * @private
+     */
+    _buildErrorResponse(rawReq, appName, err) {
+        // async-safe 새 인스턴스 (sync 공유 인스턴스 오염 방지 — 이 경로는 cold path)
+        const ctx = createContext(rawReq, this, false);
+        ctx.appName = appName || this._getDefaultAppName();
+        try {
+            this._handleContextError(err, ctx);
+        } catch (handlerErr) {
+            // 에러 핸들링 자체 실패 → 최소 500 응답 보장
+            this.logger.error('[FX] ErrorHandler 자체 실패:', handlerErr);
+            ctx._statusCode = 500;
+            ctx._body = JSON.stringify({ error: { message: err?.message || 'Internal Error', status: 500 } });
+            ctx._headers['Content-Type'] = 'application/json; charset=utf-8';
+            ctx._sent = true;
+        }
+        return ctx._toFusionResponse();
+    }
+
     /**
      * Context 에러 핸들링 — ctx에 에러 응답 설정
      *
@@ -1335,7 +1438,7 @@ export default class Application {
                 response.body || '', contentType, extraHeaders,
             );
         } catch (e) {
-            console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+            this.logger.error('[fuzionx] sendAsyncResponse 실패:', e.message);
         }
     }
 

package/lib/core/Base.js

@@ -1,3 +1,5 @@
+import { ServiceError } from './AppError.js';
+
 /**
  * Base — 공통 기본 클래스
  *
@@ -82,4 +84,15 @@ export default class Base {
 
     /** @returns {import('../cache/CacheManager.js').default|null} 캐시 매니저 */
     get cache() { return this.app._cacheManager || null; }
+
+    /**
+     * 비즈니스 로직 에러 생성 헬퍼
+     * @param {string} message - 에러 메시지
+     * @param {number} [status=400] - HTTP 상태 코드
+     * @param {object|null} [data=null] - 추가 데이터
+     * @returns {import('./AppError.js').ServiceError}
+     */
+    error(message, status = 400, data = null) {
+        return new ServiceError(message, status, data);
+    }
 }

package/lib/core/Context.js

@@ -486,7 +486,12 @@ function _createSession(rawReq, app) {
             data[key] = value;
             if (sessionId && bridge?.sessionSet) {
                 try { bridge.sessionSet(sessionId, { ...data }); }
-                catch (e) { console.error('[Session] sessionSet failed:', e?.message || e); }
+                catch (e) {
+                    // app.logger가 있으면 거기로, 없으면 stderr 보장 차원에서 console.error 폴백
+                    const msg = e?.message || e;
+                    if (app?.logger?.warn) app.logger.warn('[Session] sessionSet 실패:', msg);
+                    else console.error('[Session] sessionSet failed:', msg);
+                }
             }
         },
 

package/lib/http/ErrorHandler.js

@@ -52,28 +52,55 @@ export default class ErrorHandler {
         return this._htmlResponse(err, ctx, status);
     }
 
+    /**
+     * ValidationError(또는 422) HTML 컨텍스트 처리:
+     *   - ctx.session.flash('errors', fields) + flash('old', body)
+     *   - Referer로 리다이렉트(없으면 '/')
+     * 세션이 없거나 flash 호출 자체가 실패하면 false 반환 → 일반 HTML 페이지 폴백.
+     *
+     * @param {ValidationError} err
+     * @param {object} ctx
+     * @returns {boolean} 처리 성공 여부
+     * @private
+     */
+    _tryFlashRedirect(err, ctx) {
+        const flash = ctx.session?.flash;
+        if (typeof flash !== 'function') return false;
+        try {
+            flash.call(ctx.session, 'errors', err.fields || {});
+            if (ctx.body && typeof ctx.body === 'object') {
+                flash.call(ctx.session, 'old', ctx.body);
+            }
+            const back = (typeof ctx.get === 'function' && ctx.get('referer')) || '/';
+            ctx.redirect(back);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
     /** @private */
     _jsonResponse(err, ctx, status) {
+        const t = typeof ctx.t === 'function' ? ctx.t.bind(ctx) : (msg) => msg;
+        const translatedMessage = t(err.message) || err.message;
+
         const body = {
-            error: {
-                message: err.message,
-                status,
-            },
+            error: translatedMessage,
         };
 
         // ValidationError → 필드 에러 포함
         if (err instanceof ValidationError) {
-            body.error.fields = err.fields;
+            body.fields = err.fields;
         }
 
         // dev 모드에서 스택 노출
         if (this.isDev && status >= 500) {
-            body.error.stack = err.stack;
+            body.stack = err.stack;
         }
 
         // 추가 데이터
         if (err.data && !(err instanceof ValidationError)) {
-            body.error.data = err.data;
+            body.data = err.data;
         }
 
         ctx.status(status).json(body);
@@ -87,9 +114,18 @@ export default class ErrorHandler {
      * 2. views/{theme}/errors/default.html
      * 3. 프레임워크 내장 에러 페이지
      *
+     * View.render는 템플릿이 없으면 throw하므로 try/catch만으로 폴백 가능.
+     * (이전 휴리스틱 `<!-- template:` 검사는 Tera 출력에 존재하지 않아 무용 — 제거)
+     *
      * @private
      */
     _htmlResponse(err, ctx, status) {
+        // ── ValidationError + 세션 사용 가능 → 플래시 + 이전 페이지로 리다이렉트 (폼 흐름) ──
+        // docs/framework/08-error-handling.md 명세: HTML 컨텍스트의 422는 redirect back
+        if (err instanceof ValidationError && this._tryFlashRedirect(err, ctx)) {
+            return;
+        }
+
         const errorData = {
             error: {
                 code: status,
@@ -104,23 +140,22 @@ export default class ErrorHandler {
         const appEntry = ctx.app?._appRegistry?.get(ctx.appName);
         const view = this._view || appEntry?.view;
         if (view) {
-            const theme = ctx.theme || ctx.app?.config?.get('themes.default', 'default') || 'default';
             // 1. views/{theme}/errors/{code}.html
             try {
                 const html = view.render(`errors/${status}`, errorData);
-                if (html && !html.startsWith('<!-- template:')) {
+                if (html) {
                     ctx.status(status).html(html);
                     return;
                 }
-            } catch {}
+            } catch { /* 템플릿 없음 → 다음 폴백 */ }
             // 2. views/{theme}/errors/default.html
             try {
                 const html = view.render('errors/default', errorData);
-                if (html && !html.startsWith('<!-- template:')) {
+                if (html) {
                     ctx.status(status).html(html);
                     return;
                 }
-            } catch {}
+            } catch { /* 템플릿 없음 → 내장 에러 페이지로 폴백 */ }
         }
 
         // 3. 프레임워크 내장 에러 페이지 (모던 디자인 — XSS 방지)

package/lib/http/Validation.js

@@ -7,9 +7,20 @@
  */
 import { ValidationError } from '../core/AppError.js';
 
+/** type 룰: base schema 를 결정 (modifier 와 분리해 순서 무관 처리) */
+const TYPE_RULES = new Set(['string', 'number', 'integer', 'boolean', 'date', 'array']);
+
 /**
  * 간단 규칙 문자열을 Joi 스키마로 변환
- * @param {object} rules - { name: 'required|min:2', email: 'required|email' }
+ *
+ * 규칙은 두 그룹으로 분리되어 처리된다:
+ *   1) type 룰 (string/number/integer/boolean/date/array) — base schema 결정
+ *   2) modifier 룰 (required/optional/nullable/min/max/email/url/in/positive/alpha)
+ *
+ * type 룰을 먼저 적용하고 그 위에 modifier 를 쌓는 방식이라
+ * 'required|string' / 'string|required' 어느 순서로 써도 동일하게 동작한다.
+ *
+ * @param {object} rules - { name: 'required|min:2', email: 'string|email|nullable' }
  * @param {object} Joi - Joi 모듈 참조
  * @returns {import('joi').ObjectSchema}
  */
@@ -18,41 +29,62 @@ export function parseRules(rules, Joi) {
 
     for (const [field, rule] of Object.entries(rules)) {
         const parts = typeof rule === 'string' ? rule.split('|') : [];
-        let schema = Joi.any();
 
+        // 1단계: type 룰과 modifier 룰 분리 (type 은 마지막 선언 우선)
+        let typeName = null;
+        const modifiers = [];
         for (const part of parts) {
+            const [name] = part.split(':');
+            if (TYPE_RULES.has(name)) typeName = name;
+            else modifiers.push(part);
+        }
+
+        // 2단계: base schema 결정
+        let schema;
+        switch (typeName) {
+            case 'string':  schema = Joi.string(); break;
+            case 'number':  schema = Joi.number(); break;
+            case 'integer': schema = Joi.number().integer(); break;
+            case 'boolean': schema = Joi.boolean(); break;
+            case 'date':    schema = Joi.date(); break;
+            case 'array':   schema = Joi.array(); break;
+            default:        schema = Joi.any();
+        }
+
+        // 3단계: modifier 적용 (type 추론 가능한 룰은 base 가 any 이면 자동 승격)
+        for (const part of modifiers) {
             const [name, ...args] = part.split(':');
 
             switch (name) {
-                case 'string':
-                    schema = Joi.string(); break;
-                case 'number':
-                    schema = Joi.number(); break;
-                case 'boolean':
-                    schema = Joi.boolean(); break;
                 case 'required':
                     schema = schema.required(); break;
                 case 'optional':
                     schema = schema.optional(); break;
+                case 'nullable':
+                    // null 허용 — 클라이언트가 미입력 필드를 null 로 보내는 패턴 지원
+                    schema = schema.allow(null); break;
+                case 'empty':
+                    // 빈 문자열 허용 — Joi.string() 은 기본적으로 '' 를 거부하므로
+                    // 폼이 미입력 필드를 빈 문자열로 보내는 경우 명시적 허용 필요
+                    schema = schema.allow(''); break;
                 case 'min':
                     schema = schema.min(Number(args[0])); break;
                 case 'max':
                     schema = schema.max(Number(args[0])); break;
                 case 'email':
-                    // 기존 schema가 Joi.any()면 string()으로 교체, 이미 string()이면 유지
-                    schema = (schema.type === 'any' ? Joi.string() : schema).email(); break;
+                    if (schema.type === 'any') schema = Joi.string();
+                    schema = schema.email(); break;
                 case 'url':
-                    schema = (schema.type === 'any' ? Joi.string() : schema).uri(); break;
-                case 'in':
-                    schema = schema.valid(...args[0].split(',')); break;
-                case 'integer':
-                    schema = schema.integer ? schema.integer() : Joi.number().integer(); break;
+                    if (schema.type === 'any') schema = Joi.string();
+                    schema = schema.uri(); break;
                 case 'positive':
-                    schema = schema.positive ? schema.positive() : Joi.number().positive(); break;
-                case 'date':
-                    schema = schema.type === 'any' ? Joi.date() : schema; break;
+                    if (schema.type === 'any') schema = Joi.number();
+                    schema = schema.positive(); break;
                 case 'alpha':
-                    schema = (schema.type === 'any' ? Joi.string() : schema).alphanum(); break;
+                    if (schema.type === 'any') schema = Joi.string();
+                    schema = schema.alphanum(); break;
+                case 'in':
+                    schema = schema.valid(...args[0].split(',')); break;
                 default:
                     // 알 수 없는 규칙은 무시
                     break;
@@ -86,13 +118,13 @@ export default class Validation {
         const result = {};
 
         if (validateOpts.body) {
-            result.body = this._validate(ctx.body, validateOpts.body);
+            result.body = this._validate(ctx, ctx.body, validateOpts.body);
         }
         if (validateOpts.query) {
-            result.query = this._validate(ctx.query, validateOpts.query);
+            result.query = this._validate(ctx, ctx.query, validateOpts.query);
         }
         if (validateOpts.params) {
-            result.params = this._validate(ctx.params, validateOpts.params);
+            result.params = this._validate(ctx, ctx.params, validateOpts.params);
         }
 
         return result;
@@ -101,7 +133,7 @@ export default class Validation {
     /**
      * @private
      */
-    _validate(data, schema) {
+    _validate(ctx, data, schema) {
         // 간단문법 객체 → Joi 변환
         if (schema && typeof schema === 'object' && !schema.validate) {
             schema = parseRules(schema, this._Joi);
@@ -114,8 +146,19 @@ export default class Validation {
 
         if (error) {
             const fields = {};
+            const translate = typeof ctx.t === 'function' ? ctx.t : () => '';
+
             for (const detail of error.details) {
-                fields[detail.path.join('.')] = detail.message;
+                // 1. 필드명 다국어 번역 시도 (예: username -> 아이디)
+                // fields.username 키가 없으면 원래 영문 필드명 사용
+                const fieldName = translate(`fields.${detail.context.key}`) || detail.context.key;
+                
+                // 2. Joi 에러 타입별 다국어 매핑 (예: any.required -> {field}은(는) 필수입니다)
+                // detail.context 에는 limit, val 등의 추가 제약 정보가 포함되어 있음
+                const i18nMsg = translate(`validation.${detail.type}`, { ...detail.context, field: fieldName });
+                
+                // 3. 번역된 메세지가 없으면 Joi의 기본 영문 메세지 fallback
+                fields[detail.path.join('.')] = i18nMsg || detail.message;
             }
             throw new ValidationError('Validation failed', fields);
         }

package/lib/middleware/apiAuth.js

@@ -3,13 +3,17 @@
  *
  * Authorization: Bearer <token> → 검증 → ctx.user
  *
+ * 인증 실패 시 ServiceError(401) throw → ErrorHandler가 Accept 협상으로 응답.
+ *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.secret] - JWT 시크릿
  * @param {string} [opts.model='User']
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { ServiceError } from '../core/AppError.js';
 
 export function apiAuth(opts = {}) {
     const modelName = opts.model || 'User';
@@ -18,29 +22,27 @@ export function apiAuth(opts = {}) {
         const authHeader = ctx.get('authorization') || '';
 
         if (!authHeader.startsWith('Bearer ')) {
-            ctx.status(401).json({ error: { message: 'Token required', status: 401 } });
-            return;
+            throw new ServiceError('Token required', 401);
         }
 
         const token = authHeader.slice(7);
+        const secret = opts.secret || ctx.app?.config?.get('app.auth.secret', 'fuzionx');
 
+        let payload;
         try {
-            const secret = opts.secret || ctx.app?.config?.get('app.auth.secret', 'fuzionx');
-            const payload = decodeJwtPayload(token, secret);
+            payload = decodeJwtPayload(token, secret);
+        } catch {
+            throw new ServiceError('Invalid token', 401);
+        }
 
-            if (!payload || !payload.sub) {
-                ctx.status(401).json({ error: { message: 'Invalid token', status: 401 } });
-                return;
-            }
+        if (!payload || !payload.sub) {
+            throw new ServiceError('Invalid token', 401);
+        }
 
-            if (ctx.app?.db?.[modelName]) {
-                ctx.user = await ctx.app.db[modelName].find(payload.sub);
-            } else {
-                ctx.user = { id: payload.sub, ...payload };
-            }
-        } catch {
-            ctx.status(401).json({ error: { message: 'Invalid token', status: 401 } });
-            return;
+        if (ctx.app?.db?.[modelName]) {
+            ctx.user = await ctx.app.db[modelName].find(payload.sub);
+        } else {
+            ctx.user = { id: payload.sub, ...payload };
         }
 
         await next();

package/lib/middleware/auth.js

@@ -3,13 +3,20 @@
  *
  * ctx.session.userId → db.User.find() → ctx.user
  *
+ * 미인증 처리:
+ *   - redirectTo 지정 시: 해당 URL로 302 리다이렉트 (HTML 라우트용)
+ *   - 미지정 시: ServiceError(401) throw → ErrorHandler가 Accept 협상으로 응답 형식 결정
+ *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.sessionKey='userId']
  * @param {string} [opts.model='User']
- * @param {string} [opts.redirectTo='/login']
+ * @param {string} [opts.redirectTo] - 미지정 시 401 throw, 지정 시 해당 URL로 redirect
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function auth(opts = {}) {
     const sessionKey = opts.sessionKey || 'userId';
     const modelName = opts.model || 'User';
@@ -21,10 +28,9 @@ export function auth(opts = {}) {
         if (!userId) {
             if (redirectTo) {
                 ctx.redirect(redirectTo);
-            } else {
-                ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
+                return;
             }
-            return;
+            throw new ServiceError('Unauthorized', 401);
         }
 
         if (ctx.app?.db?.[modelName]) {

package/lib/middleware/csrf.js

@@ -2,13 +2,17 @@
  * csrf — CSRF 보호 미들웨어
  *
  * GET/HEAD/OPTIONS 는 통과, 나머지는 토큰 검증.
+ * 토큰 불일치 시 ServiceError(403) throw → ErrorHandler가 Accept 협상으로 응답.
  *
  * @see docs/framework/12-middleware.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {object} [opts]
  * @param {string} [opts.headerName='x-csrf-token']
  * @param {string} [opts.sessionKey='_csrfToken']
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function csrf(opts = {}) {
     const headerName = opts.headerName || 'x-csrf-token';
     const sessionKey = opts.sessionKey || '_csrfToken';
@@ -23,8 +27,7 @@ export function csrf(opts = {}) {
         const expected = ctx._rawReq?.session?.[sessionKey];
 
         if (!token || !expected || token !== expected) {
-            ctx.status(403).json({ error: { message: 'CSRF token mismatch', status: 403 } });
-            return;
+            throw new ServiceError('CSRF token mismatch', 403);
         }
 
         await next();

package/lib/middleware/roleGuard.js

@@ -4,6 +4,10 @@
  * `auth()` 미들웨어 이후에 사용.
  * ctx.user.role_code가 허용된 역할 목록에 포함되는지 검사.
  *
+ * 거부 시 ServiceError throw → ErrorHandler가 Accept 협상으로 응답.
+ *   - 미인증: 401
+ *   - 권한 부족: 403
+ *
  * @example
  * // 관리자 백오피스: developer, admin만 허용
  * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin'])] }, (r) => { ... });
@@ -12,6 +16,7 @@
  * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin', 'reseller'])] }, (r) => { ... });
  *
  * @see docs/framework/14-authentication.md
+ * @see docs/framework/08-error-handling.md
  *
  * @param {string[]} allowedRoles - 접근 허용 역할 코드 배열
  * @param {object} [opts]
@@ -19,6 +24,8 @@
  * @param {string} [opts.message='auth.role_denied'] - 거부 시 에러 메시지 키
  * @returns {Function} 미들웨어 함수
  */
+import { ServiceError } from '../core/AppError.js';
+
 export function roleGuard(allowedRoles, opts = {}) {
     const roleField = opts.roleField || 'role_code';
     const message = opts.message || 'auth.role_denied';
@@ -26,8 +33,7 @@ export function roleGuard(allowedRoles, opts = {}) {
     return async (ctx, next) => {
         /** 인증되지 않은 사용자 */
         if (!ctx.user) {
-            ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
-            return;
+            throw new ServiceError('Unauthorized', 401);
         }
 
         /** 역할 코드 추출 */
@@ -35,13 +41,8 @@ export function roleGuard(allowedRoles, opts = {}) {
 
         /** 허용된 역할인지 확인 */
         if (!userRole || !allowedRoles.includes(userRole)) {
-            ctx.status(403).json({
-                error: {
-                    message: ctx.t ? ctx.t(message) : message,
-                    status: 403,
-                },
-            });
-            return;
+            const msg = (typeof ctx.t === 'function') ? ctx.t(message) : message;
+            throw new ServiceError(msg, 403);
         }
 
         await next();

package/lib/services/Service.js

@@ -8,7 +8,6 @@
  * @see docs/framework/class-design.mm.md (Service)
  */
 import Base from '../core/Base.js';
-import { ServiceError } from '../core/AppError.js';
 
 /** @type {Map<string, { value: *, expires: number }>} 전역 캐시 스토어 */
 const _cache = new Map();
@@ -141,6 +140,28 @@ export default class Service extends Base {
         return cached ? cached.expires > Date.now() : false;
     }
 
+    /**
+     * 접두어 기반 캐시 일괄 무효화
+     *
+     * prefix로 시작하는 모든 캐시 키를 삭제한다.
+     * 예: 'reseller:tree:' → 'reseller:tree:roots', 'reseller:tree:full', 'reseller:tree:children:5' 등 모두 삭제
+     *
+     * @param {string} prefix - 캐시 키 접두어
+     */
+    async invalidateCacheByPrefix(prefix) {
+        // 인메모리 Map — prefix로 시작하는 키 일괄 삭제
+        for (const key of _cache.keys()) {
+            if (key.startsWith(prefix)) {
+                _cache.delete(key);
+            }
+        }
+
+        // CacheManager — deleteByPrefix 지원 시 위임
+        if (this.cache && typeof this.cache.deleteByPrefix === 'function') {
+            await this.cache.deleteByPrefix(prefix);
+        }
+    }
+
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     //  병렬 실행
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -257,19 +278,6 @@ export default class Service extends Base {
         }
     }
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  에러
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 에러 생성 헬퍼
-     * @param {string} message
-     * @param {number} [status=400]
-     * @returns {ServiceError}
-     */
-    error(message, status = 400) {
-        return new ServiceError(message, status);
-    }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "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.75",
+    "@fuzionx/core": "^0.1.76",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",