mega-framework 0.1.0

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

@@ -0,0 +1,15 @@
+// @ts-check
+/**
+ * apps/main/routes/auth.js — 인증 라우트(자동 로딩, loadRoutes, ADR-155). 로그인/로그아웃/회원가입은
+ * `/admin/**` 보호 영역 **밖**에 둔다(보호 영역 안이면 비로그인 → 로그인 리다이렉트 루프). HTML 폼은
+ * GET/POST 만 쓰므로 로그아웃도 POST(+CSRF)다.
+ */
+import { AuthController } from '../controllers/auth-controller.js'
+
+export default (/** @type {any} */ router) => {
+  router.http.get('/auth/login', AuthController.loginForm)
+  router.http.post('/auth/login', AuthController.login)
+  router.http.post('/auth/logout', AuthController.logout)
+  router.http.get('/register', AuthController.registerForm)
+  router.http.post('/register', AuthController.register)
+}

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

@@ -0,0 +1,14 @@
+// @ts-check
+/**
+ * apps/main/routes/cron.js — /demo/cron 스케줄러 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로). 수동 실행은 HTML 폼이라 POST 다.
+ */
+import { CronController } from '../controllers/cron-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/cron', CronController.index, guarded)
+  router.http.post('/demo/cron/run', CronController.runNow, guarded)
+}

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

@@ -0,0 +1,25 @@
+// @ts-check
+/**
+ * apps/main/routes/guide.js — /guide 가이드 뷰어(MPA) 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로). 둘 다 읽기 전용 GET 이다.
+ */
+import { GuideController } from '../controllers/guide-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+/**
+ * slug path 파라미터 스키마(ADR-019) — 라우터 AJV 가 형식을 1차 검증해 잘못된 slug 를 핸들러 진입 전에
+ * 400 으로 막는다(소문자·숫자로 시작, 이후 소문자·숫자·하이픈만). guide-service 의 화이트리스트·SLUG_RE
+ * 가드는 그대로 둔다 — 경로 조작 차단의 심층 방어이자, 형식은 맞지만 존재하지 않는 slug 의 404 처리를 맡는다.
+ */
+const slugParams = {
+  type: 'object',
+  required: ['slug'],
+  properties: { slug: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$', maxLength: 100 } },
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 가이드 뷰어 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/guide', GuideController.index, guarded)
+  router.http.get('/guide/:slug', GuideController.page, { ...guarded, schema: { params: slugParams } })
+}

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

@@ -0,0 +1,14 @@
+// @ts-check
+/**
+ * apps/main/routes/jobs.js — /demo/jobs 잡 큐 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다. enqueue 는 HTML 폼이라 POST(CSRF 토큰 검증).
+ */
+import { JobsController } from '../controllers/jobs-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/jobs', JobsController.index, guarded)
+  router.http.post('/demo/jobs/enqueue', JobsController.enqueue, guarded)
+}

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

@@ -0,0 +1,28 @@
+// @ts-check
+/**
+ * apps/main/routes/logs.js — /demo/logs 구조적 로깅 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157/163).
+ * `webRequireAuth`(ADR-155)로 보호한다. 로그 emit 은 HTML 폼이라 POST(PRG).
+ */
+import { LogsController } from '../controllers/logs-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+/**
+ * emit 폼 body 스키마(ADR-019) — 라우터 AJV 가 타입·길이를 검증한다. level 의 허용값(allowlist) 판정과
+ * 빈값 폴백은 logs-demo-service 가 도메인 규칙으로 계속 맡으므로(중복 금지) 여기선 타입만 본다. message 는
+ * 과대 페이로드(비치명적 본문) 차단용 상한만 둔다. CSRF 토큰(`_csrf`)이 같은 폼 body 로 오므로
+ * additionalProperties 는 닫지 않는다 — 글로벌 CSRF 가드(preHandler)가 검증 후 소비한다.
+ */
+const emitBody = {
+  type: 'object',
+  properties: {
+    level: { type: 'string' },
+    message: { type: 'string', maxLength: 500 },
+  },
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/logs', LogsController.index, guarded)
+  router.http.post('/demo/logs/emit', LogsController.emit, { ...guarded, schema: { body: emitBody } })
+}

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

