mega-framework 0.1.5 → 0.1.7

package/types/models/model-crud.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 모델의 schema record(컬럼·PK·unique)를 1회 평가·메모이즈한다(ADR-204 `buildModelRecord` 재사용).
+ * `static schema` 없으면 `model.crud_requires_schema`.
+ * @param {any} Model @returns {ModelMeta}
+ */
+export function getModelMeta(Model: any): ModelMeta;
+/**
+ * Model 의 어댑터 driver 로 SQL dialect(DML facet)를 해석한다. mongo·DML facet 미구현 driver 는 throw.
+ * @param {any} Model @returns {{ dialect: any, driver: string }}
+ */
+export function getCrudDialect(Model: any): {
+    dialect: any;
+    driver: string;
+};
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export function findOne(Model: any, filter: Record<string, any>, opts?: {
+    select?: string[];
+}): Promise<any | null>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit?: number, offset?: number }} [opts] @returns {Promise<any[]>} */
+export function findMany(Model: any, filter: Record<string, any>, opts?: {
+    select?: string[];
+    orderBy?: any;
+    limit?: number;
+    offset?: number;
+}): Promise<any[]>;
+/** @param {any} Model @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export function findById(Model: any, id: any, opts?: {
+    select?: string[];
+}): Promise<any | null>;
+/** @param {any} Model @param {Record<string, any>} [filter] @returns {Promise<number>} */
+export function count(Model: any, filter?: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<boolean>} */
+export function exists(Model: any, filter: Record<string, any>): Promise<boolean>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit: number, offset?: number, withTotal?: boolean }} opts @returns {Promise<{ rows: any[], limit: number, offset: number, total?: number }>} */
+export function paginate(Model: any, filter: Record<string, any>, opts: {
+    select?: string[];
+    orderBy?: any;
+    limit: number;
+    offset?: number;
+    withTotal?: boolean;
+}): Promise<{
+    rows: any[];
+    limit: number;
+    offset: number;
+    total?: number;
+}>;
+/** @param {any} Model @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+export function insertOne(Model: any, data: Record<string, any>, opts?: {
+    returning?: boolean;
+}): Promise<any>;
+/** @param {any} Model @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+export function insertMany(Model: any, rows: Record<string, any>[], opts?: {
+    returning?: boolean;
+}): Promise<{
+    count: number;
+} | any[]>;
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+export function updateOne(Model: any, filter: Record<string, any>, patch: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export function updateMany(Model: any, filter: Record<string, any>, patch: Record<string, any>, opts?: {
+    all?: boolean;
+}): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<number>} */
+export function deleteOne(Model: any, filter: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export function deleteMany(Model: any, filter: Record<string, any>, opts?: {
+    all?: boolean;
+}): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} data @param {{ conflict: string[], update?: string[], returning?: boolean }} opts @returns {Promise<any>} */
+export function upsert(Model: any, data: Record<string, any>, opts: {
+    conflict: string[];
+    update?: string[];
+    returning?: boolean;
+}): Promise<any>;
+export type ModelMeta = {
+    record: any;
+    cols: Set<string>;
+    pk: string | null;
+    pkCols: string[];
+    uniques: Set<string>;
+    table: string;
+};

package/types/models/mongo-crud.d.ts

