Files
tech-log-frontend/src/features/tech-log/adapters/static/public-content.ts
T
DongHyeonkaandClaude Opus 5 618a228eff fix: 관계의 묶음 이름과 작성자가 쓴 문장을 갈라 놓는다
관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지,
대상이 무엇인지 — 셋 다 `reason` 한 칸을 지나느라 경로마다 다른 것이 같은 자리에
나왔다. 렌더 모델 경로에서는 작성자의 문장이 묶음 이름 자리에 눌려 한 줄짜리 라벨인
척했고, 공개 조회 경로에서는 묶음 이름이 그 자리를 차지하고 작성자의 문장은 아예
버려졌다. 「다음에 무엇을 읽을지」의 답이 그 문장인데 공개 화면에 한 번도 나오지 않았다.

이제 셋이 각자의 칸을 갖는다. `label` 은 대상의 종류, `note` 는 작성자가 쓴 문장,
`summary` 는 대상의 요약이다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을
보인다 — 요약은 대상을 설명하고 문장은 왜 지금 이것을 읽어야 하는지를 설명한다.

공개 주소로 종류를 되짚던 삼항 사슬도 표로 바꾼다. `/concepts/` 가 어디에도 없어서
개념으로 가는 관계가 전부 `PROJECT` 로 떨어지고 있었다 — 손으로 나열한 목록에 새
종류를 빠뜨리는 일이 이 저장소에서만 다섯 번째다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 16:48:11 +09:00

854 lines
33 KiB
TypeScript

