mega-framework 0.1.5 → 0.1.7

package/sample/crud/apps/main/migrations/20260606000001-create-users.js

@@ -1,27 +1,105 @@
 // @ts-check
 /**
- * 마이그레이션 create-users (20260606000001). up = users 테이블 생성, down = 제거(ADR-149).
- * `mega migrate`(up)·`mega migrate:down`·`mega migrate:status` 로 실행. 적용 이력은 대상 DB 의
- * `mega_migrations` 테이블이 추적하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ * 마이그레이션 create-users (20260612092543) — `mega migrate:generate` 자동 생성 (ADR-204).
+ * 기준 스냅샷: .mega/journal/history/20260612092543-create-users.json
+ * 적용 전 SQL 검토 필수 — 파괴적 변경(-- 경고)·캐스트(-- TODO) 주석이 있으면 직접 확정하세요.
+ * 적용은 `mega migrate`(락·checksum 은 러너 관리, ADR-149/190), 롤백은 `mega migrate:down`.
  *
  * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
  * @returns {Promise<void>}
  */
 export async function up(db) {
-  await db.query(`
-    CREATE TABLE IF NOT EXISTS users (
-      id         SERIAL PRIMARY KEY,
-      name       TEXT NOT NULL,
-      email      TEXT NOT NULL UNIQUE,
-      created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-    )
-  `)
+  await db.query(`CREATE TABLE user_levels (
+  id SERIAL PRIMARY KEY,
+  code TEXT NOT NULL,
+  type_code TEXT NOT NULL,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+)`)
+  await db.query(`COMMENT ON TABLE user_levels IS '회원 등급 테이블'`)
+  await db.query(`ALTER TABLE user_levels ADD CONSTRAINT uniq_user_levels_code UNIQUE (code)`)
+  await db.query(`COMMENT ON COLUMN user_levels.code IS '회원 등급 코드'`)
+  await db.query(`COMMENT ON COLUMN user_levels.type_code IS '회원 유형 코드'`)
+  await db.query(`COMMENT ON COLUMN user_levels.sort_order IS '정렬 순서'`)
+  await db.query(`COMMENT ON COLUMN user_levels.name IS '회원 등급명'`)
+  await db.query(`COMMENT ON COLUMN user_levels.created_at IS '생성 시간'`)
+  await db.query(`CREATE TABLE users (
+  id BIGSERIAL PRIMARY KEY,
+  uuid UUID NOT NULL DEFAULT gen_random_uuid(),
+  username TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  type_code TEXT NOT NULL DEFAULT 'USER',
+  level_code TEXT NOT NULL DEFAULT 'lv1',
+  name TEXT NOT NULL,
+  nickname TEXT NOT NULL,
+  email TEXT,
+  phone_number TEXT,
+  last_login_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+)`)
+  await db.query(`COMMENT ON TABLE users IS '회원 테이블'`)
+  await db.query(`COMMENT ON COLUMN users.uuid IS '고유값'`)
+  await db.query(`ALTER TABLE users ADD CONSTRAINT uniq_users_username UNIQUE (username)`)
+  await db.query(`COMMENT ON COLUMN users.username IS '로그인 아이디'`)
+  await db.query(`COMMENT ON COLUMN users.password_hash IS '비밀번호 해시'`)
+  await db.query(`COMMENT ON COLUMN users.type_code IS '회원 유형'`)
+  await db.query(`COMMENT ON COLUMN users.level_code IS '회원 등급'`)
+  await db.query(`COMMENT ON COLUMN users.name IS '실명'`)
+  await db.query(`ALTER TABLE users ADD CONSTRAINT uniq_users_nickname UNIQUE (nickname)`)
+  await db.query(`COMMENT ON COLUMN users.nickname IS '별명'`)
+  await db.query(`COMMENT ON COLUMN users.email IS '이메일'`)
+  await db.query(`COMMENT ON COLUMN users.phone_number IS '전화번호'`)
+  await db.query(`COMMENT ON COLUMN users.last_login_at IS '마지막 로그인 시간'`)
+  await db.query(`COMMENT ON COLUMN users.created_at IS '생성 시간'`)
+  await db.query(`CREATE TABLE user_types (
+  id SERIAL PRIMARY KEY,
+  code TEXT NOT NULL,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+)`)
+  await db.query(`COMMENT ON TABLE user_types IS '회원 유형 테이블'`)
+  await db.query(`ALTER TABLE user_types ADD CONSTRAINT uniq_user_types_code UNIQUE (code)`)
+  await db.query(`COMMENT ON COLUMN user_types.code IS '회원 유형 코드'`)
+  await db.query(`COMMENT ON COLUMN user_types.sort_order IS '정렬 순서'`)
+  await db.query(`COMMENT ON COLUMN user_types.name IS '회원 유형명'`)
+  await db.query(`COMMENT ON COLUMN user_types.created_at IS '생성 시간'`)
+  await db.query(`CREATE TABLE wallets (
+  id SERIAL PRIMARY KEY,
+  user_id BIGINT NOT NULL,
+  balance NUMERIC(20, 4) NOT NULL DEFAULT 0,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+)`)
+  await db.query(`COMMENT ON TABLE wallets IS '회원 지갑 테이블'`)
+  await db.query(`COMMENT ON COLUMN wallets.user_id IS '회원 ID'`)
+  await db.query(`COMMENT ON COLUMN wallets.balance IS '잔액'`)
+  await db.query(`COMMENT ON COLUMN wallets.created_at IS '생성 시간'`)
+  await db.query(`ALTER TABLE user_levels ADD CONSTRAINT fk_user_levels_type_code_user_types FOREIGN KEY (type_code) REFERENCES user_types (code) ON DELETE CASCADE`)
+  await db.query(`ALTER TABLE wallets ADD CONSTRAINT fk_wallets_user_id_users FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE`)
+  await db.query(`CREATE INDEX idx_user_levels_type_code ON user_levels (type_code)`)
+  await db.query(`CREATE UNIQUE INDEX idx_users_uuid ON users (uuid)`)
+  await db.query(`CREATE INDEX idx_users_email ON users (email)`)
+  await db.query(`CREATE INDEX idx_users_type_code ON users (type_code)`)
+  await db.query(`CREATE INDEX idx_users_level_code ON users (level_code)`)
+  await db.query(`CREATE INDEX idx_wallets_user_id ON wallets (user_id)`)
 }
 
 /**
- * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
  * @returns {Promise<void>}
  */
 export async function down(db) {
-  await db.query('DROP TABLE IF EXISTS users')
+  await db.query(`DROP INDEX IF EXISTS idx_wallets_user_id`)
+  await db.query(`DROP INDEX IF EXISTS idx_users_level_code`)
+  await db.query(`DROP INDEX IF EXISTS idx_users_type_code`)
+  await db.query(`DROP INDEX IF EXISTS idx_users_email`)
+  await db.query(`DROP INDEX IF EXISTS idx_users_uuid`)
+  await db.query(`DROP INDEX IF EXISTS idx_user_levels_type_code`)
+  await db.query(`ALTER TABLE wallets DROP CONSTRAINT fk_wallets_user_id_users`)
+  await db.query(`ALTER TABLE user_levels DROP CONSTRAINT fk_user_levels_type_code_user_types`)
+  await db.query(`DROP TABLE IF EXISTS wallets`)
+  await db.query(`DROP TABLE IF EXISTS user_types`)
+  await db.query(`DROP TABLE IF EXISTS users`)
+  await db.query(`DROP TABLE IF EXISTS user_levels`)
 }

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' })]
+}