Files
tech-log-frontend/src/features/tech-log/presentation/studio/components/document-list.tsx
T
DongHyeonkaandClaude Opus 5 3af9be9e09 feat: 환경 구성(SETUP) 기록 종류를 더한다
다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시
하려면 무엇부터 하는가다. Case 의 environment 는 평문 한 칸이라 명령이
들어가지 않고, 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.

프로젝트는 필수, 주제는 선택으로 둔다. 주제 없는 셋업이 그 프로젝트의 공통
구성이고, 주제를 붙이면 그 주제의 구성이다 — 스키마를 나누지 않고 두 범위를
같은 종류로 받는다.

버전만 본문 밖에 둔다(pinnedVersions). 이 절차가 어느 버전 위에서 성립했는지는
그 기록의 유효 범위이고, 목록과 머리말이 본문을 열지 않고 보여 줘야 한다.
나머지 셋(실행 절차·구성 값·확인 방법)은 명령과 표를 담아야 하므로 본문이다.

이름은 SETUP 이다. ENVIRONMENT 가 영어로는 자연스럽지만 case_detail.environment
와 겹친다 — 이 저장소가 열네 번 밟은 실패가 「종류를 손으로 나열한 곳을
빠뜨린다」이고 그걸 찾는 수단이 grep 이다.

손으로 나열해 두었던 자리를 이번에 표로 바꿨다. publicPath 의 삼항 사슬은
마지막 else 가 「나머지 전부」여서 새 종류의 주소가 조용히 /questions/… 가
됐고, document-editor 의 칸 경로도 같은 모양이었다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 14:12:44 +09:00

373 lines
14 KiB
TypeScript