export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
export type QuestionStatus =
| "OPEN"
| "INVESTIGATING"
| "PAUSED"
| "RESOLVED"
| "ARCHIVED";
export type PublicRelation = {
reason: string;
summary: string;
title: string;
path: string;
/**
* 작성자가 관계마다 남긴 이유. 아래 정적 자료에는 아무도 쓴 적이 없으므로 여기서는 빈 값이고,
* 내보낼 때 {@link publicRecords} 가 한 번에 채운다. 목록마다 `note: ""` 를 손으로 적게 하면
* 언젠가 하나를 빠뜨린다 — 이 저장소에서 이미 다섯 번 그랬다.
*/
note: string;
/** 낮을수록 먼저. */
priority: number;
};
/** 정적 자료가 실제로 적는 모양. 작성자가 남긴 이유가 없으므로 두 칸이 선택이다. */
type StaticRelation = Omit<PublicRelation, "note" | "priority"> &
Partial<Pick<PublicRelation, "note" | "priority">>;
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. 계약의 `BodyAsset` 과 같은 모양이다. */
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 원문. 정적 기록은 문서 화면이 자체 본문을 쓰므로 비어 있다. */
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;
};
};
/**
* 개념. Reference 가 규칙·적용·예외로 나뉘는 것과 달리 본문 하나로 흐르고, 낡음은 검증일이
* 아니라 기준 버전이 말한다. 프로젝트가 없어도 되는 유일한 종류다.
*/
export type ConceptRecord = PublicRecordBase & {
kind: "CONCEPT";
basisVersion: string;
content: string;
bodyAssets: ReadonlyArray<PublicBodyAsset>;
sections: ReadonlyArray<RecordSection>;
};
export type PublicRecord =
| CaseRecord
| ReferenceRecord
| QuestionRecord
| ConceptRecord;
export type ProjectDecision = {
id: 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;
topics: ReadonlyArray<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 }>;
};
export type Profile = {
name: string;
introduction: string;
principles: ReadonlyArray<{ title: string; description: string }>;
currentProjectSlugs: ReadonlyArray<string>;
topics: ReadonlyArray<string>;
email?: 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;
};
/** 아래 목록이 적는 모양. 관계의 두 칸만 느슨하다. 유니온마다 나눠 적용한다. */
type Draft<T> = T extends unknown
? Omit<T, "relations"> & { relations: ReadonlyArray<StaticRelation> }
: never;
/**
* 관계의 빈 칸을 채운다. 정적 자료가 적는 모양과 포트가 요구하는 모양이 갈리는 지점이 여기
* 하나뿐이도록 한다.
*/
function withRelationDefaults(record: Draft<PublicRecord>): PublicRecord {
return {
...record,
relations: record.relations.map((relation) => ({
...relation,
note: relation.note ?? "",
priority: relation.priority ?? 0,
})),
} as PublicRecord;
}
const staticPublicRecords: ReadonlyArray<Draft<PublicRecord>> = [
{
kind: "CONCEPT",
slug: "kubernetes-scheduling",
title: "Kubernetes 스케줄링은 어떻게 결정되는가",
summary:
"Pod 가 Node 에 앉기까지 scheduler 가 거치는 단계를 따라가고, 예약과 실제 바인딩이 갈라지는 지점을 짚습니다.",
path: "/concepts/kubernetes-scheduling",
topic: "Kubernetes",
topicSlug: "kubernetes",
// 개념은 프로젝트 없이 선다 — 프로젝트 산출물이 아니라 아는 것이다.
projectSlug: "",
projectTitle: "",
publishedAt: "2026-08-20T10:00:00+09:00",
publishedLabel: "2026.08.20",
visibility: "PUBLIC",
basisVersion: "Kubernetes 1.31",
content: "",
bodyAssets: [],
sections: [
{
id: "what-the-scheduler-sees",
title: "스케줄러가 보는 것",
paragraphs: [
"스케줄러는 아직 노드가 정해지지 않은 Pod 를 감시한다. 그 목록은 API 서버가 주고, 결정의 근거는 노드의 여유 자원과 Pod 가 건 조건이다.",
],
},
{
id: "filtering-and-scoring",
title: "Filtering 과 Scoring",
paragraphs: [
"먼저 둘 수 없는 노드를 걸러 내고(Filtering), 남은 노드에 점수를 매긴다(Scoring). 거르는 단계에서 전부 탈락하면 Pod 는 Pending 으로 남는다.",
],
},
{
id: "reservation-and-binding",
title: "예약과 실제 바인딩의 간격",
paragraphs: [
"점수가 가장 높은 노드를 고른 뒤 스케줄러는 먼저 자기 캐시에 자리를 예약하고, 바인딩은 API 서버에 따로 보낸다. 그 사이에 노드 상태가 바뀌면 kubelet 이 거절할 수 있다.",
],
},
],
relations: [],
},
{
kind: "CASE",
slug: "collection-fetch-join-pagination",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
summary:
"반환된 20건 뒤에서 전체 컬렉션이 로드되는 과정을 측정하고, 목록의 페이지 경계를 다시 세웠습니다.",
path: "/cases/collection-fetch-join-pagination",
topic: "JPA",
topicSlug: "jpa",
projectSlug: "backend-skeleton",
projectTitle: "Backend Skeleton",
publishedAt: "2026-08-11T14:10:00+09:00",
publishedLabel: "2026.08.11",
visibility: "PUBLIC",
problem:
"FeedItem 20건을 요청했지만 컬렉션 Fetch Join 때문에 DB LIMIT가 사라지고, 전체 부모와 자식 행을 읽은 뒤 메모리에서 20건만 남겼습니다.",
conclusion:
"목록 페이징 쿼리와 컬렉션 로딩을 분리하고, 현재 페이지의 부모 키만 IN 배치로 조회합니다.",
environment: "PostgreSQL 16 · Hibernate 6 · Spring Data JPA",
verification: "FeedItem 100개, Zipf 편중 Highlight/Mention",
lastVerifiedLabel: "2026.08.11",
content: "",
bodyAssets: [],
sections: [
{
id: "fix-the-problem",
title: "문제를 고정하기",
paragraphs: [
"피드 목록에는 FeedItem과 작성자, 페이지, 하이라이트, 멘션이 함께 필요했다. 화면은 공개된 FeedItem을 최초 하이라이트 시각의 역순으로 20개씩 보여주고, 각 항목에는 최신 하이라이트를 최대 3개까지 붙인다.",
],
},
{
id: "fetch-join-attempt",
title: "첫 번째 시도: 컬렉션 Fetch Join",
paragraphs: [
"실험에 사용한 조회의 핵심 형태는 다음과 같다.",
],
},
{
id: "observed-values",
title: "관찰한 값",
paragraphs: [
"테스트 데이터는 FeedItem 100개와 Zipf 형태로 편중된 Highlight·Mention으로 구성했다. 소수의 FeedItem에 자식이 몰리도록 해 평균값만으로 문제가 가려지지 않게 했다.",
],
},
{
id: "separate-loading",
title: "페이징과 컬렉션 로딩을 분리하기",
paragraphs: [
"최종 구조는 두 단계다. 먼저 목록 정렬에 필요한 부모를 데이터베이스에서 20개로 고정한다. 그다음 현재 페이지의 부모 ID에 대해서만 필요한 컬렉션을 가져온다.",
],
},
{
id: "give-up-one-query",
title: "왜 한 번의 쿼리를 포기했는가",
paragraphs: [
"쿼리 수만 보면 한 번의 Fetch Join이 가장 단순해 보인다. 목록에서는 쿼리 수보다 페이지 경계가 먼저다. 데이터베이스가 20개 부모를 확정하지 못하면 자식 분포가 바뀔 때마다 읽는 행 수와 메모리 사용량이 흔들린다. 반환 개수는 같아도 비용을 예측할 수 없다.",
],
},
{
id: "remaining-cost",
title: "남은 비용과 적용 범위",
paragraphs: [
"Batch Fetch는 컬렉션 N+1을 줄이지만 필요한 자식만 자동으로 골라 주지는 않는다. 한 FeedItem에 Highlight가 매우 많다면 현재 페이지의 모든 Highlight가 로드될 수 있다. 최신 3개가 계약이면 부모별 제한 쿼리를 별도로 두어야 한다.",
],
},
],
relations: [
{
reason: "이 질문에서 시작됨",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination",
},
{
reason: "이 Case로 결정함",
summary: "",
title: "피드 목록은 부모 페이징과 연관 컬렉션 로딩을 분리합니다.",
path: "/projects/backend-skeleton/decisions#feed-pagination-boundary",
},
{
reason: "이 기준 문서로 정리됨",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy",
},
],
},
{
kind: "CASE",
slug: "redis-adapter-ttl-boundary",
title: "Redis Adapter가 도메인 TTL 정책을 소유하지 않는 이유",
summary:
"만료 정책과 Redis 명령 실행 책임을 분리해 Adapter를 바꿔도 애플리케이션 규칙이 유지되게 했습니다.",
path: "/cases/redis-adapter-ttl-boundary",
topic: "Redis",
topicSlug: "redis",
projectSlug: "backend-skeleton",
projectTitle: "Backend Skeleton",
publishedAt: "2026-08-07T16:30:00+09:00",
publishedLabel: "2026.08.07",
visibility: "PUBLIC",
problem:
"Redis Adapter가 키 이름과 TTL까지 결정하면 도메인 규칙이 저장 기술 내부로 들어가 메모리 구현이나 다른 저장소로 교체할 때 같은 정책을 다시 만들어야 했습니다.",
conclusion:
"애플리케이션은 만료 의미와 시간을 결정하고 Redis Adapter는 전달받은 저장 계약을 Redis 명령으로 변환합니다.",
environment: "Spring Boot · Redis · Testcontainers",
verification: "동일한 Port 계약으로 In-memory와 Redis Adapter 계약 테스트 실행",
lastVerifiedLabel: "2026.08.07",
content: "",
bodyAssets: [],
sections: [
{
id: "ownership",
title: "정책과 저장 명령의 주인을 구분하기",
paragraphs: [
"세션 만료나 임시 링크의 유효 시간은 제품 규칙입니다. EXPIRE 명령을 실행하는 방법은 Redis 구현 세부입니다. 두 책임을 같은 클래스에 두지 않았습니다.",
],
},
{
id: "contract",
title: "Port가 표현해야 하는 것",
paragraphs: [
"Port는 저장할 값과 만료 시각을 입력으로 받습니다. Adapter는 밀리초 변환과 명령 조합을 맡되 기본 TTL을 임의로 보충하지 않습니다.",
],
},
],
relations: [
{
reason: "이 프로젝트에 속함",
summary: "",
title: "Backend Skeleton",
path: "/projects/backend-skeleton",
},
{
reason: "이 결정과 연결됨",
summary: "",
title: "StoragePort와 Adapter의 책임을 분리합니다.",
path: "/projects/backend-skeleton/decisions#storage-port-unification",
},
],
},
{
kind: "REFERENCE",
slug: "state-and-nonce-boundary",
title: "Authorization Code Flow에서 state와 nonce의 경계",
summary:
"요청 위조 방지와 ID Token 재사용 방지를 서로 다른 검증값으로 정리했습니다.",
path: "/references/state-and-nonce-boundary",
topic: "Authentication",
topicSlug: "authentication",
projectSlug: "auth-lab",
projectTitle: "Auth Lab",
publishedAt: "2026-08-09T21:20:00+09:00",
publishedLabel: "2026.08.09",
visibility: "PUBLIC",
purpose:
"Authorization Code Flow에서 state와 nonce를 같은 보안 값처럼 설명하지 않고 각각 무엇을 검증하는지 다시 찾기 위한 기준입니다.",
rules: [
{
title: "state는 요청과 콜백을 연결합니다",
body: "클라이언트가 만든 state를 인증 요청에 넣고 콜백의 값과 비교해 자신이 시작한 흐름인지 확인합니다.",
},
{
title: "nonce는 인증 결과와 ID Token을 연결합니다",
body: "OIDC 요청의 nonce를 ID Token의 nonce claim과 비교해 다른 인증 결과가 재사용되는 위험을 줄입니다.",
},
{
title: "PKCE는 Code를 교환할 클라이언트를 증명합니다",
body: "code_challenge와 code_verifier는 탈취한 Authorization Code만으로 Token을 교환하지 못하게 합니다.",
},
],
applyWhen: [
"브라우저 기반 public client에서 Authorization Code Flow를 구성할 때",
"OIDC ID Token을 받아 로그인 결과를 검증할 때",
"state, nonce, PKCE의 책임을 설계 문서나 시퀀스에 나눠 표시할 때",
],
exceptions: [
"OAuth만 사용해 ID Token을 받지 않는 흐름에는 nonce 검증 대상이 없습니다.",
"state가 있다고 PKCE나 redirect URI 검증을 생략할 수는 없습니다.",
],
examples: [
"SPA는 state와 nonce를 요청별로 생성하고 code_verifier는 브라우저 밖으로 보내지 않습니다.",
"서버 기반 클라이언트도 state로 로그인 시작 요청과 콜백을 연결합니다.",
],
verifiedAt: "2026.08.09",
relations: [
{
reason: "이 질문의 검증 기준",
summary: "",
title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?",
path: "/questions/validate-edge-token-again",
},
{
reason: "이 프로젝트에 속함",
summary: "",
title: "Auth Lab",
path: "/projects/auth-lab",
},
],
},
{
kind: "REFERENCE",
slug: "jpa-list-fetch-strategy",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
summary:
"ToOne과 컬렉션, 페이지 경계, 전송 행 수를 함께 보고 목록 조회 전략을 고르는 기준입니다.",
path: "/references/jpa-list-fetch-strategy",
topic: "JPA",
topicSlug: "jpa",
projectSlug: "backend-skeleton",
projectTitle: "Backend Skeleton",
publishedAt: "2026-08-10T09:40:00+09:00",
publishedLabel: "2026.08.10",
visibility: "PUBLIC",
purpose:
"목록 조회에서 쿼리 수만 줄이다 페이지 경계나 전송량을 잃지 않도록 Fetch 전략을 선택하는 순서를 고정합니다.",
rules: [
{
title: "부모 페이지 경계를 먼저 고정합니다",
body: "LIMIT과 정렬이 DB에서 부모 행에 적용되는지 먼저 확인합니다.",
},
{
title: "ToOne과 컬렉션을 분리해 판단합니다",
body: "ToOne Fetch Join의 행 증가와 컬렉션 Fetch Join의 중복 행 증가는 비용이 다릅니다.",
},
{
title: "쿼리 수와 로드량을 함께 측정합니다",
body: "적은 쿼리가 곧 적은 데이터 로드를 의미하지 않으므로 반환 부모 수, 조인 행 수, 로드 엔티티 수를 함께 기록합니다.",
},
],
applyWhen: [
"연관 관계가 포함된 목록에 페이지 나누기가 필요할 때",
"N+1을 줄인 뒤 메모리 사용량과 전송 행 수가 늘었을 때",
"Fetch Join, Batch Fetch, DTO 조회 중 하나를 선택할 때",
],
exceptions: [
"부모 한 건을 읽는 상세 조회에는 목록 페이지 경계 기준을 그대로 적용하지 않습니다.",
"데이터 분포가 크게 치우치면 평균 대신 상위 구간의 로드량도 확인합니다.",
],
examples: [
"부모 ID를 먼저 20개 고른 뒤 해당 ID의 Highlight를 IN 배치로 읽습니다.",
"두 개의 List 컬렉션을 동시에 Fetch Join하면 MultipleBagFetchException 가능성을 먼저 확인합니다.",
],
verifiedAt: "2026.08.11",
relations: [
{
reason: "이 Case에서 측정함",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
{
reason: "이 질문을 해결함",
summary: "",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
path: "/questions/collection-fetch-join-with-pagination",
},
],
},
{
kind: "QUESTION",
slug: "validate-edge-token-again",
title: "oauth2-proxy가 전달한 토큰을 다시 검증해야 하는가?",
summary:
"Edge에서 인증한 뒤 Resource Server가 무엇을 신뢰할지 결정하기 위한 열린 질문입니다.",
path: "/questions/validate-edge-token-again",
topic: "Authentication",
topicSlug: "authentication",
projectSlug: "auth-lab",
projectTitle: "Auth Lab",
publishedAt: "2026-08-08T19:05:00+09:00",
publishedLabel: "2026.08.08",
visibility: "PUBLIC",
questionStatus: "OPEN",
facts: [
"oauth2-proxy는 Access Token 또는 사용자 식별 헤더를 upstream에 전달할 수 있습니다.",
"Spring Resource Server는 발급자와 공개 키를 기준으로 JWT를 다시 검증할 수 있습니다.",
],
assumptions: [
"nginx와 oauth2-proxy, Spring Server는 같은 운영 경계 안에 배치합니다.",
],
unknowns: [
"내부 요청에서 사용자 헤더 위조를 어떤 계층이 차단할지 아직 확정하지 않았습니다.",
"각 요청의 JWT 재검증 비용이 실제 병목이 되는지 측정하지 않았습니다.",
],
constraints: [
"브라우저에는 Access Token을 노출하지 않습니다.",
"Spring Server가 직접 외부 요청을 받는 우회 경로를 허용하지 않습니다.",
],
options: [
{
title: "Resource Server가 JWT를 다시 검증",
description: "서비스 경계를 독립적으로 유지하지만 검증 설정과 연산이 중복됩니다.",
},
{
title: "보호된 신뢰 헤더만 사용",
description: "구조는 단순하지만 Edge 우회 차단과 헤더 정제 책임을 명확히 증명해야 합니다.",
},
],
nextValidation:
"토큰 전달안과 신뢰 헤더안을 위협 모델로 비교하고 Edge 우회 요청을 포함한 통합 테스트를 실행합니다.",
relations: [
{
reason: "검증 기준",
summary: "",
title: "Authorization Code Flow에서 state와 nonce의 경계",
path: "/references/state-and-nonce-boundary",
},
{
reason: "이 프로젝트에서 추적함",
summary: "",
title: "Auth Lab 활동",
path: "/projects/auth-lab/activity#edge-trust-boundary",
},
],
},
{
kind: "QUESTION",
slug: "collection-fetch-join-with-pagination",
title: "컬렉션 Fetch Join을 유지하면서 페이징할 수 있는가?",
summary:
"컬렉션을 한 번에 읽으면서 부모 페이지 경계도 DB에 남길 수 있는지 확인한 질문입니다.",
path: "/questions/collection-fetch-join-with-pagination",
topic: "JPA",
topicSlug: "jpa",
projectSlug: "backend-skeleton",
projectTitle: "Backend Skeleton",
publishedAt: "2026-08-05T20:30:00+09:00",
publishedLabel: "2026.08.05",
visibility: "PUBLIC",
questionStatus: "RESOLVED",
facts: [
"Hibernate는 컬렉션 Fetch Join과 페이지 제한을 함께 사용하면 메모리 페이징 경고를 남깁니다.",
"부모 한 건에 자식이 여러 개면 SQL 결과 행에서 부모가 중복됩니다.",
],
assumptions: [
"목록은 부모 FeedItem 20건을 안정적으로 반환해야 합니다.",
],
unknowns: [],
constraints: [
"정렬과 LIMIT는 부모 목록 쿼리에서 적용되어야 합니다.",
"현재 페이지 밖의 컬렉션을 읽지 않아야 합니다.",
],
options: [
{
title: "컬렉션 Fetch Join 유지",
description: "쿼리는 하나지만 DB 페이지 경계를 잃고 전체 조인 결과를 읽습니다.",
},
{
title: "부모 페이징과 컬렉션 조회 분리",
description: "쿼리는 늘지만 부모 페이지 경계와 로드 범위를 지킬 수 있습니다.",
},
],
nextValidation: "결정한 분리 조회를 데이터 편중 조건에서도 반복 측정합니다.",
resolution: {
summary:
"컬렉션 Fetch Join을 목록 페이징에서 제거하고 부모 페이지 조회 뒤 현재 ID의 컬렉션만 배치로 읽기로 결정했습니다.",
path: "/cases/collection-fetch-join-pagination",
linkLabel: "해결 과정을 Case로 읽기",
},
relations: [
{
reason: "이 Case로 해결됨",
summary: "",
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
{
reason: "적용 기준",
summary: "",
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy",
},
],
},
];
export const publicRecords: ReadonlyArray<PublicRecord> =
staticPublicRecords.map(withRelationDefaults);
export const projects: ReadonlyArray<Project> = [
{
slug: "backend-skeleton",
title: "Backend Skeleton",
summary:
"저장소·Redis·JPA·MongoDB 같은 기술을 붙일 때 애플리케이션 경계를 다시 만들지 않도록 공통 계약을 정리하는 프로젝트입니다.",
thesis:
"기술별 기능을 많이 제공하는 것보다 교체 가능한 경계와 검증 가능한 계약을 먼저 고정합니다.",
stage: "DESIGN",
currentGoal: "Filesystem과 Object Storage를 하나의 StoragePort로 통합",
nextStep: "MinIO Adapter와 공통 계약 테스트 연결",
topics: ["Backend Architecture", "JPA", "Redis", "Storage"],
decisions: [
{
id: "storage-port-unification",
status: "ADOPTED",
date: "2026.08.10",
title: "파일 저장 계약을 하나로 통합합니다",
summary:
"저장 기술이 달라도 애플리케이션이 요구하는 의미는 같습니다.\n그래서 호출 계약을 기술별로 나누지 않습니다.",
statement:
"Filesystem과 Object Storage는 하나의 StoragePort와 서로 다른 Adapter로 구성합니다.",
rationale:
"애플리케이션이 요구하는 저장 의미는 같고 실제 저장 방식만 달라지므로 호출 계약을 기술별로 나누지 않습니다.",
consequences: [
"로컬과 MinIO 구현이 같은 계약 테스트를 통과해야 합니다.",
"스토리지별 설정과 전송 최적화는 Adapter 내부에 남깁니다.",
],
evidence: [
{
title: "파일 저장소 계약을 하나로 통합했습니다",
path: "/projects/backend-skeleton/activity#storage-contract",
},
{
title: "Redis Adapter가 도메인 TTL 정책을 소유하지 않는 이유",
path: "/cases/redis-adapter-ttl-boundary",
},
],
},
{
id: "feed-pagination-boundary",
status: "ADOPTED",
date: "2026.08.11",
title: "목록 페이징과 컬렉션 로딩을 분리합니다",
summary: "컬렉션 Fetch Join 이 페이지 경계를 지우므로 부모 페이징과 컬렉션 로딩을 나눕니다.",
statement:
"피드 목록은 부모를 먼저 페이징하고 현재 페이지의 연관 컬렉션만 별도 조회합니다.",
rationale:
"컬렉션 Fetch Join이 DB LIMIT를 제거하고 현재 페이지 밖의 데이터까지 읽는 문제를 피하기 위한 결정입니다.",
consequences: [
"목록 조회는 한 번의 SQL로 끝나지 않습니다.",
"쿼리 수뿐 아니라 조인 행 수와 로드 엔티티 수도 함께 측정합니다.",
],
evidence: [
{
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
{
title: "JPA 목록 조회에서 Fetch 전략을 선택하는 기준",
path: "/references/jpa-list-fetch-strategy",
},
],
},
],
activity: [
{
id: "fetch-join-case-published",
date: "2026.08.11",
dateTime: "2026-08-11T14:10:00+09:00",
type: "PUBLICATION",
title: "Fetch Join과 페이징 Case를 게시했습니다",
summary: "20건을 요청했지만 DB LIMIT 없이 전체 컬렉션이 로드되는 과정을 측정했습니다.",
path: "/cases/collection-fetch-join-pagination",
recordPath: "/cases/collection-fetch-join-pagination",
},
{
id: "storage-contract",
date: "2026.08.10",
dateTime: "2026-08-10T18:40:00+09:00",
type: "PROJECT UPDATE",
title: "파일 저장소 계약을 하나로 통합했습니다",
summary: "Filesystem과 Object Storage를 같은 Port 뒤의 Adapter로 정리했습니다.",
path: "/projects/backend-skeleton/activity#storage-contract",
},
{
id: "redis-case-published",
date: "2026.08.07",
dateTime: "2026-08-07T16:30:00+09:00",
type: "PUBLICATION",
title: "Redis Adapter 책임 경계 Case를 게시했습니다",
summary: "만료 정책과 Redis 명령 실행 책임을 분리해 Adapter 교체 범위를 고정했습니다.",
path: "/cases/redis-adapter-ttl-boundary",
recordPath: "/cases/redis-adapter-ttl-boundary",
},
],
},
{
slug: "auth-lab",
title: "Auth Lab",
summary:
"브라우저·Edge·Spring 사이에서 Token과 Session의 책임을 나누고 인증 경계를 검증하는 프로젝트입니다.",
thesis:
"인증 방식을 이름으로 비교하지 않고 Code 교환, Token 보관, 요청 검증의 실제 주체를 기준으로 나눕니다.",
stage: "VALIDATION",
currentGoal: "oauth2-proxy 뒤의 Spring 신뢰 경계 결정",
nextStep: "JWT 재검증안과 신뢰 헤더안의 위협 모델 비교",
topics: ["Authentication", "OAuth 2.0", "OIDC", "Keycloak"],
decisions: [
{
id: "browser-secret-boundary",
status: "ADOPTED",
date: "2026.08.09",
title: "브라우저 클라이언트에는 Client Secret을 두지 않습니다",
summary: "브라우저에 전달된 값은 사용자가 볼 수 있어 비밀로 클라이언트를 증명할 수 없습니다.",
statement: "SPA는 public client와 Authorization Code Flow + PKCE로 구성합니다.",
rationale:
"브라우저에 전달된 값은 사용자가 확인할 수 있으므로 Client Secret으로 클라이언트를 증명할 수 없습니다.",
consequences: [
"Code 교환에는 요청별 code_verifier가 필요합니다.",
"state와 nonce는 PKCE와 다른 검증 책임으로 유지합니다.",
],
evidence: [
{
title: "Authorization Code Flow에서 state와 nonce의 경계",
path: "/references/state-and-nonce-boundary",
},
],
},
],
activity: [
{
id: "state-nonce-reference",
date: "2026.08.09",
dateTime: "2026-08-09T21:20:00+09:00",
type: "PUBLICATION",
title: "state와 nonce의 경계 Reference를 게시했습니다",
summary: "요청 위조 방지와 ID Token 재사용 방지를 서로 다른 검증값으로 정리했습니다.",
path: "/references/state-and-nonce-boundary",
recordPath: "/references/state-and-nonce-boundary",
},
{
id: "edge-trust-boundary",
date: "2026.08.08",
dateTime: "2026-08-08T19:05:00+09:00",
type: "QUESTION",
title: "oauth2-proxy 뒤에서 토큰을 다시 검증할 것인가",
summary: "Edge 인증 이후 Spring이 신뢰할 경계를 OpenQuestion으로 분리했습니다.",
path: "/projects/auth-lab/activity#edge-trust-boundary",
recordPath: "/questions/validate-edge-token-again",
},
],
},
];
export const releases: ReadonlyArray<Release> = [
{
version: "0.1.0",
path: "/releases/0.1.0",
title: "TechLog Public·Studio 경계를 확정했습니다",
summary:
"Public은 불변 게시 Snapshot을 읽고, Studio는 API 계약을 따르는 세션 전용 프론트엔드 시뮬레이션으로 분리했습니다.",
publishedAt: "2026-08-06T22:15:00+09:00",
publishedLabel: "2026.08.06",
changes: [
"Public은 게시 이벤트 시점의 불변 Snapshot을 읽고 탐색하도록 분리했습니다.",
"Studio는 API 계약을 따르는 세션 전용 프론트엔드 시뮬레이션으로 구성했습니다.",
"작업본 저장은 Public을 바꾸지 않으며 게시·재게시·게시 취소는 Studio 세션 안에서만 상태를 갱신합니다.",
],
reasons: [
"작성 중인 내용과 독자가 읽는 문서를 같은 상태로 다루면 저장 실수와 미완성 내용이 외부에 노출될 수 있습니다.",
"공개 문서는 관계와 경로까지 함께 검증된 시점의 상태를 유지해야 합니다.",
],
impacts: [
"로그인·데이터베이스·서버 저장 없이 Case·Reference·Question의 작성 흐름을 확인할 수 있습니다.",
"새로고침이나 Public 이동 뒤에는 Studio의 세션 Mock 상태가 초기화됩니다.",
"Studio의 Mock 게시·게시 취소는 기존 Public 콘텐츠와 검색 결과를 바꾸지 않습니다.",
],
related: [
{ title: "TechLog 홈", path: "/" },
{ title: "공개 기록 탐색", path: "/explore" },
{
title: "컬렉션 Fetch Join과 페이징은 왜 충돌하는가",
path: "/cases/collection-fetch-join-pagination",
},
],
},
];
export const profile: Profile = {
name: "동현",
introduction: "문제를 재현하고 검증해 운영 가능한 설계로 연결합니다.",
principles: [
{
title: "관찰한 사실과 판단을 나눕니다",
description: "측정값, 문서 근거, 아직 확인하지 못한 가정을 같은 문장에 섞지 않습니다.",
},
{
title: "결론보다 경계를 남깁니다",
description: "어떤 조건에서 선택했고 어디까지 적용할 수 있는지 함께 기록합니다.",
},
{
title: "프로젝트 맥락으로 다시 연결합니다",
description: "Case와 Reference, Question, Decision이 따로 흩어지지 않게 실제 작업과 연결합니다.",
},
],
currentProjectSlugs: ["backend-skeleton", "auth-lab"],
topics: ["Backend Architecture", "JPA", "Authentication", "Redis"],
};