docs: 개념(CONCEPT) 문서 종류 구현 계획

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:22:24 +09:00
co-authored by Claude Opus 5
parent 05df030530
commit 9ecc017f22
@@ -0,0 +1,597 @@
# 개념(CONCEPT) 문서 종류 Implementation Plan
> **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:** Kubernetes 내부 동작처럼 처음부터 풀어 읽어야 하는 글을 쓸 수 있도록 `CONCEPT` 문서 종류를 세 저장소에 추가한다.
**Architecture:** 개념은 `document` 테이블의 세 번째 `document_type` 이다. `document` 가 이미 `body_markdown`·`content_format`·`slug`·`primary_topic_id` 를 갖고 있으므로 새로 만드는 것은 `basis_version` 하나를 담는 `concept_detail` 뿐이다. 작성·게시·관계·Asset 참조는 Case/Reference 가 쓰는 기존 기계를 그대로 탄다.
**Tech Stack:** OpenAPI 3.1 (design-package) · Spring Boot 4 / JdbcClient / Flyway (backend) · React 19 / openapi-typescript / Vitest (frontend)
**Spec:** `docs/superpowers/specs/2026-08-27-concept-record-kind-design.md`
## Global Constraints
- 종류 이름은 `CONCEPT`, 공개 경로는 `/concepts/{slug}`, 화면 표기는 `개념`.
- 개념은 **주제가 게시 조건**이다 — `topicId` 가 없으면 `TOPIC_REQUIRED` 를 **error** 로 낸다(다른 종류는 warning 그대로).
- 개념은 프로젝트가 없어도 정상이다 — CONCEPT 에는 `PROJECT_MISSING` 경고를 내지 않는다.
- `bodyMarkdown` 은 마크다운 원문만 저장한다. Asset 은 `:::evidence key="<assetKey>"` 로만 참조하고 object storage URL 을 원문에 넣지 않는다.
- `basisVersion` 은 선택이다(빈 문자열 허용). 비어 있으면 화면에 그리지 않는다.
- 계약 원본은 `tech-log-design-package` 다. 백엔드는 `src/config/openapi/` 로 vendoring 하고 `MANIFEST.sha256` 을 갱신한다. 프론트는 `npm run generate:tech-log-contract` 로 재생성한다.
- 배포는 **백엔드 먼저, 프론트 나중**이다.
- 프론트 배포 전 검증은 네 개를 다 돌린다: `check:types` · `lint` · `test:unit` · `test:tech-log`.
---
### Task 1: 계약 — design-package
**Files:**
- Modify: `contracts/openapi/studio-v1.yaml`
- Modify: `contracts/openapi/public-v1.yaml`
**Interfaces:**
- Produces: `RecordKind` 에 `CONCEPT`; `ConceptInput`/`ConceptWorkingCopy`; `ConceptDetailResponse`; `KnowledgeListItem.type` 과 `LatestEntry.entryType` 과 `exploreKnowledge.type` 에 `CONCEPT`; `GET /concepts/{slug}`.
- [ ] **Step 1: `RecordKind` 넓히기**
`studio-v1.yaml` 835행:
```yaml
RecordKind:
type: string
enum: [CASE, REFERENCE, QUESTION, PROJECT_DECISION, CONCEPT]
```
- [ ] **Step 2: `ConceptInput` 추가** (`ReferenceInput` 다음)
```yaml
ConceptInput:
unevaluatedProperties: false
allOf:
- { $ref: "#/components/schemas/WorkingCopyInputBase" }
- type: object
required: [kind, bodyMarkdown, basisVersion]
properties:
kind: { type: string, enum: [CONCEPT] }
bodyMarkdown:
type: string
maxLength: 100000
description: |
Markdown 원문. Asset은 `:::evidence key="<assetKey>"` directive로
참조한다. object storage URL을 원문에 직접 저장하지 않는다.
basisVersion:
type: string
maxLength: 120
description: |
"Kubernetes 1.31" 처럼 이 글이 무엇을 보고 쓴 것인지 한 줄. 개념이
낡는 방식은 날짜가 아니라 버전이므로 검증일 대신 이것을 둔다. 비워도 된다.
```
- [ ] **Step 3: 작업본 응답형과 union 분기 추가**
`CaseWorkingCopy` 를 찾아 같은 자리에 `ConceptWorkingCopy` 를 더하고, `WorkingCopyInput`/`WorkingCopy` 의 `oneOf` 와 `discriminator.mapping` 에 `CONCEPT` 을 넣는다.
- [ ] **Step 4: 공개 계약 넓히기** (`public-v1.yaml`)
```yaml
# KnowledgeListItem.type
enum: [CASE, REFERENCE, CONCEPT]
# LatestEntry.entryType
enum: [CASE, REFERENCE, QUESTION, CONCEPT, PROJECT_ACTIVITY, RELEASE]
# exploreKnowledge 의 type 질의 파라미터
schema: { type: string, enum: [CASE, REFERENCE, CONCEPT] }
```
- [ ] **Step 5: `GET /concepts/{slug}` 와 `ConceptDetailResponse` 추가**
`/references/{slug}` 블록을 본떠 경로를 더하고, 응답 스키마를 넣는다:
```yaml
ConceptDetailResponse:
type: object
required: [canonicalPath, indexable, concept, relations]
properties:
canonicalPath: { type: string }
indexable: { type: boolean, default: true }
concept:
type: object
required: [title, summary, content, contentFormat, contentFormatVersion, tags, publishedAt, updatedAt]
properties:
title: { type: string }
summary: { type: string }
basisVersion: { type: string }
content: { type: string }
contentFormat: { type: string, enum: [MARKDOWN] }
contentFormatVersion: { type: integer }
bodyAssets: { type: array, items: { $ref: "#/components/schemas/AssetReference" } }
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" } }
```
- [ ] **Step 6: 검증기 3종 실행**
```bash
cd /home/donghyeon/workspace/tech-log-design-package
python3 scripts/check-openapi.py && python3 scripts/check-consistency.py && python3 scripts/check-contract-parity.py
```
Expected: 모두 통과. `check-contract-parity` 의 `RecordKind FE=… BE=…` 줄에 `CONCEPT` 이 양쪽에 나온다.
- [ ] **Step 7: 커밋**
```bash
git add contracts/openapi/studio-v1.yaml contracts/openapi/public-v1.yaml
git commit -m "contract: 개념(CONCEPT) 문서 종류를 더한다"
```
---
### Task 2: 백엔드 마이그레이션 V11
**Files:**
- Create: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V11__techlog_concept_document.sql`
- Modify: `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/.../PostgreSqlMigrationIntegrationTest.java`
**Interfaces:**
- Consumes: Task 1 의 `CONCEPT` 이름.
- Produces: `document_type='CONCEPT'` 를 허용하는 `document`, `concept_detail(document_id, basis_version)`, `source_kind`/`resource_type` 제약에 `CONCEPT`.
- [ ] **Step 1: 마이그레이션 작성**
```sql
-- 개념은 document 의 세 번째 유형이다. body_markdown·content_format·slug·primary_topic_id 는
-- document 가 이미 갖고 있으므로 새로 만드는 것은 basis_version 하나뿐이다.
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'));
CREATE TABLE concept_detail (
document_id uuid PRIMARY KEY,
document_type varchar(20) NOT NULL DEFAULT 'CONCEPT'
CHECK (document_type = 'CONCEPT'),
-- "Kubernetes 1.31" 처럼 무엇을 보고 썼는지. 개념이 낡는 방식은 날짜가 아니라 버전이다.
basis_version varchar(120) NOT NULL DEFAULT '',
CONSTRAINT fk_concept_detail_document
FOREIGN KEY (document_id, document_type)
REFERENCES document(id, document_type)
ON DELETE CASCADE
);
-- 작업본·검증·미리보기·게시가 종류를 검사하는 자리. 하나라도 빠지면 개념은 그 단계에서 막힌다.
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'));
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'));
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'));
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'));
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'));
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',
'PROJECT', 'PROJECT_DECISION', 'PROJECT_ACTIVITY', 'RELEASE', 'PROFILE'
));
```
실제 제약 이름은 `\d+ <table>` 로 먼저 확인한다 — Postgres 가 자동 생성한 이름이 위와 다르면 그 이름을 쓴다.
- [ ] **Step 2: 마이그레이션 목록 테스트 갱신**
`PostgreSqlMigrationIntegrationTest` 의 버전 배열에 `"11"` 을 더한다.
- [ ] **Step 3: 실행 확인**
```bash
cd /home/donghyeon/workspace/desktop-server-git/tech-log-backend/src
./gradlew :adapter:outbound:persistence-jpa:postgresqlMigrationIntegrationTest
```
Expected: BUILD SUCCESSFUL.
- [ ] **Step 4: 커밋**
---
### Task 3: 백엔드 도메인과 검증
**Files:**
- Modify: `src/application-core/src/main/java/dev/caskeleton/application/techlog/studio/model/RecordKind.java`
- Modify: `src/application-core/src/main/java/dev/caskeleton/application/techlog/studio/model/PublicPaths.java`
- Modify: `src/application-core/src/main/java/dev/caskeleton/application/techlog/studio/validation/StudioDocumentValidator.java`
- Test: 검증기 단위 테스트 (같은 모듈의 기존 테스트 파일)
**Interfaces:**
- Consumes: Task 1 의 계약, Task 2 의 테이블.
- Produces: `RecordKind.CONCEPT`; `PublicPaths.forKind(CONCEPT, slug, _) == "/concepts/" + slug`; CONCEPT 에 한해 주제 없음이 error.
- [ ] **Step 1: 실패하는 테스트 먼저**
```java
@Test
void aConceptWithoutATopicCannotBePublished() {
var issues = validate(conceptDraft().withTopicId(null));
assertThat(issues.errors())
.as("개념은 프로젝트 없이 설 수 있는 유일한 종류다 — 주제까지 비면 아무 데도 안 붙는다")
.extracting("code")
.contains("TOPIC_REQUIRED");
}
@Test
void aConceptWithoutAProjectIsSilent() {
var issues = validate(conceptDraft().withProjectId(null));
assertThat(issues.all()).extracting("code").doesNotContain("PROJECT_MISSING");
}
```
- [ ] **Step 2: 실패 확인**
```bash
./gradlew :application-core:test --tests '*StudioDocumentValidator*'
```
Expected: FAIL — `CONCEPT` 이 enum 에 없어 컴파일부터 막힌다.
- [ ] **Step 3: `RecordKind` 와 `PublicPaths`**
```java
public enum RecordKind {
CASE,
REFERENCE,
QUESTION,
PROJECT_DECISION,
CONCEPT
}
```
```java
case CONCEPT -> "/concepts/" + slug;
```
- [ ] **Step 4: 검증기**
`StudioDocumentValidator` 77행의 주제 검사와 프로젝트 검사를 종류로 가른다:
```java
if (base.topicId() == null) {
if (base.kind() == RecordKind.CONCEPT) {
// 개념은 프로젝트 없이 설 수 있는 유일한 종류다. 주제가 유일한 집이므로 비면 막는다.
issues.error("TOPIC_REQUIRED", "/topicId", "a concept needs a topic to publish");
} else {
issues.warning("TOPIC_REQUIRED", "/topicId", "a topic is required to publish");
}
}
```
프로젝트 없음 경고는 `RecordKind.CONCEPT` 을 제외한다 — 개념에 프로젝트가 없는 것은 정상이다.
- [ ] **Step 5: 통과 확인 후 커밋**
---
### Task 4: 백엔드 영속성 — 작업본과 게시
**Files:**
- Modify: `.../workingcopy/DocumentWorkingCopyStore.java`
- Modify: `.../studio/publication/JdbcPublicationWriterAdapter.java`
- Modify: `.../publicsite/JdbcPublicDocumentQueryAdapter.java`
- Modify: `src/application-core/.../publicsite/model/` 의 뷰 타입 (`ConceptDetailView` 신설)
**Interfaces:**
- Consumes: `RecordKind.CONCEPT`, `concept_detail` 테이블.
- Produces: `documents.findConcept(slug) → Optional<ConceptDetailView>`; 개념 작업본 읽기·쓰기; 개념 게시본 기록.
- [ ] **Step 1: `DocumentWorkingCopyStore` 에 CONCEPT 분기**
`document` 행은 그대로 쓰고 `concept_detail` 만 upsert 한다:
```java
// 개념은 document 의 세 번째 유형이다. 본문·slug·주제는 document 가 갖고 있으므로
// 여기서는 basis_version 만 따로 둔다.
jdbcClient
.sql("INSERT INTO concept_detail (document_id, basis_version) VALUES (:id, :basisVersion)"
+ " ON CONFLICT (document_id) DO UPDATE SET basis_version = EXCLUDED.basis_version")
.param("id", documentId)
.param("basisVersion", input.basisVersion())
.update();
```
- [ ] **Step 2: 게시 기록기에 CONCEPT 추가**
`JdbcPublicationWriterAdapter` 가 `CASE`/`REFERENCE` 를 분기하는 자리에 `CONCEPT` 을 더한다. projection 의 `navigation_path` 는 `PublicPaths.forKind` 가 만든 값을 그대로 쓴다.
- [ ] **Step 3: 공개 상세 조회**
```java
public Optional<ConceptDetailView> findConcept(String slug) {
return jdbcClient
.sql("SELECT d.title, d.body_markdown, d.content_format, d.content_format_version,"
+ " d.summary, c.basis_version, t.name AS topic_name, t.slug AS topic_slug"
+ " FROM document d"
+ " JOIN concept_detail c ON c.document_id = d.id"
+ " LEFT JOIN topic t ON t.id = d.primary_topic_id"
+ " WHERE d.document_type = 'CONCEPT' AND d.slug = :slug"
+ " AND d.workflow_status = 'PUBLISHED' AND d.target_visibility = 'PUBLIC'")
.param("slug", slug)
.query(...)
.optional();
}
```
실제 컬럼 이름은 `document` 정의를 다시 확인하고 맞춘다 (`summary` 컬럼이 없으면 projection 에서 가져온다).
- [ ] **Step 4: 통합 테스트**
`PublicSitePersistenceIntegrationTest` 에 개념 픽스처를 하나 만들고 상세가 본문과 기준 버전을 돌려주는지 확인한다.
- [ ] **Step 5: 커밋**
---
### Task 5: 백엔드 공개 목록
**Files:**
- Modify: `.../publicsite/PublicSql.java`
- Modify: `.../publicsite/JdbcPublicSiteQueryAdapter.java` (지식 목록의 유형 필터)
- Modify: `.../query/JdbcCatalogQueryAdapter.java`
- Test: `PublicSitePersistenceIntegrationTest`
- [ ] **Step 1: 최근 기록에 개념 포함**
```java
static final String LATEST_ENTRY_TYPES =
" p.resource_type IN ('CASE', 'REFERENCE', 'QUESTION', 'CONCEPT', 'PROJECT_ACTIVITY') ";
```
- [ ] **Step 2: 지식 목록(`exploreKnowledge`)이 개념을 담게 한다**
`CASE`/`REFERENCE` 로 좁히는 자리에 `CONCEPT` 을 더한다.
- [ ] **Step 3: 관계 후보에 개념 포함** — `JdbcCatalogQueryAdapter` 의 RELATION/EVIDENCE 질의가 개념 작업본도 돌려주는지 확인한다(모든 작업본을 돌려주고 있으면 그대로 따라온다).
- [ ] **Step 4: 통합 테스트에 단언 추가**
```java
assertThat(view.latestEntries())
.as("게시한 개념도 최근 기록에 나온다")
.extracting("entryType")
.contains("CONCEPT");
```
- [ ] **Step 5: 커밋**
---
### Task 6: 백엔드 웹 계층
**Files:**
- Modify: `src/config/openapi/public-v1.yaml`, `studio-v1.yaml`, `MANIFEST.sha256`
- Modify: `.../web/techlog/studio/mapper/StudioRequestMapper.java`, `StudioResponseMapper.java`
- Modify: `.../web/techlog/studio/render/PublicRenderModelFactory.java`
- Modify: `.../web/techlog/publicapi/mapper/PublicResponseMapper.java` + 컨트롤러
- [ ] **Step 1: vendoring 과 MANIFEST**
```bash
cp ~/workspace/tech-log-design-package/contracts/openapi/{public-v1,studio-v1}.yaml src/config/openapi/
# MANIFEST.sha256 의 해시와 @커밋 을 갱신한다
```
- [ ] **Step 2: 매퍼 분기** — 요청/응답 매퍼에 CONCEPT 분기를 더한다. 생성된 `ConceptInput`/`ConceptWorkingCopy` 타입을 쓴다.
- [ ] **Step 3: 즉시 미리보기** — `PublicRenderModelFactory` 가 CONCEPT 을 Case 와 같은 마크다운 파서로 넘긴다.
- [ ] **Step 4: `/concepts/{slug}` 컨트롤러** — 생성된 API 인터페이스를 구현한다.
- [ ] **Step 5: 전체 빌드**
```bash
./gradlew cleanStaleTraceableJars spotlessApply build test
```
Expected: BUILD SUCCESSFUL. (`caseDetailReadsTheOriginalTableNotTheProjectionPayload` 는 이 작업 이전부터 실패한다 — 새로 깨진 것과 구분한다.)
- [ ] **Step 6: 커밋**
---
### Task 7: 프론트 계약과 포트
**Files:**
- Modify: `src/features/tech-log/contracts/**` (codegen 산출물)
- Modify: `src/features/tech-log/application/ports/public-content-queries.ts`
- Modify: `src/features/tech-log/application/ports/studio-gateway.ts`
- [ ] **Step 1: 재생성**
```bash
npm run generate:tech-log-contract
```
Expected: `LatestEntry.entryType` 과 `KnowledgeListItem.type` 에 `CONCEPT` 이 보인다.
- [ ] **Step 2: 포트 타입**
```ts
export type RecordKind = "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT";
export type ConceptRecord = PublicRecordBase & {
kind: "CONCEPT";
basisVersion: string;
content: string;
bodyAssets: readonly BodyAsset[];
sections: readonly RecordSection[];
};
```
`LatestRecordEntry.entryType` 에도 `"CONCEPT"` 을 더한다.
- [ ] **Step 3: `check:types` 로 깨진 자리를 전부 드러낸다**
```bash
npm run check:types
```
Expected: `kind` 를 남김없이 다루던 switch/삼항이 CONCEPT 을 빠뜨렸다고 실패한다 — 그 목록이 다음 태스크의 할 일이다.
---
### Task 8: 프론트 편집기
**Files:**
- Create: `src/features/tech-log/presentation/studio/components/concept-fields.tsx`
- Modify: `src/features/tech-log/presentation/studio/components/document-editor.tsx`
- Modify: `src/features/tech-log/adapters/mock/validate-working-copy.ts`
- Test: `tests/features/tech-log/studio-editor-smoke.test.tsx`
- [ ] **Step 1: `concept-fields.tsx`**
Case 의 본문 칸과 Asset Picker 를 그대로 쓰고 기준 버전을 더한다:
```tsx
export const CONCEPT_FIELD_PATHS = ["/bodyMarkdown", "/basisVersion"] as const;
export function ConceptFields({ draft, issues, onChange, onAssetsObserved, onAssetUploaded }: …) {
return (
<section className="studio-editor-section" aria-labelledby="studio-concept-fields-title">
<header className="studio-editor-section-heading">
<p className="studio-eyebrow">CONCEPT</p>
<h2 id="studio-concept-fields-title">개념</h2>
</header>
<div className="studio-field-grid">
<label className="studio-field"><span>기준 버전</span>
<input value={draft.basisVersion} onChange={(event) => {
const value = event.currentTarget.value;
onChange({ ...draft, basisVersion: value });
}} />
<small>“Kubernetes 1.31” 처럼 무엇을 보고 썼는지. 비워도 됩니다.</small>
</label>
</div>
…본문 Markdown 칸 + AssetPanel (case-fields.tsx 와 동일)…
</section>
);
}
```
`setState` 콜백 안에서 `event.currentTarget` 을 읽지 않는다 — 값은 먼저 꺼낸다(eslint 규칙이 막는다).
- [ ] **Step 2: 편집기 분기와 검증 스텁** — `document-editor.tsx` 의 종류 삼항과 `kindPaths` 에 CONCEPT 을 더하고, 모의 검증기에도 같은 규칙(주제 필수, 프로젝트 경고 없음)을 넣는다.
- [ ] **Step 3: 화면 테스트 후 커밋**
---
### Task 9: 프론트 공개 렌더와 라우트
**Files:**
- Create: `src/features/tech-log/presentation/public/components/concept-document-page.tsx`
- Modify: `src/features/tech-log/presentation/shared/public-render/public-record-renderer.tsx`
- Modify: `src/features/tech-log/adapters/http/http-public-content-gateway.ts`
- Modify: 라우트 등록 (`TECH_LOG_CONCEPT` = `/concepts/:slug`)
- Test: `tests/features/tech-log/public-concept-mapping.test.ts` (신규)
- [ ] **Step 1: 매핑 테스트 먼저** — `public-question-mapping.test.ts` 와 같은 방식으로, 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣고 본문·기준 버전·관계가 채워지는지 묻는다.
- [ ] **Step 2: 게이트웨이 매핑** — `getRecord("CONCEPT", slug)` 분기를 더한다. `content` 를 `markdownSections` 로 목차화하고 `bodyAssets` 를 그대로 싣는다.
- [ ] **Step 3: 렌더러** — 제목·요약·기준 버전·목차·본문·관계. Case 의 본문 렌더 블록을 재사용한다.
- [ ] **Step 4: 라우트와 페이지** — `/concepts/:slug`, `/explore/concepts`.
- [ ] **Step 5: 통과 확인 후 커밋**
---
### Task 10: 프론트 탐색·홈·머리말
**Files:**
- Modify: `src/features/tech-log/presentation/public/components/explore-filter-form.tsx`
- Modify: `src/features/tech-log/presentation/public/pages/home-page.tsx`
- Modify: `src/features/tech-log/presentation/public/components/public-document-header.tsx`
- Modify: `src/features/tech-log/presentation/public/pages/explore-kind-page.tsx`
- Test: `tests/features/tech-log/public-document-screens.test.tsx`
- [ ] **Step 1: 프로젝트 없는 머리말 — 실패하는 테스트 먼저**
```tsx
it("개념 글에 프로젝트가 없으면 머리말이 두 마디만 그린다", async () => {
await renderDocumentRoute("TECH_LOG_CONCEPT", "/concepts/kubernetes-scheduling");
const breadcrumb = within(screen.getByRole("main")).getByRole("navigation", { name: "문서 경로" });
expect(breadcrumb).toHaveTextContent("개념/Kubernetes");
expect(within(breadcrumb).queryByRole("link", { name: /Patterns/ })).toBeNull();
expect(screen.getByRole("main").querySelector(".public-document-header dl"))
.not.toHaveTextContent("프로젝트");
});
```
- [ ] **Step 2: 머리말 고치기** — 프로젝트가 비면 breadcrumb 의 세 번째 마디와 dl 의 `프로젝트` 행을 그리지 않는다. `kindLabels` 에 `CONCEPT: "개념"` 을 더한다.
- [ ] **Step 3: 탐색 유형 선택지와 홈 표기**
```tsx
<option value="CONCEPT">개념</option>
```
```ts
const latestTypeLabels = { PROJECT_ACTIVITY: "PROJECT ACTIVITY", QUESTION: "OPEN QUESTION", CONCEPT: "개념" };
```
- [ ] **Step 4: 네 검증 다 돌리고 커밋**
```bash
npm run check:types && npm run lint && npm run test:unit && npm run test:tech-log
```
---
### Task 11: 픽스처
**Files:**
- Modify: `src/features/tech-log/adapters/static/public-content.ts`
- Modify: `src/features/tech-log/adapters/mock/fixtures.ts`
- [ ] **Step 1: 개념 문서 하나 추가** — 주제 `Kubernetes`, 프로젝트 없음, 본문에 `##` 소제목 두 개. 프로젝트 없는 머리말 테스트가 이 픽스처를 쓴다.
- [ ] **Step 2: 정적 어댑터의 `listRecords`/`getRecord` 가 CONCEPT 을 다루는지 확인**
- [ ] **Step 3: 커밋**
---
### Task 12: 배포
- [ ] **Step 1: 백엔드 이미지 빌드 → 임포트 → 롤아웃** (마이그레이션이 먼저 적용되어야 한다)
- [ ] **Step 2: 마이그레이션 적용 확인**
```bash
kubectl -n hyeonworks-prod exec postgres-0 -- psql -U postgres -d appdb \
-c "SELECT version FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 3;"
```
- [ ] **Step 3: 프론트 이미지 빌드 → 임포트 → 롤아웃**
- [ ] **Step 4: 운영에서 개념 문서를 하나 써서 게시하고 홈·탐색·주제·상세를 눈으로 확인**