import { useEffect, useState, type FormEvent } from "react";
import type { ListDocumentsQuery } from "../../../application/ports/studio-gateway.ts";
import type { DocumentPage } from "../../../contracts/studio/contract.ts";
import type { components } from "../../../contracts/studio/generated.ts";
import { managementFailureMessage } from "../../../application/ports/management-gateway-error.ts";
import { useStudio } from "../use-studio.ts";
import { GuardedStudioLink } from "./guarded-studio-link.tsx";
import { StudioPagination } from "./studio-pagination.tsx";
import { DOCUMENT_KIND_LABELS } from "../../shared/document-kind-labels.ts";
type RecordKind = components["schemas"]["RecordKind"];
/*
작업본 목록이 거를 수 있는 종류. 손으로 나열하지 않고 `Record<RecordKind, …>` 에서 뽑는다 —
종류가 늘면 컴파일러가 빈 자리를 잡는다.
*/
const STUDIO_KIND_ORDER: Record<RecordKind, number> = {
CASE: 1,
CONCEPT: 2,
REFERENCE: 3,
QUESTION: 4,
SETUP: 5,
PROJECT_DECISION: 6,
};
const STUDIO_KINDS: ReadonlyArray<RecordKind> = Object.freeze(
(Object.keys(STUDIO_KIND_ORDER) as RecordKind[]).sort(
(left, right) => STUDIO_KIND_ORDER[left] - STUDIO_KIND_ORDER[right],
),
);
const publicationLabel = {
NEVER_PUBLISHED: "게시 전",
PUBLISHED: "게시 중",
UNPUBLISHED: "게시 취소",
} as const;
const nextLabel = {
CONTINUE_EDITING: "작성 계속",
VALIDATE: "검증하기",
FIX_VALIDATION: "오류 수정",
CREATE_PREVIEW: "미리보기",
PUBLISH: "게시하기",
NONE: "완료",
} as const;
/**
* 다음 단계는 이름만 있고 갈 곳이 없었다. 작성자는 편집 → 검증 → 미리보기 → 게시를 순서대로
* 밟아야만 게시 화면에 닿을 수 있었고, 그 경로 어디에도 "게시" 라는 말이 먼저 보이지 않아
* 게시하는 방법을 알기 어려웠다. 서버가 이미 다음 할 일을 알려 주므로, 그 말을 그대로 링크로
* 만든다.
*/
const nextHref = {
CONTINUE_EDITING: "edit",
VALIDATE: "validation",
FIX_VALIDATION: "edit",
CREATE_PREVIEW: "preview",
PUBLISH: "publish",
NONE: "",
} as const;
function isAbortError(error: unknown): boolean {
return error instanceof DOMException && error.name === "AbortError";
}
export function DocumentList() {
const { gateway, managementGateway, setRequestAnnouncement } = useStudio();
const [deletingId, setDeletingId] = useState<string | null>(null);
const [deleteError, setDeleteError] = useState("");
const [searchDraft, setSearchDraft] = useState("");
const [q, setQ] = useState("");
const [kind, setKind] = useState<ListDocumentsQuery["kind"]>();
const [status, setStatus] =
useState<ListDocumentsQuery["publicationStatus"]>();
const [pageNumber, setPageNumber] = useState(1);
const [page, setPage] = useState<DocumentPage | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState("");
const [retryGeneration, setRetryGeneration] = useState(0);
/**
* 목록 행에는 version 이 없다 (계약의 `DocumentSummary`). 삭제는 expectedVersion 을 요구하므로
* 지우기 직전에 작업본을 한 번 읽어 그 시점의 version 을 쓴다 — 목록을 띄워 둔 채 다른 곳에서
* 수정된 경우 여기서 409 로 걸리는 편이, 목록이 기억하던 낡은 version 으로 지우는 것보다 낫다.
*/
const removeDocument = async (item: DocumentPage["items"][number]) => {
if (deletingId !== null) return;
setDeletingId(item.id);
setDeleteError("");
try {
const detail = await gateway.getDocument(item.id);
if (item.kind === "PROJECT_DECISION") {
// Decision 은 프로젝트에 속하고 경로가 둘을 요구한다. 목록 행이 프로젝트를 들고 있지
// 않으면 지울 주소를 만들 수 없다 — 그때는 프로젝트를 먼저 지정해야 한다.
if (!item.project) {
setDeleteError("프로젝트에 속하지 않은 결정은 여기서 지울 수 없습니다. 먼저 프로젝트를 지정해 주세요.");
return;
}
await managementGateway.deleteDecision(
item.project.id,
item.id,
detail.document.version,
);
} else {
/*
예전에는 여기서 `as "CASE" | "REFERENCE" | "QUESTION"` 으로 종류를 좁혔다. 개념이
더해졌을 때 그 캐스팅이 개념을 가렸고, 게이트웨이의 마지막 else 가 질문 삭제를
부르는 바람에 「질문을 찾을 수 없습니다」가 났다. 캐스팅을 걷어내면 새 종류가
생길 때 타입이 여기서 막는다.
*/
await managementGateway.deleteDocument(
item.kind,
item.id,
detail.document.version,
);
}
setRequestAnnouncement(`작업본 ${item.title || "제목 없음"} 을(를) 삭제했습니다.`);
// 다시 불러오지 않고 이 행만 지운다. 목록은 커서 페이지네이션이라 재조회하면 다음
// 항목이 빈 자리를 즉시 채우고, 개수도 20 그대로다 — 작성자에게는 삭제가 아무 일도
// 하지 않은 것처럼 보인다. 삭제가 성공한 뒤의 화면은 그 행이 없는 화면이 맞다.
setPage((current) =>
current
? { ...current, items: current.items.filter((row) => row.id !== item.id) }
: current,
);
} catch (error) {
// 서버는 무엇이 막았는지 정확히 알고 그것을 보내 준다. 예전에는 그 문구를 버리고 추측 셋을
// 늘어놓아, 버전 충돌도 "사용 중" 으로 읽혔다.
setDeleteError(managementFailureMessage(error, "삭제하지 못했습니다."));
} finally {
setDeletingId(null);
}
};
useEffect(() => {
const controller = new AbortController();
setLoading(true);
setError("");
void gateway
.listDocuments(
{
...(q ? { q } : {}),
...(kind ? { kind } : {}),
...(status ? { publicationStatus: status } : {}),
page: pageNumber,
limit: 20,
},
{ signal: controller.signal },
)
.then(
(value) => {
setPage(value);
setLoading(false);
},
(reason: unknown) => {
if (isAbortError(reason)) return;
setError("작업본을 불러오지 못했습니다.");
setLoading(false);
},
);
return () => controller.abort();
}, [gateway, kind, pageNumber, q, retryGeneration, status]);
const changeFilter = (next: {
kind?: ListDocumentsQuery["kind"];
status?: ListDocumentsQuery["publicationStatus"];
}) => {
if ("kind" in next) setKind(next.kind);
if ("status" in next) setStatus(next.status);
// 3쪽에 있던 채로 필터를 좁히면 결과가 그보다 적어 빈 화면이 나온다.
setPageNumber(1);
};
const submitSearch = (event: FormEvent) => {
event.preventDefault();
setQ(searchDraft.trim());
setPageNumber(1);
};
return (
<div className="studio-page studio-documents-page">
<header className="studio-page-top">
<div className="studio-page-heading">
<p className="studio-eyebrow">WORKING COPIES</p>
<h1>작업본</h1>
<p>
세션에 있는 검증 기록·동작 원리·적용 기준·열린 질문·설계 결정을 찾고 다음 작업으로 이동합니다.
</p>
</div>
<GuardedStudioLink className="studio-primary-action" href="/studio/documents/new">
새 문서
</GuardedStudioLink>
</header>
<section className="studio-document-tools" aria-label="작업본 검색과 필터">
<form role="search" onSubmit={submitSearch}>
<label htmlFor="studio-search">검색</label>
<div>
<input
id="studio-search"
type="search"
value={searchDraft}
placeholder="제목, 요약, slug"
onChange={(event) => setSearchDraft(event.target.value)}
/>
<button type="submit">검색</button>
</div>
</form>
<label>
종류
<select
value={kind ?? ""}
onChange={(event) =>
changeFilter({
kind: (event.target.value || undefined) as ListDocumentsQuery["kind"],
})
}
>
<option value="">전체</option>
{/*
이름은 공용 표에서 가져온다. 여기 손으로 적어 두었을 때 개념이 통째로 빠져 있었고
— 개념 작업본은 만들 수는 있는데 걸러 볼 수가 없었다 — 이름도 영문이라 목록 안의
배지와 어긋났다. 같은 문서가 한 화면에서 두 이름으로 보였다.
*/}
{STUDIO_KINDS.map((value) => (
<option key={value} value={value}>
{DOCUMENT_KIND_LABELS[value]}
</option>
))}
</select>
</label>
<label>
상태
<select
value={status ?? ""}
onChange={(event) =>
changeFilter({
status: (event.target.value || undefined) as ListDocumentsQuery["publicationStatus"],
})
}
>
<option value="">전체</option>
<option value="NEVER_PUBLISHED">게시 전</option>
<option value="PUBLISHED">게시 중</option>
<option value="UNPUBLISHED">게시 취소</option>
</select>
</label>
</section>
{loading ? (
<p className="studio-loading" role="status">
작업본을 불러오는 중입니다.
</p>
) : null}
{error ? (
<>
<p className="studio-screen-error" role="alert">
{error}
</p>
<button
className="studio-secondary-button"
type="button"
onClick={() => setRetryGeneration((current) => current + 1)}
>
다시 시도
</button>
</>
) : null}
{page && !loading && !error ? (
<>
{/*
이 숫자는 전체가 아니라 이 페이지에 실린 수다. 예전 문구는 그것을 전체처럼 읽히게
해서, 28건 중 20건이 보이는 동안 무엇을 지워도 "20개" 가 그대로였다.
*/}
<p className="studio-result-count">
<span>
{page.page.totalElements}개 중 {page.items.length}개 표시 중
</span>
{page.page.totalPages > 1 ? (
<span>
{" "}
· {page.page.number} / {page.page.totalPages} 쪽
</span>
) : null}
</p>
{deleteError ? (
<p className="studio-screen-error" role="alert">
{deleteError}
</p>
) : null}
{page.items.length ? (
<div className="studio-document-list">
{page.items.map((item) => (
<article className="studio-document-row" key={item.id}>
<p className="studio-row-label">{DOCUMENT_KIND_LABELS[item.kind]}</p>
<div className="studio-document-title">
<h2>
<GuardedStudioLink href={`/studio/documents/${item.id}/edit`}>
{item.title || "제목 없는 작업본"}
</GuardedStudioLink>
</h2>
<p>{item.project?.label ?? "프로젝트 미지정"}</p>
</div>
<dl>
<div>
<dt>상태</dt>
<dd>{publicationLabel[item.publicationStatus]}</dd>
</div>
<div>
<dt>다음</dt>
<dd>
{nextHref[item.nextAction] ? (
<GuardedStudioLink
href={`/studio/documents/${item.id}/${nextHref[item.nextAction]}`}
>
{nextLabel[item.nextAction]}
</GuardedStudioLink>
) : (
nextLabel[item.nextAction]
)}
</dd>
</div>
<div>
<dt>수정</dt>
<dd>
<time dateTime={item.updatedAt}>
{new Date(item.updatedAt).toLocaleDateString("ko-KR", {
timeZone: "Asia/Seoul",
})}
</time>
</dd>
</div>
</dl>
{/*
편집은 제목 링크였고 삭제만 버튼이라, 행에서 눈에 띄는 단 하나가 되돌릴 수
없는 동작이었다. 편집을 같은 격의 버튼으로 올리고 삭제는 그 옆에 둔다.
*/}
<div className="studio-row-actions">
<GuardedStudioLink
className="studio-secondary-button"
href={`/studio/documents/${item.id}/edit`}
>
편집
</GuardedStudioLink>
<button
className="studio-secondary-button studio-danger-button"
type="button"
disabled={deletingId !== null}
onClick={() => void removeDocument(item)}
>
삭제
</button>
</div>
</article>
))}
</div>
) : (
<section className="studio-empty-state">
<h2>조건에 맞는 작업본이 없습니다</h2>
<p>검색어 또는 필터를 바꾸거나 새 문서를 만드세요.</p>
<GuardedStudioLink href="/studio/documents/new">
새 문서 만들기
</GuardedStudioLink>
</section>
)}
<StudioPagination
page={page.page}
label="작업본 페이지"
onChange={setPageNumber}
/>
</>
) : null}
</div>
);
}