@@ -0,0 +1,13 @@
+// @ts-check
+/**
+ * apps/main/routes/metrics.js — /demo/metrics 관측 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157/163).
+ * `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로).
+ */
+import { MetricsController } from '../controllers/metrics-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/metrics', MetricsController.index, guarded)
+}

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

@@ -0,0 +1,19 @@
+// @ts-check
+/**
+ * apps/main/routes/notes.js — mongo notes 데모 UI(MPA) 라우트(자동 로딩, loadRoutes, ADR-157).
+ * users 의 web.js 와 같은 규약 — HTML 폼은 GET/POST 만 쓰므로 수정/삭제도 POST 다. `/demo/notes`
+ * 네임스페이스 전체를 `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로 리다이렉트).
+ */
+import { NoteController } from '../controllers/note-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/notes', NoteController.list, guarded)
+  router.http.get('/demo/notes/new', NoteController.newForm, guarded)
+  router.http.post('/demo/notes', NoteController.create, guarded)
+  router.http.get('/demo/notes/:id/edit', NoteController.editForm, guarded)
+  router.http.post('/demo/notes/:id', NoteController.update, guarded)
+  router.http.post('/demo/notes/:id/delete', NoteController.destroy, guarded)
+}

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

@@ -0,0 +1,47 @@
+// @ts-check
+/**
+ * apps/main/routes/perf.js — /perf 성능 벤치마크 데모 UI + 실행 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로). 실행(run)은 AJAX(JSON) 엔드포인트라
+ * CSRF 는 토큰 면제 + Origin 검증으로 통과한다(ADR-051). body 는 AJV 스키마로 검증한다(ADR-019).
+ */
+import { PerfController } from '../controllers/perf-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+/**
+ * POST /perf/run body 스키마(AJV). scenario enum 은 서비스 SCENARIO_LIMITS 키와 동일 집합. iterations 는
+ * 필수, concurrency/payloadSize 는 선택(미지정 시 서비스가 시나리오별 디폴트·clamp 적용). additionalProperties:
+ * false — JSON 요청이라 폼 `_csrf` 필드가 섞이지 않으므로 엄격하게 닫는다(per ADR-051 JSON 토큰 면제).
+ */
+const runSchema = {
+  body: {
+    type: 'object',
+    required: ['scenario', 'iterations'],
+    additionalProperties: false,
+    properties: {
+      scenario: {
+        type: 'string',
+        enum: [
+          'http.echo',
+          'http.jsonSmall',
+          'http.jsonLarge',
+          'crypto.hash',
+          'crypto.aspRoundtrip',
+          'db.pg.insertSelect',
+          'db.mongo.insertFind',
+          'cache.redis.setGet',
+          'session.createRead',
+        ],
+      },
+      iterations: { type: 'integer', minimum: 1, maximum: 100000 },
+      concurrency: { type: 'integer', minimum: 1, maximum: 100 },
+      payloadSize: { type: 'integer', minimum: 0, maximum: 1048576 },
+    },
+  },
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/perf', PerfController.index, guarded)
+  router.http.post('/perf/run', PerfController.run, { before: [webRequireAuth], schema: runSchema })
+}

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

@@ -0,0 +1,14 @@
+// @ts-check
+/**
+ * apps/main/routes/redis.js — /demo/redis 데모 UI(MPA) 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다(비로그인은 로그인 페이지로). 캐시 비우기는 HTML 폼이라 POST 다.
+ */
+import { RedisController } from '../controllers/redis-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/redis', RedisController.index, guarded)
+  router.http.post('/demo/redis/clear', RedisController.clearCache, guarded)
+}

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

@@ -0,0 +1,14 @@
+// @ts-check
+/**
+ * apps/main/routes/tracing.js — /demo/tracing 분산 추적 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157/163).
+ * `webRequireAuth`(ADR-155)로 보호한다. trace 생성은 HTML 폼이라 POST(PRG).
+ */
+import { TracingController } from '../controllers/tracing-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/tracing', TracingController.index, guarded)
+  router.http.post('/demo/tracing/generate', TracingController.generate, guarded)
+}

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