@@ -0,0 +1,59 @@
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export function findOne(Model: any, filter: Record<string, any>, opts?: {
+    select?: string[];
+}): Promise<any | null>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit?: number, offset?: number }} [opts] @returns {Promise<any[]>} */
+export function findMany(Model: any, filter: Record<string, any>, opts?: {
+    select?: string[];
+    orderBy?: any;
+    limit?: number;
+    offset?: number;
+}): Promise<any[]>;
+/** @param {any} Model @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export function findById(Model: any, id: any, opts?: {
+    select?: string[];
+}): Promise<any | null>;
+/** @param {any} Model @param {Record<string, any>} [filter] @returns {Promise<number>} */
+export function count(Model: any, filter?: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<boolean>} */
+export function exists(Model: any, filter: Record<string, any>): Promise<boolean>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit: number, offset?: number, withTotal?: boolean }} opts @returns {Promise<{ rows: any[], limit: number, offset: number, total?: number }>} */
+export function paginate(Model: any, filter: Record<string, any>, opts: {
+    select?: string[];
+    orderBy?: any;
+    limit: number;
+    offset?: number;
+    withTotal?: boolean;
+}): Promise<{
+    rows: any[];
+    limit: number;
+    offset: number;
+    total?: number;
+}>;
+/** @param {any} Model @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+export function insertOne(Model: any, data: Record<string, any>, opts?: {
+    returning?: boolean;
+}): Promise<any>;
+/** @param {any} Model @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+export function insertMany(Model: any, rows: Record<string, any>[], opts?: {
+    returning?: boolean;
+}): Promise<{
+    count: number;
+} | any[]>;
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+export function updateOne(Model: any, filter: Record<string, any>, patch: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export function updateMany(Model: any, filter: Record<string, any>, patch: Record<string, any>, opts?: {
+    all?: boolean;
+}): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<number>} */
+export function deleteOne(Model: any, filter: Record<string, any>): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export function deleteMany(Model: any, filter: Record<string, any>, opts?: {
+    all?: boolean;
+}): Promise<number>;
+/** @param {any} Model @param {Record<string, any>} data @param {{ conflict: string[], returning?: boolean }} opts @returns {Promise<any>} */
+export function upsert(Model: any, data: Record<string, any>, opts: {
+    conflict: string[];
+    returning?: boolean;
+}): Promise<any>;

package/types/test/index.d.ts

