feat: 주제 화면을 계약에 잇고, 등록을 잊는 사고를 가드로 막는다

주제 화면은 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만
열었다. 제목과 설명까지 코드에 있었고, 목록에 없는 주제는 기록이 멀쩡히 있어도 404 로
갔다 — 픽스처의 `kubernetes` 가 그랬다. 계약에는 처음부터 `/topics/{slug}` 가 있었지만
아무도 부르지 않았다. 이제 그 연산을 부르고, 주제가 답하는 질문(논지)과 그 질문에 대해
실제로 만들어 본 답들(축)을 화면의 뼈대로 둔다.

프로젝트의 논지도 마찬가지다. 담을 칸이 없어 목적(`purpose`)을 대신 보여 주고
있었는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다.

축 CRUD 네 연산은 계약에 있으면서 기여 목록에 없었다 — 등록되지 않은 연산은 타입에는
멀쩡히 보이는데 부를 수가 없다. `getPublicConcept` 과 `deleteConceptDraft` 가 정확히
그래서 못 불렸고, 개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" 가 떴다.
그래서 가드를 둘 넣는다. 공개 계약은 전수 대조하고(봉투 없이 바이트를 주는 `/media` 만
면제), 관리 계약은 **한 종류만 빠진 자리**를 본다 — 깨진 것이 늘 그 모양이었다.
개념 삭제 등록을 지워 보고 실제로 멈추는 것을 확인했다.

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 16:57:24 +09:00
co-authored by Claude Opus 5
parent 618a228eff
commit 15e6ea8f15
18 changed files with 512 additions and 80 deletions
@@ -2,64 +2,88 @@ import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { PublicDocumentRelations } from "../../shared/public-render/public-document-relations.tsx";
import { ProseText } from "../../shared/public-render/prose-text.tsx";
import { PublicRecordList } from "../components/public-record-list.tsx";
import { usePublicContent } from "../use-public-content.tsx";
const topics = {
jpa: {
title: "JPA",
description: "목록 조회, 연관 로딩과 페이지 경계를 함께 검증한 기록입니다.",
},
authentication: {
title: "Authentication",
description:
"브라우저와 Edge, Resource Server 사이의 인증 책임과 신뢰 경계를 검증한 기록입니다.",
},
redis: {
title: "Redis",
description:
"애플리케이션 정책과 Redis 저장 명령의 책임 경계를 검증한 기록입니다.",
},
} as const;
function topicConfig(value: unknown) {
if (
value === "jpa" ||
value === "authentication" ||
value === "redis"
) {
return topics[value];
}
return undefined;
}
/**
* 주제 한 편.
*
* <p>이 화면은 오래 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만 열었다.
* 제목과 설명까지 코드에 있었고, 새 주제를 만들면 화면이 그대로 404 로 갔다 — 계약에는 처음부터
* `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. 손으로 나열한 목록에 새 것을 빠뜨리는 일이
* 이 저장소에서 반복됐고, 여기서는 목록 자체를 없앤다.
*
* <p>주제가 답하는 질문(논지)과, 그 질문에 대해 실제로 만들어 본 답들(축)이 이 화면의 뼈대다.
* 축이 없는 주제도 있으므로 — 축을 쓸지는 주제마다 다르다 — 비면 그 자리를 그리지 않는다.
*/
export function TopicPage() {
const { params } = useRouteInput<"TECH_LOG_TOPIC">();
const topic = topicConfig(params.slug);
// Hooks run unconditionally, so the unknown-topic case is handled by the
// loader and the not-found route is chosen after it.
const slug = typeof params.slug === "string" ? params.slug : "";
const view = usePublicContent(
["tech-log", "topic", slug],
async (queries) =>
topic ? { records: await queries.listRecords({ topic: slug }) } : { records: [] },
);
if (!topic) return <RegisteredNotFoundRoute />;
const view = usePublicContent(["tech-log", "topic", slug], async (queries) => ({
topic: await queries.getTopicDetail(slug),
records: await queries.listRecords({ topic: slug }),
}));
if (!view.ready) return view.fallback;
const { records } = view.data;
const { topic, records } = view.data;
if (!topic) return <RegisteredNotFoundRoute />;
const axisLabel = topic.variantLabel.trim() || "접근";
return (
<main id="main-content" className="shell public-index-page">
<main id="main-content" className="shell public-index-page topic-hub">
<header className="public-page-header">
<p className="section-kicker">Topic</p>
<h1>{topic.title}</h1>
<p>{topic.description}</p>
<h1>{topic.name}</h1>
{/*
논지가 있으면 그것이 이 주제의 첫 문장이다. 설명은 목록에서 주제를 가려내는 한 줄이고,
논지는 이 주제가 무엇에 답하는지를 말한다 — 둘 다 있으면 논지를 보인다.
*/}
<ProseText text={topic.thesis || topic.description} />
</header>
{topic.variants.length > 0 ? (
<section className="topic-variants" aria-labelledby="topic-variants-title">
<p className="section-kicker">{axisLabel}</p>
<h2 id="topic-variants-title">{`${axisLabel}별로 무엇을 알게 됐나`}</h2>
<ul>
{topic.variants.map((variant) => (
<li key={variant.slug}>
<a href={variant.path}>
<strong>{variant.title}</strong>
{/*
비교표가 읽는 것은 결론이다. 요약은 이것이 무엇인가를 말하고, 결론은 만들어
보고 무엇을 알게 됐는가를 말한다 — 축을 견주는 자리에서 쓸모 있는 것은 뒤쪽이다.
*/}
<p>{variant.conclusion || variant.summary}</p>
{variant.recordCount > 0 ? (
<span aria-hidden="true">{`기록 ${variant.recordCount}`}</span>
) : null}
</a>
</li>
))}
</ul>
</section>
) : null}
<PublicDocumentRelations
relations={[...topic.featuredCases, ...topic.activeQuestions]}
kicker="Reading order"
title="먼저 읽을 것"
/>
<div className="public-result-heading">
<h2>관련 기록</h2>
<p>{records.length}개의 관련 기록</p>
<p>{`${records.length}개의 관련 기록`}</p>
</div>
<PublicRecordList records={records} />
<PublicDocumentRelations
relations={topic.relatedProjects}
kicker="Projects"
title="이 주제를 다룬 프로젝트"
/>
</main>
);
}
@@ -48,7 +48,11 @@ export function PublicDocumentRelations({
return (
<li key={relation.path}>
<Link to={relation.path}>
{relation.label ? <span>{relation.label}</span> : null}
{/*
묶음 이름이 없어도 자리는 남긴다 — 이 링크는 세 칸짜리 격자라 첫 칸이 사라지면
제목이 라벨 칸으로 밀려 들어간다.
*/}
<span>{relation.label ?? ""}</span>
<div>
<strong>{relation.title}</strong>
{description ? <p aria-hidden="true">{description}</p> : null}
@@ -2821,3 +2821,84 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
font-size: 13px;
line-height: 1.6;
}
/*
주제 화면의 축 비교.
이 자리는 표가 아니라 목록이다. 축이 둘이든 넷이든 같은 배치로 읽히고, 좁은 화면에서 표가
가로로 밀리는 일도 없다. 이 사이트의 다른 목록과 같은 규칙을 따른다 — 테두리는 줄을 가르는
가로선 하나, 강조는 글자 굵기와 색으로만.
*/
.topic-variants {
margin-top: 64px;
padding-top: 30px;
border-top: 1px solid var(--line-strong);
}
.topic-variants h2 {
margin: 10px 0 20px;
font-size: 26px;
letter-spacing: -0.03em;
}
.topic-variants ul {
margin: 0;
padding: 0;
list-style: none;
}
.topic-variants li {
border-top: 1px solid var(--line);
}
.topic-variants li:last-child {
border-bottom: 1px solid var(--line);
}
.topic-variants a {
display: grid;
grid-template-columns: 180px minmax(0, 1fr) 72px;
gap: 20px;
align-items: baseline;
padding: 26px 2px 27px;
}
.topic-variants strong {
color: var(--ink);
font-size: 16px;
font-weight: 620;
line-height: 1.5;
}
.topic-variants p {
margin: 0;
color: var(--muted);
font-size: 14px;
line-height: 1.65;
}
.topic-variants a > span {
color: var(--faint);
font-size: 12px;
text-align: right;
}
.topic-variants a:hover strong {
color: var(--signal);
}
/* 주제 화면에서는 관계 목록이 본문 안에 있으므로 문서 하단만큼 띄우지 않는다. */
.topic-hub .document-relations {
margin-top: 64px !important;
}
@media (max-width: 720px) {
.topic-variants a {
grid-template-columns: minmax(0, 1fr);
gap: 8px;
}
.topic-variants a > span {
text-align: left;
}
}