diff --git a/docs/superpowers/plans/2026-08-27-concept-record-kind.md b/docs/superpowers/plans/2026-08-27-concept-record-kind.md new file mode 100644 index 0000000..cc8f366 --- /dev/null +++ b/docs/superpowers/plans/2026-08-27-concept-record-kind.md @@ -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=""` 로만 참조하고 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=""` 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+ ` 로 먼저 확인한다 — 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`; 개념 작업본 읽기·쓰기; 개념 게시본 기록. + +- [ ] **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 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 ( +
+
+

CONCEPT

+

개념

+
+
+ +
+ …본문 Markdown 칸 + AssetPanel (case-fields.tsx 와 동일)… +
+ ); +} +``` + +`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 + +``` + +```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: 운영에서 개념 문서를 하나 써서 게시하고 홈·탐색·주제·상세를 눈으로 확인**