feat: 환경 구성(SETUP) 기록 종류를 더한다

다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시
하려면 무엇부터 하는가다. Case 의 environment 는 평문 한 칸이라 명령이
들어가지 않고, 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.

프로젝트는 필수, 주제는 선택으로 둔다. 주제 없는 셋업이 그 프로젝트의 공통
구성이고, 주제를 붙이면 그 주제의 구성이다 — 스키마를 나누지 않고 두 범위를
같은 종류로 받는다.

버전만 본문 밖에 둔다(pinnedVersions). 이 절차가 어느 버전 위에서 성립했는지는
그 기록의 유효 범위이고, 목록과 머리말이 본문을 열지 않고 보여 줘야 한다.
나머지 셋(실행 절차·구성 값·확인 방법)은 명령과 표를 담아야 하므로 본문이다.

이름은 SETUP 이다. ENVIRONMENT 가 영어로는 자연스럽지만 case_detail.environment
와 겹친다 — 이 저장소가 열네 번 밟은 실패가 「종류를 손으로 나열한 곳을
빠뜨린다」이고 그걸 찾는 수단이 grep 이다.

손으로 나열해 두었던 자리를 이번에 표로 바꿨다. publicPath 의 삼항 사슬은
마지막 else 가 「나머지 전부」여서 새 종류의 주소가 조용히 /questions/… 가
됐고, document-editor 의 칸 경로도 같은 모양이었다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
This commit is contained in:
DongHyeonka
2026-09-09 14:12:44 +09:00
co-authored by Claude Opus 5
parent 3374f286be
commit 3af9be9e09
45 changed files with 2195 additions and 65 deletions
@@ -157,6 +157,7 @@ export function createHttpManagementGateway(
REFERENCE: "deleteReferenceDraft",
QUESTION: "deleteQuestion",
CONCEPT: "deleteConceptDraft",
SETUP: "deleteSetupDraft",
};
await run<void>(OPERATIONS[kind], { id, expectedVersion });
},
@@ -188,6 +188,7 @@ export function createHttpPublicContentGateway(
REFERENCE: "getPublicReference",
QUESTION: "getPublicQuestion",
CONCEPT: "getPublicConcept",
SETUP: "getPublicSetup",
};
const operationId = OPERATIONS[kind];
const detail = await read<Readonly<Record<string, unknown>>>(operationId, { slug });
@@ -1,6 +1,7 @@
import type {
CaseRecord,
ConceptRecord,
SetupRecord,
ProjectActivity,
ProjectDecision,
PublicRecord,
@@ -232,6 +233,7 @@ const KNOWLEDGE_LIST_KINDS: Record<string, PublicRecord["kind"]> = {
CASE: "CASE",
CONCEPT: "CONCEPT",
REFERENCE: "REFERENCE",
SETUP: "SETUP",
};
export function knowledgeListItemToRecord(item: Readonly<Record<string, unknown>>): PublicRecord | null {
@@ -263,6 +265,17 @@ export function knowledgeListItemToRecord(item: Readonly<Record<string, unknown>
sections: Object.freeze([]),
}) as CaseRecord;
}
if (type === "SETUP") {
return Object.freeze({
...base,
kind: "SETUP",
pinnedVersions: Object.freeze([]),
// 목록 항목은 본문을 담지 않는다 — 본문은 상세 조회에서만 온다.
content: "",
bodyAssets: Object.freeze([]),
sections: Object.freeze([]),
}) as SetupRecord;
}
if (type === "CONCEPT") {
return Object.freeze({
...base,
@@ -61,6 +61,7 @@ function runtimeShapeErrors(value: unknown): FieldError[] {
REFERENCE: ["purpose", "rules", "applyWhen", "exceptions", "examples", "verifiedOn"],
QUESTION: ["questionStatus", "facts", "assumptions", "unknowns", "constraints", "options", "nextValidation", "resolution"],
PROJECT_DECISION: ["decisionStatus", "decidedOn", "statement", "rationale", "consequences"],
SETUP: ["bodyMarkdown", "pinnedVersions"],
};
const known = Object.hasOwn(BRANCH_FIELDS, kind as string);
const branch = known ? BRANCH_FIELDS[kind as RecordKind] : [];
@@ -68,7 +69,7 @@ function runtimeShapeErrors(value: unknown): FieldError[] {
const allowed = new Set([...base, ...optional, ...branch]);
for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push({ path: `/${escape(key)}`, message: "Additional properties are not allowed." });
for (const key of [...base, ...branch]) if (!Object.hasOwn(value, key)) errors.push({ path: `/${key}`, message: "Field is required." });
const stringFields = ["title", "slug", "summary", ...(kind === "CASE" ? ["problem", "conclusion", "environment", "reproduction", "bodyMarkdown"] : []), ...(kind === "CONCEPT" ? ["bodyMarkdown", "basisVersion"] : []), ...(kind === "REFERENCE" ? ["purpose"] : []), ...(kind === "QUESTION" ? ["nextValidation"] : []), ...(kind === "PROJECT_DECISION" ? ["statement", "rationale"] : [])];
const stringFields = ["title", "slug", "summary", ...(kind === "CASE" ? ["problem", "conclusion", "environment", "reproduction", "bodyMarkdown"] : []), ...(kind === "CONCEPT" ? ["bodyMarkdown", "basisVersion"] : []), ...(kind === "REFERENCE" ? ["purpose"] : []), ...(kind === "QUESTION" ? ["nextValidation"] : []), ...(kind === "PROJECT_DECISION" ? ["statement", "rationale"] : []), ...(kind === "SETUP" ? ["bodyMarkdown"] : [])];
for (const key of stringFields) if (Object.hasOwn(value, key) && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a string." });
for (const key of ["topicId", "projectId"]) if (Object.hasOwn(value, key) && value[key] !== null && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a UUID or null." });
for (const key of ["lastVerifiedOn", "verifiedOn", "decidedOn"]) if (Object.hasOwn(value, key) && value[key] !== null && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a date or null." });
@@ -103,6 +104,9 @@ function runtimeShapeErrors(value: unknown): FieldError[] {
if (kind === "PROJECT_DECISION") {
checkArray("consequences", { id: "string", text: "string", order: "number" });
}
if (kind === "SETUP") {
checkArray("pinnedVersions", { name: "string", version: "string" });
}
return errors.filter((entry, index) => errors.findIndex(({ path }) => path === entry.path) === index);
}
@@ -166,6 +170,12 @@ export function validateWorkingCopyInputStructure(input: WorkingCopyInput): Fiel
} else if (input.kind === "CONCEPT") {
text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000);
text(errors, "/basisVersion", input.basisVersion, 120);
} else if (input.kind === "SETUP") {
text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000);
for (const [index, pinned] of input.pinnedVersions.entries()) {
text(errors, `/pinnedVersions/${index}/name`, pinned.name, 60, 1);
text(errors, `/pinnedVersions/${index}/version`, pinned.version, 40, 1);
}
} else {
text(errors, "/statement", input.statement, 100_000);
text(errors, "/rationale", input.rationale, 100_000);
@@ -233,6 +243,16 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat
} else if (document.kind === "CONCEPT") {
// 개념은 본문이 전부다. 비어 있으면 제목만 있는 글이 공개된다.
if (blank(document.bodyMarkdown)) warning("BODY_REQUIRED", "/bodyMarkdown", "본문을 입력하세요.");
} else if (document.kind === "SETUP") {
/*
셋업은 절차가 전부다. 본문이 비면 따라 할 것이 없다.
프로젝트는 오류다 — 셋업은 언제나 어떤 프로젝트의 셋업이고, 프로젝트가 없으면 어느
코드를 띄우는 절차인지 알 수 없다. 주제는 비어도 된다: 주제 없는 셋업이 그 프로젝트의
공통 구성이다.
*/
if (blank(document.bodyMarkdown)) error("BODY_REQUIRED", "/bodyMarkdown", "절차를 입력하세요.");
if (!document.projectId) error("PROJECT_REQUIRED", "/projectId", "프로젝트가 필요합니다.");
} 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" | "CONCEPT";
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP";
export type QuestionStatus =
| "OPEN"
| "INVESTIGATING"
@@ -121,11 +121,24 @@ export type ConceptRecord = PublicRecordBase & {
sections: ReadonlyArray<RecordSection>;
};
/**
* 환경 구성. 다른 종류가 끝난 일을 적는 것과 달리 따라 하는 절차를 적는다. 낡음은 검증일이
* 아니라 고정한 버전들이 말한다. 주제가 없어도 되는 유일한 종류다.
*/
export type SetupRecord = PublicRecordBase & {
kind: "SETUP";
pinnedVersions: ReadonlyArray<{ name: string; version: string }>;
content: string;
bodyAssets: ReadonlyArray<PublicBodyAsset>;
sections: ReadonlyArray<RecordSection>;
};
export type PublicRecord =
| CaseRecord
| ReferenceRecord
| QuestionRecord
| ConceptRecord;
| ConceptRecord
| SetupRecord;
export type ProjectDecision = {
id: string;
@@ -26,7 +26,7 @@ import type {
* 수 없는 주제를 화면이 보여주게 된다.
*/
/** 이 게이트웨이로 지울 수 있는 문서 종류. 결정은 프로젝트 경로를 요구하므로 별도 메서드다. */
export type DeletableDocumentKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
export type DeletableDocumentKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP";
export type ManagementGateway = Readonly<{
listTopics(): Promise<TopicEdit[]>;
@@ -1,4 +1,8 @@
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
/*
화면이 다루는 기록 종류. Studio 계약의 `RecordKind` 와 같은 집합이어야 한다 — 다만 결정은
자기 상세 화면이 없어 여기 없다.
*/
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP";
export type QuestionStatus =
| "OPEN"
@@ -130,11 +134,29 @@ export type ConceptRecord = PublicRecordBase & {
sections: ReadonlyArray<RecordSection>;
};
/**
* 환경 구성.
*
* <p>다른 종류가 끝난 일을 적는 것과 달리, 이 종류만 읽는 사람이 그대로 따라 하는 절차를 적는다.
* 낡음은 검증일도 한 줄짜리 기준 버전도 아니라 이름·버전 쌍의 목록이 말한다 — 이 절차가
* 성립한 버전들이 곧 유효 범위다.
*/
export type SetupRecord = PublicRecordBase & {
kind: "SETUP";
/** 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다. */
pinnedVersions: ReadonlyArray<{ name: string; version: string }>;
/** 본문 Markdown 원문. Case 와 같은 규칙으로 `:::evidence` 가 도식을 끌어온다. */
content: string;
bodyAssets: ReadonlyArray<PublicBodyAsset>;
sections: ReadonlyArray<RecordSection>;
};
export type PublicRecord =
| CaseRecord
| ReferenceRecord
| QuestionRecord
| ConceptRecord;
| ConceptRecord
| SetupRecord;
export type ProjectDecision = {
id: string;
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:fa91ee5069c1117cd328e582044e1d4f9a0787634d75d7b048f812336ebbba18",
"sourceRevision": "1aae8dc",
"digest": "sha256:0c226600c45b06433480a8a2ef3d812480dce3850c333bfcab5f626143ce77ea",
"sourceRevision": "1249527",
"operationIds": [
"createCaseDraft",
"getCaseForEdit",
@@ -13,6 +13,7 @@
"updateReferenceDraft",
"deleteReferenceDraft",
"deleteConceptDraft",
"deleteSetupDraft",
"validateCase",
"submitReviewCase",
"returnToDraftCase",
@@ -88,6 +88,26 @@ export interface paths {
patch?: never;
trace?: never;
};
"/api/v1/studio/setups/{id}": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
post?: never;
/** @description 환경 구성 작업본을 지운다. Case·Reference·개념과 같은 `document` 테이블을 쓰므로
* 같은 유스케이스가 처리하며 `document_type` 으로만 갈린다. 공개된 셋업은 지우지
* 않는다 — 공개 취소가 그 경로다.
* */
delete: operations["deleteSetupDraft"];
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/studio/cases/{id}/validate": {
parameters: {
query?: never;
@@ -1098,7 +1118,7 @@ export interface components {
};
RelatedEntry: {
/** @enum {string} */
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
title: string;
summary?: string;
path: string;
@@ -2488,6 +2508,59 @@ export interface operations {
};
};
};
deleteSetupDraft: {
parameters: {
query?: never;
header: {
"X-CSRF-TOKEN": components["parameters"]["CsrfToken"];
};
path: {
id: string;
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["ExpectedVersionRequest"];
};
};
responses: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description Bad Request */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
/** @description Conflict */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
};
};
validateCase: {
parameters: {
query?: never;
@@ -603,6 +603,52 @@ paths:
$ref: '#/components/schemas/ProblemDetails'
security:
- sessionCookie: []
/api/v1/studio/setups/{id}:
delete:
operationId: deleteSetupDraft
tags:
- Setups
description: |
환경 구성 작업본을 지운다. Case·Reference·개념과 같은 `document` 테이블을 쓰므로
같은 유스케이스가 처리하며 `document_type` 으로만 갈린다. 공개된 셋업은 지우지
않는다 — 공개 취소가 그 경로다.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/CsrfToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpectedVersionRequest'
responses:
'204':
description: No Content
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
security:
- sessionCookie: []
/api/v1/studio/cases/{id}/validate:
post:
operationId: validateCase
@@ -5973,6 +6019,7 @@ components:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
- PROJECT
- PROJECT_DECISION
- RELEASE
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:957cd1aa02ddde85420ea959c241ba7898fad6563db28d36dc0b364c2c545b03",
"sourceRevision": "1aae8dc",
"digest": "sha256:0159d7b834d69252c6edcb5102166084769a58fe1c36764958b90511bb5ec2cc",
"sourceRevision": "1249527",
"operationIds": [
"getPublicSite",
"getPublicHome",
@@ -13,6 +13,7 @@
"getPublicCase",
"getPublicReference",
"getPublicConcept",
"getPublicSetup",
"getPublicQuestion",
"listPublicProjects",
"getPublicProject",
@@ -163,6 +163,22 @@ export interface paths {
patch?: never;
trace?: never;
};
"/setups/{slug}": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get: operations["getPublicSetup"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/questions/{slug}": {
parameters: {
query?: never;
@@ -415,7 +431,7 @@ export interface components {
};
RelatedEntry: {
/** @enum {string} */
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
title: string;
summary?: string;
/** @description 작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에
@@ -476,7 +492,7 @@ export interface components {
};
LatestEntry: {
/** @enum {string} */
entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT_ACTIVITY" | "RELEASE";
entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT_ACTIVITY" | "RELEASE";
title: string;
summary: string;
path: string;
@@ -497,7 +513,7 @@ export interface components {
};
KnowledgeListItem: {
/** @enum {string} */
type: "CASE" | "REFERENCE" | "CONCEPT";
type: "CASE" | "REFERENCE" | "CONCEPT" | "SETUP";
title: string;
path: string;
primarySummary: string;
@@ -659,6 +675,50 @@ export interface components {
data: components["schemas"]["ConceptDetailResponse"];
meta: components["schemas"]["ResponseMeta"];
};
/** @description 환경 구성은 끝난 일이 아니라 따라 하는 절차다. 낡음은 검증일이 아니라
* `pinnedVersions` 가 말한다 — 어느 버전 위에서 이 절차가 성립했는지가 유효 범위다.
* 주제는 없을 수 있다. 주제 없는 셋업은 그 프로젝트의 공통 구성이다.
* */
SetupDetailResponse: {
canonicalPath: string;
/** @default true */
indexable: boolean;
setup: {
title: string;
summary: string;
/** @description 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다. */
pinnedVersions: {
name: string;
version: 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"][];
};
};
SetupDetailResponseEnvelope: {
/** @constant */
success: true;
data: components["schemas"]["SetupDetailResponse"];
meta: components["schemas"]["ResponseMeta"];
};
ReferenceDetailResponse: {
canonicalPath: string;
/** @default true */
@@ -823,7 +883,7 @@ export interface components {
* */
ProjectRecordItem: {
/** @enum {string} */
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP";
title: string;
path: string;
summary: string;
@@ -1121,7 +1181,7 @@ export interface operations {
exploreKnowledge: {
parameters: {
query?: {
type?: "CASE" | "REFERENCE" | "CONCEPT";
type?: "CASE" | "REFERENCE" | "CONCEPT" | "SETUP";
topic?: string;
/** @description 주제 안의 축 slug. 그 축에 걸린 기록만 남긴다. `topic` 과 함께 준다 — 축 slug 는
* 주제 안에서만 유일하다.
@@ -1408,6 +1468,37 @@ export interface operations {
};
};
};
getPublicSetup: {
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"]["SetupDetailResponseEnvelope"];
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorEnvelope"];
};
};
};
};
getPublicQuestion: {
parameters: {
query?: never;
@@ -1573,7 +1664,7 @@ export interface operations {
listPublicProjectRecords: {
parameters: {
query?: {
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP";
relation?: "PRIMARY" | "RELATED";
page?: number;
size?: number;
@@ -1787,7 +1878,7 @@ export interface operations {
parameters: {
query: {
q: string;
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "RELEASE";
type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "RELEASE";
topic?: string;
page?: number;
size?: number;
@@ -115,6 +115,7 @@ paths:
- CASE
- REFERENCE
- CONCEPT
- SETUP
- name: topic
in: query
schema:
@@ -390,6 +391,30 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/setups/{slug}:
get:
operationId: getPublicSetup
tags:
- Setup
parameters:
- name: slug
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetupDetailResponseEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/questions/{slug}:
get:
operationId: getPublicQuestion
@@ -530,6 +555,7 @@ paths:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
- name: relation
in: query
schema:
@@ -696,6 +722,7 @@ paths:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
- PROJECT
- RELEASE
- name: topic
@@ -917,6 +944,7 @@ components:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
- PROJECT
- PROJECT_DECISION
- RELEASE
@@ -1083,6 +1111,7 @@ components:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
- PROJECT_ACTIVITY
- RELEASE
title:
@@ -1139,6 +1168,7 @@ components:
- CASE
- REFERENCE
- CONCEPT
- SETUP
title:
type: string
path:
@@ -1513,6 +1543,112 @@ components:
$ref: '#/components/schemas/ConceptDetailResponse'
meta:
$ref: '#/components/schemas/ResponseMeta'
SetupDetailResponse:
type: object
description: |
환경 구성은 끝난 일이 아니라 따라 하는 절차다. 낡음은 검증일이 아니라
`pinnedVersions` 가 말한다 — 어느 버전 위에서 이 절차가 성립했는지가 유효 범위다.
주제는 없을 수 있다. 주제 없는 셋업은 그 프로젝트의 공통 구성이다.
required:
- canonicalPath
- indexable
- setup
- relations
properties:
canonicalPath:
type: string
indexable:
type: boolean
default: true
setup:
type: object
required:
- title
- summary
- pinnedVersions
- content
- contentFormat
- contentFormatVersion
- bodyAssets
- tags
- publishedAt
- updatedAt
properties:
title:
type: string
summary:
type: string
pinnedVersions:
type: array
description: 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다.
items:
type: object
additionalProperties: false
required:
- name
- version
properties:
name:
type: string
version:
type: string
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'
SetupDetailResponseEnvelope:
type: object
additionalProperties: false
required:
- success
- data
- meta
properties:
success:
type: boolean
const: true
data:
$ref: '#/components/schemas/SetupDetailResponse'
meta:
$ref: '#/components/schemas/ResponseMeta'
ReferenceDetailResponse:
type: object
required:
@@ -1918,6 +2054,7 @@ components:
- REFERENCE
- QUESTION
- CONCEPT
- SETUP
title:
type: string
path:
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c",
"sourceRevision": "1aae8dc",
"digest": "sha256:035b07f07eb0d26062b940a3652960444274f34ac9cb273391a3df2326ed14a8",
"sourceRevision": "1249527",
"operationIds": [
"getStudioSession",
"getStudioDashboard",
@@ -520,7 +520,7 @@ export interface components {
*
* @enum {string}
*/
RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION" | "CONCEPT";
RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION" | "CONCEPT" | "SETUP";
/** @enum {string} */
PublicationStatus: "NEVER_PUBLISHED" | "PUBLISHED" | "UNPUBLISHED";
/**
@@ -627,6 +627,13 @@ export interface components {
*/
kind: "REFERENCE";
};
/** @description 이 셋업이 어느 버전을 기준으로 쓰였는지. "Keycloak" / "26.7.0" 처럼 이름과 버전을
* 나눠 담는다. 목록과 머리말이 본문을 열지 않고 보여 주는 값이라 본문에 두지 않는다.
* */
PinnedVersion: {
name: string;
version: string;
};
ConceptInput: components["schemas"]["WorkingCopyInputBase"] & {
/** @enum {string} */
kind: "CONCEPT";
@@ -645,6 +652,22 @@ export interface components {
*/
kind: "CONCEPT";
};
SetupInput: components["schemas"]["WorkingCopyInputBase"] & {
/** @enum {string} */
kind: "SETUP";
/** @description Markdown 원문. 실행 절차·구성 값·확인 방법을 `##` 절로 적는다. 절 이름을
* 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. Asset은
* `:::evidence key="<assetKey>"` directive로 참조한다.
* */
bodyMarkdown: string;
pinnedVersions: components["schemas"]["PinnedVersion"][];
} & {
/**
* @description discriminator enum property added by openapi-typescript
* @enum {string}
*/
kind: "SETUP";
};
QuestionInput: components["schemas"]["WorkingCopyInputBase"] & {
/** @enum {string} */
kind: "QUESTION";
@@ -695,7 +718,7 @@ export interface components {
*/
kind: "PROJECT_DECISION";
};
WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"] | components["schemas"]["ConceptInput"];
WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"] | components["schemas"]["ConceptInput"] | components["schemas"]["SetupInput"];
WorkingCopyBase: components["schemas"]["WorkingCopyInputBase"] & {
/**
* Format: uuid
@@ -753,6 +776,18 @@ export interface components {
*/
kind: "CONCEPT";
};
SetupWorkingCopy: components["schemas"]["WorkingCopyBase"] & {
/** @enum {string} */
kind: "SETUP";
bodyMarkdown: string;
pinnedVersions: components["schemas"]["PinnedVersion"][];
} & {
/**
* @description discriminator enum property added by openapi-typescript
* @enum {string}
*/
kind: "SETUP";
};
QuestionWorkingCopy: components["schemas"]["WorkingCopyBase"] & {
/** @enum {string} */
kind: "QUESTION";
@@ -798,9 +833,10 @@ export interface components {
* | QuestionWorkingCopy
* | ProjectDecisionWorkingCopy
* | ConceptWorkingCopy
* | SetupWorkingCopy
* ```
* */
WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"] | components["schemas"]["ConceptWorkingCopy"];
WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"] | components["schemas"]["ConceptWorkingCopy"] | components["schemas"]["SetupWorkingCopy"];
CreateDocumentInput: components["schemas"]["WorkingCopyInput"];
SaveDocumentCommand: {
expectedVersion: number;
@@ -1184,6 +1220,18 @@ export interface components {
*/
kind: "CONCEPT";
};
SetupPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & {
/** @enum {string} */
kind: "SETUP";
pinnedVersions: components["schemas"]["PinnedVersion"][];
bodyBlocks: components["schemas"]["CaseRenderBlock"][];
} & {
/**
* @description discriminator enum property added by openapi-typescript
* @enum {string}
*/
kind: "SETUP";
};
QuestionPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & {
/** @enum {string} */
kind: "QUESTION";
@@ -1223,7 +1271,7 @@ export interface components {
*/
kind: "PROJECT_DECISION";
};
PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"] | components["schemas"]["ConceptPublicRenderModel"];
PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"] | components["schemas"]["ConceptPublicRenderModel"] | components["schemas"]["SetupPublicRenderModel"];
PublicPreview: {
/** Format: uuid */
previewId: string;
@@ -837,7 +837,7 @@ components:
# ------------------------------------------------------------ enumerations
RecordKind:
type: string
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT]
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT, SETUP]
description: |
Studio 편집 대상 유형. API projection discriminator이며 Domain Aggregate가
아니다. `PROJECT_DECISION`은 `ProjectDecision` capability로 dispatch된다.
@@ -961,6 +961,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 }
PinnedVersion:
type: object
additionalProperties: false
required: [name, version]
description: |
이 셋업이 어느 버전을 기준으로 쓰였는지. "Keycloak" / "26.7.0" 처럼 이름과 버전을
나눠 담는다. 목록과 머리말이 본문을 열지 않고 보여 주는 값이라 본문에 두지 않는다.
properties:
name: { type: string, minLength: 1, maxLength: 60 }
version: { type: string, minLength: 1, maxLength: 40 }
ConceptInput:
unevaluatedProperties: false
allOf:
@@ -981,6 +991,25 @@ components:
description: |
"Kubernetes 1.31" 처럼 이 글이 무엇을 보고 쓴 것인지 한 줄. 개념이 낡는
방식은 날짜가 아니라 버전이므로 `lastVerifiedOn` 대신 이것을 둔다. 비워도 된다.
SetupInput:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/WorkingCopyInputBase" }
- type: object
required: [kind, bodyMarkdown, pinnedVersions]
properties:
kind: { type: string, enum: [SETUP] }
bodyMarkdown:
type: string
maxLength: 100000
description: |
Markdown 원문. 실행 절차·구성 값·확인 방법을 `##` 절로 적는다. 절 이름을
강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. Asset은
`:::evidence key="<assetKey>"` directive로 참조한다.
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
QuestionInput:
unevaluatedProperties: false
allOf:
@@ -1039,6 +1068,7 @@ components:
- { $ref: "#/components/schemas/QuestionInput" }
- { $ref: "#/components/schemas/ProjectDecisionInput" }
- { $ref: "#/components/schemas/ConceptInput" }
- { $ref: "#/components/schemas/SetupInput" }
discriminator:
propertyName: kind
mapping:
@@ -1047,6 +1077,7 @@ components:
QUESTION: "#/components/schemas/QuestionInput"
PROJECT_DECISION: "#/components/schemas/ProjectDecisionInput"
CONCEPT: "#/components/schemas/ConceptInput"
SETUP: "#/components/schemas/SetupInput"
# ------------------------------------------------------- working copy output
WorkingCopyBase:
@@ -1100,6 +1131,19 @@ components:
kind: { type: string, enum: [CONCEPT] }
bodyMarkdown: { type: string, maxLength: 100000 }
basisVersion: { type: string, maxLength: 120 }
SetupWorkingCopy:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/WorkingCopyBase" }
- type: object
required: [kind, bodyMarkdown, pinnedVersions]
properties:
kind: { type: string, enum: [SETUP] }
bodyMarkdown: { type: string, maxLength: 100000 }
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
QuestionWorkingCopy:
unevaluatedProperties: false
allOf:
@@ -1143,6 +1187,7 @@ components:
| QuestionWorkingCopy
| ProjectDecisionWorkingCopy
| ConceptWorkingCopy
| SetupWorkingCopy
```
oneOf:
- { $ref: "#/components/schemas/CaseWorkingCopy" }
@@ -1150,6 +1195,7 @@ components:
- { $ref: "#/components/schemas/QuestionWorkingCopy" }
- { $ref: "#/components/schemas/ProjectDecisionWorkingCopy" }
- { $ref: "#/components/schemas/ConceptWorkingCopy" }
- { $ref: "#/components/schemas/SetupWorkingCopy" }
discriminator:
propertyName: kind
mapping:
@@ -1158,6 +1204,7 @@ components:
QUESTION: "#/components/schemas/QuestionWorkingCopy"
PROJECT_DECISION: "#/components/schemas/ProjectDecisionWorkingCopy"
CONCEPT: "#/components/schemas/ConceptWorkingCopy"
SETUP: "#/components/schemas/SetupWorkingCopy"
# -------------------------------------------------------------- commands
CreateDocumentInput: { $ref: "#/components/schemas/WorkingCopyInput" }
@@ -1596,6 +1643,19 @@ components:
kind: { type: string, enum: [CONCEPT] }
basisVersion: { type: string, maxLength: 120 }
bodyBlocks: { type: array, maxItems: 10000, items: { $ref: "#/components/schemas/CaseRenderBlock" } }
SetupPublicRenderModel:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/PublicRenderModelBase" }
- type: object
required: [kind, pinnedVersions, bodyBlocks]
properties:
kind: { type: string, enum: [SETUP] }
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
bodyBlocks: { type: array, maxItems: 10000, items: { $ref: "#/components/schemas/CaseRenderBlock" } }
QuestionPublicRenderModel:
unevaluatedProperties: false
allOf:
@@ -1641,6 +1701,7 @@ components:
- { $ref: "#/components/schemas/QuestionPublicRenderModel" }
- { $ref: "#/components/schemas/ProjectDecisionPublicRenderModel" }
- { $ref: "#/components/schemas/ConceptPublicRenderModel" }
- { $ref: "#/components/schemas/SetupPublicRenderModel" }
discriminator:
propertyName: kind
mapping:
@@ -1649,6 +1710,7 @@ components:
QUESTION: "#/components/schemas/QuestionPublicRenderModel"
PROJECT_DECISION: "#/components/schemas/ProjectDecisionPublicRenderModel"
CONCEPT: "#/components/schemas/ConceptPublicRenderModel"
SETUP: "#/components/schemas/SetupPublicRenderModel"
# ---------------------------------------------------------------- preview
PublicPreview:
@@ -526,6 +526,25 @@ const HTTP_CONTRACTS = Object.freeze([
});
},
),
writeOperation(
"deleteSetupDraft",
"DELETE",
`${D}/setups/{id}`,
{
acceptedStatuses: [204],
emptyBodyStatuses: [204],
requestByteLimit: 1_024,
responseByteLimit: 1_024,
},
(input: never) => {
const value = input as unknown as Readonly<{ id: string; expectedVersion: number }>;
return Object.freeze({
pathValues: Object.freeze({ id: value.id }),
queryEntries: NO_QUERY,
body: { expectedVersion: value.expectedVersion },
});
},
),
writeOperation(
"deleteCaseDraft",
"DELETE",
@@ -128,6 +128,7 @@ const HTTP_CONTRACTS = Object.freeze([
publicRead("getPublicReference", `${P}/references/{slug}`, 524_288, bySlug),
publicRead("getPublicQuestion", `${P}/questions/{slug}`, 524_288, bySlug),
publicRead("getPublicConcept", `${P}/concepts/{slug}`, 524_288, bySlug),
publicRead("getPublicSetup", `${P}/setups/{slug}`, 524_288, bySlug),
publicRead("listPublicProjects", `${P}/projects`, 262_144),
publicRead("getPublicProject", `${P}/projects/{slug}`, 262_144, bySlug),
publicRead("listPublicProjectDecisions", `${P}/projects/{slug}/decisions`, 262_144, bySlug),
@@ -28,6 +28,7 @@ const TECH_LOG_ROUTE_SPECS = [
defineSpec({ routeId: "TECH_LOG_CASE", path: "/cases/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: "TechLogCaseStateSearch", title: "Case", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_REFERENCE", path: "/references/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Reference", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_CONCEPT", path: "/concepts/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "개념", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_SETUP", path: "/setups/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "환경 구성", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_QUESTION", path: "/questions/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Open Question", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_TOPICS", path: "/topics", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "주제", navigationLabel: "주제", navigationOrder: 15 }),
defineSpec({ routeId: "TECH_LOG_TOPIC", path: "/topics/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Topic", navigationLabel: null, navigationOrder: null }),
@@ -7,10 +7,12 @@ import {
} from "./parse-case-content.ts";
type WorkingCopyInput = components["schemas"]["WorkingCopyInput"];
type RecordKind = components["schemas"]["RecordKind"];
type CatalogEntry = components["schemas"]["CatalogEntry"];
type PublicRenderModel = components["schemas"]["PublicRenderModel"];
type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"];
type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"];
type SetupPublicRenderModel = components["schemas"]["SetupPublicRenderModel"];
type RenderContext = components["schemas"]["RenderContext"];
/**
@@ -27,9 +29,12 @@ export type AuthoringRenderModel =
| (Omit<ConceptPublicRenderModel, "bodyBlocks"> & {
bodyBlocks: CaseAuthoringBlock[];
})
| (Omit<SetupPublicRenderModel, "bodyBlocks"> & {
bodyBlocks: CaseAuthoringBlock[];
})
| Exclude<
PublicRenderModel,
CasePublicRenderModel | ConceptPublicRenderModel
CasePublicRenderModel | ConceptPublicRenderModel | SetupPublicRenderModel
>;
export type ProjectionContext =
@@ -43,7 +48,7 @@ export type ProjectionContext =
/**
* Attaches the resolved asset descriptor to every EVIDENCE_FIGURE block of the
* two kinds that carry a markdown body — CASE and CONCEPT — turning an
* kinds that carry a markdown body — CASE, CONCEPT and SETUP — 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.
@@ -52,7 +57,7 @@ export function resolveCaseEvidenceAssets(
model: AuthoringRenderModel,
resolveAsset: (key: string) => components["schemas"]["ResolvedAsset"],
): PublicRenderModel {
if (model.kind !== "CASE" && model.kind !== "CONCEPT") return model;
if (model.kind !== "CASE" && model.kind !== "CONCEPT" && model.kind !== "SETUP") return model;
return {
...model,
@@ -154,15 +159,19 @@ function publicPath(input: WorkingCopyInput, project: CatalogEntry | null) {
}
return `${project.publicPath}/decisions#${input.slug}`;
}
const prefix =
input.kind === "CASE"
? "cases"
: input.kind === "REFERENCE"
? "references"
: input.kind === "CONCEPT"
? "concepts"
: "questions";
return `/${prefix}/${input.slug}`;
/*
삼항 사슬이던 동안 마지막 `else` 가 「나머지 전부」였다. 종류를 더하면 그 종류의 주소가
조용히 `/questions/…` 가 된다 — 게시는 되고 링크만 다른 곳을 가리킨다. 표로 두면
컴파일러가 빈 자리를 잡는다. Decision 은 위에서 먼저 돌아가므로 이 표에 없다.
*/
const PREFIXES: Record<Exclude<RecordKind, "PROJECT_DECISION">, string> = {
CASE: "cases",
REFERENCE: "references",
CONCEPT: "concepts",
QUESTION: "questions",
SETUP: "setups",
};
return `/${PREFIXES[input.kind]}/${input.slug}`;
}
function resolvedRelations(
@@ -210,6 +219,13 @@ export function projectWorkingCopy(
if (input.kind === "PROJECT_DECISION" && !project) {
fail("Decision 은 프로젝트에 속합니다. 기본 정보에서 프로젝트를 골라 주세요.");
}
/*
셋업은 언제나 어떤 프로젝트의 셋업이다. 프로젝트가 없으면 어느 코드를 띄우는 절차인지
화면이 말할 수 없다. 주제는 비어도 된다 — 주제 없는 셋업이 그 프로젝트의 공통 구성이다.
*/
if (input.kind === "SETUP" && !project) {
fail("환경 구성은 프로젝트에 속합니다. 기본 정보에서 프로젝트를 골라 주세요.");
}
const base = {
kind: input.kind,
@@ -273,6 +289,30 @@ export function projectWorkingCopy(
};
}
case "SETUP": {
/*
셋업의 본문도 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: "SETUP",
pinnedVersions: input.pinnedVersions.map((pinned) => ({ ...pinned })),
bodyBlocks,
};
}
case "REFERENCE":
return {
...base,
@@ -18,6 +18,7 @@ const EXPLORE_KIND_ORDER: Record<RecordKind, number> = {
REFERENCE: 2,
QUESTION: 3,
CONCEPT: 4,
SETUP: 5,
};
export const EXPLORE_KINDS: ReadonlyArray<RecordKind> = Object.freeze(
@@ -0,0 +1,81 @@
import type { SetupRecord } from "../../../application/ports/public-content-queries.ts";
import {
parseCaseContent,
type CaseAuthoringBlock,
} from "../../../domain/content-format/parse-case-content.ts";
import { resolveCaseEvidenceAssets } from "../../../domain/content-format/project-public-render-model.ts";
import { PublicRecordRenderer } from "../../shared/public-render/public-record-renderer.tsx";
import { publicRenderModelBase } from "./public-document-header.tsx";
/**
* 환경 구성의 본문도 Case 와 같은 파서를 탄다 — `##` 소제목이 목차가 되고 `:::evidence` 가
* 도식을 끌어온다. 셋업 절차에 구성도가 붙는 길이 그것뿐이다.
*
* <p>본문이 지원하지 않는 문법을 담고 있으면 화면 전체를 잃는 대신 빈 블록으로 돌아간다.
* 읽는 사람에게는 덜 정확한 화면이 빈 화면보다 낫다 — Case 가 쓰는 것과 같은 판단이다.
*/
function setupBodyBlocks(record: SetupRecord): CaseAuthoringBlock[] {
if (!record.content.trim()) return [];
try {
return parseCaseContent(record.content);
} catch {
return [];
}
}
export function SetupDocumentPage({ record }: { record: SetupRecord }) {
/*
본문은 evidence 를 key 로만 가리키고 `/media/{assetId}` 는 UUID 로만 서빙하므로, 계약이 함께
준 `bodyAssets` 로 key 를 주소로 바꾼다. 대응이 없는 key 는 그 블록을 지운다 — 해석기가
던지면 문서 전체가 사라지고, 남겨 두면 주소 없는 그림 자리가 남는다.
*/
const assetsByKey = new Map(
record.bodyAssets.map((asset) => [asset.assetKey, asset]),
);
const blocks = setupBodyBlocks(record).filter(
(block) => block.type !== "EVIDENCE_FIGURE" || assetsByKey.has(block.key),
);
const model = resolveCaseEvidenceAssets(
{
...publicRenderModelBase(record),
kind: "SETUP",
pinnedVersions: record.pinnedVersions.map((pinned) => ({ ...pinned })),
bodyBlocks: blocks,
},
(key) => {
const asset = assetsByKey.get(key);
// 위에서 이미 걸렀다 — 여기 닿으면 필터와 해석기가 어긋난 것이다.
if (!asset) throw new Error(`setup evidence asset not found: ${key}`);
return {
assetId: asset.assetId,
assetKey: asset.assetKey,
mediaType: asset.contentType,
publicPath: asset.url,
width: asset.width,
height: asset.height,
decorative: asset.decorative,
};
},
);
return (
<PublicRecordRenderer
model={model}
resolveEvidenceAsset={(key) => {
const asset = assetsByKey.get(key);
if (!asset) throw new Error(`setup evidence asset not found: ${key}`);
return {
src: asset.url,
width: asset.width ?? 0,
height: asset.height ?? 0,
triggerLabel: `${asset.altText || asset.assetKey} 크게 보기`,
dialogLabel: asset.altText || asset.assetKey,
};
}}
resolvePublishedLabel={(path) =>
path === record.path ? record.publishedLabel : undefined
}
/>
);
}
@@ -14,6 +14,7 @@ const kinds = {
references: { kind: "REFERENCE", title: DOCUMENT_KIND_LABELS.REFERENCE, description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." },
questions: { kind: "QUESTION", title: DOCUMENT_KIND_LABELS.QUESTION, description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." },
concepts: { kind: "CONCEPT", title: DOCUMENT_KIND_LABELS.CONCEPT, description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." },
setups: { kind: "SETUP", title: DOCUMENT_KIND_LABELS.SETUP, description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다." },
} as const;
function optionalString(value: unknown): string | undefined {
@@ -25,7 +26,8 @@ function getKindConfig(value: string | undefined) {
value === "cases" ||
value === "references" ||
value === "questions" ||
value === "concepts"
value === "concepts" ||
value === "setups"
) {
return kinds[value];
}
@@ -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", CONCEPT: "개념", PROJECT: "Project", RELEASE: "Release" } as const;
const labels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", CONCEPT: "개념", SETUP: "환경 구성", PROJECT: "Project", RELEASE: "Release" } as const;
function optionalString(value: unknown): string | undefined {
return typeof value === "string" ? value : undefined;
@@ -0,0 +1,29 @@
import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { SetupDocumentPage } from "../components/setup-document-page.tsx";
import { usePublicContent } from "../use-public-content.tsx";
function optionalString(value: unknown): string | undefined {
return typeof value === "string" ? value : undefined;
}
export function SetupPage() {
const { params } = useRouteInput<"TECH_LOG_SETUP">();
const slug = optionalString(params.slug);
const view = usePublicContent(
["tech-log", "setup", slug],
async (queries) => ({
record: slug ? await queries.getRecord("SETUP", slug) : undefined,
}),
);
if (!view.ready) return view.fallback;
const { record } = view.data;
return record ? (
<SetupDocumentPage record={record} />
) : (
<RegisteredNotFoundRoute />
);
}
@@ -23,6 +23,7 @@ export const DOCUMENT_KIND_LABELS: Record<RecordKind, string> = {
REFERENCE: "적용 기준",
PROJECT_DECISION: "설계 결정",
QUESTION: "열린 질문",
SETUP: "환경 구성",
};
/**
@@ -38,6 +39,8 @@ export const DOCUMENT_KIND_STATES: Record<RecordKind, "CONFIRMED" | "SETTLED" |
REFERENCE: "SETTLED",
PROJECT_DECISION: "SETTLED",
QUESTION: "OPEN",
/* 셋업은 확인한 것도 열린 것도 아니다 — 절차를 정리해 둔 것이다. */
SETUP: "SETTLED",
};
/**
@@ -56,4 +59,5 @@ export const EXPLORE_KIND_PATHS: Record<RecordKind, string> = {
REFERENCE: "/explore/references",
QUESTION: "/explore/questions",
PROJECT_DECISION: "/projects",
SETUP: "/explore/setups",
};
@@ -21,6 +21,7 @@ type PublicRenderModelBase = components["schemas"]["PublicRenderModelBase"];
type ResolvedRelation = components["schemas"]["ResolvedRelation"];
type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"];
type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"];
type SetupPublicRenderModel = components["schemas"]["SetupPublicRenderModel"];
type ReferencePublicRenderModel =
components["schemas"]["ReferencePublicRenderModel"];
type QuestionPublicRenderModel =
@@ -308,6 +309,93 @@ function ConceptDocument({
);
}
/**
* 환경 구성.
*
* <p>개념과 같은 본문·목차·Asset 을 쓰되 머리말이 다르다. 낡음을 말하는 것이 한 줄짜리
* 「기준」이 아니라 이름·버전 쌍의 표다 — Keycloak 과 Spring Boot 와 PostgreSQL 이 각각
* 어느 버전이었는지가 이 절차의 유효 범위다.
*
* <p>주제는 없을 수 있다. 주제 없는 셋업이 그 프로젝트의 공통 구성이고, 그때는 경로에서
* 주제 마디를 뺀다 — 빈 링크가 남으면 누를 것이 없는 자리가 생긴다.
*/
function SetupDocument({
model,
embedded,
resolveEvidenceAsset,
resolvePublishedLabel,
}: {
model: SetupPublicRenderModel;
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/setups">{DOCUMENT_KIND_LABELS.SETUP}</Link>
{model.topic.label ? (
<>
<span aria-hidden="true">/</span>
<TargetLink target={model.topic} />
</>
) : null}
{model.project ? (
<>
<span aria-hidden="true">/</span>
<TargetLink target={model.project} />
</>
) : null}
</nav>
<h1>{model.title}</h1>
<ProseText text={model.summary} className="case-summary" />
{model.pinnedVersions.length > 0 ? (
<dl className="case-meta setup-versions">
{model.pinnedVersions.map((pinned) => (
<div key={`${pinned.name}-${pinned.version}`}>
<dt>{pinned.name}</dt>
<dd>{pinned.version}</dd>
</div>
))}
</dl>
) : null}
<dl className="case-meta">
<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)} />
</article>
<DocumentToc headings={headings} variant="desktop" />
</div>
</Root>
);
}
function ReferenceDocument({
model,
embedded,
@@ -613,6 +701,15 @@ export function PublicRecordRenderer({
resolvePublishedLabel={resolvePublishedLabel}
/>
);
case "SETUP":
return (
<SetupDocument
model={model}
embedded={embedded}
resolveEvidenceAsset={resolveEvidenceAsset}
resolvePublishedLabel={resolvePublishedLabel}
/>
);
case "PROJECT_DECISION":
return (
<ProjectDecisionDocument model={model} embedded={embedded} />
@@ -11,8 +11,10 @@ import { DECISION_FIELD_PATHS, ProjectDecisionFields } from "./project-decision-
import { issuesOutside } from "./field-issues.tsx";
import { QUESTION_FIELD_PATHS, QuestionFields } from "./question-fields.tsx";
import { REFERENCE_FIELD_PATHS, ReferenceFields } from "./reference-fields.tsx";
import { SETUP_FIELD_PATHS, SetupFields } from "./setup-fields.tsx";
type CatalogEntry = components["schemas"]["CatalogEntry"];
type RecordKind = components["schemas"]["RecordKind"];
export function DocumentEditor({
controller,
@@ -44,15 +46,20 @@ 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"
? QUESTION_FIELD_PATHS
: DECISION_FIELD_PATHS;
/*
삼항 사슬의 마지막 else 가 「나머지 전부」였다. 종류를 더하면 그 종류의 지적이 결정의
칸 경로로 걸러져, 자기 칸 아래에 붙지도 게시 버튼 옆에 남지도 않고 사라진다. 표로 두면
컴파일러가 빈 자리를 잡는다.
*/
const KIND_PATHS: Record<RecordKind, readonly string[]> = {
CASE: CASE_FIELD_PATHS,
CONCEPT: CONCEPT_FIELD_PATHS,
REFERENCE: REFERENCE_FIELD_PATHS,
QUESTION: QUESTION_FIELD_PATHS,
SETUP: SETUP_FIELD_PATHS,
PROJECT_DECISION: DECISION_FIELD_PATHS,
};
const kindPaths = KIND_PATHS[controller.draft.kind];
const unplaced = issuesOutside(issues, [...COMMON_FIELD_PATHS, ...kindPaths]);
/*
@@ -77,6 +84,8 @@ export function DocumentEditor({
? <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 === "SETUP"
? <SetupFields 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"
@@ -20,7 +20,8 @@ const STUDIO_KIND_ORDER: Record<RecordKind, number> = {
CONCEPT: 2,
REFERENCE: 3,
QUESTION: 4,
PROJECT_DECISION: 5,
SETUP: 5,
PROJECT_DECISION: 6,
};
const STUDIO_KINDS: ReadonlyArray<RecordKind> = Object.freeze(
@@ -26,6 +26,12 @@ const types = [
description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다.",
fields: "기준 버전 · 본문",
},
{
kind: "SETUP",
title: "환경 구성",
description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다.",
fields: "버전 · 본문",
},
{
kind: "QUESTION",
title: "Question",
@@ -76,6 +82,18 @@ function emptyDocument(kind: RecordKind): CreateDocumentInput {
if (kind === "CONCEPT") {
return { ...common, kind, bodyMarkdown: "", basisVersion: "" };
}
if (kind === "SETUP") {
/*
절 이름을 스키마로 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. 대신 빈 본문
대신 뼈대를 넣어 준다. 지우고 자기 절을 써도 되고, 그대로 채워도 된다.
*/
return {
...common,
kind,
bodyMarkdown: "## 실행 절차\n\n## 구성 값\n\n## 확인 방법\n",
pinnedVersions: [],
};
}
if (kind === "QUESTION") {
return {
...common,
@@ -0,0 +1,202 @@
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 { MarkdownToolbar } from "./markdown-toolbar.tsx";
import { FieldNotice, type FieldIssue } from "./field-issues.tsx";
type SetupInput = components["schemas"]["SetupInput"];
type PinnedVersion = components["schemas"]["PinnedVersion"];
/** 이 화면이 자기 칸 아래에 보여 줄 수 있는 경로. */
export const SETUP_FIELD_PATHS = ["/pinnedVersions", "/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}`);
}
/**
* 환경 구성 편집 화면.
*
* <p>다른 다섯 종류는 끝난 일을 적는다. 이 종류만 읽는 사람이 그대로 따라 하는 절차를 적으므로,
* 본문에 명령과 표가 들어간다 — Case 의 「검증 환경」 같은 평문 한 칸으로는 담기지 않는다.
*
* <p>버전만 본문 밖에 둔다. 이 절차가 어느 버전 위에서 성립했는지는 그 기록의 유효 범위이고,
* 목록과 머리말이 본문을 열지 않고 보여 줘야 하는 값이기 때문이다. 개념의 「기준 버전」이 같은
* 이유로 따로 있고, 다른 점은 셋업의 버전이 하나가 아니라 여럿이라는 것뿐이다.
*/
export function SetupFields({
draft,
issues,
onChange,
onAssetsObserved,
onAssetUploaded,
}: {
draft: SetupInput;
/** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */
issues: readonly FieldIssue[];
onChange(draft: SetupInput): void;
onAssetsObserved?: (assets: readonly Asset[]) => void;
onAssetUploaded?: (asset: Asset) => void;
}) {
const assetGateway = useStudioAssetGateway();
const bodyRef = useRef<HTMLTextAreaElement>(null);
const uploadTriggerRef = useRef<HTMLButtonElement>(null);
const [uploadKind, setUploadKind] = useState<AssetKind>("DIAGRAM");
const [uploadOpen, setUploadOpen] = useState(false);
const update = (patch: Partial<SetupInput>) => onChange({ ...draft, ...patch });
const replaceVersion = (index: number, patch: Partial<PinnedVersion>) => {
update({
pinnedVersions: draft.pinnedVersions.map((pinned, at) =>
at === index ? { ...pinned, ...patch } : pinned,
),
});
};
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-setup-fields-title">
<div className="studio-editor-section-heading">
<p className="studio-eyebrow">SETUP</p>
<h2 id="studio-setup-fields-title">환경 구성</h2>
</div>
<div className="studio-field-grid">
<div className="studio-field studio-field--wide" role="group" aria-labelledby="studio-pinned-versions-title">
<span id="studio-pinned-versions-title">고정한 버전</span>
<ul className="studio-pinned-versions">
{draft.pinnedVersions.map((pinned, index) => (
// 행에는 안정된 식별자가 없다. 값으로 키를 만들면 이름을 지우는 순간 키가
// 겹쳐 입력 중이던 칸이 다른 행으로 옮겨 간다.
<li key={index}>
<label>
<span>이름</span>
<input
value={pinned.name}
onChange={(event) => replaceVersion(index, { name: event.currentTarget.value })}
/>
</label>
<label>
<span>버전</span>
<input
value={pinned.version}
onChange={(event) => replaceVersion(index, { version: event.currentTarget.value })}
/>
</label>
<button
type="button"
onClick={() =>
update({
pinnedVersions: draft.pinnedVersions.filter((_, at) => at !== index),
})
}
>
{`${pinned.name || `${index + 1}번째`} 삭제`}
</button>
</li>
))}
</ul>
<button
type="button"
onClick={() =>
update({ pinnedVersions: [...draft.pinnedVersions, { name: "", version: "" }] })
}
>
버전 추가
</button>
<small>&ldquo;Keycloak&rdquo; / &ldquo;26.7.0&rdquo; 처럼 적습니다. 비우면 화면에 표를 그리지 않습니다.</small>
<FieldNotice issues={issues} path="/pinnedVersions" />
</div>
<div className="studio-field studio-field--wide">
<label htmlFor="studio-field-body">절차 Markdown</label>
<MarkdownToolbar target={bodyRef} onInsert={(next) => update({ bodyMarkdown: next })} />
<textarea
id="studio-field-body"
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" />
</div>
</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>
);
}
@@ -75,6 +75,13 @@ export const TECH_LOG_ROUTE_RUNTIME = Object.freeze({
"ConceptPage",
),
),
TECH_LOG_SETUP: runtime(
"TECH_LOG_SETUP",
routeModule(
() => import("./public/pages/setup-page.tsx"),
"SetupPage",
),
),
TECH_LOG_QUESTION: runtime(
"TECH_LOG_QUESTION",
routeModule(