From 4da6d77c431c3312292f80d451e54c6ed6c83429 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 1 Sep 2026 17:13:18 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=EA=B8=B0=EB=A1=9D=EC=9D=84=20=EC=B6=95?= =?UTF-8?q?=EC=97=90=20=EA=B1=B8=EA=B3=A0,=20=ED=83=90=EC=83=89=EC=9D=84?= =?UTF-8?q?=20=EC=A3=BC=EC=A0=9C=EB=A1=9C=20=EB=AC=B6=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 기록↔축 연결을 저장할 경로가 없었다. `record_variant` 는 공개 조회가 읽기만 할 뿐 아무도 쓰지 않았고, 계약의 `variantIds` 도 어디에도 닿지 않았다. 관계와 같은 「통째 교체」 방식으로 세 저장소(문서·질문·결정)에 배선한다 — 클라이언트가 보낸 배열이 곧 최종 상태이고, diff 를 뜨면 순서 재배열과 삭제를 구분하지 못한다. 문서 편집기에서 고른 주제의 축을 체크박스로 고른다. 축은 주제 안에서만 뜻이 있으므로 카탈로그에 섞지 않고 따로 읽는다. 아무 축에도 걸지 않아도 되고, 그 경우 이 기록은 그 주제의 공통 기록이 된다 — 빈 줄이 곧 「공통」이라 따로 표시하지 않는다. 탐색은 `type=CONCEPT` 을 조용히 버리고 있었다. 필터 폼은 개념을 고를 수 있게 하는데 화면 쪽 목록에는 개념이 없어서, 고르면 주소만 바뀌고 아무것도 걸리지 않았다. 목록을 손으로 적지 않고 `Record` 에서 뽑아 컴파일러가 잡게 한다. 그리고 탐색을 주제로 묶는다. 게시 순서 한 줄로는 무엇이 있는지는 보여도 무엇에 대한 것들인지가 보이지 않아, 스무 편이 넘어가면 목록이 아니라 더미가 된다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- .../public/components/explore-filter-form.tsx | 17 +++- .../public/pages/explore-page.tsx | 64 +++++++++++++-- .../components/common-document-fields.tsx | 36 +++++++++ .../components/document-editor-screen.tsx | 30 +++++++ .../studio/components/document-editor.tsx | 6 +- .../tech-log/presentation/styles/globals.css | 18 +++++ .../public-discovery-screens.test.tsx | 18 ++++- .../tech-log/topic-variant-wiring.test.ts | 81 +++++++++++++++++++ 8 files changed, 259 insertions(+), 11 deletions(-) create mode 100644 tests/features/tech-log/topic-variant-wiring.test.ts diff --git a/src/features/tech-log/presentation/public/components/explore-filter-form.tsx b/src/features/tech-log/presentation/public/components/explore-filter-form.tsx index f8b2ae2..0d3d79c 100644 --- a/src/features/tech-log/presentation/public/components/explore-filter-form.tsx +++ b/src/features/tech-log/presentation/public/components/explore-filter-form.tsx @@ -8,8 +8,23 @@ import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; 탐색이 거를 수 있는 종류. 이름은 공용 표에서 가져온다 — 예전에는 이 목록만 「개념」이라 적어 두어 배지·머리말과 어긋났고, 같은 문서가 화면마다 다른 이름으로 보였다. 결정은 프로젝트 안에서만 읽히므로 여기 없다. + + 목록을 손으로 적지 않고 `Record` 에서 뽑는다. 종류가 늘면 이 표가 비어 있는 + 것을 컴파일러가 잡는다 — 손으로 나열한 목록에 새 종류를 빠뜨리는 일이 이 저장소에서 반복됐고, + 탐색 화면은 그래서 실제로 `type=CONCEPT` 을 조용히 버리고 있었다(고를 수는 있는데 걸리지 않았다). */ -const EXPLORE_KINDS = ["CASE", "REFERENCE", "QUESTION", "CONCEPT"] as const; +const EXPLORE_KIND_ORDER: Record = { + CASE: 1, + REFERENCE: 2, + QUESTION: 3, + CONCEPT: 4, +}; + +export const EXPLORE_KINDS: ReadonlyArray = Object.freeze( + (Object.keys(EXPLORE_KIND_ORDER) as RecordKind[]).sort( + (left, right) => EXPLORE_KIND_ORDER[left] - EXPLORE_KIND_ORDER[right], + ), +); export function ExploreFilterForm({ action, diff --git a/src/features/tech-log/presentation/public/pages/explore-page.tsx b/src/features/tech-log/presentation/public/pages/explore-page.tsx index 08de317..587249c 100644 --- a/src/features/tech-log/presentation/public/pages/explore-page.tsx +++ b/src/features/tech-log/presentation/public/pages/explore-page.tsx @@ -1,6 +1,8 @@ -import type { RecordKind } from "../../../application/ports/public-content-queries.ts"; +import { Link } from "react-router-dom"; + +import type { PublicRecord } from "../../../application/ports/public-content-queries.ts"; import { useRouteInput } from "../../../../../presentation/routes/route-input.tsx"; -import { ExploreFilterForm } from "../components/explore-filter-form.tsx"; +import { EXPLORE_KINDS, ExploreFilterForm } from "../components/explore-filter-form.tsx"; import { PublicRecordList } from "../components/public-record-list.tsx"; import { usePublicContent } from "../use-public-content.tsx"; @@ -8,14 +10,39 @@ function optionalString(value: unknown): string | undefined { return typeof value === "string" ? value : undefined; } +/** + * 기록을 주제별로 묶는다. + * + *

탐색은 오래 게시 순서 한 줄이었다. 무엇이 있는지는 보이지만 무엇에 대한 것들인지는 보이지 + * 않아서, 스무 편이 넘어가면 목록이 아니라 더미가 된다. 주제 안에서는 원래 순서(게시 역순)를 + * 그대로 지킨다. + * + *

묶음의 순서는 기록이 많은 주제부터다 — 가장 많이 다룬 것이 이 기록의 중심이다. + */ +function byTopic(records: ReadonlyArray) { + const groups = new Map(); + for (const record of records) { + const slug = record.topicSlug || ""; + const group = groups.get(slug); + if (group) group.records.push(record); + else groups.set(slug, { slug, name: record.topic || "주제 없음", records: [record] }); + } + return [...groups.values()].sort( + (left, right) => + right.records.length - left.records.length || (left.name < right.name ? -1 : 1), + ); +} + export function ExplorePage() { const { search } = useRouteInput<"TECH_LOG_EXPLORE">(); const requestedKind = optionalString(search.type); const topic = optionalString(search.topic); const project = optionalString(search.project); - const kind = (["CASE", "REFERENCE", "QUESTION"] as const).find( - (item) => item === requestedKind, - ) satisfies RecordKind | undefined; + /* + 거를 종류는 필터 폼과 같은 목록에서 읽는다. 여기 손으로 적어 둔 목록에 개념이 없어서, + 필터에서 「동작 원리」를 골라도 주소만 `type=CONCEPT` 이 되고 화면은 거르지 않았다. + */ + const kind = EXPLORE_KINDS.find((item) => item === requestedKind); const view = usePublicContent( ["tech-log", "explore", kind, topic, project], async (queries) => ({ @@ -29,10 +56,35 @@ export function ExplorePage() { if (!view.ready) return view.fallback; const { records } = view.data; + const groups = byTopic(records); + /* + 주제를 이미 하나로 좁혀 놓았다면 다시 주제로 묶어 봐야 묶음이 하나뿐이다. 그때는 평평한 + 목록이 낫다 — 제목만 한 줄 더 생긴다. + */ + const grouped = !topic && groups.length > 1; + return

Explore

탐색

유형과 기술 주제, 프로젝트를 조합해 공개 기록을 찾습니다.

공개 기록

{records.length}개의 공개 기록

- + {grouped ? ( + groups.map((group) => ( +
+ {/* + 주제 이름은 그 주제 화면으로 가는 링크다. 목록에서 한 주제가 눈에 들면 그 주제가 + 무엇에 답하는지로 바로 갈 수 있어야 한다. + */} +
+

+ {group.name} +

+

{`${group.records.length}개`}

+
+ +
+ )) + ) : ( + + )}
; } diff --git a/src/features/tech-log/presentation/studio/components/common-document-fields.tsx b/src/features/tech-log/presentation/studio/components/common-document-fields.tsx index 9f33de4..59f868c 100644 --- a/src/features/tech-log/presentation/studio/components/common-document-fields.tsx +++ b/src/features/tech-log/presentation/studio/components/common-document-fields.tsx @@ -1,6 +1,7 @@ import type { components } from "../../../contracts/studio/generated.ts"; import type { WorkingCopyInput } from "../../../contracts/studio/contract.ts"; import { FieldNotice, type FieldIssue } from "./field-issues.tsx"; +import type { TopicVariantEdit } from "../../../contracts/management/contract.ts"; import { RelationEditor } from "./relation-editor.tsx"; type CatalogEntry = components["schemas"]["CatalogEntry"]; @@ -26,6 +27,7 @@ export const COMMON_FIELD_PATHS = [ "/topicId", "/projectId", "/relations", + "/variantIds", ] as const; export function CommonDocumentFields({ @@ -33,6 +35,7 @@ export function CommonDocumentFields({ topics, projects, relations, + variants, issues, onUpdate, }: { @@ -40,6 +43,8 @@ export function CommonDocumentFields({ topics: CatalogEntry[]; projects: CatalogEntry[]; relations: CatalogEntry[]; + /** 고른 주제의 축. 주제를 고르지 않았거나 축을 쓰지 않는 주제면 빈 목록이다. */ + variants: readonly TopicVariantEdit[]; /** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */ issues: readonly FieldIssue[]; onUpdate(patch: Partial): void; @@ -66,6 +71,37 @@ export function CommonDocumentFields({

{draft.summary.length >= SUMMARY_MAX ? `요약을 ${SUMMARY_MAX}자까지 모두 썼습니다. 더 입력되지 않습니다.` : ""}

+ {/* + 축은 주제 안에서만 뜻이 있다. 주제를 고르지 않았거나 축을 쓰지 않는 주제면 이 자리를 + 그리지 않는다 — 고를 것이 없는 목록은 무엇을 놓쳤나 싶게 만든다. + + 아무 축에도 걸지 않아도 된다. 그 경우 이 기록은 주제의 공통 기록으로 읽힌다. + */} + {variants.length > 0 ? ( +
+ 축 — 고르지 않으면 이 주제의 공통 기록이 됩니다 + {variants.map((variant) => ( + + ))} + +
+ ) : null} onUpdate({ relations: next })} /> diff --git a/src/features/tech-log/presentation/studio/components/document-editor-screen.tsx b/src/features/tech-log/presentation/studio/components/document-editor-screen.tsx index d383042..7a8ffad 100644 --- a/src/features/tech-log/presentation/studio/components/document-editor-screen.tsx +++ b/src/features/tech-log/presentation/studio/components/document-editor-screen.tsx @@ -8,6 +8,7 @@ import type { WorkingCopyInput, WorkingCopyDetail, } from "../../../contracts/studio/contract.ts"; +import type { TopicVariantEdit } from "../../../contracts/management/contract.ts"; import { mergeAssetCatalog } from "../../../domain/content-format/asset-evidence-catalog.ts"; import { createLocalId } from "../../../domain/studio/local-id.ts"; import type { DocumentEditorController } from "./document-editor-controller.ts"; @@ -296,6 +297,34 @@ export function DocumentEditorScreen({ documentId }: { documentId: string }) { */ const validation = validationSource ? validationOf(validationSource, studio.now()) : null; + /* + 고른 주제의 축. 카탈로그(`TOPIC`/`PROJECT`/`RELATION`/`EVIDENCE`)는 주제와 무관한 전체 + 목록이라 여기에 섞을 수 없다 — 축은 주제 안에서만 뜻이 있고, 주제를 바꾸면 고를 수 있는 + 것이 통째로 바뀐다. + */ + const selectedTopicId = editor?.draft.topicId ?? null; + const [variants, setVariants] = useState([]); + + useEffect(() => { + if (!selectedTopicId) { + setVariants([]); + return; + } + let cancelled = false; + void (async () => { + try { + const loaded = await studio.managementGateway.listTopicVariants(selectedTopicId); + if (!cancelled) setVariants(loaded); + } catch { + // 축을 못 읽어도 편집은 계속돼야 한다 — 축은 선택 사항이다. + if (!cancelled) setVariants([]); + } + })(); + return () => { + cancelled = true; + }; + }, [selectedTopicId, studio.managementGateway]); + const controller = useMemo(() => { if (!editor || editor.documentId !== documentId) return null; return { @@ -349,6 +378,7 @@ export function DocumentEditorScreen({ documentId }: { documentId: string }) { void; @@ -68,7 +72,7 @@ export function DocumentEditor({

문서 편집

{controller.draft.title || "제목 없는 작업본"}

- + {controller.draft.kind === "CASE" ? : controller.draft.kind === "CONCEPT" diff --git a/src/features/tech-log/presentation/styles/globals.css b/src/features/tech-log/presentation/styles/globals.css index ab89472..911ad2e 100644 --- a/src/features/tech-log/presentation/styles/globals.css +++ b/src/features/tech-log/presentation/styles/globals.css @@ -2902,3 +2902,21 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65 text-align: left; } } + +/* + 탐색의 주제 묶음. 묶음 제목은 그 주제 화면으로 가는 링크이고, 그 아래는 평소의 기록 목록 + 그대로다 — 새 배치를 만들지 않고 사이 여백만 준다. +*/ +.explore-topic-group + .explore-topic-group { + margin-top: 56px; +} + +.explore-topic-group .public-result-heading h3 { + margin: 0; + font-size: 20px; + letter-spacing: -0.02em; +} + +.explore-topic-group .public-result-heading h3 a:hover { + color: var(--signal); +} diff --git a/tests/features/tech-log/public-discovery-screens.test.tsx b/tests/features/tech-log/public-discovery-screens.test.tsx index fa6d5db..4336f13 100644 --- a/tests/features/tech-log/public-discovery-screens.test.tsx +++ b/tests/features/tech-log/public-discovery-screens.test.tsx @@ -346,19 +346,31 @@ describe("TechLog explore discovery", () => { expect(router.state.location.search).toBe(""); }); expect(screen.getByText("7개의 공개 기록")).toBeVisible(); + /* + 탐색은 오래 게시 순서 한 줄이었다. 무엇이 있는지는 보이지만 무엇에 대한 것들인지는 보이지 + 않아서, 스무 편이 넘어가면 목록이 아니라 더미가 된다. 이제 주제로 묶고, 묶음은 기록이 + 많은 주제부터 온다 — 가장 많이 다룬 것이 이 기록의 중심이다. + */ + expect( + within(screen.getByRole("main")) + .getAllByRole("heading", { level: 3 }) + .map((heading) => heading.textContent), + ).toEqual(["JPA", "Authentication", "Kubernetes", "Redis"]); + // 주제 이름은 그 주제 화면으로 가는 링크다. + expect(screen.getByRole("link", { name: "JPA" })).toHaveAttribute("href", "/topics/jpa"); + // 묶음 안에서는 원래 순서(게시 역순)를 그대로 지킨다. 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", + "/questions/collection-fetch-join-with-pagination", "/references/state-and-nonce-boundary", "/questions/validate-edge-token-again", + "/concepts/kubernetes-scheduling", "/cases/redis-adapter-ttl-boundary", - "/questions/collection-fetch-join-with-pagination", ]); }); diff --git a/tests/features/tech-log/topic-variant-wiring.test.ts b/tests/features/tech-log/topic-variant-wiring.test.ts new file mode 100644 index 0000000..a073b3c --- /dev/null +++ b/tests/features/tech-log/topic-variant-wiring.test.ts @@ -0,0 +1,81 @@ +import assert from "node:assert/strict"; +import { test } from "vitest"; + +import { TECH_LOG_MANAGEMENT_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-management-contract-contribution.ts"; + +/** + * 축(variant) CRUD 네 연산이 실제로 나가는 주소와 메서드. + * + *

계약에만 있고 기여 목록에 없으면 타입에는 멀쩡히 보이는데 부를 수가 없다. 축을 더할 때 + * 정확히 그 상태였다 — 계약에 넷이 다 있는데 화면에서 하나도 부를 수 없었다. + */ +const EXPECTED = [ + { operationId: "listTopicVariants", method: "GET", path: "/api/v1/studio/topics/{id}/variants" }, + { + operationId: "createTopicVariant", + method: "POST", + path: "/api/v1/studio/topics/{id}/variants", + }, + { + operationId: "updateTopicVariant", + method: "PUT", + path: "/api/v1/studio/topics/{id}/variants/{variantId}", + }, + { + operationId: "deleteTopicVariant", + method: "DELETE", + path: "/api/v1/studio/topics/{id}/variants/{variantId}", + }, +] as const; + +test("축 CRUD 네 연산이 자기 주소와 메서드로 등록되어 있다", () => { + const byId = new Map( + TECH_LOG_MANAGEMENT_CONTRIBUTION.http.map((entry) => [entry.contract.operationId, entry]), + ); + + for (const expected of EXPECTED) { + const installed = byId.get(expected.operationId); + assert.ok(installed, `${expected.operationId} 가 기여 목록에 있어야 한다`); + assert.equal(installed.contract.method, expected.method); + assert.equal(installed.contract.pathTemplate, expected.path); + } +}); + +/** + * 주소가 있는 것과 게이트웨이가 그것을 부르는 것은 다르다 — 삭제 경로에서 겪은 그대로다. + * 그래서 게이트웨이를 실제로 불러 어떤 연산이 어떤 인자로 나가는지 본다. + */ +test("게이트웨이가 축 연산을 주제 id 와 함께 부른다", async () => { + const { createHttpManagementGateway } = await import( + "../../../src/features/tech-log/adapters/http/http-management-gateway.ts" + ); + + const called: { operationId: string; input: unknown }[] = []; + const gateway = createHttpManagementGateway({ + operations: { + execute: (operationId: string, input: unknown) => { + called.push({ operationId, input }); + return Promise.resolve({ kind: "SUCCESS", value: [] }); + }, + }, + } as never); + + const topicId = "11111111-1111-4111-8111-111111111111"; + const variantId = "22222222-2222-4222-8222-222222222222"; + await gateway.listTopicVariants(topicId); + await gateway.createTopicVariant(topicId, { slug: "bff", title: "BFF" }); + await gateway.updateTopicVariant(topicId, variantId, { slug: "bff", title: "BFF" }); + await gateway.deleteTopicVariant(topicId, variantId, 3); + + assert.deepEqual( + called.map((entry) => entry.operationId), + ["listTopicVariants", "createTopicVariant", "updateTopicVariant", "deleteTopicVariant"], + ); + // 경로가 주제를 요구한다. 주제 id 를 빠뜨리면 서버는 다른 주제의 축을 보게 된다. + for (const entry of called) { + assert.equal((entry.input as { id?: string }).id, topicId, entry.operationId); + } + for (const entry of called.slice(2)) { + assert.equal((entry.input as { variantId?: string }).variantId, variantId, entry.operationId); + } +});