feat: 개념(CONCEPT) 문서 종류 — 편집기·공개 화면·탐색

Kubernetes 내부 동작처럼 처음부터 풀어 읽어야 하는 글을 쓸 자리를 만든다. Reference 는
판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉘고, 그 틀에 개념을 넣으면 두 글이 서로를
망친다 — 기준을 찾으러 온 사람은 배경을 지나야 하고, 개념을 배우러 온 사람은 규칙에서
시작한다.

편집기는 Case 의 본문 칸과 Asset Picker 를 그대로 쓴다. 아키텍처 도식은 같은
`:::evidence` 로 들어오고, `##` 소제목이 목차가 된다. 개념이 따로 갖는 것은 기준 버전
하나다 — 개념이 낡는 방식은 날짜가 아니라 버전이다.

공개 렌더는 Case 와 본문·목차를 공유하되 머리말이 다르다. 문제도 결론도 검증 환경도 없고,
프로젝트 마디는 값이 있을 때만 그린다 — 개념은 프로젝트 없이 서는 유일한 종류다.

픽스처가 실제 결함을 하나 드러냈다. 프로젝트 없는 기록이 처음 생기자 `?project=` 빈 값이
"프로젝트가 없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다. 빈
필터는 아무것도 고르지 않도록 고쳤다. 예전에는 빈 값에 걸릴 기록이 없어 저절로 맞았다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
This commit is contained in:
DongHyeonka
2026-08-28 19:51:20 +09:00
co-authored by Claude Opus 5
parent 9ecc017f22
commit 048c1b2f68
27 changed files with 749 additions and 47 deletions
@@ -10,19 +10,27 @@ type WorkingCopyInput = components["schemas"]["WorkingCopyInput"];
type CatalogEntry = components["schemas"]["CatalogEntry"];
type PublicRenderModel = components["schemas"]["PublicRenderModel"];
type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"];
type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"];
type RenderContext = components["schemas"]["RenderContext"];
/**
* `projectWorkingCopy` has no asset catalog access (that is an adapter concern),
* so a CASE projection cannot resolve `EvidenceFigureBlock.asset`. Everything else
* matches `PublicRenderModel` exactly; only the CASE variant's `bodyBlocks` narrows
* to the authoring shape until an adapter attaches the resolved asset descriptor.
* so a CASE or CONCEPT projection cannot resolve `EvidenceFigureBlock.asset`.
* Everything else matches `PublicRenderModel` exactly; only those two variants'
* `bodyBlocks` narrow to the authoring shape until an adapter attaches the
* resolved asset descriptor.
*/
export type AuthoringRenderModel =
| (Omit<CasePublicRenderModel, "bodyBlocks"> & {
bodyBlocks: CaseAuthoringBlock[];
})
| Exclude<PublicRenderModel, CasePublicRenderModel>;
| (Omit<ConceptPublicRenderModel, "bodyBlocks"> & {
bodyBlocks: CaseAuthoringBlock[];
})
| Exclude<
PublicRenderModel,
CasePublicRenderModel | ConceptPublicRenderModel
>;
export type ProjectionContext =
| RenderContext
@@ -34,16 +42,17 @@ export type ProjectionContext =
};
/**
* Attaches the resolved asset descriptor to every CASE EVIDENCE_FIGURE block,
* turning an `AuthoringRenderModel` into a genuine `PublicRenderModel`. Callers
* own the actual asset catalog (a mock gateway's static registry, a preview's
* own fixture data, ...), so this stays a pure mapping over a supplied resolver.
* Attaches the resolved asset descriptor to every EVIDENCE_FIGURE block of the
* two kinds that carry a markdown body — CASE and CONCEPT — turning an
* `AuthoringRenderModel` into a genuine `PublicRenderModel`. Callers own the
* actual asset catalog (a mock gateway's static registry, a preview's own
* fixture data, ...), so this stays a pure mapping over a supplied resolver.
*/
export function resolveCaseEvidenceAssets(
model: AuthoringRenderModel,
resolveAsset: (key: string) => components["schemas"]["ResolvedAsset"],
): PublicRenderModel {
if (model.kind !== "CASE") return model;
if (model.kind !== "CASE" && model.kind !== "CONCEPT") return model;
return {
...model,
@@ -150,7 +159,9 @@ function publicPath(input: WorkingCopyInput, project: CatalogEntry | null) {
? "cases"
: input.kind === "REFERENCE"
? "references"
: "questions";
: input.kind === "CONCEPT"
? "concepts"
: "questions";
return `/${prefix}/${input.slug}`;
}
@@ -237,6 +248,31 @@ export function projectWorkingCopy(
};
}
case "CONCEPT": {
/*
개념의 본문은 Case 와 같은 규칙을 탄다 — `:::evidence` 가 도식을 끌어오고, 그 키가
실제로 있는지 여기서 먼저 확인한다. 확인하지 않으면 미리보기는 열리지만 게시한 화면에서
그림 자리가 비어 버린다.
*/
const bodyBlocks = parseCaseContent(input.bodyMarkdown);
for (const block of bodyBlocks) {
if (block.type !== "EVIDENCE_FIGURE") continue;
if (!supportsEvidenceKey(block.key)) {
fail(`supported local evidence key not found: ${block.key}`);
}
if (!evidenceCatalogEntryFor(catalog, block.key)) {
fail(`EVIDENCE catalog entry not found: ${block.key}`);
}
}
return {
...base,
kind: "CONCEPT",
basisVersion: input.basisVersion,
bodyBlocks,
};
}
case "REFERENCE":
return {
...base,