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
@@ -8,7 +8,8 @@ export type QuestionStatus =
| "ARCHIVED";
export type PublicRelation = {
reason: string;
/** 묶음 이름. 「근거」「적용 기준」처럼 분류다. 문장이 아니다. */
label: string;
/** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */
summary: string;
/** 작성자가 남긴 이유. 「다음에 무엇을 읽을지」의 답이다. */
@@ -193,6 +194,43 @@ export type PublicTopic = {
recordCount: number;
};
/**
* 주제 안의 접근/구조 하나.
*
* <p>이 주제가 답하는 질문에 대해 실제로 만들어 본 답이 하나씩이다. 인증 경계라면 SPA·BFF·
* Mediator 가 각각 하나고, 각자 무엇을 알게 됐는지({@link conclusion})가 다르다. 그 결론이
* 이 기록의 값어치이므로 비교표가 읽는 칸도 요약이 아니라 결론이다.
*/
export type PublicTopicVariant = {
slug: string;
title: string;
path: string;
summary: string;
/** 만들어 보고 무엇을 알게 됐는가. 비어 있으면 아직 아무도 쓰지 않은 것이다. */
conclusion: string;
recordCount: number;
};
/**
* 주제 한 편. 목록의 {@link PublicTopic} 과 달리 주제 화면이 통째로 쓰는 모양이다.
*
* <p>주제 화면은 오래 주제 셋을 코드에 적어 두고 그 셋만 열었다. 새 주제를 만들면 화면이
* 404 로 갔고, 계약에 이미 있던 `/topics/{slug}` 는 아무도 부르지 않았다.
*/
export type PublicTopicDetail = {
name: string;
slug: string;
description: string;
/** 이 주제가 답하는 질문. 사람이 쓴 한 문단이고, 기록을 합쳐 만들지 않는다. */
thesis: string;
/** 축의 이름. 「구조」「조회 전략」처럼 독자에게 보일 말이다. 비면 축을 쓰지 않는 주제다. */
variantLabel: string;
variants: ReadonlyArray<PublicTopicVariant>;
featuredCases: ReadonlyArray<PublicRelation>;
activeQuestions: ReadonlyArray<PublicRelation>;
relatedProjects: ReadonlyArray<PublicRelation>;
};
/**
* 홈의 "최근 기록" 한 줄. 서버가 공개 투영에서 직접 고른다.
*
@@ -274,6 +312,8 @@ export type PublicContentQueries = Readonly<{
* 있었고, Studio 에서 주제를 만들어도 바뀌지 않았다.
*/
listTopics(): Promise<PublicTopic[]>;
/** 주제 한 편. 주제가 없으면 `undefined`. */
getTopicDetail(slug: string): Promise<PublicTopicDetail | undefined>;
getLatestEntries(): Promise<LatestRecordEntry[]>;
getHomeFocusItems(): Promise<HomeFocusItem[]>;
searchPublicContent(query: string): Promise<SearchablePublicEntity[]>;