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">
{/*
@@ -78,28 +78,49 @@ export function ValidationReport({
<div><dt>검증 시각</dt><dd>{formatDateTime(report.validatedAt)}</dd></div>
<div><dt>유효 시각</dt><dd>{formatDateTime(report.validUntil)}</dd></div>
</dl>
{/*
오류와 경고를 갈라 세고 각각의 수를 제목에 적는다.
한 목록에 섞여 있으면 "게시를 막는 것이 몇 개인가" 라는 질문에 답하려면 줄마다 배지를
읽어야 한다. 게시 전에 작성자가 알아야 하는 것은 그 수 하나다 — 경고는 지금 고치지
않아도 나갈 수 있고 오류는 아니다.
*/}
{issues.length ? (
<ol
className={`studio-workflow-issue-list${current ? "" : " studio-workflow-issue-list--stale"}`}
aria-label={current ? "검증 항목" : "지난 검증 항목"}
>
{issues.map((issue, index) => (
<li key={`${issue.severity}-${issue.code}-${issue.path}-${index}`}>
<GuardedStudioLink
href={`/studio/documents/${documentId}/edit#${validationFieldTarget(issue.path)}`}
>
<span className="studio-workflow-issue-severity">
{severityLabel[issue.severity]}
</span>
<span className="studio-workflow-issue-body">
<strong>{issue.message}</strong>
<small>{issue.code} · {issue.path || "/"}</small>
</span>
<span aria-hidden="true">편집 →</span>
</GuardedStudioLink>
</li>
))}
</ol>
<>
{(["ERROR", "WARNING"] as const).map((severity) => {
const group = issues.filter((issue) => issue.severity === severity);
if (group.length === 0) return null;
return (
<div className="studio-workflow-issue-group" key={severity}>
<h3>
{severity === "ERROR" ? "게시를 막는 것" : "확인해 둘 것"}
<span>{group.length}</span>
</h3>
<ol
className={`studio-workflow-issue-list${current ? "" : " studio-workflow-issue-list--stale"}`}
aria-label={`${severityLabel[severity]} 항목`}
>
{group.map((issue, index) => (
<li key={`${issue.severity}-${issue.code}-${issue.path}-${index}`}>
<GuardedStudioLink
href={`/studio/documents/${documentId}/edit#${validationFieldTarget(issue.path)}`}
>
<span className="studio-workflow-issue-severity">
{severityLabel[issue.severity]}
</span>
<span className="studio-workflow-issue-body">
<strong>{issue.message}</strong>
<small>{issue.code} · {issue.path || "/"}</small>
</span>
<span aria-hidden="true">편집 →</span>
</GuardedStudioLink>
</li>
))}
</ol>
</div>
);
})}
</>
) : (
<p className="studio-workflow-empty-issues">오류와 경고가 없습니다.</p>
)}
@@ -468,3 +468,22 @@
.studio-app .studio-row-overflow > summary:hover { background: var(--canvas); color: var(--ink); }
.studio-app .studio-row-overflow > div { position: absolute; z-index: 5; top: 100%; right: 0; padding: 7px; border: 1px solid var(--line-strong); border-radius: 6px; background: var(--paper); box-shadow: 0 6px 18px rgb(0 0 0 / 8%); }
.studio-app .studio-unpublished-mark { color: var(--warning); }
/* 검증 결과 — 게시를 막는 것과 확인해 둘 것을 갈라 센다 */
.studio-app .studio-workflow-issue-group + .studio-workflow-issue-group { margin-top: 26px; }
.studio-app .studio-workflow-issue-group > h3 { display: flex; gap: 10px; align-items: baseline; margin: 22px 0 0; font-size: 14px; font-weight: 650; }
.studio-app .studio-workflow-issue-group > h3 > span { color: var(--faint); font-family: "IBM Plex Mono", monospace; font-size: 13px; }
/* Asset — 해시가 아니라 뜻으로 고른다 */
.studio-app .asset-library-list button { display: flex; flex-direction: column; gap: 3px; align-items: flex-start; text-align: left; }
.studio-app .asset-library-list button strong { color: var(--ink); font-size: 15px; font-weight: 600; }
.studio-app .asset-library-list button small { color: var(--muted); font-size: 12px; }
.studio-app .asset-library-list__key { color: var(--faint) !important; font-family: "IBM Plex Mono", monospace; font-size: 11px !important; }
.studio-app .asset-usage { color: var(--muted); font-size: 12px; }
.studio-app .asset-usage--none { color: var(--faint); }
.studio-app .asset-detail-facts { display: grid; gap: 8px 22px; margin: 14px 0 0; }
.studio-app .asset-detail-facts > div { display: flex; gap: 12px; align-items: baseline; }
.studio-app .asset-detail-facts dt { min-width: 84px; color: var(--faint); font-size: 12px; font-weight: 620; }
.studio-app .asset-detail-facts dd { margin: 0; color: var(--ink-soft); font-size: 14px; }
.studio-app .asset-detail-facts code { font-family: "IBM Plex Mono", monospace; font-size: 12px; }
.studio-app .asset-detail-usage-title { margin: 24px 0 10px; font-size: 13px; font-weight: 650; }