import { mkdir, readFile, rm, writeFile } from "node:fs/promises"; import path from "node:path"; import process from "node:process"; import { chromium, type APIRequestContext, type BrowserContext, type Page } from "@playwright/test"; import { TECH_LOG_ROUTE_REGISTRY } from "../src/features/tech-log/contracts/tech-log-route-contract.ts"; /** * 공개 화면과 Studio 화면 전부를 찍는다. UI 검토용이다. * *

찍을 목록을 손으로 적지 않는다. 라우트 레지스트리를 그대로 돌고, 라우트 하나당 해석기를 * {@link RESOLVERS} 에 반드시 하나 두게 한다 — `Record` 라 라우트가 늘면 컴파일러가 * 빈 자리를 잡는다. 이 저장소에서 손으로 나열한 목록에 새 항목을 빠뜨리는 일이 반복됐고(종류 * 필터에서 개념·환경 구성이 빠졌던 것이 같은 실수다), 검토용 목록이 조용히 낡으면 "찍히지 않은 * 화면은 문제가 없는 것처럼" 보인다. * *

`:slug` 같은 자리는 지어내지 않고 살아 있는 API 에서 실제 값을 가져온다. 지어낸 주소는 * 404 화면을 찍어 놓고 검토가 끝난 것처럼 보이게 만든다. 채울 값이 없으면 건너뛰되 그 사실을 * 결과에 남긴다. * *

Studio 는 로그인이 필요하다. 세션을 파일로 저장해 두고 재사용하며, 매 화면마다 로그인 관문 * (`[data-surface="authentication-required"]`)이 아닌지 확인한다 — 세션이 끊긴 채로 돌면 같은 * 로그인 화면 수십 장을 찍어 놓고 Studio 를 다 봤다고 착각한다. * * 사용법: * node scripts/capture-screens.ts --login # 창을 열어 직접 로그인하고 세션 저장 * node scripts/capture-screens.ts # 공개 + Studio 전부 * node scripts/capture-screens.ts --only=public * node scripts/capture-screens.ts --widths=1440 --slices=3 * node scripts/capture-screens.ts --base=http://localhost:5173 */ type RouteId = keyof typeof TECH_LOG_ROUTE_REGISTRY; const DEFAULT_BASE = "https://hyeonworks.com"; /** 이 사이트의 반응형 분기는 1179 / 1050 / 900 / 767 이다. 그 위와 아래를 하나씩 본다. */ const DEFAULT_WIDTHS = [1440, 390] as const; const VIEWPORT_HEIGHT = 900; /** 한 폭당 이만큼까지만 자른다. 긴 문서라도 검토는 앞쪽에서 대부분 끝난다. */ const DEFAULT_SLICES = 5; const OUTPUT_DIRECTORY = "artifacts/design-review/screens"; const SESSION_FILE = "artifacts/design-review/studio-session.json"; /** 로그인 관문. 이것이 보이면 그 화면은 Studio 화면이 아니라 로그인 화면이다. */ const AUTH_GATE = '[data-surface="authentication-required"]'; type LiveData = { /** 종류별 공개 경로 한 개씩. 값이 없으면 그 종류로 게시된 기록이 아직 없다는 뜻이다. */ readonly knowledgePaths: Readonly>; readonly questionPath: string | null; readonly topicSlug: string | null; /** 접근(variant)을 가진 주제와 그 접근 하나. 접근이 없는 주제만 있으면 null 이다. */ readonly topicWithVariant: Readonly<{ slug: string; variant: string }> | null; readonly projectSlug: string | null; readonly releaseVersion: string | null; readonly documentId: string | null; readonly publicationEventId: string | null; readonly studioProjectId: string | null; readonly studioTopicId: string | null; readonly studioReleaseId: string | null; }; type Resolver = (data: LiveData) => string | null; function knowledge(kind: string): Resolver { return (data) => data.knowledgePaths[kind] ?? null; } /** * 라우트 하나를 실제 주소로 바꾸는 법. * *

`null` 은 "지금 살아 있는 자료로는 이 화면을 열 수 없다"는 뜻이다. 결과 보고서에 이유와 함께 * 남는다 — 조용히 빠지면 검토에서 그 화면이 없었다는 사실 자체가 보이지 않는다. */ const RESOLVERS: Record = { TECH_LOG_HOME: () => "/", TECH_LOG_EXPLORE: () => "/explore", // `/explore/:kind` 는 두 갈래가 화면이 서로 다르다. 둘 다 찍는다. TECH_LOG_EXPLORE_KIND: () => "/explore/knowledge", TECH_LOG_CASE: knowledge("CASE"), TECH_LOG_REFERENCE: knowledge("REFERENCE"), TECH_LOG_CONCEPT: knowledge("CONCEPT"), TECH_LOG_SETUP: knowledge("SETUP"), TECH_LOG_QUESTION: (data) => data.questionPath, TECH_LOG_TOPICS: () => "/topics", TECH_LOG_TOPIC: (data) => (data.topicSlug ? `/topics/${data.topicSlug}` : null), TECH_LOG_TOPIC_VARIANT: (data) => data.topicWithVariant ? `/topics/${data.topicWithVariant.slug}/${data.topicWithVariant.variant}` : null, TECH_LOG_PROJECTS: () => "/projects", TECH_LOG_PROJECT: (data) => (data.projectSlug ? `/projects/${data.projectSlug}` : null), TECH_LOG_PROJECT_RECORDS: (data) => data.projectSlug ? `/projects/${data.projectSlug}/records` : null, TECH_LOG_PROJECT_DECISIONS: (data) => data.projectSlug ? `/projects/${data.projectSlug}/decisions` : null, TECH_LOG_PROJECT_ACTIVITY: (data) => data.projectSlug ? `/projects/${data.projectSlug}/activity` : null, TECH_LOG_RELEASES: () => "/releases", TECH_LOG_RELEASE: (data) => (data.releaseVersion ? `/releases/${data.releaseVersion}` : null), TECH_LOG_PROFILE: () => "/profile", // 빈 검색 결과가 아니라 실제로 걸리는 말을 넣는다. 빈 화면은 배치를 보여 주지 않는다. TECH_LOG_SEARCH: () => "/search?q=%EA%B0%80%EC%83%81%ED%99%94", TECH_LOG_STUDIO_HOME: () => "/studio", TECH_LOG_STUDIO_DOCUMENTS: () => "/studio/documents", TECH_LOG_STUDIO_DOCUMENT_NEW: () => "/studio/documents/new", TECH_LOG_STUDIO_DOCUMENT_EDIT: (data) => data.documentId ? `/studio/documents/${data.documentId}/edit` : null, TECH_LOG_STUDIO_DOCUMENT_VALIDATION: (data) => data.documentId ? `/studio/documents/${data.documentId}/validation` : null, TECH_LOG_STUDIO_DOCUMENT_PREVIEW: (data) => data.documentId ? `/studio/documents/${data.documentId}/preview` : null, TECH_LOG_STUDIO_DOCUMENT_PUBLISH: (data) => data.documentId ? `/studio/documents/${data.documentId}/publish` : null, TECH_LOG_STUDIO_PUBLICATIONS: () => "/studio/publications", TECH_LOG_STUDIO_PUBLICATION_PREVIEW: (data) => data.publicationEventId ? `/studio/publications/${data.publicationEventId}/preview` : null, TECH_LOG_STUDIO_ASSETS: () => "/studio/assets", TECH_LOG_STUDIO_TAXONOMY: () => "/studio/taxonomy", TECH_LOG_STUDIO_PROJECT_EDIT: (data) => data.studioProjectId ? `/studio/projects/${data.studioProjectId}` : null, TECH_LOG_STUDIO_TOPIC_EDIT: (data) => data.studioTopicId ? `/studio/topics/${data.studioTopicId}` : null, TECH_LOG_STUDIO_RELEASES: () => "/studio/releases", TECH_LOG_STUDIO_RELEASE_EDIT: (data) => data.studioReleaseId ? `/studio/releases/${data.studioReleaseId}` : null, // 없는 주소여야 찍을 수 있는 화면이다. TECH_LOG_STUDIO_NOT_FOUND: () => "/studio/no-such-studio-page", NOT_FOUND: () => "/no-such-page", }; /** * 한 라우트가 여러 화면을 그리는 경우. `/explore/:kind` 의 두 갈래처럼 같은 코드가 아니라 서로 * 다른 화면이면 검토에서 둘 다 봐야 한다. */ const EXTRA_TARGETS: ReadonlyArray> = [{ id: "TECH_LOG_EXPLORE_KIND-questions", group: "PUBLIC", url: "/explore/questions" }]; type Target = Readonly<{ id: string; group: "PUBLIC" | "STUDIO"; url: string }>; type Skipped = Readonly<{ id: string; group: string; reason: string }>; async function json(request: APIRequestContext, url: string): Promise { const response = await request.get(url, { headers: { Accept: "application/json" } }); if (!response.ok()) return null; try { return (await response.json()) as unknown; } catch { return null; } } function envelope(value: unknown): Record | null { if (typeof value !== "object" || value === null) return null; const data = (value as { data?: unknown }).data; return typeof data === "object" && data !== null ? (data as Record) : null; } function itemsOf(value: unknown): ReadonlyArray> { const data = envelope(value); const items = data?.["items"]; return Array.isArray(items) ? (items as Record[]) : []; } function text(row: Record | undefined, key: string): string | null { const value = row?.[key]; return typeof value === "string" && value.length > 0 ? value : null; } /** 공개 화면에 필요한 값. 로그인 없이 읽는다. */ async function readPublic(request: APIRequestContext, base: string) { const [knowledgeRaw, questionsRaw, topicsRaw, projectsRaw, releasesRaw] = await Promise.all([ json(request, `${base}/api/v1/public/explore/knowledge?limit=100`), json(request, `${base}/api/v1/public/explore/questions?limit=20`), json(request, `${base}/api/v1/public/topics`), json(request, `${base}/api/v1/public/projects`), json(request, `${base}/api/v1/public/releases`), ]); const knowledgePaths: Record = {}; for (const row of itemsOf(knowledgeRaw)) { const kind = text(row, "type"); const routePath = text(row, "path"); if (kind && routePath && !(kind in knowledgePaths)) knowledgePaths[kind] = routePath; } const topics = itemsOf(topicsRaw); const withVariant = topics.find((row) => Number(row["variantCount"] ?? 0) > 0); let topicWithVariant: { slug: string; variant: string } | null = null; const withVariantSlug = text(withVariant, "slug"); if (withVariantSlug) { const detail = envelope(await json(request, `${base}/api/v1/public/topics/${withVariantSlug}`)); const variants = detail?.["variants"]; const first = Array.isArray(variants) ? (variants[0] as Record) : undefined; const variant = text(first, "slug") ?? text(first, "variantSlug"); if (variant) topicWithVariant = { slug: withVariantSlug, variant }; } return { knowledgePaths, questionPath: text(itemsOf(questionsRaw)[0], "path"), topicSlug: text(topics[0], "slug"), topicWithVariant, projectSlug: text(itemsOf(projectsRaw)[0], "slug"), releaseVersion: text(itemsOf(releasesRaw)[0], "version"), }; } /** Studio 화면에 필요한 값. 저장된 세션으로 읽는다. */ async function readStudio(request: APIRequestContext, base: string) { const [documentsRaw, publicationsRaw, projectsRaw, topicsRaw, releasesRaw] = await Promise.all([ json(request, `${base}/api/v1/studio/documents?limit=1`), json(request, `${base}/api/v1/studio/publications?limit=1`), json(request, `${base}/api/v1/studio/catalog?type=PROJECT&limit=1`), json(request, `${base}/api/v1/studio/catalog?type=TOPIC&limit=1`), json(request, `${base}/api/v1/studio/releases?size=1`), ]); const event = itemsOf(publicationsRaw)[0]?.["event"]; const releases = itemsOf(releasesRaw); return { documentId: text(itemsOf(documentsRaw)[0], "id"), publicationEventId: text( typeof event === "object" && event !== null ? (event as Record) : undefined, "publicationEventId", ), studioProjectId: text(itemsOf(projectsRaw)[0], "id"), studioTopicId: text(itemsOf(topicsRaw)[0], "id"), studioReleaseId: text(releases[0], "id") ?? text(releases[0], "releaseId"), }; } const EMPTY_STUDIO = { documentId: null, publicationEventId: null, studioProjectId: null, studioTopicId: null, studioReleaseId: null, } as const; /** * 창을 열어 사람이 직접 로그인하게 하고 그 세션을 파일로 남긴다. * *

자격 증명을 스크립트가 들고 있지 않아도 되고, Keycloak 화면이 바뀌어도 깨지지 않는다. */ async function login(base: string): Promise { const browser = await chromium.launch({ headless: false }); const context = await browser.newContext({ viewport: { width: 1440, height: 900 } }); const page = await context.newPage(); await page.goto(`${base}/studio`); process.stdout.write("열린 창에서 로그인하세요. Studio 화면이 뜨면 자동으로 저장합니다...\n"); try { await page.waitForSelector('a[href="/studio/documents"]', { timeout: 300_000 }); await mkdir(path.dirname(SESSION_FILE), { recursive: true }); await context.storageState({ path: SESSION_FILE }); process.stdout.write(`세션 저장: ${SESSION_FILE}\n`); } finally { await browser.close(); } } async function sessionState(): Promise { try { await readFile(SESSION_FILE, "utf8"); return SESSION_FILE; } catch { return undefined; } } /** * 한 화면을 폭마다 찍는다. * *

전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 17px 글자가 7~8px 로 * 뭉갠다. 덩어리는 보이지만 정작 타이포는 못 본다. 그래서 화면 높이만큼씩 잘라 찍는다. */ async function capture( page: Page, target: Target, base: string, widths: readonly number[], maxSlices: number, ): Promise<{ files: string[]; problem: string | null }> { const files: string[] = []; const directory = path.join(OUTPUT_DIRECTORY, target.group.toLowerCase()); for (const width of widths) { await page.setViewportSize({ width, height: VIEWPORT_HEIGHT }); await page.goto(`${base}${target.url}`, { waitUntil: "domcontentloaded" }); await page.waitForSelector("main", { timeout: 20_000 }).catch(() => undefined); // 자료를 받아 다시 그리는 화면이 많다. 반쯤 그려진 상태를 남기면 검토가 그것을 지적한다. await page.waitForLoadState("networkidle", { timeout: 15_000 }).catch(() => undefined); await page.waitForTimeout(400); if (target.group === "STUDIO" && (await page.locator(AUTH_GATE).count()) > 0) { return { files, problem: "세션이 끊겨 로그인 화면이 떴습니다 — --login 으로 다시 로그인하세요" }; } const height = await page.evaluate(() => document.documentElement.scrollHeight); const slices = Math.min(Math.max(Math.ceil(height / VIEWPORT_HEIGHT), 1), maxSlices); for (let index = 0; index < slices; index += 1) { await page.evaluate((top: number) => window.scrollTo(0, top), index * VIEWPORT_HEIGHT); await page.waitForTimeout(200); const file = path.join(directory, `${target.id}-${width}-${index + 1}.png`); await page.screenshot({ path: file, scale: "css" }); files.push(file); } } return { files, problem: null }; } function flag(name: string): string | null { const found = process.argv.slice(2).find((entry) => entry.startsWith(`--${name}=`)); return found ? found.slice(name.length + 3) : null; } async function main(): Promise { const base = (flag("base") ?? DEFAULT_BASE).replace(/\/+$/u, ""); if (process.argv.includes("--login")) { await login(base); return; } const only = flag("only"); const widths = flag("widths")?.split(",").map(Number).filter(Number.isFinite) ?? [ ...DEFAULT_WIDTHS, ]; const maxSlices = Number(flag("slices") ?? DEFAULT_SLICES); /* 이번에 찍는 묶음만 비운다. 통째로 지우면 `--only=studio` 한 번이 직전에 찍어 둔 공개 화면을 전부 날린다 — 실제로 한 번 날렸다. */ const clearing = only === "public" ? ["public"] : only === "studio" ? ["studio"] : ["public", "studio"]; for (const group of clearing) { await rm(path.join(OUTPUT_DIRECTORY, group), { recursive: true, force: true }); await mkdir(path.join(OUTPUT_DIRECTORY, group), { recursive: true }); } const browser = await chromium.launch(); const skipped: Skipped[] = []; const captured: Array<{ target: Target; files: string[] }> = []; try { const publicContext = await browser.newContext({ viewport: { width: 1440, height: 900 } }); const publicData = await readPublic(publicContext.request, base); const storage = await sessionState(); let studioContext: BrowserContext | null = null; let studioData: Awaited> = { ...EMPTY_STUDIO }; if (only !== "public") { if (!storage) { process.stdout.write( `Studio 세션이 없습니다(${SESSION_FILE}). 공개 화면만 찍습니다.\n` + " → node scripts/capture-screens.ts --login 으로 먼저 로그인하세요.\n\n", ); } else { studioContext = await browser.newContext({ storageState: storage, viewport: { width: 1440, height: 900 }, }); studioData = await readStudio(studioContext.request, base); } } const data: LiveData = { ...publicData, ...studioData }; const targets: Target[] = []; for (const [routeId, definition] of Object.entries(TECH_LOG_ROUTE_REGISTRY)) { const group = definition.layoutGroup === "STUDIO" ? "STUDIO" : "PUBLIC"; if (only === "public" && group === "STUDIO") continue; if (only === "studio" && group === "PUBLIC") continue; if (group === "STUDIO" && !studioContext) { skipped.push({ id: routeId, group, reason: "Studio 세션 없음" }); continue; } const url = RESOLVERS[routeId as RouteId](data); if (url === null) { skipped.push({ id: routeId, group, reason: "이 화면을 채울 실제 자료가 없습니다" }); continue; } targets.push({ id: routeId, group, url }); } for (const extra of EXTRA_TARGETS) { if (only === "studio" && extra.group === "PUBLIC") continue; if (only === "public" && extra.group === "STUDIO") continue; targets.push(extra); } const publicPage = await publicContext.newPage(); const studioPage = studioContext ? await studioContext.newPage() : null; for (const target of targets) { const page = target.group === "STUDIO" ? studioPage : publicPage; if (!page) continue; const result = await capture(page, target, base, widths, maxSlices); if (result.problem) { skipped.push({ id: target.id, group: target.group, reason: result.problem }); process.stdout.write(` ✗ ${target.id} ${target.url} — ${result.problem}\n`); continue; } captured.push({ target, files: result.files }); process.stdout.write(` ✓ ${target.id} ${target.url} (${result.files.length}장)\n`); } } finally { await browser.close(); } /* 묶음별로 결과를 남기고, 목차는 남아 있는 파일 전부에서 다시 만든다. `--only` 로 한쪽만 찍어도 목차에서 다른 쪽이 사라지지 않는다. */ for (const group of clearing) { const rows = captured.filter((entry) => entry.target.group.toLowerCase() === group); const groupSkipped = skipped.filter((entry) => entry.group.toLowerCase() === group); await writeFile( path.join(OUTPUT_DIRECTORY, `captured-${group}.json`), `${JSON.stringify({ base, captured: rows, skipped: groupSkipped }, null, 2)}\n`, "utf8", ); } const merged: Array<{ target: Target; files: string[] }> = []; const mergedSkipped: Skipped[] = []; for (const group of ["public", "studio"]) { try { const raw = JSON.parse( await readFile(path.join(OUTPUT_DIRECTORY, `captured-${group}.json`), "utf8"), ) as { captured: Array<{ target: Target; files: string[] }>; skipped: Skipped[] }; merged.push(...raw.captured); mergedSkipped.push(...raw.skipped); } catch { // 아직 찍지 않은 묶음이다. } } const lines = ["# 화면 목록", "", `기준 주소: ${base}`, ""]; for (const group of ["PUBLIC", "STUDIO"] as const) { const rows = merged.filter((entry) => entry.target.group === group); if (rows.length === 0) continue; lines.push(`## ${group === "PUBLIC" ? "공개" : "Studio"} (${rows.length})`, ""); for (const { target, files } of rows) { lines.push(`### ${target.id}`, "", `\`${target.url}\``, ""); for (const file of files) lines.push(`![${path.basename(file)}](${path.relative(OUTPUT_DIRECTORY, file)})`); lines.push(""); } } if (mergedSkipped.length > 0) { lines.push("## 찍지 못한 화면", ""); for (const entry of mergedSkipped) lines.push(`- \`${entry.id}\` (${entry.group}) — ${entry.reason}`); lines.push(""); } await writeFile(path.join(OUTPUT_DIRECTORY, "index.md"), `${lines.join("\n")}\n`, "utf8"); process.stdout.write( `\n찍은 화면 ${captured.length}개, 건너뛴 화면 ${skipped.length}개\n` + `${OUTPUT_DIRECTORY}/index.md\n`, ); } await main();