@@ -0,0 +1,84 @@
+export class MegaTest {
+    /**
+     * HTTP 액션 단위 테스트용 fixture (03-api-spec §12). 정적 메서드 컨트롤러·인라인 핸들러를
+     * `(req, res, ctx)` 로 직접 호출해 검증할 수 있다.
+     *
+     * @param {object} [opts]
+     * @param {Record<string, any>} [opts.params] - 경로 파라미터(`req.params`).
+     * @param {Record<string, any>} [opts.query] - 쿼리스트링(`req.query`).
+     * @param {any} [opts.body] - 요청 본문(`req.body`).
+     * @param {Record<string, any>} [opts.headers] - 요청 헤더(`req.headers`).
+     * @param {Record<string, any>} [opts.services] - `ctx.services` 로 주입할 서비스 mock 맵.
+     * @param {any} [opts.user] - 인증 사용자(`req.user`/`ctx.user`). 가드 우회 단위 테스트용.
+     * @param {Record<string, any>|null} [opts.session] - `req.session`/`ctx.session` 객체.
+     * @param {string} [opts.method] - HTTP 메서드(기본 'GET').
+     * @param {string} [opts.url] - 요청 경로(기본 '/').
+     * @param {string} [opts.requestId] - `ctx.requestId`/`req.id`(기본 'test-req').
+     * @param {any} [opts.app] - `ctx.app`(기본 null).
+     * @param {any} [opts.log] - 로거(기본 silent).
+     * @param {Record<string, any>} [opts.db] - `ctx.db(alias)` mock 맵.
+     * @param {Record<string, any>} [opts.cache] - `ctx.cache(alias)` mock 맵.
+     * @param {Record<string, any>} [opts.bus] - `ctx.bus(alias)` mock 맵.
+     * @param {Record<string, any>} [opts.lock] - `ctx.lock(alias)` mock 맵.
+     * @returns {{ req: any, res: any, ctx: any }} 핸들러에 그대로 넘기는 fixture(느슨한 타입 — 테스트 편의).
+     */
+    static makeHttp({ params, query, body, headers, services, user, session, method, url, requestId, app, log, db, cache, bus, lock, }?: {
+        params?: Record<string, any>;
+        query?: Record<string, any>;
+        body?: any;
+        headers?: Record<string, any>;
+        services?: Record<string, any>;
+        user?: any;
+        session?: Record<string, any> | null;
+        method?: string;
+        url?: string;
+        requestId?: string;
+        app?: any;
+        log?: any;
+        db?: Record<string, any>;
+        cache?: Record<string, any>;
+        bus?: Record<string, any>;
+        lock?: Record<string, any>;
+    }): {
+        req: any;
+        res: any;
+        ctx: any;
+    };
+    /**
+     * WS 채널 단위 테스트용 fixture (03-api-spec §12). 채널 메서드(`async join(sock, payload, ctx)` 등)를
+     * 직접 호출해 검증한다. `ctx.channel` 은 broadcast/directToUser 를 기록하는 stub.
+     *
+     * @param {object} [opts]
+     * @param {any} [opts.user] - 인증 사용자(`ctx.user`).
+     * @param {Record<string, any>} [opts.services] - `ctx.services` mock 맵.
+     * @param {Record<string, any>|null} [opts.session] - `ctx.session`.
+     * @param {{ id?: string, metadata?: object }} [opts.socket] - 소켓 초기값.
+     * @param {any} [opts.log] - 로거(기본 silent).
+     * @returns {{ sock: any, ctx: any }} 채널 메서드에 넘기는 fixture(느슨한 타입 — 테스트 편의).
+     */
+    static makeWs({ user, services, session, socket, log }?: {
+        user?: any;
+        services?: Record<string, any>;
+        session?: Record<string, any> | null;
+        socket?: {
+            id?: string;
+            metadata?: object;
+        };
+        log?: any;
+    }): {
+        sock: any;
+        ctx: any;
+    };
+    /**
+     * in-memory mock bus — `publish` 호출을 기록하고 `subscribe` 핸들러로 즉시 dispatch 한다. 실 NATS
+     * 없이 잡/이벤트 발행 검증용.
+     * @returns {Record<string, any>}
+     */
+    static mockBus(): Record<string, any>;
+    /**
+     * in-memory mock cache — Map 백엔드 `get/set/del/has`. TTL 인자는 받지만 만료는 흉내 내지 않는다
+     * (단위 테스트는 만료 동작이 아니라 호출·값을 검증).
+     * @returns {Record<string, any>}
+     */
+    static mockCache(): Record<string, any>;
+}

package/.env

