fix: 종류 이름을 화면마다 하나로 맞추고, 읽는 순서를 기록에서 만든다

홈 한 화면에 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 `CASE`·`CONCEPT`·`OPEN
QUESTION`·`REFERENCE` 로, 바로 아래 「종류별로 읽기」는 「검증 기록」·「동작 원리」·
「적용 기준」·「열린 질문」으로 같은 넷을 불렀다. 독자는 둘이 같은 것이라는 단서를 어디서도
받지 못했다 — 이름을 바꾸기 전보다 나빠진 유일한 자리다. 목록도 공용 표에서 가져온다.

주제 허브의 「먼저 읽을 것」은 넷 다 열린 질문이었다. 서버가 주는 대표 값은 순서가 아니라
통 두 개(대표 Case · 열린 질문)이고 앞쪽이 비어 있어서, 아직 답이 없는 질문만 모아 놓고
「먼저 읽을 것」이라 부르고 있었다. 그리고 그 넷이 바로 아래 목록에 그대로 다시 나왔다.
이제 기록에서 순서를 만든다 — 원리 → 확인한 기록 → 기준 → 아직 모르는 것 — 그리고 위에
오른 편은 아래에서 뺀다.

개념은 목록 매퍼에서 통째로 버려지고 있었다. 서버는 보내고 필터에는 「동작 원리」가 있는데
결과가 0건이라, 독자에게는 기록이 없는 것으로 보였다. 손으로 나열한 종류 목록에 개념을
빠뜨리는 일이 이 저장소에서 반복됐고, 이번에는 계약에서 종류를 읽어 대조하는 가드를 둔다.

