docs: SETUP 종류 설계·계획을 구현 결과와 맞춘다

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
This commit is contained in:
DongHyeonka
2026-09-09 14:39:32 +09:00
co-authored by Claude Opus 5
parent 7cd11a7b35
commit 28dce83398
2 changed files with 64 additions and 3 deletions
@@ -772,3 +772,31 @@ cd FE && git add . && git commit -m "feat: 환경 구성(SETUP) 기록 종류"
- [ ] **Step 5: 운영 확인**
Studio 에서 셋업 문서를 하나 써서 게시 → `/setups/{slug}` · `/explore/setups` · 홈 최근 기록 · Case 에서 건 관계를 눈으로 확인.
---
## 진행 상태 (2026-09-09)
Task 1~10 완료. Task 11 은 게이트까지 끝났고 **배포는 하지 않았다**.
| 커밋 | 저장소 | 내용 |
|---|---|---|
| `3af9be9` | frontend | 계약·타입·화면·가드 |
| `7cd11a7` | frontend | `CatalogEntry.kind` · `ResolvedRelation.targetKind` |
| `17fe3d1` | backend | V17 · 경로 가드 · 작성/게시/공개 조회 |
**확인한 것**
- 프론트 다섯 게이트: `check:types` · `lint` 통과, `test:component`(78파일 560건) ·
`test:tech-log` 통과, `test:unit` 은 사전 실패 3건만 남음
- 백엔드 `./gradlew test` 전체 통과(816건)
- V17 이 실제 PostgreSQL 에서 적용됨 — `postgresqlTechLogSchemaMigrationTest` 3건 통과
- 경로 가드를 되돌려(`PublicSql.pathOf` 의 SETUP 갈래 삭제) 실패하는 것을 보고 되돌렸다
**하지 않은 것**
- 배포(Task 11 Step 3~5). 운영에 나가는 일이라 승인 전에 멈췄다.
- DB CHECK 제약 대조 가드(Task 4 Step 1). V17 이 아홉 제약을 모두 고쳤고 통합 테스트가
마이그레이션을 실제로 적용해 확인했지만, 「계약 enum 과 DB CHECK 를 대조하는」 가드 자체는
아직 없다. 다음에 종류를 더할 때 `record_variant` 같은 새 제약을 또 빠뜨릴 수 있는 자리다.
@@ -271,8 +271,41 @@ EXPLORE_KIND_PATHS SETUP: "/explore/setups"
백엔드를 먼저 올린다. 프론트가 먼저 올라가면 `/setups/{slug}` 를 부르는 화면이 404 를
받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.
## 구현하면서 이 설계가 틀린 것으로 드러난 곳
설계는 「종류 enum 이 하나」라고 가정했다. 아니었다.
**계약에 종류를 나열하는 자리가 셋이다.** `RecordKind` 말고도 `CatalogEntry.kind`(관계 후보
목록)와 `ResolvedRelation.targetKind`(응답의 관계 항목)가 각각 따로 나열한다. 둘을 빠뜨리면
Case 가 셋업을 관계로 걸 수 없고, 걸어도 응답에서 종류가 튕긴다. 백엔드의 계약 union Jackson
테스트가 앞의 것을, 프론트 타입 검사가 뒤의 것을 잡았다.
**삭제 경로가 계약 밖에 있었다.** `DeletableDocumentKind` 는 계약이 아니라 손으로 쓴 union
이고, 종류마다 별도 관리 operation(`deleteCaseDraft` …)을 요구한다. `deleteSetupDraft` 를
계약·기여 목록·컨트롤러 셋 다에 더해야 했다.
**프론트에도 손으로 쓴 `RecordKind` 가 둘 더 있다.** `application/ports/public-content-queries.ts`
와 `adapters/static/public-content.ts` 가 각자 문자열 union 을 갖고 있다. 계약의 것과 같은
집합이어야 하는데 대조하는 것이 없다.
**주제 없는 머리말은 한 곳만 고치면 됐다.** 설계는 렌더러 세 자리를 다 막으라고 적었으나,
주제가 빌 수 있는 종류는 SETUP 뿐이고 그것은 자기 렌더러(`SetupDocument`)를 갖는다. 개념·Case
의 머리말은 주제가 늘 있으므로 손대지 않았다 — 고쳐도 화면이 달라지지 않고, 스냅샷만 흔든다.
**공개 조회의 행 매핑은 나열을 뒤집었다.** `isCase || isConcept ? … : …`(본문을 가진 종류를
나열)를 `isReference ? … : …`(다른 하나를 지목)로 바꿨다. 규칙·적용·신선도를 갖는 것은
Reference 뿐이므로 종류가 늘어도 이 판단은 그대로다.
**`SetupDetailResponse.relations` 는 자기 타입을 얻지 못한다.** 생성기가 구조가 같은 inline
스키마를 합쳐 `ConceptDetailResponseRelations` 로 낸다. 이름을 다르게 만들려고 계약에 없는
차이를 넣지 않았다.
## 남은 문제
- `tech-log-design-package` 가 지금 로컬에 없다(`/home/donghyeon/workspace/tech-log-design-package`
없음). 계약을 고치려면 이 저장소를 먼저 되살려야 한다. 백엔드의
`src/config/openapi/` 에 vendored 사본이 있으므로 내용은 남아 있다.
- `tech-log-design-package` 는 되살리지 않았다. 계약 원본은 이제 프론트의 vendored yaml 이고,
백엔드 `src/config/openapi/` 와 `MANIFEST.sha256` 이 그 사본과 해시를 들고 있다. 타입 생성기는
`TECH_LOG_DESIGN_PACKAGE` 로 임시 git 저장소를 가리켜 돌린다.
- 이번 변경 전부터 실패하던 것: 프론트 `tests/unit/ci-workflow-generation.test.ts` 3건,
백엔드 통합 `caseDetailReadsTheOriginalTableNotTheProjectionPayload`(환경 요약이 빈 목록),
`assetsRoundTripAndReportTheirUsage`(에셋 경로가 `/media/…` 가 아니라 `/api/v1/public/media/…`).
이전 커밋의 worktree 에서 같은 실패를 확인했다.