Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
33 KiB
환경 구성(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
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:
RecordKindenum 값SETUP; 스키마PinnedVersion·SetupInput·SetupWorkingCopy·SetupPublicRenderModel; 세 union(WorkingCopyInput·WorkingCopy·PublicRenderModel)의SETUP분기 -
Step 1:
RecordKindenum 에SETUP추가 (840행)
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT, SETUP]
- Step 2:
PinnedVersion스키마 신설 —ConceptInput(964행) 바로 앞
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블록 바로 뒤
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:
WorkingCopyInputunion(1035행 부근)에 분기 추가
- { $ref: "#/components/schemas/SetupInput" }
그리고 mapping: 아래에
SETUP: "#/components/schemas/SetupInput"
- Step 5:
SetupWorkingCopy신설 —ConceptWorkingCopy(1093행) 블록 뒤
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:
WorkingCopyunion(1145행 부근)에 분기 추가 — 설명 블록의| ConceptWorkingCopy줄 뒤에| SetupWorkingCopy,oneOf에$ref,mapping에SETUP -
Step 7:
SetupPublicRenderModel신설 —ConceptPublicRenderModel(1589행) 블록 뒤
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:
PublicRenderModelunion 에 분기 추가 (oneOf+mapping) -
Step 9: yaml 이 파싱되는지 확인
Run:
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 의
SETUPenum 값(이름만 공유, 파일은 독립) -
Produces:
GET /setups/{slug}·SetupDetailResponse·SetupDetailResponseEnvelope·getPublicSetupoperationId -
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행) 바로 뒤에 같은 모양으로
/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 와 같다):
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:
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 을 백엔드로 복사
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갱신
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 로 임시 저장소를 만든다.
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: 타입 재생성
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 게이트 통과 확인
cd FE && npm run generate:tech-log-contract -- --check
Expected: tech-log contracts are in sync: 세 줄
- Step 7: 생성물에 SETUP 이 실제로 들어갔는지 확인
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: 커밋 (두 저장소)
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 의 모든 값이 각 제약에 들어 있는지 본다. 대상 제약 여덟(종류) + 하나(활동 유형):
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 을 쓴다
-- 환경 구성(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'
));
제약 이름은 실제 이름으로 맞춘다. 쓰기 전에 확인:
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: 커밋
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: 세 곳을 고친다
// RecordKind.java
CONCEPT,
SETUP
// PublicPaths.java — sealed switch 이므로 넣지 않으면 컴파일이 막힌다
case SETUP -> "/setups/" + slug;
// 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: 커밋
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: 커밋
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: 공개 조회 컨트롤러/포트 —
getPublicSetupoperation 배선
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: 커밋
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:
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: 세 표를 채운다
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에 종류 추가
SETUP: {
label: "환경 구성",
description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다.",
fields: "버전 · 본문",
},
bodyMarkdown 초기값으로 뼈대를 넣는다:
## 실행 절차
## 구성 값
## 확인 방법
-
Step 3:
document-editor-controller.tsx에 SETUP 분기와SETUP_FIELD_PATHS추가 -
Step 4: 컴포넌트 테스트
Run:
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: 라우트 등록
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항목 추가
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:
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: 프론트 다섯 게이트
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: 프론트 커밋
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 에서 건 관계를 눈으로 확인.
진행 상태 (2026-09-09)
Task 1~10 완료. Task 11 은 게이트까지 끝났고 배포는 하지 않았다.
| 커밋 | 저장소 | 내용 |
|---|---|---|
3af9be9 |
frontend | 계약·타입·화면·가드 |
7cd11a7 |
frontend | CatalogEntry.kind · ResolvedRelation.targetKind |
17fe3d1 |
backend | V17 · 경로 가드 · 작성/게시/공개 조회 |
확인한 것
- 프론트 다섯 게이트:
check:types·lint통과,test:component(78파일 560건) ·test:tech-log통과,test:unit은 사전 실패 3건만 남음 - 백엔드
./gradlew test전체 통과(816건) - V17 이 실제 PostgreSQL 에서 적용됨 —
postgresqlTechLogSchemaMigrationTest3건 통과 - 경로 가드를 되돌려(
PublicSql.pathOf의 SETUP 갈래 삭제) 실패하는 것을 보고 되돌렸다
하지 않은 것
- 배포(Task 11 Step 3~5). 운영에 나가는 일이라 승인 전에 멈췄다.
- DB CHECK 제약 대조 가드(Task 4 Step 1). V17 이 아홉 제약을 모두 고쳤고 통합 테스트가
마이그레이션을 실제로 적용해 확인했지만, 「계약 enum 과 DB CHECK 를 대조하는」 가드 자체는
아직 없다. 다음에 종류를 더할 때
record_variant같은 새 제약을 또 빠뜨릴 수 있는 자리다.