feat: 환경 구성(SETUP) 기록 종류를 더한다

다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시
하려면 무엇부터 하는가다. Case 의 environment 는 평문 한 칸이라 명령이
들어가지 않고, 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.

프로젝트는 필수, 주제는 선택으로 둔다. 주제 없는 셋업이 그 프로젝트의 공통
구성이고, 주제를 붙이면 그 주제의 구성이다 — 스키마를 나누지 않고 두 범위를
같은 종류로 받는다.

버전만 본문 밖에 둔다(pinnedVersions). 이 절차가 어느 버전 위에서 성립했는지는
그 기록의 유효 범위이고, 목록과 머리말이 본문을 열지 않고 보여 줘야 한다.
나머지 셋(실행 절차·구성 값·확인 방법)은 명령과 표를 담아야 하므로 본문이다.

이름은 SETUP 이다. ENVIRONMENT 가 영어로는 자연스럽지만 case_detail.environment
와 겹친다 — 이 저장소가 열네 번 밟은 실패가 「종류를 손으로 나열한 곳을
빠뜨린다」이고 그걸 찾는 수단이 grep 이다.

손으로 나열해 두었던 자리를 이번에 표로 바꿨다. publicPath 의 삼항 사슬은
마지막 else 가 「나머지 전부」여서 새 종류의 주소가 조용히 /questions/… 가
됐고, document-editor 의 칸 경로도 같은 모양이었다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
This commit is contained in:
DongHyeonka
2026-09-09 14:12:44 +09:00
co-authored by Claude Opus 5
parent 3374f286be
commit 3af9be9e09
45 changed files with 2195 additions and 65 deletions
@@ -0,0 +1,278 @@
# 환경 구성(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` 테이블을 공유하므로 새 테이블은 하나뿐이다.
```sql
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 를
받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.
## 남은 문제
- `tech-log-design-package` 가 지금 로컬에 없다(`/home/donghyeon/workspace/tech-log-design-package`
없음). 계약을 고치려면 이 저장소를 먼저 되살려야 한다. 백엔드의
`src/config/openapi/` 에 vendored 사본이 있으므로 내용은 남아 있다.