feat: 기록을 축에 걸고, 탐색을 주제로 묶는다

기록↔축 연결을 저장할 경로가 없었다. `record_variant` 는 공개 조회가 읽기만 할 뿐
아무도 쓰지 않았고, 계약의 `variantIds` 도 어디에도 닿지 않았다. 관계와 같은 「통째
교체」 방식으로 세 저장소(문서·질문·결정)에 배선한다 — 클라이언트가 보낸 배열이 곧 최종
상태이고, diff 를 뜨면 순서 재배열과 삭제를 구분하지 못한다.

문서 편집기에서 고른 주제의 축을 체크박스로 고른다. 축은 주제 안에서만 뜻이 있으므로
카탈로그에 섞지 않고 따로 읽는다. 아무 축에도 걸지 않아도 되고, 그 경우 이 기록은 그
주제의 공통 기록이 된다 — 빈 줄이 곧 「공통」이라 따로 표시하지 않는다.

탐색은 `type=CONCEPT` 을 조용히 버리고 있었다. 필터 폼은 개념을 고를 수 있게 하는데
화면 쪽 목록에는 개념이 없어서, 고르면 주소만 바뀌고 아무것도 걸리지 않았다. 목록을
손으로 적지 않고 `Record<RecordKind, …>` 에서 뽑아 컴파일러가 잡게 한다.

