fix: 관계의 묶음 이름과 작성자가 쓴 문장을 갈라 놓는다

관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지,
대상이 무엇인지 — 셋 다 `reason` 한 칸을 지나느라 경로마다 다른 것이 같은 자리에
나왔다. 렌더 모델 경로에서는 작성자의 문장이 묶음 이름 자리에 눌려 한 줄짜리 라벨인
척했고, 공개 조회 경로에서는 묶음 이름이 그 자리를 차지하고 작성자의 문장은 아예
버려졌다. 「다음에 무엇을 읽을지」의 답이 그 문장인데 공개 화면에 한 번도 나오지 않았다.

이제 셋이 각자의 칸을 갖는다. `label` 은 대상의 종류, `note` 는 작성자가 쓴 문장,
`summary` 는 대상의 요약이다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을
보인다 — 요약은 대상을 설명하고 문장은 왜 지금 이것을 읽어야 하는지를 설명한다.

공개 주소로 종류를 되짚던 삼항 사슬도 표로 바꾼다. `/concepts/` 가 어디에도 없어서
개념으로 가는 관계가 전부 `PROJECT` 로 떨어지고 있었다 — 손으로 나열한 목록에 새
종류를 빠뜨리는 일이 이 저장소에서만 다섯 번째다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
This commit is contained in:
DongHyeonka
2026-09-01 16:48:11 +09:00
co-authored by Claude Opus 5
parent af5a6bbf23
commit 618a228eff
22 changed files with 698 additions and 76 deletions
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/management-contract",
"version": "1.0.0",
"digest": "sha256:a422ff091cdba5f17a27edfa12fec06e077bcc52c9615136ddecfa8df58a5f6e",
"sourceRevision": "fa67a64",
"digest": "sha256:5452be2aa2ac4164c82db393ae94eb0b7dcfa27c34a26dcd73f26f9f1a8e8998",
"sourceRevision": "ca1bbfe",
"operationIds": [
"createCaseDraft",
"getCaseForEdit",
@@ -70,6 +70,10 @@
"createTopic",
"updateTopic",
"deleteTopic",
"listTopicVariants",
"createTopicVariant",
"updateTopicVariant",
"deleteTopicVariant",
"listStudioTags",
"createTag",
"updateTag",
@@ -765,6 +765,40 @@ export interface paths {
patch?: never;
trace?: never;
};
"/api/v1/studio/topics/{id}/variants": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/** @description 주제 안의 접근/구조. 표시 순서대로 온다. */
get: operations["listTopicVariants"];
put?: never;
post: operations["createTopicVariant"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/studio/topics/{id}/variants/{variantId}": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put: operations["updateTopicVariant"];
post?: never;
/** @description 접근/구조를 지운다. 걸려 있던 기록은 지우지 않는다 — 연결만 끊어져 그 주제의 공통 기록이 된다. */
delete: operations["deleteTopicVariant"];
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/studio/tags": {
parameters: {
query?: never;
@@ -1337,6 +1371,9 @@ export interface components {
createdProjectDecisionId?: string;
};
ProjectUpdateRequest: {
/** @description 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 —
* 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. */
thesis?: string;
/** Format: int64 */
expectedVersion: number;
name: string;
@@ -1357,6 +1394,9 @@ export interface components {
questionLinks?: components["schemas"]["ProjectResourceLinkEdit"][];
};
ProjectEditResponse: {
/** @description 이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 —
* 프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다. */
thesis?: string;
/** Format: uuid */
id: string;
/** Format: int64 */
@@ -1464,6 +1504,13 @@ export interface components {
slug: string;
description?: string;
scope?: string;
/** @description 이 주제가 답하는 질문을 한 문단으로 적는다. 기록을 합쳐 자동으로 나오는 글이
* 아니라 사람이 쓰는 글이므로 자리를 따로 둔다. */
thesis?: string;
/** @description 독자에게 보이는 축의 이름. 인증 경계에서는 「구조」, 조회 성능에서는 「조회 전략」이
* 된다 — 내부 모델 이름(variant)을 화면에 그대로 쓰지 않는다. 비어 있으면 이 주제는
* 축을 쓰지 않는다. */
variantLabel?: string;
/** @enum {string} */
status?: "ACTIVE" | "ARCHIVED";
/** Format: int64 */
@@ -1472,6 +1519,24 @@ export interface components {
featuredReferenceId?: string;
featuredCaseIds?: string[];
};
/** @description 주제 안의 접근/구조 하나. slug 는 그 주제 안에서만 유일하다 — 주소가
* `/topics/{topicSlug}/{variantSlug}` 이고, 다른 주제에서 같은 이름을 쓸 수 있어야 한다. */
TopicVariantEdit: {
/** Format: uuid */
id?: string;
/** Format: int64 */
version?: number;
slug: string;
title: string;
/** @description 이것이 무엇인가. */
summary?: string;
/** @description 만들어 보고 무엇을 알게 됐는가. 홈 비교표가 읽는 것이 이 칸이다 — 기록의 요약
* 첫 줄을 잘라 쓰면 안 되는 자리라 따로 둔다. */
conclusion?: string;
displayOrder?: number;
/** Format: int64 */
expectedVersion?: number;
};
TagEdit: {
name: string;
slug: string;
@@ -7378,6 +7443,166 @@ export interface operations {
};
};
};
listTopicVariants: {
parameters: {
query?: never;
header?: never;
path: {
id: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description OK */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["TopicVariantEdit"][];
};
};
};
};
createTopicVariant: {
parameters: {
query?: never;
header: {
"X-CSRF-TOKEN": components["parameters"]["CsrfToken"];
};
path: {
id: string;
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["TopicVariantEdit"];
};
};
responses: {
/** @description Created */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["TopicVariantEdit"];
};
};
/** @description Bad Request */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
/** @description Conflict */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
};
};
updateTopicVariant: {
parameters: {
query?: never;
header: {
"X-CSRF-TOKEN": components["parameters"]["CsrfToken"];
};
path: {
id: string;
variantId: string;
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["TopicVariantEdit"];
};
};
responses: {
/** @description OK */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["TopicVariantEdit"];
};
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
/** @description Conflict */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
};
};
deleteTopicVariant: {
parameters: {
query?: never;
header: {
"X-CSRF-TOKEN": components["parameters"]["CsrfToken"];
};
path: {
id: string;
variantId: string;
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["ExpectedVersionRequest"];
};
};
responses: {
/** @description No Content */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description Not Found */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
/** @description Conflict */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/problem+json": components["schemas"]["ProblemDetails"];
};
};
};
};
listStudioTags: {
parameters: {
query?: never;
@@ -4430,6 +4430,142 @@ paths:
$ref: '#/components/schemas/ExpectedVersionRequest'
security:
- sessionCookie: []
/api/v1/studio/topics/{id}/variants:
get:
operationId: listTopicVariants
tags: [Topics]
description: 주제 안의 접근/구조. 표시 순서대로 온다.
parameters:
- name: id
in: path
required: true
schema: { type: string, format: uuid }
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TopicVariantEdit'
security:
- sessionCookie: []
post:
operationId: createTopicVariant
tags: [Topics]
parameters:
- name: id
in: path
required: true
schema: { type: string, format: uuid }
- $ref: '#/components/parameters/CsrfToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TopicVariantEdit'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/TopicVariantEdit'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
security:
- sessionCookie: []
/api/v1/studio/topics/{id}/variants/{variantId}:
put:
operationId: updateTopicVariant
tags: [Topics]
parameters:
- name: id
in: path
required: true
schema: { type: string, format: uuid }
- name: variantId
in: path
required: true
schema: { type: string, format: uuid }
- $ref: '#/components/parameters/CsrfToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TopicVariantEdit'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TopicVariantEdit'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
security:
- sessionCookie: []
delete:
operationId: deleteTopicVariant
tags: [Topics]
description: |-
접근/구조를 지운다. 걸려 있던 기록은 지우지 않는다 — 연결만 끊어져 그 주제의 공통 기록이 된다.
parameters:
- name: id
in: path
required: true
schema: { type: string, format: uuid }
- name: variantId
in: path
required: true
schema: { type: string, format: uuid }
- $ref: '#/components/parameters/CsrfToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpectedVersionRequest'
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
security:
- sessionCookie: []
/api/v1/studio/tags:
get:
operationId: listStudioTags
@@ -6539,6 +6675,12 @@ components:
- technologyLabels
- targetVisibility
properties:
thesis:
type: string
maxLength: 2000
description: |-
이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 —
프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다.
expectedVersion:
type: integer
format: int64
@@ -6600,6 +6742,12 @@ components:
- publication
- updatedAt
properties:
thesis:
type: string
maxLength: 2000
description: |-
이 프로젝트가 무엇을 밝혔는지 한 문단으로. 기록을 합쳐 자동으로 나오는 글이 아니다 —
프로젝트 화면의 THESIS 자리가 비어 있던 것은 담을 칸이 없어서였다.
id:
type: string
format: uuid
@@ -6839,6 +6987,19 @@ components:
maxLength: 600
scope:
type: string
thesis:
type: string
maxLength: 2000
description: |-
이 주제가 답하는 질문을 한 문단으로 적는다. 기록을 합쳐 자동으로 나오는 글이
아니라 사람이 쓰는 글이므로 자리를 따로 둔다.
variantLabel:
type: string
maxLength: 40
description: |-
독자에게 보이는 축의 이름. 인증 경계에서는 「구조」, 조회 성능에서는 「조회 전략」이
된다 — 내부 모델 이름(variant)을 화면에 그대로 쓰지 않는다. 비어 있으면 이 주제는
축을 쓰지 않는다.
status:
type: string
enum:
@@ -6856,6 +7017,44 @@ components:
items:
type: string
format: uuid
TopicVariantEdit:
type: object
required:
- slug
- title
description: |-
주제 안의 접근/구조 하나. slug 는 그 주제 안에서만 유일하다 — 주소가
`/topics/{topicSlug}/{variantSlug}` 이고, 다른 주제에서 같은 이름을 쓸 수 있어야 한다.
properties:
id:
type: string
format: uuid
version:
type: integer
format: int64
slug:
type: string
maxLength: 100
pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
title:
type: string
maxLength: 80
summary:
type: string
maxLength: 600
description: 이것이 무엇인가.
conclusion:
type: string
maxLength: 600
description: |-
만들어 보고 무엇을 알게 됐는가. 홈 비교표가 읽는 것이 이 칸이다 — 기록의 요약
첫 줄을 잘라 쓰면 안 되는 자리라 따로 둔다.
displayOrder:
type: integer
minimum: 0
expectedVersion:
type: integer
format: int64
TagEdit:
type: object
required:
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/public-contract",
"version": "2.1.0",
"digest": "sha256:afe415880eb5d6289ae10abf493333c97270c323c16a7245a466d4db4466e630",
"sourceRevision": "fa67a64",
"digest": "sha256:92c15205d373bd7048d9596e75b211c30198bb4fb3339e1d7f92a2acabe75440",
"sourceRevision": "ca1bbfe",
"operationIds": [
"getPublicSite",
"getPublicHome",
@@ -418,6 +418,12 @@ export interface components {
type: "CASE" | "REFERENCE" | "QUESTION" | "CONCEPT" | "PROJECT" | "PROJECT_DECISION" | "RELEASE";
title: string;
summary?: string;
/** @description 작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에
* 자리가 없어 독자는 볼 수 없었다 — 「다음에 무엇을 읽을지」의 답이 이 문장이다. */
reason?: string;
/** @description 낮을수록 먼저. 상세 화면은 앞의 한둘만 펴 두고 나머지는 접는다 — 균등한 넷은
* 선택이 아니라 부담이다. */
priority?: number;
path: string;
};
ContactLink: {
@@ -539,13 +545,26 @@ export interface components {
slug: string;
description: string;
scope?: string;
thesis?: string;
variantLabel?: string;
};
/** @description 주제 안의 접근/구조. 표시 순서대로 온다. 비어 있으면 이 주제는 축을 쓰지 않는다. */
variants?: components["schemas"]["TopicVariantSummary"][];
featuredReference?: components["schemas"]["RelatedEntry"];
featuredCases: components["schemas"]["RelatedEntry"][];
activeQuestions: components["schemas"]["RelatedEntry"][];
relatedProjects: components["schemas"]["RelatedEntry"][];
latestRecords: components["schemas"]["LatestEntry"][];
};
TopicVariantSummary: {
slug: string;
title: string;
path: string;
summary?: string;
/** @description 만들어 보고 무엇을 알게 됐는가. 비교표가 읽는 칸이다. */
conclusion?: string;
recordCount?: number;
};
CaseDetailResponse: {
canonicalPath: string;
/** @default true */
@@ -910,6 +910,17 @@ components:
type: string
summary:
type: string
reason:
type: string
description: |-
작성자가 남긴, 왜 이 기록이 걸려 있는지. Studio 에 이미 저장돼 있으나 공개 응답에
자리가 없어 독자는 볼 수 없었다 — 「다음에 무엇을 읽을지」의 답이 이 문장이다.
priority:
type: integer
minimum: 0
description: |-
낮을수록 먼저. 상세 화면은 앞의 한둘만 펴 두고 나머지는 접는다 — 균등한 넷은
선택이 아니라 부담이다.
path:
type: string
ContactLink:
@@ -1231,6 +1242,16 @@ components:
type: string
scope:
type: string
thesis:
type: string
variantLabel:
type: string
variants:
type: array
description: |-
주제 안의 접근/구조. 표시 순서대로 온다. 비어 있으면 이 주제는 축을 쓰지 않는다.
items:
$ref: '#/components/schemas/TopicVariantSummary'
featuredReference:
$ref: '#/components/schemas/RelatedEntry'
featuredCases:
@@ -1249,6 +1270,27 @@ components:
type: array
items:
$ref: '#/components/schemas/LatestEntry'
TopicVariantSummary:
type: object
required:
- slug
- title
- path
properties:
slug:
type: string
title:
type: string
path:
type: string
summary:
type: string
conclusion:
type: string
description: 만들어 보고 무엇을 알게 됐는가. 비교표가 읽는 칸이다.
recordCount:
type: integer
minimum: 0
CaseDetailResponse:
type: object
required:
@@ -1,8 +1,8 @@
{
"packageId": "@tech-log/studio-contract",
"version": "3.1.0",
"digest": "sha256:7de83618e7bf5e0816f12136be91abc0e779c3ee06f86276a2b2498a5d51a4e0",
"sourceRevision": "fa67a64",
"digest": "sha256:d2bfbe0a12136f131ccb8c42f8868108ba8d0f0182b347f9b815316c343a970c",
"sourceRevision": "ca1bbfe",
"operationIds": [
"getStudioSession",
"getStudioDashboard",
@@ -582,6 +582,7 @@ export interface components {
summary: string;
/** Format: uuid */
topicId: string | null;
variantIds?: string[];
/**
* Format: uuid
* @description `kind=PROJECT_DECISION`은 게시 시점에 non-null이어야 한다. 저장 시점에는 강제하지 않는다.
@@ -919,6 +919,10 @@ components:
- { type: string, minLength: 3, maxLength: 100, pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
summary: { type: string, maxLength: 2000 }
topicId: { type: [string, "null"], format: uuid }
# 이 기록이 걸리는 주제 안의 접근/구조. 여럿일 수 있다 — PKCE 는 SPA 와 BFF 양쪽에
# 관계되고, credential 변환 경계는 Mediator 와 BFF 를 견준다. 비어 있으면 그 주제의
# 공통 기록으로 읽는다. required 에 넣지 않는다: 이미 저장된 작업본을 깨지 않는다.
variantIds: { type: array, maxItems: 8, items: { type: string, format: uuid } }
projectId:
type: [string, "null"]
format: uuid
@@ -35,7 +35,12 @@ const TECH_LOG_ROUTE_SPECS = [
defineSpec({ routeId: "TECH_LOG_PROJECT_RECORDS", path: "/projects/:slug/records", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 기록", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_PROJECT_DECISIONS", path: "/projects/:slug/decisions", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 결정", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_PROJECT_ACTIVITY", path: "/projects/:slug/activity", layoutGroup: "PUBLIC", paramsSchema: "TechLogSlugParams", searchSchema: null, title: "프로젝트 활동", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_RELEASES", path: "/releases", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "변경 기록", navigationLabel: "변경 기록", navigationOrder: 30 }),
/*
변경 기록은 주 내비에서 내린다. 독자의 작업은 읽고·탐색하고·주제와 프로젝트를 따라가고
검색하는 것이고, 「사이트가 언제 무엇을 공개했는가」는 그 축이 아니다. 주소는 그대로 두고
푸터가 데려간다.
*/
defineSpec({ routeId: "TECH_LOG_RELEASES", path: "/releases", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "변경 기록", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_RELEASE", path: "/releases/:version", layoutGroup: "PUBLIC", paramsSchema: "TechLogVersionParams", searchSchema: null, title: "변경 기록", navigationLabel: null, navigationOrder: null }),
defineSpec({ routeId: "TECH_LOG_PROFILE", path: "/profile", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: null, title: "프로필", navigationLabel: "프로필", navigationOrder: 40 }),
defineSpec({ routeId: "TECH_LOG_SEARCH", path: "/search", layoutGroup: "PUBLIC", paramsSchema: null, searchSchema: "TechLogSearchQuery", title: "검색", navigationLabel: null, navigationOrder: null }),