mega-framework 0.1.6 → 0.1.8

package/sample/crud/apps/main/migrations/20260606000002-create-boards.js

@@ -0,0 +1,165 @@
+// @ts-check
+/**
+ * 마이그레이션 create-boards (20260606000002). up = 게시판 관련 테이블 생성, down = 제거(ADR-149).
+ * `mega migrate`(up)·`mega migrate:down`·`mega migrate:status` 로 실행. 적용 이력은 대상 DB 의
+ * `mega_migrations` 테이블이 추적하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ *
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+
+  // ltree 확장 활성화 (계층형 게시물 sort_path 용)
+  await db.query(`CREATE EXTENSION IF NOT EXISTS ltree`)
+
+  // 게시판 설정 테이블
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS board_configs (
+      id              SERIAL PRIMARY KEY,
+      uuid            UUID NOT NULL DEFAULT gen_random_uuid(),
+      code            TEXT NOT NULL UNIQUE,
+      type            TEXT NOT NULL,
+      use_comment     BOOLEAN NOT NULL DEFAULT true,
+      use_file        BOOLEAN NOT NULL DEFAULT true,      
+      name            TEXT NOT NULL,
+      sort_order      INTEGER NOT NULL DEFAULT 0,
+      is_enabled      BOOLEAN NOT NULL DEFAULT true,
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    COMMENT ON TABLE board_configs IS '게시판 설정 테이블';
+    COMMENT ON COLUMN board_configs.uuid IS '고유값';
+    COMMENT ON COLUMN board_configs.code IS '게시판 코드';
+    COMMENT ON COLUMN board_configs.name IS '게시판 명칭';
+    COMMENT ON COLUMN board_configs.sort_order IS '정렬 순서';
+    COMMENT ON COLUMN board_configs.is_enabled IS '사용 여부';
+    COMMENT ON COLUMN board_configs.created_at IS '생성 시간';
+    CREATE UNIQUE INDEX idx_board_configs_uuid ON board_configs (uuid);
+  `)
+
+  // 게시물 테이블
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS boards (
+      id               BIGSERIAL PRIMARY KEY,
+      uuid             UUID NOT NULL DEFAULT gen_random_uuid(),
+      config_code      TEXT NOT NULL REFERENCES board_configs(code) ON DELETE CASCADE,
+      user_id          BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      parent_id        BIGINT REFERENCES boards(id) ON DELETE CASCADE,
+      depth            INTEGER NOT NULL DEFAULT 0,
+      sort_path        ltree NOT NULL DEFAULT '',
+      title            TEXT NOT NULL,
+      content          TEXT,
+      view_count       INTEGER NOT NULL DEFAULT 0,
+      reply_count      INTEGER NOT NULL DEFAULT 0,
+      like_count       INTEGER NOT NULL DEFAULT 0,
+      dislike_count    INTEGER NOT NULL DEFAULT 0,
+      is_pinned        BOOLEAN NOT NULL DEFAULT false,
+      is_recommended   BOOLEAN NOT NULL DEFAULT false,
+      is_deleted       BOOLEAN NOT NULL DEFAULT false,
+      deleted_at       TIMESTAMPTZ,
+      created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at       TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    COMMENT ON TABLE boards IS '게시물 테이블';
+    COMMENT ON COLUMN boards.uuid IS '고유값';
+    COMMENT ON COLUMN boards.user_id IS '작성자 ID';
+    COMMENT ON COLUMN boards.config_code IS '게시판 코드';
+    COMMENT ON COLUMN boards.parent_id IS '부모 게시물 ID (답글 원글)';
+    COMMENT ON COLUMN boards.depth IS '계층 깊이 (0=원글, 1=답글, 2=답답글...)';
+    COMMENT ON COLUMN boards.sort_path IS '계층 정렬 경로 (ltree)';
+    COMMENT ON COLUMN boards.title IS '제목';
+    COMMENT ON COLUMN boards.content IS '내용';
+    COMMENT ON COLUMN boards.view_count IS '조회수';
+    COMMENT ON COLUMN boards.reply_count IS '답변 수';
+    COMMENT ON COLUMN boards.like_count IS '좋아요 수';
+    COMMENT ON COLUMN boards.dislike_count IS '싫어요 수';
+    COMMENT ON COLUMN boards.is_pinned IS '고정 여부';
+    COMMENT ON COLUMN boards.is_recommended IS '추천 여부';
+    COMMENT ON COLUMN boards.is_deleted IS '삭제 여부';
+    COMMENT ON COLUMN boards.deleted_at IS '삭제 시간';
+    COMMENT ON COLUMN boards.created_at IS '생성 시간';
+    COMMENT ON COLUMN boards.updated_at IS '수정 시간';
+    CREATE UNIQUE INDEX idx_boards_uuid ON boards (uuid);
+    CREATE INDEX idx_boards_config_code ON boards (config_code);
+    CREATE INDEX idx_boards_user_id ON boards (user_id);
+    CREATE INDEX idx_boards_parent_id ON boards (parent_id);
+    CREATE INDEX idx_boards_sort_path ON boards USING GIST (sort_path);
+    CREATE INDEX idx_boards_created_at ON boards (created_at DESC) WHERE is_deleted = false;
+  `)
+
+  // 게시물 댓글 테이블
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS board_comments (
+      id            BIGSERIAL PRIMARY KEY,
+      uuid          UUID NOT NULL DEFAULT gen_random_uuid(),
+      user_id       BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      board_id      BIGINT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
+      parent_id     BIGINT REFERENCES board_comments(id) ON DELETE CASCADE,
+      content       TEXT,
+      like_count    INTEGER NOT NULL DEFAULT 0,
+      dislike_count INTEGER NOT NULL DEFAULT 0,
+      is_deleted    BOOLEAN NOT NULL DEFAULT false,
+      deleted_at    TIMESTAMPTZ,
+      created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    COMMENT ON TABLE board_comments IS '게시물 댓글 테이블';
+    COMMENT ON COLUMN board_comments.uuid IS '고유값';
+    COMMENT ON COLUMN board_comments.user_id IS '작성자 ID';
+    COMMENT ON COLUMN board_comments.board_id IS '게시판 ID';
+    COMMENT ON COLUMN board_comments.parent_id IS '부모 댓글 ID (대댓글용)';
+    COMMENT ON COLUMN board_comments.content IS '내용';
+    COMMENT ON COLUMN board_comments.like_count IS '좋아요 수';
+    COMMENT ON COLUMN board_comments.dislike_count IS '싫어요 수';
+    COMMENT ON COLUMN board_comments.is_deleted IS '삭제 여부';
+    COMMENT ON COLUMN board_comments.deleted_at IS '삭제 시간';
+    COMMENT ON COLUMN board_comments.created_at IS '생성 시간';
+    COMMENT ON COLUMN board_comments.updated_at IS '수정 시간';
+    CREATE UNIQUE INDEX idx_board_comments_uuid ON board_comments (uuid);
+    CREATE INDEX idx_board_comments_user_id ON board_comments (user_id);
+    CREATE INDEX idx_board_comments_board_id ON board_comments (board_id);
+    CREATE INDEX idx_board_comments_parent_id ON board_comments (parent_id);
+  `)
+
+  // 게시글 첨부 파일 테이블
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS board_files (
+      id            SERIAL PRIMARY KEY,
+      uuid          UUID NOT NULL DEFAULT gen_random_uuid(),
+      user_id       BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      board_id      BIGINT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
+      original_name TEXT NOT NULL,
+      stored_name   TEXT NOT NULL,
+      file_type     TEXT NOT NULL DEFAULT 'unknown',
+      file_size     INTEGER NOT NULL,
+      download_count INTEGER NOT NULL DEFAULT 0,
+      created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+    COMMENT ON TABLE board_files IS '게시글 첨부 파일 테이블';
+    COMMENT ON COLUMN board_files.uuid IS '고유값';
+    COMMENT ON COLUMN board_files.user_id IS '작성자 ID';
+    COMMENT ON COLUMN board_files.board_id IS '게시판 ID';
+    COMMENT ON COLUMN board_files.original_name IS '원본파일명';
+    COMMENT ON COLUMN board_files.stored_name IS '저장명';
+    COMMENT ON COLUMN board_files.file_type IS '파일 유형';
+    COMMENT ON COLUMN board_files.file_size IS '파일 크기';
+    COMMENT ON COLUMN board_files.download_count IS '다운로드 수';
+    COMMENT ON COLUMN board_files.created_at IS '생성 시간';
+    COMMENT ON COLUMN board_files.updated_at IS '수정 시간';
+    CREATE UNIQUE INDEX idx_board_files_uuid ON board_files (uuid);
+    CREATE INDEX idx_board_files_user_id ON board_files (user_id);
+    CREATE INDEX idx_board_files_board_id ON board_files (board_id);
+  `)
+}
+
+/**
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+  await db.query('DROP TABLE IF EXISTS board_files')
+  await db.query('DROP TABLE IF EXISTS board_comments')
+  await db.query('DROP TABLE IF EXISTS boards')
+  await db.query('DROP TABLE IF EXISTS board_configs')
+  await db.query('DROP EXTENSION IF EXISTS ltree')
+}

package/sample/crud/apps/main/migrations/20260606000003-create-logs.js

@@ -0,0 +1,107 @@
+// @ts-check
+/**
+ * 마이그레이션 create-logs (20260606000003). up = 로그 관련 파티션 테이블 및 초기 파티션 생성, down = 제거(ADR-149).
+ * `mega migrate`(up)·`mega migrate:down`·`mega migrate:status` 로 실행. 적용 이력은 대상 DB 의
+ * `mega_migrations` 테이블이 추적하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ *
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+
+    // 활동 로그 파티션 테이블 생성 (created_at 컬럼을 기준으로 범위 파티셔닝 적용)
+    await db.query(`
+        CREATE TABLE IF NOT EXISTS action_logs (
+            id            BIGSERIAL,
+            uuid          UUID NOT NULL DEFAULT gen_random_uuid(),
+            user_id       BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+            action_type   TEXT NOT NULL,
+            action_target TEXT NOT NULL,
+            action_target_id TEXT,
+            message       TEXT,
+            created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (id, created_at) -- 파티션 제약 조건에 따라 파티션 키가 PK에 포함되어야 함
+        ) PARTITION BY RANGE (created_at);
+        COMMENT ON TABLE action_logs IS '활동 로그 파티션 테이블';
+        COMMENT ON COLUMN action_logs.uuid IS '고유값';
+        COMMENT ON COLUMN action_logs.action_type IS '활동 유형';
+        COMMENT ON COLUMN action_logs.action_target IS '활동 대상';
+        COMMENT ON COLUMN action_logs.action_target_id IS '활동 대상 ID';
+        COMMENT ON COLUMN action_logs.message IS '메시지';
+        COMMENT ON COLUMN action_logs.created_at IS '생성 시간';
+        CREATE UNIQUE INDEX idx_action_logs_uuid ON action_logs (uuid, created_at); -- 고유 인덱스에도 파티션 키 필수 포함
+        CREATE INDEX idx_action_logs_user_id ON action_logs (user_id);
+        CREATE INDEX idx_action_logs_action_type ON action_logs (action_type);
+    `)
+
+    // 지갑 로그 파티션 테이블 생성 (created_at 컬럼을 기준으로 범위 파티셔닝 적용)
+    await db.query(`
+        CREATE TABLE IF NOT EXISTS wallet_logs (
+            id              BIGSERIAL,
+            uuid            UUID NOT NULL DEFAULT gen_random_uuid(),
+            user_id         BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+            wallet_id       BIGINT NOT NULL REFERENCES wallets(id) ON DELETE CASCADE,
+            action_type     TEXT NOT NULL,
+            action_target   TEXT NOT NULL,
+            action_target_id TEXT,
+            message       TEXT,
+            created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (id, created_at) -- 파티션 제약 조건에 따라 파티션 키가 PK에 포함되어야 함
+        ) PARTITION BY RANGE (created_at);
+        COMMENT ON TABLE wallet_logs IS '지갑 로그 파티션 테이블';
+        COMMENT ON COLUMN wallet_logs.uuid IS '고유값';
+        COMMENT ON COLUMN wallet_logs.action_type IS '활동 유형';
+        COMMENT ON COLUMN wallet_logs.action_target IS '활동 대상';
+        COMMENT ON COLUMN wallet_logs.action_target_id IS '활동 대상 ID';
+        COMMENT ON COLUMN wallet_logs.message IS '메시지';
+        COMMENT ON COLUMN wallet_logs.created_at IS '생성 시간';
+        CREATE UNIQUE INDEX idx_wallet_logs_uuid ON wallet_logs (uuid, created_at); -- 고유 인덱스에도 파티션 키 필수 포함
+        CREATE INDEX idx_wallet_logs_user_id ON wallet_logs (user_id);
+        CREATE INDEX idx_wallet_logs_action_type ON wallet_logs (action_type);
+    `)
+
+    // 상세 로그 파티션 테이블 생성 (created_at 컬럼을 기준으로 범위 파티셔닝 적용)
+    await db.query(`
+        CREATE TABLE IF NOT EXISTS detail_logs (
+            id            BIGSERIAL,
+            uuid          UUID NOT NULL DEFAULT gen_random_uuid(),
+            log_id        BIGINT NOT NULL,
+            log_json      JSONB NOT NULL,
+            created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (id, created_at) -- 파티션 제약 조건에 따라 파티션 키가 PK에 포함되어야 함
+        ) PARTITION BY RANGE (created_at);
+        COMMENT ON TABLE detail_logs IS '상세 로그 파티션 테이블';
+        COMMENT ON COLUMN detail_logs.uuid IS '고유값';
+        COMMENT ON COLUMN detail_logs.log_id IS '로그 ID';
+        COMMENT ON COLUMN detail_logs.log_json IS '상세 로그 JSON';
+        COMMENT ON COLUMN detail_logs.created_at IS '생성 시간';
+        CREATE UNIQUE INDEX idx_detail_logs_uuid ON detail_logs (uuid, created_at); -- 고유 인덱스에도 파티션 키 필수 포함
+        CREATE UNIQUE INDEX idx_detail_logs_log_id ON detail_logs (log_id, created_at); -- 고유 인덱스에도 파티션 키 필수 포함
+    `)
+
+    // 초기 파티션 생성 (2026년 6월 및 7월)
+    // 데이터 유실 및 쿼리 에러를 미연에 방지하기 위해 마이그레이션 시점에 현재 월과 다음 월의 파티션을 생성해 둡니다.
+    await db.query(`
+        CREATE TABLE IF NOT EXISTS action_logs_y2026m06 PARTITION OF action_logs FOR VALUES FROM ('2026-06-01 00:00:00+09') TO ('2026-07-01 00:00:00+09');
+        CREATE TABLE IF NOT EXISTS action_logs_y2026m07 PARTITION OF action_logs FOR VALUES FROM ('2026-07-01 00:00:00+09') TO ('2026-08-01 00:00:00+09');
+
+        CREATE TABLE IF NOT EXISTS wallet_logs_y2026m06 PARTITION OF wallet_logs FOR VALUES FROM ('2026-06-01 00:00:00+09') TO ('2026-07-01 00:00:00+09');
+        CREATE TABLE IF NOT EXISTS wallet_logs_y2026m07 PARTITION OF wallet_logs FOR VALUES FROM ('2026-07-01 00:00:00+09') TO ('2026-08-01 00:00:00+09');
+
+        CREATE TABLE IF NOT EXISTS detail_logs_y2026m06 PARTITION OF detail_logs FOR VALUES FROM ('2026-06-01 00:00:00+09') TO ('2026-07-01 00:00:00+09');
+        CREATE TABLE IF NOT EXISTS detail_logs_y2026m07 PARTITION OF detail_logs FOR VALUES FROM ('2026-07-01 00:00:00+09') TO ('2026-08-01 00:00:00+09');
+    `)
+}
+
+/**
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+    // 부모 테이블 삭제 시 하위 파티션 테이블(y2026m06 등)은 자동으로 함께 드롭됩니다.
+    await db.query(`
+        DROP TABLE IF EXISTS detail_logs;
+        DROP TABLE IF EXISTS action_logs;
+        DROP TABLE IF EXISTS wallet_logs;
+    `)
+}

package/sample/crud/apps/main/models/log-partition-model.js

@@ -0,0 +1,105 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * 로그 파티션 테이블에 대한 직접적인 DDL 쿼리를 실행하는 모델 클래스 (ADR-009/138).
+ * @extends {MegaModel}
+ */
+export class LogPartitionModel extends MegaModel {
+  static adapter = 'primary'
+  // MegaModel 요구사항: 기본 관리 대상이 되는 대표 테이블 지정
+  static table = 'action_logs'
+
+  /**
+   * 대상 부모 테이블의 하위 파티션 목록을 데이터베이스에서 조회합니다.
+   * @param {string} parentTable - 부모 테이블 이름 ('action_logs', 'wallet_logs', 'detail_logs')
+   * @returns {Promise<string[]>} 하위 파티션 테이블 명칭 배열
+   */
+  static async getPartitions(parentTable) {
+    // 부모 테이블 이름 화이트리스트 검사 (SQL 인젝션 방지)
+    const allowed = ['action_logs', 'wallet_logs', 'detail_logs']
+    if (!allowed.includes(parentTable)) {
+      throw new Error(`허용되지 않은 부모 테이블명입니다: ${parentTable}`)
+    }
+
+    // pg_inherits 시스템 테이블을 조회하여 파티션 목록 조회
+    const sql = `
+      SELECT c.relname AS partition_name
+      FROM pg_inherits i
+      JOIN pg_class c ON c.oid = i.inhrelid
+      JOIN pg_class p ON p.oid = i.inhparent
+      WHERE p.relname = $1
+      ORDER BY c.relname ASC
+    `
+    const { rows } = await super.query(sql, [parentTable])
+    
+    // 파티션 테이블명만 추출하여 리턴
+    return rows.map((/** @type {any} */ r) => r.partition_name)
+  }
+
+  /**
+   * 지정한 연월 범위의 파티션 테이블을 생성합니다.
+   * @param {string} parentTable - 부모 테이블 이름
+   * @param {number} year - 연도 (예: 2026)
+   * @param {number} month - 월 (예: 6)
+   * @returns {Promise<void>}
+   */
+  static async createPartition(parentTable, year, month) {
+    const allowed = ['action_logs', 'wallet_logs', 'detail_logs']
+    if (!allowed.includes(parentTable)) {
+      throw new Error(`허용되지 않은 부모 테이블명입니다: ${parentTable}`)
+    }
+
+    // 월 자릿수를 두 자리 문자열로 포맷팅 (예: 6 -> '06')
+    const monthStr = month.toString().padStart(2, '0')
+    const partitionName = `${parentTable}_y${year}m${monthStr}`
+
+    // 시작일(해당 월 1일) 및 종료일(다음 달 1일) 계산
+    const startDate = `${year}-${monthStr}-01 00:00:00+09`
+    
+    // 다음 달 계산 로직 (12월인 경우 다음 해 1월로 이월)
+    const nextYear = month === 12 ? year + 1 : year
+    const nextMonth = month === 12 ? 1 : month + 1
+    const nextMonthStr = nextMonth.toString().padStart(2, '0')
+    const endDate = `${nextYear}-${nextMonthStr}-01 00:00:00+09`
+
+    // 파티션 테이블 생성 쿼리 (안전한 명칭 포맷을 사전에 정규식 검증)
+    if (!/^[a-z0-9_]+$/.test(partitionName)) {
+      throw new Error(`부적절한 파티션 테이블 이름입니다: ${partitionName}`)
+    }
+
+    // 파티션 생성 쿼리 실행
+    await super.query(`
+      CREATE TABLE IF NOT EXISTS ${partitionName} 
+      PARTITION OF ${parentTable} 
+      FOR VALUES FROM ('${startDate}') TO ('${endDate}')
+    `)
+  }
+
+  /**
+   * 지정한 파티션 테이블을 부모 테이블에서 분리(Detach)하고 물리적으로 제거(Drop)합니다.
+   * @param {string} parentTable - 부모 테이블 이름
+   * @param {string} partitionName - 드롭할 파티션 테이블 이름
+   * @returns {Promise<void>}
+   */
+  static async dropPartition(parentTable, partitionName) {
+    const allowed = ['action_logs', 'wallet_logs', 'detail_logs']
+    if (!allowed.includes(parentTable)) {
+      throw new Error(`허용되지 않은 부모 테이블명입니다: ${parentTable}`)
+    }
+
+    // 파티션 명칭 검증 (형식: 테이블명_yYYYYmMM)
+    if (!partitionName.startsWith(`${parentTable}_y`)) {
+      throw new Error(`부모 테이블에 일치하지 않는 파티션입니다: ${partitionName}`)
+    }
+    if (!/^[a-z0-9_]+$/.test(partitionName)) {
+      throw new Error(`부적절한 파티션 테이블 이름입니다: ${partitionName}`)
+    }
+
+    // 1단계: 부모 테이블로부터 파티션 분리 (락 오버헤드를 최소화하기 위해 선(先)분리 후(後)삭제 수행)
+    await super.query(`ALTER TABLE ${parentTable} DETACH PARTITION ${partitionName}`)
+
+    // 2단계: 분리된 독립 테이블 제거
+    await super.query(`DROP TABLE IF EXISTS ${partitionName}`)
+  }
+}