@@ -1,127 +0,0 @@
-# Environment
-NODE_ENV=development
-
-# Server
-# 세션 쿠키 HMAC 키 — ≥32자 필수(config-validator M-1). dev/test 전용. ⚠️ 운영은 별도 시크릿으로 교체.
-SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
-# cluster 워커 프로세스 수(ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일 프로세스.
-# MEGA_CLUSTER_WORKERS=max
-
-# ─────────────────────────────────────────────────────────────────────
-# Docker 통합 테스트 인프라 제어 (ADR-103) — docker-compose.yml 이 읽음
-# 모두 dev/test 전용. ⚠️ 운영 환경 사용 금지.
-# 미설정 시 docker-compose.yml 의 인라인 디폴트가 그대로 적용됨.
-# 네이밍: MEGA_<SERVICE>_<FIELD> (코드의 MEGA_WSHUB_* 패턴과 정합)
-# ─────────────────────────────────────────────────────────────────────
-# Postgres (Step 4)
-MEGA_PG_PORT=5432
-MEGA_PG_USER=mega
-MEGA_PG_PASSWORD=dkTkqkfl12
-MEGA_PG_DB=mega_test
-# MariaDB (Step 4)
-MEGA_MARIA_PORT=3306
-MEGA_MARIA_ROOT_PASSWORD=dkTkqkfl12
-MEGA_MARIA_USER=mega
-MEGA_MARIA_PASSWORD=dkTkqkfl12
-MEGA_MARIA_DB=mega_test
-# MongoDB (Step 5)
-MEGA_MONGO_PORT=27017
-MEGA_MONGO_USER=mega
-MEGA_MONGO_PASSWORD=dkTkqkfl12
-MEGA_MONGO_DB=mega_test
-# Redis (Step 6)
-MEGA_REDIS_PORT=6379
-MEGA_REDIS_PASSWORD=dkTkqkfl12
-# NATS (Step 6)
-MEGA_NATS_PORT=4222
-MEGA_NATS_MONITOR_PORT=8222
-# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no
-MEGA_INFRA_RESTART=unless-stopped
-
-# ─────────────────────────────────────────────────────────────────────
-# 연결 문자열 (services config 가 읽음) — 위 docker 디폴트와 정합
-# 네이밍: <SERVICE>_URL (prefix 없는 services-키 패턴)
-# ─────────────────────────────────────────────────────────────────────
-# Database (services.databases.*)
-PG_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
-MARIA_URL=mariadb://mega:dkTkqkfl12@localhost:3306/mega_test
-MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
-
-# Redis (services.caches.*)
-REDIS_SESSION_URL=redis://:dkTkqkfl12@localhost:6379/0
-REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/1
-REDIS_RATE_URL=redis://:dkTkqkfl12@localhost:6379/2
-
-# NATS (services.buses.*)
-NATS_EVENTS_URL=nats://localhost:4222
-NATS_JOBS_URL=nats://localhost:4222
-
-# ─────────────────────────────────────────────────────────────────────
-# 어댑터 옵션 자동 매핑 (ADR-109, 12-factor) — services.<domain>.<key>.envPrefix 지정 시
-#   MegaAdapterManager 가 buildAdapterEnvConfig 로 읽어 어댑터 옵션에 병합(env 우선).
-#   grammar: MEGA_<SERVICE>_<KEY>
-#     URL                    → url
-#     HOST/PORT/USER/PASSWORD → 연결필드 (PORT 만 정수, 나머지 항상 문자열)
-#     DATABASE | DB          → database  /  DBNAME → dbName (Mongo)
-#     POOL_<X>               → pool.{camelCase(X)}   (driver 무관 공통 풀 인터페이스, 값 자동 타입변환)
-#     OPTIONS_<X>            → options.{driver별 키}  (driver-aware, 아래 표 — 값 자동 타입변환)
-#   ⚠️ 위 MEGA_<SERVICE>_PORT/USER/PASSWORD/DB 는 docker-compose(ADR-103)와 namespace 공유.
-#      grammar 불일치 키(예: MEGA_MARIA_ROOT_PASSWORD)는 어댑터 매핑에서 무시됨.
-#   # OPTIONS_* driver별 키 표기 (ADR-109 보강, Step 6 QA H-1 — .env 는 UPPER_SNAKE 로 통일해 적되
-#   #  driver 가 인식하는 표기로 자동 변환됨):
-#   #    redis/nats/mongodb/mariadb = camelCase  (KEY_PREFIX→keyPrefix, MAX_RECONNECT_ATTEMPTS→maxReconnectAttempts,
-#   #                                             SERVER_SELECTION_TIMEOUT_MS→serverSelectionTimeoutMS[MS 보존])
-#   #    postgres/sqlite/file       = snake_case (STATEMENT_TIMEOUT→statement_timeout)
-# ─────────────────────────────────────────────────────────────────────
-# 공통 풀 인터페이스 (드라이버 키로 자동 매핑 — 단위: idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs=ms)
-#   MEGA_PG_POOL_MIN=0
-#   MEGA_PG_POOL_MAX=10
-#   MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
-#   MEGA_PG_POOL_ACQUIRE_TIMEOUT_MS=0
-#   MEGA_PG_POOL_MAX_LIFETIME_MS=0            # pg 전용 (maria/mongo 미지원→throw)
-# 드라이버 특화 옵션 (passthrough — driver별 키 변환)
-#   MEGA_PG_OPTIONS_SSL=true                  # → options.ssl (pg=snake_case)
-#   MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000   # → options.statement_timeout
-#   MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number  # → options.bigIntStrategy (maria=camel) 'number'(디폴트,2^53 초과 정밀도 손실)|'bigint'|'string'
-#   MEGA_MARIA_OPTIONS_CHARSET=utf8mb4        # → options.charset
-#   MEGA_MARIA_OPTIONS_MULTIPLE_STATEMENTS=false  # → options.multipleStatements (camel 변환)
-#   MEGA_MONGO_DBNAME=mega_test               # Mongo dbName (url path 로도 가능)
-#   MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin      # → options.authSource (mongo=camel)
-#   MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS (MS 대문자 보존, 이제 env 로 가능)
-
-# WS Hub (mega ws-hub CLI — src/cli/ws-hub.js, runWsHubCli)
-# 코드가 읽는 키는 MEGA_WSHUB_* (언더스코어 없는 단일 service 토큰). TOKENS 만 필수.
-# 비밀 토큰은 운영에서 교체. hub 는 `mega ws-hub` 실행 시에만 기동(자동 기동 없음).
-MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
-MEGA_WSHUB_PORT=3100
-MEGA_WSHUB_HOST=0.0.0.0
-MEGA_WSHUB_HEARTBEAT_MS=25000
-MEGA_WSHUB_MAX_PAYLOAD=1048576
-# 압축(ADR-078) — 'true' 일 때만 ON. THRESHOLD 는 압축 ON 시에만 적용(byte).
-MEGA_WSHUB_COMPRESSION=false
-MEGA_WSHUB_COMPRESSION_THRESHOLD=1024
-
-# Telegram (옵션 — 로거 sink)
-# TG_BOT_TOKEN=   ← 실토큰은 .env.local 에. npm publish 노출 방지로 .env 에선 비움(2026-06-08).
-# TG_CHAT_ID=
-
-# OpenTelemetry 분산 트레이싱 (옵션 — Phase 3 Step 8 / Phase 5 Step 1, MegaTracing)
-#   MegaTracing.fromEnv() 가 읽는 런타임 키(ADR-114/126). 옵트인 OFF(디폴트)면 0 비용.
-#   ⚠️ 구 OTEL_ENABLED/OTEL_ENDPOINT(prefix 없는)는 코드가 안 읽는 죽은 키라 제거 — 반드시 MEGA_OTEL_*.
-MEGA_OTEL_ENABLED=false
-MEGA_OTEL_SERVICE_NAME=mega-app
-MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
-MEGA_OTEL_VERSION=
-MEGA_OTEL_ENVIRONMENT=
-
-# ── 실 OTel collector + Zipkin docker 백엔드 (ADR-128) — 통합 테스트(tracing E2E)가 읽음 ──
-# docker-compose 의 otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 실 OTLP→collector→zipkin 검증.
-# 미설정 시 tracing E2E(otel-collector-e2e)만 자동 skip(CI 일관성). OTLP HTTP traces path 는 /v1/traces.
-MEGA_OTEL_OTLP_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
-MEGA_OTEL_HEALTH_URL=http://localhost:13133
-
-# Log level
-LOG_LEVEL=info

