mega-framework 0.1.5 → 0.1.7

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('생성 시간'),
+  })
+}

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

@@ -0,0 +1,24 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * WalletModel — `wallets`(회원 지갑). user_id 는 users(id) FK(ON DELETE CASCADE). idx_wallets_user_id 동반.
+ *
+ * ⚠️ balance: 원본 손 DDL 은 무정밀 `DECIMAL`(임의 정밀도) 이지만 schema DSL 은 `decimal(p, s)` 만
+ *    표현 가능 → `NUMERIC(20, 4)` 로 **명시**(오너 승인 필요한 의도적 타입 명세). 정밀도 정책은 변경 가능.
+ *
+ * @typedef {{ id: number, user_id: number, balance: string, created_at: string }} WalletRow
+ */
+export class WalletModel extends MegaModel {
+  static adapter = 'primary'
+  static table = 'wallets'
+
+  static schema = /** @param {any} t */ (t) => ({
+    id: t.serial().primary(),
+    user_id: t.bigInteger().notNull().references('UserModel', 'id', { onDelete: 'cascade' }).comment('회원 ID'),
+    balance: t.decimal(20, 4).notNull().default(0).comment('잔액'),
+    created_at: t.timestamptz().notNull().default({ raw: 'now()' }).comment('생성 시간'),
+  })
+
+  static indexes = /** @param {any} t */ (t) => [t.index(['user_id'], { name: 'idx_wallets_user_id' })]
+}

package/sample/crud/apps/main/routes/users.js

@@ -11,44 +11,89 @@ import { requireAuth } from 'mega-framework/auth'
 import { UserController } from '../controllers/user-controller.js'
 
 /**
- * users REST 라우트의 OpenAPI 메타·schema(ADR-070/140/163). openapi 메타(tags/summary/description)는 명세에
- * 그대로 반영되고, body schema 는 명세 표시용으로 **비강제**(required 없음)라 기존 검증 동작을 바꾸지 않는다
- * (필드 검증은 user-service 가 담당, ADR). path 파라미터(id)는 문자열로 문서화한다.
+ * users REST 라우트의 schema + OpenAPI 메타(ADR-070/140/163/184).
+ *
+ * body schema 는 **강제 검증**이다(ADR-019 — 1차 검증은 Fastify 네이티브 AJV). 형식 위반은 핸들러
+ * 진입 전에 400 `validation.failed` envelope 로 거부되고, 서비스의 도메인 검증(user.invalid 등)은
+ * 2차 방어로 남는다. JSON API 는 CSRF 토큰 면제(Origin 검증, ADR-051)라 `_csrf` 필드가 없어
+ * `additionalProperties:false` 를 쓸 수 있다(폼 라우트와 다른 점). 단 Fastify 디폴트 AJV 는
+ * `removeAdditional:true` 라 선언 외 필드는 **거부가 아니라 제거**된다(입력 sanitize — 실측 확인).
+ *
+ * response schema 는 raw row 모양으로 선언한다 — 프레임워크가 envelope(`{ok,data,meta}`) 모양으로
+ * 자동 합성(ADR-184)하므로 선언 외 필드는 data 안에서 제거되고(ADR-020 strict — 우발 노출 방지)
+ * OpenAPI 명세도 실제 응답과 일치한다.
  */
 const idParams = { type: 'object', properties: { id: { type: 'string', description: '사용자 id' } } }
-const userBody = {
+const userCreateBody = {
+  type: 'object',
+  required: ['username', 'name', 'nickname', 'password'],
+  additionalProperties: false,
+  properties: {
+    username: { type: 'string', minLength: 1, description: '로그인 아이디' },
+    password: { type: 'string', minLength: 8, description: '비밀번호(8자 이상)' },
+    name: { type: 'string', minLength: 1, description: '실명' },
+    nickname: { type: 'string', minLength: 1, description: '별명' },
+    email: { type: 'string', format: 'email', description: '이메일(선택)' },
+    phone_number: { type: 'string', description: '전화번호(선택)' },
+  },
+}
+const userPatchBody = {
   type: 'object',
+  additionalProperties: false,
   properties: {
-    name: { type: 'string', description: '사용자 이름' },
+    name: { type: 'string', minLength: 1, description: '실명' },
+    nickname: { type: 'string', minLength: 1, description: '별명' },
     email: { type: 'string', format: 'email', description: '이메일' },
+    phone_number: { type: 'string', description: '전화번호' },
+  },
+}
+/** users 테이블 공개 row 응답 모양 (password_hash·uuid 제외 — UserModel.PUBLIC_COLUMNS 와 정합). */
+const userRow = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: '사용자 id(bigint → 문자열)' },
+    username: { type: 'string', description: '로그인 아이디' },
+    name: { type: 'string', description: '실명' },
+    nickname: { type: 'string', description: '별명' },
+    email: { type: ['string', 'null'], description: '이메일' },
+    phone_number: { type: ['string', 'null'], description: '전화번호' },
+    type_code: { type: 'string', description: '회원 유형' },
+    level_code: { type: 'string', description: '회원 등급' },
+    last_login_at: { type: ['string', 'null'], description: '마지막 로그인(ISO)' },
+    created_at: { type: 'string', description: '생성 시각(ISO)' },
   },
 }