package/sample/crud/apps/main/models/note-model.js

@@ -0,0 +1,79 @@
+// @ts-check
+import { randomUUID } from 'node:crypto'
+import { MegaModel } from 'mega-framework'
+
+/**
+ * NoteModel — `notes` 컬렉션(globalKey 'mongo' 의 MongoDB, ADR-108). `static schema`(ADR-209 $jsonSchema)
+ * 선언으로 공통 CRUD(ADR-212 P3 — mongo 경로)를 켜고, 도메인 메서드 본문을 그 CRUD 로 작성한다. mongo CRUD 는
+ * SQL 과 동일 표면이되 내부적으로 `this.db.collection().find/insertOne/...` 도큐먼트 연산으로 디스패치된다.
+ *
+ * 식별자는 라우트/폼에서 다루기 쉬운 자체 `id`(UUID v4)를 쓰고, 조회 응답에서는 mongo 내부 `_id` 를
+ * projection(select)으로 제외해 도메인 형태만 노출한다. (공통 CRUD 의 PK 는 `_id` 지만, 도메인 lookup 은
+ * `findOne({ id })` 로 UUID 를 쓴다 — NoteModel 의 기존 패턴 보존.)
+ *
+ * @typedef {{ id: string, title: string, body: string, created_at: string }} NoteDoc
+ */
+export class NoteModel extends MegaModel {
+  static adapter = 'mongo'
+  static table = 'notes'
+
+  /**
+   * 컬렉션 스키마(ADR-209) — 공통 CRUD 식별자 화이트리스트 + (마이그레이션 생성 시) $jsonSchema validator.
+   * `_id` 는 mongo 네이티브 PK(ObjectId), `id` 는 도메인 식별자(UUID, unique). created_at 은 ISO 문자열로 저장.
+   */
+  static schema = /** @param {any} t */ (t) => ({
+    _id: t.objectId().primary(),
+    id: t.uuid().notNull().unique(),
+    title: t.varchar(120).notNull(),
+    body: t.text(),
+    created_at: t.timestamptz().notNull(),
+  })
+
+  /** 조회 공개 필드 — 내부 `_id` 를 빼고 도메인 필드만(공통 CRUD select projection). @type {string[]} */
+  static PUBLIC_FIELDS = ['id', 'title', 'body', 'created_at']
+
+  /** 최신순 전체 목록(ADR-212 findMany). @returns {Promise<NoteDoc[]>} */
+  static async list() {
+    return this.findMany({}, { select: this.PUBLIC_FIELDS, orderBy: [{ column: 'created_at', dir: 'desc' }] })
+  }
+
+  /** 단건 조회(도메인 id=UUID, 없으면 null). @param {string} id @returns {Promise<NoteDoc | null>} */
+  static async findById(id) {
+    return this.findOne({ id }, { select: this.PUBLIC_FIELDS })
+  }
+
+  /** 생성 — UUID·생성시각을 부여해 삽입(ADR-212 insertOne). 반환은 삽입한 도메인 도큐먼트. @param {{ title: string, body: string }} input @returns {Promise<NoteDoc>} */
+  static async create({ title, body }) {
+    /** @type {NoteDoc} */
+    const doc = { id: randomUUID(), title, body, created_at: new Date().toISOString() }
+    await this.insertOne({ ...doc }) // 새 _id 는 mongo 가 부여(반환값은 도메인 doc 사용)
+    return doc
+  }
+
+  /**
+   * 수정 — 주어진 필드만 $set(undefined 제외). 대상 없으면 null. id 는 unique 라 0|1 매칭(updateOne).
+   * @param {string} id @param {{ title?: string, body?: string }} patch @returns {Promise<NoteDoc | null>}
+   */
+  static async update(id, { title, body }) {
+    /** @type {Record<string, string>} */
+    const set = {}
+    if (title !== undefined) set.title = title
+    if (body !== undefined) set.body = body
+    if (Object.keys(set).length === 0) return this.findById(id) // 변경 없음
+    const n = await this.updateOne({ id }, set)
+    return n > 0 ? this.findById(id) : null
+  }
+
+  /** 삭제 — id(unique) 기준(deleteOne). @param {string} id @returns {Promise<boolean>} */
+  static async remove(id) {
+    return (await this.deleteOne({ id })) > 0
+  }
+
+  /**
+   * 전체 도큐먼트 수(캐시 데모용). 도메인 메서드명 `count` 가 CRUD `count` 와 충돌하므로 `super.count()`
+   * (부모=ADR-212 CRUD)로 호출한다(자기 재귀 회피). @returns {Promise<number>}
+   */
+  static async count() {
+    return super.count()
+  }
+}

