「다음에 읽을 것」에 걸린 결정 링크가 404 였다. 주소는 서버가 게시할 때 만들어 저장한 문자열이라 화면 코드 어디에도 흔적이 없었고, 방문자만 그것을 만났다. - `resolvesToPublicRoute` 가 route contract 에서 읽은 라우트 표에 주소를 맞춰 본다. 맞는 라우트가 없는 줄은 관계 목록이 링크로 그리지 않는다. - 결정 목록의 각 항목이 `slug` 를 element id 로 단다 — 결정의 공개 주소가 이 목록 위의 앵커이므로, id(UUID)를 달면 다른 기록이 건 링크가 갈 곳을 잃는다. - 앵커로 들어오면 그 결정까지 내려간다. 목록은 받아온 뒤에 그려지므로 브라우저의 기본 앵커 이동만으로는 닿지 않는다. 주제 화면 셋을 더하면서 함께 늘려야 했던 것들도 여기서 맞춘다 — nginx 로 나가는 경로 패턴, 라우트마다 하나씩인 수동 접근성 증거, 그리고 그 둘을 세는 CI 게이트 기준값. 게이트 형상 digest 는 이전 gates.json 에서 옛 값(87a22f68…)을 먼저 재현한 뒤 새로 계산했다.
339 lines
11 KiB
TypeScript
339 lines
11 KiB
TypeScript
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
|
|
|
|
export type QuestionStatus =
|
|
| "OPEN"
|
|
| "INVESTIGATING"
|
|
| "PAUSED"
|
|
| "RESOLVED"
|
|
| "ARCHIVED";
|
|
|
|
export type PublicRelation = {
|
|
/** 묶음 이름. 「근거」「적용 기준」처럼 분류다. 문장이 아니다. */
|
|
label: string;
|
|
/** 관계 대상의 요약. 왜 이 기록이 걸려 있는지를 목록에서 바로 읽게 한다. */
|
|
summary: string;
|
|
/** 작성자가 남긴 이유. 「다음에 무엇을 읽을지」의 답이다. */
|
|
note: string;
|
|
/** 낮을수록 먼저. 상세 화면이 앞의 한둘만 펴 두는 데 쓴다. */
|
|
priority: number;
|
|
title: string;
|
|
path: string;
|
|
};
|
|
|
|
export type RecordSection = {
|
|
id: string;
|
|
title: string;
|
|
paragraphs: ReadonlyArray<string>;
|
|
bullets?: ReadonlyArray<string>;
|
|
};
|
|
|
|
type PublicRecordBase = {
|
|
kind: RecordKind;
|
|
slug: string;
|
|
title: string;
|
|
summary: string;
|
|
path: string;
|
|
topic: string;
|
|
topicSlug: string;
|
|
projectSlug: string;
|
|
projectTitle: string;
|
|
publishedAt: string;
|
|
publishedLabel: string;
|
|
visibility: "PUBLIC";
|
|
relations: ReadonlyArray<PublicRelation>;
|
|
};
|
|
|
|
/**
|
|
* 본문이 `:::evidence key="..."` 로 가리키는 Asset.
|
|
*
|
|
* <p>본문에는 key 만 있고 `/media/{assetId}` 는 UUID 로만 서빙하므로 — 주소가 추측 불가능한 것이
|
|
* 의도된 성질이다 — 공개 화면이 key 를 주소로 바꾸려면 이 대응이 함께 와야 한다.
|
|
*/
|
|
export type PublicBodyAsset = {
|
|
assetKey: string;
|
|
assetId: string;
|
|
url: string;
|
|
contentType: string;
|
|
altText: string;
|
|
width: number | null;
|
|
height: number | null;
|
|
decorative: boolean;
|
|
};
|
|
|
|
export type CaseRecord = PublicRecordBase & {
|
|
kind: "CASE";
|
|
problem: string;
|
|
conclusion: string;
|
|
environment: string;
|
|
verification: string;
|
|
lastVerifiedLabel: string;
|
|
/**
|
|
* 본문 Markdown 원문.
|
|
*
|
|
* <p>`sections` 는 이것을 제목·문단·불릿으로만 줄인 것이라 표·코드·callout·evidence 가 사라진다.
|
|
* 문서 화면은 원문을 직접 파싱한다.
|
|
*/
|
|
content: string;
|
|
bodyAssets: ReadonlyArray<PublicBodyAsset>;
|
|
sections: ReadonlyArray<RecordSection>;
|
|
};
|
|
|
|
export type ReferenceRule = {
|
|
title: string;
|
|
body: string;
|
|
};
|
|
|
|
export type ReferenceRecord = PublicRecordBase & {
|
|
kind: "REFERENCE";
|
|
purpose: string;
|
|
rules: ReadonlyArray<ReferenceRule>;
|
|
applyWhen: ReadonlyArray<string>;
|
|
exceptions: ReadonlyArray<string>;
|
|
examples: ReadonlyArray<string>;
|
|
verifiedAt: string;
|
|
};
|
|
|
|
export type QuestionOption = {
|
|
title: string;
|
|
description: string;
|
|
};
|
|
|
|
export type QuestionRecord = PublicRecordBase & {
|
|
kind: "QUESTION";
|
|
questionStatus: QuestionStatus;
|
|
facts: ReadonlyArray<string>;
|
|
assumptions: ReadonlyArray<string>;
|
|
unknowns: ReadonlyArray<string>;
|
|
constraints: ReadonlyArray<string>;
|
|
options: ReadonlyArray<QuestionOption>;
|
|
nextValidation: string;
|
|
resolution?: {
|
|
summary: string;
|
|
path: string;
|
|
linkLabel: string;
|
|
};
|
|
};
|
|
|
|
/**
|
|
* 개념.
|
|
*
|
|
* <p>Reference 는 판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉜다. 개념은 그렇게 나누지 않는다 —
|
|
* 처음부터 풀어 읽는 글이라 본문 하나로 흐르고, 낡음은 검증일이 아니라 `basisVersion` 이 말한다.
|
|
*/
|
|
export type ConceptRecord = PublicRecordBase & {
|
|
kind: "CONCEPT";
|
|
/** "Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 비면 화면에 그리지 않는다. */
|
|
basisVersion: string;
|
|
/** 본문 Markdown 원문. Case 와 같은 규칙으로 `:::evidence` 가 도식을 끌어온다. */
|
|
content: string;
|
|
bodyAssets: ReadonlyArray<PublicBodyAsset>;
|
|
sections: ReadonlyArray<RecordSection>;
|
|
};
|
|
|
|
export type PublicRecord =
|
|
| CaseRecord
|
|
| ReferenceRecord
|
|
| QuestionRecord
|
|
| ConceptRecord;
|
|
|
|
export type ProjectDecision = {
|
|
id: string;
|
|
/**
|
|
* 공개 주소의 앵커. 결정에는 상세 화면이 없어 다른 기록은
|
|
* `/projects/{project}/decisions#{slug}` 로 이 결정을 가리킨다. 목록의 각 항목이 이 값을
|
|
* element id 로 달아야 그 링크가 도착한다 — id(UUID)를 달면 링크가 갈 곳을 잃는다.
|
|
*/
|
|
slug: string;
|
|
status: "ADOPTED" | "PROPOSED";
|
|
date: string;
|
|
/** 작성자가 붙인 제목. 결정문과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다. */
|
|
title: string;
|
|
/** 제목 바로 아래에 오는 요약. */
|
|
summary: string;
|
|
statement: string;
|
|
rationale: string;
|
|
consequences: ReadonlyArray<string>;
|
|
evidence: ReadonlyArray<{ title: string; path: string }>;
|
|
};
|
|
|
|
export type ProjectActivity = {
|
|
id: string;
|
|
date: string;
|
|
dateTime: string;
|
|
type: "PUBLICATION" | "PROJECT UPDATE" | "QUESTION";
|
|
title: string;
|
|
summary: string;
|
|
path: string;
|
|
recordPath?: string;
|
|
};
|
|
|
|
export type Project = {
|
|
slug: string;
|
|
title: string;
|
|
summary: string;
|
|
thesis: string;
|
|
stage: "DESIGN" | "VALIDATION";
|
|
currentGoal: string;
|
|
nextStep: string;
|
|
/*
|
|
이름만 있으면 그 주제로 갈 수 없다. 프로젝트 화면의 「주요 주제」가 오래 글자 목록이었던
|
|
것은 slug 를 여기서 버렸기 때문이고, 계약은 처음부터 둘 다 주고 있었다.
|
|
*/
|
|
topics: ReadonlyArray<{ name: string; slug: string }>;
|
|
decisions: ReadonlyArray<ProjectDecision>;
|
|
activity: ReadonlyArray<ProjectActivity>;
|
|
};
|
|
|
|
export type Release = {
|
|
version: string;
|
|
path: string;
|
|
title: string;
|
|
summary: string;
|
|
publishedAt: string;
|
|
publishedLabel: string;
|
|
changes: ReadonlyArray<string>;
|
|
reasons: ReadonlyArray<string>;
|
|
impacts: ReadonlyArray<string>;
|
|
related: ReadonlyArray<{ title: string; path: string }>;
|
|
};
|
|
|
|
/** 계약 `TopicListItem`. 목록 화면이 쓰는 만큼만 옮긴다. */
|
|
export type PublicTopic = {
|
|
name: string;
|
|
slug: string;
|
|
/** 이 주제가 답하는 질문. 이름은 무엇에 대한 것인지만 말하고 무엇에 답하는지는 말하지 않는다. */
|
|
thesis: string;
|
|
description: string;
|
|
/** 축의 이름. 비면 이 주제는 축을 쓰지 않는다. */
|
|
variantLabel: string;
|
|
variantCount: number;
|
|
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>;
|
|
};
|
|
|
|
/**
|
|
* 홈의 "최근 기록" 한 줄. 서버가 공개 투영에서 직접 고른다.
|
|
*
|
|
* 화면이 프로젝트를 하나씩 돌며 조립하던 때에는, 게시된 문서라도 그 문서가 매달린 프로젝트가
|
|
* 공개되어 있지 않으면 목록에서 통째로 빠졌다 — 실제로 게시한 Case 는 안 보이고 릴리스만
|
|
* 남았다. 무엇이 최근인지는 공개 투영 하나가 알고 있으므로 거기서 그대로 읽는다.
|
|
*/
|
|
export type LatestRecordEntry = {
|
|
id: string;
|
|
entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT_ACTIVITY" | "RELEASE";
|
|
title: string;
|
|
summary: string;
|
|
path: string;
|
|
publishedAt: string;
|
|
topic: string;
|
|
project: string;
|
|
};
|
|
|
|
export type FocusKey = "current" | "question" | "decision";
|
|
|
|
export type HomeFocusItem = {
|
|
key: FocusKey;
|
|
label: string;
|
|
title: string;
|
|
summary: string;
|
|
details: ReadonlyArray<{ label: string; value: string }>;
|
|
targetPath: string;
|
|
};
|
|
|
|
export type RecordFilters = {
|
|
kind?: RecordKind;
|
|
topic?: string;
|
|
/** 주제 안의 축. 주제 안에서만 유일하므로 `topic` 과 함께 준다. */
|
|
variant?: string;
|
|
project?: string;
|
|
openQuestionsOnly?: boolean;
|
|
};
|
|
|
|
export type SearchablePublicEntity = {
|
|
contentType: RecordKind | "PROJECT" | "RELEASE";
|
|
title: string;
|
|
summary: string;
|
|
path: string;
|
|
topic?: string;
|
|
topics?: ReadonlyArray<string>;
|
|
project?: string;
|
|
publishedAt?: string;
|
|
};
|
|
|
|
/**
|
|
* The application-facing boundary for the immutable source Public catalog.
|
|
* Method signatures intentionally retain the source query argument and return shapes.
|
|
*/
|
|
/**
|
|
* The public read surface.
|
|
*
|
|
* Every method is async because one of the two adapters behind this port is a
|
|
* network client. The other reads a bundled fixture and could answer
|
|
* synchronously, but a port has one shape: if the fixture adapter kept the
|
|
* synchronous signature, the HTTP adapter could not implement the same port
|
|
* and callers written against the fixture would not compile against the
|
|
* network.
|
|
*
|
|
* Failures throw rather than resolving to a Result. That matches the Studio
|
|
* gateways, and it lets `useApplicationQuery` classify a rejection once at the
|
|
* boundary instead of every caller unwrapping.
|
|
*/
|
|
export type PublicContentQueries = Readonly<{
|
|
listRecords(filters?: RecordFilters): Promise<PublicRecord[]>;
|
|
getRecord<K extends RecordKind>(
|
|
kind: K,
|
|
slug: string,
|
|
): Promise<Extract<PublicRecord, { kind: K }> | undefined>;
|
|
getProject(slug: string): Promise<Project | undefined>;
|
|
getRelease(version: string): Promise<Release | undefined>;
|
|
getProjectRecords(projectSlug: string): Promise<PublicRecord[]>;
|
|
getProjectDecisions(projectSlug: string): Promise<ProjectDecision[]>;
|
|
getProjectActivity(projectSlug: string): Promise<ProjectActivity[]>;
|
|
/**
|
|
* 공개된 주제 목록. 프로필의 "주요 관심 주제"가 이 값을 그린다 — 그 목록은 코드에 박혀
|
|
* 있었고, Studio 에서 주제를 만들어도 바뀌지 않았다.
|
|
*/
|
|
listTopics(): Promise<PublicTopic[]>;
|
|
/** 주제 한 편. 주제가 없으면 `undefined`. */
|
|
getTopicDetail(slug: string): Promise<PublicTopicDetail | undefined>;
|
|
getLatestEntries(): Promise<LatestRecordEntry[]>;
|
|
getHomeFocusItems(): Promise<HomeFocusItem[]>;
|
|
searchPublicContent(query: string): Promise<SearchablePublicEntity[]>;
|
|
}>;
|