From 618a228eff319d3ab79fe56ab78b484c2b92ef99 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 1 Sep 2026 16:48:11 +0900 Subject: [PATCH] =?UTF-8?q?fix:=20=EA=B4=80=EA=B3=84=EC=9D=98=20=EB=AC=B6?= =?UTF-8?q?=EC=9D=8C=20=EC=9D=B4=EB=A6=84=EA=B3=BC=20=EC=9E=91=EC=84=B1?= =?UTF-8?q?=EC=9E=90=EA=B0=80=20=EC=93=B4=20=EB=AC=B8=EC=9E=A5=EC=9D=84=20?= =?UTF-8?q?=EA=B0=88=EB=9D=BC=20=EB=86=93=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지, 대상이 무엇인지 — 셋 다 `reason` 한 칸을 지나느라 경로마다 다른 것이 같은 자리에 나왔다. 렌더 모델 경로에서는 작성자의 문장이 묶음 이름 자리에 눌려 한 줄짜리 라벨인 척했고, 공개 조회 경로에서는 묶음 이름이 그 자리를 차지하고 작성자의 문장은 아예 버려졌다. 「다음에 무엇을 읽을지」의 답이 그 문장인데 공개 화면에 한 번도 나오지 않았다. 이제 셋이 각자의 칸을 갖는다. `label` 은 대상의 종류, `note` 는 작성자가 쓴 문장, `summary` 는 대상의 요약이다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을 보인다 — 요약은 대상을 설명하고 문장은 왜 지금 이것을 읽어야 하는지를 설명한다. 공개 주소로 종류를 되짚던 삼항 사슬도 표로 바꾼다. `/concepts/` 가 어디에도 없어서 개념으로 가는 관계가 전부 `PROJECT` 로 떨어지고 있었다 — 손으로 나열한 목록에 새 종류를 빠뜨리는 일이 이 저장소에서만 다섯 번째다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- public/release-manifest.json | 14 +- .../adapters/http/public-content-mapping.ts | 33 ++- .../adapters/static/public-content.ts | 37 ++- .../ports/public-content-queries.ts | 4 + .../management/canonical-source.json | 8 +- .../contracts/management/generated.ts | 225 ++++++++++++++++++ .../management/management-api.openapi.yaml | 199 ++++++++++++++++ .../contracts/public/canonical-source.json | 4 +- .../tech-log/contracts/public/generated.ts | 19 ++ .../contracts/public/public-api.openapi.yaml | 42 ++++ .../contracts/studio/canonical-source.json | 4 +- .../tech-log/contracts/studio/generated.ts | 1 + .../contracts/studio/studio-api.openapi.yaml | 4 + .../contracts/tech-log-route-contract.ts | 7 +- .../components/public-document-header.tsx | 42 +++- .../public-document-relations.tsx | 60 +++-- .../public-render/public-record-renderer.tsx | 10 +- tests/component/prose-text.test.tsx | 46 ++-- .../tech-log/navigation-derivation.test.ts | 1 - .../features/tech-log/public-render.test.tsx | 12 +- tests/features/tech-log/public-shell.test.tsx | 1 - .../features/tech-log/route-contract.test.ts | 1 - 22 files changed, 698 insertions(+), 76 deletions(-) diff --git a/public/release-manifest.json b/public/release-manifest.json index 7fbb2d9..d24b401 100644 --- a/public/release-manifest.json +++ b/public/release-manifest.json @@ -38,28 +38,28 @@ }, "contractSet": { "setAlgorithm": "CA_CONTRACT_SET_V1", - "setDigest": "sha256:c7c1680c3ff437bb8e41ee534e14e8a42b41689bc341f613d425814a6cc6a7c2", + "setDigest": "sha256:1adabaefedaaa702bb7a62828bc42bb4fa1440811e2053adc51b6bbf3844603e", "packages": [ { "packageId": "@tech-log/management-contract", "version": "1.0.0", - "digest": "sha256:a422ff091cdba5f17a27edfa12fec06e077bcc52c9615136ddecfa8df58a5f6e", + "digest": "sha256:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998", "runtimeProtocolVersion": 1, - "sourceRevision": "fa67a64" + "sourceRevision": "ca1bbfe" }, { "packageId": "@tech-log/public-contract", "version": "2.1.0", - "digest": "sha256:afe415880eb5d6289ae10abf493333c97270c323c16a7245a466d4db4466e630", + "digest": "sha256:92c15205d373bd7048d9596e75b211c30198bb4fb3339e1d7f92a2acabe75440", "runtimeProtocolVersion": 1, - "sourceRevision": "fa67a64" + "sourceRevision": "ca1bbfe" }, { "packageId": "@tech-log/studio-contract", "version": "3.1.0", - "digest": "sha256:7de83618e7bf5e0816f12136be91abc0e779c3ee06f86276a2b2498a5d51a4e0", + "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", "runtimeProtocolVersion": 1, - "sourceRevision": "fa67a64" + "sourceRevision": "ca1bbfe" } ] } diff --git a/src/features/tech-log/adapters/http/public-content-mapping.ts b/src/features/tech-log/adapters/http/public-content-mapping.ts index 61061a6..5a6b345 100644 --- a/src/features/tech-log/adapters/http/public-content-mapping.ts +++ b/src/features/tech-log/adapters/http/public-content-mapping.ts @@ -127,18 +127,35 @@ function slugOf(title: string, index: number): string { return normalized.length > 0 ? normalized : `section-${index + 1}`; } -type Related = Readonly<{ type?: string; title?: string; summary?: string; path?: string }>; +type Related = Readonly<{ + type?: string; + title?: string; + summary?: string; + path?: string; + /** 작성자가 남긴, 왜 이 기록이 걸려 있는지. 그룹 이름(`reason`)과는 다른 칸이다. */ + reason?: string; + priority?: number; +}>; /** * The contract groups relations by why they relate (origin question, derived * references, related cases); the renderer takes one list where the reason is a * label. Flattening keeps the group name as that label. */ +type PublicRelationEntry = { + reason: string; + title: string; + path: string; + summary: string; + note: string; + priority: number; +}; + export function flattenRelations( groups: Readonly>, labels: Readonly>, -): ReadonlyArray<{ reason: string; title: string; path: string; summary: string }> { - const flat: { reason: string; title: string; path: string; summary: string }[] = []; +): ReadonlyArray { + const flat: PublicRelationEntry[] = []; for (const [group, value] of Object.entries(groups)) { if (!value) continue; const reason = labels[group] ?? group; @@ -152,7 +169,13 @@ export function flattenRelations( reason, title: entry.title, path: entry.path, - summary: cardSummary((entry as { summary?: string }).summary), + summary: cardSummary(entry.summary), + /* + 작성자가 관계마다 남긴 문장. 「다음에 무엇을 읽을지」의 답이 이것이고, 그룹 이름은 + 그저 분류다. 오래 Studio 에만 있었다. + */ + note: (entry.reason ?? "").trim(), + priority: entry.priority ?? 0, }); } } @@ -171,7 +194,7 @@ export function baseOf( primaryTopic?: Summary; primaryProject?: Summary; publishedAt?: string | null; - relations?: ReadonlyArray<{ reason: string; title: string; path: string; summary: string }>; + relations?: ReadonlyArray; }>, ) { return { diff --git a/src/features/tech-log/adapters/static/public-content.ts b/src/features/tech-log/adapters/static/public-content.ts index 488c2b4..f19aaec 100644 --- a/src/features/tech-log/adapters/static/public-content.ts +++ b/src/features/tech-log/adapters/static/public-content.ts @@ -11,8 +11,20 @@ export type PublicRelation = { summary: string; title: string; path: string; + /** + * 작성자가 관계마다 남긴 이유. 아래 정적 자료에는 아무도 쓴 적이 없으므로 여기서는 빈 값이고, + * 내보낼 때 {@link publicRecords} 가 한 번에 채운다. 목록마다 `note: ""` 를 손으로 적게 하면 + * 언젠가 하나를 빠뜨린다 — 이 저장소에서 이미 다섯 번 그랬다. + */ + note: string; + /** 낮을수록 먼저. */ + priority: number; }; +/** 정적 자료가 실제로 적는 모양. 작성자가 남긴 이유가 없으므로 두 칸이 선택이다. */ +type StaticRelation = Omit & + Partial>; + export type RecordSection = { id: string; title: string; @@ -185,7 +197,27 @@ export type HomeFocusItem = { targetPath: string; }; -export const publicRecords: ReadonlyArray = [ +/** 아래 목록이 적는 모양. 관계의 두 칸만 느슨하다. 유니온마다 나눠 적용한다. */ +type Draft = T extends unknown + ? Omit & { relations: ReadonlyArray } + : never; + +/** + * 관계의 빈 칸을 채운다. 정적 자료가 적는 모양과 포트가 요구하는 모양이 갈리는 지점이 여기 + * 하나뿐이도록 한다. + */ +function withRelationDefaults(record: Draft): PublicRecord { + return { + ...record, + relations: record.relations.map((relation) => ({ + ...relation, + note: relation.note ?? "", + priority: relation.priority ?? 0, + })), + } as PublicRecord; +} + +const staticPublicRecords: ReadonlyArray> = [ { kind: "CONCEPT", slug: "kubernetes-scheduling", @@ -607,6 +639,9 @@ export const publicRecords: ReadonlyArray = [ }, ]; +export const publicRecords: ReadonlyArray = + staticPublicRecords.map(withRelationDefaults); + export const projects: ReadonlyArray = [ { slug: "backend-skeleton", 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 5992bba..e5a70e1 100644 --- a/src/features/tech-log/application/ports/public-content-queries.ts +++ b/src/features/tech-log/application/ports/public-content-queries.ts @@ -11,6 +11,10 @@ export type PublicRelation = { reason: string; /** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */ summary: string; + /** 작성자가 남긴 이유. 「다음에 무엇을 읽을지」의 답이다. */ + note: string; + /** 낮을수록 먼저. 상세 화면이 앞의 한둘만 펴 두는 데 쓴다. */ + priority: number; title: 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 7f3a010..8e9908d 100644 --- a/src/features/tech-log/contracts/management/canonical-source.json +++ b/src/features/tech-log/contracts/management/canonical-source.json @@ -1,8 +1,8 @@ { "packageId": "@tech-log/management-contract", "version": "1.0.0", - "digest": "sha256:a422ff091cdba5f17a27edfa12fec06e077bcc52c9615136ddecfa8df58a5f6e", - "sourceRevision": "fa67a64", + "digest": "sha256:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998", + "sourceRevision": "ca1bbfe", "operationIds": [ "createCaseDraft", "getCaseForEdit", @@ -70,6 +70,10 @@ "createTopic", "updateTopic", "deleteTopic", + "listTopicVariants", + "createTopicVariant", + "updateTopicVariant", + "deleteTopicVariant", "listStudioTags", "createTag", "updateTag", diff --git a/src/features/tech-log/contracts/management/generated.ts b/src/features/tech-log/contracts/management/generated.ts index 4218f96..b729bc5 100644 --- a/src/features/tech-log/contracts/management/generated.ts +++ b/src/features/tech-log/contracts/management/generated.ts @@ -765,6 +765,40 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v1/studio/topics/{id}/variants": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description 주제 안의 접근/구조. 표시 순서대로 온다. */ + get: operations["listTopicVariants"]; + put?: never; + post: operations["createTopicVariant"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/v1/studio/topics/{id}/variants/{variantId}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put: operations["updateTopicVariant"]; + post?: never; + /** @description 접근/구조를 지운다. 걸려 있던 기록은 지우지 않는다 — 연결만 끊어져 그 주제의 공통 기록이 된다. */ + delete: operations["deleteTopicVariant"]; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v1/studio/tags": { parameters: { query?: never; @@ -1337,6 +1371,9 @@ export interface components { createdProjectDecisionId?: string; }; ProjectUpdateRequest: { + /** @description 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 — + * 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. */ + thesis?: string; /** Format: int64 */ expectedVersion: number; name: string; @@ -1357,6 +1394,9 @@ export interface components { questionLinks?: components["schemas"]["ProjectResourceLinkEdit"][]; }; ProjectEditResponse: { + /** @description 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 — + * 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. */ + thesis?: string; /** Format: uuid */ id: string; /** Format: int64 */ @@ -1464,6 +1504,13 @@ export interface components { slug: string; description?: string; scope?: string; + /** @description 이 주제가 답하는 질문을 한 문단으로 적는다. 기록을 합쳐 자동으로 나오는 글이 + * 아니라 사람이 쓰는 글이므로 자리를 따로 둔다. */ + thesis?: string; + /** @description 독자에게 보이는 축의 이름. 인증 경계에서는 「구조」, 조회 성능에서는 「조회 전략」이 + * 된다 — 내부 모델 이름(variant)을 화면에 그대로 쓰지 않는다. 비어 있으면 이 주제는 + * 축을 쓰지 않는다. */ + variantLabel?: string; /** @enum {string} */ status?: "ACTIVE" | "ARCHIVED"; /** Format: int64 */ @@ -1472,6 +1519,24 @@ export interface components { featuredReferenceId?: string; featuredCaseIds?: string[]; }; + /** @description 주제 안의 접근/구조 하나. slug 는 그 주제 안에서만 유일하다 — 주소가 + * `/topics/{topicSlug}/{variantSlug}` 이고, 다른 주제에서 같은 이름을 쓸 수 있어야 한다. */ + TopicVariantEdit: { + /** Format: uuid */ + id?: string; + /** Format: int64 */ + version?: number; + slug: string; + title: string; + /** @description 이것이 무엇인가. */ + summary?: string; + /** @description 만들어 보고 무엇을 알게 됐는가. 홈 비교표가 읽는 것이 이 칸이다 — 기록의 요약 + * 첫 줄을 잘라 쓰면 안 되는 자리라 따로 둔다. */ + conclusion?: string; + displayOrder?: number; + /** Format: int64 */ + expectedVersion?: number; + }; TagEdit: { name: string; slug: string; @@ -7378,6 +7443,166 @@ export interface operations { }; }; }; + listTopicVariants: { + parameters: { + query?: never; + header?: never; + path: { + id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["TopicVariantEdit"][]; + }; + }; + }; + }; + createTopicVariant: { + parameters: { + query?: never; + header: { + "X-CSRF-TOKEN": components["parameters"]["CsrfToken"]; + }; + path: { + id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["TopicVariantEdit"]; + }; + }; + responses: { + /** @description Created */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["TopicVariantEdit"]; + }; + }; + /** @description Bad Request */ + 400: { + 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"]; + }; + }; + }; + }; + updateTopicVariant: { + parameters: { + query?: never; + header: { + "X-CSRF-TOKEN": components["parameters"]["CsrfToken"]; + }; + path: { + id: string; + variantId: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["TopicVariantEdit"]; + }; + }; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["TopicVariantEdit"]; + }; + }; + /** @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"]; + }; + }; + }; + }; + deleteTopicVariant: { + parameters: { + query?: never; + header: { + "X-CSRF-TOKEN": components["parameters"]["CsrfToken"]; + }; + path: { + id: string; + variantId: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["ExpectedVersionRequest"]; + }; + }; + responses: { + /** @description No Content */ + 204: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @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"]; + }; + }; + }; + }; listStudioTags: { parameters: { query?: never; diff --git a/src/features/tech-log/contracts/management/management-api.openapi.yaml b/src/features/tech-log/contracts/management/management-api.openapi.yaml index a7096b9..526053d 100644 --- a/src/features/tech-log/contracts/management/management-api.openapi.yaml +++ b/src/features/tech-log/contracts/management/management-api.openapi.yaml @@ -4430,6 +4430,142 @@ paths: $ref: '#/components/schemas/ExpectedVersionRequest' security: - sessionCookie: [] + /api/v1/studio/topics/{id}/variants: + get: + operationId: listTopicVariants + tags: [Topics] + description: 주제 안의 접근/구조. 표시 순서대로 온다. + parameters: + - name: id + in: path + required: true + schema: { type: string, format: uuid } + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TopicVariantEdit' + security: + - sessionCookie: [] + post: + operationId: createTopicVariant + tags: [Topics] + 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/TopicVariantEdit' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/TopicVariantEdit' + '400': + description: Bad Request + 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/topics/{id}/variants/{variantId}: + put: + operationId: updateTopicVariant + tags: [Topics] + parameters: + - name: id + in: path + required: true + schema: { type: string, format: uuid } + - name: variantId + in: path + required: true + schema: { type: string, format: uuid } + - $ref: '#/components/parameters/CsrfToken' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TopicVariantEdit' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TopicVariantEdit' + '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: [] + delete: + operationId: deleteTopicVariant + tags: [Topics] + description: |- + 접근/구조를 지운다. 걸려 있던 기록은 지우지 않는다 — 연결만 끊어져 그 주제의 공통 기록이 된다. + parameters: + - name: id + in: path + required: true + schema: { type: string, format: uuid } + - name: variantId + 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 + '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/tags: get: operationId: listStudioTags @@ -6539,6 +6675,12 @@ components: - technologyLabels - targetVisibility properties: + thesis: + type: string + maxLength: 2000 + description: |- + 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 — + 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. expectedVersion: type: integer format: int64 @@ -6600,6 +6742,12 @@ components: - publication - updatedAt properties: + thesis: + type: string + maxLength: 2000 + description: |- + 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 — + 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. id: type: string format: uuid @@ -6839,6 +6987,19 @@ components: maxLength: 600 scope: type: string + thesis: + type: string + maxLength: 2000 + description: |- + 이 주제가 답하는 질문을 한 문단으로 적는다. 기록을 합쳐 자동으로 나오는 글이 + 아니라 사람이 쓰는 글이므로 자리를 따로 둔다. + variantLabel: + type: string + maxLength: 40 + description: |- + 독자에게 보이는 축의 이름. 인증 경계에서는 「구조」, 조회 성능에서는 「조회 전략」이 + 된다 — 내부 모델 이름(variant)을 화면에 그대로 쓰지 않는다. 비어 있으면 이 주제는 + 축을 쓰지 않는다. status: type: string enum: @@ -6856,6 +7017,44 @@ components: items: type: string format: uuid + TopicVariantEdit: + type: object + required: + - slug + - title + description: |- + 주제 안의 접근/구조 하나. slug 는 그 주제 안에서만 유일하다 — 주소가 + `/topics/{topicSlug}/{variantSlug}` 이고, 다른 주제에서 같은 이름을 쓸 수 있어야 한다. + properties: + id: + type: string + format: uuid + version: + type: integer + format: int64 + slug: + type: string + maxLength: 100 + pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" + title: + type: string + maxLength: 80 + summary: + type: string + maxLength: 600 + description: 이것이 무엇인가. + conclusion: + type: string + maxLength: 600 + description: |- + 만들어 보고 무엇을 알게 됐는가. 홈 비교표가 읽는 것이 이 칸이다 — 기록의 요약 + 첫 줄을 잘라 쓰면 안 되는 자리라 따로 둔다. + displayOrder: + type: integer + minimum: 0 + expectedVersion: + type: integer + format: int64 TagEdit: type: object required: diff --git a/src/features/tech-log/contracts/public/canonical-source.json b/src/features/tech-log/contracts/public/canonical-source.json index 4b99b75..6c48dad 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:afe415880eb5d6289ae10abf493333c97270c323c16a7245a466d4db4466e630", - "sourceRevision": "fa67a64", + "digest": "sha256:92c15205d373bd7048d9596e75b211c30198bb4fb3339e1d7f92a2acabe75440", + "sourceRevision": "ca1bbfe", "operationIds": [ "getPublicSite", "getPublicHome", diff --git a/src/features/tech-log/contracts/public/generated.ts b/src/features/tech-log/contracts/public/generated.ts index c35352a..21d7612 100644 --- a/src/features/tech-log/contracts/public/generated.ts +++ b/src/features/tech-log/contracts/public/generated.ts @@ -418,6 +418,12 @@ export interface components { type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE"; title: string; summary?: string; + /** @description 작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에 + * 자리가 없어 독자는 볼 수 없었다 — 「다음에 무엇을 읽을지」의 답이 이 문장이다. */ + reason?: string; + /** @description 낮을수록 먼저. 상세 화면은 앞의 한둘만 펴 두고 나머지는 접는다 — 균등한 넷은 + * 선택이 아니라 부담이다. */ + priority?: number; path: string; }; ContactLink: { @@ -539,13 +545,26 @@ export interface components { slug: string; description: string; scope?: string; + thesis?: string; + variantLabel?: string; }; + /** @description 주제 안의 접근/구조. 표시 순서대로 온다. 비어 있으면 이 주제는 축을 쓰지 않는다. */ + variants?: components["schemas"]["TopicVariantSummary"][]; featuredReference?: components["schemas"]["RelatedEntry"]; featuredCases: components["schemas"]["RelatedEntry"][]; activeQuestions: components["schemas"]["RelatedEntry"][]; relatedProjects: components["schemas"]["RelatedEntry"][]; latestRecords: components["schemas"]["LatestEntry"][]; }; + TopicVariantSummary: { + slug: string; + title: string; + path: string; + summary?: string; + /** @description 만들어 보고 무엇을 알게 됐는가. 비교표가 읽는 칸이다. */ + conclusion?: string; + recordCount?: number; + }; CaseDetailResponse: { canonicalPath: string; /** @default true */ 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 c5678ab..da7f606 100644 --- a/src/features/tech-log/contracts/public/public-api.openapi.yaml +++ b/src/features/tech-log/contracts/public/public-api.openapi.yaml @@ -910,6 +910,17 @@ components: type: string summary: type: string + reason: + type: string + description: |- + 작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에 + 자리가 없어 독자는 볼 수 없었다 — 「다음에 무엇을 읽을지」의 답이 이 문장이다. + priority: + type: integer + minimum: 0 + description: |- + 낮을수록 먼저. 상세 화면은 앞의 한둘만 펴 두고 나머지는 접는다 — 균등한 넷은 + 선택이 아니라 부담이다. path: type: string ContactLink: @@ -1231,6 +1242,16 @@ components: type: string scope: type: string + thesis: + type: string + variantLabel: + type: string + variants: + type: array + description: |- + 주제 안의 접근/구조. 표시 순서대로 온다. 비어 있으면 이 주제는 축을 쓰지 않는다. + items: + $ref: '#/components/schemas/TopicVariantSummary' featuredReference: $ref: '#/components/schemas/RelatedEntry' featuredCases: @@ -1249,6 +1270,27 @@ components: type: array items: $ref: '#/components/schemas/LatestEntry' + TopicVariantSummary: + type: object + required: + - slug + - title + - path + properties: + slug: + type: string + title: + type: string + path: + type: string + summary: + type: string + conclusion: + type: string + description: 만들어 보고 무엇을 알게 됐는가. 비교표가 읽는 칸이다. + recordCount: + type: integer + minimum: 0 CaseDetailResponse: 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 52fa336..b70a53a 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:7de83618e7bf5e0816f12136be91abc0e779c3ee06f86276a2b2498a5d51a4e0", - "sourceRevision": "fa67a64", + "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", + "sourceRevision": "ca1bbfe", "operationIds": [ "getStudioSession", "getStudioDashboard", diff --git a/src/features/tech-log/contracts/studio/generated.ts b/src/features/tech-log/contracts/studio/generated.ts index 4357de5..7fbbca1 100644 --- a/src/features/tech-log/contracts/studio/generated.ts +++ b/src/features/tech-log/contracts/studio/generated.ts @@ -582,6 +582,7 @@ export interface components { summary: string; /** Format: uuid */ topicId: string | null; + variantIds?: string[]; /** * Format: uuid * @description `kind=PROJECT_DECISION`은 게시 시점에 non-null이어야 한다. 저장 시점에는 강제하지 않는다. 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 f79cd41..8e2abf6 100644 --- a/src/features/tech-log/contracts/studio/studio-api.openapi.yaml +++ b/src/features/tech-log/contracts/studio/studio-api.openapi.yaml @@ -919,6 +919,10 @@ components: - { type: string, minLength: 3, maxLength: 100, pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" } summary: { type: string, maxLength: 2000 } topicId: { type: [string, "null"], format: uuid } + # 이 기록이 걸리는 주제 안의 접근/구조. 여럿일 수 있다 — PKCE 는 SPA 와 BFF 양쪽에 + # 관계되고, credential 변환 경계는 Mediator 와 BFF 를 견준다. 비어 있으면 그 주제의 + # 공통 기록으로 읽는다. required 에 넣지 않는다: 이미 저장된 작업본을 깨지 않는다. + variantIds: { type: array, maxItems: 8, items: { type: string, format: uuid } } projectId: type: [string, "null"] format: uuid diff --git a/src/features/tech-log/contracts/tech-log-route-contract.ts b/src/features/tech-log/contracts/tech-log-route-contract.ts index a48940b..2512be6 100644 --- a/src/features/tech-log/contracts/tech-log-route-contract.ts +++ b/src/features/tech-log/contracts/tech-log-route-contract.ts @@ -35,7 +35,12 @@ const TECH_LOG_ROUTE_SPECS = [ defineSpec({ routeId: "TECH_LOG_PROJECT_RECORDS", path: "/projects/:slug/records", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 기록", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_PROJECT_DECISIONS", path: "/projects/:slug/decisions", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 결정", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_PROJECT_ACTIVITY", path: "/projects/:slug/activity", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 활동", navigationLabel: null, navigationOrder: null }), - defineSpec({ routeId: "TECH_LOG_RELEASES", path: "/releases", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "변경 기록", navigationLabel: "변경 기록", navigationOrder: 30 }), + /* + 변경 기록은 주 내비에서 내린다. 독자의 작업은 읽고·탐색하고·주제와 프로젝트를 따라가고 + 검색하는 것이고, 「사이트가 언제 무엇을 공개했는가」는 그 축이 아니다. 주소는 그대로 두고 + 푸터가 데려간다. + */ + defineSpec({ routeId: "TECH_LOG_RELEASES", path: "/releases", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "변경 기록", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_RELEASE", path: "/releases/:version", layoutGroup: "PUBLIC", paramsSchema: "TechLogVersionParams", searchSchema: null, title: "변경 기록", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_PROFILE", path: "/profile", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "프로필", navigationLabel: "프로필", navigationOrder: 40 }), defineSpec({ routeId: "TECH_LOG_SEARCH", path: "/search", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: "TechLogSearchQuery", title: "검색", navigationLabel: null, navigationOrder: null }), 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 255a135..f7d00ef 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 @@ -5,6 +5,29 @@ import type { components } from "../../../contracts/studio/generated.ts"; import { ProseText } from "../../shared/public-render/prose-text.tsx"; import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; +type TargetKind = components["schemas"]["ResolvedRelation"]["targetKind"]; + +/** + * 공개 주소의 앞머리로 대상 종류를 되짚는다. + * + *

목록으로 적는다. 이 자리가 삼항 사슬이던 동안 `/concepts/` 가 어디에도 없어서 개념 문서로 + * 가는 관계가 전부 `PROJECT` 로 떨어졌고, 종류 이름이 화면에 「프로젝트」로 나왔다. 종류를 + * 더할 때 짝을 빠뜨리는 일이 이 저장소에서만 다섯 번 있었다. + */ +const PATH_PREFIX_KINDS: ReadonlyArray = [ + ["/cases/", "CASE"], + ["/references/", "REFERENCE"], + ["/questions/", "QUESTION"], + ["/concepts/", "CONCEPT"], +]; + +function targetKindOf(path: string): TargetKind { + const matched = PATH_PREFIX_KINDS.find(([prefix]) => path.startsWith(prefix)); + if (matched) return matched[1]; + // 결정은 프로젝트 화면 안의 앵커로 산다. 그래서 앞머리가 아니라 조각으로 가른다. + return path.includes("/decisions#") ? "PROJECT_DECISION" : "PROJECT"; +} + export function publicRenderModelBase( record: PublicRecord, ): components["schemas"]["PublicRenderModelBase"] { @@ -29,21 +52,18 @@ export function publicRenderModelBase( relations: record.relations.map((relation, index) => ({ id: `public-relation-${index + 1}-${relation.path}`, targetId: relation.path, - targetKind: relation.path.startsWith("/cases/") - ? "CASE" - : relation.path.startsWith("/references/") - ? "REFERENCE" - : relation.path.startsWith("/questions/") - ? "QUESTION" - : relation.path.includes("/decisions#") - ? "PROJECT_DECISION" - : "PROJECT", + targetKind: targetKindOf(relation.path), title: relation.title, + /* + 렌더 모델의 `reason` 은 작성자가 이 관계에 남긴 문장이다. 공개 조회는 그 문장을 `note` + 로 주고, `reason` 자리에는 묶음 이름이 온다 — 두 경로에서 같은 이름이 서로 다른 것을 + 뜻해서, 작성자가 쓴 문장이 화면에 한 번도 나오지 않은 채로 오래 있었다. + */ publicPath: relation.path, - reason: relation.reason, + reason: relation.note, /* 계약이 관계마다 주는 요약. 여기서 버리면 목록에 제목만 남는다. */ summary: relation.summary, - order: index + 1, + order: relation.priority || index + 1, })), renderContext: { generatedAt: record.publishedAt, diff --git a/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx b/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx index 7488381..613b6a2 100644 --- a/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx +++ b/src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx @@ -1,11 +1,24 @@ import { Link } from "react-router-dom"; +/** + * 관계 한 줄. + * + *

세 칸이 서로 다른 것을 뜻한다. 오래 이 셋이 `reason` 한 칸에 뭉쳐 있었고, 그래서 화면마다 + * 다른 것이 같은 자리에 나왔다 — 렌더 모델 경로에서는 작성자가 쓴 문장이 묶음 이름 자리에 작은 + * 회색 글씨로 눌려 나왔고, 공개 조회 경로에서는 작성자가 쓴 문장이 아예 버려졌다. + */ export type PublicRelation = Readonly<{ - /** 왜 걸려 있는지 — 관계 묶음의 사람이 읽는 이름. */ - reason: string; + /** 묶음 이름. 「근거」「관련 기준」처럼 분류다. 문장이 아니다. */ + label?: string; title: string; path: string; - /** 대상 문서의 요약. 눌러 보지 않고도 무엇인지 알게 한다. */ + /** + * 작성자가 이 관계에 남긴 문장. 「다음에 무엇을 읽을지」의 답이 이것이다. 있으면 요약보다 + * 이쪽을 보인다 — 대상의 요약은 대상을 설명하고, 이 문장은 왜 지금 이것을 읽어야 하는지를 + * 설명한다. + */ + note?: string; + /** 대상 문서의 요약. 작성자가 아무것도 남기지 않았을 때의 차선이다. */ summary?: string; }>; @@ -25,27 +38,26 @@ export function PublicDocumentRelations({

{kicker}

{title}

    - {relations.map((relation) => ( -
  • - - {relation.reason} -
    - {relation.title} - {/* - 계약은 관계마다 요약을 함께 준다. 예전에는 그것을 버려서 목록에 제목만 남았고, - 독자는 왜 이 기록이 걸려 있는지 눌러 봐야 알 수 있었다. - */} - {/* - 링크의 이름은 「관계 이름 + 제목」으로 둔다. 요약까지 이름에 들어가면 관계 - 목록을 훑을 때 링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다. - 요약은 눈으로 보는 보조 정보이고, 전문은 눌러 들어가면 있다. - */} - {relation.summary ? : null} -
    - - -
  • - ))} + {relations.map((relation) => { + /* + 링크의 이름은 「묶음 이름 + 제목」까지다. 설명까지 이름에 들어가면 관계 목록을 훑을 때 + 링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다. 설명은 눈으로 보는 보조 + 정보이고, 전문은 눌러 들어가면 있다. + */ + const description = relation.note?.trim() || relation.summary?.trim() || ""; + return ( +
  • + + {relation.label ? {relation.label} : null} +
    + {relation.title} + {description ? : null} +
    + + +
  • + ); + })}
); 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 72eb592..50803b3 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 @@ -108,6 +108,11 @@ function ModelDocumentHeader({ ); } +/** 관계 대상의 종류 이름. 프로젝트만 표에 없다 — 기록이 아니라 묶음이기 때문이다. */ +function kindLabel(kind: ResolvedRelation["targetKind"]): string { + return kind === "PROJECT" ? "프로젝트" : DOCUMENT_KIND_LABELS[kind]; +} + function publicRelations( relations: ReadonlyArray, ): PublicRelation[] { @@ -118,9 +123,12 @@ function publicRelations( ) .sort((left, right) => left.order - right.order) .map((relation) => ({ - reason: relation.reason, + // 묶음 이름은 대상이 어떤 종류의 기록인가로 붙인다. 「동작 원리」인지 「열린 질문」인지가 + // 독자가 목록에서 먼저 가려내는 것이고, 그 이름은 이미 한 곳에 있다. + label: kindLabel(relation.targetKind), title: relation.title, path: relation.publicPath, + note: relation.reason, summary: relation.summary, })); } diff --git a/tests/component/prose-text.test.tsx b/tests/component/prose-text.test.tsx index 9d65a50..02cd69d 100644 --- a/tests/component/prose-text.test.tsx +++ b/tests/component/prose-text.test.tsx @@ -83,34 +83,52 @@ describe("릴리스 노트 목록 읽기", () => { * 눌러 봐야 알 수 있었다. */ describe("관계 목록", () => { - it("대상 요약을 제목 아래 보여 주되 링크 이름에는 넣지 않는다", async () => { + async function renderRelations(relation: Record) { const { PublicDocumentRelations } = await import( "../../src/features/tech-log/presentation/shared/public-render/public-document-relations.tsx" ); const { MemoryRouter: Router } = await import("react-router-dom"); - const { container, getByRole } = render( + return render( - + , ); + } + + it("대상 요약을 제목 아래 보여 주되 링크 이름에는 넣지 않는다", async () => { + const { container, getByRole } = await renderRelations({ + label: "적용 기준", + title: "SPA에서 토큰을 직접 관리하면서 드러난 경계", + path: "/cases/spa-browser-credential-boundary", + summary: "SPA가 public OAuth client로 code를 직접 교환한다.", + }); expect(container.querySelector(".document-relations li p")).toHaveTextContent( "SPA가 public OAuth client로 code를 직접 교환한다.", ); /* 링크 이름에 요약이 들어가면 관계 목록을 훑을 때 링크 하나하나가 문단이 되어 목록으로서 - 쓸모가 없어진다 — 이름은 「관계 이름 + 제목」까지다. + 쓸모가 없어진다 — 이름은 「묶음 이름 + 제목」까지다. */ - const link = getByRole("link", { name: /이 기준의 근거가 된 기록/ }); + const link = getByRole("link", { name: /적용 기준/ }); expect(link.getAttribute("aria-label")).toBeNull(); expect(link).not.toHaveAccessibleName(/code를 직접 교환/); }); + + /* + 작성자가 관계마다 남긴 문장이 「다음에 무엇을 읽을지」의 답이다. 대상의 요약은 대상을 + 설명할 뿐이라, 둘 다 있으면 작성자의 문장을 보인다. 이 문장은 오래 Studio 에만 있었고 + 공개 화면에는 한 번도 나오지 않았다. + */ + it("작성자가 남긴 이유가 있으면 대상 요약 대신 그것을 보인다", async () => { + const { container } = await renderRelations({ + label: "검증 기록", + title: "SPA에서 토큰을 직접 관리하면서 드러난 경계", + path: "/cases/spa-browser-credential-boundary", + note: "이 기준이 왜 필요했는지를 이 기록이 보여 준다.", + summary: "SPA가 public OAuth client로 code를 직접 교환한다.", + }); + const description = container.querySelector(".document-relations li p"); + expect(description).toHaveTextContent("이 기준이 왜 필요했는지를 이 기록이 보여 준다."); + expect(description).not.toHaveTextContent("code를 직접 교환"); + }); }); diff --git a/tests/features/tech-log/navigation-derivation.test.ts b/tests/features/tech-log/navigation-derivation.test.ts index 4423300..c39a2f3 100644 --- a/tests/features/tech-log/navigation-derivation.test.ts +++ b/tests/features/tech-log/navigation-derivation.test.ts @@ -16,7 +16,6 @@ describe("TechLog navigation derivation", () => { ).toEqual([ ["탐색", "/explore"], ["프로젝트", "/projects"], - ["변경 기록", "/releases"], ["프로필", "/profile"], ]); }); diff --git a/tests/features/tech-log/public-render.test.tsx b/tests/features/tech-log/public-render.test.tsx index bb9ad4e..04b90e0 100644 --- a/tests/features/tech-log/public-render.test.tsx +++ b/tests/features/tech-log/public-render.test.tsx @@ -113,7 +113,7 @@ function caseModel( targetKind: "REFERENCE", title: "연결된 기준", publicPath: "/references/linked", - reason: "판단 기준", + reason: "이 기록의 결론이 그대로 이 기준이 되었다.", order: 1, }, ], @@ -380,11 +380,17 @@ describe("shared Public record renderer", () => { expect(screen.getByText("목차 · 강조 강함 코드")).toBeVisible(); expect(screen.getByRole("link", { name: "강조 강함 코드 바로가기" })).toBeVisible(); /* - 관계 항목이 제목만 있던 시절에는 라벨과 제목이 붙어 한 이름이었다. 지금은 제목과 요약을 + 관계 항목이 제목만 있던 시절에는 라벨과 제목이 붙어 한 이름이었다. 지금은 제목과 설명을 묶는 상자가 하나 더 있어 그 사이에 공백이 생긴다 — 이름의 구성은 그대로다. + + 묶음 이름은 대상의 종류에서 온다. 예전에는 작성자가 쓴 문장이 이 자리에 눌려 들어가 + 한 줄짜리 라벨인 척했고, 그래서 문장은 문장대로 잘려 보이고 종류는 어디에도 없었다. */ - const relation = screen.getByRole("link", { name: /판단 기준\s*연결된 기준/ }); + const relation = screen.getByRole("link", { name: /적용 기준\s*연결된 기준/ }); expect(relation).toHaveAttribute("href", "/references/linked"); + // 작성자가 남긴 문장은 이름이 아니라 설명 자리에 온다. + expect(relation).not.toHaveAccessibleName(/그대로 이 기준이/); + expect(relation.querySelector("p")).toHaveTextContent("그대로 이 기준이 되었다"); expect(relation.parentElement?.parentElement?.previousElementSibling).toHaveTextContent( "이 기록의 연결", ); diff --git a/tests/features/tech-log/public-shell.test.tsx b/tests/features/tech-log/public-shell.test.tsx index fef1ce7..c56d126 100644 --- a/tests/features/tech-log/public-shell.test.tsx +++ b/tests/features/tech-log/public-shell.test.tsx @@ -103,7 +103,6 @@ describe("TechLog Public shell", () => { const expectedNavigation = [ ["탐색", "/explore"], ["프로젝트", "/projects"], - ["변경 기록", "/releases"], ["프로필", "/profile"], ]; expect( diff --git a/tests/features/tech-log/route-contract.test.ts b/tests/features/tech-log/route-contract.test.ts index d4b6b83..2fdd738 100644 --- a/tests/features/tech-log/route-contract.test.ts +++ b/tests/features/tech-log/route-contract.test.ts @@ -147,7 +147,6 @@ describe("TechLog route boundary contract", () => { ).toEqual([ ["TECH_LOG_EXPLORE", "PUBLIC", "탐색", 10], ["TECH_LOG_PROJECTS", "PUBLIC", "프로젝트", 20], - ["TECH_LOG_RELEASES", "PUBLIC", "변경 기록", 30], ["TECH_LOG_PROFILE", "PUBLIC", "프로필", 40], ["TECH_LOG_STUDIO_DOCUMENTS", "STUDIO", "작업본", 10], ["TECH_LOG_STUDIO_DOCUMENT_NEW", "STUDIO", "새 문서", 30],