+const userList = { type: 'array', items: userRow }
 
 export default (/** @type {any} */ router) => {
   /** @type {{ before: Function[] }} REST API 인증 가드(401 throw). */
   const guarded = { before: [requireAuth] }
   router.http.get('/users', UserController.index, {
     ...guarded,
+    schema: { response: { 200: userList } },
     openapi: { tags: ['users'], summary: '사용자 목록', description: '모든 사용자를 반환한다.' },
   })
   router.http.get('/users/:id', UserController.show, {
     ...guarded,
-    schema: { params: idParams },
+    schema: { params: idParams, response: { 200: userRow } },
     openapi: { tags: ['users'], summary: '사용자 조회', description: 'id 로 단일 사용자를 반환한다.' },
   })
   router.http.post('/users', UserController.create, {
     ...guarded,
-    schema: { body: userBody },
-    openapi: { tags: ['users'], summary: '사용자 생성', description: 'name·email 로 사용자를 생성한다.' },
+    schema: { body: userCreateBody, response: { 201: userRow } },
+    openapi: { tags: ['users'], summary: '사용자 생성', description: 'username·password·name·nickname 으로 사용자를 생성한다(email·phone 선택).' },
   })
   router.http.put('/users/:id', UserController.update, {
     ...guarded,
-    schema: { params: idParams, body: userBody },
+    schema: { params: idParams, body: userPatchBody, response: { 200: userRow } },
     openapi: { tags: ['users'], summary: '사용자 수정', description: 'id 사용자를 수정한다.' },
   })
   router.http.delete('/users/:id', UserController.destroy, {
     ...guarded,
-    schema: { params: idParams },
+    schema: {
+      params: idParams,
+      response: { 200: { type: 'object', properties: { deleted: { type: 'boolean' } } } },
+    },
     openapi: { tags: ['users'], summary: '사용자 삭제', description: 'id 사용자를 삭제한다.' },
   })
 }

package/sample/crud/apps/main/schedules/log-partition-schedule.js

@@ -0,0 +1,33 @@
+// @ts-check
+import { MegaSchedule } from 'mega-framework'
+import { LogPartitionService } from '../services/log-partition-service.js'
+
+/**
+ * LogPartitionSchedule — 로그 테이블 월별 파티셔닝 정기 관리 스케줄러 (ADR-028/118).
+ * `mega scheduler` 프로세스가 백그라운드에서 실행하며, 분산 락을 통해 멀티 인스턴스 환경에서 중복 실행을 예방합니다.
+ *
+ * 매일 새벽 2시에 작동하여 다음 달/다다음 달 파티션을 미리 생성해두고, 1개월 보존 기간이 만료된 지지난 달 파티션을 정리합니다.
+ */
+export class LogPartitionSchedule extends MegaSchedule {
+  // 매일 새벽 2시 0분에 작동하는 cron 식
+  static cron = '0 2 * * *'
+  // 실행 기준 타임존
+  static timezone = 'Asia/Seoul'
+  // 분산 락 설정 — lock 어댑터는 config.locks.main 을 공유하고, key 는 MegaScheduler 가
+  // 'mega:schedule:LogPartitionSchedule' 로 자동 생성하므로 다른 스케줄과 충돌 없음.
+  // TTL 은 DDL 수행 시간(수백 ms)보다 넉넉하게 1분으로 설정.
+  static lock = { lock: 'main', ttl: 60_000 }
+
+  /**
+   * 스케줄러 주기마다 호출되는 메인 비즈니스 함수입니다.
+   * @param {Record<string, any>} ctx - scheduler 프로세스 컨텍스트
+   * @returns {Promise<void>}
+   */
+  async run(ctx) {
+    ctx.log?.info?.('[LogPartitionSchedule] 스케줄링 태스크가 트리거되었습니다.')
+    
+    // 파티션 서비스 인스턴스를 생성하고 관리 프로세스 실행
+    const partitionService = new LogPartitionService(ctx)
+    await partitionService.manage()
+  }
+}

