Files
tech-log-frontend/docs/superpowers/specs/2026-09-09-setup-record-kind-design.md
T

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 (작성)

  • RecordKind enum 에 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 이 비면 마디를 뺄 수 있도록

주제가 없으면 링크 없는 빈 마디가 남는다. 다른 종류는 주제가 늘 있으므로 이 변경으로 화면이 달라지지 않는다 — 회귀 테스트로 확인한다.

가드 — 셋

손으로 나열한 곳마다 하나씩. 전부 계약을 읽어 대조하는 방식이다. 목록을 또 손으로 적으면 같은 실패가 가드 안으로 옮겨 갈 뿐이다.

  1. PublicSql.pathOf 전수 대조 — vendored studio-v1.yaml 의 RecordKind enum 을 읽어 모든 값에 대해 pathOf 가 null 이 아닌 경로를 내는지 본다. 문자열 switch 의 default -> null 을 막는 유일한 수단이다.
  2. validate-working-copy.ts 필드 대조 — 계약 스키마의 종류별 문자열 필드를 파싱해 stringFields 와 집합이 같은지 본다.
  3. 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

반영 순서

  1. design package 계약 → 검증기 → 커밋
  2. 백엔드: vendored 계약 + MANIFEST.sha256, V17, 코드, 가드 1·3, 테스트 → 커밋
  3. 프론트: codegen, 편집기·렌더러·라우트, 가드 2, 테스트 → 다섯 게이트 → 커밋
  4. 백엔드 이미지 → 임포트 → 롤아웃 (마이그레이션이 먼저 적용되어야 한다)
  5. 프론트 이미지 → 롤아웃
  6. 운영에서 셋업 문서를 하나 써서 게시 → 홈·탐색·상세·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.ts 3건, 백엔드 통합 caseDetailReadsTheOriginalTableNotTheProjectionPayload(환경 요약이 빈 목록), assetsRoundTripAndReportTheirUsage(에셋 경로가 /media/… 가 아니라 /api/v1/public/media/…). 이전 커밋의 worktree 에서 같은 실패를 확인했다.