@fuzionx/framework 0.1.39 → 0.1.41

package/lib/helpers/CryptoHelper.js

@@ -1,48 +1,48 @@
-/**
- * CryptoHelper — Bridge crypto N-API 래퍼
- *
- * @see docs/framework/19-utilities.md — "1. Crypto (app.crypto)"
- * @see packages/fuzionx/lib/crypto.js (Core 래퍼)
- */
-import { randomUUID, createHash as nodeCreateHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
-
-export default class CryptoHelper {
-    constructor(bridge) { this._bridge = bridge; }
-
-    uuid() {
-        if (this._bridge?.cryptoUuid) return this._bridge.cryptoUuid();
-        return randomUUID();
-    }
-
-    md5(input) {
-        if (this._bridge?.cryptoMd5) return this._bridge.cryptoMd5(input);
-        return nodeCreateHash('md5').update(input).digest('hex');
-    }
-
-    sha256(input) {
-        if (this._bridge?.cryptoSha256) return this._bridge.cryptoSha256(input);
-        return nodeCreateHash('sha256').update(input).digest('hex');
-    }
-
-    encrypt(key, plaintext) {
-        if (this._bridge?.cryptoEncryptAes) return this._bridge.cryptoEncryptAes(key, plaintext);
-        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
-        const iv = randomBytes(12);
-        const cipher = createCipheriv('aes-256-gcm', keyBuf, iv);
-        let encrypted = cipher.update(plaintext, 'utf-8', 'base64');
-        encrypted += cipher.final('base64');
-        const tag = cipher.getAuthTag().toString('base64');
-        return `${iv.toString('base64')}.${encrypted}.${tag}`;
-    }
-
-    decrypt(key, ciphertext) {
-        if (this._bridge?.cryptoDecryptAes) return this._bridge.cryptoDecryptAes(key, ciphertext);
-        const [ivB64, encB64, tagB64] = ciphertext.split('.');
-        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
-        const decipher = createDecipheriv('aes-256-gcm', keyBuf, Buffer.from(ivB64, 'base64'));
-        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
-        let decrypted = decipher.update(encB64, 'base64', 'utf-8');
-        decrypted += decipher.final('utf-8');
-        return decrypted;
-    }
-}
+/**
+ * CryptoHelper — Bridge crypto N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "1. Crypto (app.crypto)"
+ * @see packages/fuzionx/lib/crypto.js (Core 래퍼)
+ */
+import { randomUUID, createHash as nodeCreateHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+export default class CryptoHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    uuid() {
+        if (this._bridge?.cryptoUuid) return this._bridge.cryptoUuid();
+        return randomUUID();
+    }
+
+    md5(input) {
+        if (this._bridge?.cryptoMd5) return this._bridge.cryptoMd5(input);
+        return nodeCreateHash('md5').update(input).digest('hex');
+    }
+
+    sha256(input) {
+        if (this._bridge?.cryptoSha256) return this._bridge.cryptoSha256(input);
+        return nodeCreateHash('sha256').update(input).digest('hex');
+    }
+
+    encrypt(key, plaintext) {
+        if (this._bridge?.cryptoEncryptAes) return this._bridge.cryptoEncryptAes(key, plaintext);
+        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', keyBuf, iv);
+        let encrypted = cipher.update(plaintext, 'utf-8', 'base64');
+        encrypted += cipher.final('base64');
+        const tag = cipher.getAuthTag().toString('base64');
+        return `${iv.toString('base64')}.${encrypted}.${tag}`;
+    }
+
+    decrypt(key, ciphertext) {
+        if (this._bridge?.cryptoDecryptAes) return this._bridge.cryptoDecryptAes(key, ciphertext);
+        const [ivB64, encB64, tagB64] = ciphertext.split('.');
+        const keyBuf = Buffer.from(key.padEnd(32, '0').slice(0, 32));
+        const decipher = createDecipheriv('aes-256-gcm', keyBuf, Buffer.from(ivB64, 'base64'));
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+        let decrypted = decipher.update(encB64, 'base64', 'utf-8');
+        decrypted += decipher.final('utf-8');
+        return decrypted;
+    }
+}

package/lib/helpers/FileHelper.js

@@ -1,61 +1,61 @@
-/**
- * FileHelper — Bridge file N-API 래퍼
- *
- * @see docs/framework/19-utilities.md — "4. File (app.file)"
- * @see packages/fuzionx/lib/file.js (Core 래퍼)
- */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-
-export default class FileHelper {
-    constructor(bridge) { this._bridge = bridge; }
-
-    async move(src, dst) {
-        if (this._bridge?.fileMoveFile) return this._bridge.fileMoveFile(src, dst);
-        await fs.mkdir(path.dirname(dst), { recursive: true });
-        await fs.rename(src, dst).catch(async () => {
-            await fs.copyFile(src, dst);
-            await fs.unlink(src);
-        });
-    }
-
-    async copy(src, dst) {
-        if (this._bridge?.fileCopyFile) return this._bridge.fileCopyFile(src, dst);
-        await fs.mkdir(path.dirname(dst), { recursive: true });
-        await fs.copyFile(src, dst);
-        const stat = await fs.stat(dst);
-        return stat.size;
-    }
-
-    async ensureDir(dirPath) {
-        if (this._bridge?.fileEnsureDir) return this._bridge.fileEnsureDir(dirPath);
-        await fs.mkdir(dirPath, { recursive: true });
-    }
-
-    async size(filePath) {
-        if (this._bridge?.fileSize) return this._bridge.fileSize(filePath);
-        const stat = await fs.stat(filePath);
-        return stat.size;
-    }
-
-    async exists(filePath) {
-        if (this._bridge?.fileExists) return this._bridge.fileExists(filePath);
-        try { await fs.access(filePath); return true; } catch { return false; }
-    }
-
-    async remove(filePath) {
-        if (this._bridge?.fileRemove) return this._bridge.fileRemove(filePath);
-        await fs.unlink(filePath);
-    }
-
-    tempPath(prefix = 'fx') {
-        if (this._bridge?.fileTempPath) return this._bridge.fileTempPath(prefix);
-        return path.join('/tmp', `${prefix}-${randomUUID()}`);
-    }
-
-    extension(filePath) {
-        const ext = path.extname(filePath).slice(1).toLowerCase();
-        return ext || null;
-    }
-}
+/**
+ * FileHelper — Bridge file N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "4. File (app.file)"
+ * @see packages/fuzionx/lib/file.js (Core 래퍼)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export default class FileHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    async move(src, dst) {
+        if (this._bridge?.fileMoveFile) return this._bridge.fileMoveFile(src, dst);
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.rename(src, dst).catch(async () => {
+            await fs.copyFile(src, dst);
+            await fs.unlink(src);
+        });
+    }
+
+    async copy(src, dst) {
+        if (this._bridge?.fileCopyFile) return this._bridge.fileCopyFile(src, dst);
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.copyFile(src, dst);
+        const stat = await fs.stat(dst);
+        return stat.size;
+    }
+
+    async ensureDir(dirPath) {
+        if (this._bridge?.fileEnsureDir) return this._bridge.fileEnsureDir(dirPath);
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+
+    async size(filePath) {
+        if (this._bridge?.fileSize) return this._bridge.fileSize(filePath);
+        const stat = await fs.stat(filePath);
+        return stat.size;
+    }
+
+    async exists(filePath) {
+        if (this._bridge?.fileExists) return this._bridge.fileExists(filePath);
+        try { await fs.access(filePath); return true; } catch { return false; }
+    }
+
+    async remove(filePath) {
+        if (this._bridge?.fileRemove) return this._bridge.fileRemove(filePath);
+        await fs.unlink(filePath);
+    }
+
+    tempPath(prefix = 'fx') {
+        if (this._bridge?.fileTempPath) return this._bridge.fileTempPath(prefix);
+        return path.join('/tmp', `${prefix}-${randomUUID()}`);
+    }
+
+    extension(filePath) {
+        const ext = path.extname(filePath).slice(1).toLowerCase();
+        return ext || null;
+    }
+}

package/lib/helpers/HashHelper.js

@@ -1,39 +1,39 @@
-/**
- * HashHelper — Bridge hash N-API 래퍼
- *
- * @see docs/framework/19-utilities.md — "2. Hash (app.hash)"
- * @see packages/fuzionx/lib/hash.js (Core 래퍼)
- */
-import { randomUUID, createHash as nodeCreateHash } from 'node:crypto';
-
-export default class HashHelper {
-    constructor(bridge) { this._bridge = bridge; }
-
-    /** ⚠️ JS 폴백: SHA-256 기반 유사 구현 (테스트 전용, 프로덕션은 Bridge 필수) */
-    bcrypt(password, cost = 12) {
-        if (this._bridge?.hashBcrypt) return this._bridge.hashBcrypt(password, cost);
-        const salt = randomUUID().replace(/-/g, '').slice(0, 22);
-        return `$2b$${cost}$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
-    }
-
-    bcryptVerify(password, hash) {
-        if (this._bridge?.hashBcryptVerify) return this._bridge.hashBcryptVerify(password, hash);
-        const salt = hash.slice(7, 29);
-        const expected = `$2b$12$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
-        return hash === expected;
-    }
-
-    argon2(password) {
-        if (this._bridge?.hashArgon2) return this._bridge.hashArgon2(password);
-        const salt = randomUUID().replace(/-/g, '');
-        return `$argon2id$v=19$m=65536,t=3,p=4$${salt}$${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
-    }
-
-    argon2Verify(password, hash) {
-        if (this._bridge?.hashArgon2Verify) return this._bridge.hashArgon2Verify(password, hash);
-        const parts = hash.split('$');
-        const salt = parts[4] || '';
-        const expected = nodeCreateHash('sha256').update(password + salt).digest('hex');
-        return parts[5] === expected;
-    }
-}
+/**
+ * HashHelper — Bridge hash N-API 래퍼
+ *
+ * @see docs/framework/19-utilities.md — "2. Hash (app.hash)"
+ * @see packages/fuzionx/lib/hash.js (Core 래퍼)
+ */
+import { randomUUID, createHash as nodeCreateHash } from 'node:crypto';
+
+export default class HashHelper {
+    constructor(bridge) { this._bridge = bridge; }
+
+    /** ⚠️ JS 폴백: SHA-256 기반 유사 구현 (테스트 전용, 프로덕션은 Bridge 필수) */
+    bcrypt(password, cost = 12) {
+        if (this._bridge?.hashBcrypt) return this._bridge.hashBcrypt(password, cost);
+        const salt = randomUUID().replace(/-/g, '').slice(0, 22);
+        return `$2b$${cost}$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+    }
+
+    bcryptVerify(password, hash) {
+        if (this._bridge?.hashBcryptVerify) return this._bridge.hashBcryptVerify(password, hash);
+        const salt = hash.slice(7, 29);
+        const expected = `$2b$12$${salt}${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+        return hash === expected;
+    }
+
+    argon2(password) {
+        if (this._bridge?.hashArgon2) return this._bridge.hashArgon2(password);
+        const salt = randomUUID().replace(/-/g, '');
+        return `$argon2id$v=19$m=65536,t=3,p=4$${salt}$${nodeCreateHash('sha256').update(password + salt).digest('hex')}`;
+    }
+
+    argon2Verify(password, hash) {
+        if (this._bridge?.hashArgon2Verify) return this._bridge.hashArgon2Verify(password, hash);
+        const parts = hash.split('$');
+        const salt = parts[4] || '';
+        const expected = nodeCreateHash('sha256').update(password + salt).digest('hex');
+        return parts[5] === expected;
+    }
+}

package/lib/helpers/I18nHelper.js

@@ -1,174 +1,174 @@
-/**
- * I18nHelper — Bridge i18n N-API 위임 + JS 폴백
- *
- * Bridge의 i18NTranslate(locale, key) 직접 호출.
- * Bridge 없으면 JS 파일 기반 폴백.
- *
- * @see docs/framework/18-i18n.md
- * @see packages/fuzionx/lib/i18n.js (Core 래퍼 참조)
- */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-
-export default class I18nHelper {
-    /**
-     * @param {object} [opts]
-     * @param {string} [opts.defaultLocale='ko']
-     * @param {string} [opts.fallback='en']
-     * @param {string} [opts.dir='./locales']
-     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
-     */
-    constructor(opts = {}) {
-        this.defaultLocale = opts.defaultLocale || 'ko';
-        this.fallback = opts.fallback || 'en';
-        this.dir = opts.dir || './locales';
-        this._bridge = opts.bridge || null;
-        this._messages = new Map(); // locale → { flat key: value }
-        this._loaded = false;
-    }
-
-    /**
-     * 번역 파일 로드 (JS 폴백용)
-     */
-    async load() {
-        if (this._loaded) return;
-        try {
-            const entries = await fs.readdir(this.dir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isFile()) continue;
-                const ext = path.extname(entry.name);
-                if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') continue;
-                const locale = path.basename(entry.name, ext);
-                const content = await fs.readFile(path.join(this.dir, entry.name), 'utf-8');
-                const data = ext === '.json' ? JSON.parse(content) : this._parseSimpleYaml(content);
-                this._messages.set(locale, this._flatten(data));
-            }
-        } catch {} // locales/ 없으면 무시
-        this._loaded = true;
-    }
-
-    /**
-     * 번역 키 조회
-     *
-     * Bridge가 있으면 bridge.i18NTranslate(locale, key) 호출.
-     * Bridge 없으면 JS 메시지 맵에서 조회.
-     *
-     * @param {string} locale
-     * @param {string} key - dot-notation (e.g. 'auth.login_required')
-     * @param {object} [vars] - 치환 변수 + { default? }
-     * @returns {string}
-     */
-    translate(locale, key, vars = {}) {
-        // ── Bridge N-API 위임 ──
-        if (this._bridge && typeof this._bridge.i18NTranslate === 'function') {
-            try {
-                const result = this._bridge.i18NTranslate(locale, key);
-                if (result != null) return this._substitute(result, vars);
-            } catch {} // Bridge 실패 시 JS 폴백
-        }
-
-        // ── JS 폴백 ──
-        const messages = this._messages.get(locale)
-            || this._messages.get(this.fallback)
-            || this._messages.get(this.defaultLocale);
-
-        const value = messages?.[key];
-        if (value != null) return this._substitute(value, vars);
-
-        // ── auto_complete: 누락 키 자동 등록 ──
-        // default 값이 제공된 경우, Bridge에 누락 키를 보고하여
-        // 모든 locale 파일에 자동으로 추가한다.
-        if (vars.default) {
-            this.updateMissing(key, vars.default);
-        }
-
-        return vars.default || key;
-    }
-
-    /**
-     * 전체 locale 데이터 반환 (뷰 주입용)
-     * @param {string} locale
-     * @returns {object}
-     */
-    all(locale) {
-        const messages = this._messages.get(locale) || this._messages.get(this.defaultLocale);
-        if (!messages) return {};
-        return { ...messages };
-    }
-
-    /** getAll alias (ctx.t.all() 호환) */
-    getAll(locale) { return this.all(locale); }
-
-    /**
-     * 사용 가능한 locale 목록
-     * @returns {string[]}
-     */
-    locales() {
-        if (this._bridge && typeof this._bridge.i18NGetLocales === 'function') {
-            try { return this._bridge.i18NGetLocales(); } catch {}
-        }
-        return [...this._messages.keys()];
-    }
-
-    /**
-     * 누락 키 업데이트 (dev 모드)
-     * @param {string} key
-     * @param {string} value
-     */
-    updateMissing(key, value) {
-        if (this._bridge && typeof this._bridge.i18NUpdateMissingKey === 'function') {
-            try { this._bridge.i18NUpdateMissingKey(key, value); } catch {}
-        }
-    }
-
-    /** {field} → value 치환 */
-    _substitute(template, vars) {
-        if (!vars || typeof template !== 'string') return template;
-        return template.replace(/\{(\w+)\}/g, (_, key) => {
-            if (key === 'locale' || key === 'default') return `{${key}}`; // 예약어
-            return vars[key] !== undefined ? String(vars[key]) : `{${key}}`;
-        });
-    }
-
-    /** YAML 간단 파서 (중첩 키 → dot-notation flat map) */
-    _parseSimpleYaml(content) {
-        const result = {};
-        const lines = content.split('\n');
-        const stack = [];
-
-        for (const line of lines) {
-            if (!line.trim() || line.trim().startsWith('#')) continue;
-
-            const indent = line.search(/\S/);
-            const match = line.match(/^(\s*)(\w[\w.]*)\s*:\s*(.*)$/);
-            if (!match) continue;
-
-            const [, , key, rawValue] = match;
-            const level = Math.floor(indent / 2);
-
-            while (stack.length > level) stack.pop();
-            stack[level] = key;
-
-            const value = rawValue.replace(/^["']|["']$/g, '').trim();
-            if (value) {
-                const fullKey = stack.filter(Boolean).join('.');
-                result[fullKey] = value;
-            }
-        }
-        return result;
-    }
-
-    /** 중첩 객체 → flat dot-notation */
-    _flatten(obj, prefix = '') {
-        const result = {};
-        for (const [key, value] of Object.entries(obj)) {
-            const fullKey = prefix ? `${prefix}.${key}` : key;
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                Object.assign(result, this._flatten(value, fullKey));
-            } else {
-                result[fullKey] = String(value);
-            }
-        }
-        return result;
-    }
-}
+/**
+ * I18nHelper — Bridge i18n N-API 위임 + JS 폴백
+ *
+ * Bridge의 i18NTranslate(locale, key) 직접 호출.
+ * Bridge 없으면 JS 파일 기반 폴백.
+ *
+ * @see docs/framework/18-i18n.md
+ * @see packages/fuzionx/lib/i18n.js (Core 래퍼 참조)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export default class I18nHelper {
+    /**
+     * @param {object} [opts]
+     * @param {string} [opts.defaultLocale='ko']
+     * @param {string} [opts.fallback='en']
+     * @param {string} [opts.dir='./locales']
+     * @param {object} [opts.bridge] - Bridge N-API 인스턴스
+     */
+    constructor(opts = {}) {
+        this.defaultLocale = opts.defaultLocale || 'ko';
+        this.fallback = opts.fallback || 'en';
+        this.dir = opts.dir || './locales';
+        this._bridge = opts.bridge || null;
+        this._messages = new Map(); // locale → { flat key: value }
+        this._loaded = false;
+    }
+
+    /**
+     * 번역 파일 로드 (JS 폴백용)
+     */
+    async load() {
+        if (this._loaded) return;
+        try {
+            const entries = await fs.readdir(this.dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile()) continue;
+                const ext = path.extname(entry.name);
+                if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') continue;
+                const locale = path.basename(entry.name, ext);
+                const content = await fs.readFile(path.join(this.dir, entry.name), 'utf-8');
+                const data = ext === '.json' ? JSON.parse(content) : this._parseSimpleYaml(content);
+                this._messages.set(locale, this._flatten(data));
+            }
+        } catch {} // locales/ 없으면 무시
+        this._loaded = true;
+    }
+
+    /**
+     * 번역 키 조회
+     *
+     * Bridge가 있으면 bridge.i18NTranslate(locale, key) 호출.
+     * Bridge 없으면 JS 메시지 맵에서 조회.
+     *
+     * @param {string} locale
+     * @param {string} key - dot-notation (e.g. 'auth.login_required')
+     * @param {object} [vars] - 치환 변수 + { default? }
+     * @returns {string}
+     */
+    translate(locale, key, vars = {}) {
+        // ── Bridge N-API 위임 ──
+        if (this._bridge && typeof this._bridge.i18NTranslate === 'function') {
+            try {
+                const result = this._bridge.i18NTranslate(locale, key);
+                if (result != null) return this._substitute(result, vars);
+            } catch {} // Bridge 실패 시 JS 폴백
+        }
+
+        // ── JS 폴백 ──
+        const messages = this._messages.get(locale)
+            || this._messages.get(this.fallback)
+            || this._messages.get(this.defaultLocale);
+
+        const value = messages?.[key];
+        if (value != null) return this._substitute(value, vars);
+
+        // ── auto_complete: 누락 키 자동 등록 ──
+        // default 값이 제공된 경우, Bridge에 누락 키를 보고하여
+        // 모든 locale 파일에 자동으로 추가한다.
+        if (vars.default) {
+            this.updateMissing(key, vars.default);
+        }
+
+        return vars.default || key;
+    }
+
+    /**
+     * 전체 locale 데이터 반환 (뷰 주입용)
+     * @param {string} locale
+     * @returns {object}
+     */
+    all(locale) {
+        const messages = this._messages.get(locale) || this._messages.get(this.defaultLocale);
+        if (!messages) return {};
+        return { ...messages };
+    }
+
+    /** getAll alias (ctx.t.all() 호환) */
+    getAll(locale) { return this.all(locale); }
+
+    /**
+     * 사용 가능한 locale 목록
+     * @returns {string[]}
+     */
+    locales() {
+        if (this._bridge && typeof this._bridge.i18NGetLocales === 'function') {
+            try { return this._bridge.i18NGetLocales(); } catch {}
+        }
+        return [...this._messages.keys()];
+    }
+
+    /**
+     * 누락 키 업데이트 (dev 모드)
+     * @param {string} key
+     * @param {string} value
+     */
+    updateMissing(key, value) {
+        if (this._bridge && typeof this._bridge.i18NUpdateMissingKey === 'function') {
+            try { this._bridge.i18NUpdateMissingKey(key, value); } catch {}
+        }
+    }
+
+    /** {field} → value 치환 */
+    _substitute(template, vars) {
+        if (!vars || typeof template !== 'string') return template;
+        return template.replace(/\{(\w+)\}/g, (_, key) => {
+            if (key === 'locale' || key === 'default') return `{${key}}`; // 예약어
+            return vars[key] !== undefined ? String(vars[key]) : `{${key}}`;
+        });
+    }
+
+    /** YAML 간단 파서 (중첩 키 → dot-notation flat map) */
+    _parseSimpleYaml(content) {
+        const result = {};
+        const lines = content.split('\n');
+        const stack = [];
+
+        for (const line of lines) {
+            if (!line.trim() || line.trim().startsWith('#')) continue;
+
+            const indent = line.search(/\S/);
+            const match = line.match(/^(\s*)(\w[\w.]*)\s*:\s*(.*)$/);
+            if (!match) continue;
+
+            const [, , key, rawValue] = match;
+            const level = Math.floor(indent / 2);
+
+            while (stack.length > level) stack.pop();
+            stack[level] = key;
+
+            const value = rawValue.replace(/^["']|["']$/g, '').trim();
+            if (value) {
+                const fullKey = stack.filter(Boolean).join('.');
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+
+    /** 중첩 객체 → flat dot-notation */
+    _flatten(obj, prefix = '') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                Object.assign(result, this._flatten(value, fullKey));
+            } else {
+                result[fullKey] = String(value);
+            }
+        }
+        return result;
+    }
+}