mega-framework 0.1.6 → 0.1.7

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 }

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

@@ -1,56 +1,81 @@
 // @ts-check
 import { MegaService } from 'mega-framework'
+import { MegaHash } from 'mega-framework'
 import { MegaNotFoundError, MegaValidationError, MegaConflictError } from 'mega-framework/errors'
-import { User } from '../models/user.js'
+import { UserModel } from '../models/user-model.js'
 
 /**
  * UserService — user 도메인 비즈니스 로직(ADR-022). 컨트롤러는 모델을 직접 만지지 않고 이 서비스를
  * 거친다. 파일명 `user-service.js` → 자동 DI 이름 `user`(ctx.services.user, ADR-148). 모델 import 는
  * 서비스에서만 허용(유일한 모델 접근 경로).
+ *
+ * `users` 테이블이 username·name·nickname·password_hash 를 NOT NULL 로 요구하므로(ADR-204 schema),
+ * 관리자 생성도 회원가입과 동일하게 이 4개를 필수로 받고 비밀번호를 해시해 저장한다. 로그인 식별자는
+ * username 이다(email 은 선택).
  */
 export class UserService extends MegaService {
+  /** 비밀번호 최소 길이(auth-service 와 동일 정책). */
+  static MIN_PASSWORD = 8
+
   /** @returns {Promise<object[]>} */
   async list() {
     this.log.debug?.('user.list')
-    return User.list()
+    return UserModel.list()
   }
 
   /** @param {string|number} id @returns {Promise<object>} @throws {MegaNotFoundError} */
   async get(id) {
-    const user = await User.findById(Number(id))
+    const user = await UserModel.findById(Number(id))
     if (!user) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
     return user
   }
 
-  /** @param {{ name?: unknown, email?: unknown }} input @returns {Promise<object>} */
+  /**
+   * 관리자 사용자 생성. 필수: username·name·nickname·password. 선택: email·phone_number·type_code·level_code.
+   * 비밀번호는 해시해 저장(평문 미보관). 반환은 공개 컬럼(해시 미노출).
+   * @param {{ username?: unknown, name?: unknown, nickname?: unknown, email?: unknown, phone_number?: unknown, password?: unknown, type_code?: unknown, level_code?: unknown }} input
+   * @returns {Promise<object>}
+   * @throws {MegaValidationError} `user.invalid` @throws {MegaConflictError} `user.username_taken`|`user.nickname_taken`
+   */
   async create(input) {
+    const username = typeof input?.username === 'string' ? input.username.trim() : ''
     const name = typeof input?.name === 'string' ? input.name.trim() : ''
-    const email = typeof input?.email === 'string' ? input.email.trim() : ''
-    if (!name || !email) {
-      throw new MegaValidationError('user.invalid', 'name and email are required', { details: { name: !!name, email: !!email } })
+    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 : ''
+    const valid = { username: !!username, name: !!name, nickname: !!nickname, password: password.length >= UserService.MIN_PASSWORD }
+    if (!username || !name || !nickname || password.length < UserService.MIN_PASSWORD) {
+      throw new MegaValidationError('user.invalid', 'username, name, nickname and password(8+) are required', { details: valid })
     }
+    const passwordHash = await MegaHash.password.hash(password)
     try {
-      return await User.create({ name, email })
+      return await UserModel.create({
+        username,
+        name,
+        nickname,
+        email: email || null,
+        phone_number: phone || null,
+        passwordHash,
+        type_code: typeof input?.type_code === 'string' && input.type_code ? input.type_code : undefined,
+        level_code: typeof input?.level_code === 'string' && input.level_code ? input.level_code : undefined,
+      })
     } catch (err) {
-      // postgres unique_violation(23505) → 이메일 중복은 도메인 충돌(409)로 매핑(P4 — 명시 처리 후 throw).
-      if (/** @type {any} */ (err)?.code === '23505') {
-        throw new MegaConflictError('user.email_taken', `email '${email}' already exists`, { details: { email }, cause: err })
-      }
-      throw err
+      throw UserService.#mapConflict(err, { username, nickname })
     }
   }
 
-  /** @param {string|number} id @param {{ name?: string, email?: string }} patch @returns {Promise<object>} @throws {MegaNotFoundError} @throws {MegaConflictError} */
+  /**
+   * 부분 수정 — name·nickname·email·phone_number·type_code·level_code. username·password 는 안 바꾼다.
+   * @param {string|number} id @param {Record<string, any>} patch @returns {Promise<object>}
+   * @throws {MegaNotFoundError} @throws {MegaConflictError}
+   */
   async update(id, patch) {
     let updated
     try {
-      updated = await User.update(Number(id), { name: patch?.name, email: patch?.email })
+      updated = await UserModel.update(Number(id), patch ?? {})
     } catch (err) {
-      // create() 와 동일 — 이메일 중복(unique_violation 23505)은 도메인 충돌(409)로 매핑(P4 — 명시 처리 후 throw).
-      if (/** @type {any} */ (err)?.code === '23505') {
-        throw new MegaConflictError('user.email_taken', `email '${patch?.email}' already exists`, { details: { email: patch?.email }, cause: err })
-      }
-      throw err
+      throw UserService.#mapConflict(err, { nickname: patch?.nickname })
     }
     if (!updated) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
     return updated
@@ -58,8 +83,24 @@ export class UserService extends MegaService {
 
   /** @param {string|number} id @returns {Promise<{ deleted: true }>} @throws {MegaNotFoundError} */
   async remove(id) {
-    const ok = await User.remove(Number(id))
+    const ok = await UserModel.remove(Number(id))
     if (!ok) throw new MegaNotFoundError('user.not_found', `User ${id} not found`, { details: { id } })
     return { deleted: true }
   }
+
+  /**
+   * postgres unique_violation(23505) → username/nickname 도메인 충돌(409) 매핑(P4 — 명시 처리 후 throw).
+   * 그 외 에러는 그대로 반환(상위에서 throw).
+   * @param {unknown} err @param {{ username?: string, nickname?: string }} ctx @returns {Error}
+   */
+  static #mapConflict(err, ctx) {
+    if (/** @type {any} */ (err)?.code === '23505') {
+      const constraint = String(/** @type {any} */ (err)?.constraint ?? '')
+      if (constraint.includes('nickname')) {
+        return new MegaConflictError('user.nickname_taken', `nickname '${ctx.nickname}' already exists`, { details: { nickname: ctx.nickname }, cause: /** @type {any} */ (err) })
+      }
+      return new MegaConflictError('user.username_taken', `username '${ctx.username}' already exists`, { details: { username: ctx.username }, cause: /** @type {any} */ (err) })
+    }
+    return /** @type {Error} */ (err)
+  }
 }

package/sample/crud/apps/main/views/auth/login.ejs

@@ -17,14 +17,14 @@
           <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
           <div class="mb-3">
-            <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+            <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
             <input
-              type="email"
+              type="text"
               class="form-control"
-              id="email"
-              name="email"
-              value="<%= values && values.email ? values.email : '' %>"
-              placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
+              id="username"
+              name="username"
+              value="<%= values && values.username ? values.username : '' %>"
+              placeholder="<%= t('field_username_ph', '예: hong123') %>"
               autocomplete="username"
               required
             />

package/sample/crud/apps/main/views/auth/register.ejs

@@ -13,6 +13,21 @@
         <form method="post" action="/register" novalidate>
           <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+          <div class="mb-3">
+            <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+            <input
+              type="text"
+              class="form-control <%= invalid && invalid.username ? 'is-invalid' : '' %>"
+              id="username"
+              name="username"
+              value="<%= values && values.username ? values.username : '' %>"
+              placeholder="<%= t('field_username_ph', '예: hong123') %>"
+              autocomplete="username"
+              required
+            />
+            <div class="invalid-feedback"><%= t('field_username_required', '아이디를 입력하세요.') %></div>
+          </div>
+
           <div class="mb-3">
             <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
             <input
@@ -29,18 +44,44 @@
           </div>
 
           <div class="mb-3">
-            <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+            <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+            <input
+              type="text"
+              class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+              id="nickname"
+              name="nickname"
+              value="<%= values && values.nickname ? values.nickname : '' %>"
+              placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+              autocomplete="nickname"
+              required
+            />
+            <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+          </div>
+
+          <div class="mb-3">
+            <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
             <input
               type="email"
-              class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+              class="form-control"
               id="email"
               name="email"
               value="<%= values && values.email ? values.email : '' %>"
               placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
-              autocomplete="username"
-              required
+              autocomplete="email"
+            />
+          </div>
+
+          <div class="mb-3">
+            <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+            <input
+              type="tel"
+              class="form-control"
+              id="phone_number"
+              name="phone_number"
+              value="<%= values && values.phone_number ? values.phone_number : '' %>"
+              placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+              autocomplete="tel"
             />
-            <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
           </div>
 
           <div class="mb-4">

package/sample/crud/apps/main/views/users/edit.ejs

@@ -11,6 +11,19 @@
     <form method="post" action="/admin/users/<%= values.id %>" novalidate>
       <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+      <div class="mb-3">
+        <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+        <input
+          type="text"
+          class="form-control"
+          id="username"
+          value="<%= values && values.username ? values.username : '' %>"
+          readonly
+          disabled
+        />
+        <div class="form-text"><%= t('field_username_readonly', '아이디는 변경할 수 없습니다.') %></div>
+      </div>
+
       <div class="mb-3">
         <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
         <input
@@ -25,18 +38,42 @@
         <div class="invalid-feedback"><%= t('field_name_required', '이름을 입력하세요.') %></div>
       </div>
 
-      <div class="mb-4">
-        <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+      <div class="mb-3">
+        <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+          id="nickname"
+          name="nickname"
+          value="<%= values && values.nickname ? values.nickname : '' %>"
+          placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-3">
+        <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
         <input
           type="email"
-          class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+          class="form-control"
           id="email"
           name="email"
           value="<%= values && values.email ? values.email : '' %>"
           placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
-          required
         />
-        <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-4">
+        <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+        <input
+          type="tel"
+          class="form-control"
+          id="phone_number"
+          name="phone_number"
+          value="<%= values && values.phone_number ? values.phone_number : '' %>"
+          placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+        />
       </div>
 
       <div class="d-flex gap-2">

package/sample/crud/apps/main/views/users/list.ejs

@@ -24,7 +24,9 @@
       <thead>
         <tr>
           <th scope="col" class="text-end" style="width: 5rem"><%= t('col_id', 'ID') %></th>
+          <th scope="col"><%= t('col_username', '아이디') %></th>
           <th scope="col"><%= t('col_name', '이름') %></th>
+          <th scope="col"><%= t('col_nickname', '별명') %></th>
           <th scope="col"><%= t('col_email', '이메일') %></th>
           <th scope="col"><%= t('col_created', '생성일') %></th>
           <th scope="col" class="text-end"><%= t('col_actions', '관리') %></th>
@@ -34,8 +36,10 @@
         <% users.forEach(function (u) { %>
           <tr>
             <td class="text-end text-body-secondary"><%= u.id %></td>
-            <td class="fw-medium"><%= u.name %></td>
-            <td><%= u.email %></td>
+            <td class="fw-medium"><%= u.username %></td>
+            <td><%= u.name %></td>
+            <td><%= u.nickname %></td>
+            <td class="text-body-secondary"><%= u.email || '-' %></td>
             <td class="text-body-secondary small"><%= u.created_at %></td>
             <td class="text-end text-nowrap">
               <a href="/admin/users/<%= u.id %>/edit" class="btn btn-sm btn-outline-secondary"><%= t('action_edit', '수정') %></a>

package/sample/crud/apps/main/views/users/new.ejs

@@ -11,6 +11,21 @@
     <form method="post" action="/admin/users" novalidate>
       <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+      <div class="mb-3">
+        <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.username ? 'is-invalid' : '' %>"
+          id="username"
+          name="username"
+          value="<%= values && values.username ? values.username : '' %>"
+          placeholder="<%= t('field_username_ph', '예: hong123') %>"
+          autocomplete="off"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_username_required', '아이디를 입력하세요.') %></div>
+      </div>
+
       <div class="mb-3">
         <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
         <input
@@ -25,18 +40,55 @@
         <div class="invalid-feedback"><%= t('field_name_required', '이름을 입력하세요.') %></div>
       </div>
 
-      <div class="mb-4">
-        <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+      <div class="mb-3">
+        <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+          id="nickname"
+          name="nickname"
+          value="<%= values && values.nickname ? values.nickname : '' %>"
+          placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-3">
+        <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
         <input
           type="email"
-          class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+          class="form-control"
           id="email"
           name="email"
           value="<%= values && values.email ? values.email : '' %>"
           placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
+        />
+      </div>
+
+      <div class="mb-3">
+        <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+        <input
+          type="tel"
+          class="form-control"
+          id="phone_number"
+          name="phone_number"
+          value="<%= values && values.phone_number ? values.phone_number : '' %>"
+          placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+        />
+      </div>
+
+      <div class="mb-4">
+        <label for="password" class="form-label"><%= t('field_password', '비밀번호') %></label>
+        <input
+          type="password"
+          class="form-control <%= invalid && invalid.password ? 'is-invalid' : '' %>"
+          id="password"
+          name="password"
+          autocomplete="new-password"
           required
         />
-        <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
+        <div class="form-text <%= invalid && invalid.password ? 'text-danger' : '' %>"><%= t('field_password_hint', '최소 8자 이상 입력하세요.') %></div>
       </div>
 
       <div class="d-flex gap-2">

package/sample/crud/docs/log_partition_design.mm.md

@@ -0,0 +1,23 @@
+# 🏗️ Log Table Partitioning Architecture
+
+## 📦 LogPartitionSchedule
+- **Role**: 로그 테이블 파티션 자동 관리 스케줄러
+- **Responsibilities**
+    - 매일 특정 시각(예: 새벽 2시)에 실행
+    - 미래(다음 달, 다다음 달) 파티션 테이블 자동 생성
+    - 과거(1개월 이전) 오래된 파티션 테이블 자동 분리(Detach) 및 삭제(Drop)
+- **Concurrency Control**
+    - `static lock = { lock: 'log-partition', ttl: 60000 }` (Redlock을 활용하여 스케줄러 인스턴스 간 중복 실행 방지)
+
+## 📦 Database Partitioned Tables
+- **Role**: 시간 기반 범위 파티셔닝(Range Partitioning by `created_at`)을 통한 로그 데이터 관리
+- **Properties**
+    - `action_logs` (PARTITION BY RANGE (created_at))
+    - `wallet_logs` (PARTITION BY RANGE (created_at))
+    - `detail_logs` (PARTITION BY RANGE (created_at))
+- **Responsibilities**
+    - 대량 로그 유입 시 쓰기 성능 향상 및 Vacuum 오버헤드 완화
+    - 보관 주기(1개월) 만료 데이터의 물리적 삭제 성능 최적화 (DROP PARTITION)
+- **Constraints**
+    - Primary Key에 파티션 키 `created_at` 포함 필수: `PRIMARY KEY (id, created_at)`
+    - Unique Index에 파티션 키 `created_at` 포함 필수: `UNIQUE (uuid, created_at)` 등

package/sample/crud/mega.config.js

@@ -4,6 +4,7 @@
  * App-only 키(databases 별명 등)는 apps/<name>/app.config.js 로.
  */
 import { CronCounterSchedule } from './apps/main/schedules/cron-counter-schedule.js'
+import { LogPartitionSchedule } from './apps/main/schedules/log-partition-schedule.js'
 import { EmailJob } from './apps/main/jobs/email-job.js'
 import { HashWorker } from './apps/main/workers/hash-worker.js'
 
@@ -135,7 +136,7 @@ export default {
   // },
 
   // 정기 작업(ADR-028/118) — `mega scheduler` 프로세스가 등록·실행한다(config.schedules, ADR-123).
-  schedules: [CronCounterSchedule],
+  schedules: [CronCounterSchedule, LogPartitionSchedule],
 
   // 영속 잡(ADR-028/119) — `mega worker` 프로세스(ecosystem instances:2)가 소비한다(config.jobs, ADR-123).
   jobs: [EmailJob],
@@ -168,7 +169,7 @@ export default {
     // (예시·미사용) liveness/readiness 경로 — 기본 '/health' · '/health/ready'.
     // paths: { live: '/health', ready: '/health/ready' },
     // (예시·미사용) 메트릭 resource service.name — 미지정 시 server.serviceName → MEGA_OTEL_SERVICE_NAME 폴백.
-    // serviceName: 'sample-crud',
+    serviceName: 'sample-crud',
   },
 
   // OpenTelemetry 분산 트레이싱 — **config 블록이 아니라 .env 의 MEGA_OTEL_\*** 로 설정한다

package/sample/crud/package.json

@@ -23,6 +23,6 @@
   },
   "devDependencies": {
     "concurrently": "^9.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   }
 }

package/sample/crud/scripts/start-ws-hub.sh

@@ -6,8 +6,8 @@
 # 앱(`yarn dev` = `mega start`)이 app.config 의 `bridgeHub` 로 이 허브에 **자동 연결**한다(ADR-176).
 #
 # ⚠️ `mega-ws-hub` 는 `mega start` 와 달리 `.env` 를 자동 로드하지 않는다(직접 process.env 만 읽음,
-#    src/cli/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
-#    읽는 env(src/cli/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
+#    src/lib/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
+#    읽는 env(src/lib/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
 #    MEGA_WSHUB_PORT(기본 3100) / MEGA_WSHUB_HOST(기본 0.0.0.0) / MEGA_WSHUB_HEARTBEAT_MS.
 #
 # 사용:

package/sample/simple/package.json

@@ -16,10 +16,10 @@
     "test": "mega test"
   },
   "dependencies": {
-    "mega-framework": "^0.1.1"
+    "mega-framework": "file:../.."
   },
   "devDependencies": {
     "concurrently": "^9.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.8"
   }
 }

package/src/adapters/adapter-manager.js

@@ -127,7 +127,8 @@ export function buildFromGlobalConfig(globalConfig, { registerShutdownHook = tru
   if (registerShutdownHook) {
     // 재빌드 안전 — 항상 1개만 유지(MegaApp 의 hublink hook 패턴과 동일).
     MegaShutdown.unregister(SHUTDOWN_HOOK)
-    MegaShutdown.register(SHUTDOWN_HOOK, async () => disconnectAll())
+    // 'adapters' stage — 서버/잡/앱 정리(어댑터를 쓰는 정리)가 모두 끝난 뒤 disconnect 된다.
+    MegaShutdown.register(SHUTDOWN_HOOK, async () => disconnectAll(), { stage: 'adapters' })
   }
 }
 

package/src/adapters/adapter-options.js

@@ -47,6 +47,36 @@ function invalidOption(message, details) {
   return new MegaValidationError('adapter.invalid_option', message, { details })
 }
 
+/**
+ * `withTransaction(fn, opts)` 의 isolation 값 → 표준 SQL 조각 (ADR-190).
+ * 화이트리스트 매핑이라 SQL 인젝션이 구조적으로 불가능하다(임의 문자열은 throw).
+ * @type {Record<string, string>}
+ */
+const TX_ISOLATION_SQL = {
+  'read uncommitted': 'READ UNCOMMITTED',
+  'read committed': 'READ COMMITTED',
+  'repeatable read': 'REPEATABLE READ',
+  serializable: 'SERIALIZABLE',
+}
+
+/**
+ * 트랜잭션 격리수준 옵션 검증 + SQL 조각 변환 (ADR-190). `undefined` 는 driver 디폴트 위임(undefined 반환).
+ * @param {unknown} isolation - `withTransaction` 의 `opts.isolation`.
+ * @param {string} driver - 에러 메시지용 driver 이름.
+ * @returns {string | undefined} `SET TRANSACTION ISOLATION LEVEL <조각>` 에 쓸 SQL 조각.
+ * @throws {MegaValidationError} `adapter.invalid_option` - 화이트리스트 외 값.
+ */
+export function resolveTxIsolation(isolation, driver) {
+  if (isolation === undefined) return undefined
+  if (typeof isolation !== 'string' || !Object.prototype.hasOwnProperty.call(TX_ISOLATION_SQL, isolation)) {
+    throw invalidOption(
+      `${driver}: withTransaction "isolation" must be one of 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'. Got ${JSON.stringify(isolation)}.`,
+      { driver, option: 'isolation', value: isolation },
+    )
+  }
+  return TX_ISOLATION_SQL[isolation]
+}
+
 /**
  * 양의 정수(> 0) 검증 (undefined 통과). 위반 시 `adapter.invalid_option` throw.
  * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}