From 642afa878cedc1940b833de2648fa8a565b0065e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Mon, 31 Aug 2026 11:04:42 +0900 Subject: [PATCH] =?UTF-8?q?fix:=20=EA=B4=80=EA=B3=84=20=EB=AA=A9=EB=A1=9D?= =?UTF-8?q?=EC=9D=B4=20=EC=82=AC=EB=9E=8C=EC=9D=B4=20=EC=9D=BD=EB=8A=94=20?= =?UTF-8?q?=EC=9D=B4=EB=A6=84=EA=B3=BC=20=EC=9A=94=EC=95=BD=EC=9D=84=20?= =?UTF-8?q?=EB=B3=B4=EC=97=AC=20=EC=A4=80=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reference 화면에 `supportingCases` 가 한글 라벨 없이 네 번 반복해서 나왔다. 라벨 표의 키가 계약이 실제로 주는 이름과 어긋나 있었기 때문이다 — `originCases`·`projectDecisions` 로 적혀 있었고 계약은 `supportingCases`· `relatedDecisions` 를 준다. 표에 없는 키는 그대로 화면에 나온다. Question 은 같은 결함을 이미 겪고 고친 자리다(주석에 남아 있다). 이번에는 표를 상수로 빼서 계약이 주는 이름 전부가 등록됐는지 확인할 수 있게 한다. 계약은 관계마다 요약도 함께 주는데 평탄화가 그것을 버렸다. 독자가 목록에서 보는 것이 제목뿐이라, 왜 이 기록이 걸려 있는지는 눌러 봐야 알 수 있었다. 요약을 흘려보내 제목 아래 두 줄로 보여 준다. 요약은 링크의 이름에서 뺀다 — 이름에 들어가면 관계 목록을 훑을 때 링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다. `cardSummary` 를 domain 으로 옮긴다. 어댑터가 presentation 을 import 하는 것을 아키텍처 규칙이 막았고, 그 지적이 옳다 — 이 함수는 화면이 아니라 글을 다루는 규칙이다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- .../http/http-public-content-gateway.ts | 45 ++++++++++++------- .../adapters/http/public-content-mapping.ts | 18 ++++++-- .../adapters/static/public-content.ts | 14 ++++++ .../ports/public-content-queries.ts | 2 + .../content-format}/card-summary.ts | 0 .../public/components/home-focus.tsx | 2 +- .../public/components/latest-index.tsx | 2 +- .../public/components/public-record-list.tsx | 2 +- .../public/components/search-dialog.tsx | 2 +- .../public-document-relations.tsx | 17 ++++++- .../tech-log/presentation/styles/globals.css | 3 ++ tests/component/highlight-match.test.tsx | 4 +- .../features/tech-log/public-render.test.tsx | 6 ++- 13 files changed, 89 insertions(+), 28 deletions(-) rename src/features/tech-log/{presentation/shared => domain/content-format}/card-summary.ts (100%) diff --git a/src/features/tech-log/adapters/http/http-public-content-gateway.ts b/src/features/tech-log/adapters/http/http-public-content-gateway.ts index 67bf30b..e91247a 100644 --- a/src/features/tech-log/adapters/http/http-public-content-gateway.ts +++ b/src/features/tech-log/adapters/http/http-public-content-gateway.ts @@ -63,6 +63,32 @@ function problemCode(problem: unknown): string { 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( deps: Readonly<{ operations: StudioOperationExecutor }>, ): PublicContentQueries { @@ -160,12 +186,7 @@ export function createHttpPublicContentGateway( primaryTopic: body.primaryTopic as never, primaryProject: body.primaryProject as never, publishedAt: body.publishedAt as string, - relations: flattenRelations(groups, { - originQuestion: "이 기록이 시작된 질문", - projectDecisions: "이 기록이 뒷받침하는 결정", - derivedReferences: "이 기록에서 정리된 기준", - relatedCases: "관련 기록", - }), + relations: flattenRelations(groups, CASE_RELATION_LABELS), }), kind: "CASE", problem: (body.problemSummary as string) ?? "", @@ -205,11 +226,7 @@ export function createHttpPublicContentGateway( primaryTopic: body.primaryTopic as never, primaryProject: body.primaryProject as never, publishedAt: body.publishedAt as string, - relations: flattenRelations(groups, { - originCases: "이 기준이 나온 기록", - projectDecisions: "이 기준을 따르는 결정", - relatedReferences: "관련 기준", - }), + relations: flattenRelations(groups, REFERENCE_RELATION_LABELS), }), kind: "REFERENCE", /* @@ -283,11 +300,7 @@ export function createHttpPublicContentGateway( producedDecision: groups.producedDecision, derivedReferences: groups.derivedReferences, }, - { - resultCase: "이 질문에서 나온 기록", - producedDecision: "이 질문이 이끈 결정", - derivedReferences: "이 질문에서 정리된 기준", - }, + QUESTION_RELATION_LABELS, ), }), kind: "QUESTION", diff --git a/src/features/tech-log/adapters/http/public-content-mapping.ts b/src/features/tech-log/adapters/http/public-content-mapping.ts index 35d7dd0..61061a6 100644 --- a/src/features/tech-log/adapters/http/public-content-mapping.ts +++ b/src/features/tech-log/adapters/http/public-content-mapping.ts @@ -10,6 +10,7 @@ import type { Release, SearchablePublicEntity, } 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. @@ -136,14 +137,23 @@ type Related = Readonly<{ type?: string; title?: string; summary?: string; path? export function flattenRelations( groups: Readonly>, labels: Readonly>, -): ReadonlyArray<{ reason: string; title: string; path: string }> { - const flat: { reason: string; title: string; path: string }[] = []; +): ReadonlyArray<{ reason: string; title: string; path: string; summary: string }> { + const flat: { reason: string; title: string; path: string; summary: string }[] = []; for (const [group, value] of Object.entries(groups)) { if (!value) continue; const reason = labels[group] ?? group; for (const entry of Array.isArray(value) ? value : [value as Related]) { 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); @@ -161,7 +171,7 @@ export function baseOf( primaryTopic?: Summary; primaryProject?: Summary; publishedAt?: string | null; - relations?: ReadonlyArray<{ reason: string; title: string; path: string }>; + relations?: ReadonlyArray<{ reason: string; title: string; path: string; summary: string }>; }>, ) { return { diff --git a/src/features/tech-log/adapters/static/public-content.ts b/src/features/tech-log/adapters/static/public-content.ts index 9986029..488c2b4 100644 --- a/src/features/tech-log/adapters/static/public-content.ts +++ b/src/features/tech-log/adapters/static/public-content.ts @@ -8,6 +8,7 @@ export type QuestionStatus = export type PublicRelation = { reason: string; + summary: string; title: string; path: string; }; @@ -298,16 +299,19 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "이 질문에서 시작됨", + summary: "", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", path: "/questions/collection-fetch-join-with-pagination", }, { reason: "이 Case로 결정함", + summary: "", title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.", path: "/projects/backend-skeleton/decisions#feed-pagination-boundary", }, { reason: "이 기준 문서로 정리됨", + summary: "", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", path: "/references/jpa-list-fetch-strategy", }, @@ -355,11 +359,13 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "이 프로젝트에 속함", + summary: "", title: "Backend Skeleton", path: "/projects/backend-skeleton", }, { reason: "이 결정과 연결됨", + summary: "", title: "StoragePort와 Adapter의 책임을 분리합니다.", path: "/projects/backend-skeleton/decisions#storage-port-unification", }, @@ -412,11 +418,13 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "이 질문의 검증 기준", + summary: "", title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?", path: "/questions/validate-edge-token-again", }, { reason: "이 프로젝트에 속함", + summary: "", title: "Auth Lab", path: "/projects/auth-lab", }, @@ -469,11 +477,13 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "이 Case에서 측정함", + summary: "", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", path: "/cases/collection-fetch-join-pagination", }, { reason: "이 질문을 해결함", + summary: "", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", path: "/questions/collection-fetch-join-with-pagination", }, @@ -524,11 +534,13 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "검증 기준", + summary: "", title: "Authorization Code Flow에서 state와 nonce의 경계", path: "/references/state-and-nonce-boundary", }, { reason: "이 프로젝트에서 추적함", + summary: "", title: "Auth Lab 활동", path: "/projects/auth-lab/activity#edge-trust-boundary", }, @@ -581,11 +593,13 @@ export const publicRecords: ReadonlyArray = [ relations: [ { reason: "이 Case로 해결됨", + summary: "", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", path: "/cases/collection-fetch-join-pagination", }, { reason: "적용 기준", + summary: "", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", path: "/references/jpa-list-fetch-strategy", }, diff --git a/src/features/tech-log/application/ports/public-content-queries.ts b/src/features/tech-log/application/ports/public-content-queries.ts index 42b2808..5992bba 100644 --- a/src/features/tech-log/application/ports/public-content-queries.ts +++ b/src/features/tech-log/application/ports/public-content-queries.ts @@ -9,6 +9,8 @@ export type QuestionStatus = export type PublicRelation = { reason: string; + /** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */ + summary: string; title: string; path: string; }; diff --git a/src/features/tech-log/presentation/shared/card-summary.ts b/src/features/tech-log/domain/content-format/card-summary.ts similarity index 100% rename from src/features/tech-log/presentation/shared/card-summary.ts rename to src/features/tech-log/domain/content-format/card-summary.ts diff --git a/src/features/tech-log/presentation/public/components/home-focus.tsx b/src/features/tech-log/presentation/public/components/home-focus.tsx index 6b83d31..0268661 100644 --- a/src/features/tech-log/presentation/public/components/home-focus.tsx +++ b/src/features/tech-log/presentation/public/components/home-focus.tsx @@ -9,7 +9,7 @@ import { moveFocus, shouldNormalizeFocusUrl, } from "../../../domain/public/focus-state.ts"; -import { cardSummary } from "../../shared/card-summary.ts"; +import { cardSummary } from "../../../domain/content-format/card-summary.ts"; type HomeFocusProps = { items: ReadonlyArray; diff --git a/src/features/tech-log/presentation/public/components/latest-index.tsx b/src/features/tech-log/presentation/public/components/latest-index.tsx index 536c606..4760baa 100644 --- a/src/features/tech-log/presentation/public/components/latest-index.tsx +++ b/src/features/tech-log/presentation/public/components/latest-index.tsx @@ -1,5 +1,5 @@ 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 = { id: string; diff --git a/src/features/tech-log/presentation/public/components/public-record-list.tsx b/src/features/tech-log/presentation/public/components/public-record-list.tsx index 0686b9d..d1d4e2e 100644 --- a/src/features/tech-log/presentation/public/components/public-record-list.tsx +++ b/src/features/tech-log/presentation/public/components/public-record-list.tsx @@ -2,7 +2,7 @@ import { Link } from "react-router-dom"; import type { PublicRecord } from "../../../application/ports/public-content-queries.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({ records, diff --git a/src/features/tech-log/presentation/public/components/search-dialog.tsx b/src/features/tech-log/presentation/public/components/search-dialog.tsx index 3263c74..0563c87 100644 --- a/src/features/tech-log/presentation/public/components/search-dialog.tsx +++ b/src/features/tech-log/presentation/public/components/search-dialog.tsx @@ -3,7 +3,7 @@ import { Link } from "react-router-dom"; import { usePublicContent } from "../use-public-content.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 = { className?: string; diff --git a/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx b/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx index 41cad1c..7488381 100644 --- a/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx +++ b/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx @@ -1,9 +1,12 @@ import { Link } from "react-router-dom"; export type PublicRelation = Readonly<{ + /** 왜 걸려 있는지 — 관계 묶음의 사람이 읽는 이름. */ reason: string; title: string; path: string; + /** 대상 문서의 요약. 눌러 보지 않고도 무엇인지 알게 한다. */ + summary?: string; }>; export function PublicDocumentRelations({ @@ -26,7 +29,19 @@ export function PublicDocumentRelations({
  • {relation.reason} - {relation.title} +
    + {relation.title} + {/* + 계약은 관계마다 요약을 함께 준다. 예전에는 그것을 버려서 목록에 제목만 남았고, + 독자는 왜 이 기록이 걸려 있는지 눌러 봐야 알 수 있었다. + */} + {/* + 링크의 이름은 「관계 이름 + 제목」으로 둔다. 요약까지 이름에 들어가면 관계 + 목록을 훑을 때 링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다. + 요약은 눈으로 보는 보조 정보이고, 전문은 눌러 들어가면 있다. + */} + {relation.summary ? : null} +
  • diff --git a/src/features/tech-log/presentation/styles/globals.css b/src/features/tech-log/presentation/styles/globals.css index 8f957c7..d6b3135 100644 --- a/src/features/tech-log/presentation/styles/globals.css +++ b/src/features/tech-log/presentation/styles/globals.css @@ -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 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 > 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 strong { font-size: 14px; font-weight: 600; } .document-relations a:hover strong { color: var(--signal); } diff --git a/tests/component/highlight-match.test.tsx b/tests/component/highlight-match.test.tsx index b01b5b9..7e89da9 100644 --- a/tests/component/highlight-match.test.tsx +++ b/tests/component/highlight-match.test.tsx @@ -45,7 +45,7 @@ describe("검색어 강조", () => { describe("카드 요약", () => { it("백틱을 지우고 줄바꿈을 접는다", async () => { 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( "모두 하나의 로그인 상태로 보면 안 된다. 두 번째 문단.", @@ -54,7 +54,7 @@ describe("카드 요약", () => { it("빈 값이면 빈 문자열을 준다", async () => { 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(" ")).toBe(""); diff --git a/tests/features/tech-log/public-render.test.tsx b/tests/features/tech-log/public-render.test.tsx index 3ed3745..bb9ad4e 100644 --- a/tests/features/tech-log/public-render.test.tsx +++ b/tests/features/tech-log/public-render.test.tsx @@ -379,7 +379,11 @@ describe("shared Public record renderer", () => { ); expect(screen.getByText("목차 · 강조 강함 코드")).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.parentElement?.parentElement?.previousElementSibling).toHaveTextContent( "이 기록의 연결",