@fuzionx/framework 0.1.75 → 0.1.77

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.77",
     "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';
@@ -299,8 +300,50 @@ export default class Application {
         await this.i18n.load();
 
         // 3. Scheduler / Queue / Telegram / Storage / Cache 초기화
-        this._scheduler = new Scheduler(this);
-        this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
+        //
+        // yaml 구조:
+        //   app.scheduler.enabled / .lock.{driver,redis_url,prefix}
+        //   app.queue.{driver,redis_url,prefix}
+        // fuzionx 기존 코드는 top-level (config.get('queue')) 였지만 실제로는
+        // app.* 아래에 있음 — fallback 둘 다 지원.
+        const queueCfg     = this.config.get('app.queue')     || this.config.get('queue')     || {};
+        const schedulerCfg = this.config.get('app.scheduler') || this.config.get('scheduler') || {};
+        const lockCfg      = schedulerCfg.lock || {};
+
+        // Scheduler — leader election 용 redis URL
+        //   우선순위: app.scheduler.lock.redis_url → app.queue.redis_url 재사용
+        //   lock.driver !== 'redis' 면 leader election 비활성 (fallback)
+        const schedulerLockEnabled = lockCfg.driver === 'redis';
+        const schedulerRedisUrl = schedulerLockEnabled
+            ? (lockCfg.redis_url || queueCfg.redis_url || null)
+            : null;
+        this._scheduler = new Scheduler(this, {
+            url:    schedulerRedisUrl,
+            prefix: lockCfg.prefix || 'fuzionx:scheduler',
+        });
+        this._schedulerEnabled = schedulerCfg.enabled !== false;   // 기본 true
+        if (this._schedulerEnabled) {
+            try {
+                await this._scheduler.connect();
+            } catch (e) {
+                this.logger.warn(`[Scheduler] connect failed: ${e.message}`);
+            }
+        } else {
+            this.logger.info('[Scheduler] disabled (app.scheduler.enabled=false)');
+        }
+
+        this._queue = new Queue(this, {
+            driver: queueCfg.driver || 'memory',
+            url:    queueCfg.redis_url,
+            prefix: queueCfg.prefix,
+            brpopTimeoutSec:    queueCfg.brpop_timeout_sec,
+            promoterIntervalMs: queueCfg.promoter_interval_ms,
+        });
+        try {
+            await this._queue.start();
+        } catch (e) {
+            this.logger.error(`[Queue] start failed: ${e.message}`);
+        }
         
         // 텔레그램 매니저 로드 (Queue 기반이므로 _queue 설정 직후 구성)
         const telegramConfig = this.config.get('app.telegram');
@@ -530,8 +573,11 @@ export default class Application {
 
         // Scheduler 시작 — primary 프로세스에서만 (워커 중복 실행 방지)
         // fuzionx 상위 레이어가 cluster.fork()로 워커를 생성하므로
-        // cluster.isPrimary로 단일 프로세스 보장
-        if (this._scheduler && this._scheduler._jobs.length > 0 && !cluster.isWorker) {
+        // cluster.isPrimary로 단일 프로세스 보장 — multi-worker 차원 보호.
+        // 추가로 redis leader election (Scheduler.connect) 가 multi-server 차원 보호.
+        // app.scheduler.enabled=false 면 전체 스킵.
+        if (this._scheduler && this._scheduler._jobs.length > 0
+            && !cluster.isWorker && this._schedulerEnabled !== false) {
             this._scheduler.start();
         }
 
@@ -709,6 +755,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 +837,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 +852,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 +868,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 +884,8 @@ export default class Application {
         ctx.appName = appName;
 
         // ── Sync-first 실행 ──
+        // 핸들러/미들웨어 throw → _handleContextError 가 ErrorHandler 로깅까지 책임지므로
+        // 여기서는 별도 console 출력 없이 ctx 응답만 만든다 (중복 로그 방지).
         let chainResult;
         try {
             if (middlewareFns.length === 0) {
@@ -835,7 +895,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 +910,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 +995,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 +1011,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 +1021,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 +1037,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 +1334,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 +1483,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);
         }
     }
 
@@ -1390,7 +1538,7 @@ export default class Application {
             await this.emit('shutting-down', { signal });
 
             // 1. 스케줄러 정지 (04-bootstrap-lifecycle.md)
-            if (this._scheduler) this._scheduler.stop();
+            if (this._scheduler) await this._scheduler.stop();
 
             // 2. 큐 drain — 처리 중 Task 완료 대기 (doc 04 순서 3)
             if (this._queue && this._queue.pending > 0) {

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);
         }