Files
tech-log-frontend/src/features/tech-log/presentation/public/pages/topic-page.tsx
T
DongHyeonkaandClaude Opus 5 dc2fda7a5d fix: 종류 이름을 화면마다 하나로 맞추고, 읽는 순서를 기록에서 만든다
홈 한 화면에 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 `CASE`·`CONCEPT`·`OPEN
QUESTION`·`REFERENCE` 로, 바로 아래 「종류별로 읽기」는 「검증 기록」·「동작 원리」·
「적용 기준」·「열린 질문」으로 같은 넷을 불렀다. 독자는 둘이 같은 것이라는 단서를 어디서도
받지 못했다 — 이름을 바꾸기 전보다 나빠진 유일한 자리다. 목록도 공용 표에서 가져온다.

주제 허브의 「먼저 읽을 것」은 넷 다 열린 질문이었다. 서버가 주는 대표 값은 순서가 아니라
통 두 개(대표 Case · 열린 질문)이고 앞쪽이 비어 있어서, 아직 답이 없는 질문만 모아 놓고
「먼저 읽을 것」이라 부르고 있었다. 그리고 그 넷이 바로 아래 목록에 그대로 다시 나왔다.
이제 기록에서 순서를 만든다 — 원리 → 확인한 기록 → 기준 → 아직 모르는 것 — 그리고 위에
오른 편은 아래에서 뺀다.

개념은 목록 매퍼에서 통째로 버려지고 있었다. 서버는 보내고 필터에는 「동작 원리」가 있는데
결과가 0건이라, 독자에게는 기록이 없는 것으로 보였다. 손으로 나열한 종류 목록에 개념을
빠뜨리는 일이 이 저장소에서 반복됐고, 이번에는 계약에서 종류를 읽어 대조하는 가드를 둔다.

그 밖에: 질문 줄의 맥락이 「· 프로젝트」로 시작하던 것(계약에 주제가 없었다), 릴리스가
주 내비에서만 빠지고 홈 목록에는 남아 있던 것, 홈 목록이 화면의 절반을 차지하던 것,
값이 없는 「현재 목표」·「다음 작업」이 빈 칸으로 남던 것, 종류 배지 넷이 시각적으로 같던 것.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 18:36:52 +09:00

146 lines
6.7 KiB
TypeScript

