mega-framework 0.1.0

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

@@ -0,0 +1,145 @@
+// @ts-check
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Marked } from 'marked'
+import hljs from 'highlight.js'
+import { MegaService } from 'mega-framework'
+import { MegaNotFoundError } from 'mega-framework/errors'
+
+/**
+ * GuideService — /guide 가이드 뷰어 로직(서버사이드 마크다운 렌더). 파일명 `guide-service.js` → 자동 DI
+ * 이름 `guide`(ctx.services.guide, ADR-148). 레포 루트의 `docs/guide/*.md` 를 읽어,
+ *
+ *   1) **목록** — 디렉토리를 scan 해 각 파일의 첫 H1 을 제목으로 뽑는다(인덱스 카드용).
+ *   2) **단일 페이지** — 마크다운을 marked 로 HTML 화하고, 코드블록은 highlight.js 로 미리 하이라이트한다.
+ *      브라우저 JS 를 추가하지 않으려 렌더를 전부 서버에서 끝낸다(CSP script-src 'self' 호환).
+ *
+ * 가이드 파일은 정적이라 목록은 프로세스 단위로 캐시한다(개발 중 변경은 재시작으로 갱신).
+ */
+
+/** 가이드 마크다운 디렉토리 — 레포 루트의 docs/guide(이 파일 기준 5단계 위). */
+const GUIDE_DIR = fileURLToPath(new URL('../../../../../docs/guide/', import.meta.url))
+
+/** 유효 slug 형식 — 소문자·숫자·하이픈만(경로 조작 차단의 1차 게이트). */
+const SLUG_RE = /^[a-z0-9-]+$/
+
+/**
+ * GitHub 호환 헤더 슬러그에서 제거할 문자 집합.
+ * 출처: github-slugger(https://github.com/Flet/github-slugger) — 구두점을 지우고 공백을 하이픈으로 바꾸며
+ * 유니코드(한글 포함)는 보존한다. docs/guide 의 목차 앵커(`#mega-g--generate` 등)가 이 규칙으로 만들어져 있어
+ * 같은 규칙으로 헤딩 id 를 달아야 페이지 내 목차 링크가 동작한다.
+ */
+const SLUG_STRIP = /[ -⸀-⹿\\'!"#$%&()*+,./:;<=>?@[\]^`{|}~’]/g
+
+/** 목록 캐시(프로세스 단위). 가이드 파일은 정적이므로 1회 scan 후 재사용. */
+let listCache = null
+
+/**
+ * 마크다운 첫 H1 을 제목으로 뽑는다. 없으면 null.
+ * @param {string} md
+ * @returns {string | null}
+ */
+function parseTitle(md) {
+  const m = md.match(/^#\s+(.+?)\s*$/m)
+  return m ? m[1].trim() : null
+}
+
+/** HTML 특수문자 이스케이프(하이라이터를 안 거치는 코드블록 fallback 용). @param {string} s @returns {string} */
+function escapeHtml(s) {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/**
+ * 헤딩 id 생성기 — github-slugger 와 같은 규칙. 같은 문서 내 중복 slug 에는 `-1`, `-2` … 를 붙여 유일화한다.
+ * (예: 명령마다 반복되는 `### 시그니처`.) 페이지마다 새로 만들어 카운터를 격리한다.
+ * @returns {(raw: string) => string}
+ */
+function makeSlugger() {
+  /** @type {Record<string, number>} base slug → 지금까지 본 횟수. */
+  const occurrences = Object.create(null)
+  return (raw) => {
+    const base = raw.toLowerCase().replace(SLUG_STRIP, '').replace(/ /g, '-')
+    let result = base
+    while (occurrences[result] !== undefined) {
+      occurrences[base] = (occurrences[base] ?? 0) + 1
+      result = `${base}-${occurrences[base]}`
+    }
+    occurrences[result] = 0
+    return result
+  }
+}
+
+/**
+ * 가이드 1페이지 전용 marked 인스턴스. 코드블록은 highlight.js 로 미리 하이라이트하고, 헤딩에는 목차 앵커용
+ * id 를 단다. 지원하지 않는 언어(ejs 등)는 하이라이트 없이 이스케이프만 한다(코드가 깨지지 않게).
+ * @returns {Marked}
+ */
+function createMarked() {
+  const slugger = makeSlugger()
+  const m = new Marked({ gfm: true, breaks: true })
+  m.use({
+    renderer: {
+      /** @this {any} @param {{ text: string, lang?: string }} token */
+      code({ text, lang }) {
+        const language = lang && hljs.getLanguage(lang) ? lang : null
+        const body = language ? hljs.highlight(text, { language }).value : escapeHtml(text)
+        const cls = language ? ` language-${language}` : ''
+        return `<pre><code class="hljs${cls}">${body}</code></pre>\n`
+      },
+      /** @this {any} @param {{ tokens: any[], depth: number, text: string }} token */
+      heading({ tokens, depth, text }) {
+        const inner = this.parser.parseInline(tokens)
+        const id = slugger(text)
+        return `<h${depth} id="${id}">${inner}</h${depth}>\n`
+      },
+    },
+  })
+  return m
+}
+
+export class GuideService extends MegaService {
+  /**
+   * docs/guide 의 모든 가이드를 slug·title 로 나열한다(파일명 오름차순 = 가이드 번호순). 프로세스 단위 캐시.
+   * @returns {Promise<Array<{ slug: string, title: string }>>}
+   */
+  async listGuides() {
+    if (listCache) return listCache
+    const files = (await readdir(GUIDE_DIR)).filter((f) => f.endsWith('.md')).sort()
+    const guides = []
+    for (const file of files) {
+      const slug = file.slice(0, -3)
+      if (!SLUG_RE.test(slug)) continue
+      const content = await readFile(join(GUIDE_DIR, file), 'utf8')
+      guides.push({ slug, title: parseTitle(content) ?? slug })
+    }
+    this.ctx.log?.debug?.({ count: guides.length }, 'guide.list')
+    listCache = guides
+    return guides
+  }
+
+  /**
+   * 단일 가이드를 HTML 로 렌더한다. slug 는 목록에 실제로 존재하는 것만 허용한다(화이트리스트 — 경로 조작 차단).
+   * @param {string} slug
+   * @returns {Promise<{ slug: string, title: string, html: string }>}
+   * @throws {MegaNotFoundError} slug 가 형식에 안 맞거나 목록에 없을 때.
+   */
+  async renderGuide(slug) {
+    if (!SLUG_RE.test(slug)) {
+      throw new MegaNotFoundError('guide.not_found', `Guide '${slug}' not found.`)
+    }
+    const guides = await this.listGuides()
+    const found = guides.find((g) => g.slug === slug)
+    if (!found) {
+      throw new MegaNotFoundError('guide.not_found', `Guide '${slug}' not found.`)
+    }
+    const md = await readFile(join(GUIDE_DIR, `${slug}.md`), 'utf8')
+    const html = String(createMarked().parse(md))
+    this.ctx.log?.debug?.({ slug, bytes: html.length }, 'guide.render')
+    return { slug: found.slug, title: found.title, html }
+  }
+}

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

@@ -0,0 +1,83 @@
+// @ts-check
+import { MegaService, MegaJobQueue } from 'mega-framework'
+import { EmailJob } from '../jobs/email-job.js'
+
+/** JetStream NOT_FOUND API 에러 코드(스트림/메시지 없음) — mega-job-queue 의 동일 상수와 정합. */
+const NOT_FOUND_CODE = '404'
+
+/**
+ * EmailJob 의 DLQ 스트림/서브젝트 이름. MegaJobQueue 는 `<subject>.dlq` 로 발행하고 DLQ 스트림을
+ * `<streamPrefix>_<sanitized subject>_DLQ`(streamPrefix 기본 'MEGA_JOBS', subject 의 '.'→'_')로 만든다
+ * (mega-job-queue `#dlqStreamName`/`#routeToDlq` 정본). 웹은 이 스트림을 직접 읽어 격리된 잡을 보여준다.
+ */
+const DLQ_SUBJECT = `${EmailJob.subject}.dlq`
+const DLQ_STREAM = `MEGA_JOBS_${EmailJob.subject.replace(/[^A-Za-z0-9_-]/g, '_')}_DLQ`
+
+/**
+ * JobsDemoService — /demo/jobs 잡 큐 데모 로직(ADR-028/119). 파일명 `jobs-demo-service.js` → 자동 DI 이름
+ * `jobsDemo`(ctx.services.jobsDemo, ADR-148).
+ *
+ * producer 측(웹 mega start 프로세스)에서 EmailJob 을 NATS JetStream 에 enqueue 한다 — nc 는 `ctx.bus('jobs')`
+ * 어댑터의 raw 핸들(`.native`, ADR-009)로 풀고, MegaJobQueue 가 워크 스트림 발행을 담당한다. 소비·재시도·DLQ
+ * 라우팅은 `mega worker` 프로세스의 EmailJob.run 이 처리하며, 양쪽이 같은 'demo' 캐시(redis)·같은 NATS 스트림을
+ * 보므로 enqueue 결과·처리 이벤트·DLQ 격리분이 한 화면에 함께 보인다.
+ */
+export class JobsDemoService extends MegaService {
+  /**
+   * EmailJob 1건을 큐에 넣는다(JetStream publish — 서버에 영속 저장 후 워커가 가져감).
+   * @param {{ id: string, to: string, subject?: string, mode: 'ok'|'flaky'|'fail' }} payload
+   * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   */
+  async enqueue(payload) {
+    const nc = this.ctx.bus('jobs').native
+    const queue = new MegaJobQueue({ nc })
+    const ack = await queue.enqueue(EmailJob, payload)
+    this.ctx.log?.debug?.({ id: payload.id, mode: payload.mode, seq: ack.seq }, 'jobs-demo.enqueue')
+    return ack
+  }
+
+  /**
+   * 최근 처리 이벤트(최신순) — 워커가 EmailJob.run 에서 남긴 시도/성공/실패 타임라인.
+   * @returns {Promise<Array<{ id: string, to: string, mode: string, attempt: number, status: string, at: string }>>}
+   */
+  async events() {
+    const redis = this.ctx.cache('demo').native
+    const raw = await redis.lrange(EmailJob.EVENTS_KEY, 0, EmailJob.EVENTS_MAX - 1)
+    return raw.map((/** @type {string} */ s) => JSON.parse(s))
+  }
+
+  /**
+   * DLQ(Dead Letter Queue) 상태 — 영구 실패해 격리된 잡 수 + 가장 최근 1건. DLQ 스트림이 아직 없으면
+   * (DLQ 로 간 잡이 한 번도 없으면) 빈 상태를 돌려준다.
+   * @returns {Promise<{ count: number, latest: { failedAt: string, deliveryCount: number, error: string, payload: any } | null }>}
+   */
+  async dlq() {
+    const nc = this.ctx.bus('jobs').native
+    const jsm = await nc.jetstreamManager()
+    let count = 0
+    try {
+      const info = await jsm.streams.info(DLQ_STREAM)
+      count = info.state.messages
+    } catch (e) {
+      // 스트림 미존재(404)는 "DLQ 로 간 잡이 아직 없음" — 빈 상태로 본다. 그 외(연결 장애 등)는 전파.
+      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
+      return { count: 0, latest: null }
+    }
+    if (count === 0) return { count, latest: null }
+    let latest = null
+    try {
+      const msg = await jsm.streams.getMessage(DLQ_STREAM, { last_by_subj: DLQ_SUBJECT })
+      const body = /** @type {any} */ (msg.json())
+      latest = {
+        failedAt: body.failedAt,
+        deliveryCount: body.deliveryCount,
+        error: body.error?.message ?? String(body.error ?? ''),
+        payload: body.payload,
+      }
+    } catch (e) {
+      // 카운트는 있으나 마지막 메시지 조회가 404(경쟁 삭제 등)면 latest 없이 카운트만 보여준다. 그 외는 전파.
+      if (/** @type {any} */ (e)?.code !== NOT_FOUND_CODE) throw e
+    }
+    return { count, latest }
+  }
+}

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

@@ -0,0 +1,59 @@
+// @ts-check
+import { MegaService, MegaTracing } from 'mega-framework'
+
+/**
+ * LogsDemoService — /demo/logs 구조적 로깅 데모 로직(ADR-023/141/163). 파일명 `logs-demo-service.js` →
+ * 자동 DI 이름 `logsDemo`(ctx.services.logsDemo, ADR-148).
+ *
+ * `ctx.log`(요청별 pino child, reqId 바인딩)로 실제 로그를 emit 한다 — console sink 로 나가며, redact 설정이
+ * `password`/`token`/`secret` 을 `[Redacted]` 로 마스킹하고, trace_id mixin 이 활성 span 의 trace_id 를 자동
+ * 첨부한다(ADR-141). 브라우저는 console 출력을 볼 수 없으므로, emit 한 로그의 **안전한 메타데이터만**(level/msg/
+ * trace_id/reqId/at — 시크릿 제외) redis LIST 에 남겨 화면에서 emit·trace 상관을 확인하게 한다. 키는 'demo'
+ * 캐시 안 `demo:logs:*` 네임스페이스다. 실제 마스킹·구조적 NDJSON 은 서버 콘솔에서 확인한다.
+ */
+export class LogsDemoService extends MegaService {
+  /** 최근 emit 메타 LIST 키. */
+  static RECENT_KEY = 'demo:logs:recent'
+  /** 이력 보관 최대 건수(LTRIM 유지). */
+  static RECENT_MAX = 20
+  /** emit 허용 레벨 화이트리스트(임의 메서드 호출 방지). */
+  static LEVELS = ['debug', 'info', 'warn', 'error']
+
+  /**
+   * 한 건의 로그를 실제 pino logger 로 emit 하고, 안전 메타데이터를 redis 이력에 남긴다. payload 엔
+   * 시연용 민감필드(token/password)를 일부러 넣어 console 에서 마스킹을 확인하게 한다 — 단 redis 이력엔
+   * 시크릿을 저장하지 않는다.
+   * @param {string} level - 'debug'|'info'|'warn'|'error'(화이트리스트). 그 외는 'info' 폴백.
+   * @param {string} message - 사용자 입력 메시지(표시·로그 msg).
+   * @returns {Promise<{ level: string, message: string, traceId: string|null, at: string }>}
+   */
+  async emit(level, message) {
+    const lvl = LogsDemoService.LEVELS.includes(level) ? level : 'info'
+    const msg = typeof message === 'string' && message.trim().length > 0 ? message.trim() : 'demo log line'
+    const ids = MegaTracing.currentTraceIds()
+
+    // 실제 emit — 민감필드(demo.token/demo.password)는 redact 가 console 출력에서 [Redacted] 로 가린다(ADR-141).
+    this.ctx.log?.[lvl]?.(
+      { demo: { token: 'demo-token-abc123', password: 'p@ssw0rd' }, sample: true, kind: 'logs-demo' },
+      msg,
+    )
+
+    // 화면 표시용 안전 메타데이터(시크릿 제외)만 redis 이력에 보관.
+    const redis = this.ctx.cache('demo').native
+    const record = { level: lvl, message: msg, traceId: ids?.traceId ?? null, reqId: this.ctx.requestId ?? null, at: new Date().toISOString() }
+    await redis.lpush(LogsDemoService.RECENT_KEY, JSON.stringify(record))
+    await redis.ltrim(LogsDemoService.RECENT_KEY, 0, LogsDemoService.RECENT_MAX - 1)
+    return { level: lvl, message: msg, traceId: ids?.traceId ?? null, at: record.at }
+  }
+
+  /**
+   * 화면 렌더용 스냅샷 — 최근 emit 메타 목록 + 허용 레벨.
+   * @returns {Promise<{ recent: Array<{ level: string, message: string, traceId: string|null, reqId: string|null, at: string }>, levels: string[] }>}
+   */
+  async snapshot() {
+    const redis = this.ctx.cache('demo').native
+    const rawList = await redis.lrange(LogsDemoService.RECENT_KEY, 0, LogsDemoService.RECENT_MAX - 1)
+    const recent = rawList.map((/** @type {string} */ s) => JSON.parse(s))
+    return { recent, levels: LogsDemoService.LEVELS }
+  }
+}

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

@@ -0,0 +1,144 @@
+// @ts-check
+import { MegaService, collectCluster } from 'mega-framework'
+
+/**
+ * MetricsDemoService — /demo/metrics 관측 데모 로직(ADR-131/132/154/163). 파일명 `metrics-demo-service.js` →
+ * 자동 DI 이름 `metricsDemo`(ctx.services.metricsDemo, ADR-148).
+ *
+ * 프레임워크 Prometheus 메트릭을 `collectCluster()`로 읽어 사람이 보기 좋은 숫자로 요약한다. raw `/metrics`
+ * 는 기계용(scrape)이라, 같은 데이터를 카드용으로 한 번 정리하는 게 데모의 목적이다. **클러스터 모드면
+ * `collectCluster` 가 마스터 IPC 로 전 워커 메트릭을 합산해 돌려준다(ADR-163)** — 단일 프로세스면 로컬과
+ * 동일. 덕분에 새로고침마다 다른 워커 숫자가 나오던 문제가 사라지고 클러스터 전체 누적이 일관되게 보인다.
+ *
+ * Prometheus exposition format(text/plain version=0.0.4)은 한 줄이 `name{labels} value` 다(주석은 `#` 시작).
+ * 이 포맷은 안정된 표준이라 curated 한 몇 개 메트릭 패밀리만 파싱해 합산/추출한다.
+ */
+export class MetricsDemoService extends MegaService {
+  /** 라우트 카운트 카드에 보여줄 상위 라우트 개수. */
+  static TOP_ROUTES = 6
+
+  /**
+   * 한 줄(`name{a="1",b="2"} 3.5`)을 `{ name, labels, value }` 로 파싱한다. 주석/빈 줄/형식 불일치는 null.
+   * @param {string} line
+   * @returns {{ name: string, labels: Record<string,string>, value: number } | null}
+   */
+  static parseLine(line) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0 || trimmed.startsWith('#')) return null
+    const m = trimmed.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)(\{[^}]*\})?\s+([0-9eE.+-]+)$/)
+    if (!m) return null
+    const value = Number(m[3])
+    if (!Number.isFinite(value)) return null
+    /** @type {Record<string,string>} */
+    const labels = {}
+    if (m[2]) {
+      // {method="GET",route="/x"} → 각 key="value" 추출(값 안의 이스케이프 따옴표 허용).
+      const re = /([a-zA-Z_][a-zA-Z0-9_]*)="((?:[^"\\]|\\.)*)"/g
+      let lm
+      while ((lm = re.exec(m[2])) !== null) labels[lm[1]] = lm[2].replace(/\\"/g, '"')
+    }
+    return { name: m[1], labels, value }
+  }
+
+  /**
+   * exposition 텍스트를 파싱된 샘플 배열로 변환한다.
+   * @param {string} text
+   * @returns {Array<{ name: string, labels: Record<string,string>, value: number }>}
+   */
+  static parse(text) {
+    /** @type {Array<{ name: string, labels: Record<string,string>, value: number }>} */
+    const samples = []
+    for (const line of text.split('\n')) {
+      const parsed = MetricsDemoService.parseLine(line)
+      if (parsed) samples.push(parsed)
+    }
+    return samples
+  }
+
+  /**
+   * 메트릭 패밀리(name)의 모든 label 조합 값을 합산한다(필터 옵션).
+   * @param {Array<{ name: string, labels: Record<string,string>, value: number }>} samples
+   * @param {string} name
+   * @param {(labels: Record<string,string>) => boolean} [filter]
+   * @returns {number}
+   */
+  static sum(samples, name, filter) {
+    let total = 0
+    for (const s of samples) {
+      if (s.name !== name) continue
+      if (filter && !filter(s.labels)) continue
+      total += s.value
+    }
+    return total
+  }
+
+  /**
+   * 화면 렌더용 스냅샷 — HTTP/잡/WS/process 핵심 카운터를 사람 친화 숫자로 정리한다. 메트릭 OFF 면
+   * `enabled:false`(collect() 가 빈 문자열) 로 알린다.
+   * @returns {Promise<{
+   *   enabled: boolean,
+   *   metricsPath: string,
+   *   http: { total: number, byClass: Record<string,number>, topRoutes: Array<{ route: string, count: number }> },
+   *   jobs: Record<string, number>,
+   *   ws: { total: number, byType: Array<{ type: string, count: number }> },
+   *   process: { heapUsedMb: number, rssMb: number, uptimeSec: number, cpuSec: number },
+   * }>}
+   */
+  async snapshot() {
+    const text = await collectCluster()
+    this.ctx.log?.debug?.({ enabled: text.length > 0, bytes: text.length }, 'metrics-demo.collect')
+    const samples = MetricsDemoService.parse(text)
+    const S = MetricsDemoService
+
+    // HTTP — 총 요청 수 + 상태 클래스(2xx/3xx/4xx/5xx) + 라우트별 상위.
+    const httpName = 'mega_http_requests_total'
+    /** @type {Record<string,number>} */
+    const byClass = { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0 }
+    /** @type {Record<string,number>} */
+    const routeCounts = {}
+    for (const s of samples) {
+      if (s.name !== httpName) continue
+      const cls = `${String(s.labels.status_code ?? '0')[0]}xx`
+      if (cls in byClass) byClass[cls] += s.value
+      const route = s.labels.route ?? '(unknown)'
+      routeCounts[route] = (routeCounts[route] ?? 0) + s.value
+    }
+    const topRoutes = Object.entries(routeCounts)
+      .map(([route, count]) => ({ route, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, S.TOP_ROUTES)
+
+    // 잡 — event(enqueued/processed/retried/dlq)별 합산(Step 2.1d 잡 큐와 연동).
+    const jobsName = 'mega_jobs_total'
+    /** @type {Record<string,number>} */
+    const jobs = { enqueued: 0, processed: 0, retried: 0, dlq: 0 }
+    for (const e of Object.keys(jobs)) jobs[e] = S.sum(samples, jobsName, (l) => l.event === e)
+
+    // WS — 총 메시지 수 + type 별(Step 2.1c 채팅과 연동).
+    const wsName = 'mega_ws_messages_total'
+    /** @type {Record<string,number>} */
+    const wsTypeCounts = {}
+    for (const s of samples) {
+      if (s.name !== wsName) continue
+      const type = s.labels.type ?? '(unknown)'
+      wsTypeCounts[type] = (wsTypeCounts[type] ?? 0) + s.value
+    }
+    const wsByType = Object.entries(wsTypeCounts)
+      .map(([type, count]) => ({ type, count }))
+      .sort((a, b) => b.count - a.count)
+
+    return {
+      enabled: text.length > 0,
+      metricsPath: '/metrics',
+      http: { total: S.sum(samples, httpName), byClass, topRoutes },
+      jobs,
+      ws: { total: S.sum(samples, wsName), byType: wsByType },
+      process: {
+        heapUsedMb: S.sum(samples, 'mega_process_memory_bytes', (l) => l.kind === 'heapUsed') / 1024 / 1024,
+        rssMb: S.sum(samples, 'mega_process_memory_bytes', (l) => l.kind === 'rss') / 1024 / 1024,
+        uptimeSec: S.sum(samples, 'mega_process_uptime_seconds'),
+        cpuSec: S.sum(samples, 'mega_process_cpu_seconds_total'),
+      },
+    }
+  }
+}

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

@@ -0,0 +1,75 @@
+// @ts-check
+import { MegaService } from 'mega-framework'
+import { MegaNotFoundError, MegaValidationError } from 'mega-framework/errors'
+import { Note } from '../models/note.js'
+
+/**
+ * NoteService — note 도메인 비즈니스 로직(ADR-022). 컨트롤러는 모델을 직접 만지지 않고 이 서비스를 거친다.
+ * 파일명 `note-service.js` → 자동 DI 이름 `note`(ctx.services.note, ADR-148). 모델 import 는 서비스에서만 허용.
+ *
+ * mongo 백엔드라 unique 제약/충돌 매핑(postgres 23505)은 없다 — notes 데모는 제목·본문 검증만 한다.
+ */
+export class NoteService extends MegaService {
+  /** 제목 최대 길이(과도한 입력 방어 — UI 카드 가독성 기준). */
+  static MAX_TITLE = 120
+
+  /** @returns {Promise<object[]>} */
+  async list() {
+    this.log.debug?.('note.list')
+    return Note.list()
+  }
+
+  /** @param {string} id @returns {Promise<object>} @throws {MegaNotFoundError} */
+  async get(id) {
+    const note = await Note.findById(String(id))
+    if (!note) throw new MegaNotFoundError('note.not_found', `Note ${id} not found`, { details: { id } })
+    return note
+  }
+
+  /**
+   * 생성 — 제목은 필수(공백 trim 후 비면 거부), 본문은 선택(빈 문자열 허용).
+   * @param {{ title?: unknown, body?: unknown }} input @returns {Promise<object>}
+   * @throws {MegaValidationError} `note.invalid` - 제목 누락 또는 길이 초과.
+   */
+  async create(input) {
+    const { title, body } = NoteService.#normalize(input)
+    this.log.debug?.({ title }, 'note.create')
+    return Note.create({ title, body })
+  }
+
+  /**
+   * 수정 — 검증 후 변경. 대상이 없으면 404.
+   * @param {string} id @param {{ title?: unknown, body?: unknown }} patch @returns {Promise<object>}
+   * @throws {MegaNotFoundError} @throws {MegaValidationError}
+   */
+  async update(id, patch) {
+    const { title, body } = NoteService.#normalize(patch)
+    const updated = await Note.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))
+    if (!ok) throw new MegaNotFoundError('note.not_found', `Note ${id} not found`, { details: { id } })
+    return { deleted: true }
+  }
+
+  /**
+   * 입력 정규화·검증. 제목은 trim 후 필수·길이 제한, 본문은 trim 후 선택.
+   * @param {{ title?: unknown, body?: unknown }} input @returns {{ title: string, body: string }}
+   * @throws {MegaValidationError} `note.invalid`
+   */
+  static #normalize(input) {
+    const title = typeof input?.title === 'string' ? input.title.trim() : ''
+    const body = typeof input?.body === 'string' ? input.body.trim() : ''
+    if (!title) {
+      throw new MegaValidationError('note.invalid', 'title is required', { details: { title: false } })
+    }
+    if (title.length > NoteService.MAX_TITLE) {
+      throw new MegaValidationError('note.invalid', `title must be at most ${NoteService.MAX_TITLE} characters`, { details: { title: false } })
+    }
+    return { title, body }
+  }
+}