Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
17 KiB
환경 구성(SETUP) 문서 종류 추가
작성일 2026-09-09 · 대상 저장소 tech-log-design-package · tech-log-backend · tech-log-frontend
왜
이 저장소의 다섯 종류는 전부 끝난 일을 남긴다. Case 는 무엇을 관찰했는지, Concept 은 무엇이 어떻게 도는지, Reference 는 무엇을 기준으로 판단하는지를 남긴다.
없는 것은 읽는 사람이 자기 손으로 다시 해 보려면 무엇부터 하는가다. Keycloak 네 패턴을 읽고 "그래서 이걸 어떻게 띄우지"에 답하는 자리가 지금은 없다.
Case 에 environment(「검증 환경」)가 이미 있지만 이 자리를 대신하지 못한다. 두 가지 이유다.
- 평문 한 칸이다.
docker compose up, realm import 명령, 포트 표가 들어가지 않는다. Markdown 을 거치지 않고 그대로 그려지는 칸이다. - 범위 표시지 절차가 아니다. 「검증 환경」은 이 결과가 어디까지 유효한가를 적는 자리다. 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.
그래서 종류를 하나 더한다. Case 의 environment 는 그대로 둔다 — 둘은 다른 질문에 답한다.
무엇이 아닌가
- Case 의 「검증 환경」·「재현 조건」을 없애지 않는다. 범위 표시는 그 기록의 것이다.
- 전용 관계 칸을 만들지 않는다. 「이 환경에서 측정했다」는 기존
relations의reason으로 적는다. 칸을 새로 만들면 관계에도 있고 전용 칸에도 있는 두 진실이 생긴다. - 셋업이 실제로 도는지 CI 에서 돌려 보지 않는다. 실행 검증은 별건이다. 이 종류가 하는 일은 절차를 한 곳에 두는 것까지다.
- 절 이름을 스키마로 강제하지 않는다. 실행 절차 · 구성 값 · 확인 방법은 권장 뼈대이지
필수 칸이 아니다. 프로젝트마다 셋업의 모양이 다르다. 대신 Studio 의 새 문서 폼이 그
뼈대를
bodyMarkdown초기값으로 넣어 준다. - 기존 문서를 자동으로 고치지 않는다. 이미 쓴 Case 의 본문은 손대지 않는다.
이름
| 자리 | 값 | 이유 |
|---|---|---|
| 계약 enum | SETUP |
case_detail.environment 와 겹치지 않게 |
| 화면 라벨 | 「환경 구성」 | DOCUMENT_KIND_LABELS 의 네 글자 결 |
| 공개 경로 | /setups/{slug} |
|
| 목록 경로 | /explore/setups |
|
| 지식 상태 | SETTLED |
정리한 것. 확인한 것(Case·Concept)도, 열린 것(Question)도 아니다 |
ENVIRONMENT 가 영어로는 자연스럽지만 쓰지 않는다. 이 저장소가 열네 번 밟은 실패는
「종류를 손으로 나열한 곳을 빠뜨린다」이고, 그걸 찾는 수단이 grep 이다. 필드 이름
environment 와 종류 이름 ENVIRONMENT 가 같은 저장소에 있으면 그 수단이 무뎌진다.
붙는 자리
| 붙는 곳 | 규칙 | 왜 |
|---|---|---|
| 프로젝트 | 필수 — 없으면 게시 오류 | 셋업은 언제나 어떤 프로젝트의 셋업이다. PROJECT_DECISION 과 같은 규칙 |
| 주제 | 선택 | 이 선택이 두 범위를 다 준다(아래) |
| 관계 | 자유 | 「이 환경에서 측정했다」 |
주제를 선택으로 두는 것이 요구사항을 그대로 만족한다.
주제 없음 → 그 프로젝트의 공통 셋업 (프로젝트마다 하나)
주제 있음 → 그 프로젝트 · 그 주제의 셋업 (주제마다 다를 때)
한 프로젝트 안에서 주제별로 다른 구성을 쓰면 주제를 붙인 셋업을 여러 개 두고, 구성이 하나면 주제 없는 셋업 하나만 둔다. 스키마를 나누지 않고 같은 종류로 둘 다 된다.
문서의 모양
base (모든 종류 공유)
kind · title · slug · summary · topicId · projectId · relations · tags
SETUP 이 더하는 것
pinnedVersions : [{ name, version }] 구조화. 예) { "Keycloak", "26.7.0" }
머리말 아래에 표로 그린다. 비어 있으면 그리지 않는다
bodyMarkdown : 자유 마크다운. Case·Concept 와 같은 파서를 쓴다 —
`##` 소제목이 목차가 되고 `:::evidence key="…"` 로 도식을 끼운다
왜 버전만 구조화하나
넷 중 셋(실행 절차 · 구성 값 · 확인 방법)은 명령과 코드블록과 표를 담아야 한다. 평문 칸에 들어가지 않고, Markdown 칸을 넷으로 쪼개면 같은 렌더러를 네 번 붙이게 된다.
버전만 다르다. 버전은 이 기록의 유효 범위를 정하는 값이고, 목록과 머리말에서 본문을
열지 않고도 보여야 한다. Concept 의 basisVersion 이 같은 이유로 따로 있다. 다른 점은
셋업은 한 줄이 아니라 여럿이라는 것뿐이다 — Keycloak · Spring Boot · PostgreSQL 이 각각.
reference_detail.rules · examples 가 이미 jsonb 배열 + jsonb_typeof = 'array' CHECK
로 되어 있으므로 같은 모양을 쓴다. 자식 테이블을 만들지 않는 이유는 이 값으로 검색하거나
조인하지 않고 표로만 그리기 때문이다.
계약 변경 — design package 가 소유
studio-v1.yaml (작성)
RecordKindenum 에SETUP추가SetupInput신설 —WorkingCopyInputBase+{ kind, bodyMarkdown, pinnedVersions }SetupWorkingCopy(응답형) 신설 — 같은 모양에id · version · updatedAt- 작업본 union(
WorkingCopyInput/WorkingCopy)에 분기 추가 PinnedVersion스키마 신설 —{ name: string(1..60), version: string(1..40) }
public-v1.yaml (공개)
SetupDetailResponse신설setup: { title, summary, pinnedVersions[], content, contentFormat, contentFormatVersion, bodyAssets, primaryTopic?, primaryProject, tags, publishedAt, updatedAt }
KnowledgeListItem.type에SETUP추가LatestEntry.entryType에SETUP추가exploreKnowledge의type질의 파라미터에SETUP추가GET /setups/{slug}경로 추가
studio-management-v1.yaml
- 종류를 나열하는 자리에
SETUP추가
백엔드
마이그레이션 V17
V11(개념 추가)과 같은 모양이다. document 테이블을 공유하므로 새 테이블은 하나뿐이다.
CREATE TABLE setup_detail (
document_id uuid PRIMARY KEY,
document_type varchar(20) NOT NULL DEFAULT 'SETUP' CHECK (document_type = 'SETUP'),
pinned_versions jsonb NOT NULL DEFAULT '[]'::jsonb
CHECK (jsonb_typeof(pinned_versions) = 'array'),
CONSTRAINT fk_setup_detail_document
FOREIGN KEY (document_id, document_type) REFERENCES document(id, document_type)
ON DELETE CASCADE
);
허용 목록을 고쳐야 하는 CHECK 제약 아홉 개. 하나라도 빠뜨리면 그 단계에서 제약 위반으로 막히고, 막힌 이유는 화면에 드러나지 않는다.
| 테이블 | 제약 | 더할 값 |
|---|---|---|
document |
document_document_type_check |
'SETUP' |
studio_relation |
studio_relation_source_kind_check |
'SETUP' |
studio_validation |
studio_validation_source_kind_check |
'SETUP' |
studio_preview |
studio_preview_source_kind_check |
'SETUP' |
publication |
publication_source_kind_check |
'SETUP' |
publication_event |
publication_event_source_kind_check |
'SETUP' |
public_resource_projection |
..._resource_type_check |
'SETUP' |
record_variant |
record_variant_record_kind_check |
'SETUP' |
project_activity |
project_activity_activity_type_check |
'SETUP_PUBLISHED' |
record_variant 가 이 표에서 가장 중요하다. V11 은 여덟 개를 고쳤는데 record_variant
는 그때 없었다(V14 에서 생겼다). V14 의 주석이 그 사정을 이렇게 적어 두었다 — "개념을 더할
때 이런 목록을 빠뜨려 실제로 화면이 깨진 적이 있다." 같은 자리가 이번에 다시 온다.
코드
컴파일러가 잡아 주는 곳과 아닌 곳이 갈린다. 아래쪽이 사고 지점이다.
잡힘 — RecordKind enum 을 받는 sealed switch 식
| 파일 | 할 일 |
|---|---|
RecordKind |
enum 에 SETUP |
PublicPaths |
SETUP → /setups/{slug} |
JdbcPublicationWriterAdapter |
documentBacked · unpublish switch 에 SETUP |
안 잡힘 — 문자열 switch · SQL 리터럴 · 분기
| 파일 | 할 일 | 빠뜨리면 |
|---|---|---|
PublicSql.pathOf |
case "SETUP" -> "/setups/" + slug |
게시는 되고 링크만 죽는다. default -> null 이라 조용하다. 결정 404 가 정확히 여기서 났다 |
PublicSql.LATEST_ENTRY_TYPES |
'SETUP' 추가 |
홈·주제의 최근 기록에서 빠진다 |
StudioDocumentSql |
SETUP 조회·저장 SQL | |
JdbcWorkingCopyRepositoryAdapter + SetupWorkingCopyStore(신규) |
작업본 읽기·쓰기 | |
JdbcPublicDocumentQueryAdapter |
/setups/{slug} 상세 조회 |
|
JdbcCatalogQueryAdapter |
RELATION 후보에 셋업 포함 | Case 가 셋업을 가리킬 수 없다 |
StudioDocumentValidator |
프로젝트 없으면 오류, bodyMarkdown 비면 오류 |
|
StudioRequestMapper / StudioResponseMapper |
SETUP 분기 | |
PublicRenderModelFactory |
즉시 미리보기를 Case 와 같은 파서로 |
프론트엔드
잡힘 — Record<RecordKind, _> 표 세 개. 빠뜨리면 컴파일이 막힌다.
DOCUMENT_KIND_LABELS SETUP: "환경 구성"
DOCUMENT_KIND_STATES SETUP: "SETTLED"
EXPLORE_KIND_PATHS SETUP: "/explore/setups"
새로 만드는 것
| 파일 | 할 일 |
|---|---|
| 계약 codegen | npm run generate:tech-log-contract |
setup-fields.tsx (신규) |
편집기 — 버전 표(행 추가·삭제) + 본문 마크다운. Case 의 Asset Picker 재사용 |
setup-document-page.tsx (신규) |
공개 상세 |
public-record-renderer.tsx |
셋업 렌더 — 제목·요약·버전 표·본문·목차·관계 |
| 라우트 | TECH_LOG_SETUP = /setups/:slug, explore-kind-page 에 setups |
document-editor-controller.tsx |
SETUP 분기와 SETUP_FIELD_PATHS |
new-document-form.tsx |
종류 선택지 + 뼈대 초기값(실행 절차 / 구성 값 / 확인 방법 세 절) |
explore-filter-form.tsx |
유형 선택지에 「환경 구성」 |
public-document-header.tsx |
kindLabels 에 SETUP |
home-page.tsx |
latestTypeLabels 에 SETUP: "환경 구성" |
| 모의 어댑터 | 픽스처에 셋업 문서 추가 |
안 잡힘
| 파일 | 할 일 |
|---|---|
validate-working-copy.ts:71 |
stringFields 에 kind === "SETUP" ? ["bodyMarkdown"] : [] |
| 같은 파일 | pinnedVersions 배열 검사(checkArray) 추가 |
주제 없는 셋업의 머리말
주제가 없는 문서는 이번이 처음이다. 개념이 프로젝트 없는 첫 종류였던 것과 같은 자리다.
지금 상태를 확인해 보면 렌더러가 두 갈래다.
| 자리 | 지금 | 할 일 |
|---|---|---|
public-record-renderer.tsx:83 |
model.topic.label ? 로 이미 막는다 |
그대로 |
public-record-renderer.tsx:178, :269 |
<TargetLink target={model.topic} /> 를 조건 없이 그린다 |
같은 방식으로 막는다 |
public-document-header.tsx:40-51 |
topic 객체를 늘 만든다. publicPath 만 topicSlug 없을 때 null |
label 이 비면 마디를 뺄 수 있도록 |
주제가 없으면 링크 없는 빈 마디가 남는다. 다른 종류는 주제가 늘 있으므로 이 변경으로 화면이 달라지지 않는다 — 회귀 테스트로 확인한다.
가드 — 셋
손으로 나열한 곳마다 하나씩. 전부 계약을 읽어 대조하는 방식이다. 목록을 또 손으로 적으면 같은 실패가 가드 안으로 옮겨 갈 뿐이다.
PublicSql.pathOf전수 대조 — vendoredstudio-v1.yaml의RecordKindenum 을 읽어 모든 값에 대해pathOf가 null 이 아닌 경로를 내는지 본다. 문자열 switch 의default -> null을 막는 유일한 수단이다.validate-working-copy.ts필드 대조 — 계약 스키마의 종류별 문자열 필드를 파싱해stringFields와 집합이 같은지 본다.- DB CHECK 제약 대조 (통합 테스트) — 위 표의 제약 아홉 개가 허용하는 값 집합이 계약
enum 과 일치하는지 본다.
information_schema에서 CHECK 절을 읽어 대조한다. 다음에 종류를 더할 때record_variant같은 새 제약이 생겨도 이 가드가 그 자리를 알려 준다.
각 가드는 되돌려서 실패하는 것을 보고 나서 센다. 되돌리지 않은 가드는 가드가 아니다.
테스트
- 계약: design package 검증기 3종 (
check-openapi/check-consistency/check-contract-parity) - 백엔드
PublicSitePersistenceIntegrationTest— 셋업 게시본이 홈·주제 최근 기록에 나온다- 공개 상세 통합 테스트 —
/setups/{slug}가 본문·버전 표·관계를 돌려준다 - 검증기 단위 테스트 — 프로젝트 없는 SETUP 은 게시가 막힌다(오류), 주제 없음은 조용하다
- 가드 1·3
- 프론트엔드
public-setup-mapping.test.ts— 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣어 본문·버전 표·관계가 채워지는지 본다- 화면 테스트 — 셋업 상세가 목차·본문·버전 표를 그리고, 주제 없는 머리말이 그 마디를 뺀다
- 탐색 필터 테스트 —
type=SETUP으로 걸러진다 route-contract.test.ts— 새 라우트 등록- 가드 2
- 다섯 게이트:
check:types·lint·test:unit·test:component·test:tech-log
반영 순서
- design package 계약 → 검증기 → 커밋
- 백엔드: vendored 계약 +
MANIFEST.sha256, V17, 코드, 가드 1·3, 테스트 → 커밋 - 프론트: codegen, 편집기·렌더러·라우트, 가드 2, 테스트 → 다섯 게이트 → 커밋
- 백엔드 이미지 → 임포트 → 롤아웃 (마이그레이션이 먼저 적용되어야 한다)
- 프론트 이미지 → 롤아웃
- 운영에서 셋업 문서를 하나 써서 게시 → 홈·탐색·상세·Case 에서 건 관계를 눈으로 확인
백엔드를 먼저 올린다. 프론트가 먼저 올라가면 /setups/{slug} 를 부르는 화면이 404 를
받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.
구현하면서 이 설계가 틀린 것으로 드러난 곳
설계는 「종류 enum 이 하나」라고 가정했다. 아니었다.
계약에 종류를 나열하는 자리가 셋이다. RecordKind 말고도 CatalogEntry.kind(관계 후보
목록)와 ResolvedRelation.targetKind(응답의 관계 항목)가 각각 따로 나열한다. 둘을 빠뜨리면
Case 가 셋업을 관계로 걸 수 없고, 걸어도 응답에서 종류가 튕긴다. 백엔드의 계약 union Jackson
테스트가 앞의 것을, 프론트 타입 검사가 뒤의 것을 잡았다.
삭제 경로가 계약 밖에 있었다. DeletableDocumentKind 는 계약이 아니라 손으로 쓴 union
이고, 종류마다 별도 관리 operation(deleteCaseDraft …)을 요구한다. deleteSetupDraft 를
계약·기여 목록·컨트롤러 셋 다에 더해야 했다.
프론트에도 손으로 쓴 RecordKind 가 둘 더 있다. application/ports/public-content-queries.ts
와 adapters/static/public-content.ts 가 각자 문자열 union 을 갖고 있다. 계약의 것과 같은
집합이어야 하는데 대조하는 것이 없다.
주제 없는 머리말은 한 곳만 고치면 됐다. 설계는 렌더러 세 자리를 다 막으라고 적었으나,
주제가 빌 수 있는 종류는 SETUP 뿐이고 그것은 자기 렌더러(SetupDocument)를 갖는다. 개념·Case
의 머리말은 주제가 늘 있으므로 손대지 않았다 — 고쳐도 화면이 달라지지 않고, 스냅샷만 흔든다.
공개 조회의 행 매핑은 나열을 뒤집었다. isCase || isConcept ? … : …(본문을 가진 종류를
나열)를 isReference ? … : …(다른 하나를 지목)로 바꿨다. 규칙·적용·신선도를 갖는 것은
Reference 뿐이므로 종류가 늘어도 이 판단은 그대로다.
SetupDetailResponse.relations 는 자기 타입을 얻지 못한다. 생성기가 구조가 같은 inline
스키마를 합쳐 ConceptDetailResponseRelations 로 낸다. 이름을 다르게 만들려고 계약에 없는
차이를 넣지 않았다.
남은 문제
tech-log-design-package는 되살리지 않았다. 계약 원본은 이제 프론트의 vendored yaml 이고, 백엔드src/config/openapi/와MANIFEST.sha256이 그 사본과 해시를 들고 있다. 타입 생성기는TECH_LOG_DESIGN_PACKAGE로 임시 git 저장소를 가리켜 돌린다.- 이번 변경 전부터 실패하던 것: 프론트
tests/unit/ci-workflow-generation.test.ts3건, 백엔드 통합caseDetailReadsTheOriginalTableNotTheProjectionPayload(환경 요약이 빈 목록),assetsRoundTripAndReportTheirUsage(에셋 경로가/media/…가 아니라/api/v1/public/media/…). 이전 커밋의 worktree 에서 같은 실패를 확인했다.