feat: 자료를 해시가 아니라 뜻으로 고르고, 검증이 막는 것을 세어 준다

Asset 목록이 `assetKey` 를 앞세우고 있었다. key 는 본문이 가리키는 불변 식별자이지
사람이 기억하는 이름이 아니다 — 스무 줄이면 해시 같은 문자열 스무 개에서 찾던 도식을
눈으로 골라야 했다. 파일 이름을 앞에 두고 형식·치수·크기를 함께 적는다. key 는 아래에
작게 남긴다(복사해 쓰는 값이라 지우지 않는다).

「사용 0건」과 「사용 3건」이 같은 회색으로 나란했다. 쓰이지 않는 자료는 지워도 되는
것이고 쓰이는 자료는 지우면 화면이 깨지므로, 그 차이를 말로 가른다. 상세에서는 어느
기록이 쓰는지를 링크로 연다 — 바꾸거나 지우기 전에 무엇이 깨질지 숫자만으로는 알 수
없다. 관리 상태도 `ARCHIVED` 대신 「보관됨」으로 적는다.

검증 결과는 오류와 경고가 한 목록에 섞여 있었다. 게시 전에 작성자가 알아야 하는 것은
"게시를 막는 것이 몇 개인가" 하나인데, 그 답을 얻으려면 줄마다 배지를 읽어야 했다.
둘을 갈라 각각의 수를 제목에 적는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
DongHyeonka
2026-09-15 20:33:07 +09:00
co-authored by Claude Opus 5
parent 9545860605
commit ae6da7156e
4 changed files with 167 additions and 57 deletions
@@ -6,6 +6,29 @@ import type { StudioAssetGateway } from "../../../application/ports/studio-asset
import { isStudioGatewayError } from "../../../application/ports/studio-gateway-error.ts";
import { createLocalId } from "../../../domain/studio/local-id.ts";
/** 관리 상태. 화면에 영문 상수가 그대로 나오던 자리다. */
const ASSET_STATUS_LABELS: Record<Asset["managementStatus"], string> = {
READY: "사용 가능",
ARCHIVED: "보관됨",
REJECTED: "거부됨",
QUARANTINED: "검사 보류",
};
/** 사람이 고를 때 실제로 보는 사실들 — 무엇이고, 얼마나 크고, 몇 바이트인가. */
function assetFacts(asset: Asset): string {
const parts = [asset.mediaType.replace(/^image\//u, "").toUpperCase()];
// 치수를 모르는 자료가 있다(첨부파일, 처리 중). 모르면 적지 않는다 — 0×0 은 거짓이다.
if (asset.width && asset.height) parts.push(`${asset.width}×${asset.height}`);
parts.push(byteLabel(asset.byteSize));
return parts.join(" · ");
}
function byteLabel(bytes: number): string {
if (bytes < 1024) return `${bytes} B`;
if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
}
/** `document-list.tsx`'s page size for the same screen shape. */
const PAGE_SIZE = 20;
@@ -314,6 +337,12 @@ export function AssetLibrary(props: Readonly<{ gateway: StudioAssetGateway }>) {
{asset.kind === "ATTACHMENT" ? "파일" : "—"}
</span>
)}
{/*
사람이 고르는 이름은 파일 이름이다. 목록이 `assetKey` 를 앞세우던 동안 작성자는
해시 같은 문자열 스무 줄에서 찾던 도식을 눈으로 골라야 했다 — key 는 본문이
가리키는 불변 식별자이지 사람이 기억하는 이름이 아니다. 이름을 앞에 두고 key 는
아래에 작게 남긴다.
*/}
<button
type="button"
ref={(node) => {
@@ -322,12 +351,24 @@ export function AssetLibrary(props: Readonly<{ gateway: StudioAssetGateway }>) {
else rows.delete(asset.id);
}}
aria-current={selected?.asset.id === asset.id ? "true" : undefined}
/* 버튼의 이름은 사람이 부르는 이름까지다. 크기·형식까지 이름에 넣으면 목록을
훑을 때 버튼 하나하나가 문장이 되어 고를 수 없다. */
aria-label={asset.originalFilename || asset.assetKey}
onClick={(event) => void openDetail(asset, event.currentTarget)}
>
{asset.assetKey}
<strong>{asset.originalFilename || asset.assetKey}</strong>
<small>{assetFacts(asset)}</small>
<small className="asset-library-list__key">{asset.assetKey}</small>
</button>
<span>{asset.managementStatus}</span>
<span>사용 {asset.usageCount}건</span>
<span>{ASSET_STATUS_LABELS[asset.managementStatus]}</span>
{/*
쓰이지 않는 자료는 지워도 되는 것이고, 쓰이는 자료는 지우면 화면이 깨진다. 그
차이가 숫자 하나로만 표시되던 동안 「사용 0건」과 「사용 3건」이 같은 회색으로
나란했다.
*/}
<span className={asset.usageCount === 0 ? "asset-usage asset-usage--none" : "asset-usage"}>
{asset.usageCount === 0 ? "쓰이지 않음" : `${asset.usageCount}곳에서 사용`}
</span>
</li>
))}
</ul>
@@ -345,19 +386,43 @@ export function AssetLibrary(props: Readonly<{ gateway: StudioAssetGateway }>) {
) : null}
{selected ? (
<div className="asset-detail" aria-label={`${selected.asset.assetKey} 상세`}>
<div
className="asset-detail"
aria-label={`${selected.asset.originalFilename || selected.asset.assetKey} 상세`}
>
<h2 ref={detailHeadingRef} tabIndex={-1}>
{selected.asset.assetKey}
{selected.asset.originalFilename || selected.asset.assetKey}
</h2>
<p>{selected.asset.managementStatus}</p>
<dl className="asset-detail-facts">
<div><dt>상태</dt><dd>{ASSET_STATUS_LABELS[selected.asset.managementStatus]}</dd></div>
<div><dt>파일</dt><dd>{assetFacts(selected.asset)}</dd></div>
{/* 본문이 가리키는 불변 식별자. 사람이 기억하는 이름이 아니라 복사해 쓰는 값이다. */}
<div><dt>Key</dt><dd><code>{selected.asset.assetKey}</code></dd></div>
{selected.asset.altText ? (
<div><dt>대체 텍스트</dt><dd>{selected.asset.altText}</dd></div>
) : null}
</dl>
{/*
바꾸거나 지우기 전에 어디에 쓰이는지 전부 보여야 한다. 숫자만으로는 무엇이 깨질지
알 수 없다.
*/}
<h3 className="asset-detail-usage-title">쓰이는 곳</h3>
{selected.usages.length > 0 ? (
<ul>
{selected.usages.map((usage) => (
<li key={usage.documentId}>{usage.title}</li>
<li key={usage.documentId}>
{/*
평범한 링크다. 이 화면은 Studio 컨텍스트를 받지 않고 게이트웨이 하나만 받아
혼자 설 수 있게 되어 있고, 여기서 떠날 때 지킬 편집 상태도 없다.
*/}
<a href={`/studio/documents/${usage.documentId}/edit`}>
{usage.title || "제목 없는 작업본"}
</a>
</li>
))}
</ul>
) : (
<p>사용 중인 문서가 없습니다.</p>
<p>아직 어느 기록도 이 자료를 쓰지 않습니다.</p>
)}
<div className="asset-detail-actions">
{/*