package/sample/crud/apps/main/services/auth-service.js

@@ -2,12 +2,13 @@
 import { MegaService } from 'mega-framework'
 import { MegaHash } from 'mega-framework'
 import { MegaValidationError, MegaConflictError } from 'mega-framework/errors'
-import { User } from '../models/user.js'
+import { UserModel } from '../models/user-model.js'
 
 /**
  * AuthService — 회원가입·로그인 검증 로직(ADR-155). 파일명 `auth-service.js` → 자동 DI 이름 `auth`
  * (ctx.services.auth, ADR-148). 비밀번호는 scrypt(MegaHash, ADR-130)로 해시해 저장하고, 검증은 상수
- * 시간 비교로 한다 — 평문은 어디에도 저장·로그하지 않는다.
+ * 시간 비교로 한다 — 평문은 어디에도 저장·로그하지 않는다. 로그인 식별자는 **username**(users.username,
+ * unique) 이다 — email 은 선택 입력이라 로그인 키로 쓰지 않는다.
  *
  * brute-force(반복 시도 잠금)는 이 서비스가 아니라 컨트롤러가 `ctx.bruteForce`(redis, ADR-049/130)로
  * 다룬다 — 잠금은 HTTP 요청(IP)·세션 흐름에 묶여 있어 컨트롤러 책임이기 때문이다.
@@ -16,59 +17,73 @@ export class AuthService extends MegaService {
   /** 비밀번호 최소 길이(OWASP Password Storage Cheat Sheet — 최소 8자 권장). */
   static MIN_PASSWORD = 8
 
