fix: 열리지 않는 주소를 링크로 그리지 않는다

「다음에 읽을 것」에 걸린 결정 링크가 404 였다. 주소는 서버가 게시할 때 만들어 저장한
문자열이라 화면 코드 어디에도 흔적이 없었고, 방문자만 그것을 만났다.

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

주제 화면 셋을 더하면서 함께 늘려야 했던 것들도 여기서 맞춘다 — nginx 로 나가는 경로
패턴, 라우트마다 하나씩인 수동 접근성 증거, 그리고 그 둘을 세는 CI 게이트 기준값.
게이트 형상 digest 는 이전 gates.json 에서 옛 값(87a22f68…)을 먼저 재현한 뒤 새로 계산했다.
This commit is contained in:
DongHyeonka
2026-09-02 09:54:51 +09:00
parent eedc90b674
commit fe6b56a96c
21 changed files with 239 additions and 19 deletions
@@ -0,0 +1,18 @@
# TECH_LOG_STUDIO_TOPIC_EDIT accessibility review
Status: pending-manual-review
Route ID: TECH_LOG_STUDIO_TOPIC_EDIT
Release ID:
Reviewer:
Reviewed at:
Signature:
Attestation: pending
M1 Keyboard: pending
M2 Visible focus: pending
M3 Route focus: pending
M4 Modal focus: pending
M5 Error association: pending
M6 Color signal: pending
M7 Reduced motion: pending
Screen reader: pending
Notes: Human review pending; automated evidence does not replace signed keyboard, focus, and screen-reader review.
@@ -0,0 +1,18 @@
# TECH_LOG_TOPICS accessibility review
Status: pending-manual-review
Route ID: TECH_LOG_TOPICS
Release ID:
Reviewer:
Reviewed at:
Signature:
Attestation: pending
M1 Keyboard: pending
M2 Visible focus: pending
M3 Route focus: pending
M4 Modal focus: pending
M5 Error association: pending
M6 Color signal: pending
M7 Reduced motion: pending
Screen reader: pending
Notes: Human review pending; automated evidence does not replace signed keyboard, focus, and screen-reader review.
@@ -0,0 +1,18 @@
# TECH_LOG_TOPIC_VARIANT accessibility review
Status: pending-manual-review
Route ID: TECH_LOG_TOPIC_VARIANT
Release ID:
Reviewer:
Reviewed at:
Signature:
Attestation: pending
M1 Keyboard: pending
M2 Visible focus: pending
M3 Route focus: pending
M4 Modal focus: pending
M5 Error association: pending
M6 Color signal: pending
M7 Reduced motion: pending
Screen reader: pending
Notes: Human review pending; automated evidence does not replace signed keyboard, focus, and screen-reader review.
+21
View File
@@ -1238,6 +1238,24 @@
"schemaId": "markdown",
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPICS-md",
"path": "artifacts/tests/a11y-manual/TECH_LOG_TOPICS.md",
"schemaId": "markdown",
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-VARIANT-md",
"path": "artifacts/tests/a11y-manual/TECH_LOG_TOPIC_VARIANT.md",
"schemaId": "markdown",
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TOPIC-EDIT-md",
"path": "artifacts/tests/a11y-manual/TECH_LOG_STUDIO_TOPIC_EDIT.md",
"schemaId": "markdown",
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-report-json",
"path": "artifacts/tests/a11y-manual/report.json",
@@ -1960,7 +1978,9 @@
"artifact-artifacts-tests-a11y-manual-TECH-LOG-REFERENCE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-CONCEPT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-QUESTION-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPICS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-VARIANT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECTS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-RECORDS-md",
@@ -1982,6 +2002,7 @@
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-ASSETS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TAXONOMY-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PROJECT-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TOPIC-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASES-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASE-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-NOT-FOUND-md",
+5 -5
View File
@@ -38,28 +38,28 @@
},
"contractSet": {
"setAlgorithm": "CA_CONTRACT_SET_V1",
"setDigest": "sha256:eecf0834de5be9bd7dfcc9f0e8e8a3e04d661213468c94e9051def7c90e2b5c1",
"setDigest": "sha256:898ecb949562bd88090d4a316fdfe324a62b7e841fed5c6a82e3b1bbbb95dfbd",
"packages": [
{
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:fa91ee5069c1117cd328e582044e1d4f9a0787634d75d7b048f812336ebbba18",
"runtimeProtocolVersion": 1,
"sourceRevision": "ffa088b"
"sourceRevision": "1aae8dc"
},
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:babb24ab85c5b92b2d8b9ad9aa10151430fd15aae84ca5318564468b3c9278ca",
"digest": "sha256:957cd1aa02ddde85420ea959c241ba7898fad6563db28d36dc0b364c2c545b03",
"runtimeProtocolVersion": 1,
"sourceRevision": "ffa088b"
"sourceRevision": "1aae8dc"
},
{
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c",
"runtimeProtocolVersion": 1,
"sourceRevision": "ffa088b"
"sourceRevision": "1aae8dc"
}
]
}
+8 -3
View File
@@ -476,7 +476,10 @@ const CANONICAL_GATE_SHAPE_SHA256 =
// 이 값을 만든 계산이 상수가 고정될 때 쓰인 그 계산임을 확인했다.
// 릴리즈 편집 화면: 같은 방법으로 다시 계산했다. f9e7e521… 을 이전 gates.json 에서 먼저
// 재현했다.
"87a22f686ab8f80bd333811102b338e283dc6d25a114011d34f74ca554c58f2d";
// 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`): FE-GATE-009 가 각
// 라우트의 수동 접근성 증거를 얻어 다시 계산했다. 같은 방법이다 — 87a22f68… 을 이전
// gates.json 에서 먼저 재현해 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
"e4e61b069cee79d97a1cac3972934af312a8d97e18dad4bf5f7fa06931b60c99";
function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
const normalized = gates.map(
@@ -538,8 +541,10 @@ function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[]
// list, so editing meant scrolling past every release to reach it.
// 개념(CONCEPT) 문서 종류가 `/concepts/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성 증거를
// 하나씩 갖는 규칙이 그대로 적용된다.
if (contract.artifacts.length !== 135) {
failures.push(`artifact authority baseline must contain exactly 135 artifacts; received ${contract.artifacts.length}`);
// 주제(Topic) 화면 셋이 뒤를 이었다: 목록 `/topics`, 축 상세 `/topics/:slug/:variant`,
// 그리고 Studio 의 주제 편집 `/studio/topics/:id`.
if (contract.artifacts.length !== 138) {
failures.push(`artifact authority baseline must contain exactly 138 artifacts; received ${contract.artifacts.length}`);
}
if (contract.stages.length !== 5) {
failures.push(`stage authority baseline must contain exactly 5 stages; received ${contract.stages.length}`);
@@ -381,6 +381,7 @@ export function decisionItemToDecision(item: Readonly<Record<string, unknown>>):
];
return Object.freeze({
id: String(item.id ?? ""),
slug: String(item.slug ?? ""),
status: (item.status as ProjectDecision["status"]) ?? "PROPOSED",
date: dateLabel(item.decidedAt as string),
/*
@@ -129,6 +129,8 @@ export type PublicRecord =
export type ProjectDecision = {
id: string;
/** 공개 주소의 앵커(`/projects/{project}/decisions#{slug}`). 이 카탈로그에서는 id 와 같다. */
slug: string;
status: "ADOPTED" | "PROPOSED";
date: string;
title: string;
@@ -663,6 +665,7 @@ export const projects: ReadonlyArray<Project> = [
decisions: [
{
id: "storage-port-unification",
slug: "storage-port-unification",
status: "ADOPTED",
date: "2026.08.10",
title: "파일 저장 계약을 하나로 통합합니다",
@@ -689,6 +692,7 @@ export const projects: ReadonlyArray<Project> = [
},
{
id: "feed-pagination-boundary",
slug: "feed-pagination-boundary",
status: "ADOPTED",
date: "2026.08.11",
title: "목록 페이징과 컬렉션 로딩을 분리합니다",
@@ -764,6 +768,7 @@ export const projects: ReadonlyArray<Project> = [
decisions: [
{
id: "browser-secret-boundary",
slug: "browser-secret-boundary",
status: "ADOPTED",
date: "2026.08.09",
title: "브라우저 클라이언트에는 Client Secret을 두지 않습니다",
@@ -138,6 +138,12 @@ export type PublicRecord =
export type ProjectDecision = {
id: string;
/**
* 공개 주소의 앵커. 결정에는 상세 화면이 없어 다른 기록은
* `/projects/{project}/decisions#{slug}` 로 이 결정을 가리킨다. 목록의 각 항목이 이 값을
* element id 로 달아야 그 링크가 도착한다 — id(UUID)를 달면 링크가 갈 곳을 잃는다.
*/
slug: string;
status: "ADOPTED" | "PROPOSED";
date: string;
/** 작성자가 붙인 제목. 결정문과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다. */
@@ -2,7 +2,7 @@
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:fa91ee5069c1117cd328e582044e1d4f9a0787634d75d7b048f812336ebbba18",
"sourceRevision": "ffa088b",
"sourceRevision": "1aae8dc",
"operationIds": [
"createCaseDraft",
"getCaseForEdit",
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:babb24ab85c5b92b2d8b9ad9aa10151430fd15aae84ca5318564468b3c9278ca",
"sourceRevision": "ffa088b",
"digest": "sha256:957cd1aa02ddde85420ea959c241ba7898fad6563db28d36dc0b364c2c545b03",
"sourceRevision": "1aae8dc",
"operationIds": [
"getPublicSite",
"getPublicHome",
@@ -791,6 +791,11 @@ export interface components {
ProjectDecisionItem: {
/** Format: uuid */
id: string;
/** @description 공개 주소의 앵커. 결정에는 상세 화면이 없으므로 다른 기록이 이 결정을 가리킬 때 쓰는 주소가
* `/projects/{projectSlug}/decisions#{slug}` 이고, 목록의 각 항목이 이 값을 element id 로 단다.
* id(UUID)를 앵커로 쓰면 다른 기록이 건 링크가 재발행 때마다 깨진다.
* */
slug: string;
/** @description 작성자가 붙인 제목. 결정문(`statement`)과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다. */
title: string;
/** @description 제목 바로 아래에 오는 요약. */
@@ -1842,6 +1842,7 @@ components:
type: object
required:
- id
- slug
- title
- summary
- statement
@@ -1851,6 +1852,12 @@ components:
- decidedAt
properties:
id: *id004
slug:
type: string
description: |
공개 주소의 앵커. 결정에는 상세 화면이 없으므로 다른 기록이 이 결정을 가리킬 때 쓰는 주소가
`/projects/{projectSlug}/decisions#{slug}` 이고, 목록의 각 항목이 이 값을 element id 로 단다.
id(UUID)를 앵커로 쓰면 다른 기록이 건 링크가 재발행 때마다 깨진다.
title:
type: string
description: 작성자가 붙인 제목. 결정문(`statement`)과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다.
@@ -2,7 +2,7 @@
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c",
"sourceRevision": "ffa088b",
"sourceRevision": "1aae8dc",
"operationIds": [
"getStudioSession",
"getStudioDashboard",
@@ -0,0 +1,39 @@
import { TECH_LOG_ROUTE_REGISTRY } from "../../contracts/tech-log-route-contract.ts";
/**
* 서버가 준 공개 주소가 실제로 열리는 주소인지 본다.
*
* 화면에 걸리는 링크의 상당수는 서버가 만든 문자열이다 — 관계("다음에 읽을 것"), 홈의 최신 목록,
* 근거 링크. 그 문자열은 게시 시점에 굳어져 저장되므로, 라우트가 없는 모양으로 한 번 만들어지면
* 화면 코드를 아무리 봐도 드러나지 않고 방문자만 404 를 만난다. 실제로 결정의 주소가
* `/projects/{p}/decisions/{d}` 로 저장돼 있었고 그런 라우트는 없었다.
*
* 그래서 링크를 그리기 전에 라우트 표에 맞춰 본다. 표는 손으로 옮겨 적지 않고 route contract 에서
* 읽는다 — 라우트가 늘면 이 검사도 함께 는다.
*/
const PUBLIC_ROUTE_PATTERNS = Object.values(TECH_LOG_ROUTE_REGISTRY)
.filter((route) => route.layoutGroup === "PUBLIC" && !route.path.endsWith("*"))
.map((route) =>
new RegExp(
`^${route.path
.split("/")
.map((segment) => (segment.startsWith(":") ? "[^/]+" : escapeLiteral(segment)))
.join("/")}$`,
),
);
function escapeLiteral(segment: string) {
return segment.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
}
/** 앵커(`#`)와 질의 문자열은 라우트를 고르지 않는다 — 떼고 본다. */
export function resolvesToPublicRoute(path: string | null | undefined): boolean {
if (!path) return false;
if (!path.startsWith("/")) return false;
const withoutFragment = path.split("#")[0]!.split("?")[0]!;
const normalized =
withoutFragment.length > 1 && withoutFragment.endsWith("/")
? withoutFragment.slice(0, -1)
: withoutFragment;
return PUBLIC_ROUTE_PATTERNS.some((pattern) => pattern.test(normalized));
}
@@ -1,4 +1,5 @@
import { Link } from "react-router-dom";
import { useEffect } from "react";
import { Link, useLocation } from "react-router-dom";
import {
RegisteredNotFoundRoute,
@@ -11,12 +12,24 @@ import { usePublicContent } from "../use-public-content.tsx";
export function ProjectDecisionsPage() {
const { params } = useRouteInput<"TECH_LOG_PROJECT_DECISIONS">();
const slug = typeof params.slug === "string" ? params.slug : "";
const { hash } = useLocation();
const view = usePublicContent(["tech-log", "project", slug, "decisions"], async (queries) => {
const project = await queries.getProject(slug);
return project
? { project, decisions: await queries.getProjectDecisions(slug) }
: { project: undefined, decisions: [] };
});
/*
결정은 상세 화면이 없다. 다른 기록이 거는 주소가 이 목록 위의 앵커(`#slug`)이므로, 그 링크로
들어오면 해당 결정까지 내려가 있어야 한다. 브라우저의 기본 앵커 이동은 문서가 이미 그려져
있을 때만 일어나는데 이 목록은 받아온 뒤에 그려지므로, 그려진 다음 한 번 더 맞춘다.
*/
const ready = view.ready;
useEffect(() => {
if (!ready || !hash) return;
document.getElementById(decodeURIComponent(hash.slice(1)))?.scrollIntoView();
}, [ready, hash]);
if (!view.ready) return view.fallback;
const { project, decisions } = view.data;
@@ -28,7 +41,7 @@ export function ProjectDecisionsPage() {
<ol className="project-decision-list">
{decisions.map((decision) => (
<li key={decision.id}>
<article id={decision.id}>
<article id={decision.slug || decision.id}>
{/*
작성자가 나눠 쓴 줄은 그대로 나눠 보여야 한다. 이 칸들은 Markdown 을 거치지 않고
텍스트 노드로 들어가므로, HTML 이 줄바꿈을 공백으로 접어 여러 문단이 한 줄로
@@ -1,5 +1,7 @@
import { Link } from "react-router-dom";
import { resolvesToPublicRoute } from "../../../domain/navigation/public-path.ts";
/**
* 관계 한 줄.
*
@@ -35,14 +37,20 @@ export function PublicDocumentRelations({
kicker?: string;
title?: string;
}) {
if (relations.length === 0) return null;
/*
주소는 서버가 게시할 때 만들어 저장한 문자열이다. 라우트가 없는 모양으로 저장되면 화면 코드
어디에도 흔적이 없고 방문자만 404 를 만난다 — 결정의 주소가 실제로 그랬다. 열리지 않는 줄은
링크로 그리지 않는다.
*/
const reachable = relations.filter((relation) => resolvesToPublicRoute(relation.path));
if (reachable.length === 0) return null;
return (
<section className="document-relations" aria-labelledby="relations-title">
<p className="section-kicker">{kicker}</p>
<h2 id="relations-title">{title}</h2>
<ul>
{relations.map((relation) => {
{reachable.map((relation) => {
/*
링크의 이름은 「묶음 이름 + 제목」까지다. 설명까지 이름에 들어가면 관계 목록을 훑을 때
링크 하나하나가 문단이 되어 목록으로서 쓸모가 없어진다. 설명은 눈으로 보는 보조
@@ -0,0 +1,51 @@
import { describe, expect, it } from "vitest";
import { resolvesToPublicRoute } from "../../../src/features/tech-log/domain/navigation/public-path.ts";
/**
* 서버가 게시 때 만들어 저장하는 공개 주소의 모양들. 백엔드 `PublicPaths.forKind` 와 짝이다 —
* 그쪽에서 라우트 없는 모양을 만들면 여기가 먼저 깨진다.
*/
describe("서버가 만드는 공개 주소", () => {
it.each([
["/cases/collection-fetch-join-in-memory-paging"],
["/references/external-idp-federation-application-boundary"],
["/questions/edge-authorization-scope"],
["/concepts/idp-brokering"],
["/projects/keycloak-patterns"],
["/projects/keycloak-patterns/records"],
["/projects/keycloak-patterns/decisions"],
["/projects/keycloak-patterns/activity"],
["/topics/oauth-oidc-auth-boundary"],
["/topics/oauth-oidc-auth-boundary/spa"],
])("%s 는 열린다", (path) => {
expect(resolvesToPublicRoute(path)).toBe(true);
});
it("결정은 목록 위의 앵커다 — 앵커는 라우트를 고르지 않는다", () => {
expect(
resolvesToPublicRoute(
"/projects/keycloak-patterns/decisions#federation-is-not-an-application-pattern",
),
).toBe(true);
});
it("결정에 상세 라우트는 없다", () => {
expect(
resolvesToPublicRoute(
"/projects/keycloak-patterns/decisions/federation-is-not-an-application-pattern",
),
).toBe(false);
});
it.each([[null], [undefined], [""], ["https://example.com/cases/x"], ["/nope/x"]])(
"%s 는 열리지 않는다",
(path) => {
expect(resolvesToPublicRoute(path)).toBe(false);
},
);
it("Studio 주소는 공개 링크가 아니다", () => {
expect(resolvesToPublicRoute("/studio/projects/abc")).toBe(false);
});
});
+4 -2
View File
@@ -200,8 +200,10 @@ describe("CI gate contract", () => {
// than taking either side's number.
// Task 11 added TECH_LOG_STUDIO_ASSETS's manual accessibility evidence.
// Alignment follow-up item 2 added the TechLog junit report.
expect(contract.gates.reduce((total, gate) => total + gate.evidenceArtifactIds.length, 0)).toBe(114);
expect(contract.artifacts).toHaveLength(135);
// 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`)이 라우트마다
// 하나씩인 수동 접근성 증거를 셋 더했다.
expect(contract.gates.reduce((total, gate) => total + gate.evidenceArtifactIds.length, 0)).toBe(117);
expect(contract.artifacts).toHaveLength(138);
expect(contract.stages).toHaveLength(5);
expect(contract.retention.classes).toHaveLength(5);
expect(index.gates.get("FE-GATE-015")?.commandIds).toHaveLength(2);
@@ -192,7 +192,7 @@ describe("selective Task 3 contract closure", () => {
expect(canonical.gates).toHaveLength(27);
expect(canonical.commands).toHaveLength(85);
expect(canonical.gates.reduce((sum, gate) => sum + gate.commandIds.length, 0)).toBe(97);
expect(canonical.artifacts).toHaveLength(135);
expect(canonical.artifacts).toHaveLength(138);
expect(canonical.stages).toHaveLength(5);
expect(canonical.retention.classes).toHaveLength(5);
@@ -33,7 +33,9 @@ describe("TechLog production serving contract", () => {
"^/releases$",
"^/releases/[^/]+$",
"^/search$",
"^/topics$",
"^/topics/[^/]+$",
"^/topics/[^/]+/[^/]+$",
]);
expect(contract.studioPathPrefix).toBe("/studio");
// Derived from the route contract and sorted, exactly like the public half.
@@ -55,6 +57,7 @@ describe("TechLog production serving contract", () => {
"^/studio/releases$",
"^/studio/releases/[^/]+$",
"^/studio/taxonomy$",
"^/studio/topics/[^/]+$",
]);
expect(contract.notFound).toEqual({
status: 404,