From 3af9be9e09c9dcc9a69f83ac1077ce81ddd458f0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 9 Sep 2026 14:12:44 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=ED=99=98=EA=B2=BD=20=EA=B5=AC=EC=84=B1?= =?UTF-8?q?(SETUP)=20=EA=B8=B0=EB=A1=9D=20=EC=A2=85=EB=A5=98=EB=A5=BC=20?= =?UTF-8?q?=EB=8D=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시 하려면 무엇부터 하는가다. Case 의 environment 는 평문 한 칸이라 명령이 들어가지 않고, 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다. 프로젝트는 필수, 주제는 선택으로 둔다. 주제 없는 셋업이 그 프로젝트의 공통 구성이고, 주제를 붙이면 그 주제의 구성이다 — 스키마를 나누지 않고 두 범위를 같은 종류로 받는다. 버전만 본문 밖에 둔다(pinnedVersions). 이 절차가 어느 버전 위에서 성립했는지는 그 기록의 유효 범위이고, 목록과 머리말이 본문을 열지 않고 보여 줘야 한다. 나머지 셋(실행 절차·구성 값·확인 방법)은 명령과 표를 담아야 하므로 본문이다. 이름은 SETUP 이다. ENVIRONMENT 가 영어로는 자연스럽지만 case_detail.environment 와 겹친다 — 이 저장소가 열네 번 밟은 실패가 「종류를 손으로 나열한 곳을 빠뜨린다」이고 그걸 찾는 수단이 grep 이다. 손으로 나열해 두었던 자리를 이번에 표로 바꿨다. publicPath 의 삼항 사슬은 마지막 else 가 「나머지 전부」여서 새 종류의 주소가 조용히 /questions/… 가 됐고, document-editor 의 칸 경로도 같은 모양이었다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV --- artifacts/tests/a11y-manual/TECH_LOG_SETUP.md | 18 + config/ci/gates.json | 7 + .../plans/2026-09-09-setup-record-kind.md | 774 ++++++++++++++++++ .../2026-09-09-setup-record-kind-design.md | 278 +++++++ public/release-manifest.json | 14 +- scripts/contracts/ci-gates.ts | 11 +- .../adapters/http/http-management-gateway.ts | 1 + .../http/http-public-content-gateway.ts | 1 + .../adapters/http/public-content-mapping.ts | 13 + .../adapters/mock/validate-working-copy.ts | 22 +- .../adapters/static/public-content.ts | 17 +- .../application/ports/management-gateway.ts | 2 +- .../ports/public-content-queries.ts | 26 +- .../management/canonical-source.json | 5 +- .../contracts/management/generated.ts | 75 +- .../management/management-api.openapi.yaml | 47 ++ .../contracts/public/canonical-source.json | 5 +- .../tech-log/contracts/public/generated.ts | 105 ++- .../contracts/public/public-api.openapi.yaml | 137 ++++ .../contracts/studio/canonical-source.json | 4 +- .../tech-log/contracts/studio/generated.ts | 56 +- .../contracts/studio/studio-api.openapi.yaml | 64 +- ...ch-log-management-contract-contribution.ts | 19 + .../tech-log-public-contract-contribution.ts | 1 + .../contracts/tech-log-route-contract.ts | 1 + .../project-public-render-model.ts | 64 +- .../public/components/explore-filter-form.tsx | 1 + .../public/components/setup-document-page.tsx | 81 ++ .../public/pages/explore-kind-page.tsx | 4 +- .../presentation/public/pages/search-page.tsx | 2 +- .../presentation/public/pages/setup-page.tsx | 29 + .../shared/document-kind-labels.ts | 4 + .../public-render/public-record-renderer.tsx | 97 +++ .../studio/components/document-editor.tsx | 27 +- .../studio/components/document-list.tsx | 3 +- .../studio/components/new-document-form.tsx | 18 + .../studio/components/setup-fields.tsx | 202 +++++ .../presentation/tech-log-route-runtime.tsx | 7 + .../tech-log/knowledge-list-kinds.test.ts | 2 +- .../management-delete-routing.test.ts | 1 + .../features/tech-log/route-contract.test.ts | 6 +- tests/unit/ci-workflow-generation.test.ts | 5 +- .../unit/task3-selective-integration.test.ts | 2 +- tests/unit/tech-log-serving-contract.test.ts | 1 + vite.config.ts | 1 + 45 files changed, 2195 insertions(+), 65 deletions(-) create mode 100644 artifacts/tests/a11y-manual/TECH_LOG_SETUP.md create mode 100644 docs/superpowers/plans/2026-09-09-setup-record-kind.md create mode 100644 docs/superpowers/specs/2026-09-09-setup-record-kind-design.md create mode 100644 src/features/tech-log/presentation/public/components/setup-document-page.tsx create mode 100644 src/features/tech-log/presentation/public/pages/setup-page.tsx create mode 100644 src/features/tech-log/presentation/studio/components/setup-fields.tsx diff --git a/artifacts/tests/a11y-manual/TECH_LOG_SETUP.md b/artifacts/tests/a11y-manual/TECH_LOG_SETUP.md new file mode 100644 index 0000000..55abbda --- /dev/null +++ b/artifacts/tests/a11y-manual/TECH_LOG_SETUP.md @@ -0,0 +1,18 @@ +# TECH_LOG_SETUP accessibility review + +Status: pending-manual-review +Route ID: TECH_LOG_SETUP +Release ID: +Reviewer: +Reviewed at: +Signature: +Attestation: pending +M1 Keyboard: pending +M2 Visible focus: pending +M3 Route focus: pending +M4 Modal focus: pending +M5 Error association: pending +M6 Color signal: pending +M7 Reduced motion: pending +Screen reader: pending +Notes: Human review pending; automated evidence does not replace signed keyboard, focus, and screen-reader review. diff --git a/config/ci/gates.json b/config/ci/gates.json index e1a1a3f..814bf30 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -1076,6 +1076,12 @@ "schemaId": "markdown", "production": "source-controlled" }, + { + "id": "artifact-artifacts-tests-a11y-manual-TECH-LOG-SETUP-md", + "path": "artifacts/tests/a11y-manual/TECH_LOG_SETUP.md", + "schemaId": "markdown", + "production": "source-controlled" + }, { "id": "artifact-artifacts-tests-a11y-manual-TECH-LOG-QUESTION-md", "path": "artifacts/tests/a11y-manual/TECH_LOG_QUESTION.md", @@ -1977,6 +1983,7 @@ "artifact-artifacts-tests-a11y-manual-TECH-LOG-CASE-md", "artifact-artifacts-tests-a11y-manual-TECH-LOG-REFERENCE-md", "artifact-artifacts-tests-a11y-manual-TECH-LOG-CONCEPT-md", + "artifact-artifacts-tests-a11y-manual-TECH-LOG-SETUP-md", "artifact-artifacts-tests-a11y-manual-TECH-LOG-QUESTION-md", "artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPICS-md", "artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-md", diff --git a/docs/superpowers/plans/2026-09-09-setup-record-kind.md b/docs/superpowers/plans/2026-09-09-setup-record-kind.md new file mode 100644 index 0000000..3098e70 --- /dev/null +++ b/docs/superpowers/plans/2026-09-09-setup-record-kind.md @@ -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=""` 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 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 = { + 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` 의 `` 를 `: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 에서 건 관계를 눈으로 확인. diff --git a/docs/superpowers/specs/2026-09-09-setup-record-kind-design.md b/docs/superpowers/specs/2026-09-09-setup-record-kind-design.md new file mode 100644 index 0000000..f88e22e --- /dev/null +++ b/docs/superpowers/specs/2026-09-09-setup-record-kind-design.md @@ -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` 표 세 개.** 빠뜨리면 컴파일이 막힌다. + +``` +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` | `` 를 조건 없이 그린다 | 같은 방식으로 막는다 | +| `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 사본이 있으므로 내용은 남아 있다. diff --git a/public/release-manifest.json b/public/release-manifest.json index ed4a161..ad6c0de 100644 --- a/public/release-manifest.json +++ b/public/release-manifest.json @@ -38,28 +38,28 @@ }, "contractSet": { "setAlgorithm": "CA_CONTRACT_SET_V1", - "setDigest": "sha256:898ecb949562bd88090d4a316fdfe324a62b7e841fed5c6a82e3b1bbbb95dfbd", + "setDigest": "sha256:2348342224565150bb098988b0f2fceb6b7b41ddfc8563308a3817d686f01cd6", "packages": [ { "packageId": "@tech-log/management-contract", "version": "1.0.0", - "digest": "sha256:fa91ee5069c1117cd328e582044e1d4f9a0787634d75d7b048f812336ebbba18", + "digest": "sha256:0c226600c45b06433480a8a2ef3d812480dce3850c333bfcab5f626143ce77ea", "runtimeProtocolVersion": 1, - "sourceRevision": "1aae8dc" + "sourceRevision": "1249527" }, { "packageId": "@tech-log/public-contract", "version": "2.1.0", - "digest": "sha256:957cd1aa02ddde85420ea959c241ba7898fad6563db28d36dc0b364c2c545b03", + "digest": "sha256:0159d7b834d69252c6edcb5102166084769a58fe1c36764958b90511bb5ec2cc", "runtimeProtocolVersion": 1, - "sourceRevision": "1aae8dc" + "sourceRevision": "1249527" }, { "packageId": "@tech-log/studio-contract", "version": "3.1.0", - "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", + "digest": "sha256:035b07f07eb0d26062b940a3652960444274f34ac9cb273391a3df2326ed14a8", "runtimeProtocolVersion": 1, - "sourceRevision": "1aae8dc" + "sourceRevision": "1249527" } ] } diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index c805f48..f3fc962 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -444,6 +444,9 @@ export type LoadCiGateContractOptions = Readonly<{ }>; const CANONICAL_GATE_SHAPE_SHA256 = + // 환경 구성(SETUP) 문서 종류: FE-GATE-009 가 TECH_LOG_SETUP 수동 접근성 증거를 얻어 다시 + // 계산했다. 같은 방법이다 — 이전 상수 e4e61b06… 을 이전 gates.json 에서 먼저 재현해 + // 계산이 맞는지 확인한 뒤 새 파일을 해싱했다. // 개념(CONCEPT) 문서 종류: FE-GATE-009 가 TECH_LOG_CONCEPT 수동 접근성 증거를 얻어 다시 계산했다. // 같은 방법으로 — 옛 gates.json 에서 이전 상수 fb138e7c… 를 먼저 재현해 계산이 맞는지 // 확인한 뒤 새 파일을 해싱했다. @@ -479,7 +482,7 @@ const CANONICAL_GATE_SHAPE_SHA256 = // 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`): FE-GATE-009 가 각 // 라우트의 수동 접근성 증거를 얻어 다시 계산했다. 같은 방법이다 — 87a22f68… 을 이전 // gates.json 에서 먼저 재현해 계산이 맞는지 확인한 뒤 새 파일을 해싱했다. - "e4e61b069cee79d97a1cac3972934af312a8d97e18dad4bf5f7fa06931b60c99"; + "8a1a5479041cbce479b59d669c97921a5ba83dd7cac309131723acc221903528"; function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string { const normalized = gates.map( @@ -543,8 +546,10 @@ function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[] // 하나씩 갖는 규칙이 그대로 적용된다. // 주제(Topic) 화면 셋이 뒤를 이었다: 목록 `/topics`, 축 상세 `/topics/:slug/:variant`, // 그리고 Studio 의 주제 편집 `/studio/topics/:id`. - if (contract.artifacts.length !== 138) { - failures.push(`artifact authority baseline must contain exactly 138 artifacts; received ${contract.artifacts.length}`); + // 환경 구성(SETUP) 문서 종류가 `/setups/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성 + // 증거를 하나씩 갖는 규칙이 그대로 적용된다. + if (contract.artifacts.length !== 139) { + failures.push(`artifact authority baseline must contain exactly 139 artifacts; received ${contract.artifacts.length}`); } if (contract.stages.length !== 5) { failures.push(`stage authority baseline must contain exactly 5 stages; received ${contract.stages.length}`); diff --git a/src/features/tech-log/adapters/http/http-management-gateway.ts b/src/features/tech-log/adapters/http/http-management-gateway.ts index 43313bb..b23ce45 100644 --- a/src/features/tech-log/adapters/http/http-management-gateway.ts +++ b/src/features/tech-log/adapters/http/http-management-gateway.ts @@ -157,6 +157,7 @@ export function createHttpManagementGateway( REFERENCE: "deleteReferenceDraft", QUESTION: "deleteQuestion", CONCEPT: "deleteConceptDraft", + SETUP: "deleteSetupDraft", }; await run(OPERATIONS[kind], { id, expectedVersion }); }, diff --git a/src/features/tech-log/adapters/http/http-public-content-gateway.ts b/src/features/tech-log/adapters/http/http-public-content-gateway.ts index 259038d..6b4cded 100644 --- a/src/features/tech-log/adapters/http/http-public-content-gateway.ts +++ b/src/features/tech-log/adapters/http/http-public-content-gateway.ts @@ -188,6 +188,7 @@ export function createHttpPublicContentGateway( REFERENCE: "getPublicReference", QUESTION: "getPublicQuestion", CONCEPT: "getPublicConcept", + SETUP: "getPublicSetup", }; const operationId = OPERATIONS[kind]; const detail = await read>>(operationId, { slug }); diff --git a/src/features/tech-log/adapters/http/public-content-mapping.ts b/src/features/tech-log/adapters/http/public-content-mapping.ts index b9c69d5..9b9efce 100644 --- a/src/features/tech-log/adapters/http/public-content-mapping.ts +++ b/src/features/tech-log/adapters/http/public-content-mapping.ts @@ -1,6 +1,7 @@ import type { CaseRecord, ConceptRecord, + SetupRecord, ProjectActivity, ProjectDecision, PublicRecord, @@ -232,6 +233,7 @@ const KNOWLEDGE_LIST_KINDS: Record = { CASE: "CASE", CONCEPT: "CONCEPT", REFERENCE: "REFERENCE", + SETUP: "SETUP", }; export function knowledgeListItemToRecord(item: Readonly>): PublicRecord | null { @@ -263,6 +265,17 @@ export function knowledgeListItemToRecord(item: Readonly sections: Object.freeze([]), }) as CaseRecord; } + if (type === "SETUP") { + return Object.freeze({ + ...base, + kind: "SETUP", + pinnedVersions: Object.freeze([]), + // 목록 항목은 본문을 담지 않는다 — 본문은 상세 조회에서만 온다. + content: "", + bodyAssets: Object.freeze([]), + sections: Object.freeze([]), + }) as SetupRecord; + } if (type === "CONCEPT") { return Object.freeze({ ...base, diff --git a/src/features/tech-log/adapters/mock/validate-working-copy.ts b/src/features/tech-log/adapters/mock/validate-working-copy.ts index af9875b..8e2c266 100644 --- a/src/features/tech-log/adapters/mock/validate-working-copy.ts +++ b/src/features/tech-log/adapters/mock/validate-working-copy.ts @@ -61,6 +61,7 @@ function runtimeShapeErrors(value: unknown): FieldError[] { REFERENCE: ["purpose", "rules", "applyWhen", "exceptions", "examples", "verifiedOn"], QUESTION: ["questionStatus", "facts", "assumptions", "unknowns", "constraints", "options", "nextValidation", "resolution"], PROJECT_DECISION: ["decisionStatus", "decidedOn", "statement", "rationale", "consequences"], + SETUP: ["bodyMarkdown", "pinnedVersions"], }; const known = Object.hasOwn(BRANCH_FIELDS, kind as string); const branch = known ? BRANCH_FIELDS[kind as RecordKind] : []; @@ -68,7 +69,7 @@ function runtimeShapeErrors(value: unknown): FieldError[] { const allowed = new Set([...base, ...optional, ...branch]); for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push({ path: `/${escape(key)}`, message: "Additional properties are not allowed." }); for (const key of [...base, ...branch]) if (!Object.hasOwn(value, key)) errors.push({ path: `/${key}`, message: "Field is required." }); - const stringFields = ["title", "slug", "summary", ...(kind === "CASE" ? ["problem", "conclusion", "environment", "reproduction", "bodyMarkdown"] : []), ...(kind === "CONCEPT" ? ["bodyMarkdown", "basisVersion"] : []), ...(kind === "REFERENCE" ? ["purpose"] : []), ...(kind === "QUESTION" ? ["nextValidation"] : []), ...(kind === "PROJECT_DECISION" ? ["statement", "rationale"] : [])]; + const stringFields = ["title", "slug", "summary", ...(kind === "CASE" ? ["problem", "conclusion", "environment", "reproduction", "bodyMarkdown"] : []), ...(kind === "CONCEPT" ? ["bodyMarkdown", "basisVersion"] : []), ...(kind === "REFERENCE" ? ["purpose"] : []), ...(kind === "QUESTION" ? ["nextValidation"] : []), ...(kind === "PROJECT_DECISION" ? ["statement", "rationale"] : []), ...(kind === "SETUP" ? ["bodyMarkdown"] : [])]; for (const key of stringFields) if (Object.hasOwn(value, key) && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a string." }); for (const key of ["topicId", "projectId"]) if (Object.hasOwn(value, key) && value[key] !== null && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a UUID or null." }); for (const key of ["lastVerifiedOn", "verifiedOn", "decidedOn"]) if (Object.hasOwn(value, key) && value[key] !== null && typeof value[key] !== "string") errors.push({ path: `/${key}`, message: "Must be a date or null." }); @@ -103,6 +104,9 @@ function runtimeShapeErrors(value: unknown): FieldError[] { if (kind === "PROJECT_DECISION") { checkArray("consequences", { id: "string", text: "string", order: "number" }); } + if (kind === "SETUP") { + checkArray("pinnedVersions", { name: "string", version: "string" }); + } return errors.filter((entry, index) => errors.findIndex(({ path }) => path === entry.path) === index); } @@ -166,6 +170,12 @@ export function validateWorkingCopyInputStructure(input: WorkingCopyInput): Fiel } else if (input.kind === "CONCEPT") { text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000); text(errors, "/basisVersion", input.basisVersion, 120); + } else if (input.kind === "SETUP") { + text(errors, "/bodyMarkdown", input.bodyMarkdown, 100_000); + for (const [index, pinned] of input.pinnedVersions.entries()) { + text(errors, `/pinnedVersions/${index}/name`, pinned.name, 60, 1); + text(errors, `/pinnedVersions/${index}/version`, pinned.version, 40, 1); + } } else { text(errors, "/statement", input.statement, 100_000); text(errors, "/rationale", input.rationale, 100_000); @@ -233,6 +243,16 @@ export function validateWorkingCopy(document: WorkingCopy, dependencies: Validat } else if (document.kind === "CONCEPT") { // 개념은 본문이 전부다. 비어 있으면 제목만 있는 글이 공개된다. if (blank(document.bodyMarkdown)) warning("BODY_REQUIRED", "/bodyMarkdown", "본문을 입력하세요."); + } else if (document.kind === "SETUP") { + /* + 셋업은 절차가 전부다. 본문이 비면 따라 할 것이 없다. + + 프로젝트는 오류다 — 셋업은 언제나 어떤 프로젝트의 셋업이고, 프로젝트가 없으면 어느 + 코드를 띄우는 절차인지 알 수 없다. 주제는 비어도 된다: 주제 없는 셋업이 그 프로젝트의 + 공통 구성이다. + */ + if (blank(document.bodyMarkdown)) error("BODY_REQUIRED", "/bodyMarkdown", "절차를 입력하세요."); + if (!document.projectId) error("PROJECT_REQUIRED", "/projectId", "프로젝트가 필요합니다."); } else { if (!document.decisionStatus) warning("DECISION_STATUS_REQUIRED", "/decisionStatus", "결정 상태가 필요합니다."); if (!document.decidedOn) warning("DECIDED_ON_REQUIRED", "/decidedOn", "결정일이 필요합니다."); diff --git a/src/features/tech-log/adapters/static/public-content.ts b/src/features/tech-log/adapters/static/public-content.ts index 3d5fa18..bc81a24 100644 --- a/src/features/tech-log/adapters/static/public-content.ts +++ b/src/features/tech-log/adapters/static/public-content.ts @@ -1,4 +1,4 @@ -export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT"; +export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP"; export type QuestionStatus = | "OPEN" | "INVESTIGATING" @@ -121,11 +121,24 @@ export type ConceptRecord = PublicRecordBase & { sections: ReadonlyArray; }; +/** + * 환경 구성. 다른 종류가 끝난 일을 적는 것과 달리 따라 하는 절차를 적는다. 낡음은 검증일이 + * 아니라 고정한 버전들이 말한다. 주제가 없어도 되는 유일한 종류다. + */ +export type SetupRecord = PublicRecordBase & { + kind: "SETUP"; + pinnedVersions: ReadonlyArray<{ name: string; version: string }>; + content: string; + bodyAssets: ReadonlyArray; + sections: ReadonlyArray; +}; + export type PublicRecord = | CaseRecord | ReferenceRecord | QuestionRecord - | ConceptRecord; + | ConceptRecord + | SetupRecord; export type ProjectDecision = { id: string; diff --git a/src/features/tech-log/application/ports/management-gateway.ts b/src/features/tech-log/application/ports/management-gateway.ts index 0196fcf..3987580 100644 --- a/src/features/tech-log/application/ports/management-gateway.ts +++ b/src/features/tech-log/application/ports/management-gateway.ts @@ -26,7 +26,7 @@ import type { * 수 없는 주제를 화면이 보여주게 된다. */ /** 이 게이트웨이로 지울 수 있는 문서 종류. 결정은 프로젝트 경로를 요구하므로 별도 메서드다. */ -export type DeletableDocumentKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT"; +export type DeletableDocumentKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP"; export type ManagementGateway = Readonly<{ listTopics(): Promise; diff --git a/src/features/tech-log/application/ports/public-content-queries.ts b/src/features/tech-log/application/ports/public-content-queries.ts index 765ed01..d26336e 100644 --- a/src/features/tech-log/application/ports/public-content-queries.ts +++ b/src/features/tech-log/application/ports/public-content-queries.ts @@ -1,4 +1,8 @@ -export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT"; +/* + 화면이 다루는 기록 종류. Studio 계약의 `RecordKind` 와 같은 집합이어야 한다 — 다만 결정은 + 자기 상세 화면이 없어 여기 없다. +*/ +export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP"; export type QuestionStatus = | "OPEN" @@ -130,11 +134,29 @@ export type ConceptRecord = PublicRecordBase & { sections: ReadonlyArray; }; +/** + * 환경 구성. + * + *

