feat: 주제 화면을 계약에 잇고, 등록을 잊는 사고를 가드로 막는다
주제 화면은 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만
열었다. 제목과 설명까지 코드에 있었고, 목록에 없는 주제는 기록이 멀쩡히 있어도 404 로
갔다 — 픽스처의 `kubernetes` 가 그랬다. 계약에는 처음부터 `/topics/{slug}` 가 있었지만
아무도 부르지 않았다. 이제 그 연산을 부르고, 주제가 답하는 질문(논지)과 그 질문에 대해
실제로 만들어 본 답들(축)을 화면의 뼈대로 둔다.
프로젝트의 논지도 마찬가지다. 담을 칸이 없어 목적(`purpose`)을 대신 보여 주고
있었는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다.
축 CRUD 네 연산은 계약에 있으면서 기여 목록에 없었다 — 등록되지 않은 연산은 타입에는
멀쩡히 보이는데 부를 수가 없다. `getPublicConcept` 과 `deleteConceptDraft` 가 정확히
그래서 못 불렸고, 개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" 가 떴다.
그래서 가드를 둘 넣는다. 공개 계약은 전수 대조하고(봉투 없이 바이트를 주는 `/media` 만
면제), 관리 계약은 **한 종류만 빠진 자리**를 본다 — 깨진 것이 늘 그 모양이었다.
개념 삭제 등록을 지워 보고 실제로 멈추는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
This commit is contained in:
co-authored by
Claude Opus 5
parent
618a228eff
commit
15e6ea8f15
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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(
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 주제 한 편.
|
||||
*
|
||||
* <p>계약은 이 자리에 관계 묶음을 세 개 준다 — 대표 Case, 열린 질문, 관련 프로젝트. 화면이
|
||||
* 쓰는 모양은 관계 한 줄과 같으므로 그대로 옮긴다. 작성자가 남긴 문장(`reason`)이 있으면
|
||||
* 목록에서 그것이 먼저 보인다.
|
||||
*/
|
||||
async function getTopicDetail(slug: string): Promise<PublicTopicDetail | undefined> {
|
||||
const detail = await read<Readonly<Record<string, unknown>>>("getPublicTopic", {
|
||||
topicSlug: slug,
|
||||
});
|
||||
if (detail === NOT_FOUND) return undefined;
|
||||
const topic = (detail.topic as Readonly<Record<string, unknown>>) ?? {};
|
||||
const entries = (value: unknown, label: string) =>
|
||||
Object.freeze(
|
||||
((value as readonly Readonly<Record<string, unknown>>[] | 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<Record<string, unknown>>[] | 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,
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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<Draft<PublicRecord>> = [
|
||||
],
|
||||
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<Draft<PublicRecord>> = [
|
||||
],
|
||||
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<Draft<PublicRecord>> = [
|
||||
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<Draft<PublicRecord>> = [
|
||||
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<Draft<PublicRecord>> = [
|
||||
"토큰 전달안과 신뢰 헤더안을 위협 모델로 비교하고 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<Draft<PublicRecord>> = [
|
||||
},
|
||||
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",
|
||||
|
||||
@@ -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));
|
||||
}
|
||||
|
||||
/**
|
||||
* 픽스처판 주제 한 편.
|
||||
*
|
||||
* <p>정적 카탈로그에는 축(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();
|
||||
},
|
||||
|
||||
@@ -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;
|
||||
};
|
||||
|
||||
/**
|
||||
* 주제 안의 접근/구조 하나.
|
||||
*
|
||||
* <p>이 주제가 답하는 질문에 대해 실제로 만들어 본 답이 하나씩이다. 인증 경계라면 SPA·BFF·
|
||||
* Mediator 가 각각 하나고, 각자 무엇을 알게 됐는지({@link conclusion})가 다르다. 그 결론이
|
||||
* 이 기록의 값어치이므로 비교표가 읽는 칸도 요약이 아니라 결론이다.
|
||||
*/
|
||||
export type PublicTopicVariant = {
|
||||
slug: string;
|
||||
title: string;
|
||||
path: string;
|
||||
summary: string;
|
||||
/** 만들어 보고 무엇을 알게 됐는가. 비어 있으면 아직 아무도 쓰지 않은 것이다. */
|
||||
conclusion: string;
|
||||
recordCount: number;
|
||||
};
|
||||
|
||||
/**
|
||||
* 주제 한 편. 목록의 {@link PublicTopic} 과 달리 주제 화면이 통째로 쓰는 모양이다.
|
||||
*
|
||||
* <p>주제 화면은 오래 주제 셋을 코드에 적어 두고 그 셋만 열었다. 새 주제를 만들면 화면이
|
||||
* 404 로 갔고, 계약에 이미 있던 `/topics/{slug}` 는 아무도 부르지 않았다.
|
||||
*/
|
||||
export type PublicTopicDetail = {
|
||||
name: string;
|
||||
slug: string;
|
||||
description: string;
|
||||
/** 이 주제가 답하는 질문. 사람이 쓴 한 문단이고, 기록을 합쳐 만들지 않는다. */
|
||||
thesis: string;
|
||||
/** 축의 이름. 「구조」「조회 전략」처럼 독자에게 보일 말이다. 비면 축을 쓰지 않는 주제다. */
|
||||
variantLabel: string;
|
||||
variants: ReadonlyArray<PublicTopicVariant>;
|
||||
featuredCases: ReadonlyArray<PublicRelation>;
|
||||
activeQuestions: ReadonlyArray<PublicRelation>;
|
||||
relatedProjects: ReadonlyArray<PublicRelation>;
|
||||
};
|
||||
|
||||
/**
|
||||
* 홈의 "최근 기록" 한 줄. 서버가 공개 투영에서 직접 고른다.
|
||||
*
|
||||
@@ -274,6 +312,8 @@ export type PublicContentQueries = Readonly<{
|
||||
* 있었고, Studio 에서 주제를 만들어도 바뀌지 않았다.
|
||||
*/
|
||||
listTopics(): Promise<PublicTopic[]>;
|
||||
/** 주제 한 편. 주제가 없으면 `undefined`. */
|
||||
getTopicDetail(slug: string): Promise<PublicTopicDetail | undefined>;
|
||||
getLatestEntries(): Promise<LatestRecordEntry[]>;
|
||||
getHomeFocusItems(): Promise<HomeFocusItem[]>;
|
||||
searchPublicContent(query: string): Promise<SearchablePublicEntity[]>;
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"packageId": "@tech-log/management-contract",
|
||||
"version": "1.0.0",
|
||||
"digest": "sha256:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998",
|
||||
"sourceRevision": "ca1bbfe",
|
||||
"sourceRevision": "0f4d2cd",
|
||||
"operationIds": [
|
||||
"createCaseDraft",
|
||||
"getCaseForEdit",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -745,6 +745,11 @@ export interface components {
|
||||
name: string;
|
||||
slug: string;
|
||||
oneLinePurpose: string;
|
||||
/** @description 이 프로젝트가 무엇을 밝혔는가. 사람이 쓰는 한 문단이고, 기록을 합쳐 자동으로
|
||||
* 나오지 않는다. 프로젝트 화면의 첫 문단이 이것이다 — 담을 칸이 없어 오래
|
||||
* `purpose` 를 대신 보여 주고 있었고, 그쪽은 목적이지 결론이 아니다.
|
||||
* */
|
||||
thesis?: string;
|
||||
purpose: string;
|
||||
boundary: string;
|
||||
phase: string;
|
||||
|
||||
@@ -1758,6 +1758,13 @@ components:
|
||||
type: string
|
||||
oneLinePurpose:
|
||||
type: string
|
||||
thesis:
|
||||
type: string
|
||||
maxLength: 2000
|
||||
description: |
|
||||
이 프로젝트가 무엇을 밝혔는가. 사람이 쓰는 한 문단이고, 기록을 합쳐 자동으로
|
||||
나오지 않는다. 프로젝트 화면의 첫 문단이 이것이다 — 담을 칸이 없어 오래
|
||||
`purpose` 를 대신 보여 주고 있었고, 그쪽은 목적이지 결론이 아니다.
|
||||
purpose:
|
||||
type: string
|
||||
boundary:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"packageId": "@tech-log/studio-contract",
|
||||
"version": "3.1.0",
|
||||
"digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c",
|
||||
"sourceRevision": "ca1bbfe",
|
||||
"sourceRevision": "0f4d2cd",
|
||||
"operationIds": [
|
||||
"getStudioSession",
|
||||
"getStudioDashboard",
|
||||
|
||||
@@ -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])[] = [];
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
/**
|
||||
* 주제 한 편.
|
||||
*
|
||||
* <p>이 화면은 오래 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만 열었다.
|
||||
* 제목과 설명까지 코드에 있었고, 새 주제를 만들면 화면이 그대로 404 로 갔다 — 계약에는 처음부터
|
||||
* `/topics/{slug}` 가 있었지만 아무도 부르지 않았다. 손으로 나열한 목록에 새 것을 빠뜨리는 일이
|
||||
* 이 저장소에서 반복됐고, 여기서는 목록 자체를 없앤다.
|
||||
*
|
||||
* <p>주제가 답하는 질문(논지)과, 그 질문에 대해 실제로 만들어 본 답들(축)이 이 화면의 뼈대다.
|
||||
* 축이 없는 주제도 있으므로 — 축을 쓸지는 주제마다 다르다 — 비면 그 자리를 그리지 않는다.
|
||||
*/
|
||||
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 <RegisteredNotFoundRoute />;
|
||||
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 <RegisteredNotFoundRoute />;
|
||||
|
||||
const axisLabel = topic.variantLabel.trim() || "접근";
|
||||
return (
|
||||
<main id="main-content" className="shell public-index-page">
|
||||
<main id="main-content" className="shell public-index-page topic-hub">
|
||||
<header className="public-page-header">
|
||||
<p className="section-kicker">Topic</p>
|
||||
<h1>{topic.title}</h1>
|
||||
<p>{topic.description}</p>
|
||||
<h1>{topic.name}</h1>
|
||||
{/*
|
||||
논지가 있으면 그것이 이 주제의 첫 문장이다. 설명은 목록에서 주제를 가려내는 한 줄이고,
|
||||
논지는 이 주제가 무엇에 답하는지를 말한다 — 둘 다 있으면 논지를 보인다.
|
||||
*/}
|
||||
<ProseText text={topic.thesis || topic.description} />
|
||||
</header>
|
||||
|
||||
{topic.variants.length > 0 ? (
|
||||
<section className="topic-variants" aria-labelledby="topic-variants-title">
|
||||
<p className="section-kicker">{axisLabel}</p>
|
||||
<h2 id="topic-variants-title">{`${axisLabel}별로 무엇을 알게 됐나`}</h2>
|
||||
<ul>
|
||||
{topic.variants.map((variant) => (
|
||||
<li key={variant.slug}>
|
||||
<a href={variant.path}>
|
||||
<strong>{variant.title}</strong>
|
||||
{/*
|
||||
비교표가 읽는 것은 결론이다. 요약은 이것이 무엇인가를 말하고, 결론은 만들어
|
||||
보고 무엇을 알게 됐는가를 말한다 — 축을 견주는 자리에서 쓸모 있는 것은 뒤쪽이다.
|
||||
*/}
|
||||
<p>{variant.conclusion || variant.summary}</p>
|
||||
{variant.recordCount > 0 ? (
|
||||
<span aria-hidden="true">{`기록 ${variant.recordCount}`}</span>
|
||||
) : null}
|
||||
</a>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</section>
|
||||
) : null}
|
||||
|
||||
<PublicDocumentRelations
|
||||
relations={[...topic.featuredCases, ...topic.activeQuestions]}
|
||||
kicker="Reading order"
|
||||
title="먼저 읽을 것"
|
||||
/>
|
||||
|
||||
<div className="public-result-heading">
|
||||
<h2>관련 기록</h2>
|
||||
<p>{records.length}개의 관련 기록</p>
|
||||
<p>{`${records.length}개의 관련 기록`}</p>
|
||||
</div>
|
||||
<PublicRecordList records={records} />
|
||||
|
||||
<PublicDocumentRelations
|
||||
relations={topic.relatedProjects}
|
||||
kicker="Projects"
|
||||
title="이 주제를 다룬 프로젝트"
|
||||
/>
|
||||
</main>
|
||||
);
|
||||
}
|
||||
|
||||
+5
-1
@@ -48,7 +48,11 @@ export function PublicDocumentRelations({
|
||||
return (
|
||||
<li key={relation.path}>
|
||||
<Link to={relation.path}>
|
||||
{relation.label ? <span>{relation.label}</span> : null}
|
||||
{/*
|
||||
묶음 이름이 없어도 자리는 남긴다 — 이 링크는 세 칸짜리 격자라 첫 칸이 사라지면
|
||||
제목이 라벨 칸으로 밀려 들어간다.
|
||||
*/}
|
||||
<span>{relation.label ?? ""}</span>
|
||||
<div>
|
||||
<strong>{relation.title}</strong>
|
||||
{description ? <p aria-hidden="true">{description}</p> : null}
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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";
|
||||
|
||||
/**
|
||||
* 계약에 있는 연산은 전부 기여 목록에 등록되어 있어야 한다.
|
||||
*
|
||||
* <p>등록하지 않은 연산은 타입에는 멀쩡히 보이는데 부를 수가 없다. 그래서 화면은 그 연산이
|
||||
* 없는 줄 모르고 옆 연산을 부르거나(개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다"
|
||||
* 가 떴다), 아무것도 못 부른 채로 조용히 빈 화면이 됐다(`getPublicConcept`). 손으로 나열한
|
||||
* 목록에 새 종류를 빠뜨리는 일이 이 저장소에서만 다섯 번 넘게 났고, 매번 다섯 개의 검사를
|
||||
* 다 통과했다.
|
||||
*
|
||||
* <p>그래서 목록을 손으로 관리하지 않고 계약 문서에서 읽어 대조한다. 새 연산을 계약에 더하고
|
||||
* 등록을 잊으면 여기서 멈춘다.
|
||||
*/
|
||||
function contractOperationIds(path: string): string[] {
|
||||
const text = readFileSync(path, "utf8");
|
||||
return [...text.matchAll(/^\s+operationId:\s*(\S+)\s*$/gmu)].map((match) => match[1]!);
|
||||
}
|
||||
|
||||
/**
|
||||
* 봉투를 쓰지 않고 바이트를 그대로 돌려주는 연산. `<img src>` 가 직접 가리키므로 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/…`)로
|
||||
* 문서를 다루므로, 계약에 있으나 화면이 부르지 않는 연산이 정상적으로 많다. 그래서 전수 대조는
|
||||
* 뜻이 없고, 대신 **한 종류만 빠진 자리**를 본다 — 실제로 깨진 것이 늘 그 모양이었다.
|
||||
*
|
||||
* <p>주소에서 종류를 지우면 같은 일을 하는 연산들이 한 가족으로 모인다. 가족 하나가 세 종류만
|
||||
* 갖고 있으면 나머지 한 종류의 화면은 조용히 옆 종류의 API 를 부르거나 아무것도 못 부른다.
|
||||
*/
|
||||
const KIND_SEGMENTS = ["cases", "references", "questions", "concepts"] as const;
|
||||
|
||||
test("문서 종류별 관리 연산에 빠진 종류가 없다", () => {
|
||||
const families = new Map<string, Set<string>>();
|
||||
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<string>();
|
||||
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")}`);
|
||||
});
|
||||
@@ -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");
|
||||
|
||||
|
||||
@@ -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",
|
||||
},
|
||||
],
|
||||
|
||||
Reference in New Issue
Block a user