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
@@ -7,7 +7,7 @@ export type QuestionStatus =
| "ARCHIVED";
export type PublicRelation = {
reason: string;
label: string;
summary: string;
title: string;
path: string;
@@ -330,19 +330,19 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
],
relations: [
{
reason: "이 질문에서 시작됨",
label: "이 질문에서 시작됨",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination",
},
{
reason: "이 Case로 결정함",
label: "이 Case로 결정함",
summary: "",
title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.",
path: "/projects/backend-skeleton/decisions#feed-pagination-boundary",
},
{
reason: "이 기준 문서로 정리됨",
label: "이 기준 문서로 정리됨",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy",
@@ -390,13 +390,13 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
],
relations: [
{
reason: "이 프로젝트에 속함",
label: "이 프로젝트에 속함",
summary: "",
title: "Backend Skeleton",
path: "/projects/backend-skeleton",
},
{
reason: "이 결정과 연결됨",
label: "이 결정과 연결됨",
summary: "",
title: "StoragePort와 Adapter의 책임을 분리합니다.",
path: "/projects/backend-skeleton/decisions#storage-port-unification",
@@ -449,13 +449,13 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
verifiedAt: "2026.08.09",
relations: [
{
reason: "이 질문의 검증 기준",
label: "이 질문의 검증 기준",
summary: "",
title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?",
path: "/questions/validate-edge-token-again",
},
{
reason: "이 프로젝트에 속함",
label: "이 프로젝트에 속함",
summary: "",
title: "Auth Lab",
path: "/projects/auth-lab",
@@ -508,13 +508,13 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
verifiedAt: "2026.08.11",
relations: [
{
reason: "이 Case에서 측정함",
label: "이 Case에서 측정함",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
{
reason: "이 질문을 해결함",
label: "이 질문을 해결함",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination",
@@ -565,13 +565,13 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
"토큰 전달안과 신뢰 헤더안을 위협 모델로 비교하고 Edge 우회 요청을 포함한 통합 테스트를 실행합니다.",
relations: [
{
reason: "검증 기준",
label: "검증 기준",
summary: "",
title: "Authorization Code Flow에서 state와 nonce의 경계",
path: "/references/state-and-nonce-boundary",
},
{
reason: "이 프로젝트에서 추적함",
label: "이 프로젝트에서 추적함",
summary: "",
title: "Auth Lab 활동",
path: "/projects/auth-lab/activity#edge-trust-boundary",
@@ -624,13 +624,13 @@ const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
},
relations: [
{
reason: "이 Case로 해결됨",
label: "이 Case로 해결됨",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
{
reason: "적용 기준",
label: "적용 기준",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy",
@@ -14,6 +14,7 @@ import type {
LatestRecordEntry,
PublicContentQueries,
PublicTopic,
PublicTopicDetail,
} from "../../application/ports/public-content-queries.ts";
export type RecordFilters = {
@@ -132,6 +133,58 @@ export function listTopics(): PublicTopic[] {
.map((entry) => Object.freeze(entry));
}
/**
* 픽스처판 주제 한 편.
*
* <p>정적 카탈로그에는 축(variant)도 논지(thesis)도 없다 — 사람이 쓰는 글이라 픽스처가 지어낼
* 수 없다. 그래서 축은 비고, 기록만 종류별로 모은다. 화면은 축이 비면 축을 그리지 않는다.
*/
export function getTopicDetail(slug: string): PublicTopicDetail | undefined {
const records = listRecords().filter((record) => record.topicSlug === slug);
if (records.length === 0) return undefined;
const pick = (kind: RecordKind, label: string) =>
Object.freeze(
records
.filter((record) => record.kind === kind)
.map((record) =>
Object.freeze({
label,
title: record.title,
path: record.path,
summary: record.summary,
note: "",
priority: 0,
}),
),
);
const projects = new Map(
records
.filter((record) => record.projectSlug)
.map((record) => [
record.projectSlug,
Object.freeze({
label: "프로젝트",
title: record.projectTitle,
path: `/projects/${record.projectSlug}`,
summary: "",
note: "",
priority: 0,
}),
]),
);
return Object.freeze({
name: records[0]!.topic,
slug,
description: "",
thesis: "",
variantLabel: "",
variants: Object.freeze([]),
featuredCases: pick("CASE", "검증 기록"),
activeQuestions: pick("QUESTION", "열린 질문"),
relatedProjects: Object.freeze([...projects.values()]),
});
}
/**
* 픽스처판 "최근 기록". HTTP 어댑터가 서버에서 읽어 오는 것과 같은 의미를 픽스처에서 만든다 —
* 프로젝트 활동과 릴리스가 원천이다.
@@ -309,6 +362,9 @@ export const publicContentQueries = Object.freeze({
async listTopics() {
return listTopics();
},
async getTopicDetail(slug: string) {
return getTopicDetail(slug);
},
async getLatestEntries() {
return getLatestEntries();
},