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

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: RecordKind enum 값 SETUP; 스키마 PinnedVersion · SetupInput · SetupWorkingCopy · SetupPublicRenderModel; 세 union(WorkingCopyInput · WorkingCopy · PublicRenderModel)의 SETUP 분기

  • Step 1: RecordKind enum 에 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: WorkingCopyInput union(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: WorkingCopy union(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: PublicRenderModel union 에 분기 추가 (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 의 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행) 바로 뒤에 같은 모양으로
  /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: 공개 조회 컨트롤러/포트 — 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: 커밋
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 에서 적용됨 — postgresqlTechLogSchemaMigrationTest 3건 통과
  • 경로 가드를 되돌려(PublicSql.pathOf 의 SETUP 갈래 삭제) 실패하는 것을 보고 되돌렸다

하지 않은 것

  • 배포(Task 11 Step 3~5). 운영에 나가는 일이라 승인 전에 멈췄다.
  • DB CHECK 제약 대조 가드(Task 4 Step 1). V17 이 아홉 제약을 모두 고쳤고 통합 테스트가 마이그레이션을 실제로 적용해 확인했지만, 「계약 enum 과 DB CHECK 를 대조하는」 가드 자체는 아직 없다. 다음에 종류를 더할 때 record_variant 같은 새 제약을 또 빠뜨릴 수 있는 자리다.