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
@@ -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: