From 15e6ea8f1557cb9e4ea6dfb967c14794e1f3695e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 1 Sep 2026 16:57:24 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=EC=A3=BC=EC=A0=9C=20=ED=99=94=EB=A9=B4?= =?UTF-8?q?=EC=9D=84=20=EA=B3=84=EC=95=BD=EC=97=90=20=EC=9E=87=EA=B3=A0,?= =?UTF-8?q?=20=EB=93=B1=EB=A1=9D=EC=9D=84=20=EC=9E=8A=EB=8A=94=20=EC=82=AC?= =?UTF-8?q?=EA=B3=A0=EB=A5=BC=20=EA=B0=80=EB=93=9C=EB=A1=9C=20=EB=A7=89?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 주제 화면은 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만 열었다. 제목과 설명까지 코드에 있었고, 목록에 없는 주제는 기록이 멀쩡히 있어도 404 로 갔다 — 픽스처의 `kubernetes` 가 그랬다. 계약에는 처음부터 `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. 이제 그 연산을 부르고, 주제가 답하는 질문(논지)과 그 질문에 대해 실제로 만들어 본 답들(축)을 화면의 뼈대로 둔다. 프로젝트의 논지도 마찬가지다. 담을 칸이 없어 목적(`purpose`)을 대신 보여 주고 있었는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다. 축 CRUD 네 연산은 계약에 있으면서 기여 목록에 없었다 — 등록되지 않은 연산은 타입에는 멀쩡히 보이는데 부를 수가 없다. `getPublicConcept` 과 `deleteConceptDraft` 가 정확히 그래서 못 불렸고, 개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" 가 떴다. 그래서 가드를 둘 넣는다. 공개 계약은 전수 대조하고(봉투 없이 바이트를 주는 `/media` 만 면제), 관리 계약은 **한 종류만 빠진 자리**를 본다 — 깨진 것이 늘 그 모양이었다. 개념 삭제 등록을 지워 보고 실제로 멈추는 것을 확인했다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- public/release-manifest.json | 10 +- .../http/http-public-content-gateway.ts | 63 +++++++++- .../adapters/http/public-content-mapping.ts | 6 +- .../adapters/static/public-content.ts | 28 ++--- .../tech-log/adapters/static/public-query.ts | 56 +++++++++ .../ports/public-content-queries.ts | 42 ++++++- .../management/canonical-source.json | 2 +- .../contracts/public/canonical-source.json | 4 +- .../tech-log/contracts/public/generated.ts | 5 + .../contracts/public/public-api.openapi.yaml | 7 ++ .../contracts/studio/canonical-source.json | 2 +- ...ch-log-management-contract-contribution.ts | 60 ++++++++++ .../presentation/public/pages/topic-page.tsx | 108 +++++++++++------- .../public-document-relations.tsx | 6 +- .../tech-log/presentation/styles/globals.css | 81 +++++++++++++ .../contract-operation-coverage.test.ts | 80 +++++++++++++ .../tech-log/public-document-screens.test.tsx | 24 +++- .../tech-log/public-question-mapping.test.ts | 8 +- 18 files changed, 512 insertions(+), 80 deletions(-) create mode 100644 tests/features/tech-log/contract-operation-coverage.test.ts diff --git a/public/release-manifest.json b/public/release-manifest.json index d24b401..d02b28b 100644 --- a/public/release-manifest.json +++ b/public/release-manifest.json @@ -38,28 +38,28 @@ }, "contractSet": { "setAlgorithm": "CA_CONTRACT_SET_V1", - "setDigest": "sha256:1adabaefedaaa702bb7a62828bc42bb4fa1440811e2053adc51b6bbf3844603e", + "setDigest": "sha256:05cc77985a814e457d1113758f2e6985196d5c66c069177de9e0ebdd1f4a40af", "packages": [ { "packageId": "@tech-log/management-contract", "version": "1.0.0", "digest": "sha256:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998", "runtimeProtocolVersion": 1, - "sourceRevision": "ca1bbfe" + "sourceRevision": "0f4d2cd" }, { "packageId": "@tech-log/public-contract", "version": "2.1.0", - "digest": "sha256:92c15205d373bd7048d9596e75b211c30198bb4fb3339e1d7f92a2acabe75440", + "digest": "sha256:08b68601bd81c569926e7374a0c95711a5982da332e6edc6c811fe08d2fd19db", "runtimeProtocolVersion": 1, - "sourceRevision": "ca1bbfe" + "sourceRevision": "0f4d2cd" }, { "packageId": "@tech-log/studio-contract", "version": "3.1.0", "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", "runtimeProtocolVersion": 1, - "sourceRevision": "ca1bbfe" + "sourceRevision": "0f4d2cd" } ] } diff --git a/src/features/tech-log/adapters/http/http-public-content-gateway.ts b/src/features/tech-log/adapters/http/http-public-content-gateway.ts index d150fcd..73c5504 100644 --- a/src/features/tech-log/adapters/http/http-public-content-gateway.ts +++ b/src/features/tech-log/adapters/http/http-public-content-gateway.ts @@ -7,6 +7,7 @@ import type { PublicContentQueries, PublicRecord, PublicTopic, + PublicTopicDetail, QuestionRecord, RecordFilters, RecordKind, @@ -26,6 +27,7 @@ import { releaseDetailToRelease, searchItemToEntity, } from "./public-content-mapping.ts"; +import { cardSummary } from "../../domain/content-format/card-summary.ts"; import type { components } from "../../contracts/public/generated.ts"; import type { StudioOperationExecutor } from "./http-studio-gateway.ts"; @@ -388,7 +390,12 @@ export function createHttpPublicContentGateway( slug, title: String(body.name ?? ""), summary: String(body.oneLinePurpose ?? ""), - thesis: String(body.purpose ?? body.oneLinePurpose ?? ""), + /* + 논지는 이 프로젝트가 무엇을 밝혔는가다. 담을 칸이 없던 동안 목적(`purpose`)을 대신 + 보여 줬는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다. + 아직 아무도 쓰지 않은 프로젝트는 예전 자리로 물러선다 — 빈 화면보다는 낫다. + */ + thesis: String(body.thesis || body.purpose || body.oneLinePurpose || ""), stage: body.phase === "VALIDATION" ? "VALIDATION" : "DESIGN", currentGoal: String(body.currentObjective ?? ""), nextStep: String(body.nextStep ?? ""), @@ -445,6 +452,59 @@ export function createHttpPublicContentGateway( ); } + /** + * 주제 한 편. + * + *

계약은 이 자리에 관계 묶음을 세 개 준다 — 대표 Case, 열린 질문, 관련 프로젝트. 화면이 + * 쓰는 모양은 관계 한 줄과 같으므로 그대로 옮긴다. 작성자가 남긴 문장(`reason`)이 있으면 + * 목록에서 그것이 먼저 보인다. + */ + async function getTopicDetail(slug: string): Promise { + const detail = await read>>("getPublicTopic", { + topicSlug: slug, + }); + if (detail === NOT_FOUND) return undefined; + const topic = (detail.topic as Readonly>) ?? {}; + const entries = (value: unknown, label: string) => + Object.freeze( + ((value as readonly Readonly>[] | undefined) ?? []) + .filter((entry) => entry.path && entry.title) + .map((entry) => + Object.freeze({ + label, + title: String(entry.title ?? ""), + path: String(entry.path ?? ""), + summary: cardSummary(entry.summary as string | undefined), + note: String(entry.reason ?? "").trim(), + priority: Number(entry.priority ?? 0), + }), + ), + ); + return Object.freeze({ + name: String(topic.name ?? ""), + slug: String(topic.slug ?? slug), + description: String(topic.description ?? ""), + thesis: String(topic.thesis ?? ""), + variantLabel: String(topic.variantLabel ?? ""), + variants: Object.freeze( + ((detail.variants as readonly Readonly>[] | undefined) ?? []).map( + (variant) => + Object.freeze({ + slug: String(variant.slug ?? ""), + title: String(variant.title ?? ""), + path: String(variant.path ?? ""), + summary: String(variant.summary ?? ""), + conclusion: String(variant.conclusion ?? ""), + recordCount: Number(variant.recordCount ?? 0), + }), + ), + ), + featuredCases: entries(detail.featuredCases, "검증 기록"), + activeQuestions: entries(detail.activeQuestions, "열린 질문"), + relatedProjects: entries(detail.relatedProjects, "프로젝트"), + }); + } + /** * 공개 투영이 고른 최근 기록. `entryType` 은 계약이 네 값만 허용하므로 그대로 믿고 쓴다 — * 서버가 이미 걸러 보낸다. @@ -611,6 +671,7 @@ export function createHttpPublicContentGateway( getProject, getRelease, listTopics, + getTopicDetail, getProjectRecords, getProjectDecisions, getProjectActivity, 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 5a6b345..f523c64 100644 --- a/src/features/tech-log/adapters/http/public-content-mapping.ts +++ b/src/features/tech-log/adapters/http/public-content-mapping.ts @@ -143,7 +143,7 @@ type Related = Readonly<{ * label. Flattening keeps the group name as that label. */ type PublicRelationEntry = { - reason: string; + label: string; title: string; path: string; summary: string; @@ -158,7 +158,7 @@ export function flattenRelations( const flat: PublicRelationEntry[] = []; for (const [group, value] of Object.entries(groups)) { if (!value) continue; - const reason = labels[group] ?? group; + const label = labels[group] ?? group; for (const entry of Array.isArray(value) ? value : [value as Related]) { if (!entry?.path || !entry.title) continue; /* @@ -166,7 +166,7 @@ export function flattenRelations( 제목뿐이었다 — 왜 이 기록이 여기 걸려 있는지는 눌러 봐야 알 수 있었다. */ flat.push({ - reason, + label, title: entry.title, path: entry.path, summary: cardSummary(entry.summary), diff --git a/src/features/tech-log/adapters/static/public-content.ts b/src/features/tech-log/adapters/static/public-content.ts index f19aaec..605c00d 100644 --- a/src/features/tech-log/adapters/static/public-content.ts +++ b/src/features/tech-log/adapters/static/public-content.ts @@ -7,7 +7,7 @@ export type QuestionStatus = | "ARCHIVED"; export type PublicRelation = { - reason: string; + label: string; summary: string; title: string; path: string; @@ -330,19 +330,19 @@ const staticPublicRecords: ReadonlyArray> = [ ], relations: [ { - reason: "이 질문에서 시작됨", + label: "이 질문에서 시작됨", summary: "", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", path: "/questions/collection-fetch-join-with-pagination", }, { - reason: "이 Case로 결정함", + label: "이 Case로 결정함", summary: "", title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.", path: "/projects/backend-skeleton/decisions#feed-pagination-boundary", }, { - reason: "이 기준 문서로 정리됨", + label: "이 기준 문서로 정리됨", summary: "", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", path: "/references/jpa-list-fetch-strategy", @@ -390,13 +390,13 @@ const staticPublicRecords: ReadonlyArray> = [ ], relations: [ { - reason: "이 프로젝트에 속함", + label: "이 프로젝트에 속함", summary: "", title: "Backend Skeleton", path: "/projects/backend-skeleton", }, { - reason: "이 결정과 연결됨", + label: "이 결정과 연결됨", summary: "", title: "StoragePort와 Adapter의 책임을 분리합니다.", path: "/projects/backend-skeleton/decisions#storage-port-unification", @@ -449,13 +449,13 @@ const staticPublicRecords: ReadonlyArray> = [ verifiedAt: "2026.08.09", relations: [ { - reason: "이 질문의 검증 기준", + label: "이 질문의 검증 기준", summary: "", title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?", path: "/questions/validate-edge-token-again", }, { - reason: "이 프로젝트에 속함", + label: "이 프로젝트에 속함", summary: "", title: "Auth Lab", path: "/projects/auth-lab", @@ -508,13 +508,13 @@ const staticPublicRecords: ReadonlyArray> = [ verifiedAt: "2026.08.11", relations: [ { - reason: "이 Case에서 측정함", + label: "이 Case에서 측정함", summary: "", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", path: "/cases/collection-fetch-join-pagination", }, { - reason: "이 질문을 해결함", + label: "이 질문을 해결함", summary: "", title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?", path: "/questions/collection-fetch-join-with-pagination", @@ -565,13 +565,13 @@ const staticPublicRecords: ReadonlyArray> = [ "토큰 전달안과 신뢰 헤더안을 위협 모델로 비교하고 Edge 우회 요청을 포함한 통합 테스트를 실행합니다.", relations: [ { - reason: "검증 기준", + label: "검증 기준", summary: "", title: "Authorization Code Flow에서 state와 nonce의 경계", path: "/references/state-and-nonce-boundary", }, { - reason: "이 프로젝트에서 추적함", + label: "이 프로젝트에서 추적함", summary: "", title: "Auth Lab 활동", path: "/projects/auth-lab/activity#edge-trust-boundary", @@ -624,13 +624,13 @@ const staticPublicRecords: ReadonlyArray> = [ }, relations: [ { - reason: "이 Case로 해결됨", + label: "이 Case로 해결됨", summary: "", title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가", path: "/cases/collection-fetch-join-pagination", }, { - reason: "적용 기준", + label: "적용 기준", summary: "", title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준", path: "/references/jpa-list-fetch-strategy", diff --git a/src/features/tech-log/adapters/static/public-query.ts b/src/features/tech-log/adapters/static/public-query.ts index 648ace9..26ce04e 100644 --- a/src/features/tech-log/adapters/static/public-query.ts +++ b/src/features/tech-log/adapters/static/public-query.ts @@ -14,6 +14,7 @@ import type { LatestRecordEntry, PublicContentQueries, PublicTopic, + PublicTopicDetail, } from "../../application/ports/public-content-queries.ts"; export type RecordFilters = { @@ -132,6 +133,58 @@ export function listTopics(): PublicTopic[] { .map((entry) => Object.freeze(entry)); } +/** + * 픽스처판 주제 한 편. + * + *

정적 카탈로그에는 축(variant)도 논지(thesis)도 없다 — 사람이 쓰는 글이라 픽스처가 지어낼 + * 수 없다. 그래서 축은 비고, 기록만 종류별로 모은다. 화면은 축이 비면 축을 그리지 않는다. + */ +export function getTopicDetail(slug: string): PublicTopicDetail | undefined { + const records = listRecords().filter((record) => record.topicSlug === slug); + if (records.length === 0) return undefined; + const pick = (kind: RecordKind, label: string) => + Object.freeze( + records + .filter((record) => record.kind === kind) + .map((record) => + Object.freeze({ + label, + title: record.title, + path: record.path, + summary: record.summary, + note: "", + priority: 0, + }), + ), + ); + const projects = new Map( + records + .filter((record) => record.projectSlug) + .map((record) => [ + record.projectSlug, + Object.freeze({ + label: "프로젝트", + title: record.projectTitle, + path: `/projects/${record.projectSlug}`, + summary: "", + note: "", + priority: 0, + }), + ]), + ); + return Object.freeze({ + name: records[0]!.topic, + slug, + description: "", + thesis: "", + variantLabel: "", + variants: Object.freeze([]), + featuredCases: pick("CASE", "검증 기록"), + activeQuestions: pick("QUESTION", "열린 질문"), + relatedProjects: Object.freeze([...projects.values()]), + }); +} + /** * 픽스처판 "최근 기록". HTTP 어댑터가 서버에서 읽어 오는 것과 같은 의미를 픽스처에서 만든다 — * 프로젝트 활동과 릴리스가 원천이다. @@ -309,6 +362,9 @@ export const publicContentQueries = Object.freeze({ async listTopics() { return listTopics(); }, + async getTopicDetail(slug: string) { + return getTopicDetail(slug); + }, async getLatestEntries() { return getLatestEntries(); }, 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 e5a70e1..3bc7761 100644 --- a/src/features/tech-log/application/ports/public-content-queries.ts +++ b/src/features/tech-log/application/ports/public-content-queries.ts @@ -8,7 +8,8 @@ export type QuestionStatus = | "ARCHIVED"; export type PublicRelation = { - reason: string; + /** 묶음 이름. 「근거」「적용 기준」처럼 분류다. 문장이 아니다. */ + label: string; /** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */ summary: string; /** 작성자가 남긴 이유. 「다음에 무엇을 읽을지」의 답이다. */ @@ -193,6 +194,43 @@ export type PublicTopic = { recordCount: number; }; +/** + * 주제 안의 접근/구조 하나. + * + *

이 주제가 답하는 질문에 대해 실제로 만들어 본 답이 하나씩이다. 인증 경계라면 SPA·BFF· + * Mediator 가 각각 하나고, 각자 무엇을 알게 됐는지({@link conclusion})가 다르다. 그 결론이 + * 이 기록의 값어치이므로 비교표가 읽는 칸도 요약이 아니라 결론이다. + */ +export type PublicTopicVariant = { + slug: string; + title: string; + path: string; + summary: string; + /** 만들어 보고 무엇을 알게 됐는가. 비어 있으면 아직 아무도 쓰지 않은 것이다. */ + conclusion: string; + recordCount: number; +}; + +/** + * 주제 한 편. 목록의 {@link PublicTopic} 과 달리 주제 화면이 통째로 쓰는 모양이다. + * + *

주제 화면은 오래 주제 셋을 코드에 적어 두고 그 셋만 열었다. 새 주제를 만들면 화면이 + * 404 로 갔고, 계약에 이미 있던 `/topics/{slug}` 는 아무도 부르지 않았다. + */ +export type PublicTopicDetail = { + name: string; + slug: string; + description: string; + /** 이 주제가 답하는 질문. 사람이 쓴 한 문단이고, 기록을 합쳐 만들지 않는다. */ + thesis: string; + /** 축의 이름. 「구조」「조회 전략」처럼 독자에게 보일 말이다. 비면 축을 쓰지 않는 주제다. */ + variantLabel: string; + variants: ReadonlyArray; + featuredCases: ReadonlyArray; + activeQuestions: ReadonlyArray; + relatedProjects: ReadonlyArray; +}; + /** * 홈의 "최근 기록" 한 줄. 서버가 공개 투영에서 직접 고른다. * @@ -274,6 +312,8 @@ export type PublicContentQueries = Readonly<{ * 있었고, Studio 에서 주제를 만들어도 바뀌지 않았다. */ listTopics(): Promise; + /** 주제 한 편. 주제가 없으면 `undefined`. */ + getTopicDetail(slug: string): Promise; getLatestEntries(): Promise; getHomeFocusItems(): Promise; searchPublicContent(query: string): Promise; diff --git a/src/features/tech-log/contracts/management/canonical-source.json b/src/features/tech-log/contracts/management/canonical-source.json index 8e9908d..b52ebe3 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:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998", - "sourceRevision": "ca1bbfe", + "sourceRevision": "0f4d2cd", "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 6c48dad..f59f49d 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:92c15205d373bd7048d9596e75b211c30198bb4fb3339e1d7f92a2acabe75440", - "sourceRevision": "ca1bbfe", + "digest": "sha256:08b68601bd81c569926e7374a0c95711a5982da332e6edc6c811fe08d2fd19db", + "sourceRevision": "0f4d2cd", "operationIds": [ "getPublicSite", "getPublicHome", diff --git a/src/features/tech-log/contracts/public/generated.ts b/src/features/tech-log/contracts/public/generated.ts index 21d7612..3cfb4bf 100644 --- a/src/features/tech-log/contracts/public/generated.ts +++ b/src/features/tech-log/contracts/public/generated.ts @@ -745,6 +745,11 @@ export interface components { name: string; slug: string; oneLinePurpose: string; + /** @description 이 프로젝트가 무엇을 밝혔는가. 사람이 쓰는 한 문단이고, 기록을 합쳐 자동으로 + * 나오지 않는다. 프로젝트 화면의 첫 문단이 이것이다 — 담을 칸이 없어 오래 + * `purpose` 를 대신 보여 주고 있었고, 그쪽은 목적이지 결론이 아니다. + * */ + thesis?: string; purpose: string; boundary: string; phase: string; 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 da7f606..61640b2 100644 --- a/src/features/tech-log/contracts/public/public-api.openapi.yaml +++ b/src/features/tech-log/contracts/public/public-api.openapi.yaml @@ -1758,6 +1758,13 @@ components: type: string oneLinePurpose: type: string + thesis: + type: string + maxLength: 2000 + description: | + 이 프로젝트가 무엇을 밝혔는가. 사람이 쓰는 한 문단이고, 기록을 합쳐 자동으로 + 나오지 않는다. 프로젝트 화면의 첫 문단이 이것이다 — 담을 칸이 없어 오래 + `purpose` 를 대신 보여 주고 있었고, 그쪽은 목적이지 결론이 아니다. purpose: type: string boundary: diff --git a/src/features/tech-log/contracts/studio/canonical-source.json b/src/features/tech-log/contracts/studio/canonical-source.json index b70a53a..3f1c55f 100644 --- a/src/features/tech-log/contracts/studio/canonical-source.json +++ b/src/features/tech-log/contracts/studio/canonical-source.json @@ -2,7 +2,7 @@ "packageId": "@tech-log/studio-contract", "version": "3.1.0", "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", - "sourceRevision": "ca1bbfe", + "sourceRevision": "0f4d2cd", "operationIds": [ "getStudioSession", "getStudioDashboard", diff --git a/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts b/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts index 14953fe..986361e 100644 --- a/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts +++ b/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts @@ -211,6 +211,66 @@ const HTTP_CONTRACTS = Object.freeze([ }); }, ), + /* + 주제 안의 축(variant). 계약에 네 연산이 있는데 여기 등록되지 않으면 화면에서 부를 수가 + 없다 — `getPublicConcept` 과 `deleteConceptDraft` 가 정확히 그래서 못 불렸다. + */ + readOperation("listTopicVariants", `${T}/{id}/variants`, 65_536, byId), + writeOperation( + "createTopicVariant", + "POST", + `${T}/{id}/variants`, + { acceptedStatuses: [201], requestByteLimit: 16_384, responseByteLimit: 16_384 }, + (input: never) => { + const value = input as unknown as Readonly<{ id: string; body: unknown }>; + return Object.freeze({ + pathValues: Object.freeze({ id: value.id }), + queryEntries: NO_QUERY, + body: value.body, + }); + }, + ), + writeOperation( + "updateTopicVariant", + "PUT", + `${T}/{id}/variants/{variantId}`, + { acceptedStatuses: [200], requestByteLimit: 16_384, responseByteLimit: 16_384 }, + (input: never) => { + const value = input as unknown as Readonly<{ + id: string; + variantId: string; + body: unknown; + }>; + return Object.freeze({ + pathValues: Object.freeze({ id: value.id, variantId: value.variantId }), + queryEntries: NO_QUERY, + body: value.body, + }); + }, + ), + writeOperation( + "deleteTopicVariant", + "DELETE", + `${T}/{id}/variants/{variantId}`, + { + acceptedStatuses: [204], + emptyBodyStatuses: [204], + requestByteLimit: 1_024, + responseByteLimit: 1_024, + }, + (input: never) => { + const value = input as unknown as Readonly<{ + id: string; + variantId: string; + expectedVersion: number; + }>; + return Object.freeze({ + pathValues: Object.freeze({ id: value.id, variantId: value.variantId }), + queryEntries: NO_QUERY, + body: { expectedVersion: value.expectedVersion }, + }); + }, + ), readOperation("listStudioProjects", P, 262_144, (input: never) => { const value = input as unknown as Readonly<{ page?: number; size?: number }> | undefined; const entries: (readonly [string, string])[] = []; diff --git a/src/features/tech-log/presentation/public/pages/topic-page.tsx b/src/features/tech-log/presentation/public/pages/topic-page.tsx index d13fa09..d5fa725 100644 --- a/src/features/tech-log/presentation/public/pages/topic-page.tsx +++ b/src/features/tech-log/presentation/public/pages/topic-page.tsx @@ -2,64 +2,88 @@ import { RegisteredNotFoundRoute, useRouteInput, } from "../../../../../presentation/routes/route-input.tsx"; +import { PublicDocumentRelations } from "../../shared/public-render/public-document-relations.tsx"; +import { ProseText } from "../../shared/public-render/prose-text.tsx"; import { PublicRecordList } from "../components/public-record-list.tsx"; import { usePublicContent } from "../use-public-content.tsx"; -const topics = { - jpa: { - title: "JPA", - description: "목록 조회, 연관 로딩과 페이지 경계를 함께 검증한 기록입니다.", - }, - authentication: { - title: "Authentication", - description: - "브라우저와 Edge, Resource Server 사이의 인증 책임과 신뢰 경계를 검증한 기록입니다.", - }, - redis: { - title: "Redis", - description: - "애플리케이션 정책과 Redis 저장 명령의 책임 경계를 검증한 기록입니다.", - }, -} as const; - -function topicConfig(value: unknown) { - if ( - value === "jpa" || - value === "authentication" || - value === "redis" - ) { - return topics[value]; - } - return undefined; -} - +/** + * 주제 한 편. + * + *

이 화면은 오래 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만 열었다. + * 제목과 설명까지 코드에 있었고, 새 주제를 만들면 화면이 그대로 404 로 갔다 — 계약에는 처음부터 + * `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. 손으로 나열한 목록에 새 것을 빠뜨리는 일이 + * 이 저장소에서 반복됐고, 여기서는 목록 자체를 없앤다. + * + *

