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:
co-authored by
Claude Opus 5
parent
3374f286be
commit
3af9be9e09
@@ -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 에서 건 관계를 눈으로 확인.
|
||||
Reference in New Issue
Block a user