From a6413d0301f18d4bf329544bed13ffa992c89b4b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 1 Sep 2026 15:19:47 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=EB=AC=B8=EC=84=9C=20=EC=A2=85=EB=A5=98?= =?UTF-8?q?=EB=A5=BC=20=EB=8F=85=EC=9E=90=EC=9D=98=20=EB=A7=90=EB=A1=9C=20?= =?UTF-8?q?=EB=B0=94=EA=BE=B8=EA=B3=A0=20=EB=AF=B8=ED=95=B4=EA=B2=B0?= =?UTF-8?q?=EC=9D=84=20=EB=88=88=EC=97=90=20=EB=9D=84=EA=B2=8C=20=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이 저장소의 종류 이름은 글을 담아 둔 방식의 이름이었다 — Case, Reference, Open Question. 독자는 그 말을 배우고 나서야 목록을 읽을 수 있었고, 정작 뜻풀이는 홈 바닥(2,000px 아래)에 있었다. 이름이 하는 일을 말하게 한다: Case → 직접 해보니 Reference → 다음에 쓸 기준 Question → 아직 모르는 것 Concept → 어떻게 동작하나 Decision → 이렇게 하기로 이름이 스스로 설명하므로 홈 바닥의 뜻풀이 섹션은 종류별 입구로 바꾼다. 그 목록에 손으로 적어 둔 `OpenQuestion` 은 사이트 어디에도 없는 여섯 번째 표기였다. 탐색 필터·Case/개념 breadcrumb·종류별 화면 제목도 각자 이름을 적고 있었다 — 전부 공용 표를 쓰게 한다. 목록의 종류 표시는 다섯이 같은 회색 11px 이라 스캔되지 않았다. 색을 다섯 칠하는 대신 지식의 상태 셋(확인함·정리함·미해결)으로 가르고 미해결만 강조한다. 이 기록에서 가장 정직한 신호인데 가장 안 보였다. mono 글꼴과 대문자 변환도 걷어낸다 — 이름이 한국어 문구가 되었고, mono 는 한글을 갖지 않아 낱말 사이만 벌어진다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- .../public/components/explore-filter-form.tsx | 10 +++++- .../public/components/public-record-list.tsx | 14 ++++++-- .../public/pages/explore-kind-page.tsx | 9 ++--- .../presentation/public/pages/home-page.tsx | 32 ++++++++++-------- .../shared/document-kind-labels.ts | 33 ++++++++++++++----- .../public-render/public-record-renderer.tsx | 4 +-- .../tech-log/presentation/styles/globals.css | 12 ++++++- .../public-discovery-screens.test.tsx | 13 +++++--- .../tech-log/public-document-screens.test.tsx | 14 ++++---- .../studio-decision-authoring.test.tsx | 2 +- .../tech-log/studio-editor-smoke.test.tsx | 4 +-- 11 files changed, 101 insertions(+), 46 deletions(-) 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 11df860..f8b2ae2 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 @@ -2,6 +2,14 @@ import { Link, useNavigate } from "react-router-dom"; import type { RecordKind } from "../../../application/ports/public-content-queries.ts"; import { usePublicContent } from "../use-public-content.tsx"; +import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; + +/* + 탐색이 거를 수 있는 종류. 이름은 공용 표에서 가져온다 — 예전에는 이 목록만 「개념」이라 + 적어 두어 배지·머리말과 어긋났고, 같은 문서가 화면마다 다른 이름으로 보였다. + 결정은 프로젝트 안에서만 읽히므로 여기 없다. +*/ +const EXPLORE_KINDS = ["CASE", "REFERENCE", "QUESTION", "CONCEPT"] as const; export function ExploreFilterForm({ action, @@ -94,7 +102,7 @@ export function ExploreFilterForm({ onSubmit={submit} > {showType ? ( - + ) : null} 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 d1d4e2e..431f5b5 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 @@ -1,7 +1,10 @@ import { Link } from "react-router-dom"; import type { PublicRecord } from "../../../application/ports/public-content-queries.ts"; -import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; +import { + DOCUMENT_KIND_LABELS, + DOCUMENT_KIND_STATES, +} from "../../shared/document-kind-labels.ts"; import { cardSummary } from "../../../domain/content-format/card-summary.ts"; export function PublicRecordList({ @@ -20,7 +23,14 @@ export function PublicRecordList({ {records.map((record) => (
  • - {DOCUMENT_KIND_LABELS[record.kind]} + {/* + 다섯 종류가 같은 회색 11px 로 나오면 목록이 스캔되지 않는다. 색을 다섯 개 칠하는 + 대신 지식의 상태 셋으로만 가른다 — 그중 「아직 모르는 것」만 강조한다. 이 기록에서 + 가장 정직한 신호인데 지금까지 가장 안 보였다. + */} + + {DOCUMENT_KIND_LABELS[record.kind]} +
    {record.title}

    {cardSummary(record.summary)}

    diff --git a/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx b/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx index accc137..22710f0 100644 --- a/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx +++ b/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx @@ -7,12 +7,13 @@ import { import { ExploreFilterForm } from "../components/explore-filter-form.tsx"; import { PublicRecordList } from "../components/public-record-list.tsx"; import { usePublicContent } from "../use-public-content.tsx"; +import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; const kinds = { - cases: { kind: "CASE", title: "Case", description: "문제를 재현하고 관찰한 값에서 설계 결론까지 따라갑니다." }, - references: { kind: "REFERENCE", title: "Reference", description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." }, - questions: { kind: "QUESTION", title: "Open Question", description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." }, - concepts: { kind: "CONCEPT", title: "개념", description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." }, + cases: { kind: "CASE", title: DOCUMENT_KIND_LABELS.CASE, description: "문제를 재현하고 관찰한 값에서 설계 결론까지 따라갑니다." }, + references: { kind: "REFERENCE", title: DOCUMENT_KIND_LABELS.REFERENCE, description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." }, + questions: { kind: "QUESTION", title: DOCUMENT_KIND_LABELS.QUESTION, description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." }, + concepts: { kind: "CONCEPT", title: DOCUMENT_KIND_LABELS.CONCEPT, description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." }, } as const; function optionalString(value: unknown): string | undefined { diff --git a/src/features/tech-log/presentation/public/pages/home-page.tsx b/src/features/tech-log/presentation/public/pages/home-page.tsx index c4a3f5d..61f89bb 100644 --- a/src/features/tech-log/presentation/public/pages/home-page.tsx +++ b/src/features/tech-log/presentation/public/pages/home-page.tsx @@ -11,28 +11,32 @@ import { LatestIndex, type LatestEntry, } from "../components/latest-index.tsx"; +import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts"; +/* + 종류별 입구. 예전에는 여기가 "이 낱말은 이런 뜻입니다" 하는 범례였고, 그 낱말을 쓰는 목록은 + 2,000px 위에 있었다 — 배우기 한참 전에 먼저 쓰는 셈이었다. 이름 자체가 하는 일을 말하도록 + 바꾼 뒤로는 뜻풀이가 필요 없으므로, 설명 대신 그 종류에서 무엇을 얻는지를 적는다. + + 라벨은 공용 표에서 가져온다. 여기 손으로 적어 두었을 때 `OpenQuestion` 이라는, 사이트 + 어디에도 없는 여섯 번째 표기가 생겨 있었다. +*/ const exploreEntries = [ { - label: "Case", - description: "문제를 따라가며 검증 과정을 읽습니다", + kind: "CASE", + description: "무엇을 해보고 무엇을 확인했는지", path: "/explore/cases", }, { - label: "Reference", - description: "다시 찾을 수 있는 기술 기준을 확인합니다", + kind: "REFERENCE", + description: "다음에 같은 판단을 할 때 볼 것", path: "/explore/references", }, { - label: "OpenQuestion", - description: "아직 끝나지 않은 판단과 다음 검증을 봅니다", + kind: "QUESTION", + description: "아직 답하지 못한 것과 다음 검증", path: "/explore/questions", }, - { - label: "Project", - description: "여러 기록을 하나의 시스템 맥락에서 연결합니다", - path: "/projects", - }, ] as const; function optionalString(value: unknown): string | undefined { @@ -177,15 +181,15 @@ export function HomePage() {

    Explore

    -

    어떤 맥락으로 읽을까요?

    +

    종류별로 읽기

      {exploreEntries.map((entry) => ( -
    • +
    • {entry.description} - {entry.label} + {DOCUMENT_KIND_LABELS[entry.kind]}
    • diff --git a/src/features/tech-log/presentation/shared/document-kind-labels.ts b/src/features/tech-log/presentation/shared/document-kind-labels.ts index 87548a4..fe348a9 100644 --- a/src/features/tech-log/presentation/shared/document-kind-labels.ts +++ b/src/features/tech-log/presentation/shared/document-kind-labels.ts @@ -5,17 +5,34 @@ type RecordKind = components["schemas"]["RecordKind"]; /** * 문서 종류를 사람에게 보여 주는 이름. * - *

      이 표는 화면마다 하나씩 복사되어 있었고, 그래서 갈라졌다. 같은 `QUESTION` 이 공개 화면에서는 - * "Open Question", 작업본 목록과 게시 기록에서는 "Question", 편집기 상태 줄에서는 "QUESTION" 으로 - * 나왔다 — 여섯 벌 중 네 가지 표기였다. 쓰는 사람은 같은 문서를 화면마다 다른 이름으로 만난다. + *

      이름은 문서의 정체가 아니라 독자에게 하는 일로 적는다. `Reference` 는 이 저장소가 문서를 + * 담아 둔 방식의 이름이지 읽는 사람의 말이 아니다 — 종류 이름이 스스로 설명하면 "어떤 맥락으로 + * 읽을까요?" 같은 범례가 따로 필요 없다. + * + *

      표가 화면마다 복사되어 있던 시절에는 같은 `QUESTION` 이 화면마다 네 가지 이름으로 나왔다. * *

      한 곳에 두면 다음에 종류가 늘어날 때도 한 번만 고친다. 종류를 더하면 이 표가 비어 있는 것을 * 타입이 잡는다 — `Record` 이므로 빠진 종류가 있으면 컴파일되지 않는다. */ export const DOCUMENT_KIND_LABELS: Record = { - CASE: "Case", - REFERENCE: "Reference", - QUESTION: "Open Question", - CONCEPT: "개념", - PROJECT_DECISION: "Decision", + CASE: "직접 해보니", + REFERENCE: "다음에 쓸 기준", + QUESTION: "아직 모르는 것", + CONCEPT: "어떻게 동작하나", + PROJECT_DECISION: "이렇게 하기로", +}; + +/** + * 독자가 실제로 구분해야 하는 것은 지식의 상태다. 다섯 종류를 셋으로 접는다 — 확인한 것, + * 정리한 것, 아직 모르는 것. 목록에서 미해결만 눈에 띄게 하는 것이 이 표의 쓰임이다. + * + *

      미해결이 이 기록의 가장 정직한 신호인데 다섯 종류가 같은 회색 11px 로 나오면 그것이 + * 가장 안 보인다. + */ +export const DOCUMENT_KIND_STATES: Record = { + CASE: "CONFIRMED", + CONCEPT: "CONFIRMED", + REFERENCE: "SETTLED", + PROJECT_DECISION: "SETTLED", + QUESTION: "OPEN", }; 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 78652dc..72eb592 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 @@ -160,7 +160,7 @@ function CaseDocument({ >