docs: 개념(CONCEPT) 문서 종류 설계

Reference 는 판단 기준을 빨리 찾는 글이고, Kubernetes 내부 동작처럼 처음부터 풀어 읽어야
하는 글은 그 틀에 들어가지 않는다. 종류를 하나 더하고 Reference 구조는 그대로 둔다.

개념 글은 프로젝트 없이 게시될 수 있는 유일한 종류이므로 주제를 게시 조건으로 둔다 —
집 없는 글이 생기지 않게.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
This commit is contained in:
DongHyeonka
2026-08-28 19:19:02 +09:00
co-authored by Claude Opus 5
parent 2420fcee9f
commit 05df030530
@@ -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 를
받는다. 반대 순서는 안전하다 — 백엔드에 새 경로가 생겨도 부르는 화면이 아직 없을 뿐이다.