feat: 홈이 길을 보여 주고, 활동이 사람 말로 적힌다

홈의 첫 문장은 글 쓰는 태도를 말했다 — "문제를 재현하고 검증해 정리합니다". 맞는
말이지만 처음 온 사람이 알아야 하는 것은 태도가 아니라 길이다. 이 사이트에서 기록은
한 편으로 끝나지 않고 프로젝트 안의 주제에 속하고 주제 안에서 서로 이어진다. 그 구조를
설명하는 문장보다 실제 사슬 하나가 빠르므로, 최근 기록이 가장 많이 모인 주제를 골라
프로젝트 → 주제 → 기록으로 편다. 예시를 코드에 적어 두지 않는다 — 그 기록을 지우는
순간 홈이 죽은 링크를 가리킨다.

프로젝트 활동은 종류 자리에 `CONCEPT_PUBLISHED` 를 그대로 찍고 있었다. 그것은
데이터베이스 제약(`project_activity_activity_type_check`)이 허용하는 값이지 방문자에게
할 말이 아니다 — 감사 로그처럼 읽히고, 정작 무슨 일이 있었는지는 알 수 없었다.

포트의 타입은 `"PUBLICATION" | "PROJECT UPDATE" | "QUESTION"` 셋으로 적혀 있었는데
서버는 그중 무엇도 보내지 않는다. 매퍼가 단언으로 통과시켜서 타입 검사도 이것을 잡지
못했다. 실제 값 열하나로 맞추고, `Record<ProjectActivityType, string>` 표로 사람이 읽는
문장을 만든다. 픽스처도 같은 값을 쓰게 했다 — 픽스처가 자기만의 말을 쓰던 동안 화면은
픽스처에서만 멀쩡했다.

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:15:05 +09:00
co-authored by Claude Opus 5
parent e88ed5eeb8
commit 0b0c5cb42d
15 changed files with 311 additions and 32 deletions
@@ -0,0 +1,67 @@
import { Link } from "react-router-dom";
import type { LatestEntry } from "./latest-index.tsx";
/** 한 줄에 펴 두는 기록 수. 넘으면 길이 아니라 또 하나의 목록이 된다. */
const PATH_SIZE = 4;
/**
* 이 사이트를 어떻게 쓰는지를 실제 기록 하나로 가르친다.
*
* <p>홈의 첫 문장은 글 쓰는 태도를 말했다 — "문제를 재현하고 검증해 정리합니다". 맞는 말이지만
* 처음 온 사람이 알아야 하는 것은 태도가 아니라 <em>길</em>이다. 이 사이트에서 기록은 한 편으로
* 끝나지 않고 프로젝트 안의 주제에 속하고, 주제 안에서 서로 이어진다. 그 구조를 설명하는 문장보다
* 실제 사슬 하나를 보여 주는 편이 빠르다.
*
* <p>고르는 방법은 "최근 기록이 가장 많이 모인 주제"다. 손으로 고른 예시를 코드에 적어 두면 그
* 기록을 지우는 순간 홈이 죽은 링크를 가리킨다 — 이 저장소에서 주제 셋을 코드에 적어 두었다가
* 같은 일을 겪었다.
*
* <p>이을 것이 없으면 그리지 않는다. 한 편짜리 길은 길이 아니다.
*/
export function HomeInvestigationPath({ entries }: { entries: ReadonlyArray<LatestEntry> }) {
/* 기록만 센다. 프로젝트 활동과 릴리스는 기록이 아니라 일어난 일이라 사슬의 마디가 아니다. */
const records = entries.filter((entry) => entry.typeState !== undefined && entry.topic);
const byTopic = new Map<string, LatestEntry[]>();
for (const record of records) {
const bucket = byTopic.get(record.topic);
if (bucket) bucket.push(record);
else byTopic.set(record.topic, [record]);
}
let lead: LatestEntry[] = [];
for (const bucket of byTopic.values()) {
if (bucket.length > lead.length) lead = bucket;
}
if (lead.length < 2) return null;
const head = lead[0]!;
const path = lead.slice(0, PATH_SIZE);
return (
<section className="shell home-path" aria-labelledby="home-path-title">
<p className="section-kicker" id="home-path-title">
이렇게 이어집니다
</p>
<ol className="home-path-trail">
<li>
<span>프로젝트</span>
<strong>{head.project}</strong>
</li>
<li>
<span>주제</span>
<strong>{head.topic}</strong>
</li>
</ol>
<ul className="home-path-records">
{path.map((record) => (
<li key={record.path}>
<span>{record.typeLabel}</span>
<Link to={record.path}>{record.title}</Link>
</li>
))}
</ul>
</section>
);
}
@@ -10,6 +10,7 @@ import { useRouteInput } from "../../../../../presentation/routes/route-input.ts
import { usePublicContent } from "../use-public-content.tsx";
import { FatalErrorState } from "../components/fatal-error-state.tsx";
import { HomeFocus } from "../components/home-focus.tsx";
import { HomeInvestigationPath } from "../components/home-investigation-path.tsx";
import { HomeTopicTabs } from "../components/home-topic-tabs.tsx";
import {
LatestIndex,
@@ -203,6 +204,12 @@ export function HomePage() {
<p className="identity-statement">{publicSiteConfig.identityStatement}</p>
</section>
{/*
첫 문장은 태도를 말한다. 처음 온 사람이 알아야 하는 것은 태도가 아니라 길이므로, 실제
기록 하나로 그 길을 보여 준다 — 설명보다 사슬 하나가 빠르다.
*/}
<HomeInvestigationPath entries={latestEntries} />
{initialKey ? (
<section className="shell focus-section" aria-labelledby="focus-label">
<p className="section-kicker" id="focus-label">
@@ -2,6 +2,10 @@ import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { resolvesToPublicRoute } from "../../../domain/navigation/public-path.ts";
import { Link } from "react-router-dom";
import { projectActivityLabel } from "../../shared/project-activity-labels.ts";
import { ProjectPageHeader } from "../components/project-page-header.tsx";
import { usePublicContent } from "../use-public-content.tsx";
@@ -20,11 +24,11 @@ export function ProjectActivityPage() {
if (!project) return <RegisteredNotFoundRoute />;
/*
활동은 로그다 — 언제 무엇을 올렸는지만 적는다.
활동은 이 프로젝트에서 언제 무슨 일이 있었는지를 적는다.
예전에는 각 줄에 그 기록으로 가는 링크가 있었다. 그러면 같은 글에 닿는 길이 둘이 되고,
읽는 사람은 "기록"과 "활동"이 어떻게 다른지 매번 다시 판단해야 한다. 글을 읽는 자리는
기록 화면 하나로 둔다.
종류 자리에 `CONCEPT_PUBLISHED` 가 그대로 찍히고 있었다. 그것은 데이터베이스 제약이 허용하는
값이지 방문자에게 할 말이 아니다 — 감사 로그처럼 읽히고, 정작 무슨 일이 있었는지는 알 수
없었다. 사람이 읽는 문장으로 바꾸고, 그 일이 만든 기록으로 갈 길을 한 줄 붙인다.
*/
return (
<main id="main-content" className="shell project-page">
@@ -37,10 +41,19 @@ export function ProjectActivityPage() {
<li key={item.id}>
<article id={item.id}>
<div>
<span>{item.type}</span>
<span>{projectActivityLabel(item.type)}</span>
<time dateTime={item.dateTime}>{item.date}</time>
</div>
<h2>{item.title}</h2>
{/*
그 일이 만든 기록. 열리지 않는 주소는 줄로 그리지 않는다 — 활동의 `path` 는
이 목록 자신을 가리키는 앵커일 수도 있다.
*/}
{item.recordPath && resolvesToPublicRoute(item.recordPath) ? (
<p className="project-activity-record">
<Link to={item.recordPath}>{item.summary || "이 활동이 남긴 기록"}</Link>
</p>
) : null}
</article>
</li>
))}
@@ -0,0 +1,42 @@
import type { ProjectActivityType } from "../../application/ports/public-content-queries.ts";
/**
* 활동 한 줄을 사람이 읽는 문장으로 바꾼다.
*
* <p>공개 화면이 `CONCEPT_PUBLISHED` 를 그대로 찍고 있었다. 그것은 데이터베이스의 제약
* (`project_activity_activity_type_check`)이 허용하는 값이지 방문자에게 할 말이 아니다 — 감사
* 로그처럼 읽히고, 이 프로젝트에서 무슨 일이 있었는지는 여전히 알 수 없다.
*
* <p>`Record<ProjectActivityType, string>` 이라 종류가 늘면 컴파일러가 빈 자리를 잡는다. 빠뜨리면
* 그 활동만 다시 코드로 나오고, 그 줄은 화면에서 이상해 보이지 않는다 — 다른 줄과 같은 모양으로
* 앉아 있기 때문이다.
*/
export const PROJECT_ACTIVITY_LABELS: Record<ProjectActivityType, string> = {
PHASE_CHANGED: "프로젝트 단계를 옮겼습니다",
QUESTION_OPENED: "열린 질문을 남겼습니다",
QUESTION_RESOLVED: "열린 질문에 답했습니다",
DECISION_ACCEPTED: "설계 결정을 확정했습니다",
CASE_PUBLISHED: "검증 기록을 공개했습니다",
REFERENCE_PUBLISHED: "적용 기준을 공개했습니다",
CONCEPT_PUBLISHED: "동작 원리를 공개했습니다",
SETUP_PUBLISHED: "환경 구성을 공개했습니다",
MILESTONE_REACHED: "중간 목표에 도달했습니다",
PROJECT_PAUSED: "프로젝트를 잠시 멈췄습니다",
PROJECT_RESUMED: "프로젝트를 다시 시작했습니다",
};
const KNOWN = new Set(Object.keys(PROJECT_ACTIVITY_LABELS));
export function isProjectActivityType(value: string): value is ProjectActivityType {
return KNOWN.has(value);
}
/**
* 모르는 값이 오면 원문을 그대로 보여 준다.
*
* <p>빈 칸으로 두거나 「기타」로 뭉개면 서버가 새 종류를 내보내기 시작한 사실이 화면에서 사라진다.
* 보기 나쁜 편이 낫다 — 보기 나쁘면 고치게 된다.
*/
export function projectActivityLabel(type: string): string {
return isProjectActivityType(type) ? PROJECT_ACTIVITY_LABELS[type] : type;
}
@@ -3585,3 +3585,95 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
.project-empty-decisions ul a:hover {
color: var(--signal);
}
/* 활동이 남긴 기록으로 가는 줄 */
.project-activity-record {
margin: 9px 0 0;
}
.project-activity-record a {
color: var(--muted);
font-size: 15px;
line-height: 1.6;
}
.project-activity-record a::before {
content: "→ ";
color: var(--line-strong);
}
.project-activity-record a:hover {
color: var(--signal);
}
/* 홈 — 이렇게 이어집니다 */
.home-path {
padding-block: 4px 44px;
}
.home-path-trail {
display: flex;
flex-wrap: wrap;
gap: 8px 28px;
margin: 15px 0 0;
padding: 0;
list-style: none;
}
.home-path-trail li {
display: flex;
gap: 9px;
align-items: baseline;
}
.home-path-trail span {
color: var(--faint);
font-size: 12px;
font-weight: 620;
}
.home-path-trail strong {
color: var(--ink);
font-size: 16px;
font-weight: 640;
}
.home-path-records {
margin: 16px 0 0;
padding: 0 0 0 17px;
border-left: 2px solid var(--line-strong);
list-style: none;
}
.home-path-records li {
display: grid;
grid-template-columns: 96px minmax(0, 1fr);
gap: 16px;
padding-block: 7px;
}
.home-path-records span {
color: var(--faint);
font-size: 12px;
font-weight: 620;
line-height: 1.7;
}
.home-path-records a {
color: var(--ink-soft);
font-size: 16px;
line-height: 1.55;
}
.home-path-records a:hover {
color: var(--signal);
}
@media (max-width: 767px) {
.home-path-records li {
grid-template-columns: minmax(0, 1fr);
gap: 2px;
}
}