package/sample/crud/apps/main/migrations/20260606000002-add-auth-to-users.js

@@ -1,30 +0,0 @@
-// @ts-check
-/**
- * 마이그레이션 add-auth-to-users (20260606000002). 로그인을 위해 users 에 인증 컬럼을 더한다(ADR-155).
- * `mega migrate`(up)·`mega migrate:down` 로 실행하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
- *
- * 컬럼은 모두 nullable — 기존 row(name+email 만 있는 사용자)를 깨지 않는다. password_hash 가 비어 있는
- * 계정은 로그인 대상이 아니며, /register 로 만든 계정만 해시를 가진다.
- *
- * - password_hash: scrypt 해시 문자열(`$scrypt$…`, src/lib/mega-hash.js). 평문 비밀번호는 저장하지 않는다.
- * - last_login_at: 마지막 로그인 시각(성공 시 갱신). 운영 관측·"최근 로그인" 표시에 쓴다.
- *
- * brute-force 실패 카운트·잠금은 DB 컬럼이 아니라 redis 에 둔다(원자적 INCR, src/lib/mega-brute-force.js,
- * ADR-049/130) — 여기 failed_login_count 같은 컬럼을 두지 않는 이유다.
- *
- * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
- * @returns {Promise<void>}
- */
-export async function up(db) {
-  await db.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
-  await db.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
-}
-
-/**
- * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
- * @returns {Promise<void>}
- */
-export async function down(db) {
-  await db.query('ALTER TABLE users DROP COLUMN IF EXISTS last_login_at')
-  await db.query('ALTER TABLE users DROP COLUMN IF EXISTS password_hash')
-}

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

