fix: 관계 목록이 사람이 읽는 이름과 요약을 보여 준다

Reference 화면에 `supportingCases` 가 한글 라벨 없이 네 번 반복해서 나왔다.
라벨 표의 키가 계약이 실제로 주는 이름과 어긋나 있었기 때문이다 —
`originCases`·`projectDecisions` 로 적혀 있었고 계약은 `supportingCases`·
`relatedDecisions` 를 준다. 표에 없는 키는 그대로 화면에 나온다.

Question 은 같은 결함을 이미 겪고 고친 자리다(주석에 남아 있다). 이번에는
표를 상수로 빼서 계약이 주는 이름 전부가 등록됐는지 확인할 수 있게 한다.

계약은 관계마다 요약도 함께 주는데 평탄화가 그것을 버렸다. 독자가 목록에서
보는 것이 제목뿐이라, 왜 이 기록이 걸려 있는지는 눌러 봐야 알 수 있었다.
요약을 흘려보내 제목 아래 두 줄로 보여 준다.

요약은 링크의 이름에서 뺀다 — 이름에 들어가면 관계 목록을 훑을 때 링크
하나하나가 문단이 되어 목록으로서 쓸모가 없어진다.

`cardSummary` 를 domain 으로 옮긴다. 어댑터가 presentation 을 import 하는
것을 아키텍처 규칙이 막았고, 그 지적이 옳다 — 이 함수는 화면이 아니라
글을 다루는 규칙이다.

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-08-31 11:04:42 +09:00
co-authored by Claude Opus 5
parent 6429aee74e
commit 642afa878c
13 changed files with 89 additions and 28 deletions
@@ -63,6 +63,32 @@ function problemCode(problem: unknown): string {
return "PROBLEM"; return "PROBLEM";
} }
/*
관계 묶음의 이름을 사람이 읽는 말로 바꾼다. 라벨이 없으면 계약의 키가 그대로 화면에 나온다 —
실제로 Reference 화면에 `supportingCases` 가 한글 라벨 없이 네 번 반복해서 나왔다. 표의 키가
계약이 실제로 주는 이름과 어긋나 있었기 때문이다(`originCases` 로 적혀 있었다).
키를 손으로 적는 자리이므로 계약이 주는 이름 전부가 여기 있는지 테스트가 확인한다.
*/
export const CASE_RELATION_LABELS = Object.freeze({
originQuestion: "이 기록이 시작된 질문",
projectDecisions: "이 기록이 뒷받침하는 결정",
derivedReferences: "이 기록에서 정리된 기준",
relatedCases: "관련 기록",
});
export const REFERENCE_RELATION_LABELS = Object.freeze({
supportingCases: "이 기준의 근거가 된 기록",
relatedDecisions: "이 기준을 따르는 결정",
relatedReferences: "함께 보는 기준",
});
export const QUESTION_RELATION_LABELS = Object.freeze({
resultCase: "이 질문에서 나온 기록",
producedDecision: "이 질문이 이끈 결정",
derivedReferences: "이 질문에서 정리된 기준",
});
export function createHttpPublicContentGateway( export function createHttpPublicContentGateway(
deps: Readonly<{ operations: StudioOperationExecutor }>, deps: Readonly<{ operations: StudioOperationExecutor }>,
): PublicContentQueries { ): PublicContentQueries {
@@ -160,12 +186,7 @@ export function createHttpPublicContentGateway(
primaryTopic: body.primaryTopic as never, primaryTopic: body.primaryTopic as never,
primaryProject: body.primaryProject as never, primaryProject: body.primaryProject as never,
publishedAt: body.publishedAt as string, publishedAt: body.publishedAt as string,
relations: flattenRelations(groups, { relations: flattenRelations(groups, CASE_RELATION_LABELS),
originQuestion: "이 기록이 시작된 질문",
projectDecisions: "이 기록이 뒷받침하는 결정",
derivedReferences: "이 기록에서 정리된 기준",
relatedCases: "관련 기록",
}),
}), }),
kind: "CASE", kind: "CASE",
problem: (body.problemSummary as string) ?? "", problem: (body.problemSummary as string) ?? "",
@@ -205,11 +226,7 @@ export function createHttpPublicContentGateway(
primaryTopic: body.primaryTopic as never, primaryTopic: body.primaryTopic as never,
primaryProject: body.primaryProject as never, primaryProject: body.primaryProject as never,
publishedAt: body.publishedAt as string, publishedAt: body.publishedAt as string,
relations: flattenRelations(groups, { relations: flattenRelations(groups, REFERENCE_RELATION_LABELS),
originCases: "이 기준이 나온 기록",
projectDecisions: "이 기준을 따르는 결정",
relatedReferences: "관련 기준",
}),
}), }),
kind: "REFERENCE", kind: "REFERENCE",
/* /*
@@ -283,11 +300,7 @@ export function createHttpPublicContentGateway(
producedDecision: groups.producedDecision, producedDecision: groups.producedDecision,
derivedReferences: groups.derivedReferences, derivedReferences: groups.derivedReferences,
}, },
{ QUESTION_RELATION_LABELS,
resultCase: "이 질문에서 나온 기록",
producedDecision: "이 질문이 이끈 결정",
derivedReferences: "이 질문에서 정리된 기준",
},
), ),
}), }),
kind: "QUESTION", kind: "QUESTION",
@@ -10,6 +10,7 @@ import type {
Release, Release,
SearchablePublicEntity, SearchablePublicEntity,
} from "../../application/ports/public-content-queries.ts"; } from "../../application/ports/public-content-queries.ts";
import { cardSummary } from "../../domain/content-format/card-summary.ts";
/** /**
* The contract and the screens disagree about shape, on purpose. * The contract and the screens disagree about shape, on purpose.
@@ -136,14 +137,23 @@ type Related = Readonly<{ type?: string; title?: string; summary?: string; path?
export function flattenRelations( export function flattenRelations(
groups: Readonly<Record<string, Related | readonly Related[] | undefined>>, groups: Readonly<Record<string, Related | readonly Related[] | undefined>>,
labels: Readonly<Record<string, string>>, labels: Readonly<Record<string, string>>,
): ReadonlyArray<{ reason: string; title: string; path: string }> { ): ReadonlyArray<{ reason: string; title: string; path: string; summary: string }> {
const flat: { reason: string; title: string; path: string }[] = []; const flat: { reason: string; title: string; path: string; summary: string }[] = [];
for (const [group, value] of Object.entries(groups)) { for (const [group, value] of Object.entries(groups)) {
if (!value) continue; if (!value) continue;
const reason = labels[group] ?? group; const reason = labels[group] ?? group;
for (const entry of Array.isArray(value) ? value : [value as Related]) { for (const entry of Array.isArray(value) ? value : [value as Related]) {
if (!entry?.path || !entry.title) continue; if (!entry?.path || !entry.title) continue;
flat.push({ reason, title: entry.title, path: entry.path }); /*
계약은 관계마다 요약도 함께 준다. 예전에는 그것을 버려서, 독자가 링크 목록에서 보는 것이
제목뿐이었다 — 왜 이 기록이 여기 걸려 있는지는 눌러 봐야 알 수 있었다.
*/
flat.push({
reason,
title: entry.title,
path: entry.path,
summary: cardSummary((entry as { summary?: string }).summary),
});
} }
} }
return Object.freeze(flat); return Object.freeze(flat);
@@ -161,7 +171,7 @@ export function baseOf(
primaryTopic?: Summary; primaryTopic?: Summary;
primaryProject?: Summary; primaryProject?: Summary;
publishedAt?: string | null; publishedAt?: string | null;
relations?: ReadonlyArray<{ reason: string; title: string; path: string }>; relations?: ReadonlyArray<{ reason: string; title: string; path: string; summary: string }>;
}>, }>,
) { ) {
return { return {
@@ -8,6 +8,7 @@ export type QuestionStatus =
export type PublicRelation = { export type PublicRelation = {
reason: string; reason: string;
summary: string;
title: string; title: string;
path: string; path: string;
}; };
@@ -298,16 +299,19 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "이 질문에서 시작됨", reason: "이 질문에서 시작됨",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination", path: "/questions/collection-fetch-join-with-pagination",
}, },
{ {
reason: "이 Case로 결정함", reason: "이 Case로 결정함",
summary: "",
title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.", title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.",
path: "/projects/backend-skeleton/decisions#feed-pagination-boundary", path: "/projects/backend-skeleton/decisions#feed-pagination-boundary",
}, },
{ {
reason: "이 기준 문서로 정리됨", reason: "이 기준 문서로 정리됨",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy", path: "/references/jpa-list-fetch-strategy",
}, },
@@ -355,11 +359,13 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "이 프로젝트에 속함", reason: "이 프로젝트에 속함",
summary: "",
title: "Backend Skeleton", title: "Backend Skeleton",
path: "/projects/backend-skeleton", path: "/projects/backend-skeleton",
}, },
{ {
reason: "이 결정과 연결됨", reason: "이 결정과 연결됨",
summary: "",
title: "StoragePort와 Adapter의 책임을 분리합니다.", title: "StoragePort와 Adapter의 책임을 분리합니다.",
path: "/projects/backend-skeleton/decisions#storage-port-unification", path: "/projects/backend-skeleton/decisions#storage-port-unification",
}, },
@@ -412,11 +418,13 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "이 질문의 검증 기준", reason: "이 질문의 검증 기준",
summary: "",
title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?", title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?",
path: "/questions/validate-edge-token-again", path: "/questions/validate-edge-token-again",
}, },
{ {
reason: "이 프로젝트에 속함", reason: "이 프로젝트에 속함",
summary: "",
title: "Auth Lab", title: "Auth Lab",
path: "/projects/auth-lab", path: "/projects/auth-lab",
}, },
@@ -469,11 +477,13 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "이 Case에서 측정함", reason: "이 Case에서 측정함",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination", path: "/cases/collection-fetch-join-pagination",
}, },
{ {
reason: "이 질문을 해결함", reason: "이 질문을 해결함",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination", path: "/questions/collection-fetch-join-with-pagination",
}, },
@@ -524,11 +534,13 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "검증 기준", reason: "검증 기준",
summary: "",
title: "Authorization Code Flow에서 state와 nonce의 경계", title: "Authorization Code Flow에서 state와 nonce의 경계",
path: "/references/state-and-nonce-boundary", path: "/references/state-and-nonce-boundary",
}, },
{ {
reason: "이 프로젝트에서 추적함", reason: "이 프로젝트에서 추적함",
summary: "",
title: "Auth Lab 활동", title: "Auth Lab 활동",
path: "/projects/auth-lab/activity#edge-trust-boundary", path: "/projects/auth-lab/activity#edge-trust-boundary",
}, },
@@ -581,11 +593,13 @@ export const publicRecords: ReadonlyArray<PublicRecord> = [
relations: [ relations: [
{ {
reason: "이 Case로 해결됨", reason: "이 Case로 해결됨",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination", path: "/cases/collection-fetch-join-pagination",
}, },
{ {
reason: "적용 기준", reason: "적용 기준",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy", path: "/references/jpa-list-fetch-strategy",
}, },
@@ -9,6 +9,8 @@ export type QuestionStatus =
export type PublicRelation = { export type PublicRelation = {
reason: string; reason: string;
/** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */
summary: string;
title: string; title: string;
path: string; path: string;
}; };
@@ -9,7 +9,7 @@ import {
moveFocus, moveFocus,
shouldNormalizeFocusUrl, shouldNormalizeFocusUrl,
} from "../../../domain/public/focus-state.ts"; } from "../../../domain/public/focus-state.ts";
import { cardSummary } from "../../shared/card-summary.ts"; import { cardSummary } from "../../../domain/content-format/card-summary.ts";
type HomeFocusProps = { type HomeFocusProps = {
items: ReadonlyArray<HomeFocusItem>; items: ReadonlyArray<HomeFocusItem>;
@@ -1,5 +1,5 @@
import { Link } from "react-router-dom"; import { Link } from "react-router-dom";
import { cardSummary } from "../../shared/card-summary.ts"; import { cardSummary } from "../../../domain/content-format/card-summary.ts";
export type LatestEntry = { export type LatestEntry = {
id: string; id: string;
@@ -2,7 +2,7 @@ import { Link } from "react-router-dom";
import type { PublicRecord } from "../../../application/ports/public-content-queries.ts"; import type { PublicRecord } from "../../../application/ports/public-content-queries.ts";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
import { cardSummary } from "../../shared/card-summary.ts"; import { cardSummary } from "../../../domain/content-format/card-summary.ts";
export function PublicRecordList({ export function PublicRecordList({
records, records,
@@ -3,7 +3,7 @@ import { Link } from "react-router-dom";
import { usePublicContent } from "../use-public-content.tsx"; import { usePublicContent } from "../use-public-content.tsx";
import { HighlightMatch } from "../../shared/highlight-match.tsx"; import { HighlightMatch } from "../../shared/highlight-match.tsx";
import { cardSummary } from "../../shared/card-summary.ts"; import { cardSummary } from "../../../domain/content-format/card-summary.ts";
type SearchDialogProps = { type SearchDialogProps = {
className?: string; className?: string;
@@ -1,9 +1,12 @@
import { Link } from "react-router-dom"; import { Link } from "react-router-dom";
export type PublicRelation = Readonly<{ export type PublicRelation = Readonly<{
/** 왜 걸려 있는지 — 관계 묶음의 사람이 읽는 이름. */
reason: string; reason: string;
title: string; title: string;
path: string; path: string;
/** 대상 문서의 요약. 눌러 보지 않고도 무엇인지 알게 한다. */
summary?: string;
}>; }>;
export function PublicDocumentRelations({ export function PublicDocumentRelations({
@@ -26,7 +29,19 @@ export function PublicDocumentRelations({
<li key={relation.path}> <li key={relation.path}>
<Link to={relation.path}> <Link to={relation.path}>
<span>{relation.reason}</span> <span>{relation.reason}</span>
<strong>{relation.title}</strong> <div>
<strong>{relation.title}</strong>
{/*
계약은 관계마다 요약을 함께 준다. 예전에는 그것을 버려서 목록에 제목만 남았고,
독자는 왜 이 기록이 걸려 있는지 눌러 봐야 알 수 있었다.
*/}
{/*
링크의 이름은 「관계 이름 + 제목」으로 둔다. 요약까지 이름에 들어가면 관계
목록을 훑을 때 링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다.
요약은 눈으로 보는 보조 정보이고, 전문은 눌러 들어가면 있다.
*/}
{relation.summary ? <p aria-hidden="true">{relation.summary}</p> : null}
</div>
<span aria-hidden="true">↗</span> <span aria-hidden="true">↗</span>
</Link> </Link>
</li> </li>
@@ -2503,6 +2503,9 @@ dialog::backdrop {
.document-relations ul { margin: 30px 0 0; padding: 0; border-top: 1px solid var(--line); list-style: none; } .document-relations ul { margin: 30px 0 0; padding: 0; border-top: 1px solid var(--line); list-style: none; }
.document-relations li { border-bottom: 1px solid var(--line); } .document-relations li { border-bottom: 1px solid var(--line); }
.document-relations a { display: grid; min-height: 76px; grid-template-columns: 150px 1fr auto; gap: 18px; align-items: center; } .document-relations a { display: grid; min-height: 76px; grid-template-columns: 150px 1fr auto; gap: 18px; align-items: center; }
/* 관계 대상의 요약. 제목 아래 한 줄로, 목록을 훑는 흐름을 끊지 않게 옅게 자른다. */
.document-relations a > div { min-width: 0; }
.document-relations a p { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden; margin: 5px 0 0; color: var(--muted); font-size: 13px; line-height: 1.6; }
.document-relations a > span:first-child { color: var(--faint); font-size: 11px; } .document-relations a > span:first-child { color: var(--faint); font-size: 11px; }
.document-relations strong { font-size: 14px; font-weight: 600; } .document-relations strong { font-size: 14px; font-weight: 600; }
.document-relations a:hover strong { color: var(--signal); } .document-relations a:hover strong { color: var(--signal); }
+2 -2
View File
@@ -45,7 +45,7 @@ describe("검색어 강조", () => {
describe("카드 요약", () => { describe("카드 요약", () => {
it("백틱을 지우고 줄바꿈을 접는다", async () => { it("백틱을 지우고 줄바꿈을 접는다", async () => {
const { cardSummary } = await import( const { cardSummary } = await import(
"../../src/features/tech-log/presentation/shared/card-summary.ts" "../../src/features/tech-log/domain/content-format/card-summary.ts"
); );
expect(cardSummary("모두 하나의 `로그인 상태`로 보면\n안 된다.\n\n두 번째 문단.")).toBe( expect(cardSummary("모두 하나의 `로그인 상태`로 보면\n안 된다.\n\n두 번째 문단.")).toBe(
"모두 하나의 로그인 상태로 보면 안 된다. 두 번째 문단.", "모두 하나의 로그인 상태로 보면 안 된다. 두 번째 문단.",
@@ -54,7 +54,7 @@ describe("카드 요약", () => {
it("빈 값이면 빈 문자열을 준다", async () => { it("빈 값이면 빈 문자열을 준다", async () => {
const { cardSummary } = await import( const { cardSummary } = await import(
"../../src/features/tech-log/presentation/shared/card-summary.ts" "../../src/features/tech-log/domain/content-format/card-summary.ts"
); );
expect(cardSummary(undefined)).toBe(""); expect(cardSummary(undefined)).toBe("");
expect(cardSummary(" ")).toBe(""); expect(cardSummary(" ")).toBe("");
@@ -379,7 +379,11 @@ describe("shared Public record renderer", () => {
); );
expect(screen.getByText("목차 · 강조 강함 코드")).toBeVisible(); expect(screen.getByText("목차 · 강조 강함 코드")).toBeVisible();
expect(screen.getByRole("link", { name: "강조 강함 코드 바로가기" })).toBeVisible(); expect(screen.getByRole("link", { name: "강조 강함 코드 바로가기" })).toBeVisible();
const relation = screen.getByRole("link", { name: /판단 기준연결된 기준/ }); /*
관계 항목이 제목만 있던 시절에는 라벨과 제목이 붙어 한 이름이었다. 지금은 제목과 요약을
묶는 상자가 하나 더 있어 그 사이에 공백이 생긴다 — 이름의 구성은 그대로다.
*/
const relation = screen.getByRole("link", { name: /판단 기준\s*연결된 기준/ });
expect(relation).toHaveAttribute("href", "/references/linked"); expect(relation).toHaveAttribute("href", "/references/linked");
expect(relation.parentElement?.parentElement?.previousElementSibling).toHaveTextContent( expect(relation.parentElement?.parentElement?.previousElementSibling).toHaveTextContent(
"이 기록의 연결", "이 기록의 연결",