@fuzionx/framework 0.1.46 → 0.1.48

package/README.md

@@ -1,6 +1,6 @@
 # @fuzionx/framework
 
-> Laravel-inspired full-stack MVC framework powered by Rust N-API bridge — **500K+ RPS**
+> Laravel-inspired full-stack MVC framework powered by Rust N-API bridge, achieving an unprecedented **618K+ Req/Sec** in the Node.js ecosystem.
 
 ```
 @fuzionx/framework          ← npm install (개발자가 설치)
@@ -34,6 +34,33 @@ node app.js
 
 ---
 
+## 🚀 Why FuzionX? (The Differentiator)
+
+FuzionX is not just another framework wrapper. It fundamentally redesigns how HTTP requests are handled in the Node.js ecosystem by shifting heavy networking and parsing logic to Rust.
+
+- **Rust N-API Direct TCP Handling**: Bypasses the standard Node.js `http` parser. Raw TCP buffers are processed at native speeds via Rust's LibUV bindings, maximizing I/O efficiency.
+- **Kernel-Level Load Balancing (`SO_REUSEPORT`)**: Completely eliminates the single-thread IPC bottlenecks and PM2 cluster routing overhead. The OS kernel directly distributes incoming connections across all available CPU cores.
+- **Zero-Allocation Dispatch Pipeline**: Reusable Context (`ctx`) design and optimized closures drastically minimize V8 Garbage Collection (GC) pressure, reducing tail latencies under heavy concurrent loads.
+- **Full-Stack with S-Tier Speed**: Offers a robust Laravel-inspired MVC Developer Experience (ORM, i18n, WebSockets, Schedulers) while delivering routing and throughput capabilities normally reserved for hyper-optimized minimalist C++ servers like `uWebSockets.js`.
+
+---
+
+## 📊 Performance Benchmark
+
+**Hardware Environment**: Intel® Core™ Ultra 9 285H (16 Cores), 16GB RAM  
+**Test Configuration**: `wrk -t4 -c100 -d10s /api/benchmark` (Routing & Framework fully active, Sessions disabled)
+
+| Framework | Req/sec | Avg Latency | Max Latency |
+|:---|---:|---:|---:|
+| 🥇 **FuzionX** (SO_REUSEPORT) | **618,521** | **172.07µs** | **13.03ms** |
+| 🥈 Node.js (Pure HTTP + PM2) | 393,264 | 278.33µs | 37.26ms |
+| 🥉 Fastify (PM2) | 278,526 | 393.45µs | 43.65ms |
+| 4th Express (PM2) | 141,597 | 950.00µs | 66.91ms |
+
+> FuzionX outperforms **Fastify by +122%** and **Node.js Pure HTTP by +57%**, making it one of the absolute fastest full-stack frameworks available in the global JS ecosystem.
+
+---
+
 ## 프로젝트 구조
 
 ```
@@ -481,7 +508,7 @@ app.js 실행
 
 ## 주요 특징
 
-- ⚡ **500K+ RPS** — Rust N-API Bridge (libuv + SO_REUSEPORT)
+- ⚡ **618K+ Req/Sec** — Rust N-API Bridge (libuv + SO_REUSEPORT)
 - 🦀 **Rust 네이티브** — HTTP, 세션, CORS, Rate Limit, 암호화 모두 Rust 처리
 - 🎯 **MVC 아키텍처** — Controller, Service, Model 분리
 - 📦 **자동 스캔** — controllers/, models/, services/ 등 자동 로드

package/cli/index.js

