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
@@ -1,4 +1,4 @@
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION";
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
export type QuestionStatus =
| "OPEN"
| "INVESTIGATING"
@@ -96,7 +96,23 @@ export type QuestionRecord = PublicRecordBase & {
};
};
export type PublicRecord = CaseRecord | ReferenceRecord | QuestionRecord;
/**
* 개념. Reference 가 규칙·적용·예외로 나뉘는 것과 달리 본문 하나로 흐르고, 낡음은 검증일이
* 아니라 기준 버전이 말한다. 프로젝트가 없어도 되는 유일한 종류다.
*/
export type ConceptRecord = PublicRecordBase & {
kind: "CONCEPT";
basisVersion: string;
content: string;
bodyAssets: ReadonlyArray<PublicBodyAsset>;
sections: ReadonlyArray<RecordSection>;
};
export type PublicRecord =
| CaseRecord
| ReferenceRecord
| QuestionRecord
| ConceptRecord;
export type ProjectDecision = {
id: string;
@@ -167,6 +183,49 @@ export type HomeFocusItem = {
};
export const publicRecords: ReadonlyArray<PublicRecord> = [
{
kind: "CONCEPT",
slug: "kubernetes-scheduling",
title: "Kubernetes 스케줄링은 어떻게 결정되는가",
summary:
"Pod 가 Node 에 앉기까지 scheduler 가 거치는 단계를 따라가고, 예약과 실제 바인딩이 갈라지는 지점을 짚습니다.",
path: "/concepts/kubernetes-scheduling",
topic: "Kubernetes",
topicSlug: "kubernetes",
// 개념은 프로젝트 없이 선다 — 프로젝트 산출물이 아니라 아는 것이다.
projectSlug: "",
projectTitle: "",
publishedAt: "2026-08-20T10:00:00+09:00",
publishedLabel: "2026.08.20",
visibility: "PUBLIC",
basisVersion: "Kubernetes 1.31",
content: "",
bodyAssets: [],
sections: [
{
id: "what-the-scheduler-sees",
title: "스케줄러가 보는 것",
paragraphs: [
"스케줄러는 아직 노드가 정해지지 않은 Pod 를 감시한다. 그 목록은 API 서버가 주고, 결정의 근거는 노드의 여유 자원과 Pod 가 건 조건이다.",
],
},
{
id: "filtering-and-scoring",
title: "Filtering 과 Scoring",
paragraphs: [
"먼저 둘 수 없는 노드를 걸러 내고(Filtering), 남은 노드에 점수를 매긴다(Scoring). 거르는 단계에서 전부 탈락하면 Pod 는 Pending 으로 남는다.",
],
},
{
id: "reservation-and-binding",
title: "예약과 실제 바인딩의 간격",
paragraphs: [
"점수가 가장 높은 노드를 고른 뒤 스케줄러는 먼저 자기 캐시에 자리를 예약하고, 바인딩은 API 서버에 따로 보낸다. 그 사이에 노드 상태가 바뀌면 kubelet 이 거절할 수 있다.",
],
},
],
relations: [],
},
{
kind: "CASE",
slug: "collection-fetch-join-pagination",
@@ -42,8 +42,19 @@ function comparePublishedAt(
}
export function listRecords(filters: RecordFilters = {}): PublicRecord[] {
const hasTopicFilter = filters.topic !== undefined;
const hasProjectFilter = filters.project !== undefined;
/*
빈 필터는 아무것도 고르지 않는다.
예전에는 빈 값을 비교해도 걸리는 기록이 없어 저절로 빈 목록이 됐다. 개념이 프로젝트 없이
설 수 있게 되면서 `projectSlug` 가 빈 기록이 생겼고, 그때부터 `?project=` 는 "프로젝트가
없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다.
*/
const hasTopicFilter = filters.topic !== undefined && filters.topic.trim() !== "";
const hasProjectFilter = filters.project !== undefined && filters.project.trim() !== "";
const filtersNothing =
(filters.topic !== undefined && filters.topic.trim() === "") ||
(filters.project !== undefined && filters.project.trim() === "");
if (filtersNothing) return [];
const requestedTopic = filters.topic?.trim().toLocaleLowerCase("ko-KR");
const requestedProject = filters.project
?.trim()