그 밖에: 질문 줄의 맥락이 「· 프로젝트」로 시작하던 것(계약에 주제가 없었다), 릴리스가
주 내비에서만 빠지고 홈 목록에는 남아 있던 것, 홈 목록이 화면의 절반을 차지하던 것,
값이 없는 「현재 목표」·「다음 작업」이 빈 칸으로 남던 것, 종류 배지 넷이 시각적으로 같던 것.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
This commit is contained in:
DongHyeonka
2026-09-01 18:36:52 +09:00
co-authored by Claude Opus 5
parent 88d841dc96
commit dc2fda7a5d
14 changed files with 301 additions and 75 deletions
@@ -0,0 +1,51 @@
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { test } from "vitest";
import { knowledgeListItemToRecord } from "../../../src/features/tech-log/adapters/http/public-content-mapping.ts";
/**
* 지식 목록이 계약이 보내는 종류를 하나도 버리지 않는지 본다.
*
* <p>매퍼가 CASE 와 REFERENCE 만 알던 동안 개념은 `null` 로 버려졌다. 서버는 개념을 보내고
* 탐색 필터에는 「동작 원리」가 있는데 결과는 0건이었다 — 독자에게는 기록이 없는 것으로
* 보였고, 필터에 있는데 결과가 없으니 오해가 남았다.
*
* <p>기대 목록을 손으로 적지 않고 계약에서 읽는다. 종류가 늘면 여기서 먼저 멈춘다.
*/
const CONTRACT = readFileSync(
"src/features/tech-log/contracts/public/public-api.openapi.yaml",
"utf8",
);
function contractKnowledgeKinds(): string[] {
const block = /\n {4}KnowledgeListItem:[\s\S]*?(?=\n {4}[A-Z]\w+:)/u.exec(CONTRACT)?.[0] ?? "";
const typeBlock = /\n {8}type:\n {10}type: string\n {10}enum:\n((?: {10}- \w+\n)+)/u.exec(block);
return [...(typeBlock?.[1] ?? "").matchAll(/- (\w+)/gu)].map((match) => match[1]!);
}
test("계약이 보내는 지식 종류를 매퍼가 하나도 버리지 않는다", () => {
const kinds = contractKnowledgeKinds();
assert.deepEqual(
[...kinds].sort(),
["CASE", "CONCEPT", "REFERENCE"],
"계약이 보내는 종류가 바뀌었다 — 매퍼의 표도 함께 봐야 한다",
);
for (const type of kinds) {
const record = knowledgeListItemToRecord({
type,
title: "제목",
path: `/x/${type.toLowerCase()}`,
primarySummary: "요약",
publishedAt: "2026-01-01T00:00:00Z",
primaryTopic: { name: "주제", slug: "topic" },
primaryProject: { name: "프로젝트", slug: "project" },
});
assert.ok(record, `${type} 이 목록에서 버려진다`);
assert.equal(record.kind, type, `${type} 이 다른 종류로 읽힌다`);
// 맥락 줄이 이 두 값을 읽는다. 비면 「· 프로젝트」처럼 앞이 잘린 줄이 남는다.
assert.equal(record.topic, "주제");
assert.equal(record.projectTitle, "프로젝트");
}
});
@@ -160,6 +160,11 @@ describe("TechLog home discovery", () => {
);
}
/*
홈은 앞의 몇 편만 편다. 주제 허브가 생긴 지금 홈이 할 일은 목록을 통째로 펴 두는 것이
아니라 무엇을 견줬고 지금 무엇을 하고 있는지를 보여 주는 것이다 — 목록이 홈의 절반을
차지하면 그 둘이 스크롤 아래로 밀린다.
*/
const latest = screen.getByRole("region", { name: "최근 기록" });
expect(
within(latest).getAllByRole("heading", { level: 3 }).map((heading) =>
@@ -170,9 +175,17 @@ describe("TechLog home discovery", () => {
"파일 저장소 계약을 하나로 통합했습니다",
"Authorization Code Flow에서 state와 nonce의 경계",
"oauth2-proxy 뒤에서 토큰을 다시 검증할 것인가",
"Redis Adapter가 도메인 TTL 정책을 소유하지 않는 이유",
"TechLog Public·Studio 경계를 확정했습니다",
]);
/*
종류 이름은 목록도 범례도 같은 표에서 가져온다. 목록만 영문 대문자로 나가던 동안 홈 한
화면에 종류 이름이 아홉 개 떠 있었고, 독자는 `CASE` 와 「검증 기록」이 같은 것이라는
단서를 어디서도 받지 못했다.
*/
expect(
[...new Set(
Array.from(latest.querySelectorAll(".latest-time > span"), (span) => span.textContent),
)].every((label) => /^[가-힣 ]+$/u.test(label ?? "")),
).toBe(true);
/*
종류별 입구. 예전에는 이 자리가 낱말 뜻풀이였고 이름이 `Case`·`OpenQuestion` 같은
저장소의 말이었다. 이름이 하는 일을 말하도록 바뀌었으므로 설명도 함께 바뀐다.
@@ -245,7 +245,9 @@ describe("TechLog canonical Public documents", () => {
}
expect(
Array.from(container.querySelectorAll(".document-relations li a"), (link) =>
Array.from(
container.querySelectorAll(".document-relations")[0]!.querySelectorAll("li a"),
(link) =>
link.getAttribute("href"),
),
).toEqual(relations);
@@ -338,14 +340,44 @@ describe("TechLog canonical Public documents", () => {
describe("TechLog topics and Public not-found routing", () => {
it.each([
["jpa", "JPA", "3개의 관련 기록"],
["authentication", "Authentication", "2개의 관련 기록"],
["redis", "Redis", "1개의 관련 기록"],
])("aggregates /topics/%s with its own name and count", async (slug, title, count) => {
["jpa", "JPA"],
["authentication", "Authentication"],
["redis", "Redis"],
])("aggregates /topics/%s under its own name", async (slug, title) => {
await renderDocumentRoute("TECH_LOG_TOPIC", `/topics/${slug}`);
expect(screen.getByRole("heading", { level: 1, name: title })).toBeVisible();
expect(screen.getByText(count)).toBeVisible();
expect(screen.getByRole("heading", { name: "먼저 읽을 것" })).toBeVisible();
});
/*
서버가 주는 대표 기록은 작성자가 주제마다 손으로 골라 두는 값이라 대부분 비어 있다. 비면
열린 질문만 남아, 아직 답이 없는 질문을 모아 두고 「먼저 읽을 것」이라 부르게 된다 —
처음 온 사람에게 가장 나쁜 첫 화면이다. 그래서 기록에서 순서를 만든다:
원리 → 확인한 기록 → 기준 → 아직 모르는 것.
*/
it("orders the first reads by kind and does not repeat them below", async () => {
const { container } = await renderDocumentRoute("TECH_LOG_TOPIC", "/topics/jpa");
const firstReads = [
...(container.querySelectorAll(".document-relations")[0]?.querySelectorAll("li a") ?? []),
].map((link) => ({
label: link.querySelector("span")?.textContent,
href: link.getAttribute("href"),
}));
expect(firstReads.map((entry) => entry.label)).toEqual([
"검증 기록",
"적용 기준",
"열린 질문",
]);
// 위에 오른 편은 아래 목록에서 빠진다 — 같은 편이 두 번 나오면 순서를 정해 준 뜻이 없다.
const rest = [...container.querySelectorAll(".public-record-list > li > a")].map((link) =>
link.getAttribute("href"),
);
for (const entry of firstReads) {
expect(rest).not.toContain(entry.href);
}
});
/*
@@ -357,7 +389,6 @@ describe("TechLog topics and Public not-found routing", () => {
await renderDocumentRoute("TECH_LOG_TOPIC", "/topics/kubernetes");
expect(screen.getByRole("heading", { level: 1, name: "Kubernetes" })).toBeVisible();
expect(screen.getByText("1개의 관련 기록")).toBeVisible();
expect(
screen.queryByRole("heading", { name: "페이지를 찾을 수 없습니다." }),
).not.toBeInTheDocument();
@@ -366,9 +397,11 @@ describe("TechLog topics and Public not-found routing", () => {
it("keeps JPA topic records in canonical published order", async () => {
const { container } = await renderDocumentRoute("TECH_LOG_TOPIC", "/topics/jpa");
// 픽스처의 JPA 주제는 종류마다 한 편씩이라 셋 다 「먼저 읽을 것」으로 올라가고 아래는 빈다.
expect(
Array.from(container.querySelectorAll(".public-record-list > li > a"), (link) =>
link.getAttribute("href"),
Array.from(
container.querySelectorAll(".document-relations")[0]!.querySelectorAll("li a"),
(link) => link.getAttribute("href"),
),
).toEqual([
"/cases/collection-fetch-join-pagination",