diff --git a/docs/superpowers/specs/2026-08-27-concept-record-kind-design.md b/docs/superpowers/specs/2026-08-27-concept-record-kind-design.md new file mode 100644 index 0000000..8e3f6d8 --- /dev/null +++ b/docs/superpowers/specs/2026-08-27-concept-record-kind-design.md @@ -0,0 +1,172 @@ +# 개념(CONCEPT) 문서 종류 추가 + +작성일 2026-08-27 · 대상 저장소 `tech-log-design-package` · `tech-log-backend` · `tech-log-frontend` + +## 왜 + +Reference 는 "이렇게 판단한다"를 빨리 찾는 글이다. 규칙·적용 범위·예외·예시라는 칸을 갖고 +있고, 읽는 사람이 대상을 이미 안다고 가정한다. + +Kubernetes 의 내부 동작과 아키텍처처럼 **처음부터 풀어 읽어야 하는 글**은 그 틀에 들어가지 +않는다. 규칙이 아니라 설명이고, 결론이 아니라 경로다. Reference 에 억지로 넣으면 두 글이 +서로를 망친다 — 기준을 찾으러 온 사람은 배경 설명을 지나야 하고, 개념을 배우러 온 사람은 +규칙 목록에서 시작한다. + +그래서 종류를 하나 더한다. Reference 의 구조는 그대로 둔다. + +## 무엇이 아닌가 + +- **Reference 를 바꾸지 않는다.** 규칙·적용·예외·예시 구조는 그대로다. +- **시리즈·묶음 컨테이너를 만들지 않는다.** 순서와 이유는 이미 관계(`relations`)가 갖고 + 있다. 묶음을 따로 두면 "관계에도 있고 묶음에도 있는" 두 진실이 생긴다. +- **주제 페이지를 만들지 않는다.** 개념이 쌓이면 주제가 자연스러운 묶음이 되어 그 페이지를 + 만들 이유가 생기지만, 지금은 주제 1개에 개념 0개다. 쌓인 뒤에 별건으로 본다. +- **마지막 검증일·신선도를 두지 않는다.** 개념이 낡는 방식은 날짜가 아니라 버전이다. + +## 문서의 모양 + +`WorkingCopyInputBase` 가 이미 주는 것을 그대로 쓰고 두 칸만 더한다. + +``` +base (모든 종류 공유) + kind · title · slug · summary · topicId · projectId · relations + +CONCEPT 이 더하는 것 + bodyMarkdown : 자유 마크다운. Case 와 같은 파서를 쓴다 — + `##` 소제목이 목차가 되고 `:::evidence key="…"` 로 도식을 끼운다 + basisVersion : "Kubernetes 1.31" 같은 한 줄. 비우면 화면에 그리지 않는다 +``` + +`bodyMarkdown` 의 규칙은 Case 와 같다: 마크다운 원문만 저장하고 object storage URL 을 +원문에 넣지 않는다. Asset 은 `assetKey` 로만 참조한다. + +### 붙는 자리 + +| 붙는 곳 | 개념 글에게 | 규칙 | +|---|---|---| +| 주제 | 집. 여기서 서로를 찾는다 | **게시 시 필수** — 없으면 오류 | +| 프로젝트 | 선택. 그 프로젝트에서 썼다면 붙인다 | 없어도 됨(경고도 띄우지 않는다) | +| 관계 | 읽는 순서와 이유 | 자유 | + +주제를 오류로 두는 이유는 CONCEPT 이 **프로젝트 없이 게시될 수 있는 유일한 종류**이기 +때문이다. 다른 종류는 프로젝트라도 있으니 집이 하나는 있지만, 개념 글은 주제까지 비우면 +탐색 목록과 최근 기록에서만 보이다가 사실상 사라진다. `PROJECT_DECISION` 이 프로젝트를 +요구하는 것과 같은 규칙을 주제 쪽으로 쓴 셈이다. + +프로젝트가 없는 것은 결함이 아니라 이 종류의 정상 상태이므로, `PROJECT_MISSING` 경고를 +CONCEPT 에는 띄우지 않는다. + +### 여러 문서를 잇는 법 + +``` +Kubernetes 스케줄링은 어떻게 결정되는가 + 관계 1 → 컨트롤 플레인은 무엇을 하는가 "먼저 읽기" + 관계 2 → 네트워킹은 어떻게 연결되는가 "이어서" + 관계 3 → Forward-Auth 에서 Identity Header… "이 개념을 쓴 기록" +``` + +`RelationInput` 은 `{ targetId, reason, order }` 다. 순서가 있고 이유가 자유 문구이므로 +개념끼리도, 개념 ↔ Case/Reference 로도 같은 방식으로 이어진다. + +## 계약 변경 + +### studio-v1.yaml (작성) + +- `RecordKind` enum 에 `CONCEPT` 추가 +- `ConceptInput` 신설 — `WorkingCopyInputBase` + `{ kind, bodyMarkdown, basisVersion }` +- `ConceptWorkingCopy` (응답형) 신설 — 같은 모양에 `id · version · updatedAt` +- 작업본 union(`WorkingCopyInput` / `WorkingCopy`)에 분기 추가 + +### public-v1.yaml (공개) + +- `ConceptDetailResponse` 신설 + - `concept: { title, summary, basisVersion?, content, contentFormat, contentFormatVersion, + bodyAssets, primaryTopic, primaryProject?, tags, publishedAt, updatedAt }` + - `relations: { derivedConcepts[], relatedRecords[], primaryProject? }` +- `KnowledgeListItem.type` 에 `CONCEPT` 추가 +- `LatestEntry.entryType` 에 `CONCEPT` 추가 +- `exploreKnowledge` 의 `type` 질의 파라미터에 `CONCEPT` 추가 +- `GET /concepts/{slug}` 경로 추가 + +검색(`SearchResultItem.contentType`)은 자유 문자열이라 건드리지 않는다. + +## 백엔드 + +### 마이그레이션 V11 + +```sql +concept_working_copy -- working_copy_id, body_markdown, basis_version +concept_detail -- publication_id, body_markdown, basis_version, content_format… +``` + +`record_kind` 를 제약으로 검사하는 자리에 `'CONCEPT'` 를 더한다 — `working_copy`, +`publication`, `public_resource_projection`. + +### 코드 + +| 파일 | 할 일 | +|---|---| +| `RecordKind` | enum 에 `CONCEPT` | +| `PublicPaths` | `CONCEPT → /concepts/{slug}` | +| `StudioDocumentValidator` | CONCEPT: `topicId` 없으면 **error**, `bodyMarkdown` 비면 error, `PROJECT_MISSING` 경고 제외 | +| `JdbcWorkingCopyRepositoryAdapter` + `ConceptWorkingCopyStore` | 작업본 읽기·쓰기 | +| `JdbcPublicationWriterAdapter` | `concept_detail` 기록 + projection upsert | +| `JdbcPublicDocumentQueryAdapter` | `/concepts/{slug}` 상세 조회 | +| `PublicSql.LATEST_ENTRY_TYPES` | `'CONCEPT'` 추가 (홈·주제가 함께 쓴다) | +| `JdbcCatalogQueryAdapter` | RELATION/EVIDENCE 후보에 개념 포함 | +| `PublicRenderModelFactory` | 즉시 미리보기를 Case 와 같은 파서로 | +| `StudioRequestMapper` / `StudioResponseMapper` | CONCEPT 분기 | + +### 공개 조회의 유형 필터 + +`exploreKnowledge` 는 `CASE`/`REFERENCE` 만 담고 있다. `CONCEPT` 을 더한다 — 지식 목록의 +의미가 "기록과 기준"에서 "기록과 기준과 개념"으로 넓어진다. + +## 프론트엔드 + +| 파일 | 할 일 | +|---|---| +| 계약 codegen | `generate:tech-log-contract` 재실행 | +| `public-content-queries.ts` | `RecordKind` 에 `CONCEPT`, `ConceptRecord` 타입, `LatestRecordEntry.entryType` | +| `concept-fields.tsx` (신규) | 편집기 — 본문 마크다운 + 기준 버전. Case 의 Asset Picker 재사용 | +| `document-editor.tsx` | CONCEPT 분기와 `CONCEPT_FIELD_PATHS` | +| `public-record-renderer.tsx` | 개념 렌더 — 제목·요약·기준 버전·본문·목차·관계 | +| `concept-document-page.tsx` (신규) | 공개 상세 | +| 라우트 | `TECH_LOG_CONCEPT` = `/concepts/:slug`, `explore-kind-page` 에 `concepts` | +| `explore-filter-form.tsx` | 유형 선택지에 `개념` | +| `public-document-header.tsx` | `kindLabels` 에 CONCEPT, **프로젝트 없을 때 그 마디와 dl 행을 뺀다** | +| `home-page.tsx` | `latestTypeLabels` 에 `CONCEPT: "개념"` | +| 정적/모의 어댑터 | 픽스처에 개념 문서 추가 | + +### 프로젝트 없는 문서 — 이번에 처음 생기는 상황 + +머리말은 지금 `유형 / 주제 / 프로젝트` 세 마디와 `프로젝트` dl 행을 무조건 그린다. +프로젝트가 없으면 빈 링크와 빈 값이 남는다. 값이 없을 때 그 마디와 행을 빼도록 고친다. +Case·Reference·Question 은 값이 늘 있으므로 화면이 달라지지 않는다. + +## 테스트 + +- **계약**: design-package 검증기 3종(`check-openapi` / `check-consistency` / `check-contract-parity`) +- **백엔드**: + - `PublicSitePersistenceIntegrationTest` — 개념 게시본이 홈·주제 최근 기록에 나온다 + - 공개 상세 통합 테스트 — `/concepts/{slug}` 가 본문·기준 버전·관계를 돌려준다 + - 검증기 단위 테스트 — 주제 없는 CONCEPT 은 게시가 막힌다(오류), 프로젝트 없음은 조용하다 + - ArchUnit D20(단일 생성자)은 새 어댑터에 그대로 적용된다 +- **프론트엔드**: + - `public-question-mapping.test.ts` 와 같은 방식으로 `public-concept-mapping.test.ts` — + 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣어 본문·기준 버전·관계가 채워지는지 본다 + - 화면 테스트 — 개념 상세가 목차와 본문을 그리고, 프로젝트 없는 머리말이 두 마디만 그린다 + - 탐색 필터 테스트 — `type=CONCEPT` 로 걸러진다 + - `route-contract.test.ts` — 새 라우트 등록 + +## 반영 순서 + +1. design-package 계약 → 검증기 → 커밋 +2. 백엔드: vendored 계약 + `MANIFEST.sha256`, 마이그레이션, 코드, 테스트 → 커밋 +3. 프론트: codegen, 편집기·렌더러·라우트, 테스트 → 커밋 +4. 백엔드 이미지 → 임포트 → 롤아웃 (마이그레이션이 먼저 적용되어야 한다) +5. 프론트 이미지 → 롤아웃 +6. 운영에서 개념 문서를 하나 써서 게시 → 홈·탐색·주제·상세를 눈으로 확인 + +백엔드를 먼저 올린다. 프론트가 먼저 올라가면 `/concepts/{slug}` 를 부르는 화면이 404 를 +받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.