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:
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: 운영에서 개념 문서를 하나 써서 게시하고 홈·탐색·주제·상세를 눈으로 확인**
|
||||
Reference in New Issue
Block a user