+  /** 회원가입 필수 필드(전부 users 테이블 NOT NULL). */
+  static REQUIRED = ['username', 'name', 'nickname']
+
   /**
-   * 새 계정을 만든다. name·email·password 를 검증하고 비밀번호를 해시해 저장한다.
-   * @param {{ name?: unknown, email?: unknown, password?: unknown }} input
-   * @returns {Promise<{ id: number, name: string, email: string, created_at: string }>}
+   * 새 계정을 만든다. username·name·nickname·password 를 검증하고 비밀번호를 해시해 저장한다.
+   * email·phone_number 는 선택(빈 값 허용). type_code/level_code 는 DB 기본값(USER/lv1).
+   * @param {{ username?: unknown, name?: unknown, nickname?: unknown, email?: unknown, phone_number?: unknown, password?: unknown }} input
+   * @returns {Promise<import('../models/user-model.js').UserRow>}
    * @throws {MegaValidationError} `auth.invalid` - 필수값 누락 또는 비밀번호가 너무 짧음.
-   * @throws {MegaConflictError} `user.email_taken` - 이메일 중복.
+   * @throws {MegaConflictError} `user.username_taken` | `user.nickname_taken` - 중복.
    */
   async register(input) {
+    const username = typeof input?.username === 'string' ? input.username.trim() : ''
     const name = typeof input?.name === 'string' ? input.name.trim() : ''
+    const nickname = typeof input?.nickname === 'string' ? input.nickname.trim() : ''
     const email = typeof input?.email === 'string' ? input.email.trim().toLowerCase() : ''
+    const phone = typeof input?.phone_number === 'string' ? input.phone_number.trim() : ''
     const password = typeof input?.password === 'string' ? input.password : ''
-    if (!name || !email) {
-      throw new MegaValidationError('auth.invalid', 'name and email are required', { details: { name: !!name, email: !!email, password: password.length >= AuthService.MIN_PASSWORD } })
+
+    const valid = { username: !!username, name: !!name, nickname: !!nickname, password: password.length >= AuthService.MIN_PASSWORD }
+    if (!username || !name || !nickname) {
+      throw new MegaValidationError('auth.invalid', 'username, name, nickname are required', { details: valid })
     }
     if (password.length < AuthService.MIN_PASSWORD) {
-      throw new MegaValidationError('auth.invalid', `password must be at least ${AuthService.MIN_PASSWORD} characters`, { details: { name: !!name, email: !!email, password: false } })
+      throw new MegaValidationError('auth.invalid', `password must be at least ${AuthService.MIN_PASSWORD} characters`, { details: valid })
     }
+
     const passwordHash = await MegaHash.password.hash(password)
-    this.log.debug?.({ email }, 'auth.register')
+    this.log.debug?.({ username }, 'auth.register')
     try {
-      return await User.register({ name, email, passwordHash })
+      return await UserModel.register({ username, name, nickname, email: email || null, phone_number: phone || null, passwordHash })
     } catch (err) {
-      // 이메일 중복(postgres unique_violation 23505)은 도메인 충돌(409)로 매핑(P4 — 명시 처리 후 throw).
+      // unique_violation(23505) → 어느 제약인지로 username/nickname 충돌을 구분(409 매핑, P4 — 명시 처리 후 throw).
       if (/** @type {any} */ (err)?.code === '23505') {
-        throw new MegaConflictError('user.email_taken', `email '${email}' already exists`, { details: { email }, cause: err })
+        const constraint = String(/** @type {any} */ (err)?.constraint ?? '')
+        if (constraint.includes('nickname')) {
+          throw new MegaConflictError('user.nickname_taken', `nickname '${nickname}' already exists`, { details: { nickname }, cause: err })
+        }
+        throw new MegaConflictError('user.username_taken', `username '${username}' already exists`, { details: { username }, cause: err })
       }
       throw err
     }
   }
 
   /**
-   * 이메일+비밀번호를 검증한다. 일치하면 마지막 로그인 시각을 갱신하고 사용자 식별 정보를 돌려준다.
-   * 실패(없는 이메일·비밀번호 미설정 계정·불일치)는 **이유를 구분하지 않고** null 을 돌려준다
+   * username+비밀번호를 검증한다. 일치하면 마지막 로그인 시각을 갱신하고 사용자 식별 정보를 돌려준다.
+   * 실패(없는 username·비밀번호 미설정 계정·불일치)는 **이유를 구분하지 않고** null 을 돌려준다
    * (user enumeration 방지 — 어느 쪽이 틀렸는지 노출하지 않는다, OWASP Authentication Cheat Sheet).
-   * @param {{ email?: unknown, password?: unknown }} input
-   * @returns {Promise<{ id: number, name: string } | null>}
+   * @param {{ username?: unknown, password?: unknown }} input
+   * @returns {Promise<{ id: number|string, name: string } | null>}
    */
   async authenticate(input) {
-    const email = typeof input?.email === 'string' ? input.email.trim().toLowerCase() : ''
+    const username = typeof input?.username === 'string' ? input.username.trim() : ''
     const password = typeof input?.password === 'string' ? input.password : ''
-    if (!email || !password) return null
-    const row = await User.findByEmailWithHash(email)
-    this.log.debug?.({ email, found: row !== null }, 'auth.authenticate lookup')
+    if (!username || !password) return null
+    const row = await UserModel.findByUsernameWithHash(username)
+    this.log.debug?.({ username, found: row !== null }, 'auth.authenticate lookup')
     if (row === null || typeof row.password_hash !== 'string') {
-      // 없는 이메일이거나 비밀번호 미설정(admin CRUD 로 만든 계정) — 둘 다 로그인 불가.
+      // 없는 username 이거나 비밀번호 미설정 — 둘 다 로그인 불가.
       return null
     }
     const ok = await MegaHash.password.verify(password, row.password_hash)
     if (!ok) {
-      this.log.debug?.({ email }, 'auth.authenticate mismatch')
+      this.log.debug?.({ username }, 'auth.authenticate mismatch')
       return null
     }
-    await User.touchLastLogin(row.id)
+    await UserModel.touchLastLogin(row.id)
     return { id: row.id, name: row.name }
   }
 }

package/sample/crud/apps/main/services/log-partition-service.js

