fix: 결정 문서가 작성자가 채운 칸을 그대로 보여 준다

공개 결정 화면에 네 가지가 어긋나 있었다 — 제목 자리에 결정문 전문이 나오고, 요약이 아예
없고, 줄바꿈이 전부 접히고, 영향과 근거 기록이 늘 비어 있었다.

원인은 하나로 모인다. 결정에는 상세 endpoint 가 없다 — 공개 주소가 목록 위의 앵커다. 그런데
계약의 목록 항목에 title·summary·consequences·evidence 가 없어서, 프론트는 statement 를
제목 자리에도 쓰고 영향은 빈 배열로 고정해 두고 있었다. DB 에는 작성자가 쓴 값이 그대로
들어 있었다 — 제목, 여러 줄 요약, 영향 4건.

근거는 두 자리에서 온다. `sourceQuestion`/`sourceCase` 는 결정 하나가 원천 하나를 지목하던
예전 모양이고 지금 작성자는 관계로 여러 개를 건다. 둘을 합치되 같은 경로는 한 번만 싣는다.

줄바꿈은 별개 원인이다. 이 칸들은 Markdown 을 거치지 않고 텍스트 노드로 들어가는데 이 화면만
`PlainText` 를 쓰지 않고 값을 그대로 넣고 있었다. 글자만 확인하는 테스트로는 접힘이 보이지
않으므로, 두 줄짜리 픽스처를 두고 `<br>` 이 남는지 요소로 묻는다 — 되돌리면 빨개진다.

