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
@@ -0,0 +1,134 @@
import { useRef, useState } from "react";
import type { components } from "../../../contracts/studio/generated.ts";
import type { Asset, AssetKind } from "../../../contracts/studio/contract.ts";
import { useStudioAssetGateway } from "../use-studio.ts";
import { AssetPicker, buildEvidenceDirective } from "./asset-picker.tsx";
import { AssetUploadDialog } from "./asset-upload-dialog.tsx";
import { FieldNotice, type FieldIssue } from "./field-issues.tsx";
type ConceptInput = components["schemas"]["ConceptInput"];
/** 이 화면이 자기 칸 아래에 보여 줄 수 있는 경로. */
export const CONCEPT_FIELD_PATHS = ["/basisVersion", "/bodyMarkdown"] as const;
const ASSET_KIND_OPTIONS: ReadonlyArray<{ value: AssetKind; label: string }> = [
{ value: "IMAGE", label: "이미지" },
{ value: "DIAGRAM", label: "다이어그램" },
{ value: "ATTACHMENT", label: "첨부파일" },
];
/**
* `:::evidence ...` is a block directive, so the parser requires a blank line
* before and after it. Inserting straight into `selectionStart`/`selectionEnd`
* without normalizing the surrounding whitespace would produce a directive
* glued to adjacent text -- a well-formed-looking block that the parser still
* rejects.
*/
function insertAtCursor(
textarea: HTMLTextAreaElement,
directive: string,
commit: (next: string) => void,
) {
const { selectionStart, selectionEnd, value } = textarea;
const prefix = value.slice(0, selectionStart);
const suffix = value.slice(selectionEnd);
const before = prefix.length === 0 || prefix.endsWith("\n\n") ? prefix : `${prefix}\n\n`;
const after = suffix.startsWith("\n") ? suffix : `\n${suffix}`;
commit(`${before}${directive}${after}`);
}
export function ConceptFields({
draft,
issues,
onChange,
onAssetsObserved,
onAssetUploaded,
}: {
draft: ConceptInput;
/** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */
issues: readonly FieldIssue[];
onChange(draft: ConceptInput): void;
/**
* The editor screen owns the resolution catalog Instant Preview reads, and
* merges what the Picker observes into it -- it never adopts the Picker's
* (searchable, and so narrowable) displayed list wholesale.
*/
onAssetsObserved?: (assets: readonly Asset[]) => void;
onAssetUploaded?: (asset: Asset) => void;
}) {
// Asset UI must use the throwing accessor, not the nullable `assetGateway`
// field directly -- see `use-studio.ts`'s `useStudioAssetGateway` doc.
const assetGateway = useStudioAssetGateway();
const bodyRef = useRef<HTMLTextAreaElement>(null);
const uploadTriggerRef = useRef<HTMLButtonElement>(null);
const [uploadKind, setUploadKind] = useState<AssetKind>("IMAGE");
const [uploadOpen, setUploadOpen] = useState(false);
const update = (patch: Partial<ConceptInput>) => onChange({ ...draft, ...patch });
const insertDirective = (directive: string) => {
const textarea = bodyRef.current;
if (!textarea) {
update({
bodyMarkdown: draft.bodyMarkdown
? `${draft.bodyMarkdown}\n\n${directive}\n`
: `${directive}\n`,
});
return;
}
insertAtCursor(textarea, directive, (next) => update({ bodyMarkdown: next }));
};
const closeUpload = () => {
setUploadOpen(false);
queueMicrotask(() => uploadTriggerRef.current?.focus());
};
return (
<section className="studio-editor-section" aria-labelledby="studio-concept-fields-title">
<div className="studio-editor-section-heading"><p className="studio-eyebrow">CONCEPT</p><h2 id="studio-concept-fields-title">개념</h2></div>
<div className="studio-field-grid">
<label className="studio-field"><span>기준 버전</span><input value={draft.basisVersion} onChange={(event) => update({ basisVersion: event.currentTarget.value })} /><small>&ldquo;Kubernetes 1.31&rdquo; 처럼 무엇을 보고 썼는지. 비워도 됩니다.</small><FieldNotice issues={issues} path="/basisVersion" /></label>
<label className="studio-field studio-field--wide"><span>본문 Markdown</span><textarea ref={bodyRef} className="studio-markdown-field" value={draft.bodyMarkdown} onChange={(event) => update({ bodyMarkdown: event.currentTarget.value })} /><small>&ldquo;##&rdquo; 소제목이 목차가 됩니다. 아키텍처 도식은 아래에서 삽입하세요.</small><FieldNotice issues={issues} path="/bodyMarkdown" /></label>
</div>
<div className="studio-asset-panel" role="group" aria-labelledby="studio-asset-panel-title">
<p className="studio-eyebrow">EVIDENCE</p>
<h3 id="studio-asset-panel-title">본문에 Asset 삽입</h3>
<p>목록에서 선택하면 본문 커서 위치에 evidence 구문을 삽입합니다. READY 상태의 Asset만 선택할 수 있습니다.</p>
<div className="studio-asset-panel-actions">
<label className="studio-asset-kind-field">
<span>업로드 종류</span>
<select value={uploadKind} onChange={(event) => setUploadKind(event.currentTarget.value as AssetKind)}>
{ASSET_KIND_OPTIONS.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}
</select>
</label>
<button
ref={uploadTriggerRef}
type="button"
onClick={() => setUploadOpen(true)}
>
Asset 업로드
</button>
</div>
<AssetPicker gateway={assetGateway} onAssetsObserved={onAssetsObserved} onInsert={insertDirective} />
</div>
{uploadOpen ? (
<AssetUploadDialog
gateway={assetGateway}
kind={uploadKind}
onUploaded={(asset) => {
onAssetUploaded?.(asset);
insertDirective(buildEvidenceDirective({
assetKey: asset.assetKey,
alt: asset.decorative ? "" : (asset.altText ?? ""),
caption: "",
zoom: asset.kind === "DIAGRAM",
}));
closeUpload();
}}
onClose={closeUpload}
/>
) : null}
</section>
);
}
@@ -2,6 +2,7 @@ import type { components } from "../../../contracts/studio/generated.ts";
import type { Asset } from "../../../contracts/studio/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";
import { COMMON_FIELD_PATHS, CommonDocumentFields } from "./common-document-fields.tsx";
import { DocumentStatusBar } from "./document-status-bar.tsx";
import { InstantPreview } from "./instant-preview.tsx";
@@ -41,6 +42,8 @@ export function DocumentEditor({
const issues = controller.publishIssues;
const kindPaths = controller.draft.kind === "CASE"
? CASE_FIELD_PATHS
: controller.draft.kind === "CONCEPT"
? CONCEPT_FIELD_PATHS
: controller.draft.kind === "REFERENCE"
? REFERENCE_FIELD_PATHS
: controller.draft.kind === "QUESTION"
@@ -68,6 +71,8 @@ export function DocumentEditor({
<CommonDocumentFields draft={controller.draft} topics={topics} projects={projects} relations={relations} 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"
? <ConceptFields draft={controller.draft} issues={issues} onChange={controller.replace} onAssetsObserved={onAssetsObserved} onAssetUploaded={onAssetUploaded} />
: controller.draft.kind === "REFERENCE"
? <ReferenceFields draft={controller.draft} issues={issues} onChange={controller.replace} />
: controller.draft.kind === "QUESTION"
@@ -10,6 +10,7 @@ const kindLabel = {
CASE: "Case",
REFERENCE: "Reference",
QUESTION: "Question",
CONCEPT: "개념",
PROJECT_DECISION: "Decision",
} as const;
const publicationLabel = {
@@ -12,6 +12,7 @@ const kindLabels = {
CASE: "CASE",
REFERENCE: "REFERENCE",
QUESTION: "QUESTION",
CONCEPT: "CONCEPT",
PROJECT_DECISION: "Decision",
} as const;
@@ -20,6 +20,12 @@ const types = [
description: "반복해서 적용할 기술 기준을 정리합니다.",
fields: "목적 · 규칙 · 적용 조건 · 예외 · 예시",
},
{
kind: "CONCEPT",
title: "개념",
description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다.",
fields: "기준 버전 · 본문",
},
{
kind: "QUESTION",
title: "Question",
@@ -67,6 +73,9 @@ function emptyDocument(kind: RecordKind): CreateDocumentInput {
verifiedOn: null,
};
}
if (kind === "CONCEPT") {
return { ...common, kind, bodyMarkdown: "", basisVersion: "" };
}
if (kind === "QUESTION") {
return {
...common,
@@ -28,6 +28,7 @@ const kindLabels = {
CASE: "Case",
REFERENCE: "Reference",
QUESTION: "Question",
CONCEPT: "개념",
PROJECT_DECISION: "Decision",
} as const;
@@ -12,6 +12,7 @@ const kindLabel = {
CASE: "Case",
REFERENCE: "Reference",
QUESTION: "Question",
CONCEPT: "개념",
PROJECT_DECISION: "Decision",
} as const;
const actionLabel = {