create-fuzionx 0.1.34 → 0.1.37

package/index.js

@@ -193,7 +193,8 @@ try {
     cd ${name}
     npm install
     ${type === 'spa' ? `cd app/spa/views/default/spa && npm install && cd ../../../../..
-    ` : ''}${nextCmd}
+    ` : ''}npx fx db:sync --apply
+    ${nextCmd}
 `);
 } catch (err) {
     console.error(`❌ Failed to create app: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fuzionx",
-  "version": "0.1.34",
+  "version": "0.1.37",
   "description": "Create a new FuzionX application — npx create-fuzionx my-app",
   "type": "module",
   "bin": {

package/templates/common/database/models/Attachment.js

@@ -0,0 +1,41 @@
+import { SQLiteModel } from '@fuzionx/framework';
+
+/**
+ * Attachment — 게시글 첨부파일 모델
+ *
+ * 게시글에 첨부된 파일 메타데이터를 관리.
+ * 실제 파일은 storage/uploads/ 에 저장, DB에는 경로만 보관.
+ *
+ * @extends SQLiteModel
+ */
+export default class Attachment extends SQLiteModel {
+  /** @type {string} 테이블 명 */
+  static table = 'attachments';
+
+  /** @type {boolean} created_at 자동 관리 */
+  static timestamps = true;
+
+  /**
+   * 컬럼 정의
+   *
+   * @type {Object<string, import('@fuzionx/framework').ColumnDefinition>}
+   * @property {Object} id            - 자동 증가 기본키 (PK)
+   * @property {Object} post_id       - 게시글 ID (FK → posts.id)
+   * @property {Object} original_name - 원본 파일명
+   * @property {Object} file_path     - Storage 상대 경로 (uploads/posts/xxx.jpg)
+   * @property {Object} mime_type     - MIME 타입 (image/jpeg, application/pdf 등)
+   * @property {Object} size          - 파일 크기 (bytes)
+   * @property {Object} created_at    - 업로드 일시
+   * @property {Object} updated_at    - 수정 일시
+   */
+  static columns = {
+    id:            { type: 'increments' },
+    post_id:       { type: 'integer' },
+    original_name: { type: 'string', length: 255 },
+    file_path:     { type: 'string', length: 500 },
+    mime_type:     { type: 'string', length: 100 },
+    size:          { type: 'integer' },
+    created_at:    { type: 'datetime' },
+    updated_at:    { type: 'datetime' },
+  };
+}

package/templates/common/database/models/Post.js

@@ -0,0 +1,39 @@
+import { SQLiteModel } from '@fuzionx/framework';
+
+/**
+ * Post — 게시글 모델
+ *
+ * 게시판의 게시글 데이터를 관리하는 모델.
+ * 사용자(User)와 N:1 관계로, `user_id` 외래키로 연결.
+ *
+ * @extends SQLiteModel
+ */
+export default class Post extends SQLiteModel {
+  /** @type {string} 테이블 명 */
+  static table = 'posts';
+
+  /** @type {boolean} created_at / updated_at 자동 관리 */
+  static timestamps = true;
+
+  /**
+   * 컬럼 정의
+   *
+   * @type {Object<string, import('@fuzionx/framework').ColumnDefinition>}
+   * @property {Object} id         - 자동 증가 기본키 (PK)
+   * @property {Object} user_id    - 작성자 ID (FK → users.id)
+   * @property {Object} title      - 게시글 제목 (최대 200자)
+   * @property {Object} content    - 게시글 본문 (TEXT)
+   * @property {Object} status     - 상태: 'published' | 'processing'
+   * @property {Object} created_at - 생성 일시
+   * @property {Object} updated_at - 수정 일시
+   */
+  static columns = {
+    id:         { type: 'increments' },
+    user_id:    { type: 'integer' },
+    title:      { type: 'string', length: 200 },
+    content:    { type: 'text' },
+    status:     { type: 'string', length: 20, default: 'published' },
+    created_at: { type: 'datetime' },
+    updated_at: { type: 'datetime' },
+  };
+}

package/templates/common/database/models/Thumbnail.js

@@ -0,0 +1,53 @@
+import { SQLiteModel } from '@fuzionx/framework';
+
+/**
+ * Thumbnail — 첨부파일 썸네일 모델
+ *
+ * 이미지/비디오 첨부파일의 썸네일 메타데이터.
+ * - 이미지: 원본을 리사이즈하여 webp로 저장
+ * - 비디오: 3초 지점 프레임 추출 후 리사이즈
+ *
+ * Attachment 1:1 관계 (attachment_id FK).
+ * 실제 파일은 storage/uploads/thumbs/ 에 저장.
+ *
+ * @example
+ * // 썸네일 조회
+ * const thumb = await Thumbnail.where('attachment_id', att.id).first();
+ * const url = app.storage.url(thumb.file_path);
+ *
+ * @extends SQLiteModel
+ */
+export default class Thumbnail extends SQLiteModel {
+  /** @type {string} 테이블 명 */
+  static table = 'thumbnails';
+
+  /** @type {boolean} created_at 자동 관리 */
+  static timestamps = true;
+
+  /**
+   * 컬럼 정의
+   *
+   * @type {Object<string, import('@fuzionx/framework').ColumnDefinition>}
+   * @property {Object} id            - 자동 증가 PK
+   * @property {Object} attachment_id - 첨부파일 ID (FK → attachments.id)
+   * @property {Object} file_path     - Storage 상대 경로 (uploads/thumbs/xxx.webp)
+   * @property {Object} width         - 썸네일 가로 크기 (px)
+   * @property {Object} height        - 썸네일 세로 크기 (px)
+   * @property {Object} format        - 포맷 (webp, jpeg)
+   * @property {Object} size          - 파일 크기 (bytes)
+   * @property {Object} source_type   - 원본 타입 (image|video)
+   * @property {Object} created_at    - 생성 일시
+   */
+  static columns = {
+    id:            { type: 'increments' },
+    attachment_id: { type: 'integer' },
+    file_path:     { type: 'string', length: 500 },
+    width:         { type: 'integer' },
+    height:        { type: 'integer' },
+    format:        { type: 'string', length: 20 },
+    size:          { type: 'integer' },
+    source_type:   { type: 'string', length: 20 },
+    created_at:    { type: 'datetime' },
+    updated_at:    { type: 'datetime' },
+  };
+}

package/templates/common/database/models/User.js

@@ -1,9 +1,35 @@
-import { MariaModel } from '@fuzionx/framework';
-
-export default class User extends MariaModel {
-    static table = 'users';
-    static connection = 'main';
-    static softDelete = true;
-    static hidden = ['password'];
-    static fillable = ['name', 'email', 'password', 'role'];
+import { SQLiteModel } from '@fuzionx/framework';
+
+/**
+ * User — 사용자 모델
+ *
+ * 인증 및 사용자 프로필 데이터를 관리하는 모델.
+ * `password` 필드는 hidden 처리되어 JSON 직렬화 시 제외.
+ *
+ * @extends SQLiteModel
+ */
+export default class User extends SQLiteModel {
+  /** @type {string} 테이블 명 */
+  static table = 'users';
+
+  /** @type {boolean} created_at / updated_at 자동 관리 */
+  static timestamps = true;
+
+  /** @type {string[]} JSON 직렬화 시 제외할 필드 */
+  static hidden = ['password'];
+
+  /**
+   * 컬럼 정의
+   *
+   * @type {Object<string, import('@fuzionx/framework').ColumnDefinition>}
+   */
+  static columns = {
+    id:         { type: 'increments' },
+    name:       { type: 'string', length: 100 },
+    email:      { type: 'string', length: 150, unique: true },
+    password:   { type: 'string', length: 255 },
+    role:       { type: 'string', length: 20, default: 'user' },
+    created_at: { type: 'datetime' },
+    updated_at: { type: 'datetime' },
+  };
 }

package/templates/common/package.json.tpl

@@ -9,8 +9,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@fuzionx/framework": "^0.1.34",
-    "@fuzionx/client": "^0.1.34",
+    "@fuzionx/framework": "^0.1.37",
+    "@fuzionx/client": "^0.1.37",
     "joi": "^18.1.1"
   },
   "devDependencies": {

package/templates/common/shared/jobs/ProcessVideoThumbnailTask.js

@@ -0,0 +1,110 @@
+import { Task } from '@fuzionx/framework';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * ProcessVideoThumbnailTask — 비디오 썸네일 백그라운드 처리
+ *
+ * this.worker.run()을 사용하여 CPU-intensive 작업을 별도 스레드에 위임.
+ * Worker 결과를 받아 메인 스레드에서 DB 등록을 수행합니다.
+ *
+ * 흐름:
+ * 1. Worker 스레드: 프레임 추출 + 스프라이트 시트 생성 (CPU-intensive)
+ * 2. 메인 스레드: DB 등록 + Post.status 업데이트 (I/O)
+ */
+export default class ProcessVideoThumbnailTask extends Task {
+  static queue = 'default';
+  static retries = 2;
+  static retryDelay = 3000;
+  static timeout = 300000; // 5분 (대용량 영상)
+
+  async handle(data) {
+    const { postId, attachmentId, storagePath } = data;
+    const basePath = this.app.storage.basePath;
+
+    this.logger.info(`[VideoTask] Worker 시작: post=${postId}, att=${attachmentId}`);
+
+    // CPU-intensive 작업을 WorkerPool로 위임
+    const result = await this.worker.run('video-worker', {
+      postId, attachmentId, storagePath, basePath,
+      bridgeModulePath: this._findBridgePath(),
+    }, { timeout: 300000 });
+
+    // DB 등록 (메인 스레드)
+    const { thumbPaths, spritePath } = result;
+
+    for (const thumbAbsPath of thumbPaths) {
+      try {
+        const thumbRelPath = `uploads/thumbs/video_${attachmentId}/${path.basename(thumbAbsPath)}`;
+        const stat = await fs.stat(thumbAbsPath);
+        await this.db.Thumbnail.create({
+          attachment_id: attachmentId,
+          file_path: thumbRelPath,
+          width: 640,
+          height: 0,
+          format: 'jpeg',
+          size: stat.size,
+          source_type: 'video',
+        });
+      } catch (err) {
+        this.logger.warn(`[VideoTask] 프레임 등록 실패: ${err.message}`);
+      }
+    }
+
+    if (spritePath) {
+      try {
+        const sheetStat = await fs.stat(spritePath);
+        await this.db.Thumbnail.create({
+          attachment_id: attachmentId,
+          file_path: `uploads/thumbs/video_${attachmentId}/sprite.jpeg`,
+          width: 800,
+          height: 0,
+          format: 'jpeg',
+          size: sheetStat.size,
+          source_type: 'sprite',
+        });
+      } catch (err) {
+        this.logger.warn(`[VideoTask] 스프라이트 DB 등록 실패: ${err.message}`);
+      }
+    }
+
+    // Post 상태 → published
+    const post = await this.db.Post.find(postId);
+    if (post) {
+      await post.update({ status: 'published' });
+    }
+    this.logger.info(`[VideoTask] 완료: post=${postId}, att=${attachmentId}, frames=${thumbPaths.length}`);
+  }
+
+  /**
+   * Bridge .node 바이너리 경로 찾기
+   *
+   * npm 패키지 resolve만 사용 — 로컬 개발 시 npm link 또는
+   * workspace protocol("file:../../crates/fuzionx-bridge")로 연결.
+   */
+  _findBridgePath() {
+    const _require = createRequire(import.meta.url);
+    const candidates = ['@fuzionx/bridge', 'fuzionx-bridge'];
+
+    for (const candidate of candidates) {
+      try {
+        _require.resolve(candidate);
+        return candidate;
+      } catch {}
+    }
+    throw new Error(
+      'Bridge .node 바이너리를 찾을 수 없습니다. ' +
+      'npm install @fuzionx/bridge 또는 package.json에 workspace 의존성을 추가하세요.'
+    );
+  }
+
+  async failed(data, error) {
+    const msg = error?.message || error?.toString?.() || String(error);
+    this.logger.error(`[VideoTask] 최종 실패: post=${data.postId}, error=${msg}`);
+    try {
+      const post = await this.db.Post.find(data.postId);
+      if (post) await post.update({ status: 'published' });
+    } catch {}
+  }
+}

package/templates/common/shared/jobs/SampleQueuedTask.js

@@ -0,0 +1,84 @@
+import { Task } from '@fuzionx/framework';
+
+/**
+ * SampleQueuedTask — 비동기 큐 작업 샘플
+ *
+ * Task를 상속하여 비동기 위임 작업을 구현합니다.
+ * 기본적으로 메인 스레드에서 실행되므로
+ * this.db, this.service() 등 앱 컨텍스트에 접근 가능합니다.
+ *
+ * ## 디스패치 방법 (컨트롤러/서비스에서)
+ *   app.dispatch('SampleQueuedTask', { userId: 1, email: 'user@example.com' });
+ *
+ * ## Task vs Job 차이점
+ *   - Job:  정기 실행 (cron 스케줄, Scheduler)
+ *   - Task: 비동기 위임 (큐, dispatch()로 호출)
+ *
+ * ## 실행 모드 (useWorker)
+ * - false (기본): 메인 스레드 — this.db, this.service() 접근 가능
+ * - true        : worker_thread — CPU 전용, this.logger만 사용 가능
+ *
+ * ## CPU-intensive 작업이 필요한 경우
+ * handle() 내에서 직접 Worker를 생성하여 위임하고,
+ * Worker 결과를 받아 메인 스레드에서 DB 작업을 수행합니다.
+ * (ProcessVideoThumbnailTask.js 참고)
+ */
+export default class SampleQueuedTask extends Task {
+  /** 큐 이름 — 동일 큐 내 순차 처리 */
+  static queue = 'emails';
+
+  /** 최대 재시도 횟수 */
+  static retries = 3;
+
+  /** 재시도 딜레이 (ms) */
+  static retryDelay = 5000;
+
+  /** 타임아웃 (ms) */
+  static timeout = 30000;
+
+  /**
+   * Task 실행 — 메인 스레드에서 실행 (DB 접근 가능)
+   *
+   * @param {object} data - dispatch() 시 전달된 데이터
+   * @param {number} data.userId - 사용자 ID
+   * @param {string} data.email  - 이메일 주소
+   */
+  async handle(data) {
+    const { userId, email } = data;
+    this.logger.info(`[SampleTask] 환영 이메일 발송 시작: userId=${userId}, email=${email}`);
+
+    // DB에서 사용자 조회
+    // const user = await this.db.User.find(userId);
+    // if (!user) {
+    //   this.logger.warn(`[SampleTask] 사용자 없음: ${userId}`);
+    //   return;
+    // }
+
+    // 서비스를 통한 이메일 발송
+    // await this.service('MailService').send({
+    //   to: email,
+    //   subject: `환영합니다, ${user.name}님!`,
+    //   template: 'welcome',
+    //   data: { name: user.name },
+    // });
+
+    this.logger.info(`[SampleTask] 환영 이메일 발송 완료: ${email}`);
+  }
+
+  /**
+   * 최종 실패 시 호출 (모든 재시도 소진)
+   *
+   * @param {object} data  - dispatch 시 전달된 데이터
+   * @param {Error}  error - 마지막 에러
+   */
+  async failed(data, error) {
+    this.logger.error(`[SampleTask] 최종 실패: userId=${data.userId}, error=${error.message}`);
+
+    // 실패 기록 DB 저장
+    // await this.db.FailedTask.create({
+    //   task_name: 'SampleQueuedTask',
+    //   data: JSON.stringify(data),
+    //   error: error.message,
+    // });
+  }
+}

package/templates/common/shared/jobs/SampleScheduledJob.js

@@ -0,0 +1,75 @@
+import { Job } from '@fuzionx/framework';
+
+/**
+ * SampleScheduledJob — 정기 실행 작업 (cron 스케줄) 샘플
+ *
+ * Job을 상속하여 정기 실행 작업을 구현합니다.
+ * 메인 스레드에서 실행되므로 this.db, this.service() 등 접근 가능합니다.
+ *
+ * ## 간편 스케줄 표현식
+ *   - 'every:5s'         → 5초마다 (테스트용)
+ *   - 'every:5m'         → 5분마다
+ *   - 'every:1h'         → 1시간마다
+ *   - 'daily:02:00'      → 매일 새벽 2시
+ *   - 'weekly:mon:09:00' → 매주 월요일 오전 9시
+ *
+ * ## 사용법
+ * 1. shared/jobs/ 에 파일 생성 (AutoLoader 자동 스캔)
+ * 2. handle()에 실행할 로직 구현
+ * 3. CPU-intensive 작업은 this.worker로 위임 (아래 예시 참고)
+ *
+ * ## Worker 위임 방식 (CPU-intensive 작업)
+ *
+ * ### 방법 1: 스크립트 파일 (shared/workers/ 폴더)
+ *   const result = await this.worker.run('csv-parser', { path: '/tmp/data.csv' });
+ *   await this.db.Report.create(result);
+ *
+ * ### 방법 2: 인라인 함수 (직렬화 가능한 순수 함수)
+ *   const sum = await this.worker.exec((data) => {
+ *     let total = 0;
+ *     for (const item of data.items) total += item.amount;
+ *     return total;
+ *   }, { items });
+ */
+export default class SampleScheduledJob extends Job {
+  /** 스케줄: 5초마다 실행 (테스트용, 운영 시 'daily:03:00' 등으로 변경) */
+  static schedule = 'daily:03:00';
+
+  /** 타임아웃: 60초 */
+  static timeout = 60000;
+
+  /** false로 설정하면 스케줄 비활성화 */
+  static enabled = false;
+
+  /**
+   * Job 실행 — 메인 스레드 (DB/서비스 접근 가능)
+   *
+   * CPU-intensive 작업이 필요하면 this.worker.run() 또는
+   * this.worker.exec()으로 별도 스레드에 위임합니다.
+   */
+  async handle() {
+    this.logger.info('[SampleJob] 정기 작업 시작');
+
+    // ── DB 작업 (메인 스레드에서 직접) ──
+    // const expiredSessions = await this.db.Session.where({ expired: true });
+    // this.logger.info(`[SampleJob] 만료 세션 ${expiredSessions.length}건 발견`);
+    // await this.db.Session.deleteMany(expiredSessions.map(s => s.id));
+
+    // ── CPU 작업 (Worker에 위임 → 결과로 DB 업데이트) ──
+    // const stats = await this.worker.exec((data) => {
+    //   // 이 함수는 별도 스레드에서 실행됨
+    //   return { processed: data.count * 2 };
+    // }, { count: 100 });
+    // await this.db.Stats.create(stats);
+
+    this.logger.info('[SampleJob] 정기 작업 완료');
+  }
+
+  /**
+   * 실패 시 호출
+   * @param {Error} error
+   */
+  async onError(error) {
+    this.logger.error('[SampleJob] 실패:', error.message);
+  }
+}

package/templates/common/shared/workers/video-worker.js

@@ -0,0 +1,69 @@
+/**
+ * video-worker.js — 비디오 처리 워커 (shared/workers/)
+ *
+ * WorkerPool.run('video-worker', data) 으로 실행됩니다.
+ * Bridge의 동기 N-API 호출을 별도 스레드에서 실행하여
+ * 메인 이벤트 루프 블로킹을 방지.
+ *
+ * workerData: { postId, attachmentId, storagePath, basePath, bridgeModulePath }
+ * 결과: { postId, attachmentId, thumbPaths, spritePath }
+ */
+import { workerData, parentPort, isMainThread } from 'node:worker_threads';
+
+// 메인 스레드에서 import 되면 아무것도 하지 않음 (앱 auto-load 방지)
+if (isMainThread) process.exitCode = 0;
+
+if (!isMainThread) {
+  const { promises: fs } = await import('node:fs');
+  const path = await import('node:path');
+  const { createRequire } = await import('node:module');
+
+  const { postId, attachmentId, storagePath, basePath, bridgeModulePath } = workerData;
+
+  try {
+    // Bridge .node 바이너리 로드
+    const require = createRequire(import.meta.url);
+    const bridge = require(bridgeModulePath);
+
+    const fullPath = path.join(basePath, storagePath);
+    const thumbDir = path.join(basePath, `uploads/thumbs/video_${attachmentId}`);
+    await fs.mkdir(thumbDir, { recursive: true });
+
+    const THUMB_COUNT = 25;
+    const SPRITE_COLS = 5;
+    let duration = 60;
+
+    // 1. 영상 길이
+    try {
+      const info = bridge.mediaVideoInfo(fullPath);
+      if (info?.duration) duration = info.duration;
+    } catch (e) {
+      // videoInfo 실패 시 기본 60s 사용
+    }
+
+    // 2. 프레임 추출
+    const interval = Math.max(1, Math.floor(duration / (THUMB_COUNT + 1)));
+    const generatedPaths = bridge.mediaVideoThumbnails(fullPath, thumbDir, interval, 640, 'jpeg') || [];
+    const filesToRegister = generatedPaths.slice(0, THUMB_COUNT);
+
+    // 3. 스프라이트 시트
+    let spritePath = null;
+    if (filesToRegister.length > 0) {
+      try {
+        spritePath = path.join(thumbDir, 'sprite.jpeg');
+        bridge.mediaVideoPreviewSheet(filesToRegister, spritePath, SPRITE_COLS, 160, 0);
+      } catch (e) {
+        spritePath = null;
+      }
+    }
+
+    // WorkerPool.run()이 resolve할 최종 결과
+    parentPort.postMessage({
+      postId, attachmentId,
+      thumbPaths: filesToRegister,
+      spritePath,
+    });
+  } catch (e) {
+    throw e; // WorkerPool이 error 이벤트로 reject
+  }
+}

package/templates/spa/meta.json

@@ -4,7 +4,7 @@
   "description": "Vue.js 3 SPA + Tera SSR 하이브리드. WASM 암호화 통신.",
   "features": ["auth", "board", "i18n", "asp", "wasm"],
   "dependencies": {
-    "@fuzionx/client": "^0.1.34"
+    "@fuzionx/client": "^0.1.37"
   },
   "devDependencies": {},
   "spaDevDependencies": {