주제가 답하는 질문(논지)과, 그 질문에 대해 실제로 만들어 본 답들(축)이 이 화면의 뼈대다. + * 축이 없는 주제도 있으므로 — 축을 쓸지는 주제마다 다르다 — 비면 그 자리를 그리지 않는다. + */ export function TopicPage() { const { params } = useRouteInput<"TECH_LOG_TOPIC">(); - const topic = topicConfig(params.slug); - // Hooks run unconditionally, so the unknown-topic case is handled by the - // loader and the not-found route is chosen after it. const slug = typeof params.slug === "string" ? params.slug : ""; - const view = usePublicContent( - ["tech-log", "topic", slug], - async (queries) => - topic ? { records: await queries.listRecords({ topic: slug }) } : { records: [] }, - ); - if (!topic) return ; + const view = usePublicContent(["tech-log", "topic", slug], async (queries) => ({ + topic: await queries.getTopicDetail(slug), + records: await queries.listRecords({ topic: slug }), + })); if (!view.ready) return view.fallback; - const { records } = view.data; + const { topic, records } = view.data; + if (!topic) return ; + + const axisLabel = topic.variantLabel.trim() || "접근"; return ( -

+

Topic

-

{topic.title}

-

{topic.description}

+

{topic.name}

+ {/* + 논지가 있으면 그것이 이 주제의 첫 문장이다. 설명은 목록에서 주제를 가려내는 한 줄이고, + 논지는 이 주제가 무엇에 답하는지를 말한다 — 둘 다 있으면 논지를 보인다. + */} +
+ + {topic.variants.length > 0 ? ( +
+

{axisLabel}

+

{`${axisLabel}별로 무엇을 알게 됐나`}

+ +
+ ) : null} + + +

관련 기록

-

{records.length}개의 관련 기록

+

{`${records.length}개의 관련 기록`}

+ +
); } 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 613b6a2..0fd8be0 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 @@ -48,7 +48,11 @@ export function PublicDocumentRelations({ return (
  • - {relation.label ? {relation.label} : null} + {/* + 묶음 이름이 없어도 자리는 남긴다 — 이 링크는 세 칸짜리 격자라 첫 칸이 사라지면 + 제목이 라벨 칸으로 밀려 들어간다. + */} + {relation.label ?? ""}
    {relation.title} {description ? : null} diff --git a/src/features/tech-log/presentation/styles/globals.css b/src/features/tech-log/presentation/styles/globals.css index 33f5569..ab89472 100644 --- a/src/features/tech-log/presentation/styles/globals.css +++ b/src/features/tech-log/presentation/styles/globals.css @@ -2821,3 +2821,84 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65 font-size: 13px; line-height: 1.6; } + +/* + 주제 화면의 축 비교. + + 이 자리는 표가 아니라 목록이다. 축이 둘이든 넷이든 같은 배치로 읽히고, 좁은 화면에서 표가 + 가로로 밀리는 일도 없다. 이 사이트의 다른 목록과 같은 규칙을 따른다 — 테두리는 줄을 가르는 + 가로선 하나, 강조는 글자 굵기와 색으로만. +*/ +.topic-variants { + margin-top: 64px; + padding-top: 30px; + border-top: 1px solid var(--line-strong); +} + +.topic-variants h2 { + margin: 10px 0 20px; + font-size: 26px; + letter-spacing: -0.03em; +} + +.topic-variants ul { + margin: 0; + padding: 0; + list-style: none; +} + +.topic-variants li { + border-top: 1px solid var(--line); +} + +.topic-variants li:last-child { + border-bottom: 1px solid var(--line); +} + +.topic-variants a { + display: grid; + grid-template-columns: 180px minmax(0, 1fr) 72px; + gap: 20px; + align-items: baseline; + padding: 26px 2px 27px; +} + +.topic-variants strong { + color: var(--ink); + font-size: 16px; + font-weight: 620; + line-height: 1.5; +} + +.topic-variants p { + margin: 0; + color: var(--muted); + font-size: 14px; + line-height: 1.65; +} + +.topic-variants a > span { + color: var(--faint); + font-size: 12px; + text-align: right; +} + +.topic-variants a:hover strong { + color: var(--signal); +} + +/* 주제 화면에서는 관계 목록이 본문 안에 있으므로 문서 하단만큼 띄우지 않는다. */ +.topic-hub .document-relations { + margin-top: 64px !important; +} + +@media (max-width: 720px) { + .topic-variants a { + grid-template-columns: minmax(0, 1fr); + gap: 8px; + } + + .topic-variants a > span { + text-align: left; + } +} diff --git a/tests/features/tech-log/contract-operation-coverage.test.ts b/tests/features/tech-log/contract-operation-coverage.test.ts new file mode 100644 index 0000000..3c9a03d --- /dev/null +++ b/tests/features/tech-log/contract-operation-coverage.test.ts @@ -0,0 +1,80 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { test } from "vitest"; + +import { TECH_LOG_MANAGEMENT_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-management-contract-contribution.ts"; +import { TECH_LOG_PUBLIC_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-public-contract-contribution.ts"; + +/** + * 계약에 있는 연산은 전부 기여 목록에 등록되어 있어야 한다. + * + *

    등록하지 않은 연산은 타입에는 멀쩡히 보이는데 부를 수가 없다. 그래서 화면은 그 연산이 + * 없는 줄 모르고 옆 연산을 부르거나(개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" + * 가 떴다), 아무것도 못 부른 채로 조용히 빈 화면이 됐다(`getPublicConcept`). 손으로 나열한 + * 목록에 새 종류를 빠뜨리는 일이 이 저장소에서만 다섯 번 넘게 났고, 매번 다섯 개의 검사를 + * 다 통과했다. + * + *

    그래서 목록을 손으로 관리하지 않고 계약 문서에서 읽어 대조한다. 새 연산을 계약에 더하고 + * 등록을 잊으면 여기서 멈춘다. + */ +function contractOperationIds(path: string): string[] { + const text = readFileSync(path, "utf8"); + return [...text.matchAll(/^\s+operationId:\s*(\S+)\s*$/gmu)].map((match) => match[1]!); +} + +/** + * 봉투를 쓰지 않고 바이트를 그대로 돌려주는 연산. `` 가 직접 가리키므로 HTTP 기여 + * 목록을 지나지 않는다 — 등록을 잊은 것이 아니라 지날 이유가 없다. + */ +const NOT_A_JSON_OPERATION = new Set(["getPublicMedia"]); + +test("공개 계약의 모든 연산이 기여 목록에 등록되어 있다", () => { + const declared = contractOperationIds( + "src/features/tech-log/contracts/public/public-api.openapi.yaml", + ); + assert.ok(declared.length > 0, "계약에서 연산을 하나도 읽지 못했다 — 정규식이 낡았다"); + + const registered = new Set( + TECH_LOG_PUBLIC_CONTRIBUTION.http.map((entry) => entry.contract.operationId), + ); + const missing = declared.filter( + (operationId) => !registered.has(operationId) && !NOT_A_JSON_OPERATION.has(operationId), + ); + + assert.deepEqual(missing, [], `등록되지 않은 연산: ${missing.join(", ")}`); +}); + +/** + * 관리 계약은 다르다. Studio 는 종류마다 갈린 옛 연산 대신 작업본 하나(`/studio/documents/…`)로 + * 문서를 다루므로, 계약에 있으나 화면이 부르지 않는 연산이 정상적으로 많다. 그래서 전수 대조는 + * 뜻이 없고, 대신 **한 종류만 빠진 자리**를 본다 — 실제로 깨진 것이 늘 그 모양이었다. + * + *

    주소에서 종류를 지우면 같은 일을 하는 연산들이 한 가족으로 모인다. 가족 하나가 세 종류만 + * 갖고 있으면 나머지 한 종류의 화면은 조용히 옆 종류의 API 를 부르거나 아무것도 못 부른다. + */ +const KIND_SEGMENTS = ["cases", "references", "questions", "concepts"] as const; + +test("문서 종류별 관리 연산에 빠진 종류가 없다", () => { + const families = new Map>(); + for (const entry of TECH_LOG_MANAGEMENT_CONTRIBUTION.http) { + const { method, pathTemplate } = entry.contract; + for (const kind of KIND_SEGMENTS) { + if (!pathTemplate.includes(`/${kind}`)) continue; + const family = `${method} ${pathTemplate.replace(`/${kind}`, "/{kind}")}`; + const kinds = families.get(family) ?? new Set(); + kinds.add(kind); + families.set(family, kinds); + } + } + assert.ok(families.size > 0, "종류별 연산을 하나도 찾지 못했다 — 주소 규칙이 바뀌었다"); + + const holes: string[] = []; + for (const [family, kinds] of families) { + // 한 종류만 있는 가족은 그 종류에만 있는 일이다(예: 질문의 해결). 구멍은 여럿 중 빠진 것이다. + if (kinds.size === 1) continue; + const missing = KIND_SEGMENTS.filter((kind) => !kinds.has(kind)); + if (missing.length > 0) holes.push(`${family} ← ${missing.join(", ")} 없음`); + } + + assert.deepEqual(holes, [], `종류가 빠진 연산 가족:\n${holes.join("\n")}`); +}); diff --git a/tests/features/tech-log/public-document-screens.test.tsx b/tests/features/tech-log/public-document-screens.test.tsx index 090cfa5..4e66d17 100644 --- a/tests/features/tech-log/public-document-screens.test.tsx +++ b/tests/features/tech-log/public-document-screens.test.tsx @@ -337,17 +337,31 @@ describe("TechLog canonical Public documents", () => { describe("TechLog topics and Public not-found routing", () => { it.each([ - ["jpa", "JPA", "목록 조회, 연관 로딩과 페이지 경계를 함께 검증한 기록입니다.", "3개의 관련 기록"], - ["authentication", "Authentication", "브라우저와 Edge, Resource Server 사이의 인증 책임과 신뢰 경계를 검증한 기록입니다.", "2개의 관련 기록"], - ["redis", "Redis", "애플리케이션 정책과 Redis 저장 명령의 책임 경계를 검증한 기록입니다.", "1개의 관련 기록"], - ])("aggregates /topics/%s with exact copy and count", async (slug, title, description, count) => { + ["jpa", "JPA", "3개의 관련 기록"], + ["authentication", "Authentication", "2개의 관련 기록"], + ["redis", "Redis", "1개의 관련 기록"], + ])("aggregates /topics/%s with its own name and count", async (slug, title, count) => { await renderDocumentRoute("TECH_LOG_TOPIC", `/topics/${slug}`); expect(screen.getByRole("heading", { level: 1, name: title })).toBeVisible(); - expect(screen.getByText(description)).toBeVisible(); expect(screen.getByText(count)).toBeVisible(); }); + /* + 이 화면은 주제 셋을 코드에 적어 두고 그 셋만 열었다. 제목과 설명까지 코드에 있었고, 목록에 + 없는 주제는 기록이 멀쩡히 있어도 404 로 갔다 — 픽스처의 `kubernetes` 가 바로 그랬다. + 계약에는 처음부터 `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. + */ + it("opens a topic that was never in the hard-coded list", async () => { + await renderDocumentRoute("TECH_LOG_TOPIC", "/topics/kubernetes"); + + expect(screen.getByRole("heading", { level: 1, name: "Kubernetes" })).toBeVisible(); + expect(screen.getByText("1개의 관련 기록")).toBeVisible(); + expect( + screen.queryByRole("heading", { name: "페이지를 찾을 수 없습니다." }), + ).not.toBeInTheDocument(); + }); + it("keeps JPA topic records in canonical published order", async () => { const { container } = await renderDocumentRoute("TECH_LOG_TOPIC", "/topics/jpa"); diff --git a/tests/features/tech-log/public-question-mapping.test.ts b/tests/features/tech-log/public-question-mapping.test.ts index 621d678..ce4515a 100644 --- a/tests/features/tech-log/public-question-mapping.test.ts +++ b/tests/features/tech-log/public-question-mapping.test.ts @@ -91,19 +91,19 @@ test("a published Open Question maps its four point groups into the screen's fie }); /* - 관계의 이유 자리에 영문 키가 그대로 나오고 있었다 — 매퍼가 찾던 그룹 이름이 계약에 없는 + 묶음 이름 자리에 영문 키가 그대로 나오고 있었다 — 매퍼가 찾던 그룹 이름이 계약에 없는 것들이었기 때문이다. 그리고 `primaryProject` 는 관계가 아니라 이 질문이 속한 프로젝트다. */ -test("a question's relations read their reason from the contract's own group names", async () => { +test("a question's relations read their label from the contract's own group names", async () => { const gateway = gatewayReturning(DETAIL); const record = await gateway.getRecord("QUESTION", "refresh-rotation-replica-contention"); assert.deepEqual( - [...record!.relations].map((relation) => ({ reason: relation.reason, path: relation.path })), + [...record!.relations].map((relation) => ({ label: relation.label, path: relation.path })), [ { - reason: "이 질문에서 나온 기록", + label: "이 질문에서 나온 기록", path: "/cases/split-custody-access-token", }, ],