즉시 미리보기도 같은 구조로 맞췄다. 미리보기와 공개가 다르게 그리면 무엇을 믿을지 알 수 없다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
This commit is contained in:
DongHyeonka
2026-08-29 20:29:45 +09:00
co-authored by Claude Opus 5
parent 3b6ba64c08
commit 31afb4d800
12 changed files with 174 additions and 33 deletions
+5 -5
View File
@@ -38,28 +38,28 @@
},
"contractSet": {
"setAlgorithm": "CA_CONTRACT_SET_V1",
"setDigest": "sha256:cc3c8df1603d59aa8219320d792b5fc8b51802d67b84a03555faab43a6e91a81",
"setDigest": "sha256:6f1e4725f3e7fa76d910954bc5a9bdd2fdafd6fa39413b0846f13fea47e9e4bb",
"packages": [
{
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:762aa81e6906469939fddd833c204ed3ca53f0fa96371f18a5ea1edaf76a64e8",
"runtimeProtocolVersion": 1,
"sourceRevision": "2c25ccc"
"sourceRevision": "987c1b8"
},
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:66391f3a3fd91b632094de9f40814ccd42f2fec00d251e7134f33c9b663dfb18",
"digest": "sha256:c80f62cd37862ea48cef750e9966164570dfa0ceaf9ddc1872d497b0462a2a00",
"runtimeProtocolVersion": 1,
"sourceRevision": "2c25ccc"
"sourceRevision": "987c1b8"
},
{
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:96f655d75fc19c535eb87e24f5320fdc382d6d982aaa75b67fe6acbde1ee8ff2",
"runtimeProtocolVersion": 1,
"sourceRevision": "2c25ccc"
"sourceRevision": "987c1b8"
}
]
}
@@ -238,20 +238,35 @@ export function questionListItemToRecord(item: Readonly<Record<string, unknown>>
}
export function decisionItemToDecision(item: Readonly<Record<string, unknown>>): ProjectDecision {
const sources = [item.sourceQuestion, item.sourceCase]
.filter((entry): entry is Related => Boolean(entry))
.map((entry) => ({ title: entry.title ?? "", path: entry.path ?? "" }));
/*
근거는 두 자리에서 온다. `sourceQuestion`/`sourceCase` 는 결정 하나가 원천 하나를 지목하던
예전 모양이고, 지금 작성자는 관계로 여러 개를 건다 — 둘을 합치되 같은 경로는 한 번만 싣는다.
*/
const related = [
...[item.sourceQuestion, item.sourceCase].filter((entry): entry is Related => Boolean(entry)),
...((item.evidence as readonly Related[] | undefined) ?? []),
];
const evidence = [
...new Map(
related
.filter((entry) => entry.path && entry.title)
.map((entry) => [entry.path!, { title: entry.title!, path: entry.path! }]),
).values(),
];
return Object.freeze({
id: String(item.id ?? ""),
status: (item.status as ProjectDecision["status"]) ?? "PROPOSED",
date: dateLabel(item.decidedAt as string),
title: String(item.statement ?? ""),
/*
제목과 결정문은 다른 칸이다. 예전에는 계약에 제목이 없어 결정문을 제목 자리에도 썼고,
결정문이 여러 문단인 글에서는 제목 자리에 문서 전체가 들어갔다.
*/
title: String(item.title ?? item.statement ?? ""),
summary: String(item.summary ?? ""),
statement: String(item.statement ?? ""),
rationale: String(item.rationaleSummary ?? ""),
// The list response carries a rationale summary, not the consequence list the
// decision screen renders; the contract has no field for it here.
consequences: Object.freeze([]),
evidence: Object.freeze(sources),
consequences: Object.freeze(((item.consequences as readonly string[] | undefined) ?? []).map(String)),
evidence: Object.freeze(evidence),
});
}
@@ -119,6 +119,8 @@ export type ProjectDecision = {
status: "ADOPTED" | "PROPOSED";
date: string;
title: string;
/** 제목 바로 아래에 오는 요약. 결정문과 다른 칸이다. */
summary: string;
statement: string;
rationale: string;
consequences: ReadonlyArray<string>;
@@ -609,6 +611,8 @@ export const projects: ReadonlyArray<Project> = [
status: "ADOPTED",
date: "2026.08.10",
title: "파일 저장 계약을 하나로 통합합니다",
summary:
"저장 기술이 달라도 애플리케이션이 요구하는 의미는 같습니다.\n그래서 호출 계약을 기술별로 나누지 않습니다.",
statement:
"Filesystem과 Object Storage는 하나의 StoragePort와 서로 다른 Adapter로 구성합니다.",
rationale:
@@ -633,6 +637,7 @@ export const projects: ReadonlyArray<Project> = [
status: "ADOPTED",
date: "2026.08.11",
title: "목록 페이징과 컬렉션 로딩을 분리합니다",
summary: "컬렉션 Fetch Join 이 페이지 경계를 지우므로 부모 페이징과 컬렉션 로딩을 나눕니다.",
statement:
"피드 목록은 부모를 먼저 페이징하고 현재 페이지의 연관 컬렉션만 별도 조회합니다.",
rationale:
@@ -702,6 +707,7 @@ export const projects: ReadonlyArray<Project> = [
status: "ADOPTED",
date: "2026.08.09",
title: "브라우저 클라이언트에는 Client Secret을 두지 않습니다",
summary: "브라우저에 전달된 값은 사용자가 볼 수 있어 비밀로 클라이언트를 증명할 수 없습니다.",
statement: "SPA는 public client와 Authorization Code Flow + PKCE로 구성합니다.",
rationale:
"브라우저에 전달된 값은 사용자가 확인할 수 있으므로 Client Secret으로 클라이언트를 증명할 수 없습니다.",
@@ -133,7 +133,10 @@ export type ProjectDecision = {
id: string;
status: "ADOPTED" | "PROPOSED";
date: string;
/** 작성자가 붙인 제목. 결정문과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다. */
title: string;
/** 제목 바로 아래에 오는 요약. */
summary: string;
statement: string;
rationale: string;
consequences: ReadonlyArray<string>;
@@ -2,7 +2,7 @@
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:762aa81e6906469939fddd833c204ed3ca53f0fa96371f18a5ea1edaf76a64e8",
"sourceRevision": "2c25ccc",
"sourceRevision": "987c1b8",
"operationIds": [
"createCaseDraft",
"getCaseForEdit",
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:66391f3a3fd91b632094de9f40814ccd42f2fec00d251e7134f33c9b663dfb18",
"sourceRevision": "2c25ccc",
"digest": "sha256:c80f62cd37862ea48cef750e9966164570dfa0ceaf9ddc1872d497b0462a2a00",
"sourceRevision": "987c1b8",
"operationIds": [
"getPublicSite",
"getPublicHome",
@@ -743,12 +743,25 @@ export interface components {
activeQuestion?: components["schemas"]["RelatedEntry"];
selectedRecords: components["schemas"]["RelatedEntry"][];
};
/** @description 결정 화면은 상세 endpoint 없이 이 목록 하나로 그려진다(공개 주소가
* `/projects/{slug}/decisions#{slug}` 인 앵커다). 화면이 그리는 칸은 전부 여기 있어야 한다.
* */
ProjectDecisionItem: {
/** Format: uuid */
id: string;
/** @description 작성자가 붙인 제목. 결정문(`statement`)과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다. */
title: string;
/** @description 제목 바로 아래에 오는 요약. */
summary: string;
statement: string;
status: string;
rationaleSummary?: string;
/** @description 이 결정이 남기는 영향. 작성자가 순서대로 적는다. */
consequences: string[];
/** @description 이 결정의 근거로 연결한 공개 기록. `sourceQuestion`/`sourceCase` 는 예전의 단일 지목이고,
* 지금 작성자는 관계로 여러 개를 건다.
* */
evidence: components["schemas"]["RelatedEntry"][];
/** Format: date-time */
decidedAt: string;
sourceQuestion?: components["schemas"]["RelatedEntry"];
@@ -1749,20 +1749,45 @@ components:
items:
$ref: '#/components/schemas/RelatedEntry'
ProjectDecisionItem:
description: |
결정 화면은 상세 endpoint 없이 이 목록 하나로 그려진다(공개 주소가
`/projects/{slug}/decisions#{slug}` 인 앵커다). 화면이 그리는 칸은 전부 여기 있어야 한다.
type: object
required:
- id
- title
- summary
- statement
- status
- consequences
- evidence
- decidedAt
properties:
id: *id004
title:
type: string
description: 작성자가 붙인 제목. 결정문(`statement`)과 다르다 — 제목은 한 줄이고 결정문은 여러 문단일 수 있다.
summary:
type: string
description: 제목 바로 아래에 오는 요약.
statement:
type: string
status:
type: string
rationaleSummary:
type: string
consequences:
type: array
description: 이 결정이 남기는 영향. 작성자가 순서대로 적는다.
items:
type: string
evidence:
type: array
description: |
이 결정의 근거로 연결한 공개 기록. `sourceQuestion`/`sourceCase` 는 예전의 단일 지목이고,
지금 작성자는 관계로 여러 개를 건다.
items:
$ref: '#/components/schemas/RelatedEntry'
decidedAt: *id003
sourceQuestion:
$ref: '#/components/schemas/RelatedEntry'
@@ -2,7 +2,7 @@
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:96f655d75fc19c535eb87e24f5320fdc382d6d982aaa75b67fe6acbde1ee8ff2",
"sourceRevision": "2c25ccc",
"sourceRevision": "987c1b8",
"operationIds": [
"getStudioSession",
"getStudioDashboard",
@@ -4,6 +4,7 @@ import {
RegisteredNotFoundRoute,
useRouteInput,
} from "../../../../../presentation/routes/route-input.tsx";
import { PlainText } from "../../shared/public-render/inline-renderer.tsx";
import { ProjectPageHeader } from "../components/project-page-header.tsx";
import { usePublicContent } from "../use-public-content.tsx";
@@ -28,6 +29,11 @@ export function ProjectDecisionsPage() {
{decisions.map((decision) => (
<li key={decision.id}>
<article id={decision.id}>
{/*
작성자가 나눠 쓴 줄은 그대로 나눠 보여야 한다. 이 칸들은 Markdown 을 거치지 않고
텍스트 노드로 들어가므로, HTML 이 줄바꿈을 공백으로 접어 여러 문단이 한 줄로
이어져 보였다. `PlainText` 가 그 자리를 지킨다.
*/}
<header>
<div>
<span>{decision.status}</span>
@@ -36,29 +42,43 @@ export function ProjectDecisionsPage() {
</time>
</div>
<h2>{decision.title}</h2>
<p>{decision.statement}</p>
{decision.summary ? (
<p><PlainText text={decision.summary} /></p>
) : null}
</header>
<section>
<h3>결정</h3>
<p><PlainText text={decision.statement} /></p>
</section>
<section>
<h3>판단 이유</h3>
<p>{decision.rationale}</p>
<p><PlainText text={decision.rationale} /></p>
</section>
<section>
<h3>영향</h3>
<ul>
{decision.consequences.map((item) => (
<li key={item}>{item}</li>
))}
</ul>
{decision.consequences.length ? (
<ul>
{decision.consequences.map((item) => (
<li key={item}><PlainText text={item} /></li>
))}
</ul>
) : (
<p>남긴 영향이 없습니다.</p>
)}
</section>
<section>
<h3>근거 기록</h3>
<ul>
{decision.evidence.map((item) => (
<li key={item.path}>
<Link to={item.path}>{item.title}</Link>
</li>
))}
</ul>
{decision.evidence.length ? (
<ul>
{decision.evidence.map((item) => (
<li key={item.path}>
<Link to={item.path}>{item.title}</Link>
</li>
))}
</ul>
) : (
<p>연결한 근거 기록이 없습니다.</p>
)}
</section>
</article>
</li>
@@ -523,15 +523,21 @@ function ProjectDecisionDocument({
)}
</div>
<h2>{model.title}</h2>
<p><PlainText text={model.statement} /></p>
{model.summary ? (
<p><PlainText text={model.summary} /></p>
) : null}
</header>
<section>
<h3>결정</h3>
<p><PlainText text={model.statement} /></p>
</section>
<section>
<h3>판단 이유</h3>
<p><PlainText text={model.rationale} /></p>
</section>
<section>
<h3>영향</h3>
<OrderedItems items={model.consequences} />
<OrderedItems items={model.consequences} empty="남긴 영향이 없습니다." />
</section>
<section>
<h3>근거 기록</h3>
@@ -252,6 +252,59 @@ describe("TechLog project screens", () => {
]);
});
/*
결정에는 상세 화면이 없다 — 공개 주소가 이 목록 위의 앵커다. 그래서 작성자가 채운 칸이 전부
여기 그려져야 하는데, 계약의 목록 항목에 제목·요약·영향·근거가 없어 화면은 제목 자리에 결정문
전문을 그리고 영향과 근거를 늘 빈 목록으로 뒀다.
그리고 이 칸들은 Markdown 을 거치지 않고 텍스트 노드로 들어간다 — 작성자가 나눠 쓴 줄을
HTML 이 공백으로 접어 여러 문단이 한 줄로 이어져 보였다. 글자만 확인하면 그 접힘은 보이지
않으므로 줄바꿈이 실제 요소로 남는지 함께 묻는다.
*/
it("renders every authored field of a decision and keeps the author's line breaks", async () => {
const { container } = await renderPublicRoute(
"TECH_LOG_PROJECT_DECISIONS",
"/projects/backend-skeleton/decisions",
);
const [first] = Array.from(
container.querySelectorAll(".project-decision-list > li > article"),
);
const headings = Array.from(first!.querySelectorAll("h3"), (item) => item.textContent);
expect(headings).toEqual(["결정", "판단 이유", "영향", "근거 기록"]);
// 제목과 요약은 다른 칸이다 — 예전에는 둘 다 결정문이었다.
expect(first!.querySelector("h2")?.textContent).toBe("파일 저장 계약을 하나로 통합합니다");
expect(first!.querySelector("header p")?.textContent).toContain(
"저장 기술이 달라도",
);
const consequences = Array.from(
first!.querySelectorAll("section:nth-of-type(3) li"),
(item) => item.textContent,
);
expect(consequences.length).toBeGreaterThan(0);
});
it("keeps a multi-line decision field from collapsing into one line", async () => {
const { container } = await renderPublicRoute(
"TECH_LOG_PROJECT_DECISIONS",
"/projects/backend-skeleton/decisions",
);
/*
`PlainText` 는 줄바꿈을 `<br>` 로 남긴다. 글자만 비교하면 접혔는지 알 수 없다 — 접힌 화면도
같은 글자를 갖기 때문이다. 그래서 요소로 확인한다. 첫 결정의 요약이 두 줄짜리 픽스처다.
*/
const [first] = Array.from(
container.querySelectorAll(".project-decision-list > li > article"),
);
const summary = first!.querySelector("header p");
expect(summary?.textContent).toContain("저장 기술이 달라도");
expect(summary?.textContent).toContain("그래서 호출 계약을");
expect(summary?.querySelectorAll("br")).toHaveLength(1);
});
/*
활동은 로그다 — 언제 무엇을 올렸는지만 적는다. 각 줄에 그 기록으로 가는 링크가 있으면 같은
글에 닿는 길이 둘이 되고, 읽는 사람은 "기록"과 "활동"이 어떻게 다른지 매번 다시 판단해야 한다.