mega-framework 0.1.3 → 0.1.5

package/sample/crud/test/apps/main/chat-channel.test.js

@@ -1,149 +0,0 @@
-// @ts-check
-/**
- * ChatChannel 단위 테스트(ADR-158/176) — 라이프사이클 훅이 **프레임워크 presence/broadcast API**
- * (ctx.presence.join/list/broadcast)와 history redis(KV)를 올바르게 호출하는지 mock 으로 검증.
- * 인프라 불필요(presence·redis native 는 spy). redis pub/sub·roster HASH 직접 호출은 더 이상 없다 —
- * 클러스터 전파·접속자목록 동기화는 프레임워크(wsCluster, NATS)가 처리한다.
- */
-import { describe, test, expect, vi, beforeEach } from 'vitest'
-import { ChatChannel } from '../../../apps/main/channels/chat-channel.js'
-
-/** native redis spy — history 리스트(전파/roster 아님, 단순 기록 KV). @param {object} [o] */
-function fakeNative({ history = [] } = {}) {
-  return {
-    rpush: vi.fn(async () => 1),
-    ltrim: vi.fn(async () => 'OK'),
-    expire: vi.fn(async () => 1),
-    lrange: vi.fn(async () => history),
-  }
-}
-
-/**
- * 채널 ctx mock — auth/presence/cache/log. presence.list 가 클러스터 roster 를 흉내낸다.
- * @param {object} [o]
- */
-function makeCtx({ members = [{ sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } }], history = [], userName = 'kim' } = {}) {
-  const native = fakeNative({ history })
-  const presence = {
-    join: vi.fn(),
-    list: vi.fn(() => members),
-    broadcast: vi.fn(),
-    directToUser: vi.fn(),
-  }
-  return {
-    ctx: {
-      auth: { userId: 'u1', sessionId: 's1', userName },
-      presence,
-      cache: vi.fn(() => ({ native })),
-      log: { warn: vi.fn(), debug: vi.fn(), error: vi.fn() },
-    },
-    native,
-    presence,
-  }
-}
-
-/** sock mock — send spy + id + isOpen. */
-function makeSock() {
-  return { id: 'conn-1', isOpen: true, send: vi.fn(), close: vi.fn() }
-}
-
-beforeEach(() => vi.clearAllMocks())
-
-describe('ChatChannel.onConnect', () => {
-  test('presence.join(자동 roster) + 기록재생 + 입장 broadcast(본인 제외) + chat.history(워커PID)', async () => {
-    const { ctx, presence } = makeCtx({
-      members: [
-        { sessionId: 's0', userId: 'u0', metadata: { userName: 'old' } },
-        { sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } },
-      ],
-      history: [JSON.stringify({ userId: 'u0', userName: 'old', text: 'hi', ts: 1 })],
-    })
-    const sock = makeSock()
-    await new ChatChannel().onConnect(sock, ctx)
-
-    // 신원 매핑 + 자동 roster 등록(프레임워크에 위임).
-    expect(presence.join).toHaveBeenCalledWith({ userId: 'u1', sessionId: 's1', channels: ['chat'], metadata: { userName: 'kim' } })
-
-    // 본인에게: chat.history(me + items + 클러스터 명단 + 워커PID).
-    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
-    expect(hist.payload.me).toEqual({ userId: 'u1', userName: 'kim' })
-    expect(hist.payload.items).toHaveLength(1)
-    expect(hist.payload.online).toBe(2)
-    expect(hist.payload.members).toEqual(['old', 'kim'])
-    expect(hist.payload.workerPid).toBe(process.pid)
-
-    // 전 클러스터에: 입장 presence broadcast(본인 sessionId 제외). NATS fan-out 은 프레임워크 처리.
-    const env = presence.broadcast.mock.calls.at(-1)[0]
-    expect(env).toMatchObject({
-      channel: 'chat',
-      message: { type: 'chat.presence', payload: { event: 'join', userName: 'kim', online: 2 } },
-      exceptSessionIds: ['s1'],
-    })
-  })
-
-  test('redis(history) 없으면 빈 기록으로 연결 유지(close 안 함)', async () => {
-    const presence = { join: vi.fn(), list: vi.fn(() => [{ sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } }]), broadcast: vi.fn() }
-    const ctx = { auth: { userId: 'u1', sessionId: 's1', userName: 'kim' }, presence, cache: vi.fn(() => ({ native: null })), log: { warn: vi.fn(), debug: vi.fn() } }
-    const sock = makeSock()
-    await new ChatChannel().onConnect(sock, ctx)
-    expect(sock.close).not.toHaveBeenCalled()
-    expect(presence.join).toHaveBeenCalled()
-    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
-    expect(hist.payload.items).toEqual([])
-  })
-
-  test('손상된 기록 1건은 건너뛰고 나머지는 재생(debug 로그)', async () => {
-    const { ctx } = makeCtx({ history: ['{bad', JSON.stringify({ userName: 'a', text: 'ok', ts: 2 })] })
-    const sock = makeSock()
-    await new ChatChannel().onConnect(sock, ctx)
-    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
-    expect(hist.payload.items).toHaveLength(1)
-    expect(ctx.log.debug).toHaveBeenCalled()
-  })
-})
-
-describe('ChatChannel.chat.send', () => {
-  test('검증된 text 를 기록 적재 + 전 클러스터 broadcast(본인 포함)', async () => {
-    const { ctx, native, presence } = makeCtx()
-    await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '  hello  ' } }, ctx)
-    expect(native.rpush).toHaveBeenCalled()
-    expect(native.ltrim).toHaveBeenCalledWith('ws:chat:history', -30, -1)
-    const env = presence.broadcast.mock.calls.at(-1)[0]
-    expect(env.message.type).toBe('chat.msg')
-    expect(env.message.payload).toMatchObject({ userId: 'u1', userName: 'kim', text: 'hello' })
-    expect(env.exceptSessionIds).toBeUndefined() // 본인도 echo.
-  })
-
-  test('공백뿐인 메시지는 무시(전파·적재 없음)', async () => {
-    const { ctx, native, presence } = makeCtx()
-    await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '   ' } }, ctx)
-    expect(presence.broadcast).not.toHaveBeenCalled()
-    expect(native.rpush).not.toHaveBeenCalled()
-  })
-})
-
-describe('ChatChannel.onDisconnect', () => {
-  test('퇴장 broadcast(본인 명단 제외) — roster 제거는 프레임워크 자동', async () => {
-    // disconnect 시점에 roster 가 아직 본인을 포함할 수도 있으므로, 채널은 sessionId 로 명시 제외해야 한다.
-    const { ctx, presence } = makeCtx({
-      members: [
-        { sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } },
-        { sessionId: 's2', userId: 'u2', metadata: { userName: 'lee' } },
-      ],
-    })
-    const sock = makeSock()
-    await new ChatChannel().onDisconnect(sock, ctx)
-    const env = presence.broadcast.mock.calls.at(-1)[0]
-    expect(env.message).toMatchObject({ type: 'chat.presence', payload: { event: 'leave', userName: 'kim' } })
-    expect(env.message.payload.members).toEqual(['lee']) // 본인(s1) 제외.
-    expect(env.message.payload.online).toBe(1)
-    expect(env.exceptSessionIds).toEqual(['s1'])
-  })
-
-  test('auth 없으면 전파 없음', async () => {
-    const { ctx, presence } = makeCtx()
-    ctx.auth = null
-    await new ChatChannel().onDisconnect(makeSock(), ctx)
-    expect(presence.broadcast).not.toHaveBeenCalled()
-  })
-})

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