package/sample/crud/apps/main/models/user-level-model.js

@@ -0,0 +1,24 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * UserLevelModel — `user_levels`(회원 등급 lookup). type_code 는 user_types(code) 를 FK 참조(비-PK unique
+ * 컬럼 참조 — ADR-204 validator 가 허용). idx_user_levels_type_code 인덱스 동반.
+ *
+ * @typedef {{ id: number, code: string, type_code: string, sort_order: number, name: string, created_at: string }} UserLevelRow
+ */
+export class UserLevelModel extends MegaModel {
+  static adapter = 'primary'
+  static table = 'user_levels'
+
+  static schema = /** @param {any} t */ (t) => ({
+    id: t.serial().primary(),
+    code: t.text().notNull().unique().comment('회원 등급 코드'),
+    type_code: t.text().notNull().references('UserTypeModel', 'code', { onDelete: 'cascade' }).comment('회원 유형 코드'),
+    sort_order: t.integer().notNull().default(0).comment('정렬 순서'),
+    name: t.text().notNull().comment('회원 등급명'),
+    created_at: t.timestamptz().notNull().default({ raw: 'now()' }).comment('생성 시간'),
+  })
+
+  static indexes = /** @param {any} t */ (t) => [t.index(['type_code'], { name: 'idx_user_levels_type_code' })]
+}