@@ -0,0 +1,16 @@
+// @ts-check
+/**
+ * apps/main/routes/upload.js — /demo/upload 파일 업로드 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157/163).
+ * `webRequireAuth`(ADR-155)로 보호한다. 업로드는 multipart POST(fetch + csrf-token 헤더).
+ */
+import { UploadController } from '../controllers/upload-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/upload', UploadController.index, guarded)
+  router.http.post('/demo/upload', UploadController.upload, guarded)
+  // 다운로드 — 소스에서 파일 읽어 전송(인증 필요). 가드를 떼면 공개 다운로드로 전환된다.
+  router.http.get('/demo/upload/file/:name', UploadController.download, guarded)
+}

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

@@ -0,0 +1,54 @@
+// @ts-check
+/**
+ * apps/main/routes/users.js — users REST 라우트(자동 로딩, loadRoutes). 단일 시그니처
+ * `router.http.<method>(path, handler)`(ADR-074). 핸들러는 컨트롤러 정적 메서드 참조 — 라우트·컨트롤러는
+ * 모델을 직접 import 하지 않는다(ADR-022, `mega/no-direct-model-import`).
+ *
+ * JSON API 는 프레임워크 `requireAuth`(mega-framework/auth, ADR-143/155)로 보호한다 — 비로그인 호출은
+ * 401 `auth.required` envelope. 세션 쿠키(`mega.sid`)를 가진 요청만 통과한다(웹 UI 와 같은 세션).
+ */
+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)는 문자열로 문서화한다.
+ */
+const idParams = { type: 'object', properties: { id: { type: 'string', description: '사용자 id' } } }
+const userBody = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', description: '사용자 이름' },
+    email: { type: 'string', format: 'email', description: '이메일' },
+  },
+}
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} REST API 인증 가드(401 throw). */
+  const guarded = { before: [requireAuth] }
+  router.http.get('/users', UserController.index, {
+    ...guarded,
+    openapi: { tags: ['users'], summary: '사용자 목록', description: '모든 사용자를 반환한다.' },
+  })
+  router.http.get('/users/:id', UserController.show, {
+    ...guarded,
+    schema: { params: idParams },
+    openapi: { tags: ['users'], summary: '사용자 조회', description: 'id 로 단일 사용자를 반환한다.' },
+  })
+  router.http.post('/users', UserController.create, {
+    ...guarded,
+    schema: { body: userBody },
+    openapi: { tags: ['users'], summary: '사용자 생성', description: 'name·email 로 사용자를 생성한다.' },
+  })
+  router.http.put('/users/:id', UserController.update, {
+    ...guarded,
+    schema: { params: idParams, body: userBody },
+    openapi: { tags: ['users'], summary: '사용자 수정', description: 'id 사용자를 수정한다.' },
+  })
+  router.http.delete('/users/:id', UserController.destroy, {
+    ...guarded,
+    schema: { params: idParams },
+    openapi: { tags: ['users'], summary: '사용자 삭제', description: 'id 사용자를 삭제한다.' },
+  })
+}

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

@@ -0,0 +1,23 @@
+// @ts-check
+/**
+ * apps/main/routes/web.js — 관리 UI(MPA) 라우트(자동 로딩, loadRoutes). JSON REST API(`/users`,
+ * routes/users.js)와 충돌하지 않도록 UI 는 `/admin/users` 네임스페이스를 쓴다. HTML 폼은 GET/POST 만
+ * 쓰므로 수정/삭제도 POST 다(브라우저 폼 제약 — PUT/DELETE 는 JSON API 쪽이 RESTful 하게 제공).
+ *
+ * `/admin/**` 는 `webRequireAuth`(ADR-155)로 보호한다 — 비로그인 접근은 로그인 페이지로 리다이렉트.
+ * 랜딩(`/`)은 공개라 가드를 걸지 않는다.
+ */
+import { WebController } from '../controllers/web-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 관리 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/', WebController.home)
+  router.http.get('/admin/users', WebController.list, guarded)
+  router.http.get('/admin/users/new', WebController.newForm, guarded)
+  router.http.post('/admin/users', WebController.create, guarded)
+  router.http.get('/admin/users/:id/edit', WebController.editForm, guarded)
+  router.http.post('/admin/users/:id', WebController.update, guarded)
+  router.http.post('/admin/users/:id/delete', WebController.destroy, guarded)
+}

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

