feat: 주제·프로젝트가 조사의 상태를 말하게 한다

주제 화면은 기록이 하나뿐이면 제목과 한 줄, 목록 한 줄이 전부였다. 그 상태에서는
"아직 아무것도 없는 곳"과 "이제 막 시작한 조사"가 구분되지 않는다 — 둘 다 빈 화면으로
보인다. 무엇이 있고 무엇이 아직 없는지를 먼저 적는다. 「아직 없는 것」이 이 화면에서
가장 쓸모 있는 줄이다.

프로젝트의 「주요 주제」는 이름만 있는 목록이었다. 프로젝트를 여는 사람이 알고 싶은
것은 이름이 아니라 그 질문에 대해 지금까지 무엇을 만들어 놨는가인데, 이름만 있으면
주제 화면까지 한 번 더 들어가야 알 수 있었고 프로젝트 화면이 목차의 목차가 됐다.
주제마다 이 프로젝트의 기록을 읽는 순서대로 펴서 조사의 모양이 한 화면에 보이게 한다.
다루기로 했지만 비어 있는 주제도 지우지 않는다 — 그 사실이 조사의 상태다.

결정 화면은 결정이 없으면 통째로 빈 종이였다. 남은 질문을 함께 읽어, 그 빈 화면이
"결정할 것이 없다"가 아니라 "아직 결정에 이르지 못했다"를 말하게 한다.