import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { PublicDocumentRelations } from "../../shared/public-render/public-document-relations.tsx";
import { ProseText } from "../../shared/public-render/prose-text.tsx";
import type {
PublicRecord,
RecordKind,
} from "../../../application/ports/public-content-queries.ts";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
import { PublicRecordList } from "../components/public-record-list.tsx";
import { usePublicContent } from "../use-public-content.tsx";
/**
* 읽는 순서.
*
* <p>서버가 주는 대표 기록(`featuredCases`/`featuredReference`)은 작성자가 주제마다 손으로
* 골라 두는 값이라 대부분 비어 있다. 비어 있으면 열린 질문만 남아, 아직 답이 없는 질문 넷을
* 모아 두고 「먼저 읽을 것」이라 부르게 된다 — 처음 온 사람에게 가장 나쁜 첫 화면이다.
*
* <p>그래서 기록 자체에서 순서를 만든다. 원리를 먼저 알고, 그것을 확인한 기록을 보고, 거기서
* 나온 기준을 읽고, 아직 답하지 못한 것을 마지막에 본다.
*
* <p>서버의 대표 값을 쓰지 않는 이유는 그것이 순서가 아니라 통 두 개(대표 Case · 열린 질문)라
* 서다. 통을 이어 붙이면 기준이 통째로 빠지고, 채워져 있는 쪽이 질문뿐일 때는 질문만 남는다.
*/
const READING_ORDER: ReadonlyArray<RecordKind> = ["CONCEPT", "CASE", "REFERENCE", "QUESTION"];
/** 한 종류에서 앞의 몇 편까지. 넘으면 순서가 아니라 목록이 된다. */
const PER_KIND = 2;
function firstReads(records: ReadonlyArray<PublicRecord>) {
return READING_ORDER.flatMap((kind) =>
records
.filter((record) => record.kind === kind)
.slice(0, PER_KIND)
.map((record) => ({
label: DOCUMENT_KIND_LABELS[record.kind],
title: record.title,
path: record.path,
summary: record.summary,
})),
);
}
/**
* 주제 한 편.
*
* <p>이 화면은 오래 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만 열었다.
* 제목과 설명까지 코드에 있었고, 새 주제를 만들면 화면이 그대로 404 로 갔다 — 계약에는 처음부터
* `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. 손으로 나열한 목록에 새 것을 빠뜨리는 일이
* 이 저장소에서 반복됐고, 여기서는 목록 자체를 없앤다.
*
* <p>주제가 답하는 질문(논지)과, 그 질문에 대해 실제로 만들어 본 답들(축)이 이 화면의 뼈대다.
* 축이 없는 주제도 있으므로 — 축을 쓸지는 주제마다 다르다 — 비면 그 자리를 그리지 않는다.
*/
export function TopicPage() {
const { params } = useRouteInput<"TECH_LOG_TOPIC">();
const slug = typeof params.slug === "string" ? params.slug : "";
const view = usePublicContent(["tech-log", "topic", slug], async (queries) => ({
topic: await queries.getTopicDetail(slug),
records: await queries.listRecords({ topic: slug }),
}));
if (!view.ready) return view.fallback;
const { topic, records } = view.data;
if (!topic) return <RegisteredNotFoundRoute />;
const axisLabel = topic.variantLabel.trim() || "접근";
const readingOrder = firstReads(records);
const readingPaths = new Set(readingOrder.map((entry) => entry.path));
const rest = records.filter((record) => !readingPaths.has(record.path));
return (
<main id="main-content" className="shell public-index-page topic-hub">
<header className="public-page-header">
<p className="section-kicker">Topic</p>
<h1>{topic.name}</h1>
{/*
논지가 있으면 그것이 이 주제의 첫 문장이다. 설명은 목록에서 주제를 가려내는 한 줄이고,
논지는 이 주제가 무엇에 답하는지를 말한다 — 둘 다 있으면 논지를 보인다.
*/}
<ProseText text={topic.thesis || topic.description} />
</header>
{topic.variants.length > 0 ? (
<section className="topic-variants" aria-labelledby="topic-variants-title">
<p className="section-kicker">{axisLabel}</p>
<h2 id="topic-variants-title">{`${axisLabel}별로 무엇을 알게 됐나`}</h2>
{/*
오른쪽 숫자를 더해도 아래 목록의 개수와 맞지 않는다. 한 기록이 여러 축에 걸릴 수
있고, 어느 축에도 걸리지 않은 기록은 공통이기 때문이다 — 그 규칙을 화면이 말하지
않으면 독자는 빠진 기록이 있다고 읽는다.
*/}
<p className="topic-variants-note">
{`한 기록이 여러 ${axisLabel}에 걸릴 수 있고, 어디에도 걸리지 않은 기록은 이 주제의 공통 기록입니다.`}
</p>
<ul>
{topic.variants.map((variant) => (
/*
축의 주소(`/topics/{주제}#{축}`)가 실제로 가리키는 자리다. 다른 화면에서 이
축을 걸면 여기로 온다 — 앵커가 없으면 그 링크는 주제 화면 맨 위에 떨어진다.
*/
<li key={variant.slug} id={variant.slug}>
<a href={variant.path}>
<strong>{variant.title}</strong>
{/*
비교표가 읽는 것은 결론이다. 요약은 이것이 무엇인가를 말하고, 결론은 만들어
보고 무엇을 알게 됐는가를 말한다 — 축을 견주는 자리에서 쓸모 있는 것은 뒤쪽이다.
*/}
<p>{variant.conclusion || variant.summary}</p>
{variant.recordCount > 0 ? (
<span aria-hidden="true">{`기록 ${variant.recordCount}`}</span>
) : null}
</a>
</li>
))}
</ul>
</section>
) : null}
<PublicDocumentRelations
relations={readingOrder}
kicker="Reading order"
title="먼저 읽을 것"
/>
{/*
먼저 읽을 것에 오른 편은 여기서 뺀다. 예전에는 같은 네 편이 위아래로 두 번 나왔다 —
「먼저 읽을 것」이 목록의 앞부분을 복사한 것처럼 보이면 순서를 정해 준 뜻이 없어진다.
*/}
<div className="public-result-heading">
<h2>나머지 기록</h2>
<p>{`${rest.length}개`}</p>
</div>
<PublicRecordList records={rest} emptyMessage="먼저 읽을 것 외에 남은 기록이 없습니다." />
<PublicDocumentRelations
relations={topic.relatedProjects}
kicker="Projects"
title="이 주제를 다룬 프로젝트"
/>
</main>
);
}