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,6 +7,7 @@ import type {
PublicContentQueries,
PublicRecord,
PublicTopic,
PublicTopicDetail,
QuestionRecord,
RecordFilters,
RecordKind,
@@ -26,6 +27,7 @@ import {
releaseDetailToRelease,
searchItemToEntity,
} from "./public-content-mapping.ts";
import { cardSummary } from "../../domain/content-format/card-summary.ts";
import type { components } from "../../contracts/public/generated.ts";
import type { StudioOperationExecutor } from "./http-studio-gateway.ts";
@@ -388,7 +390,12 @@ export function createHttpPublicContentGateway(
slug,
title: String(body.name ?? ""),
summary: String(body.oneLinePurpose ?? ""),
thesis: String(body.purpose ?? body.oneLinePurpose ?? ""),
/*
논지는 이 프로젝트가 무엇을 밝혔는가다. 담을 칸이 없던 동안 목적(`purpose`)을 대신
보여 줬는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다.
아직 아무도 쓰지 않은 프로젝트는 예전 자리로 물러선다 — 빈 화면보다는 낫다.
*/
thesis: String(body.thesis || body.purpose || body.oneLinePurpose || ""),
stage: body.phase === "VALIDATION" ? "VALIDATION" : "DESIGN",
currentGoal: String(body.currentObjective ?? ""),
nextStep: String(body.nextStep ?? ""),
@@ -445,6 +452,59 @@ export function createHttpPublicContentGateway(
);
}
/**
* 주제 한 편.
*
* <p>계약은 이 자리에 관계 묶음을 세 개 준다 — 대표 Case, 열린 질문, 관련 프로젝트. 화면이
* 쓰는 모양은 관계 한 줄과 같으므로 그대로 옮긴다. 작성자가 남긴 문장(`reason`)이 있으면
* 목록에서 그것이 먼저 보인다.
*/
async function getTopicDetail(slug: string): Promise<PublicTopicDetail | undefined> {
const detail = await read<Readonly<Record<string, unknown>>>("getPublicTopic", {
topicSlug: slug,
});
if (detail === NOT_FOUND) return undefined;
const topic = (detail.topic as Readonly<Record<string, unknown>>) ?? {};
const entries = (value: unknown, label: string) =>
Object.freeze(
((value as readonly Readonly<Record<string, unknown>>[] | undefined) ?? [])
.filter((entry) => entry.path && entry.title)
.map((entry) =>
Object.freeze({
label,
title: String(entry.title ?? ""),
path: String(entry.path ?? ""),
summary: cardSummary(entry.summary as string | undefined),
note: String(entry.reason ?? "").trim(),
priority: Number(entry.priority ?? 0),
}),
),
);
return Object.freeze({
name: String(topic.name ?? ""),
slug: String(topic.slug ?? slug),
description: String(topic.description ?? ""),
thesis: String(topic.thesis ?? ""),
variantLabel: String(topic.variantLabel ?? ""),
variants: Object.freeze(
((detail.variants as readonly Readonly<Record<string, unknown>>[] | undefined) ?? []).map(
(variant) =>
Object.freeze({
slug: String(variant.slug ?? ""),
title: String(variant.title ?? ""),
path: String(variant.path ?? ""),
summary: String(variant.summary ?? ""),
conclusion: String(variant.conclusion ?? ""),
recordCount: Number(variant.recordCount ?? 0),
}),
),
),
featuredCases: entries(detail.featuredCases, "검증 기록"),
activeQuestions: entries(detail.activeQuestions, "열린 질문"),
relatedProjects: entries(detail.relatedProjects, "프로젝트"),
});
}
/**
* 공개 투영이 고른 최근 기록. `entryType` 은 계약이 네 값만 허용하므로 그대로 믿고 쓴다 —
* 서버가 이미 걸러 보낸다.
@@ -611,6 +671,7 @@ export function createHttpPublicContentGateway(
getProject,
getRelease,
listTopics,
getTopicDetail,
getProjectRecords,
getProjectDecisions,
getProjectActivity,
@@ -143,7 +143,7 @@ type Related = Readonly<{
* label. Flattening keeps the group name as that label.
*/
type PublicRelationEntry = {
reason: string;
label: string;
title: string;
path: string;
summary: string;
@@ -158,7 +158,7 @@ export function flattenRelations(
const flat: PublicRelationEntry[] = [];
for (const [group, value] of Object.entries(groups)) {
if (!value) continue;
const reason = labels[group] ?? group;
const label = labels[group] ?? group;
for (const entry of Array.isArray(value) ? value : [value as Related]) {
if (!entry?.path || !entry.title) continue;
/*
@@ -166,7 +166,7 @@ export function flattenRelations(
제목뿐이었다 — 왜 이 기록이 여기 걸려 있는지는 눌러 봐야 알 수 있었다.
*/
flat.push({
reason,
label,
title: entry.title,
path: entry.path,
summary: cardSummary(entry.summary),
@@ -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();
},