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:
co-authored by
Claude Opus 5
parent
9ecc017f22
commit
048c1b2f68
@@ -38,28 +38,28 @@
|
||||
},
|
||||
"contractSet": {
|
||||
"setAlgorithm": "CA_CONTRACT_SET_V1",
|
||||
"setDigest": "sha256:cdcfb628a502d71596f1162726eb395aad0f5f92cf05fd77d304f8e51c81b2fc",
|
||||
"setDigest": "sha256:a5ca8e1a61f3b26ab8a13e3b20206466c27e6d23aaa6ae05c6717296737eba0a",
|
||||
"packages": [
|
||||
{
|
||||
"packageId": "@tech-log/management-contract",
|
||||
"version": "1.0.0",
|
||||
"digest": "sha256:72650735061fde627f5037571eb986cb758f44a546f065c88408399f8eec4a55",
|
||||
"runtimeProtocolVersion": 1,
|
||||
"sourceRevision": "ef49d3a"
|
||||
"sourceRevision": "777aeaa"
|
||||
},
|
||||
{
|
||||
"packageId": "@tech-log/public-contract",
|
||||
"version": "2.1.0",
|
||||
"digest": "sha256:7eb668e39e279e49767306dd36e1dd51302071c39d78495d21307bbd9676220e",
|
||||
"digest": "sha256:66391f3a3fd91b632094de9f40814ccd42f2fec00d251e7134f33c9b663dfb18",
|
||||
"runtimeProtocolVersion": 1,
|
||||
"sourceRevision": "ef49d3a"
|
||||
"sourceRevision": "777aeaa"
|
||||
},
|
||||
{
|
||||
"packageId": "@tech-log/studio-contract",
|
||||
"version": "3.1.0",
|
||||
"digest": "sha256:18dd46898be64b07f7e826409d19347512613ee2e22420028a4a0644f50f37dd",
|
||||
"digest": "sha256:3acafb64f9864df9fc82d17896aa41c99b70d7cbef4c4d063bb30fa8746eacdc",
|
||||
"runtimeProtocolVersion": 1,
|
||||
"sourceRevision": "ef49d3a"
|
||||
"sourceRevision": "777aeaa"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -151,6 +151,9 @@ export function validateWorkingCopyInputStructure(input: WorkingCopyInput): Fiel
|
||||
ordered(errors, "/options", input.options, [["title", 120, 1], ["description", 100_000, 0]]);
|
||||
text(errors, "/nextValidation", input.nextValidation, 100_000);
|
||||
if (input.resolution) { text(errors, "/resolution/summary", input.resolution.summary, 100_000); uuid(errors, "/resolution/evidenceTargetId", input.resolution.evidenceTargetId, true); text(errors, "/resolution/linkLabel", input.resolution.linkLabel, 120); }
|
||||
} else if (input.kind === "CONCEPT") {
|
||||
text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000);
|
||||
text(errors, "/basisVersion", input.basisVersion, 120);
|
||||
} else {
|
||||
text(errors, "/statement", input.statement, 100_000);
|
||||
text(errors, "/rationale", input.rationale, 100_000);
|
||||
@@ -171,10 +174,15 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat
|
||||
if (blank(document.title)) error("TITLE_REQUIRED", "/title", "제목을 입력하세요.");
|
||||
if (blank(document.slug)) error("SLUG_REQUIRED", "/slug", "slug를 입력하세요."); else if (dependencies.documents.some((item) => item.id !== document.id && item.slug === document.slug)) error("SLUG_DUPLICATE", "/slug", "중복 slug입니다.");
|
||||
if (blank(document.summary)) warning("SUMMARY_REQUIRED", "/summary", "요약을 입력하세요.");
|
||||
if (!has(document.topicId, "TOPIC")) warning("TOPIC_REQUIRED", "/topicId", "Topic을 선택하세요.");
|
||||
if (!has(document.topicId, "TOPIC")) {
|
||||
// 개념은 프로젝트 없이 설 수 있는 유일한 종류다. 주제가 유일한 집이므로 비면 막는다.
|
||||
if (document.kind === "CONCEPT") error("TOPIC_REQUIRED", "/topicId", "개념에는 주제가 필요합니다.");
|
||||
else warning("TOPIC_REQUIRED", "/topicId", "Topic을 선택하세요.");
|
||||
}
|
||||
if (!document.projectId) {
|
||||
if (document.kind === "PROJECT_DECISION") warning("DECISION_PROJECT_REQUIRED", "/projectId", "Decision에는 Project가 필요합니다.");
|
||||
else warning("PROJECT_MISSING", "/projectId", "Project 연결을 권장합니다.");
|
||||
// 개념에 프로젝트가 없는 것은 결함이 아니라 정상이다 — 아는 것이지 프로젝트 산출물이 아니다.
|
||||
else if (document.kind !== "CONCEPT") warning("PROJECT_MISSING", "/projectId", "Project 연결을 권장합니다.");
|
||||
} else if (!has(document.projectId, "PROJECT")) error("PROJECT_NOT_FOUND", "/projectId", "Project를 찾을 수 없습니다.");
|
||||
document.relations.forEach((relation, index) => { if (!has(relation.targetId, "RELATION")) error("RELATION_TARGET_NOT_FOUND", `/relations/${index}/targetId`, "관계 대상을 찾을 수 없습니다."); });
|
||||
if (document.kind === "CASE") {
|
||||
@@ -210,6 +218,9 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat
|
||||
if (document.questionStatus === "OPEN") { if (!document.unknowns.length) error("QUESTION_UNKNOWN_REQUIRED", "/unknowns", "미확인 사항이 필요합니다."); if (document.resolution) error("OPEN_QUESTION_RESOLUTION_FORBIDDEN", "/resolution", "열린 질문에는 결론을 둘 수 없습니다."); }
|
||||
if (document.questionStatus === "RESOLVED") { if (!document.resolution) warning("QUESTION_RESOLUTION_REQUIRED", "/resolution", "해결 내용이 필요합니다."); else { if (blank(document.resolution.summary)) warning("RESOLUTION_SUMMARY_REQUIRED", "/resolution/summary", "요약이 필요합니다."); if (!has(document.resolution.evidenceTargetId, "EVIDENCE")) error("RESOLUTION_EVIDENCE_REQUIRED", "/resolution/evidenceTargetId", "근거가 필요합니다."); if (blank(document.resolution.linkLabel)) warning("RESOLUTION_LINK_LABEL_REQUIRED", "/resolution/linkLabel", "링크 문구가 필요합니다."); } }
|
||||
if (document.options.length < 2) warning("QUESTION_OPTIONS_FEWER_THAN_TWO", "/options", "선택지 두 개를 권장합니다.");
|
||||
} else if (document.kind === "CONCEPT") {
|
||||
// 개념은 본문이 전부다. 비어 있으면 제목만 있는 글이 공개된다.
|
||||
if (blank(document.bodyMarkdown)) warning("BODY_REQUIRED", "/bodyMarkdown", "본문을 입력하세요.");
|
||||
} else {
|
||||
if (!document.decisionStatus) warning("DECISION_STATUS_REQUIRED", "/decisionStatus", "결정 상태가 필요합니다.");
|
||||
if (!document.decidedOn) warning("DECIDED_ON_REQUIRED", "/decidedOn", "결정일이 필요합니다.");
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION";
|
||||
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
|
||||
|
||||
export type QuestionStatus =
|
||||
| "OPEN"
|
||||
@@ -107,7 +107,27 @@ export type QuestionRecord = PublicRecordBase & {
|
||||
};
|
||||
};
|
||||
|
||||
export type PublicRecord = CaseRecord | ReferenceRecord | QuestionRecord;
|
||||
/**
|
||||
* 개념.
|
||||
*
|
||||
* <p>Reference 는 판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉜다. 개념은 그렇게 나누지 않는다 —
|
||||
* 처음부터 풀어 읽는 글이라 본문 하나로 흐르고, 낡음은 검증일이 아니라 `basisVersion` 이 말한다.
|
||||
*/
|
||||
export type ConceptRecord = PublicRecordBase & {
|
||||
kind: "CONCEPT";
|
||||
/** "Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 비면 화면에 그리지 않는다. */
|
||||
basisVersion: string;
|
||||
/** 본문 Markdown 원문. Case 와 같은 규칙으로 `:::evidence` 가 도식을 끌어온다. */
|
||||
content: string;
|
||||
bodyAssets: ReadonlyArray<PublicBodyAsset>;
|
||||
sections: ReadonlyArray<RecordSection>;
|
||||
};
|
||||
|
||||
export type PublicRecord =
|
||||
| CaseRecord
|
||||
| ReferenceRecord
|
||||
| QuestionRecord
|
||||
| ConceptRecord;
|
||||
|
||||
export type ProjectDecision = {
|
||||
id: string;
|
||||
@@ -173,7 +193,7 @@ export type PublicTopic = {
|
||||
*/
|
||||
export type LatestRecordEntry = {
|
||||
id: string;
|
||||
entryType: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_ACTIVITY" | "RELEASE";
|
||||
entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT_ACTIVITY" | "RELEASE";
|
||||
title: string;
|
||||
summary: string;
|
||||
path: string;
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"packageId": "@tech-log/management-contract",
|
||||
"version": "1.0.0",
|
||||
"digest": "sha256:72650735061fde627f5037571eb986cb758f44a546f065c88408399f8eec4a55",
|
||||
"sourceRevision": "ef49d3a",
|
||||
"sourceRevision": "777aeaa",
|
||||
"operationIds": [
|
||||
"createCaseDraft",
|
||||
"getCaseForEdit",
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"packageId": "@tech-log/public-contract",
|
||||
"version": "2.1.0",
|
||||
"digest": "sha256:7eb668e39e279e49767306dd36e1dd51302071c39d78495d21307bbd9676220e",
|
||||
"sourceRevision": "ef49d3a",
|
||||
"digest": "sha256:66391f3a3fd91b632094de9f40814ccd42f2fec00d251e7134f33c9b663dfb18",
|
||||
"sourceRevision": "777aeaa",
|
||||
"operationIds": [
|
||||
"getPublicSite",
|
||||
"getPublicHome",
|
||||
@@ -12,6 +12,7 @@
|
||||
"getPublicTopic",
|
||||
"getPublicCase",
|
||||
"getPublicReference",
|
||||
"getPublicConcept",
|
||||
"getPublicQuestion",
|
||||
"listPublicProjects",
|
||||
"getPublicProject",
|
||||
|
||||
@@ -147,6 +147,22 @@ export interface paths {
|
||||
patch?: never;
|
||||
trace?: never;
|
||||
};
|
||||
"/concepts/{slug}": {
|
||||
parameters: {
|
||||
query?: never;
|
||||
header?: never;
|
||||
path?: never;
|
||||
cookie?: never;
|
||||
};
|
||||
get: operations["getPublicConcept"];
|
||||
put?: never;
|
||||
post?: never;
|
||||
delete?: never;
|
||||
options?: never;
|
||||
head?: never;
|
||||
patch?: never;
|
||||
trace?: never;
|
||||
};
|
||||
"/questions/{slug}": {
|
||||
parameters: {
|
||||
query?: never;
|
||||
@@ -399,7 +415,7 @@ export interface components {
|
||||
};
|
||||
RelatedEntry: {
|
||||
/** @enum {string} */
|
||||
type: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
|
||||
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
|
||||
title: string;
|
||||
summary?: string;
|
||||
path: string;
|
||||
@@ -454,7 +470,7 @@ export interface components {
|
||||
};
|
||||
LatestEntry: {
|
||||
/** @enum {string} */
|
||||
entryType: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_ACTIVITY" | "RELEASE";
|
||||
entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT_ACTIVITY" | "RELEASE";
|
||||
title: string;
|
||||
summary: string;
|
||||
path: string;
|
||||
@@ -475,7 +491,7 @@ export interface components {
|
||||
};
|
||||
KnowledgeListItem: {
|
||||
/** @enum {string} */
|
||||
type: "CASE" | "REFERENCE";
|
||||
type: "CASE" | "REFERENCE" | "CONCEPT";
|
||||
title: string;
|
||||
path: string;
|
||||
primarySummary: string;
|
||||
@@ -566,6 +582,46 @@ export interface components {
|
||||
relatedCases: components["schemas"]["RelatedEntry"][];
|
||||
};
|
||||
};
|
||||
/** @description 개념은 판단 기준이 아니라 설명이다. Reference 가 규칙·적용·예외로 나뉘는 것과 달리
|
||||
* 본문 하나로 흐르고, 낡음은 검증일이 아니라 `basisVersion` 이 말한다.
|
||||
* */
|
||||
ConceptDetailResponse: {
|
||||
canonicalPath: string;
|
||||
/** @default true */
|
||||
indexable: boolean;
|
||||
concept: {
|
||||
title: string;
|
||||
summary: string;
|
||||
/** @description "Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 비면 화면에 그리지 않는다. */
|
||||
basisVersion: string;
|
||||
content: string;
|
||||
/** @enum {string} */
|
||||
contentFormat: "MARKDOWN";
|
||||
contentFormatVersion: number;
|
||||
/** @description 본문이 참조하는 Asset. 아키텍처 도식이 여기로 들어온다. Case 와 같은 규칙이다 —
|
||||
* 원문에는 `:::evidence key="…"` 만 남고 URL 은 이 목록이 준다.
|
||||
* */
|
||||
bodyAssets: components["schemas"]["BodyAsset"][];
|
||||
primaryTopic?: components["schemas"]["TopicSummary"];
|
||||
primaryProject?: components["schemas"]["ProjectSummary"];
|
||||
tags: components["schemas"]["TagSummary"][];
|
||||
coverAsset?: components["schemas"]["AssetReference"];
|
||||
/** Format: date-time */
|
||||
publishedAt: string;
|
||||
/** Format: date-time */
|
||||
updatedAt: string;
|
||||
};
|
||||
relations: {
|
||||
primaryProject?: components["schemas"]["RelatedEntry"];
|
||||
relatedRecords: components["schemas"]["RelatedEntry"][];
|
||||
};
|
||||
};
|
||||
ConceptDetailResponseEnvelope: {
|
||||
/** @constant */
|
||||
success: true;
|
||||
data: components["schemas"]["ConceptDetailResponse"];
|
||||
meta: components["schemas"]["ResponseMeta"];
|
||||
};
|
||||
ReferenceDetailResponse: {
|
||||
canonicalPath: string;
|
||||
/** @default true */
|
||||
@@ -992,7 +1048,7 @@ export interface operations {
|
||||
exploreKnowledge: {
|
||||
parameters: {
|
||||
query?: {
|
||||
type?: "CASE" | "REFERENCE";
|
||||
type?: "CASE" | "REFERENCE" | "CONCEPT";
|
||||
topic?: string;
|
||||
project?: string;
|
||||
tag?: string;
|
||||
@@ -1231,6 +1287,46 @@ export interface operations {
|
||||
};
|
||||
};
|
||||
};
|
||||
getPublicConcept: {
|
||||
parameters: {
|
||||
query?: never;
|
||||
header?: never;
|
||||
path: {
|
||||
slug: string;
|
||||
};
|
||||
cookie?: never;
|
||||
};
|
||||
requestBody?: never;
|
||||
responses: {
|
||||
/** @description OK */
|
||||
200: {
|
||||
headers: {
|
||||
[name: string]: unknown;
|
||||
};
|
||||
content: {
|
||||
"application/json": components["schemas"]["ConceptDetailResponseEnvelope"];
|
||||
};
|
||||
};
|
||||
/** @description Not Found */
|
||||
404: {
|
||||
headers: {
|
||||
[name: string]: unknown;
|
||||
};
|
||||
content: {
|
||||
"application/json": components["schemas"]["ErrorEnvelope"];
|
||||
};
|
||||
};
|
||||
/** @description Internal Server Error */
|
||||
500: {
|
||||
headers: {
|
||||
[name: string]: unknown;
|
||||
};
|
||||
content: {
|
||||
"application/json": components["schemas"]["ErrorEnvelope"];
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
getPublicQuestion: {
|
||||
parameters: {
|
||||
query?: never;
|
||||
@@ -1396,7 +1492,7 @@ export interface operations {
|
||||
listPublicProjectRecords: {
|
||||
parameters: {
|
||||
query?: {
|
||||
type?: "CASE" | "REFERENCE" | "QUESTION";
|
||||
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
|
||||
relation?: "PRIMARY" | "RELATED";
|
||||
page?: number;
|
||||
size?: number;
|
||||
@@ -1610,7 +1706,7 @@ export interface operations {
|
||||
parameters: {
|
||||
query: {
|
||||
q: string;
|
||||
type?: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT" | "RELEASE";
|
||||
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "RELEASE";
|
||||
topic?: string;
|
||||
page?: number;
|
||||
size?: number;
|
||||
|
||||
@@ -114,6 +114,7 @@ paths:
|
||||
enum:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- CONCEPT
|
||||
- name: topic
|
||||
in: query
|
||||
schema:
|
||||
@@ -345,6 +346,36 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorEnvelope'
|
||||
/concepts/{slug}:
|
||||
get:
|
||||
operationId: getPublicConcept
|
||||
tags:
|
||||
- Concept
|
||||
parameters:
|
||||
- name: slug
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ConceptDetailResponseEnvelope'
|
||||
'404':
|
||||
description: Not Found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorEnvelope'
|
||||
'500':
|
||||
description: Internal Server Error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorEnvelope'
|
||||
/questions/{slug}:
|
||||
get:
|
||||
operationId: getPublicQuestion
|
||||
@@ -484,6 +515,7 @@ paths:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- QUESTION
|
||||
- CONCEPT
|
||||
- name: relation
|
||||
in: query
|
||||
schema:
|
||||
@@ -649,6 +681,7 @@ paths:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- QUESTION
|
||||
- CONCEPT
|
||||
- PROJECT
|
||||
- RELEASE
|
||||
- name: topic
|
||||
@@ -869,6 +902,7 @@ components:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- QUESTION
|
||||
- CONCEPT
|
||||
- PROJECT
|
||||
- PROJECT_DECISION
|
||||
- RELEASE
|
||||
@@ -1023,6 +1057,7 @@ components:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- QUESTION
|
||||
- CONCEPT
|
||||
- PROJECT_ACTIVITY
|
||||
- RELEASE
|
||||
title:
|
||||
@@ -1078,6 +1113,7 @@ components:
|
||||
enum:
|
||||
- CASE
|
||||
- REFERENCE
|
||||
- CONCEPT
|
||||
title:
|
||||
type: string
|
||||
path:
|
||||
@@ -1303,6 +1339,100 @@ components:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/RelatedEntry'
|
||||
ConceptDetailResponse:
|
||||
type: object
|
||||
description: |
|
||||
개념은 판단 기준이 아니라 설명이다. Reference 가 규칙·적용·예외로 나뉘는 것과 달리
|
||||
본문 하나로 흐르고, 낡음은 검증일이 아니라 `basisVersion` 이 말한다.
|
||||
required:
|
||||
- canonicalPath
|
||||
- indexable
|
||||
- concept
|
||||
- relations
|
||||
properties:
|
||||
canonicalPath:
|
||||
type: string
|
||||
indexable:
|
||||
type: boolean
|
||||
default: true
|
||||
concept:
|
||||
type: object
|
||||
required:
|
||||
- title
|
||||
- summary
|
||||
- basisVersion
|
||||
- content
|
||||
- contentFormat
|
||||
- contentFormatVersion
|
||||
- bodyAssets
|
||||
- tags
|
||||
- publishedAt
|
||||
- updatedAt
|
||||
properties:
|
||||
title:
|
||||
type: string
|
||||
summary:
|
||||
type: string
|
||||
basisVersion:
|
||||
type: string
|
||||
description: '"Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 비면 화면에 그리지 않는다.'
|
||||
content:
|
||||
type: string
|
||||
contentFormat:
|
||||
type: string
|
||||
enum:
|
||||
- MARKDOWN
|
||||
contentFormatVersion:
|
||||
type: integer
|
||||
bodyAssets:
|
||||
type: array
|
||||
description: |
|
||||
본문이 참조하는 Asset. 아키텍처 도식이 여기로 들어온다. Case 와 같은 규칙이다 —
|
||||
원문에는 `:::evidence key="…"` 만 남고 URL 은 이 목록이 준다.
|
||||
items:
|
||||
$ref: '#/components/schemas/BodyAsset'
|
||||
primaryTopic:
|
||||
$ref: '#/components/schemas/TopicSummary'
|
||||
primaryProject:
|
||||
$ref: '#/components/schemas/ProjectSummary'
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/TagSummary'
|
||||
coverAsset:
|
||||
$ref: '#/components/schemas/AssetReference'
|
||||
publishedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
relations:
|
||||
type: object
|
||||
required:
|
||||
- relatedRecords
|
||||
properties:
|
||||
primaryProject:
|
||||
$ref: '#/components/schemas/RelatedEntry'
|
||||
relatedRecords:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/RelatedEntry'
|
||||
ConceptDetailResponseEnvelope:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required:
|
||||
- success
|
||||
- data
|
||||
- meta
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
const: true
|
||||
data:
|
||||
$ref: '#/components/schemas/ConceptDetailResponse'
|
||||
meta:
|
||||
$ref: '#/components/schemas/ResponseMeta'
|
||||
ReferenceDetailResponse:
|
||||
type: object
|
||||
required:
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"packageId": "@tech-log/studio-contract",
|
||||
"version": "3.1.0",
|
||||
"digest": "sha256:18dd46898be64b07f7e826409d19347512613ee2e22420028a4a0644f50f37dd",
|
||||
"sourceRevision": "ef49d3a",
|
||||
"digest": "sha256:3acafb64f9864df9fc82d17896aa41c99b70d7cbef4c4d063bb30fa8746eacdc",
|
||||
"sourceRevision": "777aeaa",
|
||||
"operationIds": [
|
||||
"getStudioSession",
|
||||
"getStudioDashboard",
|
||||
|
||||
@@ -520,7 +520,7 @@ export interface components {
|
||||
*
|
||||
* @enum {string}
|
||||
*/
|
||||
RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION";
|
||||
RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION" | "CONCEPT";
|
||||
/** @enum {string} */
|
||||
PublicationStatus: "NEVER_PUBLISHED" | "PUBLISHED" | "UNPUBLISHED";
|
||||
/**
|
||||
@@ -626,6 +626,24 @@ export interface components {
|
||||
*/
|
||||
kind: "REFERENCE";
|
||||
};
|
||||
ConceptInput: components["schemas"]["WorkingCopyInputBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "CONCEPT";
|
||||
/** @description Markdown 원문. Asset은 `:::evidence key="<assetKey>"` directive로
|
||||
* 참조한다. object storage URL을 원문에 직접 저장하지 않는다.
|
||||
* */
|
||||
bodyMarkdown: string;
|
||||
/** @description "Kubernetes 1.31" 처럼 이 글이 무엇을 보고 쓴 것인지 한 줄. 개념이 낡는
|
||||
* 방식은 날짜가 아니라 버전이므로 `lastVerifiedOn` 대신 이것을 둔다. 비워도 된다.
|
||||
* */
|
||||
basisVersion: string;
|
||||
} & {
|
||||
/**
|
||||
* @description discriminator enum property added by openapi-typescript
|
||||
* @enum {string}
|
||||
*/
|
||||
kind: "CONCEPT";
|
||||
};
|
||||
QuestionInput: components["schemas"]["WorkingCopyInputBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "QUESTION";
|
||||
@@ -676,7 +694,7 @@ export interface components {
|
||||
*/
|
||||
kind: "PROJECT_DECISION";
|
||||
};
|
||||
WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"];
|
||||
WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"] | components["schemas"]["ConceptInput"];
|
||||
WorkingCopyBase: components["schemas"]["WorkingCopyInputBase"] & {
|
||||
/**
|
||||
* Format: uuid
|
||||
@@ -722,6 +740,18 @@ export interface components {
|
||||
*/
|
||||
kind: "REFERENCE";
|
||||
};
|
||||
ConceptWorkingCopy: components["schemas"]["WorkingCopyBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "CONCEPT";
|
||||
bodyMarkdown: string;
|
||||
basisVersion: string;
|
||||
} & {
|
||||
/**
|
||||
* @description discriminator enum property added by openapi-typescript
|
||||
* @enum {string}
|
||||
*/
|
||||
kind: "CONCEPT";
|
||||
};
|
||||
QuestionWorkingCopy: components["schemas"]["WorkingCopyBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "QUESTION";
|
||||
@@ -766,9 +796,10 @@ export interface components {
|
||||
* | ReferenceWorkingCopy
|
||||
* | QuestionWorkingCopy
|
||||
* | ProjectDecisionWorkingCopy
|
||||
* | ConceptWorkingCopy
|
||||
* ```
|
||||
* */
|
||||
WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"];
|
||||
WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"] | components["schemas"]["ConceptWorkingCopy"];
|
||||
CreateDocumentInput: components["schemas"]["WorkingCopyInput"];
|
||||
SaveDocumentCommand: {
|
||||
expectedVersion: number;
|
||||
@@ -1139,6 +1170,18 @@ export interface components {
|
||||
evidenceTarget: components["schemas"]["DisplayTarget"];
|
||||
linkLabel: string;
|
||||
};
|
||||
ConceptPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "CONCEPT";
|
||||
basisVersion: string;
|
||||
bodyBlocks: components["schemas"]["CaseRenderBlock"][];
|
||||
} & {
|
||||
/**
|
||||
* @description discriminator enum property added by openapi-typescript
|
||||
* @enum {string}
|
||||
*/
|
||||
kind: "CONCEPT";
|
||||
};
|
||||
QuestionPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & {
|
||||
/** @enum {string} */
|
||||
kind: "QUESTION";
|
||||
@@ -1178,7 +1221,7 @@ export interface components {
|
||||
*/
|
||||
kind: "PROJECT_DECISION";
|
||||
};
|
||||
PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"];
|
||||
PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"] | components["schemas"]["ConceptPublicRenderModel"];
|
||||
PublicPreview: {
|
||||
/** Format: uuid */
|
||||
previewId: string;
|
||||
|
||||
@@ -834,7 +834,7 @@ components:
|
||||
# ------------------------------------------------------------ enumerations
|
||||
RecordKind:
|
||||
type: string
|
||||
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION]
|
||||
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT]
|
||||
description: |
|
||||
Studio 편집 대상 유형. API projection discriminator이며 Domain Aggregate가
|
||||
아니다. `PROJECT_DECISION`은 `ProjectDecision` capability로 dispatch된다.
|
||||
@@ -954,6 +954,26 @@ components:
|
||||
exceptions: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } }
|
||||
examples: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } }
|
||||
verifiedOn: { type: [string, "null"], format: date }
|
||||
ConceptInput:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
- { $ref: "#/components/schemas/WorkingCopyInputBase" }
|
||||
- type: object
|
||||
required: [kind, bodyMarkdown, basisVersion]
|
||||
properties:
|
||||
kind: { type: string, enum: [CONCEPT] }
|
||||
bodyMarkdown:
|
||||
type: string
|
||||
maxLength: 100000
|
||||
description: |
|
||||
Markdown 원문. Asset은 `:::evidence key="<assetKey>"` directive로
|
||||
참조한다. object storage URL을 원문에 직접 저장하지 않는다.
|
||||
basisVersion:
|
||||
type: string
|
||||
maxLength: 120
|
||||
description: |
|
||||
"Kubernetes 1.31" 처럼 이 글이 무엇을 보고 쓴 것인지 한 줄. 개념이 낡는
|
||||
방식은 날짜가 아니라 버전이므로 `lastVerifiedOn` 대신 이것을 둔다. 비워도 된다.
|
||||
QuestionInput:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
@@ -1011,6 +1031,7 @@ components:
|
||||
- { $ref: "#/components/schemas/ReferenceInput" }
|
||||
- { $ref: "#/components/schemas/QuestionInput" }
|
||||
- { $ref: "#/components/schemas/ProjectDecisionInput" }
|
||||
- { $ref: "#/components/schemas/ConceptInput" }
|
||||
discriminator:
|
||||
propertyName: kind
|
||||
mapping:
|
||||
@@ -1018,6 +1039,7 @@ components:
|
||||
REFERENCE: "#/components/schemas/ReferenceInput"
|
||||
QUESTION: "#/components/schemas/QuestionInput"
|
||||
PROJECT_DECISION: "#/components/schemas/ProjectDecisionInput"
|
||||
CONCEPT: "#/components/schemas/ConceptInput"
|
||||
|
||||
# ------------------------------------------------------- working copy output
|
||||
WorkingCopyBase:
|
||||
@@ -1061,6 +1083,16 @@ components:
|
||||
exceptions: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } }
|
||||
examples: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } }
|
||||
verifiedOn: { type: [string, "null"], format: date }
|
||||
ConceptWorkingCopy:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
- { $ref: "#/components/schemas/WorkingCopyBase" }
|
||||
- type: object
|
||||
required: [kind, bodyMarkdown, basisVersion]
|
||||
properties:
|
||||
kind: { type: string, enum: [CONCEPT] }
|
||||
bodyMarkdown: { type: string, maxLength: 100000 }
|
||||
basisVersion: { type: string, maxLength: 120 }
|
||||
QuestionWorkingCopy:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
@@ -1103,12 +1135,14 @@ components:
|
||||
| ReferenceWorkingCopy
|
||||
| QuestionWorkingCopy
|
||||
| ProjectDecisionWorkingCopy
|
||||
| ConceptWorkingCopy
|
||||
```
|
||||
oneOf:
|
||||
- { $ref: "#/components/schemas/CaseWorkingCopy" }
|
||||
- { $ref: "#/components/schemas/ReferenceWorkingCopy" }
|
||||
- { $ref: "#/components/schemas/QuestionWorkingCopy" }
|
||||
- { $ref: "#/components/schemas/ProjectDecisionWorkingCopy" }
|
||||
- { $ref: "#/components/schemas/ConceptWorkingCopy" }
|
||||
discriminator:
|
||||
propertyName: kind
|
||||
mapping:
|
||||
@@ -1116,6 +1150,7 @@ components:
|
||||
REFERENCE: "#/components/schemas/ReferenceWorkingCopy"
|
||||
QUESTION: "#/components/schemas/QuestionWorkingCopy"
|
||||
PROJECT_DECISION: "#/components/schemas/ProjectDecisionWorkingCopy"
|
||||
CONCEPT: "#/components/schemas/ConceptWorkingCopy"
|
||||
|
||||
# -------------------------------------------------------------- commands
|
||||
CreateDocumentInput: { $ref: "#/components/schemas/WorkingCopyInput" }
|
||||
@@ -1541,6 +1576,16 @@ components:
|
||||
summary: { type: string, maxLength: 100000 }
|
||||
evidenceTarget: { $ref: "#/components/schemas/DisplayTarget" }
|
||||
linkLabel: { type: string, minLength: 1, maxLength: 120 }
|
||||
ConceptPublicRenderModel:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
- { $ref: "#/components/schemas/PublicRenderModelBase" }
|
||||
- type: object
|
||||
required: [kind, basisVersion, bodyBlocks]
|
||||
properties:
|
||||
kind: { type: string, enum: [CONCEPT] }
|
||||
basisVersion: { type: string, maxLength: 120 }
|
||||
bodyBlocks: { type: array, maxItems: 10000, items: { $ref: "#/components/schemas/CaseRenderBlock" } }
|
||||
QuestionPublicRenderModel:
|
||||
unevaluatedProperties: false
|
||||
allOf:
|
||||
@@ -1585,6 +1630,7 @@ components:
|
||||
- { $ref: "#/components/schemas/ReferencePublicRenderModel" }
|
||||
- { $ref: "#/components/schemas/QuestionPublicRenderModel" }
|
||||
- { $ref: "#/components/schemas/ProjectDecisionPublicRenderModel" }
|
||||
- { $ref: "#/components/schemas/ConceptPublicRenderModel" }
|
||||
discriminator:
|
||||
propertyName: kind
|
||||
mapping:
|
||||
@@ -1592,6 +1638,7 @@ components:
|
||||
REFERENCE: "#/components/schemas/ReferencePublicRenderModel"
|
||||
QUESTION: "#/components/schemas/QuestionPublicRenderModel"
|
||||
PROJECT_DECISION: "#/components/schemas/ProjectDecisionPublicRenderModel"
|
||||
CONCEPT: "#/components/schemas/ConceptPublicRenderModel"
|
||||
|
||||
# ---------------------------------------------------------------- preview
|
||||
PublicPreview:
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -7,6 +7,7 @@ const kindLabels = {
|
||||
CASE: "Case",
|
||||
REFERENCE: "Reference",
|
||||
QUESTION: "Open Question",
|
||||
CONCEPT: "개념",
|
||||
} as const;
|
||||
|
||||
export function PublicDocumentHeader({ record }: { record: PublicRecord }) {
|
||||
|
||||
@@ -6,6 +6,7 @@ const kindLabels = {
|
||||
CASE: "Case",
|
||||
REFERENCE: "Reference",
|
||||
QUESTION: "Open Question",
|
||||
CONCEPT: "개념",
|
||||
} as const;
|
||||
|
||||
export function PublicRecordList({
|
||||
|
||||
@@ -3,7 +3,7 @@ import { Link, useNavigate } from "react-router-dom";
|
||||
import { useRouteInput } from "../../../../../presentation/routes/route-input.tsx";
|
||||
import { usePublicContent } from "../use-public-content.tsx";
|
||||
|
||||
const labels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", PROJECT: "Project", RELEASE: "Release" } as const;
|
||||
const labels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", CONCEPT: "개념", PROJECT: "Project", RELEASE: "Release" } as const;
|
||||
|
||||
function optionalString(value: unknown): string | undefined {
|
||||
return typeof value === "string" ? value : undefined;
|
||||
|
||||
@@ -18,6 +18,7 @@ type PublicRenderModel = components["schemas"]["PublicRenderModel"];
|
||||
type PublicRenderModelBase = components["schemas"]["PublicRenderModelBase"];
|
||||
type ResolvedRelation = components["schemas"]["ResolvedRelation"];
|
||||
type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"];
|
||||
type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"];
|
||||
type ReferencePublicRenderModel =
|
||||
components["schemas"]["ReferencePublicRenderModel"];
|
||||
type QuestionPublicRenderModel =
|
||||
@@ -34,6 +35,7 @@ const kindLabels = {
|
||||
CASE: "Case",
|
||||
REFERENCE: "Reference",
|
||||
QUESTION: "Open Question",
|
||||
CONCEPT: "개념",
|
||||
PROJECT_DECISION: "Decision",
|
||||
} as const;
|
||||
|
||||
@@ -227,6 +229,85 @@ function CaseDocument({
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 개념.
|
||||
*
|
||||
* <p>Case 와 같은 본문·목차·Asset 을 쓰되 머리말이 다르다. 개념에는 문제도 결론도 검증 환경도
|
||||
* 없고, 낡음은 검증일이 아니라 기준 버전이 말한다. 프로젝트가 없을 수 있는 유일한 종류이므로
|
||||
* 그 마디는 값이 있을 때만 그린다.
|
||||
*/
|
||||
function ConceptDocument({
|
||||
model,
|
||||
embedded,
|
||||
resolveEvidenceAsset,
|
||||
resolvePublishedLabel,
|
||||
}: {
|
||||
model: ConceptPublicRenderModel;
|
||||
embedded: boolean;
|
||||
} & RenderDependencies) {
|
||||
const headings = model.bodyBlocks
|
||||
.filter((block) => block.type === "HEADING")
|
||||
.map((heading) => ({
|
||||
id: heading.id,
|
||||
label: inlinePlainText(heading.content),
|
||||
}));
|
||||
|
||||
const Root = embedded ? "div" : "main";
|
||||
return (
|
||||
<Root
|
||||
id={embedded ? undefined : "main-content"}
|
||||
className={`case-page${embedded ? " public-record-embedded" : ""}`}
|
||||
>
|
||||
<header className="shell case-header">
|
||||
<nav className="case-breadcrumb" aria-label="문서 경로">
|
||||
<Link to="/explore/concepts">개념</Link>
|
||||
<span aria-hidden="true">/</span>
|
||||
<TargetLink target={model.topic} />
|
||||
{model.project ? (
|
||||
<>
|
||||
<span aria-hidden="true">/</span>
|
||||
<TargetLink target={model.project} />
|
||||
</>
|
||||
) : null}
|
||||
</nav>
|
||||
|
||||
<h1>{model.title}</h1>
|
||||
<p className="case-summary"><PlainText text={model.summary} /></p>
|
||||
|
||||
<dl className="case-meta">
|
||||
{model.basisVersion ? (
|
||||
<div>
|
||||
<dt>기준</dt>
|
||||
<dd><PlainText text={model.basisVersion} /></dd>
|
||||
</div>
|
||||
) : null}
|
||||
<div>
|
||||
<dt>기록</dt>
|
||||
<dd>게시 {publishedLabel(model, resolvePublishedLabel)}</dd>
|
||||
</div>
|
||||
</dl>
|
||||
</header>
|
||||
|
||||
<DocumentToc headings={headings} variant="mobile" />
|
||||
|
||||
<div className="shell document-layout">
|
||||
<article className="document-body">
|
||||
<CaseBodyRenderer
|
||||
blocks={model.bodyBlocks}
|
||||
resolveEvidenceAsset={resolveEvidenceAsset}
|
||||
/>
|
||||
<PublicDocumentRelations
|
||||
relations={publicRelations(model.relations)}
|
||||
kicker="Explicit relations"
|
||||
title="이 개념의 연결"
|
||||
/>
|
||||
</article>
|
||||
<DocumentToc headings={headings} variant="desktop" />
|
||||
</div>
|
||||
</Root>
|
||||
);
|
||||
}
|
||||
|
||||
function ReferenceDocument({
|
||||
model,
|
||||
embedded,
|
||||
@@ -508,6 +589,15 @@ export function PublicRecordRenderer({
|
||||
resolvePublishedLabel={resolvePublishedLabel}
|
||||
/>
|
||||
);
|
||||
case "CONCEPT":
|
||||
return (
|
||||
<ConceptDocument
|
||||
model={model}
|
||||
embedded={embedded}
|
||||
resolveEvidenceAsset={resolveEvidenceAsset}
|
||||
resolvePublishedLabel={resolvePublishedLabel}
|
||||
/>
|
||||
);
|
||||
case "PROJECT_DECISION":
|
||||
return (
|
||||
<ProjectDecisionDocument model={model} embedded={embedded} />
|
||||
|
||||
@@ -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>“Kubernetes 1.31” 처럼 무엇을 보고 썼는지. 비워도 됩니다.</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>“##” 소제목이 목차가 됩니다. 아키텍처 도식은 아래에서 삽입하세요.</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 = {
|
||||
|
||||
@@ -340,12 +340,14 @@ describe("TechLog explore discovery", () => {
|
||||
expect(router.state.location.pathname).toBe("/explore");
|
||||
expect(router.state.location.search).toBe("");
|
||||
});
|
||||
expect(screen.getByText("6개의 공개 기록")).toBeVisible();
|
||||
expect(screen.getByText("7개의 공개 기록")).toBeVisible();
|
||||
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",
|
||||
"/references/state-and-nonce-boundary",
|
||||
@@ -550,7 +552,7 @@ describe("TechLog search discovery", () => {
|
||||
expect(router.state.location.search).toBe("");
|
||||
});
|
||||
expect(await screen.findByRole("heading", { name: "전체 검색 결과" })).toBeVisible();
|
||||
expect(screen.getByText("9개의 검색 결과")).toBeVisible();
|
||||
expect(screen.getByText("10개의 검색 결과")).toBeVisible();
|
||||
expect(screen.getByRole("searchbox", { name: "검색어" })).toHaveValue("");
|
||||
});
|
||||
|
||||
|
||||
@@ -356,7 +356,7 @@ describe("TechLog release and profile screens", () => {
|
||||
// list opened with "Backend Architecture", which no record in the fixture
|
||||
// actually carries — the profile was advertising a topic that did not
|
||||
// exist, and nothing could have caught it while the list lived in the JSX.
|
||||
).toEqual(["JPA", "Authentication", "Redis"]);
|
||||
).toEqual(["JPA", "Authentication", "Kubernetes", "Redis"]);
|
||||
expect(within(main).queryByText(/이메일|연락처|경력|소속|회사/)).not.toBeInTheDocument();
|
||||
expect(container.querySelector('a[href^="mailto:"]')).toBeNull();
|
||||
});
|
||||
|
||||
@@ -103,7 +103,7 @@ test("searches public entities by title, summary, topic, and project without dup
|
||||
);
|
||||
|
||||
const allPaths = searchPublicContent("").map((item) => item.path);
|
||||
assert.equal(allPaths.length, 9);
|
||||
assert.equal(allPaths.length, 10);
|
||||
assert.equal(new Set(allPaths).size, allPaths.length);
|
||||
});
|
||||
|
||||
@@ -139,7 +139,7 @@ test("derives project records, decisions, and activity from canonical relationsh
|
||||
});
|
||||
|
||||
test("keeps the approved canonical corpus and grounded profile", () => {
|
||||
assert.equal(publicRecords.length, 6);
|
||||
assert.equal(publicRecords.length, 7);
|
||||
assert.equal(projects.length, 2);
|
||||
assert.equal(releases.length, 1);
|
||||
assert.equal(profile.name, "동현");
|
||||
@@ -153,6 +153,8 @@ test("keeps the approved canonical corpus and grounded profile", () => {
|
||||
assert.deepEqual(
|
||||
publicRecords.map((item) => item.path),
|
||||
[
|
||||
// 개념은 프로젝트 없이 서는 유일한 종류다 — 이 코퍼스에서 그 경우를 대표한다.
|
||||
"/concepts/kubernetes-scheduling",
|
||||
"/cases/collection-fetch-join-pagination",
|
||||
"/cases/redis-adapter-ttl-boundary",
|
||||
"/references/state-and-nonce-boundary",
|
||||
|
||||
Reference in New Issue
Block a user