diff --git a/public/release-manifest.json b/public/release-manifest.json index faab20d..5ce7802 100644 --- a/public/release-manifest.json +++ b/public/release-manifest.json @@ -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" } ] } diff --git a/src/features/tech-log/adapters/mock/validate-working-copy.ts b/src/features/tech-log/adapters/mock/validate-working-copy.ts index cad2e77..a3d52dd 100644 --- a/src/features/tech-log/adapters/mock/validate-working-copy.ts +++ b/src/features/tech-log/adapters/mock/validate-working-copy.ts @@ -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", "결정일이 필요합니다."); diff --git a/src/features/tech-log/adapters/static/public-content.ts b/src/features/tech-log/adapters/static/public-content.ts index 777cba5..ad1022c 100644 --- a/src/features/tech-log/adapters/static/public-content.ts +++ b/src/features/tech-log/adapters/static/public-content.ts @@ -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; + sections: ReadonlyArray; +}; + +export type PublicRecord = + | CaseRecord + | ReferenceRecord + | QuestionRecord + | ConceptRecord; export type ProjectDecision = { id: string; @@ -167,6 +183,49 @@ export type HomeFocusItem = { }; export const publicRecords: ReadonlyArray = [ + { + 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", diff --git a/src/features/tech-log/adapters/static/public-query.ts b/src/features/tech-log/adapters/static/public-query.ts index 188d9dd..648ace9 100644 --- a/src/features/tech-log/adapters/static/public-query.ts +++ b/src/features/tech-log/adapters/static/public-query.ts @@ -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() diff --git a/src/features/tech-log/application/ports/public-content-queries.ts b/src/features/tech-log/application/ports/public-content-queries.ts index 5028a52..8508a60 100644 --- a/src/features/tech-log/application/ports/public-content-queries.ts +++ b/src/features/tech-log/application/ports/public-content-queries.ts @@ -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; +/** + * 개념. + * + *

Reference 는 판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉜다. 개념은 그렇게 나누지 않는다 — + * 처음부터 풀어 읽는 글이라 본문 하나로 흐르고, 낡음은 검증일이 아니라 `basisVersion` 이 말한다. + */ +export type ConceptRecord = PublicRecordBase & { + kind: "CONCEPT"; + /** "Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 비면 화면에 그리지 않는다. */ + basisVersion: string; + /** 본문 Markdown 원문. Case 와 같은 규칙으로 `:::evidence` 가 도식을 끌어온다. */ + content: string; + bodyAssets: ReadonlyArray; + sections: ReadonlyArray; +}; + +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; diff --git a/src/features/tech-log/contracts/management/canonical-source.json b/src/features/tech-log/contracts/management/canonical-source.json index 4642375..6456c15 100644 --- a/src/features/tech-log/contracts/management/canonical-source.json +++ b/src/features/tech-log/contracts/management/canonical-source.json @@ -2,7 +2,7 @@ "packageId": "@tech-log/management-contract", "version": "1.0.0", "digest": "sha256:72650735061fde627f5037571eb986cb758f44a546f065c88408399f8eec4a55", - "sourceRevision": "ef49d3a", + "sourceRevision": "777aeaa", "operationIds": [ "createCaseDraft", "getCaseForEdit", diff --git a/src/features/tech-log/contracts/public/canonical-source.json b/src/features/tech-log/contracts/public/canonical-source.json index 61433d0..68be42a 100644 --- a/src/features/tech-log/contracts/public/canonical-source.json +++ b/src/features/tech-log/contracts/public/canonical-source.json @@ -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", diff --git a/src/features/tech-log/contracts/public/generated.ts b/src/features/tech-log/contracts/public/generated.ts index 1c7f5a1..3990cce 100644 --- a/src/features/tech-log/contracts/public/generated.ts +++ b/src/features/tech-log/contracts/public/generated.ts @@ -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; diff --git a/src/features/tech-log/contracts/public/public-api.openapi.yaml b/src/features/tech-log/contracts/public/public-api.openapi.yaml index 1631d17..f29300e 100644 --- a/src/features/tech-log/contracts/public/public-api.openapi.yaml +++ b/src/features/tech-log/contracts/public/public-api.openapi.yaml @@ -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: diff --git a/src/features/tech-log/contracts/studio/canonical-source.json b/src/features/tech-log/contracts/studio/canonical-source.json index c014d8b..5d5a6da 100644 --- a/src/features/tech-log/contracts/studio/canonical-source.json +++ b/src/features/tech-log/contracts/studio/canonical-source.json @@ -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", diff --git a/src/features/tech-log/contracts/studio/generated.ts b/src/features/tech-log/contracts/studio/generated.ts index 12470dc..04f484f 100644 --- a/src/features/tech-log/contracts/studio/generated.ts +++ b/src/features/tech-log/contracts/studio/generated.ts @@ -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=""` 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; diff --git a/src/features/tech-log/contracts/studio/studio-api.openapi.yaml b/src/features/tech-log/contracts/studio/studio-api.openapi.yaml index fb37387..d2f21ad 100644 --- a/src/features/tech-log/contracts/studio/studio-api.openapi.yaml +++ b/src/features/tech-log/contracts/studio/studio-api.openapi.yaml @@ -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=""` 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: diff --git a/src/features/tech-log/domain/content-format/project-public-render-model.ts b/src/features/tech-log/domain/content-format/project-public-render-model.ts index c66294f..e21ce19 100644 --- a/src/features/tech-log/domain/content-format/project-public-render-model.ts +++ b/src/features/tech-log/domain/content-format/project-public-render-model.ts @@ -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 & { bodyBlocks: CaseAuthoringBlock[]; }) - | Exclude; + | (Omit & { + 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, diff --git a/src/features/tech-log/presentation/public/components/public-document-header.tsx b/src/features/tech-log/presentation/public/components/public-document-header.tsx index 6f561c1..55b28c0 100644 --- a/src/features/tech-log/presentation/public/components/public-document-header.tsx +++ b/src/features/tech-log/presentation/public/components/public-document-header.tsx @@ -7,6 +7,7 @@ const kindLabels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", + CONCEPT: "개념", } as const; export function PublicDocumentHeader({ record }: { record: PublicRecord }) { diff --git a/src/features/tech-log/presentation/public/components/public-record-list.tsx b/src/features/tech-log/presentation/public/components/public-record-list.tsx index d76989b..f155862 100644 --- a/src/features/tech-log/presentation/public/components/public-record-list.tsx +++ b/src/features/tech-log/presentation/public/components/public-record-list.tsx @@ -6,6 +6,7 @@ const kindLabels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", + CONCEPT: "개념", } as const; export function PublicRecordList({ diff --git a/src/features/tech-log/presentation/public/pages/search-page.tsx b/src/features/tech-log/presentation/public/pages/search-page.tsx index 9daa1bb..3f5bdc6 100644 --- a/src/features/tech-log/presentation/public/pages/search-page.tsx +++ b/src/features/tech-log/presentation/public/pages/search-page.tsx @@ -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; diff --git a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx index 9ac7bfe..c4af708 100644 --- a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx +++ b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx @@ -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({ ); } +/** + * 개념. + * + *

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 ( + +

+ + +

{model.title}

+

</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} /> diff --git a/src/features/tech-log/presentation/studio/components/concept-fields.tsx b/src/features/tech-log/presentation/studio/components/concept-fields.tsx new file mode 100644 index 0000000..399fed0 --- /dev/null +++ b/src/features/tech-log/presentation/studio/components/concept-fields.tsx @@ -0,0 +1,134 @@ +import { useRef, useState } from "react"; + +import type { components } from "../../../contracts/studio/generated.ts"; +import type { Asset, AssetKind } from "../../../contracts/studio/contract.ts"; +import { useStudioAssetGateway } from "../use-studio.ts"; +import { AssetPicker, buildEvidenceDirective } from "./asset-picker.tsx"; +import { AssetUploadDialog } from "./asset-upload-dialog.tsx"; +import { FieldNotice, type FieldIssue } from "./field-issues.tsx"; + +type ConceptInput = components["schemas"]["ConceptInput"]; + +/** 이 화면이 자기 칸 아래에 보여 줄 수 있는 경로. */ +export const CONCEPT_FIELD_PATHS = ["/basisVersion", "/bodyMarkdown"] as const; + +const ASSET_KIND_OPTIONS: ReadonlyArray<{ value: AssetKind; label: string }> = [ + { value: "IMAGE", label: "이미지" }, + { value: "DIAGRAM", label: "다이어그램" }, + { value: "ATTACHMENT", label: "첨부파일" }, +]; + +/** + * `:::evidence ...` is a block directive, so the parser requires a blank line + * before and after it. Inserting straight into `selectionStart`/`selectionEnd` + * without normalizing the surrounding whitespace would produce a directive + * glued to adjacent text -- a well-formed-looking block that the parser still + * rejects. + */ +function insertAtCursor( + textarea: HTMLTextAreaElement, + directive: string, + commit: (next: string) => void, +) { + const { selectionStart, selectionEnd, value } = textarea; + const prefix = value.slice(0, selectionStart); + const suffix = value.slice(selectionEnd); + const before = prefix.length === 0 || prefix.endsWith("\n\n") ? prefix : `${prefix}\n\n`; + const after = suffix.startsWith("\n") ? suffix : `\n${suffix}`; + commit(`${before}${directive}${after}`); +} + +export function ConceptFields({ + draft, + issues, + onChange, + onAssetsObserved, + onAssetUploaded, +}: { + draft: ConceptInput; + /** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */ + issues: readonly FieldIssue[]; + onChange(draft: ConceptInput): void; + /** + * The editor screen owns the resolution catalog Instant Preview reads, and + * merges what the Picker observes into it -- it never adopts the Picker's + * (searchable, and so narrowable) displayed list wholesale. + */ + onAssetsObserved?: (assets: readonly Asset[]) => void; + onAssetUploaded?: (asset: Asset) => void; +}) { + // Asset UI must use the throwing accessor, not the nullable `assetGateway` + // field directly -- see `use-studio.ts`'s `useStudioAssetGateway` doc. + const assetGateway = useStudioAssetGateway(); + const bodyRef = useRef<HTMLTextAreaElement>(null); + const uploadTriggerRef = useRef<HTMLButtonElement>(null); + const [uploadKind, setUploadKind] = useState<AssetKind>("IMAGE"); + const [uploadOpen, setUploadOpen] = useState(false); + const update = (patch: Partial<ConceptInput>) => onChange({ ...draft, ...patch }); + + const insertDirective = (directive: string) => { + const textarea = bodyRef.current; + if (!textarea) { + update({ + bodyMarkdown: draft.bodyMarkdown + ? `${draft.bodyMarkdown}\n\n${directive}\n` + : `${directive}\n`, + }); + return; + } + insertAtCursor(textarea, directive, (next) => update({ bodyMarkdown: next })); + }; + + const closeUpload = () => { + setUploadOpen(false); + queueMicrotask(() => uploadTriggerRef.current?.focus()); + }; + + return ( + <section className="studio-editor-section" aria-labelledby="studio-concept-fields-title"> + <div className="studio-editor-section-heading"><p className="studio-eyebrow">CONCEPT</p><h2 id="studio-concept-fields-title">개념</h2></div> + <div className="studio-field-grid"> + <label className="studio-field"><span>기준 버전</span><input value={draft.basisVersion} onChange={(event) => update({ basisVersion: event.currentTarget.value })} /><small>&ldquo;Kubernetes 1.31&rdquo; 처럼 무엇을 보고 썼는지. 비워도 됩니다.</small><FieldNotice issues={issues} path="/basisVersion" /></label> + <label className="studio-field studio-field--wide"><span>본문 Markdown</span><textarea ref={bodyRef} className="studio-markdown-field" value={draft.bodyMarkdown} onChange={(event) => update({ bodyMarkdown: event.currentTarget.value })} /><small>&ldquo;##&rdquo; 소제목이 목차가 됩니다. 아키텍처 도식은 아래에서 삽입하세요.</small><FieldNotice issues={issues} path="/bodyMarkdown" /></label> + </div> + <div className="studio-asset-panel" role="group" aria-labelledby="studio-asset-panel-title"> + <p className="studio-eyebrow">EVIDENCE</p> + <h3 id="studio-asset-panel-title">본문에 Asset 삽입</h3> + <p>목록에서 선택하면 본문 커서 위치에 evidence 구문을 삽입합니다. READY 상태의 Asset만 선택할 수 있습니다.</p> + <div className="studio-asset-panel-actions"> + <label className="studio-asset-kind-field"> + <span>업로드 종류</span> + <select value={uploadKind} onChange={(event) => setUploadKind(event.currentTarget.value as AssetKind)}> + {ASSET_KIND_OPTIONS.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)} + </select> + </label> + <button + ref={uploadTriggerRef} + type="button" + onClick={() => setUploadOpen(true)} + > + Asset 업로드 + </button> + </div> + <AssetPicker gateway={assetGateway} onAssetsObserved={onAssetsObserved} onInsert={insertDirective} /> + </div> + {uploadOpen ? ( + <AssetUploadDialog + gateway={assetGateway} + kind={uploadKind} + onUploaded={(asset) => { + onAssetUploaded?.(asset); + insertDirective(buildEvidenceDirective({ + assetKey: asset.assetKey, + alt: asset.decorative ? "" : (asset.altText ?? ""), + caption: "", + zoom: asset.kind === "DIAGRAM", + })); + closeUpload(); + }} + onClose={closeUpload} + /> + ) : null} + </section> + ); +} diff --git a/src/features/tech-log/presentation/studio/components/document-editor.tsx b/src/features/tech-log/presentation/studio/components/document-editor.tsx index c772801..939c548 100644 --- a/src/features/tech-log/presentation/studio/components/document-editor.tsx +++ b/src/features/tech-log/presentation/studio/components/document-editor.tsx @@ -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" diff --git a/src/features/tech-log/presentation/studio/components/document-list.tsx b/src/features/tech-log/presentation/studio/components/document-list.tsx index bf16a2b..bd4e9a5 100644 --- a/src/features/tech-log/presentation/studio/components/document-list.tsx +++ b/src/features/tech-log/presentation/studio/components/document-list.tsx @@ -10,6 +10,7 @@ const kindLabel = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Question", + CONCEPT: "개념", PROJECT_DECISION: "Decision", } as const; const publicationLabel = { diff --git a/src/features/tech-log/presentation/studio/components/document-status-bar.tsx b/src/features/tech-log/presentation/studio/components/document-status-bar.tsx index 42d120c..0907868 100644 --- a/src/features/tech-log/presentation/studio/components/document-status-bar.tsx +++ b/src/features/tech-log/presentation/studio/components/document-status-bar.tsx @@ -12,6 +12,7 @@ const kindLabels = { CASE: "CASE", REFERENCE: "REFERENCE", QUESTION: "QUESTION", + CONCEPT: "CONCEPT", PROJECT_DECISION: "Decision", } as const; diff --git a/src/features/tech-log/presentation/studio/components/new-document-form.tsx b/src/features/tech-log/presentation/studio/components/new-document-form.tsx index 8be4ebc..0dcffa9 100644 --- a/src/features/tech-log/presentation/studio/components/new-document-form.tsx +++ b/src/features/tech-log/presentation/studio/components/new-document-form.tsx @@ -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, diff --git a/src/features/tech-log/presentation/studio/components/publication-list.tsx b/src/features/tech-log/presentation/studio/components/publication-list.tsx index 7d35ccd..6da95f6 100644 --- a/src/features/tech-log/presentation/studio/components/publication-list.tsx +++ b/src/features/tech-log/presentation/studio/components/publication-list.tsx @@ -28,6 +28,7 @@ const kindLabels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Question", + CONCEPT: "개념", PROJECT_DECISION: "Decision", } as const; diff --git a/src/features/tech-log/presentation/studio/components/studio-dashboard.tsx b/src/features/tech-log/presentation/studio/components/studio-dashboard.tsx index 9a620b5..e2662e6 100644 --- a/src/features/tech-log/presentation/studio/components/studio-dashboard.tsx +++ b/src/features/tech-log/presentation/studio/components/studio-dashboard.tsx @@ -12,6 +12,7 @@ const kindLabel = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Question", + CONCEPT: "개념", PROJECT_DECISION: "Decision", } as const; const actionLabel = { diff --git a/tests/features/tech-log/public-discovery-screens.test.tsx b/tests/features/tech-log/public-discovery-screens.test.tsx index fef37d4..5b9017e 100644 --- a/tests/features/tech-log/public-discovery-screens.test.tsx +++ b/tests/features/tech-log/public-discovery-screens.test.tsx @@ -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(""); }); diff --git a/tests/features/tech-log/public-index-screens.test.tsx b/tests/features/tech-log/public-index-screens.test.tsx index a90b09a..951fe98 100644 --- a/tests/features/tech-log/public-index-screens.test.tsx +++ b/tests/features/tech-log/public-index-screens.test.tsx @@ -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(); }); diff --git a/tests/features/tech-log/public-query.test.ts b/tests/features/tech-log/public-query.test.ts index 12e7953..4ff0cc9 100644 --- a/tests/features/tech-log/public-query.test.ts +++ b/tests/features/tech-log/public-query.test.ts @@ -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",