@fuzionx/framework 0.1.46 → 0.1.47

package/cli/templates/make/app-spa/routes/api.js

@@ -0,0 +1,31 @@
+import { auth } from '@fuzionx/framework';
+import AuthController from '../controllers/AuthController.js';
+import UserController from '../controllers/UserController.js';
+import PostController from '../controllers/PostController.js';
+
+export default (r) => {
+  // ── Auth API (인증 불필요) ──
+  r.post('/api/auth/login', AuthController.login);
+  r.post('/api/auth/register', AuthController.register);
+  r.post('/api/auth/logout', AuthController.logout);
+  r.get('/api/auth/check', AuthController.check);
+
+  // ── Protected API (인증 필요) ──
+  r.group('/api', { middleware: [auth()] }, (r) => {
+    // 프로필
+    r.get('/user/profile', UserController.profile);
+    r.put('/user/profile', UserController.updateProfile);
+
+    // 게시판 (RESTful resource)
+    r.resource('posts', PostController);
+
+    // 게시글 상태 폴링 (processing 관련)
+    r.get('/posts/status', PostController.status);
+
+    // 개별 첨부파일 삭제
+    r.delete('/posts/attachment/:id', PostController.deleteAttachment);
+
+    // 하트비트 (세션 연장)
+    r.get('/heartbeat', AuthController.heartbeat);
+  });
+};

package/cli/templates/make/app-spa/routes/web.js

@@ -0,0 +1,19 @@
+import { auth } from '@fuzionx/framework';
+import HomeController from '../controllers/HomeController.js';
+import PostController from '../controllers/PostController.js';
+
+export default (r) => {
+  // SPA Shell — 모든 프론트엔드 라우트에 대해 Vue 앱 서빙
+  // Vue Router가 클라이언트에서 login, register, board 등 처리
+  r.get('/', HomeController.index);
+
+  // ── 파일 업로드 (ASP bypass — /api 가 아닌 경로) ──
+  // XHR uploadWithProgress는 plain POST → ASP 헤더 없음
+  // /api 경로는 ASP 필수이므로 /board 경로로 우회
+  r.group('', { middleware: [auth()] }, (r) => {
+    r.post('/board', PostController.store);
+    r.post('/board/:id', PostController.update);
+  });
+
+  r.get('/*', HomeController.index);
+};

package/cli/templates/make/app-spa/services/AuthService.js

@@ -0,0 +1,48 @@
+import { Service } from '@fuzionx/framework';
+
+/**
+ * AuthService — SPA 인증 서비스
+ *
+ * 회원가입/로그인 비즈니스 로직 처리.
+ * bcrypt 해시를 사용한 비밀번호 암호화 및 검증.
+ *
+ * @extends Service
+ */
+export default class AuthService extends Service {
+  /**
+   * 회원가입 — 신규 사용자 생성
+   *
+   * 이메일 중복 검사 후 bcrypt 해시 비밀번호로 사용자 생성.
+   *
+   * @param {Object} data - 가입 정보
+   * @param {string} data.name     - 사용자 이름
+   * @param {string} data.email    - 이메일 주소
+   * @param {string} data.password - 비밀번호 (평문 → bcrypt 해시 변환)
+   * @returns {Promise<import('../../../database/models/User.js').default>} 생성된 사용자
+   * @throws {AppError} 409 — 이메일 중복 시
+   */
+  async register({ name, email, password }) {
+    const existing = await this.db.User.where('email', email).first();
+    if (existing) throw this.error('auth.email_exists', 409);
+
+    const hash = this.app.hash.bcrypt(password);
+    return this.db.User.create({ name, email, password: hash, role: 'user' });
+  }
+
+  /**
+   * 로그인 — 이메일/비밀번호 검증
+   *
+   * 이메일로 사용자 조회 후 bcrypt 비밀번호 대조.
+   *
+   * @param {Object} credentials - 로그인 정보
+   * @param {string} credentials.email    - 이메일 주소
+   * @param {string} credentials.password - 비밀번호 (평문)
+   * @returns {Promise<import('../../../database/models/User.js').default|null>} 인증된 사용자 또는 null
+   */
+  async login({ email, password }) {
+    const user = await this.db.User.where('email', email).first();
+    if (!user) return null;
+    if (!this.app.hash.bcryptVerify(password, user.password)) return null;
+    return user;
+  }
+}