@@ -0,0 +1,15 @@
+// @ts-check
+/**
+ * apps/main/routes/worker.js — /demo/worker CPU 워커 풀 데모 UI 라우트(자동 로딩, loadRoutes, ADR-157).
+ * `webRequireAuth`(ADR-155)로 보호한다. 실행(run)·하트비트(ping)는 AJAX(JSON) 엔드포인트다.
+ */
+import { WorkerController } from '../controllers/worker-controller.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+
+export default (/** @type {any} */ router) => {
+  /** @type {{ before: Function[] }} 데모 UI 보호 가드(로그인 필요). */
+  const guarded = { before: [webRequireAuth] }
+  router.http.get('/demo/worker', WorkerController.index, guarded)
+  router.http.post('/demo/worker/run', WorkerController.run, guarded)
+  router.http.get('/demo/worker/ping', WorkerController.ping, guarded)
+}

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

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * apps/main/routes/ws.js — /demo/ws 채팅 데모 페이지 + /ws/chat WebSocket 엔드포인트(자동 로딩, ADR-158).
+ *
+ * 페이지(`/demo/ws`)는 webRequireAuth 로, WS upgrade(`/ws/chat`)는 makeWsRequireAuth(세션 직접 확인)로
+ * 보호한다 — 둘 다 로그인 필요. WS 채널 메시지 `chat.send` 의 payload(text)는 schemas 로 사전 검증된다(M2).
+ */
+import { WsController } from '../controllers/ws-controller.js'
+import { ChatChannel } from '../channels/chat-channel.js'
+import { webRequireAuth } from '../middleware/web-auth.js'
+import { makeWsRequireAuth } from '../middleware/ws-auth.js'
+
+/** chat.send payload 스키마 — text 1~500자만 허용(빈 메시지·과대 페이로드 차단). */
+const CHAT_SEND_SCHEMA = {
+  type: 'object',
+  required: ['text'],
+  properties: { text: { type: 'string', minLength: 1, maxLength: 500 } },
+  additionalProperties: false,
+}
+
+export default (/** @type {any} */ router) => {
+  // 데모 셸 페이지(MPA) — 로그인 가드(비로그인은 로그인 페이지로).
+  router.http.get('/demo/ws', WsController.index, { before: [webRequireAuth] })
+
+  // 실 WS 엔드포인트 — upgrade 시 세션 인증(makeWsRequireAuth). ns=/ws/chat 는 ASP E: 로 종단(app.config asp).
+  router.ws('/ws/chat', ChatChannel, {
+    before: [makeWsRequireAuth(router.app)],
+    schemas: { 'chat.send': CHAT_SEND_SCHEMA },
+  })
+}

package/sample/crud/apps/main/schedules/cron-counter-schedule.js

@@ -0,0 +1,30 @@
+// @ts-check
+import { MegaSchedule } from 'mega-framework'
+import { CronDemoService } from '../services/cron-demo-service.js'
+
+/**
+ * CronCounterSchedule — /demo/cron 정기 작업(ADR-028/118). `mega scheduler` 프로세스가 실행한다(config.schedules).
+ *
+ * 30초마다 'demo' 캐시(redis)의 누적 카운터를 1 올리고 실행 이력을 남긴다(CronDemoService.tick). 웹 페이지는
+ * 같은 redis 를 읽어 실행 이력과 다음 실행 시각을 보여준다.
+ *
+ * # 클러스터 중복방지 (leader election)
+ *   같은 스케줄을 scheduler 프로세스 여러 개에 띄우면(ecosystem 의 instances>1) 한 tick 에 양쪽이 동시에
+ *   카운터를 올려 **중복 실행**된다. `static lock` 을 선언하면 MegaScheduler 가 실행 직전 분산 락(redlock)을
+ *   딱 1개만 잡게 해(retryCount:0 — 못 잡으면 즉시 skip), tick 당 한 인스턴스만 실행한다(ADR-118/113).
+ *   ttl(ms)은 tick(원자적 INCR, 수 ms) 소요보다 넉넉하면서 다음 주기(30초)보다는 짧게 둬, 락 해제가 실패해도
+ *   다음 주기엔 자동 만료돼 재경쟁한다.
+ */
+export class CronCounterSchedule extends MegaSchedule {
+  static cron = CronDemoService.CRON_EXPR
+  static timezone = CronDemoService.TIMEZONE
+  static lock = { lock: 'main', ttl: 20_000 }
+
+  /**
+   * @param {Record<string, any>} ctx - scheduler 프로세스 컨텍스트(ctx.cache('demo') 글로벌 키).
+   * @returns {Promise<void>}
+   */
+  async run(ctx) {
+    await new CronDemoService(ctx).tick('schedule')
+  }
+}

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