@@ -1,93 +0,0 @@
-// @ts-check
-/**
- * CronDemoService 단위 테스트 — 'demo' 캐시 native(incr/get/lpush/ltrim/lrange)를 가짜로 갈음해 redis 없이
- * 카운터/이력 로직과 다음 실행 시각 계산(MegaCron)을 검증한다. 실 redis 흐름은 통합 검증(E2E)이 커버한다.
- */
-import { describe, test, expect, vi } from 'vitest'
-import { CronDemoService } from '../../../apps/main/services/cron-demo-service.js'
-
-/** incr/get/lpush/ltrim/lrange 를 추적하는 가짜 native + ctx 를 만든다. */
-function makeCtx() {
-  /** @type {Map<string, number>} */
-  const counters = new Map()
-  /** @type {Map<string, string[]>} LIST(머리 삽입). */
-  const lists = new Map()
-  const native = {
-    /** @param {string} k */
-    async incr(k) {
-      const n = (counters.get(k) ?? 0) + 1
-      counters.set(k, n)
-      return n
-    },
-    /** @param {string} k */
-    async get(k) {
-      return counters.has(k) ? String(counters.get(k)) : null
-    },
-    /** @param {string} k @param {string} v */
-    async lpush(k, v) {
-      const arr = lists.get(k) ?? []
-      arr.unshift(v)
-      lists.set(k, arr)
-      return arr.length
-    },
-    ltrim: vi.fn(async (/** @type {string} */ k, /** @type {number} */ _s, /** @type {number} */ stop) => {
-      const arr = lists.get(k) ?? []
-      lists.set(k, arr.slice(0, stop + 1))
-      return 'OK'
-    }),
-    /** @param {string} k @param {number} start @param {number} stop */
-    async lrange(k, start, stop) {
-      return (lists.get(k) ?? []).slice(start, stop + 1)
-    },
-  }
-  const cache = { native }
-  const ctx = { log: { debug() {} }, cache: (/** @type {string} */ a) => (a === 'demo' ? cache : null) }
-  return { ctx, native, counters, lists }
-}
-
-describe('CronDemoService — tick', () => {
-  test('호출마다 카운터가 1씩 증가하고 이력 LIST 머리에 source 와 함께 쌓인다', async () => {
-    const { ctx, native, lists } = makeCtx()
-    const svc = new CronDemoService(/** @type {any} */ (ctx))
-    const first = await svc.tick('schedule')
-    expect(first).toMatchObject({ count: 1, source: 'schedule' })
-    expect(typeof first.at).toBe('string')
-    const second = await svc.tick('manual')
-    expect(second.count).toBe(2)
-    // LTRIM 으로 최근 N건만 유지(매 tick 호출).
-    expect(native.ltrim).toHaveBeenCalledWith(CronDemoService.HISTORY_KEY, 0, CronDemoService.HISTORY_MAX - 1)
-    const stored = (lists.get(CronDemoService.HISTORY_KEY) ?? []).map((s) => JSON.parse(s))
-    // 최신이 머리(앞) — manual 이 먼저.
-    expect(stored[0]).toMatchObject({ count: 2, source: 'manual' })
-    expect(stored[1]).toMatchObject({ count: 1, source: 'schedule' })
-  })
-})
-
-describe('CronDemoService — snapshot', () => {
-  test('누적 카운터 + 최신순 이력 + 다음 실행 시각(미래, 오름차순)을 돌려준다', async () => {
-    const { ctx } = makeCtx()
-    const svc = new CronDemoService(/** @type {any} */ (ctx))
-    await svc.tick('schedule')
-    await svc.tick('schedule')
-    const snap = await svc.snapshot()
-    expect(snap.count).toBe(2)
-    expect(snap.cron).toBe(CronDemoService.CRON_EXPR)
-    expect(snap.timezone).toBe(CronDemoService.TIMEZONE)
-    expect(snap.history).toHaveLength(2)
-    expect(snap.nextRuns.length).toBeGreaterThan(0)
-    // 모두 미래 + 오름차순.
-    const now = Date.now()
-    for (const d of snap.nextRuns) expect(d.getTime()).toBeGreaterThan(now)
-    for (let i = 1; i < snap.nextRuns.length; i++) {
-      expect(snap.nextRuns[i].getTime()).toBeGreaterThan(snap.nextRuns[i - 1].getTime())
-    }
-  })
-
-  test('카운터 미존재(get=null) 시 0 으로 본다', async () => {
-    const { ctx } = makeCtx()
-    const svc = new CronDemoService(/** @type {any} */ (ctx))
-    const snap = await svc.snapshot()
-    expect(snap.count).toBe(0)
-    expect(snap.history).toEqual([])
-  })
-})