package/cli/templates/make/app-spa/services/PostService.js

@@ -0,0 +1,372 @@
+import { Service } from '@fuzionx/framework';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * PostService — SSR 게시글 + 첨부파일 + 썸네일 서비스
+ *
+ * ## 주요 기능
+ * - 게시글 CRUD (list, find, create, update, remove)
+ * - 첨부파일 저장/삭제 (Storage API)
+ * - 썸네일 자동 생성 (이미지: resize, 비디오: frame 추출)
+ *
+ * ## 썸네일 생성 전략
+ * - **이미지 파일**: `app.media.resize()` → 400x300 webp 썸네일
+ * - **비디오 파일**: `app.media.videoThumbnail()` → 3초 지점 프레임 추출 → jpeg
+ * - 썸네일은 `storage/uploads/thumbs/{attachmentId}.webp` 에 저장
+ * - Thumbnail 모델에 메타데이터(경로, 크기, 포맷, source_type) 기록
+ *
+ * ## 사용 예시
+ * ```js
+ * // 컨트롤러에서
+ * const post = await this.service('PostService').create(
+ *   { title: '제목', content: '내용', user_id: ctx.user.id },
+ *   ctx.files,   // Bridge 업로드 파일 배열
+ * );
+ *
+ * // 첨부파일 + 썸네일 조회
+ * const files = await this.service('PostService').getAttachmentsWithThumbs(post.id);
+ * // → [{ ...attachment, thumbUrl, isImage, isVideo }]
+ * ```
+ *
+ * @extends Service
+ */
+export default class PostService extends Service {
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  //  게시글 CRUD
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /**
+   * 게시글 목록 조회 (페이지네이션)
+   *
+   * @param {number} [page=1]     - 현재 페이지 번호
+   * @param {number} [perPage=10] - 페이지당 게시글 수
+   * @returns {Promise<{ data: Post[], page, lastPage, hasMore, total }>}
+   */
+  async list(page = 1, perPage = 10) {
+    return this.db.Post.query()
+      .orderBy('created_at', 'desc')
+      .paginate(page, perPage);
+  }
+
+  /**
+   * 게시글 단건 조회
+   *
+   * @param {number} id - 게시글 ID
+   * @returns {Promise<Post|null>}
+   */
+  async find(id) {
+    return this.db.Post.find(id);
+  }
+
+  /**
+   * 게시글 생성 + 첨부파일 + 썸네일
+   *
+   * @param {Object} data        - { title, content, user_id }
+   * @param {Array}  [files=[]]  - Bridge 업로드 파일 배열 [{fieldName, originalName, mimeType, size, tempPath}]
+   * @returns {Promise<Post>}
+   *
+   * @example
+   * const post = await postService.create(
+   *   { title: 'Hello', content: 'World', user_id: 1 },
+   *   ctx.files,
+   * );
+   */
+  async create(data, files = []) {
+    // 비디오 포함 여부에 따라 초기 status 결정
+    const hasVideo = files?.some(f => f.mimeType?.startsWith('video/'));
+    data.status = hasVideo ? 'processing' : 'published';
+    const post = await this.db.Post.create(data);
+    if (files?.length) {
+      await this._processFiles(post.id, files);
+    }
+    return post;
+  }
+
+  /**
+   * 게시글 수정 + 새 첨부파일 추가
+   *
+   * @param {number} id         - 게시글 ID
+   * @param {Object} data       - { title, content }
+   * @param {Array}  [files=[]] - 새로 추가할 파일
+   * @returns {Promise<Post>}
+   */
+  async update(id, data, files = []) {
+    const post = await this.db.Post.find(id);
+    if (!post) throw this.error('Post not found', 404);
+    await post.update(data);
+    if (files?.length) {
+      const hasVideo = files.some(f => f.mimeType?.startsWith('video/'));
+      if (hasVideo) await post.update({ status: 'processing' });
+      await this._processFiles(post.id, files);
+    }
+    return post;
+  }
+
+  /**
+   * 게시글 삭제 + 모든 첨부파일/썸네일 삭제
+   *
+   * 삭제 순서: 썸네일 → 첨부파일(Storage + DB) → 게시글
+   *
+   * @param {number} id - 게시글 ID
+   * @returns {Promise<void>}
+   */
+  async remove(id) {
+    const post = await this.db.Post.find(id);
+    if (!post) throw this.error('Post not found', 404);
+    await this._deleteAllFiles(id);
+    await post.delete();
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  //  첨부파일 + 썸네일 조회
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /**
+   * 게시글의 첨부파일 목록 + 썸네일 URL 포함
+   *
+   * 반환 객체에 추가되는 필드:
+   * - `url`      : 원본 파일 공개 URL
+   * - `thumbUrl` : 썸네일 URL (없으면 null)
+   * - `isImage`  : MIME이 image/* 인지 여부
+   * - `isVideo`  : MIME이 video/* 인지 여부
+   *
+   * @param {number} postId - 게시글 ID
+   * @returns {Promise<Array<Object>>}
+   *
+   * @example
+   * const files = await postService.getAttachmentsWithThumbs(postId);
+   * // → [{ id, original_name, url, thumbUrl, isImage, isVideo, size, mime_type }]
+   */
+  async getAttachmentsWithThumbs(postId) {
+    const attachments = await this.db.Attachment.where('post_id', postId).get();
+    if (!attachments.length) return [];
+
+    // 모든 썸네일을 한 번에 조회 (N+1 방지)
+    const attIds = attachments.map(a => a.id);
+    const thumbnails = await this.db.Thumbnail.query()
+      .whereIn('attachment_id', attIds)
+      .get();
+
+    // attachment_id → thumbnail 매핑
+    const thumbMap = new Map();
+    for (const t of thumbnails) {
+      thumbMap.set(t.attachment_id, t);
+    }
+
+    return attachments.map(att => {
+      const thumb = thumbMap.get(att.id);
+      return {
+        ...att,
+        url: this.app.storage.url(att.file_path),
+        thumbUrl: thumb ? this.app.storage.url(thumb.file_path) : null,
+        isImage: att.mime_type?.startsWith('image/'),
+        isVideo: att.mime_type?.startsWith('video/'),
+      };
+    });
+  }
+
+  /**
+   * 게시글 목록용 — 각 게시글의 대표 썸네일 1개 조회
+   *
+   * 첫 번째 첨부파일의 썸네일을 대표 이미지로 사용.
+   * 게시글 목록 페이지에서 미리보기 이미지 제공용.
+   *
+   * @param {number[]} postIds - 게시글 ID 배열
+   * @returns {Promise<Map<number, string|null>>} postId → thumbUrl
+   *
+   * @example
+   * const thumbMap = await postService.getPostThumbnails([1, 2, 3]);
+   * // → Map { 1 => '/storage/uploads/thumbs/5.webp', 2 => null, 3 => '...' }
+   */
+  async getPostThumbnails(postIds) {
+    if (!postIds.length) return new Map();
+
+    // 각 게시글의 첫 첨부파일 조회
+    const attachments = await this.db.Attachment.query()
+      .whereIn('post_id', postIds)
+      .orderBy('id', 'asc')
+      .get();
+
+    // postId → 첫 attachment 매핑
+    const firstAttMap = new Map();
+    for (const att of attachments) {
+      if (!firstAttMap.has(att.post_id)) {
+        firstAttMap.set(att.post_id, att);
+      }
+    }
+
+    // 첫 첨부파일들의 썸네일 조회
+    const attIds = [...firstAttMap.values()].map(a => a.id);
+    if (!attIds.length) return new Map();
+
+    const thumbnails = await this.db.Thumbnail.query()
+      .whereIn('attachment_id', attIds)
+      .get();
+
+    const thumbByAtt = new Map();
+    for (const t of thumbnails) {
+      thumbByAtt.set(t.attachment_id, t);
+    }
+
+    // postId → thumbUrl 매핑
+    const result = new Map();
+    for (const pid of postIds) {
+      const att = firstAttMap.get(pid);
+      if (att) {
+        const thumb = thumbByAtt.get(att.id);
+        result.set(pid, thumb ? this.app.storage.url(thumb.file_path) : null);
+      } else {
+        result.set(pid, null);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 특정 첨부파일 삭제 (썸네일 포함)
+   *
+   * @param {number} attachmentId - 첨부파일 ID
+   * @returns {Promise<void>}
+   */
+  async removeAttachment(attachmentId) {
+    const att = await this.db.Attachment.find(attachmentId);
+    if (!att) return;
+
+    // 썸네일 삭제
+    await this._deleteThumbnail(attachmentId);
+
+    // 원본 파일 삭제
+    try { await this.app.storage.delete(att.file_path); } catch {}
+    await att.delete();
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  //  Private — 파일 처리 + 썸네일 생성
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /**
+   * 파일 저장 + 썸네일 생성 (이미지/비디오 자동 감지)
+   *
+   * 처리 흐름:
+   * 1. 임시파일 → Storage 영구 저장 (`uploads/posts/{postId}/xxx.ext`)
+   * 2. Attachment DB 레코드 생성
+   * 3. 이미지인 경우 → `app.media.resize()` 로 썸네일 생성
+   * 4. 비디오인 경우 → `app.media.videoThumbnail()` 로 프레임 추출
+   * 5. Thumbnail DB 레코드 생성
+   *
+   * @private
+   * @param {number} postId - 게시글 ID
+   * @param {Array}  files  - [{fieldName, originalName, mimeType, size, tempPath}]
+   */
+  async _processFiles(postId, files) {
+    for (const f of files) {
+      // 1. 원본 파일 저장
+      const ext = f.originalName.split('.').pop() || 'bin';
+      const uid = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      const storagePath = `uploads/posts/${postId}/${uid}.${ext}`;
+      await this.app.storage.put(storagePath, f.tempPath);
+
+      // 2. Attachment 레코드
+      const att = await this.db.Attachment.create({
+        post_id: postId,
+        original_name: f.originalName,
+        file_path: storagePath,
+        mime_type: f.mimeType,
+        size: f.size,
+      });
+
+      // 3. 썸네일 생성 (이미지 or 비디오)
+      const isImage = f.mimeType?.startsWith('image/');
+      const isVideo = f.mimeType?.startsWith('video/');
+
+      if (isImage) {
+        await this._generateImageThumbnail(att, storagePath);
+      } else if (isVideo) {
+        // 비디오 썸네일은 백그라운드 Task로 위임
+        this.app.dispatch('ProcessVideoThumbnailTask', {
+          postId,
+          attachmentId: att.id,
+          storagePath,
+        });
+      }
+    }
+  }
+
+  /**
+   * 이미지 썸네일 생성
+   *
+   * `app.media.resize()` 호출:
+   * - 입력: Storage 원본 이미지
+   * - 출력: 400px 가로 webp (비율 유지, 높이 자동)
+   * - 품질: 80
+   *
+   * @private
+   * @param {Object} att         - Attachment 레코드
+   * @param {string} storagePath - 원본 Storage 경로
+   */
+  async _generateImageThumbnail(att, storagePath) {
+    try {
+      const fullPath = path.join(this.app.storage.basePath, storagePath);
+      const thumbName = `${att.id}.webp`;
+      const thumbStoragePath = `uploads/thumbs/${thumbName}`;
+      const thumbFullPath = path.join(this.app.storage.basePath, thumbStoragePath);
+
+      // 썸네일 디렉토리 생성
+      await fs.mkdir(path.dirname(thumbFullPath), { recursive: true });
+
+      // Bridge 이미지 리사이즈 (Rust native — width:400, height:0 = 비율 유지)
+      this.app.media.resize(fullPath, thumbFullPath, 400, 0, 'webp', 80);
+
+      // 썸네일 파일 정보
+      const stat = await fs.stat(thumbFullPath);
+      let info = { width: 400, height: 0 };
+      try { info = this.app.media.imageInfo(thumbFullPath); } catch {}
+
+      // Thumbnail DB 레코드
+      await this.db.Thumbnail.create({
+        attachment_id: att.id,
+        file_path: thumbStoragePath,
+        width: info.width || 400,
+        height: info.height || 0,
+        format: 'webp',
+        size: stat.size,
+        source_type: 'image',
+      });
+    } catch (err) {
+      console.warn(`[PostService] 이미지 썸네일 생성 실패 (att:${att.id}):`, err.message);
+    }
+  }
+
+  /**
+   * 특정 첨부파일의 썸네일 삭제 (Storage + DB)
+   *
+   * @private
+   * @param {number} attachmentId
+   */
+  async _deleteThumbnail(attachmentId) {
+    const thumbs = await this.db.Thumbnail.where('attachment_id', attachmentId).get();
+    for (const t of thumbs) {
+      try { await this.app.storage.delete(t.file_path); } catch {}
+      await t.delete();
+    }
+  }
+
+  /**
+   * 게시글의 모든 첨부파일 + 썸네일 삭제
+   *
+   * @private
+   * @param {number} postId
+   */
+  async _deleteAllFiles(postId) {
+    const attachments = await this.db.Attachment.where('post_id', postId).get();
+    for (const att of attachments) {
+      // 썸네일 먼저 삭제
+      await this._deleteThumbnail(att.id);
+      // 원본 파일 삭제
+      try { await this.app.storage.delete(att.file_path); } catch {}
+      await att.delete();
+    }
+  }
+}

package/cli/templates/make/app-spa/services/UserService.js

@@ -0,0 +1,48 @@
+import { Service } from '@fuzionx/framework';
+
+/**
+ * UserService — SPA 사용자 서비스
+ *
+ * 사용자 프로필 조회 및 수정 비즈니스 로직 처리.
+ * 비밀번호 변경 시 bcrypt 해시 적용.
+ *
+ * @extends Service
+ */
+export default class UserService extends Service {
+  /**
+   * 사용자 단건 조회
+   *
+   * @param {number} id - 사용자 ID
+   * @returns {Promise<import('../../../database/models/User.js').default|null>} 사용자 또는 null
+   */
+  async find(id) {
+    return this.db.User.find(id);
+  }
+
+  /**
+   * 사용자 프로필 수정
+   *
+   * name, email, password 중 변경된 필드만 업데이트.
+   * password가 있을 경우 bcrypt 해시 후 저장.
+   *
+   * @param {number} id   - 사용자 ID
+   * @param {Object} data - 수정할 데이터
+   * @param {string} [data.name]     - 이름
+   * @param {string} [data.email]    - 이메일
+   * @param {string} [data.password] - 새 비밀번호 (평문 → bcrypt 해시)
+   * @returns {Promise<import('../../../database/models/User.js').default>} 수정된 사용자
+   * @throws {AppError} 404 — 사용자 없음
+   */
+  async update(id, data) {
+    const user = await this.db.User.find(id);
+    if (!user) throw this.error('User not found', 404);
+
+    const updates = {};
+    if (data.name) updates.name = data.name;
+    if (data.email) updates.email = data.email;
+    if (data.password) updates.password = this.app.hash.bcrypt(data.password);
+
+    await user.update(updates);
+    return user;
+  }
+}

package/cli/templates/make/app-spa/views/default/errors/404.html

@@ -0,0 +1,11 @@
+{% extends "layouts/main.html" %}
+{% block title %}404{% endblock %}
+{% block content %}
+<div class="auth-container">
+  <div class="glass-card auth-card">
+    <div class="auth-logo">404</div>
+    <p class="auth-subtitle">{{ t(key="page.404", default="페이지를 찾을 수 없습니다") }}</p>
+    <a href="/" class="btn btn-primary btn-full">{{ t(key="btn.go_home", default="홈으로") }}</a>
+  </div>
+</div>
+{% endblock %}

package/cli/templates/make/app-spa/views/default/errors/500.html

@@ -0,0 +1,11 @@
+{% extends "layouts/main.html" %}
+{% block title %}500{% endblock %}
+{% block content %}
+<div class="auth-container">
+  <div class="glass-card auth-card">
+    <div class="auth-logo">500</div>
+    <p class="auth-subtitle">{{ t(key="page.500", default="서버 오류가 발생했습니다") }}</p>
+    <a href="/" class="btn btn-primary btn-full">{{ t(key="btn.go_home", default="홈으로") }}</a>
+  </div>
+</div>
+{% endblock %}

package/cli/templates/make/app-spa/views/default/layouts/main.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="{{ locale | default(value='ko') }}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{% block title %}FuzionX{% endblock %}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/public/css/style.css">
+  {% block head %}{% endblock %}
+</head>
+<body>
+  <div class="orb orb-1"></div>
+  <div class="orb orb-2"></div>
+  <div class="orb orb-3"></div>
+
+  {% if flash.error %}
+  <div class="container" style="padding-top: 1rem">
+    <div class="alert alert-error">{{ flash.error }}</div>
+  </div>
+  {% endif %}
+  {% if flash.success %}
+  <div class="container" style="padding-top: 1rem">
+    <div class="alert alert-success">{{ flash.success }}</div>
+  </div>
+  {% endif %}
+
+  <main class="main-content">
+    {% block content %}{% endblock %}
+  </main>
+
+  {% block scripts %}{% endblock %}
+</body>
+</html>

package/cli/templates/make/app-spa/views/default/pages/home.html

@@ -0,0 +1,22 @@
+{% extends "layouts/main.html" %}
+{% block title %}FuzionX SPA{% endblock %}
+
+{% block head %}
+{% if isDev %}
+<script type="module" src="http://localhost:5173/@vite/client"></script>
+<script type="module" src="http://localhost:5173/src/main.js"></script>
+{% else %}
+<script type="module" src="/public/dist/assets/main.js"></script>
+<link rel="stylesheet" href="/public/dist/assets/main.css">
+{% endif %}
+{% endblock %}
+
+{% block content %}
+<div id="app"></div>
+
+<script>
+  window.__FX_CLIENT_SECRET__ = "{{ client_secret | safe }}";
+  window.__FX__ = "{{ __fx__ | safe }}";
+  window.__FX__ENC_ENABLED = {{ __fx__enabled | safe }}  
+</script>
+{% endblock %}

package/cli/templates/make/app-spa/views/default/spa/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>FuzionX SPA</title>
+  <meta name="description" content="FuzionX — Rust-powered Node.js framework for the modern web." />
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,20 @@
+{
+  "name": "fuzionx-spa",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "pinia": "^3.0.4",
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.0",
+    "vite": "^6.0.0"
+  }
+}

package/cli/templates/make/app-spa/views/default/spa/src/App.vue

@@ -0,0 +1,41 @@
+<!--
+  App.vue — SPA 루트 컴포넌트.
+  
+  SSR main.html 레이아웃을 Vue 컴포넌트로 구현:
+  배경 orbs + Navbar (항상 표시) + FlashMessage + router-view.
+-->
+<template>
+  <div class="app-wrapper">
+    <!-- 배경 Orbs — SSR main.html body -->
+    <div class="orb orb-1"></div>
+    <div class="orb orb-2"></div>
+    <div class="orb orb-3"></div>
+
+    <!-- 네비게이션 바 — 항상 표시 -->
+    <Navbar />
+
+    <main class="main-content has-nav">
+      <!-- Flash 메시지 — SSR flash.error / flash.success -->
+      <FlashMessage />
+      <router-view />
+    </main>
+
+    <!-- 글로벌 Toast + Alert -->
+    <ToastContainer />
+    <AlertDialog />
+  </div>
+</template>
+
+<script setup>
+import { useAuthStore } from './stores/auth.js';
+import { useHeartbeat } from './composables/useHeartbeat.js';
+import Navbar from './components/Navbar.vue';
+import FlashMessage from './components/FlashMessage.vue';
+import ToastContainer from './components/ToastContainer.vue';
+import AlertDialog from './components/AlertDialog.vue';
+
+const authStore = useAuthStore();
+
+// 인증된 사용자만 하트비트 시작
+useHeartbeat();
+</script>