그리고 탐색을 주제로 묶는다. 게시 순서 한 줄로는 무엇이 있는지는 보여도 무엇에 대한
것들인지가 보이지 않아, 스무 편이 넘어가면 목록이 아니라 더미가 된다.

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-09-01 17:13:18 +09:00
co-authored by Claude Opus 5
parent 3616502463
commit 4da6d77c43
8 changed files with 259 additions and 11 deletions
@@ -8,8 +8,23 @@ import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
탐색이 거를 수 있는 종류. 이름은 공용 표에서 가져온다 — 예전에는 이 목록만 「개념」이라
적어 두어 배지·머리말과 어긋났고, 같은 문서가 화면마다 다른 이름으로 보였다.
결정은 프로젝트 안에서만 읽히므로 여기 없다.
목록을 손으로 적지 않고 `Record<RecordKind, …>` 에서 뽑는다. 종류가 늘면 이 표가 비어 있는
것을 컴파일러가 잡는다 — 손으로 나열한 목록에 새 종류를 빠뜨리는 일이 이 저장소에서 반복됐고,
탐색 화면은 그래서 실제로 `type=CONCEPT` 을 조용히 버리고 있었다(고를 수는 있는데 걸리지 않았다).
*/
const EXPLORE_KINDS = ["CASE", "REFERENCE", "QUESTION", "CONCEPT"] as const;
const EXPLORE_KIND_ORDER: Record<RecordKind, number> = {
CASE: 1,
REFERENCE: 2,
QUESTION: 3,
CONCEPT: 4,
};
export const EXPLORE_KINDS: ReadonlyArray<RecordKind> = Object.freeze(
(Object.keys(EXPLORE_KIND_ORDER) as RecordKind[]).sort(
(left, right) => EXPLORE_KIND_ORDER[left] - EXPLORE_KIND_ORDER[right],
),
);
export function ExploreFilterForm({
action,
@@ -1,6 +1,8 @@
import type { RecordKind } from "../../../application/ports/public-content-queries.ts";
import { Link } from "react-router-dom";
import type { PublicRecord } from "../../../application/ports/public-content-queries.ts";
import { useRouteInput } from "../../../../../presentation/routes/route-input.tsx";
import { ExploreFilterForm } from "../components/explore-filter-form.tsx";
import { EXPLORE_KINDS, ExploreFilterForm } from "../components/explore-filter-form.tsx";
import { PublicRecordList } from "../components/public-record-list.tsx";
import { usePublicContent } from "../use-public-content.tsx";
@@ -8,14 +10,39 @@ function optionalString(value: unknown): string | undefined {
return typeof value === "string" ? value : undefined;
}
/**
* 기록을 주제별로 묶는다.
*
* <p>탐색은 오래 게시 순서 한 줄이었다. 무엇이 있는지는 보이지만 무엇에 대한 것들인지는 보이지
* 않아서, 스무 편이 넘어가면 목록이 아니라 더미가 된다. 주제 안에서는 원래 순서(게시 역순)를
* 그대로 지킨다.
*
* <p>묶음의 순서는 기록이 많은 주제부터다 — 가장 많이 다룬 것이 이 기록의 중심이다.
*/
function byTopic(records: ReadonlyArray<PublicRecord>) {
const groups = new Map<string, { slug: string; name: string; records: PublicRecord[] }>();
for (const record of records) {
const slug = record.topicSlug || "";
const group = groups.get(slug);
if (group) group.records.push(record);
else groups.set(slug, { slug, name: record.topic || "주제 없음", records: [record] });
}
return [...groups.values()].sort(
(left, right) =>
right.records.length - left.records.length || (left.name < right.name ? -1 : 1),
);
}
export function ExplorePage() {
const { search } = useRouteInput<"TECH_LOG_EXPLORE">();
const requestedKind = optionalString(search.type);
const topic = optionalString(search.topic);
const project = optionalString(search.project);
const kind = (["CASE", "REFERENCE", "QUESTION"] as const).find(
(item) => item === requestedKind,
) satisfies RecordKind | undefined;
/*
거를 종류는 필터 폼과 같은 목록에서 읽는다. 여기 손으로 적어 둔 목록에 개념이 없어서,
필터에서 「동작 원리」를 골라도 주소만 `type=CONCEPT` 이 되고 화면은 거르지 않았다.
*/
const kind = EXPLORE_KINDS.find((item) => item === requestedKind);
const view = usePublicContent(
["tech-log", "explore", kind, topic, project],
async (queries) => ({
@@ -29,10 +56,35 @@ export function ExplorePage() {
if (!view.ready) return view.fallback;
const { records } = view.data;
const groups = byTopic(records);
/*
주제를 이미 하나로 좁혀 놓았다면 다시 주제로 묶어 봐야 묶음이 하나뿐이다. 그때는 평평한
목록이 낫다 — 제목만 한 줄 더 생긴다.
*/
const grouped = !topic && groups.length > 1;
return <main id="main-content" className="shell public-index-page">
<header className="public-page-header"><p className="section-kicker">Explore</p><h1>탐색</h1><p>유형과 기술 주제, 프로젝트를 조합해 공개 기록을 찾습니다.</p></header>
<ExploreFilterForm action="/explore" kind={kind} topic={topic} project={project} />
<div className="public-result-heading"><h2>공개 기록</h2><p>{records.length}개의 공개 기록</p></div>
<PublicRecordList records={records} />
{grouped ? (
groups.map((group) => (
<section className="explore-topic-group" key={group.slug}>
{/*
주제 이름은 그 주제 화면으로 가는 링크다. 목록에서 한 주제가 눈에 들면 그 주제가
무엇에 답하는지로 바로 갈 수 있어야 한다.
*/}
<div className="public-result-heading">
<h3>
<Link to={`/topics/${group.slug}`}>{group.name}</Link>
</h3>
<p>{`${group.records.length}개`}</p>
</div>
<PublicRecordList records={group.records} />
</section>
))
) : (
<PublicRecordList records={records} />
)}
</main>;
}
@@ -1,6 +1,7 @@
import type { components } from "../../../contracts/studio/generated.ts";
import type { WorkingCopyInput } from "../../../contracts/studio/contract.ts";
import { FieldNotice, type FieldIssue } from "./field-issues.tsx";
import type { TopicVariantEdit } from "../../../contracts/management/contract.ts";
import { RelationEditor } from "./relation-editor.tsx";
type CatalogEntry = components["schemas"]["CatalogEntry"];
@@ -26,6 +27,7 @@ export const COMMON_FIELD_PATHS = [
"/topicId",
"/projectId",
"/relations",
"/variantIds",
] as const;
export function CommonDocumentFields({
@@ -33,6 +35,7 @@ export function CommonDocumentFields({
topics,
projects,
relations,
variants,
issues,
onUpdate,
}: {
@@ -40,6 +43,8 @@ export function CommonDocumentFields({
topics: CatalogEntry[];
projects: CatalogEntry[];
relations: CatalogEntry[];
/** 고른 주제의 축. 주제를 고르지 않았거나 축을 쓰지 않는 주제면 빈 목록이다. */
variants: readonly TopicVariantEdit[];
/** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */
issues: readonly FieldIssue[];
onUpdate(patch: Partial<WorkingCopyInput>): void;
@@ -66,6 +71,37 @@ export function CommonDocumentFields({
<p role="status" className="studio-visually-hidden">
{draft.summary.length >= SUMMARY_MAX ? `요약을 ${SUMMARY_MAX}자까지 모두 썼습니다. 더 입력되지 않습니다.` : ""}
</p>
{/*
축은 주제 안에서만 뜻이 있다. 주제를 고르지 않았거나 축을 쓰지 않는 주제면 이 자리를
그리지 않는다 — 고를 것이 없는 목록은 무엇을 놓쳤나 싶게 만든다.
아무 축에도 걸지 않아도 된다. 그 경우 이 기록은 주제의 공통 기록으로 읽힌다.
*/}
{variants.length > 0 ? (
<fieldset className="studio-checkbox-set">
<legend>축 — 고르지 않으면 이 주제의 공통 기록이 됩니다</legend>
{variants.map((variant) => (
<label className="studio-field--checkbox" key={variant.id ?? variant.slug}>
<input
type="checkbox"
checked={(draft.variantIds ?? []).includes(variant.id ?? "")}
onChange={(event) => {
const checked = event.currentTarget.checked;
const id = variant.id ?? "";
const current = draft.variantIds ?? [];
onUpdate({
variantIds: checked
? [...current, id]
: current.filter((chosen) => chosen !== id),
});
}}
/>
<span>{variant.title}</span>
</label>
))}
<FieldNotice issues={issues} path="/variantIds" />
</fieldset>
) : null}
<RelationEditor evidence={draft.kind === "PROJECT_DECISION"} relations={draft.relations} catalog={relations} onChange={(next) => onUpdate({ relations: next })} />
<FieldNotice issues={issues} path="/relations" />
</section>
@@ -8,6 +8,7 @@ import type {
WorkingCopyInput,
WorkingCopyDetail,
} from "../../../contracts/studio/contract.ts";
import type { TopicVariantEdit } from "../../../contracts/management/contract.ts";
import { mergeAssetCatalog } from "../../../domain/content-format/asset-evidence-catalog.ts";
import { createLocalId } from "../../../domain/studio/local-id.ts";
import type { DocumentEditorController } from "./document-editor-controller.ts";
@@ -296,6 +297,34 @@ export function DocumentEditorScreen({ documentId }: { documentId: string }) {
*/
const validation = validationSource ? validationOf(validationSource, studio.now()) : null;
/*
고른 주제의 축. 카탈로그(`TOPIC`/`PROJECT`/`RELATION`/`EVIDENCE`)는 주제와 무관한 전체
목록이라 여기에 섞을 수 없다 — 축은 주제 안에서만 뜻이 있고, 주제를 바꾸면 고를 수 있는
것이 통째로 바뀐다.
*/
const selectedTopicId = editor?.draft.topicId ?? null;
const [variants, setVariants] = useState<readonly TopicVariantEdit[]>([]);
useEffect(() => {
if (!selectedTopicId) {
setVariants([]);
return;
}
let cancelled = false;
void (async () => {
try {
const loaded = await studio.managementGateway.listTopicVariants(selectedTopicId);
if (!cancelled) setVariants(loaded);
} catch {
// 축을 못 읽어도 편집은 계속돼야 한다 — 축은 선택 사항이다.
if (!cancelled) setVariants([]);
}
})();
return () => {
cancelled = true;
};
}, [selectedTopicId, studio.managementGateway]);
const controller = useMemo<DocumentEditorController | null>(() => {
if (!editor || editor.documentId !== documentId) return null;
return {
@@ -349,6 +378,7 @@ export function DocumentEditorScreen({ documentId }: { documentId: string }) {
<DocumentEditor
controller={controller!}
catalog={currentResult.catalog}
variants={variants}
assets={assets}
onAssetsObserved={observeAssets}
onAssetUploaded={observeUploadedAsset}
@@ -1,5 +1,6 @@
import type { components } from "../../../contracts/studio/generated.ts";
import type { Asset } from "../../../contracts/studio/contract.ts";
import type { TopicVariantEdit } from "../../../contracts/management/contract.ts";
import type { DocumentEditorController } from "./document-editor-controller.ts";
import { CASE_FIELD_PATHS, CaseFields } from "./case-fields.tsx";
import { CONCEPT_FIELD_PATHS, ConceptFields } from "./concept-fields.tsx";
@@ -16,12 +17,15 @@ type CatalogEntry = components["schemas"]["CatalogEntry"];
export function DocumentEditor({
controller,
catalog,
variants,
assets,
onAssetsObserved,
onAssetUploaded,
}: {
controller: DocumentEditorController;
catalog: CatalogEntry[];
/** 고른 주제의 축. 주제를 고르지 않았거나 축을 쓰지 않는 주제면 빈 목록이다. */
variants: readonly TopicVariantEdit[];
/** Owned by `DocumentEditorScreen` so the CASE editor's Picker/Upload and Instant Preview share one list. */
assets: readonly Asset[];
onAssetsObserved: (assets: readonly Asset[]) => void;
@@ -68,7 +72,7 @@ export function DocumentEditor({
<h1 id="studio-edit-title">문서 편집</h1>
<p>{controller.draft.title || "제목 없는 작업본"}</p>
</header>
<CommonDocumentFields draft={controller.draft} topics={topics} projects={projects} relations={relations} issues={issues} onUpdate={controller.update} />
<CommonDocumentFields draft={controller.draft} topics={topics} projects={projects} relations={relations} variants={variants} issues={issues} onUpdate={controller.update} />
{controller.draft.kind === "CASE"
? <CaseFields draft={controller.draft} issues={issues} onChange={controller.replace} onAssetsObserved={onAssetsObserved} onAssetUploaded={onAssetUploaded} />
: controller.draft.kind === "CONCEPT"
@@ -2902,3 +2902,21 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
text-align: left;
}
}
/*
탐색의 주제 묶음. 묶음 제목은 그 주제 화면으로 가는 링크이고, 그 아래는 평소의 기록 목록
그대로다 — 새 배치를 만들지 않고 사이 여백만 준다.
*/
.explore-topic-group + .explore-topic-group {
margin-top: 56px;
}
.explore-topic-group .public-result-heading h3 {
margin: 0;
font-size: 20px;
letter-spacing: -0.02em;
}
.explore-topic-group .public-result-heading h3 a:hover {
color: var(--signal);
}
@@ -346,19 +346,31 @@ describe("TechLog explore discovery", () => {
expect(router.state.location.search).toBe("");
});
expect(screen.getByText("7개의 공개 기록")).toBeVisible();
/*
탐색은 오래 게시 순서 한 줄이었다. 무엇이 있는지는 보이지만 무엇에 대한 것들인지는 보이지
않아서, 스무 편이 넘어가면 목록이 아니라 더미가 된다. 이제 주제로 묶고, 묶음은 기록이
많은 주제부터 온다 — 가장 많이 다룬 것이 이 기록의 중심이다.
*/
expect(
within(screen.getByRole("main"))
.getAllByRole("heading", { level: 3 })
.map((heading) => heading.textContent),
).toEqual(["JPA", "Authentication", "Kubernetes", "Redis"]);
// 주제 이름은 그 주제 화면으로 가는 링크다.
expect(screen.getByRole("link", { name: "JPA" })).toHaveAttribute("href", "/topics/jpa");
// 묶음 안에서는 원래 순서(게시 역순)를 그대로 지킨다.
expect(
within(screen.getByRole("main"))
.getAllByRole("listitem")
.map((item) => within(item).getByRole("link").getAttribute("href")),
).toEqual([
// 게시 역순이다 — 개념이 가장 최근이라 맨 앞에 온다.
"/concepts/kubernetes-scheduling",
"/cases/collection-fetch-join-pagination",
"/references/jpa-list-fetch-strategy",
"/questions/collection-fetch-join-with-pagination",
"/references/state-and-nonce-boundary",
"/questions/validate-edge-token-again",
"/concepts/kubernetes-scheduling",
"/cases/redis-adapter-ttl-boundary",
"/questions/collection-fetch-join-with-pagination",
]);
});
@@ -0,0 +1,81 @@
import assert from "node:assert/strict";
import { test } from "vitest";
import { TECH_LOG_MANAGEMENT_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-management-contract-contribution.ts";
/**
* 축(variant) CRUD 네 연산이 실제로 나가는 주소와 메서드.
*
* <p>계약에만 있고 기여 목록에 없으면 타입에는 멀쩡히 보이는데 부를 수가 없다. 축을 더할 때
* 정확히 그 상태였다 — 계약에 넷이 다 있는데 화면에서 하나도 부를 수 없었다.
*/
const EXPECTED = [
{ operationId: "listTopicVariants", method: "GET", path: "/api/v1/studio/topics/{id}/variants" },
{
operationId: "createTopicVariant",
method: "POST",
path: "/api/v1/studio/topics/{id}/variants",
},
{
operationId: "updateTopicVariant",
method: "PUT",
path: "/api/v1/studio/topics/{id}/variants/{variantId}",
},
{
operationId: "deleteTopicVariant",
method: "DELETE",
path: "/api/v1/studio/topics/{id}/variants/{variantId}",
},
] as const;
test("축 CRUD 네 연산이 자기 주소와 메서드로 등록되어 있다", () => {
const byId = new Map(
TECH_LOG_MANAGEMENT_CONTRIBUTION.http.map((entry) => [entry.contract.operationId, entry]),
);
for (const expected of EXPECTED) {
const installed = byId.get(expected.operationId);
assert.ok(installed, `${expected.operationId} 가 기여 목록에 있어야 한다`);
assert.equal(installed.contract.method, expected.method);
assert.equal(installed.contract.pathTemplate, expected.path);
}
});
/**
* 주소가 있는 것과 게이트웨이가 그것을 부르는 것은 다르다 — 삭제 경로에서 겪은 그대로다.
* 그래서 게이트웨이를 실제로 불러 어떤 연산이 어떤 인자로 나가는지 본다.
*/
test("게이트웨이가 축 연산을 주제 id 와 함께 부른다", async () => {
const { createHttpManagementGateway } = await import(
"../../../src/features/tech-log/adapters/http/http-management-gateway.ts"
);
const called: { operationId: string; input: unknown }[] = [];
const gateway = createHttpManagementGateway({
operations: {
execute: (operationId: string, input: unknown) => {
called.push({ operationId, input });
return Promise.resolve({ kind: "SUCCESS", value: [] });
},
},
} as never);
const topicId = "11111111-1111-4111-8111-111111111111";
const variantId = "22222222-2222-4222-8222-222222222222";
await gateway.listTopicVariants(topicId);
await gateway.createTopicVariant(topicId, { slug: "bff", title: "BFF" });
await gateway.updateTopicVariant(topicId, variantId, { slug: "bff", title: "BFF" });
await gateway.deleteTopicVariant(topicId, variantId, 3);
assert.deepEqual(
called.map((entry) => entry.operationId),
["listTopicVariants", "createTopicVariant", "updateTopicVariant", "deleteTopicVariant"],
);
// 경로가 주제를 요구한다. 주제 id 를 빠뜨리면 서버는 다른 주제의 축을 보게 된다.
for (const entry of called) {
assert.equal((entry.input as { id?: string }).id, topicId, entry.operationId);
}
for (const entry of called.slice(2)) {
assert.equal((entry.input as { variantId?: string }).variantId, variantId, entry.operationId);
}
});