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; }
+33 -28
View File
@@ -162,7 +162,7 @@ test("shows archive instead of delete for an asset in use", async () => {
hasPublicationHistory: true,
})} />);
await user.click(await screen.findByRole("button", { name: "boundary" }));
await user.click(await screen.findByRole("button", { name: "b.svg" }));
assert.ok(await screen.findByRole("button", { name: "보관" }));
expect(screen.queryByRole("button", { name: "삭제" })).not.toBeInTheDocument();
@@ -183,7 +183,7 @@ test("surfaces ASSET_IN_USE when the server rejects a delete", async () => {
},
)} />);
await user.click(await screen.findByRole("button", { name: "boundary" }));
await user.click(await screen.findByRole("button", { name: "b.svg" }));
// 삭제는 이제 확인을 한 번 거친다. 상세의 버튼이 창을 열고, 창의 버튼이 실제로 지운다.
await user.click(await screen.findByRole("button", { name: "삭제" }));
await user.click(
@@ -205,9 +205,9 @@ test("archives an asset by sending the expected command and merging the server's
});
render(<AssetLibrary gateway={gateway} />);
const row = (await screen.findByRole("button", { name: "boundary" })).closest("li");
const row = (await screen.findByRole("button", { name: "b.svg" })).closest("li");
assert.ok(row);
await user.click(await screen.findByRole("button", { name: "boundary" }));
await user.click(await screen.findByRole("button", { name: "b.svg" }));
await user.click(await screen.findByRole("button", { name: "보관" }));
assert.ok(await screen.findByText("보관했습니다."));
@@ -225,7 +225,8 @@ test("archives an asset by sending the expected command and merging the server's
// response instead of just leaving the old row in place. `findByText`
// above already settled on the post-update render, so this can assert
// directly instead of polling.
assert.ok(row.textContent?.includes("ARCHIVED"));
// 상태는 이제 사람이 읽는 말로 나온다 — 화면에 영문 상수를 그대로 찍던 자리였다.
assert.ok(row.textContent?.includes("보관됨"));
});
// Fix round 1 (I1 + Minor 4). Combines the delete success path's gateway
@@ -244,7 +245,7 @@ test("removes the asset and restores focus to the page heading, not the detached
});
render(<AssetLibrary gateway={gateway} />);
await user.click(await screen.findByRole("button", { name: "boundary" }));
await user.click(await screen.findByRole("button", { name: "b.svg" }));
// 삭제는 이제 확인을 한 번 거친다. 상세의 버튼이 창을 열고, 창의 버튼이 실제로 지운다.
await user.click(await screen.findByRole("button", { name: "삭제" }));
await user.click(
@@ -257,7 +258,7 @@ test("removes the asset and restores focus to the page heading, not the detached
const options = deleteCalls[0].options as { idempotencyKey?: unknown };
assert.equal(typeof options.idempotencyKey, "string");
assert.ok((options.idempotencyKey as string).length > 0);
expect(screen.queryByRole("button", { name: "boundary" })).not.toBeInTheDocument();
expect(screen.queryByRole("button", { name: "b.svg" })).not.toBeInTheDocument();
// `findByText` above already settled on the post-delete render -- the
// `queueMicrotask`-scheduled focus call has necessarily run by then, since
@@ -288,8 +289,12 @@ test("removes the asset and restores focus to the page heading, not the detached
type ListCall = Readonly<{ q?: string; cursor?: string; limit?: number }>;
type ListPage = Readonly<{ items: unknown[]; nextCursor: string | null }>;
/*
자료마다 사람이 부르는 이름이 다르다. 목록이 `assetKey` 를 앞세우던 동안 픽스처도 key 로만
갈라져 있었는데, 화면이 파일 이름으로 고르게 되었으므로 픽스처도 그 이름을 따로 갖는다.
*/
function assetNamed(assetKey: string, id: string) {
return { ...(ASSET as object), id, assetKey } as never;
return { ...(ASSET as object), id, assetKey, originalFilename: `${assetKey}.svg` } as never;
}
function libraryGateway(respond: (query: ListCall) => ListPage) {
@@ -324,12 +329,12 @@ test("searches assets with the typed query and announces the new result count",
);
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "newer-diagram" });
await screen.findByRole("button", { name: "newer-diagram.svg" });
await user.type(screen.getByLabelText("Asset 검색"), "older");
await user.click(screen.getByRole("button", { name: "검색" }));
assert.ok(await screen.findByRole("button", { name: "older-diagram" }));
expect(screen.queryByRole("button", { name: "newer-diagram" })).not.toBeInTheDocument();
assert.ok(await screen.findByRole("button", { name: "older-diagram.svg" }));
expect(screen.queryByRole("button", { name: "newer-diagram.svg" })).not.toBeInTheDocument();
assert.equal(calls.at(-1)?.q, "older");
// The result count lives in a `role="status"` region so a screen reader is
// told the list changed -- a silently re-rendered list is the failure mode
@@ -345,7 +350,7 @@ test("typing alone never reaches the gateway -- only the submitted query does",
const { gateway, calls } = libraryGateway(() => ({ items: [ASSET], nextCursor: null }));
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "boundary" });
await screen.findByRole("button", { name: "b.svg" });
assert.equal(calls.length, 1);
await user.type(screen.getByLabelText("Asset 검색"), "boundary");
@@ -364,12 +369,12 @@ test("loads the next page with the server cursor and appends it to the list", as
);
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "page-one" });
await screen.findByRole("button", { name: "page-one.svg" });
await user.click(screen.getByRole("button", { name: "더 보기" }));
assert.ok(await screen.findByRole("button", { name: "page-two" }));
assert.ok(await screen.findByRole("button", { name: "page-two.svg" }));
// Appended, not replaced: the first page must stay reachable.
assert.ok(screen.getByRole("button", { name: "page-one" }));
assert.ok(screen.getByRole("button", { name: "page-one.svg" }));
assert.equal(calls.at(-1)?.cursor, "cursor-1");
// Exhausted paging removes the control rather than leaving a button that
// does nothing.
@@ -387,17 +392,17 @@ test("더 보기 moves focus to the first newly loaded asset instead of strandin
);
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "focus-page-one" });
await screen.findByRole("button", { name: "focus-page-one.svg" });
await user.click(screen.getByRole("button", { name: "더 보기" }));
const appended = await screen.findByRole("button", { name: "focus-page-two" });
const appended = await screen.findByRole("button", { name: "focus-page-two.svg" });
expect(appended).toHaveFocus();
});
test("offers no 더 보기 control when the server reports no next cursor", async () => {
render(<AssetLibrary gateway={gatewayOf({ asset: ASSET, usages: [], hasPublicationHistory: false })} />);
await screen.findByRole("button", { name: "boundary" });
await screen.findByRole("button", { name: "b.svg" });
expect(screen.queryByRole("button", { name: "더 보기" })).not.toBeInTheDocument();
});
@@ -414,16 +419,16 @@ test("a new search restarts paging from the first page instead of carrying the o
});
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "reset-page-one" });
await screen.findByRole("button", { name: "reset-page-one.svg" });
await user.click(screen.getByRole("button", { name: "더 보기" }));
await screen.findByRole("button", { name: "reset-page-two" });
await screen.findByRole("button", { name: "reset-page-two.svg" });
await user.type(screen.getByLabelText("Asset 검색"), "reset-found");
await user.click(screen.getByRole("button", { name: "검색" }));
assert.ok(await screen.findByRole("button", { name: "reset-found" }));
expect(screen.queryByRole("button", { name: "reset-page-one" })).not.toBeInTheDocument();
expect(screen.queryByRole("button", { name: "reset-page-two" })).not.toBeInTheDocument();
assert.ok(await screen.findByRole("button", { name: "reset-found.svg" }));
expect(screen.queryByRole("button", { name: "reset-page-one.svg" })).not.toBeInTheDocument();
expect(screen.queryByRole("button", { name: "reset-page-two.svg" })).not.toBeInTheDocument();
assert.equal(calls.at(-1)?.cursor, undefined);
});
@@ -456,7 +461,7 @@ test("a slow earlier search never overwrites the newer search's results", async
await act(async () => {
pending[0]!.settle({ items: [initial], nextCursor: null });
});
await screen.findByRole("button", { name: "race-initial" });
await screen.findByRole("button", { name: "race-initial.svg" });
const input = screen.getByLabelText("Asset 검색");
await user.clear(input);
@@ -472,7 +477,7 @@ test("a slow earlier search never overwrites the newer search's results", async
await act(async () => {
pending[2]!.settle({ items: [fast], nextCursor: null });
});
await screen.findByRole("button", { name: "race-fast" });
await screen.findByRole("button", { name: "race-fast.svg" });
// The abandoned "slow" request lands last. Nothing about it may reach the
// screen: the user is looking at "fast" results.
@@ -480,8 +485,8 @@ test("a slow earlier search never overwrites the newer search's results", async
pending[1]!.settle({ items: [slow], nextCursor: null });
});
expect(screen.queryByRole("button", { name: "race-slow" })).not.toBeInTheDocument();
assert.ok(screen.getByRole("button", { name: "race-fast" }));
expect(screen.queryByRole("button", { name: "race-slow.svg" })).not.toBeInTheDocument();
assert.ok(screen.getByRole("button", { name: "race-fast.svg" }));
});
test("a search that matches nothing says so instead of claiming no asset was ever uploaded", async () => {
@@ -491,7 +496,7 @@ test("a search that matches nothing says so instead of claiming no asset was eve
);
render(<AssetLibrary gateway={gateway} />);
await screen.findByRole("button", { name: "boundary" });
await screen.findByRole("button", { name: "b.svg" });
await user.type(screen.getByLabelText("Asset 검색"), "없는키");
await user.click(screen.getByRole("button", { name: "검색" }));