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,774 @@
# 환경 구성(SETUP) 기록 종류 구현 계획
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Tech Log 에 여섯 번째 기록 종류 `SETUP`(「환경 구성」)을 더해, 읽는 사람이 그 결과를 자기 손으로 재현할 절차를 한 곳에 두게 한다.
**Architecture:** `document` 테이블을 공유하는 CONCEPT 방식을 그대로 따른다. 새 테이블은 `setup_detail` 하나(`pinned_versions jsonb`). 계약 → 백엔드 → 프론트 순서로 가고, 손으로 나열한 세 자리(`PublicSql.pathOf` · `validate-working-copy.ts` · DB CHECK 제약)마다 계약을 읽어 대조하는 가드를 붙인다.
**Tech Stack:** OpenAPI 3.1 · Spring Boot 4 / JdbcClient / Flyway · React 19 / openapi-typescript / Vitest
**Spec:** [docs/superpowers/specs/2026-09-09-setup-record-kind-design.md](../specs/2026-09-09-setup-record-kind-design.md)
## Global Constraints
- **계약 원본은 vendored yaml 이다.** `tech-log-design-package` 는 되살리지 않는다. 프론트의 `src/features/tech-log/contracts/{studio,public,management}/*.openapi.yaml` 과 백엔드의 `src/config/openapi/{studio-v1,public-v1,studio-management-v1}.yaml` 은 **바이트 단위로 같아야 한다**(현재 같다). 한쪽을 고치면 다른 쪽에 복사한다.
- **enum 값은 `SETUP`.** 화면 라벨은 「환경 구성」. 공개 경로 `/setups/{slug}`, 목록 경로 `/explore/setups`.
- **프로젝트 필수 · 주제 선택.** 프로젝트 없이 게시하면 오류. 주제 없음은 조용하다.
- **브랜치를 따로 파지 않는다.** 각 저장소의 `main` 에서 작업한다.
- **가드는 되돌려서 실패하는 것을 보고 나서 센다.**
- 프론트 다섯 게이트: `check:types` · `lint` · `test:unit` · `test:component` · `test:tech-log`
- vitest 는 npm 환경 변수 누출 때문에 다음으로 돌린다:
`env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') ./node_modules/.bin/vitest run <경로>`
- 백엔드 Gradle 은 `src/gradlew`. `-Werror` · ErrorProne · Checkstyle(`NeedBraces`, switch 는 default 필요)이 걸려 있다.
**경로 약어**
```
FE = /home/donghyeon/workspace/desktop-server-git/tech-log-frontend
BE = /home/donghyeon/workspace/desktop-server-git/tech-log-backend
PJ = BE/src/adapter/outbound/persistence-jpa/src/main
SQ = PJ/resources/db/migration/postgresql
PS = PJ/java/dev/caskeleton/adapter/outbound/persistence/techlog
```
---
### Task 1: studio 계약에 SETUP 을 더한다
**Files:**
- Modify: `FE/src/features/tech-log/contracts/studio/studio-api.openapi.yaml`
**Interfaces:**
- Produces: `RecordKind` enum 값 `SETUP`; 스키마 `PinnedVersion` · `SetupInput` · `SetupWorkingCopy` · `SetupPublicRenderModel`; 세 union(`WorkingCopyInput` · `WorkingCopy` · `PublicRenderModel`)의 `SETUP` 분기
- [ ] **Step 1: `RecordKind` enum 에 `SETUP` 추가 (840행)**
```yaml
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT, SETUP]
```
- [ ] **Step 2: `PinnedVersion` 스키마 신설 — `ConceptInput`(964행) 바로 앞**
```yaml
PinnedVersion:
type: object
additionalProperties: false
required: [name, version]
description: |
이 셋업이 어느 버전을 기준으로 쓰였는지. "Keycloak" / "26.7.0" 처럼 이름과 버전을
나눠 담는다. 목록과 머리말이 본문을 열지 않고 보여 주는 값이라 본문에 두지 않는다.
properties:
name: { type: string, minLength: 1, maxLength: 60 }
version: { type: string, minLength: 1, maxLength: 40 }
```
- [ ] **Step 3: `SetupInput` 신설 — `ConceptInput` 블록 바로 뒤**
```yaml
SetupInput:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/WorkingCopyInputBase" }
- type: object
required: [kind, bodyMarkdown, pinnedVersions]
properties:
kind: { type: string, enum: [SETUP] }
bodyMarkdown:
type: string
maxLength: 100000
description: |
Markdown 원문. 실행 절차·구성 값·확인 방법을 `##` 절로 적는다. 절 이름을
강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. Asset은
`:::evidence key="<assetKey>"` directive로 참조한다.
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
```
- [ ] **Step 4: `WorkingCopyInput` union(1035행 부근)에 분기 추가**
```yaml
- { $ref: "#/components/schemas/SetupInput" }
```
그리고 `mapping:` 아래에
```yaml
SETUP: "#/components/schemas/SetupInput"
```
- [ ] **Step 5: `SetupWorkingCopy` 신설 — `ConceptWorkingCopy`(1093행) 블록 뒤**
```yaml
SetupWorkingCopy:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/WorkingCopyBase" }
- type: object
required: [kind, bodyMarkdown, pinnedVersions]
properties:
kind: { type: string, enum: [SETUP] }
bodyMarkdown: { type: string, maxLength: 100000 }
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
```
- [ ] **Step 6: `WorkingCopy` union(1145행 부근)에 분기 추가 — 설명 블록의 `| ConceptWorkingCopy` 줄 뒤에 `| SetupWorkingCopy`, `oneOf` 에 `$ref`, `mapping` 에 `SETUP`**
- [ ] **Step 7: `SetupPublicRenderModel` 신설 — `ConceptPublicRenderModel`(1589행) 블록 뒤**
```yaml
SetupPublicRenderModel:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/PublicRenderModelBase" }
- type: object
required: [kind, pinnedVersions, bodyBlocks]
properties:
kind: { type: string, enum: [SETUP] }
pinnedVersions:
type: array
maxItems: 30
items: { $ref: "#/components/schemas/PinnedVersion" }
bodyBlocks: { type: array, maxItems: 10000, items: { $ref: "#/components/schemas/CaseRenderBlock" } }
```
- [ ] **Step 8: `PublicRenderModel` union 에 분기 추가 (`oneOf` + `mapping`)**
- [ ] **Step 9: yaml 이 파싱되는지 확인**
Run:
```bash
cd FE && python3 -c "import yaml,sys; d=yaml.safe_load(open('src/features/tech-log/contracts/studio/studio-api.openapi.yaml')); s=d['components']['schemas']; print(s['RecordKind']['enum']); print([k for k in s if k.startswith('Setup') or k=='PinnedVersion'])"
```
Expected: enum 에 `SETUP` 포함, `['SetupInput', 'SetupWorkingCopy', 'SetupPublicRenderModel', 'PinnedVersion']` 이 모두 나온다
---
### Task 2: public 계약에 SETUP 을 더한다
**Files:**
- Modify: `FE/src/features/tech-log/contracts/public/public-api.openapi.yaml`
**Interfaces:**
- Consumes: Task 1 의 `SETUP` enum 값(이름만 공유, 파일은 독립)
- Produces: `GET /setups/{slug}` · `SetupDetailResponse` · `SetupDetailResponseEnvelope` · `getPublicSetup` operationId
- [ ] **Step 1: 유형 enum 일곱 자리에 `SETUP` 추가**
각 자리의 지금 값과 더한 뒤의 값:
| 줄(현재) | 자리 | `SETUP` 을 넣는 위치 |
|---|---|---|
| 117 | `exploreKnowledge` 의 `type` 질의 | `CONCEPT` 뒤 |
| 532 | 주제 화면 `type` 질의 | `CONCEPT` 뒤 |
| 698 | 검색 `type` 질의 | `CONCEPT` 뒤(PROJECT 앞) |
| 919 | `SearchResultItem.type` | `CONCEPT` 뒤(PROJECT 앞) |
| 1085 | `LatestEntry.entryType` | `CONCEPT` 뒤(PROJECT_ACTIVITY 앞) |
| 1141 | 주제 최근 항목 `type` | `CONCEPT` 뒤 |
| 1920 | `KnowledgeListItem.type` | `CONCEPT` 뒤 |
- [ ] **Step 2: `GET /setups/{slug}` 경로 추가 — `/concepts/{slug}` 블록(363행) 바로 뒤에 같은 모양으로**
```yaml
/setups/{slug}:
get:
operationId: getPublicSetup
tags:
- Setup
parameters:
- name: slug
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetupDetailResponseEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
```
- [ ] **Step 3: `SetupDetailResponse` 신설 — `ConceptDetailResponse`(1422행) 블록 뒤. `basisVersion` 자리에 `pinnedVersions` 를, `primaryTopic` 을 nullable 로**
핵심 차이만 적는다(나머지 필드는 `ConceptDetailResponse` 와 같다):
```yaml
setup:
type: object
required:
- title
- summary
- pinnedVersions
- content
- contentFormat
- contentFormatVersion
- bodyAssets
- tags
- publishedAt
- updatedAt
properties:
pinnedVersions:
type: array
description: 이 셋업이 기준으로 삼은 버전. 비면 화면에 표를 그리지 않는다.
items:
type: object
required: [name, version]
properties:
name: { type: string }
version: { type: string }
```
- [ ] **Step 4: `SetupDetailResponseEnvelope` 신설 — `ConceptDetailResponseEnvelope`(1501행)와 같은 모양, `$ref` 만 `SetupDetailResponse`**
- [ ] **Step 5: 파싱과 경로 확인**
Run:
```bash
cd FE && python3 -c "
import yaml
d=yaml.safe_load(open('src/features/tech-log/contracts/public/public-api.openapi.yaml'))
print('/setups/{slug}' in d['paths'])
print(d['paths']['/setups/{slug}']['get']['operationId'])
print([k for k in d['components']['schemas'] if k.startswith('Setup')])
"
```
Expected: `True` / `getPublicSetup` / `['SetupDetailResponse', 'SetupDetailResponseEnvelope']`
---
### Task 3: management 계약 · vendor 동기화 · 타입 재생성
**Files:**
- Modify: `FE/src/features/tech-log/contracts/management/management-api.openapi.yaml:5975` 부근
- Modify: `BE/src/config/openapi/{studio-v1,public-v1,studio-management-v1}.yaml` (복사)
- Modify: `BE/src/config/openapi/MANIFEST.sha256`
- Modify: `FE/src/features/tech-log/contracts/*/generated.ts`, `*/canonical-source.json`
- [ ] **Step 1: management yaml 의 종류 enum 에 `SETUP` 추가 (5975행 `CONCEPT` 뒤)**
- [ ] **Step 2: 세 yaml 을 백엔드로 복사**
```bash
cd FE/src/features/tech-log/contracts
cp studio/studio-api.openapi.yaml BE/src/config/openapi/studio-v1.yaml
cp public/public-api.openapi.yaml BE/src/config/openapi/public-v1.yaml
cp management/management-api.openapi.yaml BE/src/config/openapi/studio-management-v1.yaml
```
- [ ] **Step 3: 백엔드 `MANIFEST.sha256` 갱신**
```bash
cd BE/src/config/openapi && sha256sum public-v1.yaml studio-v1.yaml studio-management-v1.yaml > MANIFEST.sha256 && cat MANIFEST.sha256
```
(기존 파일의 형식을 먼저 `cat` 해 보고 그 형식에 맞춘다)
- [ ] **Step 4: codegen 이 읽을 임시 canonical 저장소를 만든다**
생성기는 `${TECH_LOG_DESIGN_PACKAGE}/contracts/openapi/*.yaml` 을 읽고 그 디렉터리에서 `git rev-parse` 를 부른다. design package 가 없으므로 vendored yaml 로 임시 저장소를 만든다.
```bash
CANON=/tmp/claude-1000/tech-log-canonical
rm -rf "$CANON" && mkdir -p "$CANON/contracts/openapi"
cd FE/src/features/tech-log/contracts
cp studio/studio-api.openapi.yaml "$CANON/contracts/openapi/studio-v1.yaml"
cp public/public-api.openapi.yaml "$CANON/contracts/openapi/public-v1.yaml"
cp management/management-api.openapi.yaml "$CANON/contracts/openapi/studio-management-v1.yaml"
cd "$CANON" && git init -q && git add -A && git -c user.email=t@t -c user.name=t commit -qm "vendored contracts as canonical"
```
- [ ] **Step 5: 타입 재생성**
```bash
cd FE && TECH_LOG_DESIGN_PACKAGE=/tmp/claude-1000/tech-log-canonical npm run generate:tech-log-contract
```
Expected: 세 계약 모두 재생성, `generated.ts` 에 `SETUP` 이 들어간다
- [ ] **Step 6: drift 게이트 통과 확인**
```bash
cd FE && npm run generate:tech-log-contract -- --check
```
Expected: `tech-log contracts are in sync:` 세 줄
- [ ] **Step 7: 생성물에 SETUP 이 실제로 들어갔는지 확인**
```bash
cd FE && grep -c "SETUP" src/features/tech-log/contracts/studio/generated.ts src/features/tech-log/contracts/public/generated.ts
grep -n "getPublicSetup" src/features/tech-log/contracts/public/generated.ts | head -3
```
Expected: 두 파일 모두 0 보다 크고 `getPublicSetup` 이 나온다
- [ ] **Step 8: 커밋 (두 저장소)**
```bash
cd FE && git add src/features/tech-log/contracts docs/superpowers && git commit -m "feat: 계약에 환경 구성(SETUP) 종류를 더한다"
cd BE && git add src/config/openapi && git commit -m "feat: 계약에 환경 구성(SETUP) 종류를 더한다"
```
---
### Task 4: 마이그레이션 V17 과 DB CHECK 가드
**Files:**
- Create: `SQ/V17__techlog_setup_document.sql`
- Create: `BE/.../SetupSchemaConstraintTest.java` (통합 테스트 — 기존 통합 테스트와 같은 디렉터리)
**Interfaces:**
- Produces: `setup_detail` 테이블; 아홉 제약이 `SETUP` 을 허용
- [ ] **Step 1: 가드 테스트를 먼저 쓴다 — 계약 enum 과 DB CHECK 를 대조**
`information_schema.check_constraints` 에서 CHECK 절 원문을 읽어, 계약 `RecordKind` 의 모든 값이 각 제약에 들어 있는지 본다. 대상 제약 여덟(종류) + 하나(활동 유형):
```java
private static final List<String> KIND_CONSTRAINTS = List.of(
"document_document_type_check",
"studio_relation_source_kind_check",
"studio_validation_source_kind_check",
"studio_preview_source_kind_check",
"publication_source_kind_check",
"publication_event_source_kind_check",
"public_resource_projection_resource_type_check",
"record_variant_record_kind_check");
```
각 제약의 `check_clause` 에 `RecordKind` 의 모든 enum 값 문자열이 들어 있어야 한다. enum 목록은 손으로 적지 않고 `src/config/openapi/studio-v1.yaml` 을 읽어 뽑는다.
- [ ] **Step 2: 테스트를 돌려 실패를 본다**
Run: `cd BE/src && ./gradlew test --tests '*SetupSchemaConstraintTest*'`
Expected: FAIL — `SETUP` 이 여덟 제약 전부에서 빠져 있다
- [ ] **Step 3: V17 을 쓴다**
```sql
-- 환경 구성(SETUP) 문서 종류.
--
-- 다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 "읽는 사람이 자기 손으로 다시 하려면
-- 무엇부터 하는가" 다. Case 의 environment 는 평문 한 칸이라 명령이 들어가지 않고,
-- 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.
--
-- 셋업은 document 의 네 번째 유형이다. body_markdown·slug·primary_topic_id 를 document 가
-- 이미 갖고 있으므로 새 테이블은 pinned_versions 를 담는 setup_detail 뿐이다.
ALTER TABLE document DROP CONSTRAINT document_document_type_check;
ALTER TABLE document ADD CONSTRAINT document_document_type_check
CHECK (document_type IN ('CASE', 'REFERENCE', 'CONCEPT', 'SETUP'));
CREATE TABLE setup_detail (
document_id uuid PRIMARY KEY,
document_type varchar(20) NOT NULL DEFAULT 'SETUP'
CHECK (document_type = 'SETUP'),
-- [{"name":"Keycloak","version":"26.7.0"}, ...]. reference_detail.rules 와 같은 모양이다.
-- 이 값으로 검색하거나 조인하지 않고 표로만 그리므로 자식 테이블을 두지 않는다.
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
);
-- 작성 → 검증 → 미리보기 → 게시 로 이어지는 길에서 종류를 검사하는 자리들.
-- record_variant 는 V11(개념 추가) 때 없던 제약이다. V14 가 만들면서 "개념을 더할 때
-- 이런 목록을 빠뜨려 실제로 화면이 깨진 적이 있다"고 적어 두었다. 같은 자리가 여기다.
ALTER TABLE studio_relation DROP CONSTRAINT studio_relation_source_kind_check;
ALTER TABLE studio_relation ADD CONSTRAINT studio_relation_source_kind_check
CHECK (source_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'PROJECT_DECISION', 'CONCEPT', 'SETUP'));
ALTER TABLE studio_validation DROP CONSTRAINT studio_validation_source_kind_check;
ALTER TABLE studio_validation ADD CONSTRAINT studio_validation_source_kind_check
CHECK (source_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'PROJECT_DECISION', 'CONCEPT', 'SETUP'));
ALTER TABLE studio_preview DROP CONSTRAINT studio_preview_source_kind_check;
ALTER TABLE studio_preview ADD CONSTRAINT studio_preview_source_kind_check
CHECK (source_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'PROJECT_DECISION', 'CONCEPT', 'SETUP'));
ALTER TABLE publication DROP CONSTRAINT publication_source_kind_check;
ALTER TABLE publication ADD CONSTRAINT publication_source_kind_check
CHECK (source_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'PROJECT_DECISION', 'CONCEPT', 'SETUP'));
ALTER TABLE publication_event DROP CONSTRAINT publication_event_source_kind_check;
ALTER TABLE publication_event ADD CONSTRAINT publication_event_source_kind_check
CHECK (source_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'PROJECT_DECISION', 'CONCEPT', 'SETUP'));
ALTER TABLE record_variant DROP CONSTRAINT record_variant_record_kind_check;
ALTER TABLE record_variant ADD CONSTRAINT record_variant_record_kind_check
CHECK (record_kind IN ('CASE', 'REFERENCE', 'QUESTION', 'CONCEPT', 'PROJECT_DECISION', 'SETUP'));
ALTER TABLE public_resource_projection DROP CONSTRAINT public_resource_projection_resource_type_check;
ALTER TABLE public_resource_projection ADD CONSTRAINT public_resource_projection_resource_type_check
CHECK (resource_type IN (
'CASE', 'REFERENCE', 'QUESTION', 'CONCEPT', 'SETUP',
'PROJECT', 'PROJECT_DECISION', 'PROJECT_ACTIVITY', 'RELEASE', 'PROFILE'
));
ALTER TABLE project_activity DROP CONSTRAINT project_activity_activity_type_check;
ALTER TABLE project_activity ADD CONSTRAINT project_activity_activity_type_check
CHECK (activity_type IN (
'PHASE_CHANGED', 'QUESTION_OPENED', 'QUESTION_RESOLVED', 'DECISION_ACCEPTED',
'CASE_PUBLISHED', 'REFERENCE_PUBLISHED', 'CONCEPT_PUBLISHED', 'SETUP_PUBLISHED',
'MILESTONE_REACHED', 'PROJECT_PAUSED', 'PROJECT_RESUMED'
));
```
**제약 이름은 실제 이름으로 맞춘다.** 쓰기 전에 확인:
```bash
cd BE/src && grep -rn "CONSTRAINT.*check\|_check" $SQ/V7__techlog_core.sql | head -20
```
(V7 이 이름을 명시하지 않고 PostgreSQL 이 자동 생성한 것이면 `information_schema` 에서 실제 이름을 먼저 읽어 그 이름을 쓴다)
- [ ] **Step 4: 테스트를 다시 돌려 통과를 본다**
Run: `cd BE/src && ./gradlew test --tests '*SetupSchemaConstraintTest*'`
Expected: PASS
- [ ] **Step 5: 가드를 되돌려 실패를 확인한다**
V17 에서 `record_variant` 제약 갱신 한 줄만 주석 처리 → 테스트 실행 → FAIL 확인 → 주석 해제 → PASS 확인.
- [ ] **Step 6: 커밋**
```bash
cd BE && git add . && git commit -m "feat: 환경 구성 문서를 위한 스키마와 제약 가드"
```
---
### Task 5: `RecordKind` · `PublicPaths` · `PublicSql` 과 경로 가드
**Files:**
- Modify: `BE/.../studio/model/RecordKind.java`
- Modify: `BE/.../PublicPaths.java`
- Modify: `PS/publicsite/PublicSql.java:24-36`(`pathOf`), `:18`(`LATEST_ENTRY_TYPES`)
- Modify: `BE/.../PublicPathsTest.java`
**Interfaces:**
- Consumes: Task 3 의 vendored `studio-v1.yaml`
- Produces: `RecordKind.SETUP`; `PublicPaths.of(SETUP, slug, project)` → `/setups/{slug}`; `PublicSql.pathOf("SETUP", …)` → `/setups/{slug}`
- [ ] **Step 1: 가드 테스트를 먼저 쓴다 — `pathOf` 전수 대조**
`src/config/openapi/studio-v1.yaml` 의 `RecordKind` enum 을 읽어, 모든 값에 대해 `PublicSql.pathOf(value, "s", "p")` 가 null 이 아닌지 본다. 이것이 `default -> null` 을 막는 유일한 수단이다 — 결정 404 가 이 자리에서 났다.
- [ ] **Step 2: 테스트를 돌려 실패를 본다**
Run: `cd BE/src && ./gradlew test --tests '*PublicPathsTest*'`
Expected: FAIL — `SETUP` 에서 null 이 나온다
- [ ] **Step 3: 세 곳을 고친다**
```java
// RecordKind.java
CONCEPT,
SETUP
```
```java
// PublicPaths.java — sealed switch 이므로 넣지 않으면 컴파일이 막힌다
case SETUP -> "/setups/" + slug;
```
```java
// PublicSql.pathOf
case "SETUP" -> "/setups/" + slug;
```
`LATEST_ENTRY_TYPES` 에도 `'SETUP'` 을 더한다(현재 값을 먼저 읽고 그 형식에 맞춘다).
- [ ] **Step 4: 테스트 통과 확인**
Run: `cd BE/src && ./gradlew test --tests '*PublicPathsTest*'`
Expected: PASS
- [ ] **Step 5: 가드를 되돌려 실패를 확인한다**
`PublicSql.pathOf` 의 `case "SETUP"` 줄만 지우고 → FAIL 확인 → 되돌리고 → PASS 확인.
- [ ] **Step 6: 커밋**
```bash
cd BE && git add . && git commit -m "feat: SETUP 의 공개 경로와 전수 대조 가드"
```
---
### Task 6: Studio 작업본 — 저장 · 조회 · 검증
**Files:**
- Create: `PS/studio/SetupWorkingCopyStore.java`
- Modify: `PS/studio/StudioDocumentSql.java`
- Modify: `PS/studio/JdbcWorkingCopyRepositoryAdapter.java`
- Modify: `BE/.../StudioRequestMapper.java`, `StudioResponseMapper.java`
- Modify: `BE/.../StudioDocumentValidator.java`
- Modify: `BE/.../StudioPersistenceIntegrationTest.java`
**Interfaces:**
- Consumes: `RecordKind.SETUP`(Task 5), `setup_detail`(Task 4)
- Produces: SETUP 작업본의 저장·조회; 프로젝트 없는 SETUP 은 게시 오류
- [ ] **Step 1: 검증기 단위 테스트를 먼저 쓴다**
프로젝트 없는 SETUP → `PROJECT_REQUIRED` 오류. 주제 없는 SETUP → 오류도 경고도 없다. `bodyMarkdown` 이 비면 오류.
- [ ] **Step 2: 실패 확인**
Run: `cd BE/src && ./gradlew test --tests '*StudioDocumentValidator*'`
Expected: FAIL
- [ ] **Step 3: `SetupWorkingCopyStore` 를 쓴다 — `ConceptWorkingCopyStore` 를 그대로 본뜨고 `basis_version` 자리에 `pinned_versions`(jsonb) 를 둔다**
`ProjectDecisionWorkingCopyStore` 와 `ConceptWorkingCopyStore` 를 먼저 읽고 같은 뼈대를 쓴다. jsonb 직렬화는 `reference_detail.rules` 를 다루는 기존 코드와 같은 방식을 쓴다.
- [ ] **Step 4: `StudioDocumentSql` · `JdbcWorkingCopyRepositoryAdapter` · 두 Mapper 에 SETUP 분기 추가**
- [ ] **Step 5: `StudioDocumentValidator` 에 SETUP 규칙 추가 — 프로젝트 필수, 주제 선택, 본문 필수**
- [ ] **Step 6: 테스트 통과 확인**
Run: `cd BE/src && ./gradlew test --tests '*StudioDocumentValidator*' --tests '*StudioPersistenceIntegrationTest*'`
Expected: PASS
- [ ] **Step 7: 커밋**
```bash
cd BE && git add . && git commit -m "feat: SETUP 작업본 저장과 검증"
```
---
### Task 7: 게시와 공개 조회
**Files:**
- Modify: `PS/publicsite/JdbcPublicationWriterAdapter.java`
- Modify: `PS/publicsite/JdbcPublicDocumentQueryAdapter.java`
- Modify: `PS/studio/JdbcCatalogQueryAdapter.java`
- Modify: `BE/.../PublicRenderModelFactory.java`
- Modify: `BE/.../PublicSitePersistenceIntegrationTest.java`
- Modify: 공개 조회 컨트롤러/포트 — `getPublicSetup` operation 배선
**Interfaces:**
- Consumes: Task 5 의 경로, Task 6 의 작업본
- Produces: `GET /api/v1/public/setups/{slug}` 가 본문·버전 표·관계를 돌려준다
- [ ] **Step 1: 통합 테스트를 먼저 쓴다 — 셋업을 게시하면 `/setups/{slug}` 가 200 을 내고 홈·주제의 최근 기록에 나온다**
- [ ] **Step 2: 실패 확인**
Run: `cd BE/src && ./gradlew test --tests '*PublicSitePersistenceIntegrationTest*'`
Expected: FAIL
- [ ] **Step 3: `JdbcPublicationWriterAdapter` — `documentBacked(RecordKind)` 에 SETUP 추가, unpublish switch 식의 `CASE, REFERENCE, CONCEPT` 갈래에 `SETUP` 추가, `setup_detail` 기록, projection upsert**
- [ ] **Step 4: `JdbcPublicDocumentQueryAdapter` — `/setups/{slug}` 상세 조회**
- [ ] **Step 5: `JdbcCatalogQueryAdapter` — RELATION 후보에 셋업 포함 (Case 가 셋업을 가리킬 수 있어야 한다)**
- [ ] **Step 6: `PublicRenderModelFactory` — 즉시 미리보기를 Case 와 같은 파서로**
- [ ] **Step 7: 테스트 통과 확인**
Run: `cd BE/src && ./gradlew test --tests '*PublicSite*' --tests '*Studio*'`
Expected: PASS
- [ ] **Step 8: 전체 빌드**
Run: `cd BE/src && ./gradlew build`
Expected: BUILD SUCCESSFUL (`-Werror` · ErrorProne · Checkstyle 포함)
- [ ] **Step 9: 커밋**
```bash
cd BE && git add . && git commit -m "feat: SETUP 게시와 공개 조회"
```
---
### Task 8: 프론트 계약 표와 작업본 검증 가드
**Files:**
- Modify: `FE/src/features/tech-log/presentation/shared/document-kind-labels.ts`
- Modify: `FE/src/features/tech-log/adapters/mock/validate-working-copy.ts:71`
- Create: `FE/tests/features/tech-log/setup-working-copy-fields.test.ts`
**Interfaces:**
- Consumes: Task 3 의 `generated.ts`
- Produces: `DOCUMENT_KIND_LABELS.SETUP = "환경 구성"` 등 세 표
- [ ] **Step 1: 가드 테스트를 먼저 쓴다 — 계약 스키마의 종류별 문자열 필드와 `stringFields` 대조**
vendored `studio-api.openapi.yaml` 을 읽어 각 `*Input` 스키마의 `type: string` 속성 집합을 뽑고, `validate-working-copy.ts` 가 그 종류에 대해 검사하는 필드 집합과 같은지 본다.
- [ ] **Step 2: 실패 확인**
Run:
```bash
cd FE && env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') ./node_modules/.bin/vitest run tests/features/tech-log/setup-working-copy-fields.test.ts
```
Expected: FAIL — SETUP 이 `stringFields` 에 없다
- [ ] **Step 3: 세 표를 채운다**
```ts
export const DOCUMENT_KIND_LABELS: Record<RecordKind, string> = {
CASE: "검증 기록",
CONCEPT: "동작 원리",
REFERENCE: "적용 기준",
PROJECT_DECISION: "설계 결정",
QUESTION: "열린 질문",
SETUP: "환경 구성",
};
```
`DOCUMENT_KIND_STATES` 에 `SETUP: "SETTLED"`, `EXPLORE_KIND_PATHS` 에 `SETUP: "/explore/setups"`.
- [ ] **Step 4: `validate-working-copy.ts` 를 고친다**
71행의 `stringFields` 에 `...(kind === "SETUP" ? ["bodyMarkdown"] : [])` 를 더하고, `pinnedVersions` 배열 검사를 `checkArray("pinnedVersions", { name: "string", version: "string" })` 로 SETUP 갈래에 더한다.
- [ ] **Step 5: 통과 확인**
Run: 위 Step 2 와 같은 명령
Expected: PASS
- [ ] **Step 6: 가드를 되돌려 실패를 확인한다**
`stringFields` 의 SETUP 갈래만 지우고 → FAIL 확인 → 되돌리고 → PASS 확인.
- [ ] **Step 7: 타입 검사**
Run: `cd FE && npm run check:types`
Expected: 통과 (표를 안 채웠으면 여기서 막힌다)
---
### Task 9: Studio 편집기
**Files:**
- Create: `FE/src/features/tech-log/presentation/studio/components/setup-fields.tsx`
- Modify: `FE/src/features/tech-log/presentation/studio/components/new-document-form.tsx`
- Modify: `FE/src/features/tech-log/presentation/studio/components/document-editor-controller.tsx`
**Interfaces:**
- Consumes: Task 8 의 세 표
- Produces: SETUP 편집 화면 — 버전 표(행 추가·삭제)와 본문 마크다운
- [ ] **Step 1: `setup-fields.tsx` 를 쓴다 — `concept-fields.tsx` 를 본뜨되 `basisVersion` 한 줄 자리에 `pinnedVersions` 행 편집기를 둔다. Asset Picker 는 Case 것을 재사용**
- [ ] **Step 2: `new-document-form.tsx` 에 종류 추가**
```ts
SETUP: {
label: "환경 구성",
description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다.",
fields: "버전 · 본문",
},
```
`bodyMarkdown` 초기값으로 뼈대를 넣는다:
```
## 실행 절차
## 구성 값
## 확인 방법
```
- [ ] **Step 3: `document-editor-controller.tsx` 에 SETUP 분기와 `SETUP_FIELD_PATHS` 추가**
- [ ] **Step 4: 컴포넌트 테스트**
Run:
```bash
cd FE && env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') ./node_modules/.bin/vitest run tests/component
```
Expected: PASS
---
### Task 10: 공개 렌더와 라우트
**Files:**
- Create: `FE/src/features/tech-log/presentation/public/pages/setup-document-page.tsx`
- Modify: `FE/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx:83,178,269`
- Modify: `FE/src/features/tech-log/contracts/tech-log-route-contract.ts:31` 부근
- Modify: `FE/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx`
- Modify: `FE/src/features/tech-log/presentation/public/components/explore-filter-form.tsx`
- Modify: `FE/src/features/tech-log/presentation/public/components/public-document-header.tsx:40-51`
- Modify: `FE/src/features/tech-log/presentation/public/pages/home-page.tsx`
- Modify: `FE/src/features/tech-log/presentation/tech-log-route-runtime.tsx`
**Interfaces:**
- Consumes: Task 7 의 `GET /setups/{slug}`, Task 8 의 세 표
- Produces: `/setups/:slug` 화면; `/explore/setups` 목록
- [ ] **Step 1: 라우트 등록**
```ts
defineSpec({ routeId: "TECH_LOG_SETUP", path: "/setups/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "환경 구성", navigationLabel: null, navigationOrder: null }),
```
- [ ] **Step 2: `public-record-renderer.tsx` 에 SETUP 렌더 추가 — 제목·요약·버전 표·본문·목차·관계. 버전이 비면 표를 그리지 않는다**
- [ ] **Step 3: 주제 없는 머리말을 막는다 — `:178` 과 `:269` 의 `<TargetLink target={model.topic} />` 를 `:83` 과 같이 `model.topic.label ?` 로 감싼다**
- [ ] **Step 4: `explore-kind-page.tsx` 에 `setups` 항목 추가**
```ts
setups: { kind: "SETUP", title: DOCUMENT_KIND_LABELS.SETUP, description: "이 기록을 자기 손으로 재현하는 절차입니다." },
```
- [ ] **Step 5: `explore-filter-form.tsx` 유형 선택지와 `home-page.tsx` 의 `latestTypeLabels` 에 SETUP 추가**
- [ ] **Step 6: `tech-log-route-runtime.tsx` 에 `TECH_LOG_SETUP` → `setup-document-page.tsx` 배선**
- [ ] **Step 7: 라우트 계약 테스트**
Run:
```bash
cd FE && env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') ./node_modules/.bin/vitest run tests/component/router.test.tsx tests/features/tech-log
```
Expected: PASS
---
### Task 11: 다섯 게이트와 배포
- [ ] **Step 1: 프론트 다섯 게이트**
```bash
cd FE
npm run check:types && npm run lint
env $(env | grep -i "^npm_config" | cut -d= -f1 | sed 's/^/-u /' | tr '\n' ' ') ./node_modules/.bin/vitest run
```
Expected: 전부 통과
- [ ] **Step 2: 프론트 커밋**
```bash
cd FE && git add . && git commit -m "feat: 환경 구성(SETUP) 기록 종류"
```
- [ ] **Step 3: 백엔드 이미지 빌드 → 임포트 → 롤아웃**
커밋 뒤에 `cd BE/src && ./gradlew cleanStaleTraceableJars build`(jar 이름에 커밋 해시가 들어간다) → `docker build` → `docker save | gzip` → `scp dh-server:/tmp/deploy.tar.gz` → `kube-system` 의 ctr import Job → `kubectl set image`(컨테이너 이름 `backend`, 태그는 짧은 SHA 7자리).
**백엔드를 먼저 올린다.** 프론트가 먼저 올라가면 `/setups/{slug}` 를 부르는 화면이 404 를 받는다.
- [ ] **Step 4: 프론트 이미지 빌드 → 롤아웃**
빌드 인자 전부 필요:
`APP_PROFILE=production` · `VITE_ROUTER_BASE_PATH=/` · `RUNTIME_API_BASE_URL=https://hyeonworks.com/` · `VITE_BUILD_ID` · `VITE_COMMIT_SHA` · `RELEASE_ID` · `CI_RUNNER_IMAGE=node@sha256:3638d9a6fe4030bd716be989438248074489337ba3275657f93595428be4fc03` · `SOURCE_DATE_EPOCH`
- [ ] **Step 5: 운영 확인**
Studio 에서 셋업 문서를 하나 써서 게시 → `/setups/{slug}` · `/explore/setups` · 홈 최근 기록 · Case 에서 건 관계를 눈으로 확인.