@@ -0,0 +1,74 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { MegaHash } from 'mega-framework'
+import { MegaValidationError, MegaConflictError } from 'mega-framework/errors'
+import { User } from '../models/user.js'
+
+/**
+ * AuthService — 회원가입·로그인 검증 로직(ADR-155). 파일명 `auth-service.js` → 자동 DI 이름 `auth`
+ * (ctx.services.auth, ADR-148). 비밀번호는 scrypt(MegaHash, ADR-130)로 해시해 저장하고, 검증은 상수
+ * 시간 비교로 한다 — 평문은 어디에도 저장·로그하지 않는다.
+ *
+ * brute-force(반복 시도 잠금)는 이 서비스가 아니라 컨트롤러가 `ctx.bruteForce`(redis, ADR-049/130)로
+ * 다룬다 — 잠금은 HTTP 요청(IP)·세션 흐름에 묶여 있어 컨트롤러 책임이기 때문이다.
+ */
+export class AuthService extends MegaService {
+  /** 비밀번호 최소 길이(OWASP Password Storage Cheat Sheet — 최소 8자 권장). */
+  static MIN_PASSWORD = 8
+
+  /**
+   * 새 계정을 만든다. name·email·password 를 검증하고 비밀번호를 해시해 저장한다.
+   * @param {{ name?: unknown, email?: unknown, password?: unknown }} input
+   * @returns {Promise<{ id: number, name: string, email: string, created_at: string }>}
+   * @throws {MegaValidationError} `auth.invalid` - 필수값 누락 또는 비밀번호가 너무 짧음.
+   * @throws {MegaConflictError} `user.email_taken` - 이메일 중복.
+   */
+  async register(input) {
+    const name = typeof input?.name === 'string' ? input.name.trim() : ''
+    const email = typeof input?.email === 'string' ? input.email.trim().toLowerCase() : ''
+    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 } })
+    }
+    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 } })
+    }
+    const passwordHash = await MegaHash.password.hash(password)
+    this.log.debug?.({ email }, 'auth.register')
+    try {
+      return await User.register({ name, email, passwordHash })
+    } 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
+    }
+  }
+
+  /**
+   * 이메일+비밀번호를 검증한다. 일치하면 마지막 로그인 시각을 갱신하고 사용자 식별 정보를 돌려준다.
+   * 실패(없는 이메일·비밀번호 미설정 계정·불일치)는 **이유를 구분하지 않고** null 을 돌려준다
+   * (user enumeration 방지 — 어느 쪽이 틀렸는지 노출하지 않는다, OWASP Authentication Cheat Sheet).
+   * @param {{ email?: unknown, password?: unknown }} input
+   * @returns {Promise<{ id: number, name: string } | null>}
+   */
+  async authenticate(input) {
+    const email = typeof input?.email === 'string' ? input.email.trim().toLowerCase() : ''
+    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 (row === null || typeof row.password_hash !== 'string') {
+      // 없는 이메일이거나 비밀번호 미설정(admin CRUD 로 만든 계정) — 둘 다 로그인 불가.
+      return null
+    }
+    const ok = await MegaHash.password.verify(password, row.password_hash)
+    if (!ok) {
+      this.log.debug?.({ email }, 'auth.authenticate mismatch')
+      return null
+    }
+    await User.touchLastLogin(row.id)
+    return { id: row.id, name: row.name }
+  }
+}

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