@@ -0,0 +1,101 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { LogPartitionModel } from '../models/log-partition-model.js'
+
+/**
+ * 로그 파티션 자동 관리 서비스 클래스 (ADR-148).
+ * 매월 데이터베이스 파티션을 미리 확보하고 오래된 파티션을 드롭(Drop)하는 핵심 비즈니스 로직을 포함합니다.
+ * @extends {MegaService}
+ */
+export class LogPartitionService extends MegaService {
+  /**
+   * @param {Record<string, any>} ctx - 요청/스케줄러 컨텍스트
+   */
+  constructor(ctx) {
+    super(ctx)
+    /** @type {Record<string, any>} 요청/스케줄러 컨텍스트 (MegaService 기본 바인딩 — 타입 힌트용 재선언) */
+    this.ctx = ctx
+  }
+
+  /** 파티셔닝 대상 테이블 리스트 */
+  static TARGET_TABLES = ['action_logs', 'wallet_logs', 'detail_logs']
+
+  /**
+   * 현재 월(M) 및 미래 파티션(M+1, M+2)을 자동 생성합니다.
+   * 현재 월을 포함하여 항상 3개월 치를 보장함으로써, 스케줄러가 장기간 중단된 후
+   * 복구되더라도 INSERT 가 실패하지 않도록 방어합니다.
+   * @param {Date} baseDate - 기준 날짜 (기본값: 오늘)
+   * @returns {Promise<void>}
+   */
+  async ensurePartitions(baseDate = new Date()) {
+    // 현재 월(M) — 반드시 존재해야 INSERT 가 라우팅 됨
+    const m0 = new Date(baseDate.getFullYear(), baseDate.getMonth(), 1)
+    // 다음 달(M+1) 계산
+    const m1 = new Date(baseDate.getFullYear(), baseDate.getMonth() + 1, 1)
+    // 다다음 달(M+2) 계산
+    const m2 = new Date(baseDate.getFullYear(), baseDate.getMonth() + 2, 1)
+
+    // 각 대상 테이블마다 현재/미래 파티션 존재 여부를 확인하고 생성
+    for (const table of LogPartitionService.TARGET_TABLES) {
+      this.ctx.log?.info?.(`[LogPartition] ${table} 테이블의 파티션 보장 중 (M, M+1, M+2)...`)
+
+      // 현재 월 파티션 보장 (CREATE TABLE IF NOT EXISTS 이므로 이미 있으면 무시됨)
+      await LogPartitionModel.createPartition(table, m0.getFullYear(), m0.getMonth() + 1)
+      // 다음 달 파티션 생성
+      await LogPartitionModel.createPartition(table, m1.getFullYear(), m1.getMonth() + 1)
+      // 다다음 달 파티션 생성
+      await LogPartitionModel.createPartition(table, m2.getFullYear(), m2.getMonth() + 1)
+    }
+  }
+
+  /**
+   * 보관 주기(1달)가 초과된 과거 파티션(지지난 달 M-2 이하)을 자동 분리 후 삭제합니다.
+   * @param {Date} baseDate - 기준 날짜 (기본값: 오늘)
+   * @returns {Promise<void>}
+   */
+  async cleanupPastPartitions(baseDate = new Date()) {
+    // "한 달 보관" 기준: 이번 달(M)과 지난 달(M-1)은 보존하고,
+    // 지지난 달(M-2)의 1일 이전 데이터를 포함하는 파티션을 삭제 대상으로 판단함.
+    const cutoffDate = new Date(baseDate.getFullYear(), baseDate.getMonth() - 2, 1)
+    const cutoffYear = cutoffDate.getFullYear()
+    const cutoffMonth = cutoffDate.getMonth() + 1
+
+    for (const table of LogPartitionService.TARGET_TABLES) {
+      // 실제 존재하는 파티션 목록 조회
+      const partitions = await LogPartitionModel.getPartitions(table)
+      
+      for (const pName of partitions) {
+        // 파티션 이름에서 연도와 월 파싱 (예: action_logs_y2026m04 -> 2026, 4)
+        const match = pName.match(/_y(\d{4})m(\d{2})$/)
+        if (!match) continue
+
+        const pYear = parseInt(match[1], 10)
+        const pMonth = parseInt(match[2], 10)
+
+        // 파티션의 연월이 정리 기준선(cutoff) 이하인 경우 삭제 진행
+        const isExpired = pYear < cutoffYear || (pYear === cutoffYear && pMonth <= cutoffMonth)
+        if (isExpired) {
+          this.ctx.log?.info?.(`[LogPartition] 만료된 파티션 정리 중: ${table} -> ${pName}`)
+          // 안전하게 분리 후 삭제 진행
+          await LogPartitionModel.dropPartition(table, pName)
+        }
+      }
+    }
+  }
+
+  /**
+   * 파티션 생성 및 정리 작업을 통합 관리하는 메인 서비스 진입점입니다.
+   * @returns {Promise<void>}
+   */
+  async manage() {
+    this.ctx.log?.info?.('[LogPartition] 로그 테이블 파티션 관리 작업을 시작합니다.')
+    
+    // 1. 현재 월 + 미래 파티션 보장 (M, M+1, M+2)
+    await this.ensurePartitions()
+    
+    // 2. 만료된 과거 파티션 정리
+    await this.cleanupPastPartitions()
+    
+    this.ctx.log?.info?.('[LogPartition] 로그 테이블 파티션 관리 작업을 완료했습니다.')
+  }
+}

