Files
tech-log-frontend/src/features/tech-log/application/ports/public-content-queries.ts
T
DongHyeonka fe6b56a96c fix: 열리지 않는 주소를 링크로 그리지 않는다
「다음에 읽을 것」에 걸린 결정 링크가 404 였다. 주소는 서버가 게시할 때 만들어 저장한
문자열이라 화면 코드 어디에도 흔적이 없었고, 방문자만 그것을 만났다.

- `resolvesToPublicRoute` 가 route contract 에서 읽은 라우트 표에 주소를 맞춰 본다. 맞는
  라우트가 없는 줄은 관계 목록이 링크로 그리지 않는다.
- 결정 목록의 각 항목이 `slug` 를 element id 로 단다 — 결정의 공개 주소가 이 목록 위의
  앵커이므로, id(UUID)를 달면 다른 기록이 건 링크가 갈 곳을 잃는다.
- 앵커로 들어오면 그 결정까지 내려간다. 목록은 받아온 뒤에 그려지므로 브라우저의 기본
  앵커 이동만으로는 닿지 않는다.

주제 화면 셋을 더하면서 함께 늘려야 했던 것들도 여기서 맞춘다 — nginx 로 나가는 경로
패턴, 라우트마다 하나씩인 수동 접근성 증거, 그리고 그 둘을 세는 CI 게이트 기준값.
게이트 형상 digest 는 이전 gates.json 에서 옛 값(87a22f68…)을 먼저 재현한 뒤 새로 계산했다.
2026-09-02 09:54:51 +09:00

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[]>;
}>;