@@ -0,0 +1,66 @@
+// @ts-check
+import { MegaService, MegaCron } from 'mega-framework'
+
+/**
+ * CronDemoService — /demo/cron 스케줄러 데모 로직(ADR-028/118). 파일명 `cron-demo-service.js` → 자동 DI
+ * 이름 `cronDemo`(ctx.services.cronDemo, ADR-148).
+ *
+ * `CronCounterSchedule`(mega scheduler 프로세스)과 웹 수동 실행 버튼(mega start 프로세스)이 **같은 tick()
+ * 로직**을 공유한다 — 둘 다 'demo' 캐시(redis db1)에 원자적 카운터(INCR)를 올리고 최근 실행 이력을 redis
+ * LIST(LPUSH + LTRIM)에 남긴다. 두 프로세스가 같은 redis 를 보므로 스케줄 자동 실행과 수동 실행이 한 화면에
+ * 함께 쌓인다. 다음 실행 시각은 croner 래퍼(MegaCron)로 계산한다(타이머 없는 순수 계산).
+ *
+ * 키는 'demo' 캐시 안에서 `demo:cron:*` 네임스페이스로 두어 /demo/redis 의 `demo:redis:*` 와 분리한다.
+ */
+export class CronDemoService extends MegaService {
+  /** cron 표현식(6필드 = 초 분 시 일 월 요일) — 30초마다. CronCounterSchedule 과 공유하는 정본. */
+  static CRON_EXPR = '*/30 * * * * *'
+  /** IANA 타임존 — 다음 실행 시각 계산·표시에 쓴다. */
+  static TIMEZONE = 'Asia/Seoul'
+  /** 누적 실행 카운터 키(원자적 INCR). */
+  static COUNT_KEY = 'demo:cron:count'
+  /** 최근 실행 이력 LIST 키(LPUSH 머리쪽 삽입 → 최신이 앞). */
+  static HISTORY_KEY = 'demo:cron:history'
+  /** 이력 보관 최대 건수(LTRIM 으로 유지). */
+  static HISTORY_MAX = 10
+
+  /**
+   * 실행 1회 기록 — 누적 카운터를 원자적으로 1 올리고, 실행 이력 1건을 LIST 머리에 넣은 뒤 최근 N건만 남긴다.
+   * 스케줄 자동 실행(source='schedule')과 웹 수동 실행(source='manual')이 같은 경로를 쓴다.
+   * @param {'schedule'|'manual'} source - 실행 출처(이력에 함께 저장 — 화면에서 구분 표시).
+   * @returns {Promise<{ count: number, at: string, source: 'schedule'|'manual' }>}
+   */
+  async tick(source) {
+    const redis = this.ctx.cache('demo').native
+    const count = await redis.incr(CronDemoService.COUNT_KEY)
+    const at = new Date().toISOString()
+    await redis.lpush(CronDemoService.HISTORY_KEY, JSON.stringify({ at, count, source }))
+    // 머리쪽(0)부터 N-1 까지만 남기고 나머지(오래된 꼬리)는 버린다 — 무한 적재 방지.
+    await redis.ltrim(CronDemoService.HISTORY_KEY, 0, CronDemoService.HISTORY_MAX - 1)
+    this.ctx.log?.debug?.({ count, source }, 'cron-demo.tick')
+    return { count, at, source }
+  }
+
+  /**
+   * 화면 렌더용 스냅샷 — 누적 카운터 + 최근 실행 이력(최신순) + 다음 실행 시각 N개.
+   * @returns {Promise<{ count: number, history: Array<{ at: string, count: number, source: string }>, nextRuns: Date[], cron: string, timezone: string }>}
+   */
+  async snapshot() {
+    const redis = this.ctx.cache('demo').native
+    const rawCount = await redis.get(CronDemoService.COUNT_KEY)
+    const count = rawCount === null || rawCount === undefined ? 0 : Number(rawCount)
+    const rawList = await redis.lrange(CronDemoService.HISTORY_KEY, 0, CronDemoService.HISTORY_MAX - 1)
+    const history = rawList.map((/** @type {string} */ s) => JSON.parse(s))
+    // 다음 5개 발생 시각(타이머 미가동 순수 계산). 표현식이 무효면 register 단계에서 이미 throw 됐을 것.
+    const nextRuns = MegaCron.nextRuns(CronDemoService.CRON_EXPR, 5, undefined, {
+      timezone: CronDemoService.TIMEZONE,
+    })
+    return {
+      count,
+      history,
+      nextRuns,
+      cron: CronDemoService.CRON_EXPR,
+      timezone: CronDemoService.TIMEZONE,
+    }
+  }
+}