읽는 순서 표를 한 벌로 모았다. 세 화면이 각자 자기 목록을 들고 있으면 종류를 더할 때
한 곳만 고쳐지고 나머지는 새 종류를 맨 앞이나 맨 뒤에 조용히 던져 놓는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
DongHyeonka
2026-09-15 20:10:15 +09:00
co-authored by Claude Opus 5
parent fe1f23520e
commit e88ed5eeb8
8 changed files with 519 additions and 24 deletions
@@ -0,0 +1,111 @@
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 { byReadingOrder } from "../../shared/record-reading-order.ts";
type TopicRef = Readonly<{ name: string; slug: string }>;
/**
* 이 프로젝트가 무엇을 어디까지 조사했는지를 주제별로 편다.
*
* <p>「주요 주제」는 이름만 있는 목록이었다. 프로젝트를 여는 사람이 알고 싶은 것은 이름이 아니라
* "이 조사가 어느 질문을 붙들고 있고, 그 질문에 대해 지금까지 무엇을 만들어 놨는가"다. 이름만
* 있으면 그 주제 화면까지 한 번 더 들어가야 그것을 알 수 있고, 프로젝트 화면은 목차의 목차가 된다.
*
* <p>그래서 주제마다 이 프로젝트의 기록을 읽는 순서대로 펼친다. 이 화면 하나로 조사의 모양이
* 보이게 하는 것이 목적이다.
*
* <p>기록이 아직 없는 주제도 지우지 않는다. 다루기로 한 주제인데 아직 아무것도 없다는 사실이
* 조사의 상태이고, 지우면 그 사실만 화면에서 사라진다.
*/
export function InvestigationMap({
topics,
records,
headingId,
}: {
topics: ReadonlyArray<TopicRef>;
records: ReadonlyArray<PublicRecord>;
headingId: string;
}) {
const grouped = new Map<string, PublicRecord[]>();
for (const record of records) {
const key = record.topicSlug || "";
const bucket = grouped.get(key);
if (bucket) bucket.push(record);
else grouped.set(key, [record]);
}
/*
고른 주제가 먼저다 — 작성자가 순서까지 정한 값이기 때문이다. 그다음에 기록만 있고 고르지
않은 주제를 붙인다. 붙이지 않으면 그 주제의 기록이 어느 줄에도 속하지 않고 사라진다.
*/
const listed = [...topics];
const known = new Set(listed.map((topic) => topic.slug));
for (const record of records) {
if (record.topicSlug && !known.has(record.topicSlug)) {
known.add(record.topicSlug);
listed.push({ name: record.topic, slug: record.topicSlug });
}
}
const loose = grouped.get("") ?? [];
if (listed.length === 0 && loose.length === 0) return null;
return (
<section className="investigation-map" aria-labelledby={headingId}>
<p className="section-kicker">Investigation</p>
<h2 id={headingId}>주제별로 어디까지 왔나</h2>
<ol>
{listed.map((topic) => {
const inTopic = byReadingOrder(grouped.get(topic.slug) ?? []);
return (
<li key={topic.slug || topic.name}>
<div className="investigation-topic">
{topic.slug ? (
<Link to={`/topics/${topic.slug}`}>{topic.name}</Link>
) : (
<strong>{topic.name}</strong>
)}
<span>{inTopic.length > 0 ? `기록 ${inTopic.length}` : "기록 없음"}</span>
</div>
{inTopic.length > 0 ? (
<ul className="investigation-records">
{inTopic.map((record) => (
<li key={record.path}>
<span className="investigation-kind">
{DOCUMENT_KIND_LABELS[record.kind]}
</span>
<Link to={record.path}>{record.title}</Link>
</li>
))}
</ul>
) : (
<p className="investigation-empty">
다루기로 한 주제인데 아직 공개한 기록이 없습니다.
</p>
)}
</li>
);
})}
{/* 주제에 매이지 않은 기록. 어디에도 속하지 않은 채 사라지지 않게 마지막에 모은다. */}
{loose.length > 0 ? (
<li key="__loose">
<div className="investigation-topic">
<strong>주제 없음</strong>
<span>{`기록 ${loose.length}`}</span>
</div>
<ul className="investigation-records">
{byReadingOrder(loose).map((record) => (
<li key={record.path}>
<span className="investigation-kind">{DOCUMENT_KIND_LABELS[record.kind]}</span>
<Link to={record.path}>{record.title}</Link>
</li>
))}
</ul>
</li>
) : null}
</ol>
</section>
);
}
@@ -0,0 +1,81 @@
import type {
PublicRecord,
RecordKind,
} from "../../../application/ports/public-content-queries.ts";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
/**
* 세는 순서. 원리를 먼저 알고, 그것을 확인하고, 거기서 기준이 나오고, 재현할 환경이 따르고,
* 아직 답하지 못한 것이 마지막이다 — 읽는 순서와 같게 둔다.
*
* <p>`Record<RecordKind, …>` 라 종류가 늘면 컴파일러가 빈 자리를 잡는다. 손으로 나열한 목록에
* 새 종류를 빠뜨리는 일이 이 저장소에서 반복됐고, 여기서 빠지면 그 종류의 기록은 세어지지도
* 「아직 없는 것」에 적히지도 않아 화면이 조용히 거짓말을 한다.
*/
const COUNT_ORDER: Record<RecordKind, number> = {
CONCEPT: 1,
CASE: 2,
REFERENCE: 3,
SETUP: 4,
QUESTION: 5,
};
const KINDS: ReadonlyArray<RecordKind> = Object.freeze(
(Object.keys(COUNT_ORDER) as RecordKind[]).sort(
(left, right) => COUNT_ORDER[left] - COUNT_ORDER[right],
),
);
/**
* 이 묶음이 지금 어디까지 왔는지.
*
* <p>주제 화면은 기록이 하나뿐일 때 거의 빈 화면이 됐다. 제목과 한 줄, 그리고 목록 한 줄. 그
* 상태에서는 "아직 아무것도 없는 곳"과 "이제 막 시작한 조사"가 구분되지 않는다 — 둘 다 빈
* 화면으로 보인다.
*
* <p>그래서 무엇이 있고 무엇이 아직 없는지를 함께 적는다. 「아직 없는 것」이 이 화면에서 가장
* 쓸모 있는 줄이다. 조사가 어디까지 왔는지를 그 한 줄이 말한다.
*
* <p>세는 대상은 화면 아래 목록과 같은 배열이다. 다른 곳에서 가져오면 위의 숫자와 아래의 개수가
* 어긋나고, 독자는 빠진 기록이 있다고 읽는다.
*/
export function RecordStateSummary({
records,
headingId,
}: {
records: ReadonlyArray<PublicRecord>;
headingId: string;
}) {
const counts = new Map<RecordKind, number>();
for (const record of records) {
counts.set(record.kind, (counts.get(record.kind) ?? 0) + 1);
}
const present = KINDS.filter((kind) => (counts.get(kind) ?? 0) > 0);
const missing = KINDS.filter((kind) => (counts.get(kind) ?? 0) === 0);
return (
<section className="record-state" aria-labelledby={headingId}>
<p className="section-kicker">State</p>
<h2 id={headingId}>지금까지</h2>
{present.length > 0 ? (
<dl className="record-state-counts">
{present.map((kind) => (
<div key={kind}>
<dt>{DOCUMENT_KIND_LABELS[kind]}</dt>
<dd>{counts.get(kind)}</dd>
</div>
))}
</dl>
) : (
<p className="record-state-empty">아직 공개된 기록이 없습니다.</p>
)}
{missing.length > 0 ? (
<p className="record-state-missing">
<span>아직 없는 것</span>
{missing.map((kind) => DOCUMENT_KIND_LABELS[kind]).join(" · ")}
</p>
) : null}
</section>
);
}
@@ -15,9 +15,17 @@ export function ProjectDecisionsPage() {
const { hash } = useLocation();
const view = usePublicContent(["tech-log", "project", slug, "decisions"], async (queries) => {
const project = await queries.getProject(slug);
return project
? { project, decisions: await queries.getProjectDecisions(slug) }
: { project: undefined, decisions: [] };
if (!project) return { project: undefined, decisions: [], records: [] };
/*
결정이 하나도 없을 때 이 화면은 통째로 빈 종이였다. 그 상태에서는 "결정할 것이 없는
프로젝트"와 "아직 결정에 이르지 못한 조사"가 구분되지 않는다. 남은 질문을 함께 읽어
빈 화면이 조사의 상태를 말하게 한다.
*/
const [decisions, records] = await Promise.all([
queries.getProjectDecisions(slug),
queries.getProjectRecords(slug),
]);
return { project, decisions, records };
});
/*
결정은 상세 화면이 없다. 다른 기록이 거는 주소가 이 목록 위의 앵커(`#slug`)이므로, 그 링크로
@@ -32,9 +40,43 @@ export function ProjectDecisionsPage() {
if (!view.ready) return view.fallback;
const { project, decisions } = view.data;
const { project, decisions, records } = view.data;
if (!project) return <RegisteredNotFoundRoute />;
const openQuestions = records.filter(
(record) =>
record.kind === "QUESTION" &&
record.questionStatus !== "RESOLVED" &&
record.questionStatus !== "ARCHIVED",
);
if (decisions.length === 0) {
return (
<main id="main-content" className="shell project-page">
<ProjectPageHeader project={project} title={`${project.title} 결정`} />
<section className="project-empty-decisions" aria-labelledby="no-decisions-title">
<h2 id="no-decisions-title">아직 확정한 결정이 없습니다.</h2>
{openQuestions.length > 0 ? (
<>
<p>{`결정으로 이어질 수 있는 열린 질문이 ${openQuestions.length}개 있습니다.`}</p>
<ul>
{openQuestions.map((question) => (
<li key={question.path}>
<Link to={question.path}>{question.title}</Link>
</li>
))}
</ul>
</>
) : (
<p>
아직 열린 질문도 없습니다. 이 프로젝트의 조사는 기록을 모으는 단계입니다.
</p>
)}
</section>
</main>
);
}
return (
<main id="main-content" className="shell project-page">
<ProjectPageHeader project={project} title={`${project.title} 결정`} />
@@ -5,6 +5,7 @@ import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { InvestigationMap } from "../components/investigation-map.tsx";
import { ProjectPageHeader } from "../components/project-page-header.tsx";
import { ProseText } from "../../shared/public-render/prose-text.tsx";
import { PublicRecordList } from "../components/public-record-list.tsx";
@@ -47,6 +48,17 @@ export function ProjectOverviewPage() {
).values(),
];
/*
아직 답하지 않은 질문. `OPEN` 만 세면 조사 중인 질문(`INVESTIGATING`)이 빠져 "남은 것이
없다"로 읽힌다 — 끝난 것(`RESOLVED`)과 접은 것(`ARCHIVED`)만 빼는 편이 사실에 가깝다.
*/
const openQuestions = records.filter(
(record) =>
record.kind === "QUESTION" &&
record.questionStatus !== "RESOLVED" &&
record.questionStatus !== "ARCHIVED",
).length;
return (
<main id="main-content" className="shell project-page">
<ProjectPageHeader project={project} title={project.title} />
@@ -78,6 +90,18 @@ export function ProjectOverviewPage() {
<dd>{project.nextStep}</dd>
</div>
) : null}
{/*
단계·목표만으로는 조사가 어디까지 왔는지 알 수 없다. 남은 질문과 확정한 결정의 수가
그것을 말한다 — 둘 다 0 이면 아직 시작 단계이고, 질문만 많으면 조사 중이다.
*/}
<div>
<dt>열린 질문</dt>
<dd>{openQuestions}</dd>
</div>
<div>
<dt>확정한 결정</dt>
<dd>{decisions.filter((decision) => decision.status === "ADOPTED").length}</dd>
</div>
</dl>
{/*
숫자 셋(기록 12 · 결정 4 · 활동 9)은 이 프로젝트가 얼마나 큰지는 말해도 어디서부터 읽어야
@@ -114,26 +138,16 @@ export function ProjectOverviewPage() {
고른 목록(`project.topics`)이 먼저다 — 작성자가 순서까지 정한 값이기 때문이다. 고르지
않았으면 기록에서 뽑는다: 이 프로젝트의 공개 기록이 어느 주제에 사는지가 곧 이 프로젝트가
다루는 주제다. 고르는 것은 별도 동작이라 대부분 비어 있었고, 그동안 이 구역은 제목만
있는 빈 목록이었다 — 프로젝트가 주제를 안 다룬다는 말이 아니라 화면이 덜 만들어졌다는
말로 읽혔다.
다루는 주제다.
이름만 나열하던 자리를 조사 지도로 바꾼다. 이름만 있으면 그 주제 화면까지 한 번 더
들어가야 무엇이 있는지 알 수 있었고, 프로젝트 화면이 목차의 목차가 됐다.
*/}
{topics.length > 0 ? (
<section className="project-topics" aria-labelledby="project-topics-title">
<h2 id="project-topics-title">주요 주제</h2>
{/*
주제 이름은 그 주제 화면으로 가는 링크다. 오래 글자 목록이었던 것은 매퍼가 slug 를
버렸기 때문이고, 계약은 처음부터 이름과 slug 를 함께 주고 있었다.
*/}
<ul>
{topics.map((topic) => (
<li key={topic.slug || topic.name}>
{topic.slug ? <Link to={`/topics/${topic.slug}`}>{topic.name}</Link> : topic.name}
</li>
))}
</ul>
</section>
) : null}
<InvestigationMap
topics={topics}
records={records}
headingId="project-investigation-title"
/>
</main>
);
}
@@ -10,6 +10,7 @@ import type {
} 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 { RecordStateSummary } from "../components/record-state-summary.tsx";
import { usePublicContent } from "../use-public-content.tsx";
/**
@@ -93,6 +94,12 @@ export function TopicPage() {
<ProseText text={topic.thesis || topic.description} />
</header>
{/*
기록이 하나뿐인 주제는 제목과 한 줄, 목록 한 줄이 전부여서 "아직 아무것도 없는 곳"과
"이제 막 시작한 조사"가 구분되지 않았다. 무엇이 있고 무엇이 아직 없는지를 먼저 말한다.
*/}
<RecordStateSummary records={records} headingId="topic-state-title" />
{topic.variants.length > 0 ? (
<section className="topic-variants" aria-labelledby="topic-variants-title">
<p className="section-kicker">{axisLabel}</p>
@@ -0,0 +1,35 @@
import type { RecordKind } from "../../application/ports/public-content-queries.ts";
/**
* 기록을 읽는 순서.
*
* <p>원리를 먼저 알고, 그것을 확인한 기록을 보고, 거기서 나온 기준을 읽고, 재현할 환경이 따르고,
* 아직 답하지 못한 것을 마지막에 본다.
*
* <p>한 벌만 둔다. 주제 화면·상태 요약·조사 지도가 각자 자기 목록을 들고 있던 동안 같은 기록이
* 화면마다 다른 자리에 나왔고, 종류를 더할 때 한 곳만 고치면 나머지는 그 종류를 맨 뒤나 맨 앞에
* 조용히 던져 놓았다. `Record<RecordKind, …>` 라 종류가 늘면 컴파일러가 빈 자리를 잡는다.
*/
export const RECORD_READING_ORDER: Record<RecordKind, number> = {
CONCEPT: 1,
CASE: 2,
REFERENCE: 3,
SETUP: 4,
QUESTION: 5,
};
/** 읽는 순서대로 세운 종류 목록. */
export const RECORD_KINDS_IN_READING_ORDER: ReadonlyArray<RecordKind> = Object.freeze(
(Object.keys(RECORD_READING_ORDER) as RecordKind[]).sort(
(left, right) => RECORD_READING_ORDER[left] - RECORD_READING_ORDER[right],
),
);
/** 읽는 순서로 정렬한다. 원본 배열은 건드리지 않는다. */
export function byReadingOrder<T extends { readonly kind: RecordKind }>(
records: ReadonlyArray<T>,
): T[] {
return [...records].sort(
(left, right) => RECORD_READING_ORDER[left.kind] - RECORD_READING_ORDER[right.kind],
);
}
@@ -3387,3 +3387,201 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
gap: 3px;
}
}
/* 묶음의 상태 — 무엇이 있고 무엇이 아직 없는가 */
.record-state {
padding-block: 26px 30px;
border-bottom: 1px solid var(--line);
}
.record-state h2 {
margin: 6px 0 0;
font-size: 21px;
font-weight: 640;
letter-spacing: -0.024em;
}
.record-state-counts {
display: flex;
flex-wrap: wrap;
gap: 12px 34px;
margin: 17px 0 0;
}
.record-state-counts > div {
display: flex;
gap: 9px;
align-items: baseline;
}
.record-state-counts dt {
color: var(--muted);
font-size: 13px;
font-weight: 600;
}
.record-state-counts dd {
margin: 0;
color: var(--ink);
font-family: "IBM Plex Mono", monospace;
font-size: 17px;
font-weight: 620;
}
/*
이 줄이 이 구역에서 가장 쓸모 있다. 조사가 어디까지 왔는지를 「아직 없는 것」이 말한다 —
그래서 있는 것들보다 흐리게 두되 지우지는 않는다.
*/
.record-state-missing {
margin: 15px 0 0;
color: var(--muted);
font-size: 13px;
}
.record-state-missing > span {
margin-right: 10px;
color: var(--faint);
font-weight: 640;
}
.record-state-empty {
margin: 15px 0 0;
color: var(--muted);
font-size: 15px;
}
/* 조사 지도 — 주제별로 어디까지 왔나 */
.investigation-map {
padding-block: 40px 8px;
}
.investigation-map h2 {
margin: 6px 0 0;
font-size: 25px;
font-weight: 640;
letter-spacing: -0.028em;
}
.investigation-map > ol {
margin: 26px 0 0;
padding: 0;
list-style: none;
}
.investigation-map > ol > li {
padding-block: 21px;
border-top: 1px solid var(--line);
}
.investigation-topic {
display: flex;
flex-wrap: wrap;
gap: 8px 16px;
align-items: baseline;
justify-content: space-between;
}
.investigation-topic a,
.investigation-topic strong {
color: var(--ink);
font-size: 18px;
font-weight: 640;
letter-spacing: -0.018em;
}
.investigation-topic a:hover {
color: var(--signal);
}
.investigation-topic > span {
color: var(--faint);
font-family: "IBM Plex Mono", monospace;
font-size: 12px;
}
.investigation-records {
margin: 13px 0 0;
padding: 0;
list-style: none;
}
.investigation-records > li {
display: grid;
grid-template-columns: 96px minmax(0, 1fr);
gap: 16px;
padding-block: 6px;
}
.investigation-kind {
color: var(--faint);
font-size: 12px;
font-weight: 620;
line-height: 1.75;
}
.investigation-records a {
color: var(--ink-soft);
font-size: 16px;
line-height: 1.6;
}
.investigation-records a:hover {
color: var(--signal);
}
/* 다루기로 했지만 아직 비어 있는 주제. 지우지 않는다 — 그 사실이 조사의 상태다. */
.investigation-empty {
margin: 11px 0 0;
color: var(--muted);
font-size: 14px;
}
@media (max-width: 767px) {
.investigation-records > li {
grid-template-columns: minmax(0, 1fr);
gap: 2px;
}
}
/* 결정이 없는 프로젝트. 빈 종이 대신 조사의 상태를 말한다. */
.project-empty-decisions {
padding-block: 56px 72px;
border-top: 1px solid var(--line);
}
.project-empty-decisions h2 {
margin: 0;
font-size: 25px;
font-weight: 640;
letter-spacing: -0.028em;
}
.project-empty-decisions > p {
margin: 15px 0 0;
color: var(--muted);
font-size: 16px;
}
.project-empty-decisions ul {
margin: 22px 0 0;
padding: 0;
list-style: none;
}
.project-empty-decisions ul li {
padding-block: 11px;
border-top: 1px solid var(--line);
}
.project-empty-decisions ul a {
color: var(--ink);
font-size: 17px;
font-weight: 560;
}
.project-empty-decisions ul a:hover {
color: var(--signal);
}