package/sample/crud/apps/main/services/note-service.js

@@ -1,7 +1,7 @@
 // @ts-check
 import { MegaService } from 'mega-framework'
 import { MegaNotFoundError, MegaValidationError } from 'mega-framework/errors'
-import { Note } from '../models/note.js'
+import { NoteModel } from '../models/note-model.js'
 
 /**
  * NoteService — note 도메인 비즈니스 로직(ADR-022). 컨트롤러는 모델을 직접 만지지 않고 이 서비스를 거친다.
@@ -16,12 +16,12 @@ export class NoteService extends MegaService {
   /** @returns {Promise<object[]>} */
   async list() {
     this.log.debug?.('note.list')
-    return Note.list()
+    return NoteModel.list()
   }
 
   /** @param {string} id @returns {Promise<object>} @throws {MegaNotFoundError} */
   async get(id) {
-    const note = await Note.findById(String(id))
+    const note = await NoteModel.findById(String(id))
     if (!note) throw new MegaNotFoundError('note.not_found', `Note ${id} not found`, { details: { id } })
     return note
   }
@@ -34,7 +34,7 @@ export class NoteService extends MegaService {
   async create(input) {
     const { title, body } = NoteService.#normalize(input)
     this.log.debug?.({ title }, 'note.create')
-    return Note.create({ title, body })
+    return NoteModel.create({ title, body })
   }
 
   /**
@@ -44,14 +44,14 @@ export class NoteService extends MegaService {
    */
   async update(id, patch) {
     const { title, body } = NoteService.#normalize(patch)
-    const updated = await Note.update(String(id), { title, body })
+    const updated = await NoteModel.update(String(id), { title, body })
     if (!updated) throw new MegaNotFoundError('note.not_found', `Note ${id} not found`, { details: { id } })
     return updated
   }
 
   /** @param {string} id @returns {Promise<{ deleted: true }>} @throws {MegaNotFoundError} */
   async remove(id) {
-    const ok = await Note.remove(String(id))
+    const ok = await NoteModel.remove(String(id))
     if (!ok) throw new MegaNotFoundError('note.not_found', `Note ${id} not found`, { details: { id } })
     return { deleted: true }
   }

package/sample/crud/apps/main/services/redis-demo-service.js

@@ -1,6 +1,6 @@
 // @ts-check
 import { MegaService } from 'mega-framework'
-import { User } from '../models/user.js'
+import { UserModel } from '../models/user-model.js'
 
 /**
  * RedisDemoService — /demo/redis 데모 로직(ADR-157). 파일명 `redis-demo-service.js` → 자동 DI 이름
@@ -8,7 +8,7 @@ import { User } from '../models/user.js'
  *
  *   1) **방문 카운터** — 표준 캐시 표면(get/set)에 없는 원자적 INCR 가 필요하므로 `.native`(raw ioredis)로
  *      `INCR`/`EXPIRE` 를 직접 호출한다(ADR-009 escape hatch). 누적 카운터 + 일자별 카운터(TTL 2일).
- *   2) **쿼리 결과 캐시** — 표준 표면 `get/set`(JSON 직렬화 + TTL)으로 SQL 카운트(User.count)를 30초 캐싱한다.
+ *   2) **쿼리 결과 캐시** — 표준 표면 `get/set`(JSON 직렬화 + TTL)으로 SQL 카운트(UserModel.count)를 30초 캐싱한다.
  *      hit/miss 와 남은 TTL(`.native.ttl`)을 함께 돌려줘 캐시 동작을 눈으로 보게 한다.
  *
  * 캐시 키는 'demo' 캐시 안에서 `demo:redis:*` 네임스페이스로 두어 다른 용도와 분리한다(같은 redis 인스턴스라도
@@ -56,7 +56,7 @@ export class RedisDemoService extends MegaService {
       this.ctx.log?.debug?.({ value: cached, ttlSeconds }, 'redis-demo.cache hit')
       return { value: cached, isHit: true, ttlSeconds }
     }
-    const value = await User.count()
+    const value = await UserModel.count()
     await cache.set(RedisDemoService.USER_COUNT_KEY, value, { ttl: RedisDemoService.USER_COUNT_TTL })
     this.ctx.log?.debug?.({ value }, 'redis-demo.cache miss — recomputed from SQL')
     return { value, isHit: false, ttlSeconds: RedisDemoService.USER_COUNT_TTL }