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 에서 건 관계를 눈으로 확인.
|
||||
@@ -0,0 +1,278 @@
|
||||
# 환경 구성(SETUP) 문서 종류 추가
|
||||
|
||||
작성일 2026-09-09 · 대상 저장소 `tech-log-design-package` · `tech-log-backend` · `tech-log-frontend`
|
||||
|
||||
## 왜
|
||||
|
||||
이 저장소의 다섯 종류는 전부 **끝난 일**을 남긴다. Case 는 무엇을 관찰했는지, Concept 은
|
||||
무엇이 어떻게 도는지, Reference 는 무엇을 기준으로 판단하는지를 남긴다.
|
||||
|
||||
없는 것은 **읽는 사람이 자기 손으로 다시 해 보려면 무엇부터 하는가**다. Keycloak 네 패턴을
|
||||
읽고 "그래서 이걸 어떻게 띄우지"에 답하는 자리가 지금은 없다.
|
||||
|
||||
Case 에 `environment`(「검증 환경」)가 이미 있지만 이 자리를 대신하지 못한다. 두 가지 이유다.
|
||||
|
||||
- **평문 한 칸이다.** `docker compose up`, realm import 명령, 포트 표가 들어가지 않는다.
|
||||
Markdown 을 거치지 않고 그대로 그려지는 칸이다.
|
||||
- **범위 표시지 절차가 아니다.** 「검증 환경」은 *이 결과가 어디까지 유효한가*를 적는 자리다.
|
||||
같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.
|
||||
|
||||
그래서 종류를 하나 더한다. Case 의 `environment` 는 그대로 둔다 — 둘은 다른 질문에 답한다.
|
||||
|
||||
## 무엇이 아닌가
|
||||
|
||||
- **Case 의 「검증 환경」·「재현 조건」을 없애지 않는다.** 범위 표시는 그 기록의 것이다.
|
||||
- **전용 관계 칸을 만들지 않는다.** 「이 환경에서 측정했다」는 기존 `relations` 의 `reason`
|
||||
으로 적는다. 칸을 새로 만들면 관계에도 있고 전용 칸에도 있는 두 진실이 생긴다.
|
||||
- **셋업이 실제로 도는지 CI 에서 돌려 보지 않는다.** 실행 검증은 별건이다. 이 종류가 하는
|
||||
일은 절차를 한 곳에 두는 것까지다.
|
||||
- **절 이름을 스키마로 강제하지 않는다.** 실행 절차 · 구성 값 · 확인 방법은 권장 뼈대이지
|
||||
필수 칸이 아니다. 프로젝트마다 셋업의 모양이 다르다. 대신 Studio 의 새 문서 폼이 그
|
||||
뼈대를 `bodyMarkdown` 초기값으로 넣어 준다.
|
||||
- **기존 문서를 자동으로 고치지 않는다.** 이미 쓴 Case 의 본문은 손대지 않는다.
|
||||
|
||||
## 이름
|
||||
|
||||
| 자리 | 값 | 이유 |
|
||||
|---|---|---|
|
||||
| 계약 enum | `SETUP` | `case_detail.environment` 와 겹치지 않게 |
|
||||
| 화면 라벨 | 「환경 구성」 | `DOCUMENT_KIND_LABELS` 의 네 글자 결 |
|
||||
| 공개 경로 | `/setups/{slug}` | |
|
||||
| 목록 경로 | `/explore/setups` | |
|
||||
| 지식 상태 | `SETTLED` | 정리한 것. 확인한 것(Case·Concept)도, 열린 것(Question)도 아니다 |
|
||||
|
||||
`ENVIRONMENT` 가 영어로는 자연스럽지만 쓰지 않는다. 이 저장소가 열네 번 밟은 실패는
|
||||
「종류를 손으로 나열한 곳을 빠뜨린다」이고, 그걸 찾는 수단이 grep 이다. 필드 이름
|
||||
`environment` 와 종류 이름 `ENVIRONMENT` 가 같은 저장소에 있으면 그 수단이 무뎌진다.
|
||||
|
||||
## 붙는 자리
|
||||
|
||||
| 붙는 곳 | 규칙 | 왜 |
|
||||
|---|---|---|
|
||||
| 프로젝트 | **필수** — 없으면 게시 오류 | 셋업은 언제나 어떤 프로젝트의 셋업이다. `PROJECT_DECISION` 과 같은 규칙 |
|
||||
| 주제 | 선택 | 이 선택이 두 범위를 다 준다(아래) |
|
||||
| 관계 | 자유 | 「이 환경에서 측정했다」 |
|
||||
|
||||
주제를 선택으로 두는 것이 요구사항을 그대로 만족한다.
|
||||
|
||||
```
|
||||
주제 없음 → 그 프로젝트의 공통 셋업 (프로젝트마다 하나)
|
||||
주제 있음 → 그 프로젝트 · 그 주제의 셋업 (주제마다 다를 때)
|
||||
```
|
||||
|
||||
한 프로젝트 안에서 주제별로 다른 구성을 쓰면 주제를 붙인 셋업을 여러 개 두고, 구성이
|
||||
하나면 주제 없는 셋업 하나만 둔다. 스키마를 나누지 않고 같은 종류로 둘 다 된다.
|
||||
|
||||
## 문서의 모양
|
||||
|
||||
```
|
||||
base (모든 종류 공유)
|
||||
kind · title · slug · summary · topicId · projectId · relations · tags
|
||||
|
||||
SETUP 이 더하는 것
|
||||
pinnedVersions : [{ name, version }] 구조화. 예) { "Keycloak", "26.7.0" }
|
||||
머리말 아래에 표로 그린다. 비어 있으면 그리지 않는다
|
||||
bodyMarkdown : 자유 마크다운. Case·Concept 와 같은 파서를 쓴다 —
|
||||
`##` 소제목이 목차가 되고 `:::evidence key="…"` 로 도식을 끼운다
|
||||
```
|
||||
|
||||
### 왜 버전만 구조화하나
|
||||
|
||||
넷 중 셋(실행 절차 · 구성 값 · 확인 방법)은 명령과 코드블록과 표를 담아야 한다. 평문 칸에
|
||||
들어가지 않고, Markdown 칸을 넷으로 쪼개면 같은 렌더러를 네 번 붙이게 된다.
|
||||
|
||||
버전만 다르다. **버전은 이 기록의 유효 범위를 정하는 값**이고, 목록과 머리말에서 본문을
|
||||
열지 않고도 보여야 한다. Concept 의 `basisVersion` 이 같은 이유로 따로 있다. 다른 점은
|
||||
셋업은 한 줄이 아니라 여럿이라는 것뿐이다 — Keycloak · Spring Boot · PostgreSQL 이 각각.
|
||||
|
||||
`reference_detail.rules` · `examples` 가 이미 `jsonb` 배열 + `jsonb_typeof = 'array'` CHECK
|
||||
로 되어 있으므로 같은 모양을 쓴다. 자식 테이블을 만들지 않는 이유는 이 값으로 검색하거나
|
||||
조인하지 않고 표로만 그리기 때문이다.
|
||||
|
||||
## 계약 변경 — design package 가 소유
|
||||
|
||||
### studio-v1.yaml (작성)
|
||||
|
||||
- `RecordKind` enum 에 `SETUP` 추가
|
||||
- `SetupInput` 신설 — `WorkingCopyInputBase` + `{ kind, bodyMarkdown, pinnedVersions }`
|
||||
- `SetupWorkingCopy` (응답형) 신설 — 같은 모양에 `id · version · updatedAt`
|
||||
- 작업본 union(`WorkingCopyInput` / `WorkingCopy`)에 분기 추가
|
||||
- `PinnedVersion` 스키마 신설 — `{ name: string(1..60), version: string(1..40) }`
|
||||
|
||||
### public-v1.yaml (공개)
|
||||
|
||||
- `SetupDetailResponse` 신설
|
||||
- `setup: { title, summary, pinnedVersions[], content, contentFormat,
|
||||
contentFormatVersion, bodyAssets, primaryTopic?, primaryProject, tags,
|
||||
publishedAt, updatedAt }`
|
||||
- `KnowledgeListItem.type` 에 `SETUP` 추가
|
||||
- `LatestEntry.entryType` 에 `SETUP` 추가
|
||||
- `exploreKnowledge` 의 `type` 질의 파라미터에 `SETUP` 추가
|
||||
- `GET /setups/{slug}` 경로 추가
|
||||
|
||||
### studio-management-v1.yaml
|
||||
|
||||
- 종류를 나열하는 자리에 `SETUP` 추가
|
||||
|
||||
## 백엔드
|
||||
|
||||
### 마이그레이션 V17
|
||||
|
||||
V11(개념 추가)과 같은 모양이다. `document` 테이블을 공유하므로 새 테이블은 하나뿐이다.
|
||||
|
||||
```sql
|
||||
CREATE TABLE setup_detail (
|
||||
document_id uuid PRIMARY KEY,
|
||||
document_type varchar(20) NOT NULL DEFAULT 'SETUP' CHECK (document_type = 'SETUP'),
|
||||
pinned_versions jsonb NOT NULL DEFAULT '[]'::jsonb
|
||||
CHECK (jsonb_typeof(pinned_versions) = 'array'),
|
||||
CONSTRAINT fk_setup_detail_document
|
||||
FOREIGN KEY (document_id, document_type) REFERENCES document(id, document_type)
|
||||
ON DELETE CASCADE
|
||||
);
|
||||
```
|
||||
|
||||
허용 목록을 고쳐야 하는 **CHECK 제약 아홉 개**. 하나라도 빠뜨리면 그 단계에서 제약 위반으로
|
||||
막히고, 막힌 이유는 화면에 드러나지 않는다.
|
||||
|
||||
| 테이블 | 제약 | 더할 값 |
|
||||
|---|---|---|
|
||||
| `document` | `document_document_type_check` | `'SETUP'` |
|
||||
| `studio_relation` | `studio_relation_source_kind_check` | `'SETUP'` |
|
||||
| `studio_validation` | `studio_validation_source_kind_check` | `'SETUP'` |
|
||||
| `studio_preview` | `studio_preview_source_kind_check` | `'SETUP'` |
|
||||
| `publication` | `publication_source_kind_check` | `'SETUP'` |
|
||||
| `publication_event` | `publication_event_source_kind_check` | `'SETUP'` |
|
||||
| `public_resource_projection` | `..._resource_type_check` | `'SETUP'` |
|
||||
| `record_variant` | `record_variant_record_kind_check` | `'SETUP'` |
|
||||
| `project_activity` | `project_activity_activity_type_check` | `'SETUP_PUBLISHED'` |
|
||||
|
||||
**`record_variant` 가 이 표에서 가장 중요하다.** V11 은 여덟 개를 고쳤는데 `record_variant`
|
||||
는 그때 없었다(V14 에서 생겼다). V14 의 주석이 그 사정을 이렇게 적어 두었다 — "개념을 더할
|
||||
때 이런 목록을 빠뜨려 실제로 화면이 깨진 적이 있다." 같은 자리가 이번에 다시 온다.
|
||||
|
||||
### 코드
|
||||
|
||||
컴파일러가 잡아 주는 곳과 아닌 곳이 갈린다. **아래쪽이 사고 지점이다.**
|
||||
|
||||
**잡힘 — `RecordKind` enum 을 받는 sealed switch 식**
|
||||
|
||||
| 파일 | 할 일 |
|
||||
|---|---|
|
||||
| `RecordKind` | enum 에 `SETUP` |
|
||||
| `PublicPaths` | `SETUP → /setups/{slug}` |
|
||||
| `JdbcPublicationWriterAdapter` | `documentBacked` · unpublish switch 에 `SETUP` |
|
||||
|
||||
**안 잡힘 — 문자열 switch · SQL 리터럴 · 분기**
|
||||
|
||||
| 파일 | 할 일 | 빠뜨리면 |
|
||||
|---|---|---|
|
||||
| `PublicSql.pathOf` | `case "SETUP" -> "/setups/" + slug` | **게시는 되고 링크만 죽는다.** `default -> null` 이라 조용하다. 결정 404 가 정확히 여기서 났다 |
|
||||
| `PublicSql.LATEST_ENTRY_TYPES` | `'SETUP'` 추가 | 홈·주제의 최근 기록에서 빠진다 |
|
||||
| `StudioDocumentSql` | SETUP 조회·저장 SQL | |
|
||||
| `JdbcWorkingCopyRepositoryAdapter` + `SetupWorkingCopyStore`(신규) | 작업본 읽기·쓰기 | |
|
||||
| `JdbcPublicDocumentQueryAdapter` | `/setups/{slug}` 상세 조회 | |
|
||||
| `JdbcCatalogQueryAdapter` | RELATION 후보에 셋업 포함 | Case 가 셋업을 가리킬 수 없다 |
|
||||
| `StudioDocumentValidator` | 프로젝트 없으면 **오류**, `bodyMarkdown` 비면 오류 | |
|
||||
| `StudioRequestMapper` / `StudioResponseMapper` | SETUP 분기 | |
|
||||
| `PublicRenderModelFactory` | 즉시 미리보기를 Case 와 같은 파서로 | |
|
||||
|
||||
## 프론트엔드
|
||||
|
||||
**잡힘 — `Record<RecordKind, _>` 표 세 개.** 빠뜨리면 컴파일이 막힌다.
|
||||
|
||||
```
|
||||
DOCUMENT_KIND_LABELS SETUP: "환경 구성"
|
||||
DOCUMENT_KIND_STATES SETUP: "SETTLED"
|
||||
EXPLORE_KIND_PATHS SETUP: "/explore/setups"
|
||||
```
|
||||
|
||||
**새로 만드는 것**
|
||||
|
||||
| 파일 | 할 일 |
|
||||
|---|---|
|
||||
| 계약 codegen | `npm run generate:tech-log-contract` |
|
||||
| `setup-fields.tsx` (신규) | 편집기 — 버전 표(행 추가·삭제) + 본문 마크다운. Case 의 Asset Picker 재사용 |
|
||||
| `setup-document-page.tsx` (신규) | 공개 상세 |
|
||||
| `public-record-renderer.tsx` | 셋업 렌더 — 제목·요약·버전 표·본문·목차·관계 |
|
||||
| 라우트 | `TECH_LOG_SETUP` = `/setups/:slug`, `explore-kind-page` 에 `setups` |
|
||||
| `document-editor-controller.tsx` | SETUP 분기와 `SETUP_FIELD_PATHS` |
|
||||
| `new-document-form.tsx` | 종류 선택지 + 뼈대 초기값(실행 절차 / 구성 값 / 확인 방법 세 절) |
|
||||
| `explore-filter-form.tsx` | 유형 선택지에 「환경 구성」 |
|
||||
| `public-document-header.tsx` | `kindLabels` 에 SETUP |
|
||||
| `home-page.tsx` | `latestTypeLabels` 에 `SETUP: "환경 구성"` |
|
||||
| 모의 어댑터 | 픽스처에 셋업 문서 추가 |
|
||||
|
||||
**안 잡힘**
|
||||
|
||||
| 파일 | 할 일 |
|
||||
|---|---|
|
||||
| `validate-working-copy.ts:71` | `stringFields` 에 `kind === "SETUP" ? ["bodyMarkdown"] : []` |
|
||||
| 같은 파일 | `pinnedVersions` 배열 검사(`checkArray`) 추가 |
|
||||
|
||||
### 주제 없는 셋업의 머리말
|
||||
|
||||
**주제가 없는 문서는 이번이 처음이다.** 개념이 프로젝트 없는 첫 종류였던 것과 같은 자리다.
|
||||
|
||||
지금 상태를 확인해 보면 렌더러가 두 갈래다.
|
||||
|
||||
| 자리 | 지금 | 할 일 |
|
||||
|---|---|---|
|
||||
| `public-record-renderer.tsx:83` | `model.topic.label ?` 로 이미 막는다 | 그대로 |
|
||||
| `public-record-renderer.tsx:178`, `:269` | `<TargetLink target={model.topic} />` 를 조건 없이 그린다 | 같은 방식으로 막는다 |
|
||||
| `public-document-header.tsx:40-51` | `topic` 객체를 늘 만든다. `publicPath` 만 `topicSlug` 없을 때 `null` | `label` 이 비면 마디를 뺄 수 있도록 |
|
||||
|
||||
주제가 없으면 링크 없는 빈 마디가 남는다. 다른 종류는 주제가 늘 있으므로 이 변경으로 화면이
|
||||
달라지지 않는다 — 회귀 테스트로 확인한다.
|
||||
|
||||
## 가드 — 셋
|
||||
|
||||
손으로 나열한 곳마다 하나씩. 전부 **계약을 읽어 대조하는** 방식이다. 목록을 또 손으로 적으면
|
||||
같은 실패가 가드 안으로 옮겨 갈 뿐이다.
|
||||
|
||||
1. **`PublicSql.pathOf` 전수 대조** — vendored `studio-v1.yaml` 의 `RecordKind` enum 을 읽어
|
||||
모든 값에 대해 `pathOf` 가 null 이 아닌 경로를 내는지 본다. 문자열 switch 의 `default ->
|
||||
null` 을 막는 유일한 수단이다.
|
||||
2. **`validate-working-copy.ts` 필드 대조** — 계약 스키마의 종류별 문자열 필드를 파싱해
|
||||
`stringFields` 와 집합이 같은지 본다.
|
||||
3. **DB CHECK 제약 대조 (통합 테스트)** — 위 표의 제약 아홉 개가 허용하는 값 집합이 계약
|
||||
enum 과 일치하는지 본다. `information_schema` 에서 CHECK 절을 읽어 대조한다. 다음에 종류를
|
||||
더할 때 `record_variant` 같은 새 제약이 생겨도 이 가드가 그 자리를 알려 준다.
|
||||
|
||||
**각 가드는 되돌려서 실패하는 것을 보고 나서 센다.** 되돌리지 않은 가드는 가드가 아니다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- **계약**: design package 검증기 3종 (`check-openapi` / `check-consistency` /
|
||||
`check-contract-parity`)
|
||||
- **백엔드**
|
||||
- `PublicSitePersistenceIntegrationTest` — 셋업 게시본이 홈·주제 최근 기록에 나온다
|
||||
- 공개 상세 통합 테스트 — `/setups/{slug}` 가 본문·버전 표·관계를 돌려준다
|
||||
- 검증기 단위 테스트 — 프로젝트 없는 SETUP 은 게시가 막힌다(오류), 주제 없음은 조용하다
|
||||
- 가드 1·3
|
||||
- **프론트엔드**
|
||||
- `public-setup-mapping.test.ts` — 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣어
|
||||
본문·버전 표·관계가 채워지는지 본다
|
||||
- 화면 테스트 — 셋업 상세가 목차·본문·버전 표를 그리고, 주제 없는 머리말이 그 마디를 뺀다
|
||||
- 탐색 필터 테스트 — `type=SETUP` 으로 걸러진다
|
||||
- `route-contract.test.ts` — 새 라우트 등록
|
||||
- 가드 2
|
||||
- **다섯 게이트**: `check:types` · `lint` · `test:unit` · `test:component` · `test:tech-log`
|
||||
|
||||
## 반영 순서
|
||||
|
||||
1. design package 계약 → 검증기 → 커밋
|
||||
2. 백엔드: vendored 계약 + `MANIFEST.sha256`, V17, 코드, 가드 1·3, 테스트 → 커밋
|
||||
3. 프론트: codegen, 편집기·렌더러·라우트, 가드 2, 테스트 → 다섯 게이트 → 커밋
|
||||
4. 백엔드 이미지 → 임포트 → 롤아웃 (마이그레이션이 먼저 적용되어야 한다)
|
||||
5. 프론트 이미지 → 롤아웃
|
||||
6. 운영에서 셋업 문서를 하나 써서 게시 → 홈·탐색·상세·Case 에서 건 관계를 눈으로 확인
|
||||
|
||||
백엔드를 먼저 올린다. 프론트가 먼저 올라가면 `/setups/{slug}` 를 부르는 화면이 404 를
|
||||
받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.
|
||||
|
||||
## 남은 문제
|
||||
|
||||
- `tech-log-design-package` 가 지금 로컬에 없다(`/home/donghyeon/workspace/tech-log-design-package`
|
||||
없음). 계약을 고치려면 이 저장소를 먼저 되살려야 한다. 백엔드의
|
||||
`src/config/openapi/` 에 vendored 사본이 있으므로 내용은 남아 있다.
|
||||
Reference in New Issue
Block a user