@@ -162,16 +162,18 @@ export async function run(args) {
     if (command === 'make:app') {
         const typeFlag = rest.find(a => a.startsWith('--type='));
         const type = typeFlag?.split('=')[1] || rest[0];
+        const nameFlag = rest.find(a => a.startsWith('--name='));
         const validTypes = ['ssr', 'spa'];
 
         if (!type || !validTypes.includes(type)) {
-            console.error(`Usage: fx make:app --type=ssr|spa`);
+            console.error(`Usage: fx make:app --type=ssr|spa [--name=<appName>]`);
             console.error(`  Available types: ${validTypes.join(', ')}`);
+            console.error(`  --name: custom app directory name (default: type name)`);
             process.exit(1);
         }
 
-        // 앱 이름은 타입에 따라 고정
-        const appName = type;
+        // --name 이 있으면 커스텀 앱명, 없으면 타입명 사용
+        const appName = nameFlag?.split('=')[1] || type;
         const appDir = path.join('.', 'app', appName);
 
         // 기존 앱 확인
@@ -181,16 +183,43 @@ export async function run(args) {
             process.exit(1);
         } catch { /* 없으면 정상 */ }
 
+        // 타입별 템플릿 디렉토리 확인
+        const appTplDir = path.join(TPL_DIR, `make/app-${type}`);
+        let hasTypeTpl = false;
+        try {
+            await fs.access(appTplDir);
+            hasTypeTpl = true;
+        } catch { /* 타입별 템플릿 없으면 기본 사용 */ }
+
+        const tplDir = hasTypeTpl ? appTplDir : path.join(TPL_DIR, 'make/app');
+
         // 빈 디렉토리 생성
         for (const d of ['services', 'middleware', 'ws']) {
             const fullDir = path.join(appDir, d);
             await fs.mkdir(fullDir, { recursive: true });
-            await fs.writeFile(path.join(fullDir, '.gitkeep'), '');
+            const files = await fs.readdir(fullDir).catch(() => []);
+            if (files.length === 0) {
+                await fs.writeFile(path.join(fullDir, '.gitkeep'), '');
+            }
+        }
+
+        // 타입별 템플릿 복사 (public/ 은 프로젝트 루트로 분리)
+        const tplEntries = await fs.readdir(tplDir, { withFileTypes: true });
+        for (const entry of tplEntries) {
+            if (!entry.isDirectory()) continue;
+            if (entry.name === 'public') continue;  // public은 별도 처리
+            await copyDirRecursive(
+                path.join(tplDir, entry.name),
+                path.join(appDir, entry.name),
+            );
         }
 
-        // 기본 파일 복사 (HomeController, routes, views)
-        const appTplDir = path.join(TPL_DIR, 'make/app');
-        await copyDirRecursive(appTplDir, appDir);
+        // public/ 디렉토리 → 프로젝트 루트 public/ 으로 복사
+        const publicSrc = path.join(tplDir, 'public');
+        try {
+            await fs.access(publicSrc);
+            await copyDirRecursive(publicSrc, path.join('.', 'public'));
+        } catch { /* public 없으면 스킵 */ }
 
         console.log(`✅ Created app/${appName}/ (type: ${type})`);
         console.log(`\n   fuzionx.yaml의 apps에 추가하세요:`);
@@ -225,18 +254,23 @@ export async function run(args) {
     // ── fx dev:spa — FuzionX + Vite HMR 동시 실행 ──
     if (command === 'dev:spa') {
         const { execSync } = await import('node:child_process');
-        const spaDir = path.resolve('app/spa/views/default/spa');
+        const appFlag = rest.find(a => a.startsWith('--app='));
+        const appName = appFlag?.split('=')[1] || 'spa';
+        const spaDir = path.resolve(`app/${appName}/views/default/spa`);
         try {
             await fs.access(spaDir);
         } catch {
-            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
-            console.error('   fx make:app --type=spa 로 SPA 앱을 먼저 생성하세요.');
+            console.error(`❌ app/${appName}/views/default/spa/ 디렉토리가 없습니다.`);
+            console.error(`   fx make:app --type=spa 로 SPA 앱을 먼저 생성하세요.`);
+            if (appName === 'spa') {
+                console.error(`   커스텀 앱명을 사용했다면: fx dev:spa --app=<appName>`);
+            }
             process.exit(1);
         }
-        console.log(`🚀 Starting dev server + Vite HMR...`);
+        console.log(`🚀 Starting dev server + Vite HMR... (app: ${appName})`);
         try {
             execSync(
-                'npx concurrently "node --watch app.js" "cd app/spa/views/default/spa && npx vite"',
+                `npx concurrently "node --watch app.js" "cd app/${appName}/views/default/spa && npx vite"`,
                 { stdio: 'inherit', cwd: process.cwd() },
             );
         } catch {}
@@ -246,14 +280,19 @@ export async function run(args) {
     // ── fx build:spa — Vite 프로덕션 빌드 ──
     if (command === 'build:spa') {
         const { execSync } = await import('node:child_process');
-        const spaDir = path.resolve('app/spa/views/default/spa');
+        const appFlag = rest.find(a => a.startsWith('--app='));
+        const appName = appFlag?.split('=')[1] || 'spa';
+        const spaDir = path.resolve(`app/${appName}/views/default/spa`);
         try {
             await fs.access(spaDir);
         } catch {
-            console.error('❌ app/spa/views/default/spa/ 디렉토리가 없습니다.');
+            console.error(`❌ app/${appName}/views/default/spa/ 디렉토리가 없습니다.`);
+            if (appName === 'spa') {
+                console.error(`   커스텀 앱명을 사용했다면: fx build:spa --app=<appName>`);
+            }
             process.exit(1);
         }
-        console.log(`📦 Building SPA for production...`);
+        console.log(`📦 Building SPA for production... (app: ${appName})`);
         try {
             execSync('npx vite build', { stdio: 'inherit', cwd: spaDir });
             console.log('\n✅ Build complete → public/dist/');
@@ -470,7 +509,7 @@ export async function run(args) {
 
     console.log(`
   npx create-fuzionx <name>         Create new project
-  fx make:app --type=ssr|spa       Create app (fixed name: app/ssr or app/spa)
+  fx make:app --type=ssr|spa [--name=<appName>]  Create app
   fx make:controller <Name> --app=  Create controller (app-specific)
   fx make:service <Name> --app=     Create service (app-specific)
   fx make:model <Name>              Create model (database/models)
@@ -482,8 +521,8 @@ export async function run(args) {
   fx make:worker <Name>             Create worker (shared/workers)
   fx make:test <Name>               Create test
   fx dev                            Start dev server (--watch)
-  fx dev:spa                        Start dev server + Vite HMR
-  fx build:spa                      Build SPA for production
+  fx dev:spa [--app=<name>]          Start dev server + Vite HMR
+  fx build:spa [--app=<name>]        Build SPA for production
   fx stop                            Stop server (graceful)
   fx restart                         Restart server (graceful)
   fx test                           Run tests

package/cli/templates/make/app-spa/controllers/AuthController.js

@@ -0,0 +1,114 @@
+import { Controller } from '@fuzionx/framework';
+
+/**
+ * SPA AuthController — JSON API 전용 인증
+ *
+ * 모든 페이지는 Vue에서 렌더링. 서버는 API만 제공.
+ * 세션 기반 인증. JSON 요청/응답.
+ */
+export default class AuthController extends Controller {
+  /** @type {import('@fuzionx/framework').RouteHandler} 로그인 API */
+  static login;
+  /** @type {import('@fuzionx/framework').RouteHandler} 회원가입 API */
+  static register;
+  /** @type {import('@fuzionx/framework').RouteHandler} 로그아웃 API */
+  static logout;
+  /** @type {import('@fuzionx/framework').RouteHandler} 인증 상태 확인 API */
+  static check;
+  /** @type {import('@fuzionx/framework').RouteHandler} 하트비트 (세션 연장) */
+  static heartbeat;
+
+  /**
+   * POST /api/auth/login — 로그인
+   *
+   * email/password 검증 후 세션에 userId 저장.
+   * 성공 → { user }, 실패 → 401 { error }.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async login(ctx) {
+    const { email, password } = ctx.body;
+    const user = await this.service('AuthService').login({ email, password });
+
+    if (!user) {
+      return ctx.status(401).json({ error: ctx.t('auth.login_failed') });
+    }
+
+    ctx.session.set('userId', user.id);
+    ctx.json({ user: { id: user.id, name: user.name, email: user.email, role: user.role } });
+  }
+
+  /**
+   * POST /api/auth/register — 회원가입
+   *
+   * name/email/password/password_confirm 검증.
+   * 성공 → 201 { user }, 실패 → 400 { error }.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async register(ctx) {
+    const { name, email, password, password_confirm } = ctx.body;
+
+    if (password !== password_confirm) {
+      return ctx.status(400).json({ error: ctx.t('auth.password_mismatch') });
+    }
+
+    try {
+      const user = await this.service('AuthService').register({ name, email, password });
+      ctx.session.set('userId', user.id);
+      ctx.status(201).json({ user: { id: user.id, name: user.name, email: user.email } });
+    } catch (e) {
+      ctx.status(e.status || 400).json({ error: ctx.t(e.message) || e.message });
+    }
+  }
+
+  /**
+   * POST /api/auth/logout — 로그아웃
+   *
+   * 세션 파기 후 { success: true } 반환.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async logout(ctx) {
+    ctx.session.destroy();
+    ctx.json({ success: true });
+  }
+
+  /**
+   * GET /api/auth/check — 인증 상태 확인
+   *
+   * 세션에 userId 존재 → DB 조회 → { authenticated, user }.
+   * 미인증 시 { authenticated: false, user: null }.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async check(ctx) {
+    const userId = ctx.session.get('userId');
+    if (!userId) return ctx.json({ authenticated: false, user: null });
+
+    try {
+      const user = await this.db.User.find(userId);
+      if (!user) return ctx.json({ authenticated: false, user: null });
+      ctx.json({ authenticated: true, user: user.toJSON() });
+    } catch {
+      ctx.json({ authenticated: false, user: null });
+    }
+  }
+
+  /**
+   * GET /api/heartbeat — 세션 연장 (하트비트)
+   *
+   * 인증된 사용자의 세션 유지. { alive, user }.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async heartbeat(ctx) {
+    if (!ctx.user) return ctx.status(401).json({ alive: false });
+    ctx.json({ alive: true, user: { id: ctx.user.id } });
+  }
+}

package/cli/templates/make/app-spa/controllers/HomeController.js

@@ -0,0 +1,66 @@
+import { Controller } from '@fuzionx/framework';
+
+/**
+ * SPA HomeController — Vue 셸 렌더링
+ *
+ * 모든 프론트엔드 라우트에 대해 Vue 앱 셸을 서빙.
+ * 인증 여부와 관계없이 셸을 렌더링하며,
+ * 유저 데이터를 ASP 암호화하여 Vue에 전달.
+ * Vue가 user=null이면 로그인 화면, 아니면 대시보드를 표시.
+ *
+ * bridge.cryptoEncryptCustom(key, plaintext) → WASM decrypt_custom(key, ciphertext)
+ */
+export default class HomeController extends Controller {
+  /** @type {import('@fuzionx/framework').RouteHandler} SPA 셸 렌더링 */
+  static index;
+
+  /**
+   * GET / | /* — Vue SPA 셸 렌더링
+   *
+   * 세션에서 유저 조회 후 ASP 암호화된 payload와 함께 렌더링.
+   * payload: { user, locale, isDev, asp, app }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async index(ctx) {
+    const clientSecret = this.config.get('app.client_secret');
+    const bridge = this.app._bridge;
+
+    // ASP config에서 masterSecret 가져오기
+    const aspConfig = JSON.parse(bridge.getAspConfig());        
+
+    // 세션에서 유저 조회 (인증 안 되어 있으면 null)
+    let user = null;
+    const userId = ctx.session?.get('userId');
+    if (userId && this.db?.User) {
+      try {
+        const u = await this.db.User.find(userId);
+        if (u) user = { id: u.id, name: u.name, email: u.email, role: u.role };
+      } catch {}
+    }
+
+    const isDev = this.config.get('app.environment') === 'development';
+
+    // SPA에 전달할 payload
+    const payload = {
+      user,
+      locale: ctx.locale,
+      locales: this.app?.i18n?.locales?.() || [],
+      translations: ctx.t.all(),
+      isDev,
+      asp: { headerSignal: aspConfig.headerSignal || 'Ruxy-Enc-Mode', masterSecret: aspConfig.masterSecret },
+      app: { name: this.config.get('app.name'), theme: this.config.get('app.themes.default') },
+    };
+
+    // 암호화 (bridge crypto_encrypt_custom — WASM decrypt_custom과 호환)
+    const encryptedPayload = bridge.cryptoEncryptCustom(clientSecret, JSON.stringify(payload));    
+    
+    ctx.render('home', {
+      __fx__: encryptedPayload,      
+      __fx__enabled: aspConfig.enabled || this.config.get('app.asp').enabled,
+      client_secret: clientSecret,
+      isDev,
+    });
+  }
+}

package/cli/templates/make/app-spa/controllers/PostController.js

@@ -0,0 +1,191 @@
+import { Controller, DateUtil } from '@fuzionx/framework';
+
+/**
+ * SPA PostController — 게시판 REST API
+ *
+ * RESTful CRUD. JSON 요청/응답.
+ * r.resource('posts', PostController) 로 자동 라우트 등록.
+ */
+export default class PostController extends Controller {
+  /** @type {import('@fuzionx/framework').RouteHandler} 게시글 목록 조회 */
+  static index;
+  /** @type {import('@fuzionx/framework').RouteHandler} 게시글 상세 조회 */
+  static show;
+  /** @type {import('@fuzionx/framework').RouteHandler} 게시글 작성 */
+  static store;
+  /** @type {import('@fuzionx/framework').RouteHandler} 게시글 수정 */
+  static update;
+  /** @type {import('@fuzionx/framework').RouteHandler} 게시글 삭제 */
+  static destroy;
+
+  /**
+   * GET /api/posts — 게시글 목록 (페이지네이션)
+   *
+   * query.page로 페이지 결정. 10건씩 조회.
+   * 응답: { data, page, lastPage, hasMore, total, perPage }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async index(ctx) {
+    const page = parseInt(ctx.query.page || '1');
+    const result = await this.service('PostService').list(page, 10);
+
+    // 게시글 목록의 대표 썸네일 한 번에 조회 (N+1 방지)
+    const postIds = result.data.map(p => p.id);
+    const thumbMap = await this.service('PostService').getPostThumbnails(postIds);
+
+    // 작성자 이름 batch 조회 (N+1 방지)
+    const userIds = [...new Set(result.data.map(p => p.user_id).filter(Boolean))];
+    const userMap = new Map();
+    if (userIds.length) {
+      const users = await this.db.User.query().whereIn('id', userIds).get();
+      for (const u of users) userMap.set(u.id, u.name);
+    }
+
+    // 각 게시글에 thumbUrl, user_name, 포맷된 날짜 추가
+    const posts = result.data.map(p => ({
+      ...p,
+      thumbUrl: thumbMap.get(p.id) || null,
+      user_name: userMap.get(p.user_id) || '-',
+      created_at: DateUtil.format(p.created_at, 'YYYY-MM-DD HH:mm'),
+    }));
+
+    ctx.json({
+      data: posts,
+      page: result.page,
+      lastPage: result.lastPage,
+      hasMore: result.hasMore,
+      total: result.total,
+    });
+  }
+
+  /**
+   * GET /api/posts/:id — 게시글 상세 조회
+   *
+   * 게시글 + 작성자 정보 반환. 미존재 시 404.
+   * 응답: { post, author }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async show(ctx) {
+    const postService = this.service('PostService');
+    const post = await postService.find(ctx.params.id);
+    if (!post) return ctx.status(404).json({ error: ctx.t('post.not_found') });
+
+    const author = await this.db.User.find(post.user_id);
+    const files = await postService.getAttachmentsWithThumbs(post.id);
+
+    ctx.json({
+      post: { ...post, created_at: DateUtil.format(post.created_at, 'YYYY-MM-DD HH:mm') },
+      author: author ? { id: author.id, name: author.name } : null,
+      files,
+    });
+  }
+
+  /**
+   * POST /api/posts — 게시글 작성
+   *
+   * JSON body에서 title/content 추출. 현재 사용자의 user_id 자동 설정.
+   * 응답: 201 { post }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async store(ctx) {
+    // 업로드 오류 처리 (파일 타입/크기 제한 등)
+    if (ctx.uploadError) {
+      return ctx.status(400).json({ error: ctx.uploadError });
+    }
+    const { title, content } = ctx.body;
+    const uploadedFiles = ctx.files || [];
+    const post = await this.service('PostService').create(
+      { title, content, user_id: ctx.user.id },
+      uploadedFiles,
+    );
+    ctx.status(201).json({ post });
+  }
+
+  /**
+   * PUT /api/posts/:id — 게시글 수정
+   *
+   * 작성자 본인만 수정 가능. 권한 없으면 403.
+   * 응답: { post }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async update(ctx) {
+    // 업로드 오류 처리
+    if (ctx.uploadError) {
+      return ctx.status(400).json({ error: ctx.uploadError });
+    }
+    const post = await this.service('PostService').find(ctx.params.id);
+    if (!post || post.user_id !== ctx.user.id) {
+      return ctx.status(403).json({ error: ctx.t('common.forbidden') });
+    }
+    const { title, content } = ctx.body;
+    const uploadedFiles = ctx.files || [];
+    await this.service('PostService').update(ctx.params.id, { title, content }, uploadedFiles);
+    const updated = await this.service('PostService').find(ctx.params.id);
+    ctx.json({ post: updated });
+  }
+
+  /**
+   * DELETE /api/posts/:id — 게시글 삭제
+   *
+   * 작성자 본인만 삭제 가능. 권한 없으면 403.
+   * 응답: { deleted: true }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async destroy(ctx) {
+    const post = await this.service('PostService').find(ctx.params.id);
+    if (!post || post.user_id !== ctx.user.id) return ctx.status(403).json({ error: ctx.t('common.forbidden') });
+    await this.service('PostService').remove(ctx.params.id);
+    ctx.json({ deleted: true });
+  }
+
+  /**
+   * GET /api/posts/status?ids=1,2,3 — 게시글 상태 JSON 반환
+   *
+   * processing 상태 폴링용. SSR PostController.status와 동일.
+   * 응답: { statuses: { 1: 'published', 2: 'processing' } }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   */
+  async status(ctx) {
+    const raw = ctx.query.ids || '';
+    const ids = raw.split(',').map(Number).filter(Boolean);
+    if (!ids.length) return ctx.json({ statuses: {} });
+
+    const posts = await this.db.Post.query().whereIn('id', ids).get();
+    const statuses = {};
+    for (const p of posts) {
+      statuses[p.id] = p.status || 'published';
+    }
+    ctx.json({ statuses });
+  }
+
+  /**
+   * DELETE /api/posts/attachment/:id — 개별 첨부파일 삭제
+   *
+   * 수정 화면에서 기존 첨부파일 개별 삭제.
+   * 작성자 본인만 삭제 가능.
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   */
+  async deleteAttachment(ctx) {
+    const att = await this.db.Attachment.find(ctx.params.id);
+    if (!att) return ctx.status(404).json({ error: 'Not found' });
+
+    const post = await this.db.Post.find(att.post_id);
+    if (!post || post.user_id !== ctx.user.id) return ctx.status(403).json({ error: 'Forbidden' });
+
+    await this.service('PostService').removeAttachment(att.id);
+    ctx.json({ deleted: true });
+  }
+
+}

package/cli/templates/make/app-spa/controllers/UserController.js

@@ -0,0 +1,43 @@
+import { Controller } from '@fuzionx/framework';
+
+/**
+ * SPA UserController — 사용자 프로필 REST API
+ *
+ * 프로필 조회/수정. JSON 요청/응답.
+ */
+export default class UserController extends Controller {
+  /** @type {import('@fuzionx/framework').RouteHandler} 프로필 조회 */
+  static profile;
+  /** @type {import('@fuzionx/framework').RouteHandler} 프로필 수정 */
+  static updateProfile;
+
+  /**
+   * GET /api/user/profile — 프로필 조회
+   *
+   * 인증된 사용자의 기본 정보 반환.
+   * 응답: { user: { id, name, email, role } }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async profile(ctx) {
+    const { id, name, email, role } = ctx.user;
+    ctx.json({ user: { id, name, email, role } });
+  }
+
+  /**
+   * PUT /api/user/profile — 프로필 수정
+   *
+   * JSON body에서 name/email/password 추출.
+   * UserService.update() 호출 후 갱신된 사용자 정보 반환.
+   * 응답: { user: { id, name, email, role } }
+   *
+   * @param {import('@fuzionx/framework').Context} ctx - 요청 컨텍스트
+   * @returns {void}
+   */
+  async updateProfile(ctx) {
+    const { name, email, password } = ctx.body;
+    const user = await this.service('UserService').update(ctx.user.id, { name, email, password });
+    ctx.json({ user: { id: user.id, name: user.name, email: user.email, role: user.role } });
+  }
+}