package/sample/crud/test/apps/main/demo-flow.integration.test.js

@@ -1,386 +0,0 @@
-// @ts-check
-/**
- * 데모 흐름 통합 테스트(ADR-157) — 실 mongo(notes) + redis(카운터·캐시) + postgres(세션 사용자)로 sample/crud 를
- * 부팅하고 HTTP 전 경로를 검증한다: 비로그인 가드 → 로그인 → notes CRUD(mongo) → redis 방문 카운터·캐시 hit/miss.
- *
- * 인프라(pg·redis·mongo) env 가 없으면 통째로 skip 한다(단위 테스트가 인프라 없이 로직을 커버).
- * 실행에 필요한 env(.env): DATABASE_URL·REDIS_SESSION_URL·REDIS_RATE_URL·REDIS_DEMO_URL·MONGO_URL·SESSION_SECRET.
- */
-import { describe, test, expect, beforeAll, afterAll } from 'vitest'
-import { bootApp, MegaShutdown } from 'mega-framework'
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve } from 'node:path'
-import { existsSync, readFileSync, rmSync } from 'node:fs'
-import { User } from '../../../apps/main/models/user.js'
-import { Note } from '../../../apps/main/models/note.js'
-import { RedisDemoService } from '../../../apps/main/services/redis-demo-service.js'
-
-// 프로젝트 루트(mega.config.js 가 있는 sample/crud) — 이 파일 기준 상위 4단계.
-const PROJECT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
-
-// .env 가 DATABASE_URL 대신 PG_URL 만 줄 수 있으므로(로컬 관례) 매핑한다.
-if (!process.env.DATABASE_URL && process.env.PG_URL) process.env.DATABASE_URL = process.env.PG_URL
-
-const hasInfra = Boolean(
-  process.env.DATABASE_URL &&
-    process.env.REDIS_SESSION_URL &&
-    process.env.REDIS_RATE_URL &&
-    process.env.REDIS_DEMO_URL &&
-    process.env.MONGO_URL &&
-    process.env.SESSION_SECRET,
-)
-const d = hasInfra ? describe : describe.skip
-
-/** set-cookie 를 누적 쿠키 jar 에 반영(maxAge=0 → 삭제). @param {any} res @param {Record<string,string>} jar */
-function applyCookies(res, jar) {
-  const raw = res.headers['set-cookie']
-  const arr = Array.isArray(raw) ? raw : raw ? [raw] : []
-  for (const c of arr) {
-    const pair = String(c).split(';')[0]
-    const eq = pair.indexOf('=')
-    if (eq === -1) continue
-    const name = pair.slice(0, eq).trim()
-    const val = pair.slice(eq + 1).trim()
-    if (val === '') delete jar[name]
-    else jar[name] = val
-  }
-}
-
-/** @param {Record<string,string>} jar @returns {string} Cookie 헤더. */
-function cookieHeader(jar) {
-  return Object.entries(jar).map(([k, v]) => `${k}=${v}`).join('; ')
-}
-
-/** 렌더된 폼 HTML 에서 hidden `_csrf` 토큰을 뽑는다. @param {string} html @returns {string} */
-function csrfFrom(html) {
-  const m = /name="_csrf" value="([^"]+)"/.exec(html)
-  if (!m) throw new Error('csrf token not found in form HTML')
-  return m[1]
-}
-
-/** urlencoded 폼 바디 직렬화. @param {Record<string,string>} fields @returns {string} */
-function form(fields) {
-  return Object.entries(fields).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
-}
-
-/** 업로드 폼의 data-csrf 속성에서 토큰을 뽑는다(multipart 는 헤더로 보냄). @param {string} html @returns {string} */
-function csrfDataFrom(html) {
-  const m = /data-csrf="([^"]+)"/.exec(html)
-  if (!m) throw new Error('data-csrf token not found in upload form HTML')
-  return m[1]
-}
-
-/** N개 파일 multipart/form-data 본문 조립(추가 dep 없이). @param {Array<{ name?: string, filename?: string, contentType?: string, value?: string }>} files @param {string} [boundary] */
-function multipartBody(files, boundary = '----megademo') {
-  const chunks = []
-  for (const f of files) {
-    chunks.push(
-      Buffer.from(
-        `--${boundary}\r\nContent-Disposition: form-data; name="${f.name ?? 'file'}"; filename="${f.filename ?? 'a.bin'}"\r\n` +
-          `Content-Type: ${f.contentType ?? 'application/octet-stream'}\r\n\r\n`,
-        'utf8',
-      ),
-    )
-    chunks.push(Buffer.from(String(f.value ?? ''), 'utf8'))
-    chunks.push(Buffer.from('\r\n', 'utf8'))
-  }
-  chunks.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'))
-  return { body: Buffer.concat(chunks), contentType: `multipart/form-data; boundary=${boundary}` }
-}
-
-d('데모 흐름 E2E — sample/crud 실 mongo+redis+pg (ADR-157)', () => {
-  /** @type {Awaited<ReturnType<typeof bootApp>>} */
-  let boot
-  /** @type {any} */
-  let fastify
-  /** @type {Record<string,string>} 로그인 세션 쿠키 jar. */
-  const jar = {}
-  const EMAIL = `itest-demo-${Date.now()}@example.com`
-  const PASSWORD = 'secret-pass-123'
-  const NAME = 'Demo Tester'
-
-  beforeAll(async () => {
-    MegaShutdown._reset()
-    boot = await bootApp(PROJECT, { listen: false })
-    const app = boot.megaApps.find((a) => a.name === 'main')
-    fastify = app?.fastify
-    await fastify.ready()
-    // 스키마 보장(멱등) + 테스트 계정 정리.
-    await User.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())')
-    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
-    await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
-    await User.query('DELETE FROM users WHERE email = $1', [EMAIL])
-
-    // 회원가입 → 자동 로그인 → 세션 쿠키 확보(가드된 /demo/** 접근에 필요).
-    const regForm = await fastify.inject({ method: 'GET', url: '/register' })
-    applyCookies(regForm, jar)
-    const reg = await fastify.inject({
-      method: 'POST',
-      url: '/register',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(regForm.body), name: NAME, email: EMAIL, password: PASSWORD }),
-    })
-    applyCookies(reg, jar)
-  })
-
-  afterAll(async () => {
-    if (!boot) return
-    await User.query('DELETE FROM users WHERE email = $1', [EMAIL]).catch(() => {})
-    await Note.collection.deleteMany({ title: { $regex: /^itest / } }).catch(() => {})
-    await fastify?.close().catch(() => {})
-    const app = boot.megaApps.find((a) => a.name === 'main')
-    await app?.sessionStore?.disconnect().catch(() => {})
-    await boot.ctx.cache('rate').disconnect().catch(() => {})
-    await boot.ctx.cache('demo').disconnect().catch(() => {})
-    await boot.ctx.db('mongo').disconnect().catch(() => {})
-    await boot.ctx.db('primary').disconnect().catch(() => {})
-    MegaShutdown._reset()
-  })
-
-  test('비로그인: /demo/notes 와 /demo/redis 는 로그인으로 302', async () => {
-    const notes = await fastify.inject({ method: 'GET', url: '/demo/notes' })
-    expect(notes.statusCode).toBe(302)
-    expect(notes.headers.location).toBe('/auth/login')
-    const redis = await fastify.inject({ method: 'GET', url: '/demo/redis' })
-    expect(redis.statusCode).toBe(302)
-    expect(redis.headers.location).toBe('/auth/login')
-  })
-
-  test('notes CRUD (mongo): 생성 → 목록 표시 → 수정 → 삭제', async () => {
-    const TITLE = `itest ${Date.now()}`
-    const EDITED = `${TITLE} (edited)`
-
-    // 신규 폼 GET — CSRF 토큰.
-    const newForm = await fastify.inject({ method: 'GET', url: '/demo/notes/new', headers: { cookie: cookieHeader(jar) } })
-    expect(newForm.statusCode).toBe(200)
-
-    // 생성 POST → 목록으로 302.
-    const created = await fastify.inject({
-      method: 'POST',
-      url: '/demo/notes',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(newForm.body), title: TITLE, body: 'hello mongo' }),
-    })
-    expect(created.statusCode).toBe(302)
-    expect(created.headers.location).toBe('/demo/notes?notice=created')
-
-    // 목록에 방금 만든 제목이 보인다.
-    const list = await fastify.inject({ method: 'GET', url: '/demo/notes', headers: { cookie: cookieHeader(jar) } })
-    expect(list.statusCode).toBe(200)
-    expect(list.body).toContain(TITLE)
-
-    // 방금 만든 노트의 id 를 모델로 직접 찾는다(목록 HTML 파싱 대신 — edit URL 구성용).
-    const all = await Note.list()
-    const mine = /** @type {any} */ (all).find((n) => n.title === TITLE)
-    expect(mine).toBeTruthy()
-
-    // 수정 폼 GET → 수정 POST → 목록으로 302.
-    const editForm = await fastify.inject({ method: 'GET', url: `/demo/notes/${mine.id}/edit`, headers: { cookie: cookieHeader(jar) } })
-    expect(editForm.statusCode).toBe(200)
-    expect(editForm.body).toContain(TITLE)
-    const updated = await fastify.inject({
-      method: 'POST',
-      url: `/demo/notes/${mine.id}`,
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(editForm.body), title: EDITED, body: 'edited body' }),
-    })
-    expect(updated.statusCode).toBe(302)
-    expect(await Note.findById(mine.id)).toMatchObject({ title: EDITED })
-
-    // 삭제 POST → 목록으로 302, 모델에서도 사라진다.
-    const delList = await fastify.inject({ method: 'GET', url: '/demo/notes', headers: { cookie: cookieHeader(jar) } })
-    const del = await fastify.inject({
-      method: 'POST',
-      url: `/demo/notes/${mine.id}/delete`,
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(delList.body) }),
-    })
-    expect(del.statusCode).toBe(302)
-    expect(del.headers.location).toBe('/demo/notes?notice=deleted')
-    expect(await Note.findById(mine.id)).toBeNull()
-  })
-
-  test('redis 방문 카운터: 페이지 로드마다 누적 카운터가 1씩 증가한다', async () => {
-    const redis = boot.ctx.cache('demo').native
-    const before = Number((await redis.get(RedisDemoService.VISITS_TOTAL_KEY)) ?? 0)
-    await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
-    await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
-    const after = Number(await redis.get(RedisDemoService.VISITS_TOTAL_KEY))
-    expect(after).toBe(before + 2)
-  })
-
-  test('redis 캐시: 비운 직후 첫 로드는 miss, 다음 로드는 hit', async () => {
-    // 캐시 키를 직접 비워 결정적 상태로 만든다.
-    await boot.ctx.cache('demo').del(RedisDemoService.USER_COUNT_KEY)
-
-    const miss = await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
-    expect(miss.statusCode).toBe(200)
-    expect(miss.body).toContain('캐시 미스') // 기본 로케일 ko.
-
-    const hit = await fastify.inject({ method: 'GET', url: '/demo/redis', headers: { cookie: cookieHeader(jar) } })
-    expect(hit.statusCode).toBe(200)
-    expect(hit.body).toContain('캐시 적중')
-  })
-
-  // ── 관측 데모(ADR-163) — 메트릭/Swagger/트레이싱/로그/업로드 ──────────────────────────
-
-  test('관측 데모 비로그인 가드: 메트릭/트레이싱/로그/업로드/docs 는 로그인으로 302', async () => {
-    for (const url of ['/demo/metrics', '/demo/tracing', '/demo/logs', '/demo/upload', '/docs']) {
-      const res = await fastify.inject({ method: 'GET', url })
-      expect(res.statusCode, url).toBe(302)
-      expect(res.headers.location, url).toBe('/auth/login')
-    }
-  })
-
-  test('메트릭 데모: 로그인 시 200 + 카드 렌더', async () => {
-    const res = await fastify.inject({ method: 'GET', url: '/demo/metrics', headers: { cookie: cookieHeader(jar) } })
-    expect(res.statusCode).toBe(200)
-    expect(res.body).toContain('메트릭') // h1 title(ko).
-  })
-
-  test('Swagger: /docs/json 이 라우트 schema 를 수집한 OpenAPI 명세를 준다', async () => {
-    const res = await fastify.inject({ method: 'GET', url: '/docs/json', headers: { cookie: cookieHeader(jar) } })
-    expect(res.statusCode).toBe(200)
-    const spec = res.json()
-    expect(spec.openapi).toMatch(/^3\./)
-    // users 라우트가 자동 수집됐는지(경로 + 태그).
-    expect(spec.paths['/users']).toBeTruthy()
-    expect(JSON.stringify(spec)).toContain('users')
-  })
-
-  test('트레이싱 데모: 200 + generate POST(사용자 span + DB 핑) 302', async () => {
-    const page = await fastify.inject({ method: 'GET', url: '/demo/tracing', headers: { cookie: cookieHeader(jar) } })
-    expect(page.statusCode).toBe(200)
-    const gen = await fastify.inject({
-      method: 'POST',
-      url: '/demo/tracing/generate',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(page.body) }),
-    })
-    expect(gen.statusCode).toBe(302)
-    expect(gen.headers.location).toBe('/demo/tracing?notice=generated')
-  })
-
-  test('로그 데모: emit POST 302 → 최근 목록에 메시지 표시', async () => {
-    const page = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
-    expect(page.statusCode).toBe(200)
-    const MSG = `itest log ${Date.now()}`
-    const emit = await fastify.inject({
-      method: 'POST',
-      url: '/demo/logs/emit',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(page.body), level: 'warn', message: MSG }),
-    })
-    expect(emit.statusCode).toBe(302)
-    expect(emit.headers.location).toBe('/demo/logs?notice=emitted')
-    const after = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
-    expect(after.body).toContain(MSG)
-  })
-
-  // ── 가이드 뷰어(/guide) — 라우터 params 스키마 검증(ADR-019) + i18n ──────────────────────
-
-  test('가이드 목록: 로그인 시 200 + 카드 그리드', async () => {
-    const res = await fastify.inject({ method: 'GET', url: '/guide', headers: { cookie: cookieHeader(jar) } })
-    expect(res.statusCode).toBe(200)
-    expect(res.body).toContain('가이드') // guide_index_title(ko).
-  })
-
-  test('가이드 단일: 유효 slug 는 200 + 목차 렌더', async () => {
-    const res = await fastify.inject({ method: 'GET', url: '/guide/01-cli', headers: { cookie: cookieHeader(jar) } })
-    expect(res.statusCode).toBe(200)
-    expect(res.body).toContain('목차') // guide_toc(ko) — 좌측 목차.
-  })
-
-  test('가이드 단일: 형식 위반 slug 는 라우터 params 스키마가 400(validation.failed)으로 막는다', async () => {
-    for (const bad of ['INVALID', 'foo_bar', 'a.b']) {
-      const res = await fastify.inject({ method: 'GET', url: `/guide/${encodeURIComponent(bad)}`, headers: { cookie: cookieHeader(jar) } })
-      expect(res.statusCode, bad).toBe(400)
-      expect(res.json().error.code, bad).toBe('validation.failed')
-    }
-  })
-
-  test('가이드 단일: 형식은 맞지만 없는 slug 는 서비스가 404(guide.not_found)', async () => {
-    const res = await fastify.inject({ method: 'GET', url: '/guide/99-does-not-exist', headers: { cookie: cookieHeader(jar) } })
-    expect(res.statusCode).toBe(404)
-    expect(res.json().error.code).toBe('guide.not_found')
-  })
-
-  test('i18n: 검증 에러 메시지가 locale(ko 기본 / en 쿠키)로 번역된다', async () => {
-    const ko = await fastify.inject({ method: 'GET', url: '/guide/BAD', headers: { cookie: cookieHeader(jar) } })
-    expect(ko.json().error.message).toBe('입력값이 올바르지 않습니다.')
-    const en = await fastify.inject({ method: 'GET', url: '/guide/BAD', headers: { cookie: `${cookieHeader(jar)}; mega.lang=en` } })
-    expect(en.json().error.message).toBe('Validation failed.')
-  })
-
-  test('로그 데모: message 가 상한(500자)을 넘으면 body 스키마가 400 으로 막는다', async () => {
-    const page = await fastify.inject({ method: 'GET', url: '/demo/logs', headers: { cookie: cookieHeader(jar) } })
-    const res = await fastify.inject({
-      method: 'POST',
-      url: '/demo/logs/emit',
-      headers: { cookie: cookieHeader(jar), 'content-type': 'application/x-www-form-urlencoded' },
-      payload: form({ _csrf: csrfFrom(page.body), level: 'info', message: 'x'.repeat(501) }),
-    })
-    expect(res.statusCode).toBe(400)
-    expect(res.json().error.code).toBe('validation.failed')
-  })
-
-  test('업로드 데모: multipart + csrf-token 헤더로 저장 → JSON envelope + 최근 목록', async () => {
-    // 폼 GET — _csrf 쿠키 확보 + data-csrf 토큰 추출(multipart 는 헤더로 전송).
-    const page = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
-    expect(page.statusCode).toBe(200)
-    applyCookies(page, jar)
-    const token = csrfDataFrom(page.body)
-
-    const FNAME = `itest-${Date.now()}.txt`
-    const { body, contentType } = multipartBody([{ filename: FNAME, contentType: 'text/plain', value: 'hello upload' }])
-    const up = await fastify.inject({
-      method: 'POST',
-      url: '/demo/upload',
-      headers: { cookie: cookieHeader(jar), 'content-type': contentType, 'csrf-token': token },
-      payload: body,
-    })
-    expect(up.statusCode).toBe(200)
-    const env = up.json()
-    expect(env.ok).toBe(true)
-    expect(env.data.files[0]).toMatchObject({ filename: FNAME, mimetype: 'text/plain' })
-    // 저장 경로는 프로젝트 루트 기준 상대(var/uploads/...) — 절대경로 비노출.
-    expect(env.data.files[0].path).toMatch(/^var[/\\]uploads[/\\]/)
-
-    // 실제 디스크에 저장됐는지 확인(프로젝트 루트 기준).
-    const savedAbs = resolve(PROJECT, env.data.files[0].path)
-    expect(existsSync(savedAbs)).toBe(true)
-    expect(readFileSync(savedAbs, 'utf8')).toBe('hello upload')
-
-    // 최근 업로드 목록에 파일명 + 다운로드 링크가 보인다.
-    const after = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
-    expect(after.body).toContain(FNAME)
-    expect(after.body).toContain(`/demo/upload/file/${encodeURIComponent(FNAME)}`)
-
-    // 다운로드 — 인증 사용자는 소스에서 읽은 파일 내용을 받는다(정적 서빙 아님).
-    const dl = await fastify.inject({ method: 'GET', url: `/demo/upload/file/${encodeURIComponent(FNAME)}`, headers: { cookie: cookieHeader(jar) } })
-    expect(dl.statusCode).toBe(200)
-    expect(dl.body).toBe('hello upload')
-    expect(dl.headers['content-disposition']).toContain('attachment')
-
-    // 비로그인 다운로드는 로그인으로 리다이렉트(가드).
-    const dlGuard = await fastify.inject({ method: 'GET', url: `/demo/upload/file/${encodeURIComponent(FNAME)}` })
-    expect(dlGuard.statusCode).toBe(302)
-    expect(dlGuard.headers.location).toBe('/auth/login')
-
-    rmSync(savedAbs, { force: true }) // 테스트 산출물 정리.
-  })
-
-  test('업로드 데모: 비허용 MIME 은 415 로 거부', async () => {
-    const page = await fastify.inject({ method: 'GET', url: '/demo/upload', headers: { cookie: cookieHeader(jar) } })
-    applyCookies(page, jar)
-    const token = csrfDataFrom(page.body)
-    const { body, contentType } = multipartBody([{ filename: 'evil.bin', contentType: 'application/octet-stream', value: 'x' }])
-    const up = await fastify.inject({
-      method: 'POST',
-      url: '/demo/upload',
-      headers: { cookie: cookieHeader(jar), 'content-type': contentType, 'csrf-token': token },
-      payload: body,
-    })
-    expect(up.statusCode).toBe(415)
-  })
-})