다른 종류가 끝난 일을 적는 것과 달리, 이 종류만 읽는 사람이 그대로 따라 하는 절차를 적는다. + * 낡음은 검증일도 한 줄짜리 기준 버전도 아니라 이름·버전 쌍의 목록이 말한다 — 이 절차가 + * 성립한 버전들이 곧 유효 범위다. + */ +export type SetupRecord = PublicRecordBase & { + kind: "SETUP"; + /** 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다. */ + pinnedVersions: ReadonlyArray<{ name: string; version: string }>; + /** 본문 Markdown 원문. Case 와 같은 규칙으로 `:::evidence` 가 도식을 끌어온다. */ + content: string; + bodyAssets: ReadonlyArray; + sections: ReadonlyArray; +}; + export type PublicRecord = | CaseRecord | ReferenceRecord | QuestionRecord - | ConceptRecord; + | ConceptRecord + | SetupRecord; export type ProjectDecision = { id: string; diff --git a/src/features/tech-log/contracts/management/canonical-source.json b/src/features/tech-log/contracts/management/canonical-source.json index dac36bb..18ab87d 100644 --- a/src/features/tech-log/contracts/management/canonical-source.json +++ b/src/features/tech-log/contracts/management/canonical-source.json @@ -1,8 +1,8 @@ { "packageId": "@tech-log/management-contract", "version": "1.0.0", - "digest": "sha256:fa91ee5069c1117cd328e582044e1d4f9a0787634d75d7b048f812336ebbba18", - "sourceRevision": "1aae8dc", + "digest": "sha256:0c226600c45b06433480a8a2ef3d812480dce3850c333bfcab5f626143ce77ea", + "sourceRevision": "1249527", "operationIds": [ "createCaseDraft", "getCaseForEdit", @@ -13,6 +13,7 @@ "updateReferenceDraft", "deleteReferenceDraft", "deleteConceptDraft", + "deleteSetupDraft", "validateCase", "submitReviewCase", "returnToDraftCase", diff --git a/src/features/tech-log/contracts/management/generated.ts b/src/features/tech-log/contracts/management/generated.ts index b64c446..4a453cb 100644 --- a/src/features/tech-log/contracts/management/generated.ts +++ b/src/features/tech-log/contracts/management/generated.ts @@ -88,6 +88,26 @@ export interface paths { patch?: never; trace?: never; }; + "/api/v1/studio/setups/{id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + post?: never; + /** @description 환경 구성 작업본을 지운다. Case·Reference·개념과 같은 `document` 테이블을 쓰므로 + * 같은 유스케이스가 처리하며 `document_type` 으로만 갈린다. 공개된 셋업은 지우지 + * 않는다 — 공개 취소가 그 경로다. + * */ + delete: operations["deleteSetupDraft"]; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/api/v1/studio/cases/{id}/validate": { parameters: { query?: never; @@ -1098,7 +1118,7 @@ export interface components { }; RelatedEntry: { /** @enum {string} */ - type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE"; + type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "PROJECT_DECISION" | "RELEASE"; title: string; summary?: string; path: string; @@ -2488,6 +2508,59 @@ export interface operations { }; }; }; + deleteSetupDraft: { + parameters: { + query?: never; + header: { + "X-CSRF-TOKEN": components["parameters"]["CsrfToken"]; + }; + path: { + id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["ExpectedVersionRequest"]; + }; + }; + responses: { + /** @description No Content */ + 204: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["ProblemDetails"]; + }; + }; + /** @description Not Found */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["ProblemDetails"]; + }; + }; + /** @description Conflict */ + 409: { + headers: { + [name: string]: unknown; + }; + content: { + "application/problem+json": components["schemas"]["ProblemDetails"]; + }; + }; + }; + }; validateCase: { parameters: { query?: never; diff --git a/src/features/tech-log/contracts/management/management-api.openapi.yaml b/src/features/tech-log/contracts/management/management-api.openapi.yaml index 87b34d3..d053182 100644 --- a/src/features/tech-log/contracts/management/management-api.openapi.yaml +++ b/src/features/tech-log/contracts/management/management-api.openapi.yaml @@ -603,6 +603,52 @@ paths: $ref: '#/components/schemas/ProblemDetails' security: - sessionCookie: [] + /api/v1/studio/setups/{id}: + delete: + operationId: deleteSetupDraft + tags: + - Setups + description: | + 환경 구성 작업본을 지운다. Case·Reference·개념과 같은 `document` 테이블을 쓰므로 + 같은 유스케이스가 처리하며 `document_type` 으로만 갈린다. 공개된 셋업은 지우지 + 않는다 — 공개 취소가 그 경로다. + parameters: + - name: id + in: path + required: true + schema: + type: string + format: uuid + - $ref: '#/components/parameters/CsrfToken' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExpectedVersionRequest' + responses: + '204': + description: No Content + '400': + description: Bad Request + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + '404': + description: Not Found + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + '409': + description: Conflict + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' + security: + - sessionCookie: [] /api/v1/studio/cases/{id}/validate: post: operationId: validateCase @@ -5973,6 +6019,7 @@ components: - REFERENCE - QUESTION - CONCEPT + - SETUP - PROJECT - PROJECT_DECISION - RELEASE diff --git a/src/features/tech-log/contracts/public/canonical-source.json b/src/features/tech-log/contracts/public/canonical-source.json index d90ffca..9019e62 100644 --- a/src/features/tech-log/contracts/public/canonical-source.json +++ b/src/features/tech-log/contracts/public/canonical-source.json @@ -1,8 +1,8 @@ { "packageId": "@tech-log/public-contract", "version": "2.1.0", - "digest": "sha256:957cd1aa02ddde85420ea959c241ba7898fad6563db28d36dc0b364c2c545b03", - "sourceRevision": "1aae8dc", + "digest": "sha256:0159d7b834d69252c6edcb5102166084769a58fe1c36764958b90511bb5ec2cc", + "sourceRevision": "1249527", "operationIds": [ "getPublicSite", "getPublicHome", @@ -13,6 +13,7 @@ "getPublicCase", "getPublicReference", "getPublicConcept", + "getPublicSetup", "getPublicQuestion", "listPublicProjects", "getPublicProject", diff --git a/src/features/tech-log/contracts/public/generated.ts b/src/features/tech-log/contracts/public/generated.ts index a60e744..ac1f0ee 100644 --- a/src/features/tech-log/contracts/public/generated.ts +++ b/src/features/tech-log/contracts/public/generated.ts @@ -163,6 +163,22 @@ export interface paths { patch?: never; trace?: never; }; + "/setups/{slug}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get: operations["getPublicSetup"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/questions/{slug}": { parameters: { query?: never; @@ -415,7 +431,7 @@ export interface components { }; RelatedEntry: { /** @enum {string} */ - type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE"; + type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "PROJECT_DECISION" | "RELEASE"; title: string; summary?: string; /** @description 작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에 @@ -476,7 +492,7 @@ export interface components { }; LatestEntry: { /** @enum {string} */ - entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT_ACTIVITY" | "RELEASE"; + entryType: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT_ACTIVITY" | "RELEASE"; title: string; summary: string; path: string; @@ -497,7 +513,7 @@ export interface components { }; KnowledgeListItem: { /** @enum {string} */ - type: "CASE" | "REFERENCE" | "CONCEPT"; + type: "CASE" | "REFERENCE" | "CONCEPT" | "SETUP"; title: string; path: string; primarySummary: string; @@ -659,6 +675,50 @@ export interface components { data: components["schemas"]["ConceptDetailResponse"]; meta: components["schemas"]["ResponseMeta"]; }; + /** @description 환경 구성은 끝난 일이 아니라 따라 하는 절차다. 낡음은 검증일이 아니라 + * `pinnedVersions` 가 말한다 — 어느 버전 위에서 이 절차가 성립했는지가 유효 범위다. + * 주제는 없을 수 있다. 주제 없는 셋업은 그 프로젝트의 공통 구성이다. + * */ + SetupDetailResponse: { + canonicalPath: string; + /** @default true */ + indexable: boolean; + setup: { + title: string; + summary: string; + /** @description 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다. */ + pinnedVersions: { + name: string; + version: string; + }[]; + content: string; + /** @enum {string} */ + contentFormat: "MARKDOWN"; + contentFormatVersion: number; + /** @description 본문이 참조하는 Asset. Case 와 같은 규칙이다 — 원문에는 + * `:::evidence key="…"` 만 남고 URL 은 이 목록이 준다. + * */ + bodyAssets: components["schemas"]["BodyAsset"][]; + primaryTopic?: components["schemas"]["TopicSummary"]; + primaryProject?: components["schemas"]["ProjectSummary"]; + tags: components["schemas"]["TagSummary"][]; + coverAsset?: components["schemas"]["AssetReference"]; + /** Format: date-time */ + publishedAt: string; + /** Format: date-time */ + updatedAt: string; + }; + relations: { + primaryProject?: components["schemas"]["RelatedEntry"]; + relatedRecords: components["schemas"]["RelatedEntry"][]; + }; + }; + SetupDetailResponseEnvelope: { + /** @constant */ + success: true; + data: components["schemas"]["SetupDetailResponse"]; + meta: components["schemas"]["ResponseMeta"]; + }; ReferenceDetailResponse: { canonicalPath: string; /** @default true */ @@ -823,7 +883,7 @@ export interface components { * */ ProjectRecordItem: { /** @enum {string} */ - type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT"; + type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP"; title: string; path: string; summary: string; @@ -1121,7 +1181,7 @@ export interface operations { exploreKnowledge: { parameters: { query?: { - type?: "CASE" | "REFERENCE" | "CONCEPT"; + type?: "CASE" | "REFERENCE" | "CONCEPT" | "SETUP"; topic?: string; /** @description 주제 안의 축 slug. 그 축에 걸린 기록만 남긴다. `topic` 과 함께 준다 — 축 slug 는 * 주제 안에서만 유일하다. @@ -1408,6 +1468,37 @@ export interface operations { }; }; }; + getPublicSetup: { + parameters: { + query?: never; + header?: never; + path: { + slug: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description OK */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["SetupDetailResponseEnvelope"]; + }; + }; + /** @description Not Found */ + 404: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ErrorEnvelope"]; + }; + }; + }; + }; getPublicQuestion: { parameters: { query?: never; @@ -1573,7 +1664,7 @@ export interface operations { listPublicProjectRecords: { parameters: { query?: { - type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT"; + type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP"; relation?: "PRIMARY" | "RELATED"; page?: number; size?: number; @@ -1787,7 +1878,7 @@ export interface operations { parameters: { query: { q: string; - type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "RELEASE"; + type?: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "SETUP" | "PROJECT" | "RELEASE"; topic?: string; page?: number; size?: number; diff --git a/src/features/tech-log/contracts/public/public-api.openapi.yaml b/src/features/tech-log/contracts/public/public-api.openapi.yaml index d1f8f45..d97ea6d 100644 --- a/src/features/tech-log/contracts/public/public-api.openapi.yaml +++ b/src/features/tech-log/contracts/public/public-api.openapi.yaml @@ -115,6 +115,7 @@ paths: - CASE - REFERENCE - CONCEPT + - SETUP - name: topic in: query schema: @@ -390,6 +391,30 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + /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' /questions/{slug}: get: operationId: getPublicQuestion @@ -530,6 +555,7 @@ paths: - REFERENCE - QUESTION - CONCEPT + - SETUP - name: relation in: query schema: @@ -696,6 +722,7 @@ paths: - REFERENCE - QUESTION - CONCEPT + - SETUP - PROJECT - RELEASE - name: topic @@ -917,6 +944,7 @@ components: - REFERENCE - QUESTION - CONCEPT + - SETUP - PROJECT - PROJECT_DECISION - RELEASE @@ -1083,6 +1111,7 @@ components: - REFERENCE - QUESTION - CONCEPT + - SETUP - PROJECT_ACTIVITY - RELEASE title: @@ -1139,6 +1168,7 @@ components: - CASE - REFERENCE - CONCEPT + - SETUP title: type: string path: @@ -1513,6 +1543,112 @@ components: $ref: '#/components/schemas/ConceptDetailResponse' meta: $ref: '#/components/schemas/ResponseMeta' + SetupDetailResponse: + type: object + description: | + 환경 구성은 끝난 일이 아니라 따라 하는 절차다. 낡음은 검증일이 아니라 + `pinnedVersions` 가 말한다 — 어느 버전 위에서 이 절차가 성립했는지가 유효 범위다. + 주제는 없을 수 있다. 주제 없는 셋업은 그 프로젝트의 공통 구성이다. + required: + - canonicalPath + - indexable + - setup + - relations + properties: + canonicalPath: + type: string + indexable: + type: boolean + default: true + setup: + type: object + required: + - title + - summary + - pinnedVersions + - content + - contentFormat + - contentFormatVersion + - bodyAssets + - tags + - publishedAt + - updatedAt + properties: + title: + type: string + summary: + type: string + pinnedVersions: + type: array + description: 이 절차가 성립한 버전. 비면 화면에 표를 그리지 않는다. + items: + type: object + additionalProperties: false + required: + - name + - version + properties: + name: + type: string + version: + type: string + content: + type: string + contentFormat: + type: string + enum: + - MARKDOWN + contentFormatVersion: + type: integer + bodyAssets: + type: array + description: | + 본문이 참조하는 Asset. Case 와 같은 규칙이다 — 원문에는 + `:::evidence key="…"` 만 남고 URL 은 이 목록이 준다. + items: + $ref: '#/components/schemas/BodyAsset' + primaryTopic: + $ref: '#/components/schemas/TopicSummary' + primaryProject: + $ref: '#/components/schemas/ProjectSummary' + tags: + type: array + items: + $ref: '#/components/schemas/TagSummary' + coverAsset: + $ref: '#/components/schemas/AssetReference' + publishedAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + relations: + type: object + required: + - relatedRecords + properties: + primaryProject: + $ref: '#/components/schemas/RelatedEntry' + relatedRecords: + type: array + items: + $ref: '#/components/schemas/RelatedEntry' + SetupDetailResponseEnvelope: + type: object + additionalProperties: false + required: + - success + - data + - meta + properties: + success: + type: boolean + const: true + data: + $ref: '#/components/schemas/SetupDetailResponse' + meta: + $ref: '#/components/schemas/ResponseMeta' ReferenceDetailResponse: type: object required: @@ -1918,6 +2054,7 @@ components: - REFERENCE - QUESTION - CONCEPT + - SETUP title: type: string path: diff --git a/src/features/tech-log/contracts/studio/canonical-source.json b/src/features/tech-log/contracts/studio/canonical-source.json index 144486b..c9871a2 100644 --- a/src/features/tech-log/contracts/studio/canonical-source.json +++ b/src/features/tech-log/contracts/studio/canonical-source.json @@ -1,8 +1,8 @@ { "packageId": "@tech-log/studio-contract", "version": "3.1.0", - "digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c", - "sourceRevision": "1aae8dc", + "digest": "sha256:035b07f07eb0d26062b940a3652960444274f34ac9cb273391a3df2326ed14a8", + "sourceRevision": "1249527", "operationIds": [ "getStudioSession", "getStudioDashboard", diff --git a/src/features/tech-log/contracts/studio/generated.ts b/src/features/tech-log/contracts/studio/generated.ts index 7fbbca1..7e1dd34 100644 --- a/src/features/tech-log/contracts/studio/generated.ts +++ b/src/features/tech-log/contracts/studio/generated.ts @@ -520,7 +520,7 @@ export interface components { * * @enum {string} */ - RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION" | "CONCEPT"; + RecordKind: "CASE" | "REFERENCE" | "QUESTION" | "PROJECT_DECISION" | "CONCEPT" | "SETUP"; /** @enum {string} */ PublicationStatus: "NEVER_PUBLISHED" | "PUBLISHED" | "UNPUBLISHED"; /** @@ -627,6 +627,13 @@ export interface components { */ kind: "REFERENCE"; }; + /** @description 이 셋업이 어느 버전을 기준으로 쓰였는지. "Keycloak" / "26.7.0" 처럼 이름과 버전을 + * 나눠 담는다. 목록과 머리말이 본문을 열지 않고 보여 주는 값이라 본문에 두지 않는다. + * */ + PinnedVersion: { + name: string; + version: string; + }; ConceptInput: components["schemas"]["WorkingCopyInputBase"] & { /** @enum {string} */ kind: "CONCEPT"; @@ -645,6 +652,22 @@ export interface components { */ kind: "CONCEPT"; }; + SetupInput: components["schemas"]["WorkingCopyInputBase"] & { + /** @enum {string} */ + kind: "SETUP"; + /** @description Markdown 원문. 실행 절차·구성 값·확인 방법을 `##` 절로 적는다. 절 이름을 + * 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. Asset은 + * `:::evidence key=""` directive로 참조한다. + * */ + bodyMarkdown: string; + pinnedVersions: components["schemas"]["PinnedVersion"][]; + } & { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: "SETUP"; + }; QuestionInput: components["schemas"]["WorkingCopyInputBase"] & { /** @enum {string} */ kind: "QUESTION"; @@ -695,7 +718,7 @@ export interface components { */ kind: "PROJECT_DECISION"; }; - WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"] | components["schemas"]["ConceptInput"]; + WorkingCopyInput: components["schemas"]["CaseInput"] | components["schemas"]["ReferenceInput"] | components["schemas"]["QuestionInput"] | components["schemas"]["ProjectDecisionInput"] | components["schemas"]["ConceptInput"] | components["schemas"]["SetupInput"]; WorkingCopyBase: components["schemas"]["WorkingCopyInputBase"] & { /** * Format: uuid @@ -753,6 +776,18 @@ export interface components { */ kind: "CONCEPT"; }; + SetupWorkingCopy: components["schemas"]["WorkingCopyBase"] & { + /** @enum {string} */ + kind: "SETUP"; + bodyMarkdown: string; + pinnedVersions: components["schemas"]["PinnedVersion"][]; + } & { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: "SETUP"; + }; QuestionWorkingCopy: components["schemas"]["WorkingCopyBase"] & { /** @enum {string} */ kind: "QUESTION"; @@ -798,9 +833,10 @@ export interface components { * | QuestionWorkingCopy * | ProjectDecisionWorkingCopy * | ConceptWorkingCopy + * | SetupWorkingCopy * ``` * */ - WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"] | components["schemas"]["ConceptWorkingCopy"]; + WorkingCopy: components["schemas"]["CaseWorkingCopy"] | components["schemas"]["ReferenceWorkingCopy"] | components["schemas"]["QuestionWorkingCopy"] | components["schemas"]["ProjectDecisionWorkingCopy"] | components["schemas"]["ConceptWorkingCopy"] | components["schemas"]["SetupWorkingCopy"]; CreateDocumentInput: components["schemas"]["WorkingCopyInput"]; SaveDocumentCommand: { expectedVersion: number; @@ -1184,6 +1220,18 @@ export interface components { */ kind: "CONCEPT"; }; + SetupPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & { + /** @enum {string} */ + kind: "SETUP"; + pinnedVersions: components["schemas"]["PinnedVersion"][]; + bodyBlocks: components["schemas"]["CaseRenderBlock"][]; + } & { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: "SETUP"; + }; QuestionPublicRenderModel: components["schemas"]["PublicRenderModelBase"] & { /** @enum {string} */ kind: "QUESTION"; @@ -1223,7 +1271,7 @@ export interface components { */ kind: "PROJECT_DECISION"; }; - PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"] | components["schemas"]["ConceptPublicRenderModel"]; + PublicRenderModel: components["schemas"]["CasePublicRenderModel"] | components["schemas"]["ReferencePublicRenderModel"] | components["schemas"]["QuestionPublicRenderModel"] | components["schemas"]["ProjectDecisionPublicRenderModel"] | components["schemas"]["ConceptPublicRenderModel"] | components["schemas"]["SetupPublicRenderModel"]; PublicPreview: { /** Format: uuid */ previewId: string; diff --git a/src/features/tech-log/contracts/studio/studio-api.openapi.yaml b/src/features/tech-log/contracts/studio/studio-api.openapi.yaml index 8e2abf6..56d6560 100644 --- a/src/features/tech-log/contracts/studio/studio-api.openapi.yaml +++ b/src/features/tech-log/contracts/studio/studio-api.openapi.yaml @@ -837,7 +837,7 @@ components: # ------------------------------------------------------------ enumerations RecordKind: type: string - enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT] + enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT, SETUP] description: | Studio 편집 대상 유형. API projection discriminator이며 Domain Aggregate가 아니다. `PROJECT_DECISION`은 `ProjectDecision` capability로 dispatch된다. @@ -961,6 +961,16 @@ components: exceptions: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } } examples: { type: array, maxItems: 50, items: { $ref: "#/components/schemas/OrderedText" } } verifiedOn: { type: [string, "null"], format: date } + 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 } ConceptInput: unevaluatedProperties: false allOf: @@ -981,6 +991,25 @@ components: description: | "Kubernetes 1.31" 처럼 이 글이 무엇을 보고 쓴 것인지 한 줄. 개념이 낡는 방식은 날짜가 아니라 버전이므로 `lastVerifiedOn` 대신 이것을 둔다. 비워도 된다. + 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=""` directive로 참조한다. + pinnedVersions: + type: array + maxItems: 30 + items: { $ref: "#/components/schemas/PinnedVersion" } QuestionInput: unevaluatedProperties: false allOf: @@ -1039,6 +1068,7 @@ components: - { $ref: "#/components/schemas/QuestionInput" } - { $ref: "#/components/schemas/ProjectDecisionInput" } - { $ref: "#/components/schemas/ConceptInput" } + - { $ref: "#/components/schemas/SetupInput" } discriminator: propertyName: kind mapping: @@ -1047,6 +1077,7 @@ components: QUESTION: "#/components/schemas/QuestionInput" PROJECT_DECISION: "#/components/schemas/ProjectDecisionInput" CONCEPT: "#/components/schemas/ConceptInput" + SETUP: "#/components/schemas/SetupInput" # ------------------------------------------------------- working copy output WorkingCopyBase: @@ -1100,6 +1131,19 @@ components: kind: { type: string, enum: [CONCEPT] } bodyMarkdown: { type: string, maxLength: 100000 } basisVersion: { type: string, maxLength: 120 } + 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" } QuestionWorkingCopy: unevaluatedProperties: false allOf: @@ -1143,6 +1187,7 @@ components: | QuestionWorkingCopy | ProjectDecisionWorkingCopy | ConceptWorkingCopy + | SetupWorkingCopy ``` oneOf: - { $ref: "#/components/schemas/CaseWorkingCopy" } @@ -1150,6 +1195,7 @@ components: - { $ref: "#/components/schemas/QuestionWorkingCopy" } - { $ref: "#/components/schemas/ProjectDecisionWorkingCopy" } - { $ref: "#/components/schemas/ConceptWorkingCopy" } + - { $ref: "#/components/schemas/SetupWorkingCopy" } discriminator: propertyName: kind mapping: @@ -1158,6 +1204,7 @@ components: QUESTION: "#/components/schemas/QuestionWorkingCopy" PROJECT_DECISION: "#/components/schemas/ProjectDecisionWorkingCopy" CONCEPT: "#/components/schemas/ConceptWorkingCopy" + SETUP: "#/components/schemas/SetupWorkingCopy" # -------------------------------------------------------------- commands CreateDocumentInput: { $ref: "#/components/schemas/WorkingCopyInput" } @@ -1596,6 +1643,19 @@ components: kind: { type: string, enum: [CONCEPT] } basisVersion: { type: string, maxLength: 120 } bodyBlocks: { type: array, maxItems: 10000, items: { $ref: "#/components/schemas/CaseRenderBlock" } } + 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" } } QuestionPublicRenderModel: unevaluatedProperties: false allOf: @@ -1641,6 +1701,7 @@ components: - { $ref: "#/components/schemas/QuestionPublicRenderModel" } - { $ref: "#/components/schemas/ProjectDecisionPublicRenderModel" } - { $ref: "#/components/schemas/ConceptPublicRenderModel" } + - { $ref: "#/components/schemas/SetupPublicRenderModel" } discriminator: propertyName: kind mapping: @@ -1649,6 +1710,7 @@ components: QUESTION: "#/components/schemas/QuestionPublicRenderModel" PROJECT_DECISION: "#/components/schemas/ProjectDecisionPublicRenderModel" CONCEPT: "#/components/schemas/ConceptPublicRenderModel" + SETUP: "#/components/schemas/SetupPublicRenderModel" # ---------------------------------------------------------------- preview PublicPreview: diff --git a/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts b/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts index 986361e..f01f5ed 100644 --- a/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts +++ b/src/features/tech-log/contracts/tech-log-management-contract-contribution.ts @@ -526,6 +526,25 @@ const HTTP_CONTRACTS = Object.freeze([ }); }, ), + writeOperation( + "deleteSetupDraft", + "DELETE", + `${D}/setups/{id}`, + { + acceptedStatuses: [204], + emptyBodyStatuses: [204], + requestByteLimit: 1_024, + responseByteLimit: 1_024, + }, + (input: never) => { + const value = input as unknown as Readonly<{ id: string; expectedVersion: number }>; + return Object.freeze({ + pathValues: Object.freeze({ id: value.id }), + queryEntries: NO_QUERY, + body: { expectedVersion: value.expectedVersion }, + }); + }, + ), writeOperation( "deleteCaseDraft", "DELETE", diff --git a/src/features/tech-log/contracts/tech-log-public-contract-contribution.ts b/src/features/tech-log/contracts/tech-log-public-contract-contribution.ts index a731990..faada8a 100644 --- a/src/features/tech-log/contracts/tech-log-public-contract-contribution.ts +++ b/src/features/tech-log/contracts/tech-log-public-contract-contribution.ts @@ -128,6 +128,7 @@ const HTTP_CONTRACTS = Object.freeze([ publicRead("getPublicReference", `${P}/references/{slug}`, 524_288, bySlug), publicRead("getPublicQuestion", `${P}/questions/{slug}`, 524_288, bySlug), publicRead("getPublicConcept", `${P}/concepts/{slug}`, 524_288, bySlug), + publicRead("getPublicSetup", `${P}/setups/{slug}`, 524_288, bySlug), publicRead("listPublicProjects", `${P}/projects`, 262_144), publicRead("getPublicProject", `${P}/projects/{slug}`, 262_144, bySlug), publicRead("listPublicProjectDecisions", `${P}/projects/{slug}/decisions`, 262_144, bySlug), diff --git a/src/features/tech-log/contracts/tech-log-route-contract.ts b/src/features/tech-log/contracts/tech-log-route-contract.ts index a543228..6d77a2c 100644 --- a/src/features/tech-log/contracts/tech-log-route-contract.ts +++ b/src/features/tech-log/contracts/tech-log-route-contract.ts @@ -28,6 +28,7 @@ const TECH_LOG_ROUTE_SPECS = [ defineSpec({ routeId: "TECH_LOG_CASE", path: "/cases/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: "TechLogCaseStateSearch", title: "Case", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_REFERENCE", path: "/references/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Reference", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_CONCEPT", path: "/concepts/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "개념", navigationLabel: null, navigationOrder: null }), + defineSpec({ routeId: "TECH_LOG_SETUP", path: "/setups/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "환경 구성", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_QUESTION", path: "/questions/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Open Question", navigationLabel: null, navigationOrder: null }), defineSpec({ routeId: "TECH_LOG_TOPICS", path: "/topics", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "주제", navigationLabel: "주제", navigationOrder: 15 }), defineSpec({ routeId: "TECH_LOG_TOPIC", path: "/topics/:slug", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "Topic", navigationLabel: null, navigationOrder: null }), diff --git a/src/features/tech-log/domain/content-format/project-public-render-model.ts b/src/features/tech-log/domain/content-format/project-public-render-model.ts index e21ce19..5d26280 100644 --- a/src/features/tech-log/domain/content-format/project-public-render-model.ts +++ b/src/features/tech-log/domain/content-format/project-public-render-model.ts @@ -7,10 +7,12 @@ import { } from "./parse-case-content.ts"; type WorkingCopyInput = components["schemas"]["WorkingCopyInput"]; +type RecordKind = components["schemas"]["RecordKind"]; type CatalogEntry = components["schemas"]["CatalogEntry"]; type PublicRenderModel = components["schemas"]["PublicRenderModel"]; type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"]; type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"]; +type SetupPublicRenderModel = components["schemas"]["SetupPublicRenderModel"]; type RenderContext = components["schemas"]["RenderContext"]; /** @@ -27,9 +29,12 @@ export type AuthoringRenderModel = | (Omit & { bodyBlocks: CaseAuthoringBlock[]; }) + | (Omit & { + bodyBlocks: CaseAuthoringBlock[]; + }) | Exclude< PublicRenderModel, - CasePublicRenderModel | ConceptPublicRenderModel + CasePublicRenderModel | ConceptPublicRenderModel | SetupPublicRenderModel >; export type ProjectionContext = @@ -43,7 +48,7 @@ export type ProjectionContext = /** * Attaches the resolved asset descriptor to every EVIDENCE_FIGURE block of the - * two kinds that carry a markdown body — CASE and CONCEPT — turning an + * kinds that carry a markdown body — CASE, CONCEPT and SETUP — turning an * `AuthoringRenderModel` into a genuine `PublicRenderModel`. Callers own the * actual asset catalog (a mock gateway's static registry, a preview's own * fixture data, ...), so this stays a pure mapping over a supplied resolver. @@ -52,7 +57,7 @@ export function resolveCaseEvidenceAssets( model: AuthoringRenderModel, resolveAsset: (key: string) => components["schemas"]["ResolvedAsset"], ): PublicRenderModel { - if (model.kind !== "CASE" && model.kind !== "CONCEPT") return model; + if (model.kind !== "CASE" && model.kind !== "CONCEPT" && model.kind !== "SETUP") return model; return { ...model, @@ -154,15 +159,19 @@ function publicPath(input: WorkingCopyInput, project: CatalogEntry | null) { } return `${project.publicPath}/decisions#${input.slug}`; } - const prefix = - input.kind === "CASE" - ? "cases" - : input.kind === "REFERENCE" - ? "references" - : input.kind === "CONCEPT" - ? "concepts" - : "questions"; - return `/${prefix}/${input.slug}`; + /* + 삼항 사슬이던 동안 마지막 `else` 가 「나머지 전부」였다. 종류를 더하면 그 종류의 주소가 + 조용히 `/questions/…` 가 된다 — 게시는 되고 링크만 다른 곳을 가리킨다. 표로 두면 + 컴파일러가 빈 자리를 잡는다. Decision 은 위에서 먼저 돌아가므로 이 표에 없다. + */ + const PREFIXES: Record, string> = { + CASE: "cases", + REFERENCE: "references", + CONCEPT: "concepts", + QUESTION: "questions", + SETUP: "setups", + }; + return `/${PREFIXES[input.kind]}/${input.slug}`; } function resolvedRelations( @@ -210,6 +219,13 @@ export function projectWorkingCopy( if (input.kind === "PROJECT_DECISION" && !project) { fail("Decision 은 프로젝트에 속합니다. 기본 정보에서 프로젝트를 골라 주세요."); } + /* + 셋업은 언제나 어떤 프로젝트의 셋업이다. 프로젝트가 없으면 어느 코드를 띄우는 절차인지 + 화면이 말할 수 없다. 주제는 비어도 된다 — 주제 없는 셋업이 그 프로젝트의 공통 구성이다. + */ + if (input.kind === "SETUP" && !project) { + fail("환경 구성은 프로젝트에 속합니다. 기본 정보에서 프로젝트를 골라 주세요."); + } const base = { kind: input.kind, @@ -273,6 +289,30 @@ export function projectWorkingCopy( }; } + case "SETUP": { + /* + 셋업의 본문도 Case 와 같은 규칙을 탄다 — `:::evidence` 가 도식을 끌어오고, 그 키가 + 실제로 있는지 여기서 먼저 확인한다. + */ + const bodyBlocks = parseCaseContent(input.bodyMarkdown); + for (const block of bodyBlocks) { + if (block.type !== "EVIDENCE_FIGURE") continue; + if (!supportsEvidenceKey(block.key)) { + fail(`supported local evidence key not found: ${block.key}`); + } + if (!evidenceCatalogEntryFor(catalog, block.key)) { + fail(`EVIDENCE catalog entry not found: ${block.key}`); + } + } + + return { + ...base, + kind: "SETUP", + pinnedVersions: input.pinnedVersions.map((pinned) => ({ ...pinned })), + bodyBlocks, + }; + } + case "REFERENCE": return { ...base, diff --git a/src/features/tech-log/presentation/public/components/explore-filter-form.tsx b/src/features/tech-log/presentation/public/components/explore-filter-form.tsx index 0d3d79c..9864490 100644 --- a/src/features/tech-log/presentation/public/components/explore-filter-form.tsx +++ b/src/features/tech-log/presentation/public/components/explore-filter-form.tsx @@ -18,6 +18,7 @@ const EXPLORE_KIND_ORDER: Record = { REFERENCE: 2, QUESTION: 3, CONCEPT: 4, + SETUP: 5, }; export const EXPLORE_KINDS: ReadonlyArray = Object.freeze( diff --git a/src/features/tech-log/presentation/public/components/setup-document-page.tsx b/src/features/tech-log/presentation/public/components/setup-document-page.tsx new file mode 100644 index 0000000..e55742f --- /dev/null +++ b/src/features/tech-log/presentation/public/components/setup-document-page.tsx @@ -0,0 +1,81 @@ +import type { SetupRecord } from "../../../application/ports/public-content-queries.ts"; +import { + parseCaseContent, + type CaseAuthoringBlock, +} from "../../../domain/content-format/parse-case-content.ts"; +import { resolveCaseEvidenceAssets } from "../../../domain/content-format/project-public-render-model.ts"; +import { PublicRecordRenderer } from "../../shared/public-render/public-record-renderer.tsx"; +import { publicRenderModelBase } from "./public-document-header.tsx"; + +/** + * 환경 구성의 본문도 Case 와 같은 파서를 탄다 — `##` 소제목이 목차가 되고 `:::evidence` 가 + * 도식을 끌어온다. 셋업 절차에 구성도가 붙는 길이 그것뿐이다. + * + *

본문이 지원하지 않는 문법을 담고 있으면 화면 전체를 잃는 대신 빈 블록으로 돌아간다. + * 읽는 사람에게는 덜 정확한 화면이 빈 화면보다 낫다 — Case 가 쓰는 것과 같은 판단이다. + */ +function setupBodyBlocks(record: SetupRecord): CaseAuthoringBlock[] { + if (!record.content.trim()) return []; + try { + return parseCaseContent(record.content); + } catch { + return []; + } +} + +export function SetupDocumentPage({ record }: { record: SetupRecord }) { + /* + 본문은 evidence 를 key 로만 가리키고 `/media/{assetId}` 는 UUID 로만 서빙하므로, 계약이 함께 + 준 `bodyAssets` 로 key 를 주소로 바꾼다. 대응이 없는 key 는 그 블록을 지운다 — 해석기가 + 던지면 문서 전체가 사라지고, 남겨 두면 주소 없는 그림 자리가 남는다. + */ + const assetsByKey = new Map( + record.bodyAssets.map((asset) => [asset.assetKey, asset]), + ); + const blocks = setupBodyBlocks(record).filter( + (block) => block.type !== "EVIDENCE_FIGURE" || assetsByKey.has(block.key), + ); + + const model = resolveCaseEvidenceAssets( + { + ...publicRenderModelBase(record), + kind: "SETUP", + pinnedVersions: record.pinnedVersions.map((pinned) => ({ ...pinned })), + bodyBlocks: blocks, + }, + (key) => { + const asset = assetsByKey.get(key); + // 위에서 이미 걸렀다 — 여기 닿으면 필터와 해석기가 어긋난 것이다. + if (!asset) throw new Error(`setup evidence asset not found: ${key}`); + return { + assetId: asset.assetId, + assetKey: asset.assetKey, + mediaType: asset.contentType, + publicPath: asset.url, + width: asset.width, + height: asset.height, + decorative: asset.decorative, + }; + }, + ); + + return ( + { + const asset = assetsByKey.get(key); + if (!asset) throw new Error(`setup evidence asset not found: ${key}`); + return { + src: asset.url, + width: asset.width ?? 0, + height: asset.height ?? 0, + triggerLabel: `${asset.altText || asset.assetKey} 크게 보기`, + dialogLabel: asset.altText || asset.assetKey, + }; + }} + resolvePublishedLabel={(path) => + path === record.path ? record.publishedLabel : undefined + } + /> + ); +} diff --git a/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx b/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx index 22710f0..8d0dfe4 100644 --- a/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx +++ b/src/features/tech-log/presentation/public/pages/explore-kind-page.tsx @@ -14,6 +14,7 @@ const kinds = { references: { kind: "REFERENCE", title: DOCUMENT_KIND_LABELS.REFERENCE, description: "다시 확인할 수 있는 기술 기준과 적용 범위를 정리합니다." }, questions: { kind: "QUESTION", title: DOCUMENT_KIND_LABELS.QUESTION, description: "확인한 사실과 미지수, 다음 검증을 공개적으로 추적합니다." }, concepts: { kind: "CONCEPT", title: DOCUMENT_KIND_LABELS.CONCEPT, description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다." }, + setups: { kind: "SETUP", title: DOCUMENT_KIND_LABELS.SETUP, description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다." }, } as const; function optionalString(value: unknown): string | undefined { @@ -25,7 +26,8 @@ function getKindConfig(value: string | undefined) { value === "cases" || value === "references" || value === "questions" || - value === "concepts" + value === "concepts" || + value === "setups" ) { return kinds[value]; } diff --git a/src/features/tech-log/presentation/public/pages/search-page.tsx b/src/features/tech-log/presentation/public/pages/search-page.tsx index 3f5bdc6..08136d4 100644 --- a/src/features/tech-log/presentation/public/pages/search-page.tsx +++ b/src/features/tech-log/presentation/public/pages/search-page.tsx @@ -3,7 +3,7 @@ import { Link, useNavigate } from "react-router-dom"; import { useRouteInput } from "../../../../../presentation/routes/route-input.tsx"; import { usePublicContent } from "../use-public-content.tsx"; -const labels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", CONCEPT: "개념", PROJECT: "Project", RELEASE: "Release" } as const; +const labels = { CASE: "Case", REFERENCE: "Reference", QUESTION: "Open Question", CONCEPT: "개념", SETUP: "환경 구성", PROJECT: "Project", RELEASE: "Release" } as const; function optionalString(value: unknown): string | undefined { return typeof value === "string" ? value : undefined; diff --git a/src/features/tech-log/presentation/public/pages/setup-page.tsx b/src/features/tech-log/presentation/public/pages/setup-page.tsx new file mode 100644 index 0000000..865c6fc --- /dev/null +++ b/src/features/tech-log/presentation/public/pages/setup-page.tsx @@ -0,0 +1,29 @@ +import { + RegisteredNotFoundRoute, + useRouteInput, +} from "../../../../../presentation/routes/route-input.tsx"; +import { SetupDocumentPage } from "../components/setup-document-page.tsx"; +import { usePublicContent } from "../use-public-content.tsx"; + +function optionalString(value: unknown): string | undefined { + return typeof value === "string" ? value : undefined; +} + +export function SetupPage() { + const { params } = useRouteInput<"TECH_LOG_SETUP">(); + const slug = optionalString(params.slug); + const view = usePublicContent( + ["tech-log", "setup", slug], + async (queries) => ({ + record: slug ? await queries.getRecord("SETUP", slug) : undefined, + }), + ); + if (!view.ready) return view.fallback; + + const { record } = view.data; + return record ? ( + + ) : ( + + ); +} diff --git a/src/features/tech-log/presentation/shared/document-kind-labels.ts b/src/features/tech-log/presentation/shared/document-kind-labels.ts index 6a3cc01..14736b0 100644 --- a/src/features/tech-log/presentation/shared/document-kind-labels.ts +++ b/src/features/tech-log/presentation/shared/document-kind-labels.ts @@ -23,6 +23,7 @@ export const DOCUMENT_KIND_LABELS: Record = { REFERENCE: "적용 기준", PROJECT_DECISION: "설계 결정", QUESTION: "열린 질문", + SETUP: "환경 구성", }; /** @@ -38,6 +39,8 @@ export const DOCUMENT_KIND_STATES: Record = { REFERENCE: "/explore/references", QUESTION: "/explore/questions", PROJECT_DECISION: "/projects", + SETUP: "/explore/setups", }; diff --git a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx index 8d02548..d68d70b 100644 --- a/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx +++ b/src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx @@ -21,6 +21,7 @@ type PublicRenderModelBase = components["schemas"]["PublicRenderModelBase"]; type ResolvedRelation = components["schemas"]["ResolvedRelation"]; type CasePublicRenderModel = components["schemas"]["CasePublicRenderModel"]; type ConceptPublicRenderModel = components["schemas"]["ConceptPublicRenderModel"]; +type SetupPublicRenderModel = components["schemas"]["SetupPublicRenderModel"]; type ReferencePublicRenderModel = components["schemas"]["ReferencePublicRenderModel"]; type QuestionPublicRenderModel = @@ -308,6 +309,93 @@ function ConceptDocument({ ); } +/** + * 환경 구성. + * + *

개념과 같은 본문·목차·Asset 을 쓰되 머리말이 다르다. 낡음을 말하는 것이 한 줄짜리 + * 「기준」이 아니라 이름·버전 쌍의 표다 — Keycloak 과 Spring Boot 와 PostgreSQL 이 각각 + * 어느 버전이었는지가 이 절차의 유효 범위다. + * + *

주제는 없을 수 있다. 주제 없는 셋업이 그 프로젝트의 공통 구성이고, 그때는 경로에서 + * 주제 마디를 뺀다 — 빈 링크가 남으면 누를 것이 없는 자리가 생긴다. + */ +function SetupDocument({ + model, + embedded, + resolveEvidenceAsset, + resolvePublishedLabel, +}: { + model: SetupPublicRenderModel; + embedded: boolean; +} & RenderDependencies) { + const headings = model.bodyBlocks + .filter((block) => block.type === "HEADING") + .map((heading) => ({ + id: heading.id, + label: inlinePlainText(heading.content), + })); + + const Root = embedded ? "div" : "main"; + return ( + +

+ + +

{model.title}

+ + + {model.pinnedVersions.length > 0 ? ( +
+ {model.pinnedVersions.map((pinned) => ( +
+
{pinned.name}
+
{pinned.version}
+
+ ))} +
+ ) : null} + +
+
+
기록
+
게시 {publishedLabel(model, resolvePublishedLabel)}
+
+
+
+ + + +
+
+ + +
+ +
+ + ); +} + function ReferenceDocument({ model, embedded, @@ -613,6 +701,15 @@ export function PublicRecordRenderer({ resolvePublishedLabel={resolvePublishedLabel} /> ); + case "SETUP": + return ( + + ); case "PROJECT_DECISION": return ( diff --git a/src/features/tech-log/presentation/studio/components/document-editor.tsx b/src/features/tech-log/presentation/studio/components/document-editor.tsx index 7004aab..d7fcf67 100644 --- a/src/features/tech-log/presentation/studio/components/document-editor.tsx +++ b/src/features/tech-log/presentation/studio/components/document-editor.tsx @@ -11,8 +11,10 @@ import { DECISION_FIELD_PATHS, ProjectDecisionFields } from "./project-decision- import { issuesOutside } from "./field-issues.tsx"; import { QUESTION_FIELD_PATHS, QuestionFields } from "./question-fields.tsx"; import { REFERENCE_FIELD_PATHS, ReferenceFields } from "./reference-fields.tsx"; +import { SETUP_FIELD_PATHS, SetupFields } from "./setup-fields.tsx"; type CatalogEntry = components["schemas"]["CatalogEntry"]; +type RecordKind = components["schemas"]["RecordKind"]; export function DocumentEditor({ controller, @@ -44,15 +46,20 @@ export function DocumentEditor({ 남는다. */ const issues = controller.publishIssues; - const kindPaths = controller.draft.kind === "CASE" - ? CASE_FIELD_PATHS - : controller.draft.kind === "CONCEPT" - ? CONCEPT_FIELD_PATHS - : controller.draft.kind === "REFERENCE" - ? REFERENCE_FIELD_PATHS - : controller.draft.kind === "QUESTION" - ? QUESTION_FIELD_PATHS - : DECISION_FIELD_PATHS; + /* + 삼항 사슬의 마지막 else 가 「나머지 전부」였다. 종류를 더하면 그 종류의 지적이 결정의 + 칸 경로로 걸러져, 자기 칸 아래에 붙지도 게시 버튼 옆에 남지도 않고 사라진다. 표로 두면 + 컴파일러가 빈 자리를 잡는다. + */ + const KIND_PATHS: Record = { + CASE: CASE_FIELD_PATHS, + CONCEPT: CONCEPT_FIELD_PATHS, + REFERENCE: REFERENCE_FIELD_PATHS, + QUESTION: QUESTION_FIELD_PATHS, + SETUP: SETUP_FIELD_PATHS, + PROJECT_DECISION: DECISION_FIELD_PATHS, + }; + const kindPaths = KIND_PATHS[controller.draft.kind]; const unplaced = issuesOutside(issues, [...COMMON_FIELD_PATHS, ...kindPaths]); /* @@ -77,6 +84,8 @@ export function DocumentEditor({ ? : controller.draft.kind === "CONCEPT" ? + : controller.draft.kind === "SETUP" + ? : controller.draft.kind === "REFERENCE" ? : controller.draft.kind === "QUESTION" diff --git a/src/features/tech-log/presentation/studio/components/document-list.tsx b/src/features/tech-log/presentation/studio/components/document-list.tsx index e2d844f..35c8c66 100644 --- a/src/features/tech-log/presentation/studio/components/document-list.tsx +++ b/src/features/tech-log/presentation/studio/components/document-list.tsx @@ -20,7 +20,8 @@ const STUDIO_KIND_ORDER: Record = { CONCEPT: 2, REFERENCE: 3, QUESTION: 4, - PROJECT_DECISION: 5, + SETUP: 5, + PROJECT_DECISION: 6, }; const STUDIO_KINDS: ReadonlyArray = Object.freeze( diff --git a/src/features/tech-log/presentation/studio/components/new-document-form.tsx b/src/features/tech-log/presentation/studio/components/new-document-form.tsx index abd2c68..602e624 100644 --- a/src/features/tech-log/presentation/studio/components/new-document-form.tsx +++ b/src/features/tech-log/presentation/studio/components/new-document-form.tsx @@ -26,6 +26,12 @@ const types = [ description: "개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다.", fields: "기준 버전 · 본문", }, + { + kind: "SETUP", + title: "환경 구성", + description: "이 기록을 자기 손으로 재현하는 절차를 남깁니다.", + fields: "버전 · 본문", + }, { kind: "QUESTION", title: "Question", @@ -76,6 +82,18 @@ function emptyDocument(kind: RecordKind): CreateDocumentInput { if (kind === "CONCEPT") { return { ...common, kind, bodyMarkdown: "", basisVersion: "" }; } + if (kind === "SETUP") { + /* + 절 이름을 스키마로 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다. 대신 빈 본문 + 대신 뼈대를 넣어 준다. 지우고 자기 절을 써도 되고, 그대로 채워도 된다. + */ + return { + ...common, + kind, + bodyMarkdown: "## 실행 절차\n\n## 구성 값\n\n## 확인 방법\n", + pinnedVersions: [], + }; + } if (kind === "QUESTION") { return { ...common, diff --git a/src/features/tech-log/presentation/studio/components/setup-fields.tsx b/src/features/tech-log/presentation/studio/components/setup-fields.tsx new file mode 100644 index 0000000..37cb7fe --- /dev/null +++ b/src/features/tech-log/presentation/studio/components/setup-fields.tsx @@ -0,0 +1,202 @@ +import { useRef, useState } from "react"; + +import type { components } from "../../../contracts/studio/generated.ts"; +import type { Asset, AssetKind } from "../../../contracts/studio/contract.ts"; +import { useStudioAssetGateway } from "../use-studio.ts"; +import { AssetPicker, buildEvidenceDirective } from "./asset-picker.tsx"; +import { AssetUploadDialog } from "./asset-upload-dialog.tsx"; +import { MarkdownToolbar } from "./markdown-toolbar.tsx"; +import { FieldNotice, type FieldIssue } from "./field-issues.tsx"; + +type SetupInput = components["schemas"]["SetupInput"]; +type PinnedVersion = components["schemas"]["PinnedVersion"]; + +/** 이 화면이 자기 칸 아래에 보여 줄 수 있는 경로. */ +export const SETUP_FIELD_PATHS = ["/pinnedVersions", "/bodyMarkdown"] as const; + +const ASSET_KIND_OPTIONS: ReadonlyArray<{ value: AssetKind; label: string }> = [ + { value: "IMAGE", label: "이미지" }, + { value: "DIAGRAM", label: "다이어그램" }, + { value: "ATTACHMENT", label: "첨부파일" }, +]; + +/** + * `:::evidence ...` is a block directive, so the parser requires a blank line + * before and after it. Inserting straight into `selectionStart`/`selectionEnd` + * without normalizing the surrounding whitespace would produce a directive + * glued to adjacent text -- a well-formed-looking block that the parser still + * rejects. + */ +function insertAtCursor( + textarea: HTMLTextAreaElement, + directive: string, + commit: (next: string) => void, +) { + const { selectionStart, selectionEnd, value } = textarea; + const prefix = value.slice(0, selectionStart); + const suffix = value.slice(selectionEnd); + const before = prefix.length === 0 || prefix.endsWith("\n\n") ? prefix : `${prefix}\n\n`; + const after = suffix.startsWith("\n") ? suffix : `\n${suffix}`; + commit(`${before}${directive}${after}`); +} + +/** + * 환경 구성 편집 화면. + * + *

다른 다섯 종류는 끝난 일을 적는다. 이 종류만 읽는 사람이 그대로 따라 하는 절차를 적으므로, + * 본문에 명령과 표가 들어간다 — Case 의 「검증 환경」 같은 평문 한 칸으로는 담기지 않는다. + * + *

버전만 본문 밖에 둔다. 이 절차가 어느 버전 위에서 성립했는지는 그 기록의 유효 범위이고, + * 목록과 머리말이 본문을 열지 않고 보여 줘야 하는 값이기 때문이다. 개념의 「기준 버전」이 같은 + * 이유로 따로 있고, 다른 점은 셋업의 버전이 하나가 아니라 여럿이라는 것뿐이다. + */ +export function SetupFields({ + draft, + issues, + onChange, + onAssetsObserved, + onAssetUploaded, +}: { + draft: SetupInput; + /** 마지막 게시 시도가 남긴 지적. 각 칸 아래에는 그 칸의 것만 붙는다. */ + issues: readonly FieldIssue[]; + onChange(draft: SetupInput): void; + onAssetsObserved?: (assets: readonly Asset[]) => void; + onAssetUploaded?: (asset: Asset) => void; +}) { + const assetGateway = useStudioAssetGateway(); + const bodyRef = useRef(null); + const uploadTriggerRef = useRef(null); + const [uploadKind, setUploadKind] = useState("DIAGRAM"); + const [uploadOpen, setUploadOpen] = useState(false); + const update = (patch: Partial) => onChange({ ...draft, ...patch }); + + const replaceVersion = (index: number, patch: Partial) => { + update({ + pinnedVersions: draft.pinnedVersions.map((pinned, at) => + at === index ? { ...pinned, ...patch } : pinned, + ), + }); + }; + + const insertDirective = (directive: string) => { + const textarea = bodyRef.current; + if (!textarea) { + update({ + bodyMarkdown: draft.bodyMarkdown + ? `${draft.bodyMarkdown}\n\n${directive}\n` + : `${directive}\n`, + }); + return; + } + insertAtCursor(textarea, directive, (next) => update({ bodyMarkdown: next })); + }; + + const closeUpload = () => { + setUploadOpen(false); + queueMicrotask(() => uploadTriggerRef.current?.focus()); + }; + + return ( +

+
+

SETUP

+

환경 구성

+
+
+
+ 고정한 버전 +
    + {draft.pinnedVersions.map((pinned, index) => ( + // 행에는 안정된 식별자가 없다. 값으로 키를 만들면 이름을 지우는 순간 키가 + // 겹쳐 입력 중이던 칸이 다른 행으로 옮겨 간다. +
  • + + + +
  • + ))} +
+ + “Keycloak” / “26.7.0” 처럼 적습니다. 비우면 화면에 표를 그리지 않습니다. + +
+
+ + update({ bodyMarkdown: next })} /> +