mega-framework 0.1.5 → 0.1.7

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'
 
@@ -15,6 +16,13 @@ export default {
     port: Number(process.env.PORT ?? 3000),
     // 세션 쿠키 HMAC 서명 시크릿(global 스코프, ADR-129). boot 이 앱에 주입한다. .env 의 SESSION_SECRET.
     sessionSecret: process.env.SESSION_SECRET,
+    // (예시·미사용) listen 호스트 — 기본 '0.0.0.0'. `mega start --host H`(CLI)가 우선.
+    // host: '0.0.0.0',
+    // (예시·미사용) cluster 워커 수 — CLI `--cluster` > .env MEGA_CLUSTER_WORKERS > 이 값(ADR-154). 정수 N | 'max'.
+    // cluster: 'max',
+    // (예시·미사용) 메트릭/트레이싱 resource 의 service.name·version(health.serviceName 미지정 시 폴백).
+    // serviceName: 'sample-crud',
+    // version: '0.1.0',
   },
 
   // ASP(Application-layer Secure Protocol) masterSecret — global 스코프 시크릿(ADR-127, scope-registry).
@@ -24,6 +32,8 @@ export default {
   // 이 값을 브라우저에 주입한다 — 그래서 운영 secret 과 분리된 데모 전용 값을 .env 의 ASP_MASTER_SECRET 에 둔다.
   asp: {
     masterSecret: process.env.ASP_MASTER_SECRET,
+    // (예시·미사용) HTTP body/query 암호화 옵션(enabledPaths·driftMs·nonceCache 등)은 **앱 스코프** —
+    //   apps/<app>/app.config.js 의 asp.http 에 둔다. 여기 global 블록엔 masterSecret 만(scope-registry).
   },
 
   // 전역 어댑터(ADR-102/106/109) — globalKey 로 선언, 앱은 app.config.js 의 별명으로 참조.
@@ -33,6 +43,11 @@ export default {
       primary: {
         driver: 'postgres',
         url: process.env.DATABASE_URL,
+        // (예시·미사용) url 대신 discrete 도 가능: { host, port, user, password, database } (url 과 상호배타).
+        // (예시·미사용) 공통 풀 인터페이스 — 드라이버별 키로 자동 매핑(ADR-109). 단위 *Ms=밀리초.
+        // pool: { min: 0, max: 10, idleTimeoutMs: 10_000 },
+        // (예시·미사용) 드라이버 네이티브 옵션 passthrough(pg=snake_case).
+        // options: { ssl: false, statement_timeout: 30_000 },
       },
       // DB 'mongo' — Document DB 어댑터(ADR-108). notes 데모 컬렉션(Note 모델 static adapter='mongo')의 공유
       // 인스턴스. url path 의 dbName(mega_test)을 어댑터가 추출한다. .env 의 MONGO_URL(authSource=admin).
@@ -40,6 +55,12 @@ export default {
         driver: 'mongodb',
         url: process.env.MONGO_URL,
       },
+      // (예시·미사용) MariaDB 어댑터(ADR-105). 쓰려면 주석 해제 + .env 의 MARIA_URL 설정.
+      // 모델은 static adapter='maria'(globalKey)로 닿고, app.config.js databases 에 별명 추가.
+      // maria: {
+      //   driver: 'mariadb',
+      //   url: process.env.MARIA_URL,
+      // },
     },
     caches: {
       // redis 캐시 'rate' — brute-force(ctx.bruteForce, ADR-049/130)의 원자적 INCR 백엔드. .env 의 REDIS_RATE_URL(db 2).
@@ -60,6 +81,12 @@ export default {
         driver: 'redis',
         url: process.env.REDIS_LOCK_URL,
       },
+      // (예시·미사용) 범용 캐시 — 일반 키/값 캐싱이 필요하면 주석 해제 + .env 의 REDIS_CACHE_URL 설정.
+      // 기존 캐시(rate/demo/lock)와 키 충돌을 피해 별도 논리 DB(/4 등)를 권장. app.config.js caches 에 별명 추가.
+      // cache: {
+      //   driver: 'redis',
+      //   url: process.env.REDIS_CACHE_URL,
+      // },
     },
     // NATS 버스 'jobs' — 잡 큐(EmailJob, ADR-119)의 JetStream 백엔드. producer(웹)는 ctx.bus('jobs').native(nc)로
     // enqueue, consumer(`mega worker`)는 같은 버스로 소비한다. .env 의 NATS_JOBS_URL.
@@ -68,6 +95,11 @@ export default {
         driver: 'nats',
         url: process.env.NATS_JOBS_URL,
       },
+      // (예시·미사용) 이벤트 버스 — pub/sub 등 두 번째 NATS 버스가 필요하면 주석 해제 + .env 의 NATS_EVENTS_URL.
+      // events: {
+      //   driver: 'nats',
+      //   url: process.env.NATS_EVENTS_URL,
+      // },
     },
     // 분산 락 'main' — redlock(ADR-113). caches.lock(Redis) 을 빌려 단일 노드 redlock 을 구성한다. /demo/cron
     // 스케줄(CronCounterSchedule.static lock)의 클러스터 중복방지(leader election)에 쓰인다.