@@ -1,71 +0,0 @@
-// @ts-check
-import { randomUUID } from 'node:crypto'
-import { MegaModel } from 'mega-framework'
-
-/**
- * Note 모델 — `notes` 컬렉션(globalKey 'mongo' 의 MongoDB, ADR-108). SQL 모델(User)과 달리 `this.db` 가
- * MongoClient 의 `Db` 핸들이라, ORM 없이 도큐먼트 API(`collection().find/insertOne/...`)로 도메인 메서드를
- * 직접 작성한다(ADR-009). 모델은 서비스만 import 한다(라우트·컨트롤러 직접 import 는 `mega/no-direct-model-import` 차단, ADR-022).
- *
- * 식별자는 mongo `_id`(ObjectId) 대신 자체 `id`(UUID v4) 필드를 쓴다 — 라우트 파라미터/폼에서 다루기 쉽고,
- * `mongodb` 드라이버의 `ObjectId` 를 샘플에서 import 하지 않아도 돼 driver 결합을 피한다. 읽기에서는
- * `_id` 를 projection 으로 제외해 도메인 형태만 노출한다.
- *
- * @typedef {{ id: string, title: string, body: string, created_at: string }} NoteDoc
- */
-export class Note extends MegaModel {
-  static adapter = 'mongo'
-  static table = 'notes'
-
-  /** 읽기 공통 projection — 내부 `_id` 를 빼고 도메인 필드만 돌려준다. */
-  static #projection = { projection: { _id: 0 } }
-
-  /** @returns {import('mongodb').Collection} `notes` 컬렉션 핸들. */
-  static get collection() {
-    return this.db.collection(this.table)
-  }
-
-  /** 최신순 전체 목록. @returns {Promise<NoteDoc[]>} */
-  static async list() {
-    return /** @type {Promise<NoteDoc[]>} */ (
-      this.collection.find({}, Note.#projection).sort({ created_at: -1 }).toArray()
-    )
-  }
-
-  /** 단건 조회(없으면 null). @param {string} id @returns {Promise<NoteDoc | null>} */
-  static async findById(id) {
-    return /** @type {Promise<NoteDoc | null>} */ (this.collection.findOne({ id }, Note.#projection))
-  }
-
-  /** 생성 — UUID·생성시각을 부여해 삽입한다. @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.collection.insertOne({ ...doc })
-    return doc
-  }
-
-  /**
-   * 수정 — 주어진 필드만 $set 한다(undefined 는 제외해 기존 값 보존). 대상이 없으면 null.
-   * @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) await this.collection.updateOne({ id }, { $set: set })
-    return this.findById(id)
-  }
-
-  /** 삭제 — 삭제 건수가 1 이상이면 true. @param {string} id @returns {Promise<boolean>} */
-  static async remove(id) {
-    const { deletedCount } = await this.collection.deleteOne({ id })
-    return deletedCount > 0
-  }
-
-  /** 전체 도큐먼트 수(캐시 데모용 카운트 쿼리). @returns {Promise<number>} */
-  static async count() {
-    return this.collection.countDocuments({})
-  }
-}

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

@@ -1,86 +0,0 @@
-// @ts-check
-import { MegaModel } from 'mega-framework'
-
-/**
- * User 모델 — `users` 테이블(globalKey 'primary' 의 postgres). ORM 없이 계측 SQL(`this.query`, ADR-138)로
- * 도메인 메서드를 직접 작성한다(ADR-009). 모델은 서비스만 import 한다(라우트·컨트롤러 직접 import 는
- * `mega/no-direct-model-import` 가 차단, ADR-022).
- *
- * @typedef {{ id: number, name: string, email: string, created_at: string }} UserRow
- * @typedef {{ id: number, name: string, email: string, password_hash: string | null }} UserAuthRow
- */
-export class User extends MegaModel {
-  static adapter = 'primary'
-  static table = 'users'
-
-  /** @returns {Promise<UserRow[]>} */
-  static async list() {
-    const { rows } = await this.query('SELECT id, name, email, created_at FROM users ORDER BY id ASC')
-    return rows
-  }
-
-  /** 전체 사용자 수 — /demo/redis 캐시 데모가 캐싱하는 SQL 카운트 쿼리. @returns {Promise<number>} */
-  static async count() {
-    const { rows } = await this.query('SELECT count(*)::int AS n FROM users')
-    return rows[0].n
-  }
-
-  /** @param {number} id @returns {Promise<UserRow | null>} */
-  static async findById(id) {
-    const { rows } = await this.query('SELECT id, name, email, created_at FROM users WHERE id = $1', [id])
-    return rows[0] ?? null
-  }
-
-  /** @param {{ name: string, email: string }} input @returns {Promise<UserRow>} */
-  static async create({ name, email }) {
-    const { rows } = await this.query(
-      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id, name, email, created_at',
-      [name, email],
-    )
-    return rows[0]
-  }
-
-  /** @param {number} id @param {{ name?: string, email?: string }} patch @returns {Promise<UserRow | null>} */
-  static async update(id, { name, email }) {
-    const { rows } = await this.query(
-      'UPDATE users SET name = COALESCE($2, name), email = COALESCE($3, email) WHERE id = $1 RETURNING id, name, email, created_at',
-      [id, name ?? null, email ?? null],
-    )
-    return rows[0] ?? null
-  }
-
-  /** @param {number} id @returns {Promise<boolean>} 삭제 여부. */
-  static async remove(id) {
-    const { rowCount } = await this.query('DELETE FROM users WHERE id = $1', [id])
-    return rowCount > 0
-  }
-
-  /**
-   * 비밀번호 해시를 포함해 새 사용자를 만든다(/register). 반환에는 해시를 포함하지 않는다(노출 최소화).
-   * @param {{ name: string, email: string, passwordHash: string }} input
-   * @returns {Promise<UserRow>}
-   */
-  static async register({ name, email, passwordHash }) {
-    const { rows } = await this.query(
-      'INSERT INTO users (name, email, password_hash) VALUES ($1, $2, $3) RETURNING id, name, email, created_at',
-      [name, email, passwordHash],
-    )
-    return rows[0]
-  }
-
-  /**
-   * 로그인 검증용 — 이메일로 사용자를 찾아 password_hash 까지 돌려준다. 해시가 필요한 인증 경로에서만 쓴다
-   * (일반 조회 list/findById 는 해시를 SELECT 하지 않아 노출되지 않는다).
-   * @param {string} email
-   * @returns {Promise<UserAuthRow | null>}
-   */
-  static async findByEmailWithHash(email) {
-    const { rows } = await this.query('SELECT id, name, email, password_hash FROM users WHERE email = $1', [email])
-    return rows[0] ?? null
-  }
-
-  /** 로그인 성공 시각 갱신. @param {number} id @returns {Promise<void>} */
-  static async touchLastLogin(id) {
-    await this.query('UPDATE users SET last_login_at = now() WHERE id = $1', [id])
-  }
-}