@fuzionx/framework 0.1.61 → 0.1.62

package/lib/database/ConnectionManager.js

@@ -8,15 +8,22 @@
  * @see docs/framework/17-config.md
  */
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
 
 const _require = createRequire(import.meta.url);
+/** CWD 기반 require — 프로젝트 node_modules에서 resolve */
+const _cwdRequire = createRequire(pathToFileURL(path.join(process.cwd(), '_resolve.js')).href);
 
 /**
  * optional dependency 안전 로드
+ * 프레임워크 경로 → CWD 경로 순으로 시도
  * @private
  */
 function tryRequire(name) {
-    try { return _require(name); } catch { return null; }
+    try { return _require(name); } catch {
+        try { return _cwdRequire(name); } catch { return null; }
+    }
 }
 
 export default class ConnectionManager {
@@ -144,8 +151,20 @@ export default class ConnectionManager {
                 conn.connect = () => {
                     if (conn._connected) return Promise.resolve();
                     if (conn._connectPromise) return conn._connectPromise;
-                    const uri = config.uri || config.url
-                        || `mongodb://${config.host || '127.0.0.1'}:${config.port || 27017}/${config.database || ''}`;
+                    // user/password가 있으면 URI에 인증 정보 포함
+                    let uri = config.uri || config.url;
+                    if (!uri) {
+                        const host = config.host || '127.0.0.1';
+                        const port = config.port || 27017;
+                        const db = config.database || '';
+                        if (config.user && config.password) {
+                            // 인증 정보 포함 URI + authSource 지정
+                            const authSource = config.authSource || config.database || 'admin';
+                            uri = `mongodb://${encodeURIComponent(config.user)}:${encodeURIComponent(config.password)}@${host}:${port}/${db}?authSource=${authSource}`;
+                        } else {
+                            uri = `mongodb://${host}:${port}/${db}`;
+                        }
+                    }
                     conn._connectPromise = mongoose.connect(uri, config.options || {}).then(() => {
                         conn._connected = true;
                     });

package/lib/database/Model.js

@@ -16,9 +16,23 @@ export default class Model {
     static softDelete = false; // deleted_at 소프트 삭제
     static hidden = [];        // JSON 직렬화 시 제외 필드
     static columns = {};       // SQL 스키마 정의 (fx db:sync 용)
-    static indexes = [];       // 인덱스 정의 [{ columns: ['role'], unique? }]
+    static indexes = [];       // 인덱스 정의 [{ columns: ['role_code'], unique?: boolean, name?: string }]
     static schema = {};        // MongoDB 스키마
 
+    /**
+     * 관계 정의 — 서브클래스에서 오버라이드
+     *
+     * @example
+     * static relations = {
+     *   wallet:  { type: 'hasOne',    model: 'Wallet',    foreignKey: 'user_id' },
+     *   posts:   { type: 'hasMany',   model: 'Post',      foreignKey: 'user_id' },
+     *   role:    { type: 'belongsTo', model: 'Role',      foreignKey: 'role_code', ownerKey: 'code' },
+     * };
+     *
+     * @type {Object<string, { type: string, model: string, foreignKey: string, ownerKey?: string }>}
+     */
+    static relations = {};
+
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     //  인스턴스 (레코드 래퍼)
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/lib/database/SqlModel.js

@@ -31,6 +31,12 @@ export default class SqlModel extends Model {
      */
     static _connectionManager = null;
 
+    /**
+     * ModelRegistry 인스턴스 (Application에서 주입 — relation resolve용)
+     * @type {import('./ModelRegistry.js').default|null}
+     */
+    static _modelRegistry = null;
+
     /**
      * ConnectionManager를 모든 SqlModel 서브클래스에 주입
      * @param {import('./ConnectionManager.js').default} cm
@@ -39,6 +45,14 @@ export default class SqlModel extends Model {
         SqlModel._connectionManager = cm;
     }
 
+    /**
+     * ModelRegistry를 모든 SqlModel 서브클래스에 주입 (relation eager-loading용)
+     * @param {import('./ModelRegistry.js').default} registry
+     */
+    static setModelRegistry(registry) {
+        SqlModel._modelRegistry = registry;
+    }
+
     /**
      * DB 연결 가져오기
      * @returns {object} connection object

package/lib/database/SqlQueryBuilder.js

@@ -33,17 +33,22 @@ export default class SqlQueryBuilder extends QueryBuilder {
      */
     async get() {
         const conn = this._model.getConnection();
+        let results;
 
         if (conn.type === 'sqlite' && conn.db) {
-            return this._executeSqlite(conn.db, 'select');
+            results = this._executeSqlite(conn.db, 'select');
+        } else if (conn.type === 'knex' && conn.db) {
+            results = await this._executeKnex(conn.db, 'select');
+        } else {
+            results = [];
         }
 
-        if (conn.type === 'knex' && conn.db) {
-            return this._executeKnex(conn.db, 'select');
+        // eager-loading — with()로 지정된 관계 로드
+        if (this._withs.length > 0 && results.length > 0) {
+            await this._loadRelations(results);
         }
 
-        // Stub: no connection
-        return [];
+        return results;
     }
 
     /**
@@ -155,7 +160,7 @@ export default class SqlQueryBuilder extends QueryBuilder {
         const total = await this.count();
         this._limit = perPage;
         this._offset = (page - 1) * perPage;
-        const data = await this.get();
+        const data = await this.get(); // get() 내부에서 relation 자동 로드
         return new Pagination(data, total, page, perPage);
     }
 
@@ -329,4 +334,84 @@ export default class SqlQueryBuilder extends QueryBuilder {
         }
         return query;
     }
+
+    // ━━━━━━━━━━ Relation Eager-Loading ━━━━━━━━━━
+
+    /**
+     * with()로 지정된 관계를 일괄 조회하여 결과에 첨부 (N+1 방지)
+     *
+     * 지원 관계 타입:
+     * - hasOne:    1:1 (현재 PK → 대상 FK)
+     * - hasMany:   1:N (현재 PK → 대상 FK)
+     * - belongsTo: N:1 (현재 FK → 대상 PK/ownerKey)
+     *
+     * @param {Array<Model>} results - 메인 조회 결과
+     * @private
+     */
+    async _loadRelations(results) {
+        const modelRelations = this._model.relations || {};
+
+        for (const relName of this._withs) {
+            const rel = modelRelations[relName];
+            if (!rel) continue; // 정의되지 않은 관계는 무시
+
+            // 관계 대상 모델 클래스 resolve (문자열 → ModelRegistry에서 찾기)
+            let RelatedModel = rel.model;
+            if (typeof RelatedModel === 'string') {
+                // SqlModel._modelRegistry를 통해 모델 클래스 resolve
+                const registry = this._model._modelRegistry || this._model.constructor._modelRegistry;
+                if (registry) {
+                    RelatedModel = registry.get(rel.model);
+                }
+                if (!RelatedModel || typeof RelatedModel === 'string') {
+                    continue; // resolve 실패 시 스킵
+                }
+            }
+
+            const foreignKey = rel.foreignKey;
+            const ownerKey = rel.ownerKey || this._model.primaryKey; // belongsTo의 대상 키
+            const localKey = rel.localKey || this._model.primaryKey;  // hasOne/hasMany의 로컬 키
+
+            if (rel.type === 'hasOne' || rel.type === 'hasMany') {
+                // hasOne/hasMany: 현재 모델의 localKey 값 수집 → 대상 모델의 foreignKey로 조회
+                const localValues = [...new Set(results.map(r => r._attributes[localKey]).filter(v => v != null))];
+                if (localValues.length === 0) continue;
+
+                const related = await RelatedModel.query().whereIn(foreignKey, localValues).get();
+
+                // 결과 매핑 (FK → 로컬키 기준)
+                if (rel.type === 'hasOne') {
+                    const map = new Map();
+                    for (const r of related) map.set(r._attributes[foreignKey], r);
+                    for (const row of results) {
+                        row[relName] = map.get(row._attributes[localKey]) || null;
+                    }
+                } else {
+                    // hasMany: FK별로 그룹화
+                    const map = new Map();
+                    for (const r of related) {
+                        const key = r._attributes[foreignKey];
+                        if (!map.has(key)) map.set(key, []);
+                        map.get(key).push(r);
+                    }
+                    for (const row of results) {
+                        row[relName] = map.get(row._attributes[localKey]) || [];
+                    }
+                }
+
+            } else if (rel.type === 'belongsTo') {
+                // belongsTo: 현재 모델의 foreignKey 값 수집 → 대상 모델의 ownerKey로 조회
+                const fkValues = [...new Set(results.map(r => r._attributes[foreignKey]).filter(v => v != null))];
+                if (fkValues.length === 0) continue;
+
+                const related = await RelatedModel.query().whereIn(ownerKey, fkValues).get();
+                const map = new Map();
+                for (const r of related) map.set(r._attributes[ownerKey], r);
+
+                for (const row of results) {
+                    row[relName] = map.get(row._attributes[foreignKey]) || null;
+                }
+            }
+        }
+    }
 }

package/lib/middleware/index.js

@@ -12,3 +12,4 @@ export { csrf } from './csrf.js';
 export { session } from './session.js';
 export { theme } from './theme.js';
 export { loadUser } from './loadUser.js';
+export { roleGuard } from './roleGuard.js';

package/lib/middleware/roleGuard.js

@@ -0,0 +1,49 @@
+/**
+ * roleGuard — 역할 기반 접근 제어 미들웨어
+ *
+ * `auth()` 미들웨어 이후에 사용.
+ * ctx.user.role_code가 허용된 역할 목록에 포함되는지 검사.
+ *
+ * @example
+ * // 관리자 백오피스: developer, admin만 허용
+ * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin'])] }, (r) => { ... });
+ *
+ * // 리셀러 전용: reseller만 허용
+ * r.group('/api', { middleware: [auth(), roleGuard(['developer', 'admin', 'reseller'])] }, (r) => { ... });
+ *
+ * @see docs/framework/14-authentication.md
+ *
+ * @param {string[]} allowedRoles - 접근 허용 역할 코드 배열
+ * @param {object} [opts]
+ * @param {string} [opts.roleField='role_code'] - user 객체에서 역할을 읽을 필드명
+ * @param {string} [opts.message='auth.role_denied'] - 거부 시 에러 메시지 키
+ * @returns {Function} 미들웨어 함수
+ */
+export function roleGuard(allowedRoles, opts = {}) {
+    const roleField = opts.roleField || 'role_code';
+    const message = opts.message || 'auth.role_denied';
+
+    return async (ctx, next) => {
+        /** 인증되지 않은 사용자 */
+        if (!ctx.user) {
+            ctx.status(401).json({ error: { message: 'Unauthorized', status: 401 } });
+            return;
+        }
+
+        /** 역할 코드 추출 */
+        const userRole = ctx.user[roleField];
+
+        /** 허용된 역할인지 확인 */
+        if (!userRole || !allowedRoles.includes(userRole)) {
+            ctx.status(403).json({
+                error: {
+                    message: ctx.t ? ctx.t(message) : message,
+                    status: 403,
+                },
+            });
+            return;
+        }
+
+        await next();
+    };
+}

package/lib/middleware/theme.js

@@ -1,19 +1,72 @@
 /**
- * theme — 도메인 → 테마 매핑 미들웨어
+ * theme — 도메인 → 템플릿(테마) 매핑 미들웨어
+ *
+ * DB에 Domain 모델이 등록되어 있으면 요청 호스트로 조회하여
+ * ctx.theme을 해당 템플릿 코드로 설정.
+ * DB 없거나 매칭 도메인이 없으면 fuzionx.yaml의 기본 테마 사용.
+ *
+ * 성능: 캐시를 통해 매 요청마다 DB 조회를 방지.
  *
  * @see docs/framework/03-views-templates.md
  * @see docs/framework/12-middleware.md — "theme: 도메인 → 테마 매핑"
  *
  * @param {object} [opts]
  * @param {string} [opts.default='default'] - 기본 테마
- * @param {object} [opts.mapping] - { 'domain.com': 'theme1' }
  */
 export function theme(opts = {}) {
     const defaultTheme = opts.default || 'default';
 
     return async (ctx, next) => {
         const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
-        ctx.theme = configDefault;
+
+        // DB의 Domain 모델이 등록되어 있으면 호스트로 조회
+        const DomainModel = ctx.app?.db?.Domain;
+        if (DomainModel) {
+            const host = ctx.headers?.host || ''; // '127.0.0.1:49080' 또는 'example.com'
+
+            // 캐시 키: 도메인 호스트별
+            const cacheKey = `theme:${host}`;
+            let templateCode = null;
+
+            // CacheManager가 있으면 캐시 사용 (5분)
+            if (ctx.app._cacheManager) {
+                templateCode = await ctx.app._cacheManager.remember(cacheKey, 300, async () => {
+                    const domainRecord = await DomainModel
+                        .where('domain', host)
+                        .where('is_active', true)
+                        .first();
+
+                    if (domainRecord) {
+                        // 관계 로드하여 template.code 가져오기
+                        const TemplateModel = ctx.app.db.Template;
+                        if (TemplateModel) {
+                            const template = await TemplateModel.find(domainRecord.template_id);
+                            if (template?.is_active) return template.code;
+                        }
+                    }
+                    return null; // null도 캐시 (DB 미스 반복 방지)
+                });
+            } else {
+                // 캐시 없으면 직접 조회
+                const domainRecord = await DomainModel
+                    .where('domain', host)
+                    .where('is_active', true)
+                    .first();
+
+                if (domainRecord) {
+                    const TemplateModel = ctx.app.db.Template;
+                    if (TemplateModel) {
+                        const template = await TemplateModel.find(domainRecord.template_id);
+                        if (template?.is_active) templateCode = template.code;
+                    }
+                }
+            }
+
+            ctx.theme = templateCode || configDefault;
+        } else {
+            // Domain 모델 미등록 시 YAML 기본값 사용
+            ctx.theme = configDefault;
+        }
 
         await next();
     };

package/lib/services/Service.js

@@ -72,7 +72,10 @@ export default class Service extends Base {
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
     /**
-     * TTL 기반 인메모리 캐시로 감싸기
+     * TTL 기반 캐시로 감싸기
+     *
+     * CacheManager가 초기화되어 있으면 Redis/File 캐시 사용.
+     * 없으면 인메모리 Map 폴백 (워커 간 공유 안됨).
      *
      * @param {string} key - 캐시 키
      * @param {number} ttl - TTL (초)
@@ -85,6 +88,12 @@ export default class Service extends Base {
      * });
      */
     async withCache(key, ttl, fn) {
+        // CacheManager가 있으면 Redis/File 캐시 사용
+        if (this.cache) {
+            return this.cache.remember(key, ttl, fn);
+        }
+
+        // 폴백: 인메모리 Map (워커 간 공유 불가)
         const cached = _cache.get(key);
         if (cached && cached.expires > Date.now()) {
             return cached.value;
@@ -102,23 +111,32 @@ export default class Service extends Base {
      * 캐시 키 무효화
      * @param {string} key
      */
-    invalidateCache(key) {
+    async invalidateCache(key) {
+        if (this.cache) {
+            await this.cache.delete(key);
+        }
         _cache.delete(key);
     }
 
     /**
      * 전체 캐시 초기화
      */
-    clearCache() {
+    async clearCache() {
+        if (this.cache) {
+            await this.cache.flush();
+        }
         _cache.clear();
     }
 
     /**
      * 캐시 존재 여부
      * @param {string} key
-     * @returns {boolean}
+     * @returns {Promise<boolean>}
      */
-    hasCache(key) {
+    async hasCache(key) {
+        if (this.cache) {
+            return this.cache.has(key);
+        }
         const cached = _cache.get(key);
         return cached ? cached.expires > Date.now() : false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -34,13 +34,21 @@
     "url": "https://github.com/saytohenry/fuzionx"
   },
   "dependencies": {
-    "@fuzionx/core": "^0.1.61",
+    "@fuzionx/core": "^0.1.62",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0"
   },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "vitest": "^3.0.0"
   },