package/sample/crud/apps/main/models/user-model.js

@@ -0,0 +1,146 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * UserModel — `users` 테이블(globalKey 'primary' 의 postgres). `static schema`(ADR-204) 선언으로
+ * 공통 CRUD(ADR-212)를 켜고 도메인 메서드 본문을 그 CRUD 로 작성한다. 복잡 쿼리(now() 등)는 계측
+ * raw `this.query`(ADR-138)와 공존. 모델은 서비스만 import 한다(라우트·컨트롤러 직접 import 는
+ * `mega/no-direct-model-import` 가 차단, ADR-022).
+ *
+ * @typedef {{ id: number|string, username: string, name: string, nickname: string, email: string|null, phone_number: string|null, type_code: string, level_code: string, last_login_at: string|null, created_at: string }} UserRow
+ * @typedef {{ id: number|string, username: string, name: string, password_hash: string | null }} UserAuthRow
+ */
+export class UserModel extends MegaModel {
+  static adapter = 'primary'
+  static table = 'users'
+
+  /**
+   * 회원 테이블 스키마(ADR-204) — 손 DDL(20260606000001-create-users)의 `users` 와 동일 컬럼.
+   * 선언 시 마이그레이션 자동 생성 + 공통 CRUD(ADR-212)가 함께 켜진다. type_code/level_code 는
+   * 원본대로 FK 없는 NOT NULL TEXT(기본값만).
+   */
+  static schema = /** @param {any} t */ (t) => ({
+    id: t.bigSerial().primary(),
+    uuid: t.uuid().notNull().default({ raw: 'gen_random_uuid()' }).comment('고유값'),
+    username: t.text().notNull().unique().comment('로그인 아이디'),
+    password_hash: t.text().notNull().comment('비밀번호 해시'),
+    type_code: t.text().notNull().default('USER').comment('회원 유형'),
+    level_code: t.text().notNull().default('lv1').comment('회원 등급'),
+    name: t.text().notNull().comment('실명'),
+    nickname: t.text().notNull().unique().comment('별명'),
+    email: t.text().comment('이메일'),
+    phone_number: t.text().comment('전화번호'),
+    last_login_at: t.timestamptz().comment('마지막 로그인 시간'),
+    created_at: t.timestamptz().notNull().default({ raw: 'now()' }).comment('생성 시간'),
+  })
+
+  static indexes = /** @param {any} t */ (t) => [
+    t.index(['uuid'], { unique: true, name: 'idx_users_uuid' }),
+    t.index(['email'], { name: 'idx_users_email' }),
+    t.index(['type_code'], { name: 'idx_users_type_code' }),
+    t.index(['level_code'], { name: 'idx_users_level_code' }),
+  ]
+
+  /**
+   * 공개 컬럼 화이트리스트 — 조회 응답에 노출하는 컬럼(`password_hash`·`uuid` 제외). CRUD select 에 쓴다.
+   * @type {string[]}
+   */
+  static PUBLIC_COLUMNS = ['id', 'username', 'name', 'nickname', 'email', 'phone_number', 'type_code', 'level_code', 'last_login_at', 'created_at']
+
+  /** 목록 — 공개 컬럼만, id 오름차순(ADR-212 findMany). @returns {Promise<UserRow[]>} */
+  static async list() {
+    return this.findMany({}, { select: this.PUBLIC_COLUMNS, orderBy: 'id' })
+  }
+
+  /**
+   * 전체 사용자 수 — /demo/redis 캐시 데모가 캐싱한다. 도메인 메서드명 `count` 가 CRUD `count` 와
+   * 충돌하므로 `super.count()`(부모=ADR-212 CRUD)로 호출한다(자기 재귀 회피). @returns {Promise<number>}
+   */
+  static async count() {
+    return super.count()
+  }
+
+  /**
+   * id 단건(공개 컬럼). 이름 충돌 회피로 `super.findById`(CRUD)에 위임. @param {number|string} id
+   * @returns {Promise<UserRow | null>}
+   */
+  static async findById(id) {
+    return super.findById(Number(id), { select: this.PUBLIC_COLUMNS })
+  }
+
+  /**
+   * username 으로 단건(공개 컬럼). 로그인 폼·중복 확인용. @param {string} username @returns {Promise<UserRow | null>}
+   */
+  static async findByUsername(username) {
+    return this.findOne({ username }, { select: this.PUBLIC_COLUMNS })
+  }
+
+  /**
+   * 새 사용자 생성(관리자/회원가입 공용). 필수: username·passwordHash·name·nickname. 선택: email·
+   * phone_number·type_code·level_code(미지정 시 DB 기본값 USER/lv1). 반환은 공개 컬럼만(해시 미노출).
+   * @param {{ username: string, passwordHash: string, name: string, nickname: string, email?: string|null, phone_number?: string|null, type_code?: string, level_code?: string }} input
+   * @returns {Promise<UserRow>}
+   */
+  static async create(input) {
+    /** @type {Record<string, any>} */
+    const data = {
+      username: input.username,
+      password_hash: input.passwordHash,
+      name: input.name,
+      nickname: input.nickname,
+      email: input.email ?? null,
+      phone_number: input.phone_number ?? null,
+    }
+    if (input.type_code) data.type_code = input.type_code
+    if (input.level_code) data.level_code = input.level_code
+    const id = await this.insertOne(data) // 기본 returning=false → 새 id
+    return /** @type {Promise<UserRow>} */ (this.findById(id))
+  }
+
+  /**
+   * 회원가입(/register) — create 와 동일 본문(자동 로그인 흐름은 컨트롤러 책임). 메서드명 유지.
+   * @param {{ username: string, passwordHash: string, name: string, nickname: string, email?: string|null, phone_number?: string|null }} input
+   * @returns {Promise<UserRow>}
+   */
+  static async register(input) {
+    return this.create(input)
+  }
+
+  /**
+   * 부분 수정 — 허용 컬럼(name·nickname·email·phone_number·type_code·level_code)만. username·password 는
+   * 별도 흐름(여기서 안 바꿈). 변경 없으면 현재 행 반환. PK filter 라 0|1 매칭(updateOne, ADR-212 #3).
+   * @param {number|string} id @param {Record<string, any>} patch @returns {Promise<UserRow | null>}
+   */
+  static async update(id, patch) {
+    /** @type {Record<string, any>} */
+    const fields = {}
+    for (const k of ['name', 'nickname', 'email', 'phone_number', 'type_code', 'level_code']) {
+      if (patch?.[k] !== undefined) fields[k] = patch[k]
+    }
+    if (Object.keys(fields).length === 0) return this.findById(id) // 변경 없음 — 현재 행
+    const n = await this.updateOne({ id: Number(id) }, fields)
+    return n > 0 ? this.findById(id) : null
+  }
+
+  /** 삭제 — PK filter(deleteOne, 0|1). @param {number|string} id @returns {Promise<boolean>} 삭제 여부. */
+  static async remove(id) {
+    return (await this.deleteOne({ id: Number(id) })) > 0
+  }
+
+  /**
+   * 로그인 검증용 — username 으로 사용자를 찾아 password_hash 까지 돌려준다. 해시가 필요한 인증 경로에서만
+   * 쓴다(일반 조회 list/findById 는 해시 미선택 → 노출 없음). @param {string} username
+   * @returns {Promise<UserAuthRow | null>}
+   */
+  static async findByUsernameWithHash(username) {
+    return this.findOne({ username }, { select: ['id', 'username', 'name', 'password_hash'] })
+  }
+
+  /**
+   * 로그인 성공 시각 갱신. `now()` 는 SQL 함수라 raw 쿼리 유지(ADR-212 CRUD 는 값 바인딩만 — 오너 합의).
+   * @param {number|string} id @returns {Promise<void>}
+   */
+  static async touchLastLogin(id) {
+    await this.query('UPDATE users SET last_login_at = now() WHERE id = $1', [Number(id)])
+  }
+}

package/sample/crud/apps/main/models/user-type-model.js

@@ -0,0 +1,21 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * UserTypeModel — `user_types`(회원 유형 lookup). `static schema`(ADR-204) 로 마이그레이션 자동 생성 +
+ * 공통 CRUD(ADR-212) 를 함께 켠다. 기존 손 DDL(20260606000001-create-users)의 user_types 와 동일 형태.
+ *
+ * @typedef {{ id: number, code: string, sort_order: number, name: string, created_at: string }} UserTypeRow
+ */
+export class UserTypeModel extends MegaModel {
+  static adapter = 'primary'
+  static table = 'user_types'
+
+  static schema = /** @param {any} t */ (t) => ({
+    id: t.serial().primary(),
+    code: t.text().notNull().unique().comment('회원 유형 코드'),
+    sort_order: t.integer().notNull().default(0).comment('정렬 순서'),
+    name: t.text().notNull().comment('회원 유형명'),
+    created_at: t.timestamptz().notNull().default({ raw: 'now()' }).comment('생성 시간'),
+  })
+}