@@ -79,6 +111,17 @@ export default {
     },
   },
 
+  // (예시·미사용) Embedded WS Hub(ADR-137) — `mega ws-hub` 별도 프로세스 대신 같은 프로세스에 허브를 띄움
+  //   (single-node). 켜면 app.config.js bridgeHub.url 을 이 host:port 로 맞춘다. acceptedTokens 필수(빈 값=throw).
+  // wsHub: {
+  //   enabled: true,
+  //   port: 3100,
+  //   host: '127.0.0.1',
+  //   acceptedTokens: (process.env.MEGA_WSHUB_TOKENS ?? '').split(',').filter(Boolean),
+  //   heartbeatMs: 25_000,
+  //   // compression: { enabled: false },
+  // },
+
   // ── 클러스터 전송 선택(ADR-176, 앱당 하나·상호배타) ───────────────────────────────────────────
   // 이 샘플은 현재 **WS Hub**(app.config 의 bridgeHub → `mega ws-hub` 서버, localhost:3100)로 채팅을
   // 클러스터 전파한다. boot 가 bridgeHub 를 보고 app.connectHub 를 자동 호출한다(개발자 배선 불요).
@@ -93,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],
@@ -101,11 +144,20 @@ export default {
   // CPU 워커 풀(ADR-124) — `mega start`(boot)가 ctx.workers['hash'] 로 배선한다(config.workers).
   workers: [HashWorker],
 
+  // (예시·미사용) 플러그인 — 명시 등록만(auto-discovery 없음, ADR-079). 문자열 또는 { name, options }.
+  // plugins: [{ name: 'my-plugin', options: {} }],
+
   // pino 로깅(ADR-023/141) — console sink, dev pretty. redact 로 민감필드를 sink 출력 전 메인스레드에서
   // 마스킹한다(token/password/secret/authorization). /demo/logs 데모가 이 마스킹을 시연한다(ADR-163).
   logger: {
-    level: 'debug',
-    sinks: [{ type: 'console', pretty: true }],
+    level: process.env.LOG_LEVEL ?? 'info',
+    // sinks — 출력처 배열. console(dev pretty) 외에 file(pino-roll)·telegram sink 지원.
+    sinks: [
+      { type: 'console', pretty: true },
+      // (예시·미사용) 파일 sink — 날짜 로테이션 + keep N.
+      // { type: 'file', path: './logs/app.log', rotation: 'daily', keep: 14 },
+      // (예시·미사용) telegram sink — warn 이상 알림. botToken/chatId 는 .env 등 시크릿으로 주입(코드·git 직접 X).
+    ],
     redact: ['*.password', '*.token', '*.secret', '*.authorization', 'password', 'token', 'secret'],
   },
 
@@ -114,5 +166,13 @@ export default {
     exposeMetrics: true,
     metricsPath: '/metrics',
     metricsAllowList: ['127.0.0.1', '::1'],
+    // (예시·미사용) liveness/readiness 경로 — 기본 '/health' · '/health/ready'.
+    // paths: { live: '/health', ready: '/health/ready' },
+    // (예시·미사용) 메트릭 resource service.name — 미지정 시 server.serviceName → MEGA_OTEL_SERVICE_NAME 폴백.
+    serviceName: 'sample-crud',
   },
+
+  // OpenTelemetry 분산 트레이싱 — **config 블록이 아니라 .env 의 MEGA_OTEL_\*** 로 설정한다
+  //   (MegaTracing.fromEnv, boot.js). MEGA_OTEL_ENABLED='true' + MEGA_OTEL_SERVICE_NAME 필수.
+  //   (`tracing` 키는 스키마엔 있으나 현재 부팅이 소비하지 않음 — 죽은 설정 회피 위해 블록을 두지 않음.)
 }

package/sample/crud/package.json

@@ -7,7 +7,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "dev": "NODE_ENV=development mega start",
+    "dev": "mega start --watch",
     "start": "NODE_ENV=production mega start",
     "migrate": "mega migrate",
     "migrate:down": "mega migrate:down",
@@ -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' })
   }
 }