diff --git a/web/src/ReleaseTargets.mount.test.tsx b/web/src/ReleaseTargets.mount.test.tsx index b2005e0..7ba5b8e 100644 --- a/web/src/ReleaseTargets.mount.test.tsx +++ b/web/src/ReleaseTargets.mount.test.tsx @@ -104,6 +104,11 @@ const json = (body: unknown, status: number) => new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } }) let overviews: Record +// 维护窗口与持有作业详情:默认没有窗口;需要时按测试覆盖。 +let maintenanceBody: Record = {} +let jobDetails: Record = {} +let jobDetailFailures: Record = {} +let recoveryCalls: { scope: string; window_job_id: string }[] = [] let container: HTMLDivElement let root: Root let originalFetch: typeof fetch @@ -151,11 +156,27 @@ beforeEach(() => { internal: reply(overviewBody('internal', emptyTarget)), external: reply(overviewBody('external', unreadableTarget)), } - globalThis.fetch = (async (input: RequestInfo | URL) => { + maintenanceBody = {} + jobDetails = {} + jobDetailFailures = {} + recoveryCalls = [] + globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => { const url = String(input) if (url.startsWith('/api/v1/library/snapshots')) return json(snapshotsBody, 200) if (url.startsWith('/api/v1/library/captures')) return json({ jobs: [] }, 200) - if (url.startsWith('/api/v1/library/maintenance')) return json({}, 200) + if (url.startsWith('/api/v1/library/maintenance/recover')) { + const body = JSON.parse(String(init?.body ?? '{}')) as { scope: string; window_job_id: string } + recoveryCalls.push(body) + return json({ accepted: true, recovery_job: 'q-recover' }, 200) + } + if (url.startsWith('/api/v1/library/maintenance')) return json(maintenanceBody, 200) + if (url.startsWith('/api/v1/library/jobs/')) { + const id = decodeURIComponent(url.slice('/api/v1/library/jobs/'.length)) + const status = jobDetailFailures[id] + if (status) return json({ error: '作业详情读取失败' }, status) + const job = jobDetails[id] + return job ? json({ available: true, job }, 200) : json({ available: false, reason: '作业不存在' }, 404) + } if (url.startsWith('/api/v1/library/overview')) { const scope = new URL(url, 'http://candidate.invalid').searchParams.get('scope') const answer = overviews[scope === 'external' ? 'external' : 'internal'] @@ -264,3 +285,97 @@ describe('ReleaseTargets 同一挂载上的目标观测(F1/G1)', () => { expect(buttonLabels()).not.toContain('建立目标权威基线(维护隔离)') }) }) + +// 真实事故复现(2026-11-03 22:48 CST):needs_restore 的持有作业 A 被同 scope 较新的 +// 成功封存 B 覆盖,页面写成“导出 · 已完成”。页面级必须按 owner_job_id 读作业, +// 并且恢复只投递到持有 scope 的那一个窗口。 +describe('维护窗口按持有作业展示(页面级)', () => { + const ownerA = { + id: 'libverify-internal-A', + scope: 'internal', + kind: 'verify', + state: 'failed', + stage: 'verify', + request_digest: 'v', + queue_job_id: 'qv', + snapshot_id: '', + target_snapshot_id: '', + actor: 'admin', + error: '恢复验证失败:canary 校验不一致', + recovery: '预备份保留;按归档人工核验', + created_at: '2026-11-03T09:20:00Z', + updated_at: '2026-11-03T09:24:00Z', + finished_at: '2026-11-03T09:24:00Z', + stages: [], + } + const sealB = { + ...ownerA, + id: 'libseal-lib-internal-20261103T092352', + kind: 'seal', + state: 'succeeded', + stage: 'export', + error: '', + recovery: '', + finished_at: '2026-11-03T09:23:52Z', + } + const instanceHeld = { + held: true, + instance: 'kgmaint-weknora', + instance_maintenance: { + instance: 'kgmaint-weknora', + owner_scope: 'internal', + scope: 'internal', + owner_job_id: 'libverify-internal-A', + level: 'instance', + services: ['app'], + ingress_state: 'closed', + state: 'needs_restore', + acquired_at: '2026-11-03T09:20:00Z', + updated_at: '2026-11-03T09:24:00Z', + released_at: null, + }, + } + + it('较新封存 B 成功不覆盖 needs_restore 窗口,恢复按 A 投递到持有 scope', async () => { + maintenanceBody = instanceHeld + jobDetails = { 'libverify-internal-A': ownerA } + overviews.internal = reply({ ...overviewBody('internal', emptyTarget), job: sealB }) + await mount() + expect(text()).toContain('libverify-internal-A') + expect(text()).toContain('canary 校验不一致') + expect(text()).toContain('维护记录,未实时探测') + expect(text()).not.toContain('导出 · 已完成') + + await click('按预备份恢复') + expect(recoveryCalls).toEqual([{ scope: 'internal', window_job_id: 'libverify-internal-A' }]) + }) + + it('持有作业详情 5xx 时明确“读取失败”,不显示 B 的进度也不给强制成功', async () => { + maintenanceBody = instanceHeld + jobDetailFailures = { 'libverify-internal-A': 503 } + overviews.internal = reply({ ...overviewBody('internal', emptyTarget), job: sealB }) + await mount() + expect(text()).toContain('持有作业状态读取失败') + expect(text()).toContain('HTTP 503') + expect(text()).not.toContain('导出 · 已完成') + expect(text()).not.toContain('强制成功') + }) + + it('持有作业 404 时写“不存在”,不退回最新作业', async () => { + maintenanceBody = instanceHeld + overviews.internal = reply({ ...overviewBody('internal', emptyTarget), job: sealB }) + await mount() + expect(text()).toContain('不存在(维护记录引用了未登记的作业)') + expect(text()).not.toContain('导出 · 已完成') + }) + + it('切到另一个 scope 不向错误 scope 投递恢复', async () => { + maintenanceBody = instanceHeld + jobDetails = { 'libverify-internal-A': ownerA } + await mount() + await click('对外知识库') + expect(text()).toContain('维护窗口属于 internal') + expect(buttonLabels()).not.toContain('按预备份恢复') + expect(recoveryCalls).toEqual([]) + }) +}) diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx index c951b18..4c6013f 100644 --- a/web/src/ReleaseTargets.tsx +++ b/web/src/ReleaseTargets.tsx @@ -9,13 +9,16 @@ import { enqueueLibraryRestore, enqueueLibrarySync, fetchLibraryCaptures, + fetchLibraryJobDetail, fetchLibraryMaintenance, + maintenanceOwnerJobID, fetchLibraryOverview, fetchLibraryRestoreAvailability, fetchLibrarySnapshots, formatBytes, scopeLabel, type LibraryCaptureJob, + type LibraryJobLookup, type LibraryJobRecord, type LibraryMaintenanceView, type LibraryOverview, @@ -133,6 +136,8 @@ interface ViewProps { onRestore: () => void overview: LibraryOverview | null maintenance: LibraryMaintenanceView | null + // 维护记录里 owner_job_id 对应的作业详情;缺失就是“未读取”,不能用 overview.job 顶替。 + maintenanceOwnerJob?: LibraryJobLookup now: number onRefresh: () => void onCapture: () => void @@ -343,6 +348,10 @@ export interface MaintenanceSummary { // 作业失败但维护窗口已释放:只保留失败记录,不能再说"目标保持维护"。 releasedFailure: string recoveryNote: string + // 窗口未释放但持有作业已经是终态成功:对账缺口,页面不提供强制成功。 + unreconciledNote: string + // 实例级窗口属于另一个 scope:不在此投递恢复,提示切回持有 scope。 + scopeNote: string canRecover: boolean } @@ -365,9 +374,22 @@ const stageLabel: Record = { const ingressText = (state?: string) => state === 'closed' ? '已关闭(排空后等待写入)' : state === 'open' ? '打开' : state ? state : '未知' +// 持有作业详情没读到时只写未读取/未知,绝不拿同 scope 最新作业顶替。 +const ownerJobText = (lookup: LibraryJobLookup | undefined, ownerJobID: string) => { + const id = ownerJobID || '—' + if (lookup?.state === 'error') return `持有作业状态读取失败:${lookup.reason}(不使用其他作业推断)` + if (lookup?.state === 'missing') return `持有作业 ${id} 不存在(维护记录引用了未登记的作业)` + if (lookup?.state === 'loaded') + return `持有作业状态未读取/未知(维护记录为 ${id},读取到的是 ${lookup.job.id},不采用)` + return `持有作业状态未读取/未知(owner_job_id=${id};不使用最新作业代替)` +} + +// 维护卡只消费“维护记录里的持有作业”。同 scope 最新作业可能是一次无关封存: +// 拿它当窗口进度会把 needs_restore 显示成“导出 · 已完成”(真实事故 2026-11-03)。 export function maintenanceSummary( maintenance: LibraryMaintenanceView | null | undefined, - job: LibraryJobRecord | undefined + ownerJob?: LibraryJobLookup, + scope?: string ): MaintenanceSummary { const record = maintenance?.instance_maintenance ?? maintenance?.maintenance ?? null const level = !record @@ -378,38 +400,64 @@ export function maintenanceSummary( ? '库级' : record.level || '未知' const held = Boolean(maintenance?.held) - const failed = job?.state === 'failed' - const ownerScope = maintenance?.instance_maintenance?.owner_scope ?? record?.scope ?? '—' + const ownerScope = maintenance?.instance_maintenance?.owner_scope ?? record?.scope ?? '' + const ownerJobID = record?.owner_job_id ?? '' + // 只有 id 与维护记录一致的作业才是本窗口的进度;其余按“未读取”处理。 + const owner = ownerJob?.state === 'loaded' && ownerJob.job.id === ownerJobID ? ownerJob.job : undefined + const failed = owner?.state === 'failed' + const progress = owner + ? `${stageLabel[owner.stage] ?? owner.stage ?? '—'} · ${jobStateText(owner)}` + : record + ? ownerJobText(ownerJob, ownerJobID) + : '尚无作业进度' + // 实例级窗口跨 scope 共用:只有持有 scope 才能投递恢复,否则后端必然 409。 + const sameScope = !scope || !ownerScope || ownerScope === scope + const scopeNote = + held && !sameScope + ? `维护窗口属于 ${ownerScope},当前查看 ${scope}:页面不向另一个 scope 投递恢复,请切回 ${ownerScope} 再处理` + : '' + // 恢复只由“维护仍持有 + 本窗口作业未收口”决定,与无关的最新作业无关。 + const unsettled = owner + ? owner.state === 'failed' || owner.state === 'cancelled' + : record?.state === 'needs_restore' || record?.state === 'failed' || record?.state === 'held' return { level, held, - owner: record ? `${ownerScope} · ${record.owner_job_id || '—'}` : '—', + owner: record ? `${ownerScope || '—'} · ${record.owner_job_id || '—'}` : '—', state: record?.state || '—', ingress: record ? ingressText(record.ingress_state) : '—', services: (record?.services ?? []).join('、') || '—', acquiredAt: record?.acquired_at ? stamp(record.acquired_at) : '—', releasedAt: record?.released_at ? stamp(record.released_at) : '', - progress: job ? `${stageLabel[job.stage] ?? job.stage ?? '—'} · ${jobStateText(job)}` : '尚无作业进度', + progress, // 只有仍然 held 的失败才配 held 处置说明;窗口已释放时那段文案是假的。 - recoveryError: failed && held ? job?.error || '作业失败但没有留下错误明细' : '', - releasedFailure: failed && !held ? job?.error || '作业失败但没有留下错误明细' : '', - recoveryNote: job?.recovery || '', - canRecover: held && (failed || !job || job.state === 'cancelled'), + recoveryError: failed && held ? owner?.error || '作业失败但没有留下错误明细' : '', + releasedFailure: failed && !held ? owner?.error || '作业失败但没有留下错误明细' : '', + recoveryNote: owner?.recovery || '', + unreconciledNote: + held && owner && owner.state === 'succeeded' + ? '持有作业已完成但维护窗口仍未释放:维护记录与作业终态未对账,页面不提供强制成功,需按窗口记录人工核验' + : '', + scopeNote, + canRecover: held && Boolean(record) && sameScope && Boolean(unsettled), } } export function MaintenanceCard({ maintenance, - job, + ownerJob, + scope, canWrite, onRecover, }: { maintenance: LibraryMaintenanceView | null | undefined - job: LibraryJobRecord | undefined + // 只收“按 owner_job_id 读到的持有作业”,不是 scope 的最新作业。 + ownerJob?: LibraryJobLookup + scope?: string canWrite: boolean onRecover: (windowJobID: string) => void }) { - const summary = maintenanceSummary(maintenance, job) + const summary = maintenanceSummary(maintenance, ownerJob, scope) const record = maintenance?.instance_maintenance ?? maintenance?.maintenance // "没有窗口记录"不等于"没有维护能力":能力是配置事实,接口单独返回。 // 接口没给能力信息时也不能猜,明确写"未知"。 @@ -463,7 +511,11 @@ export function MaintenanceCard({ {summary.state}
  • - 入口 {summary.ingress} + 入口(维护记录,未实时探测) + {summary.ingress} +
  • +
  • + 服务 {summary.services}
  • @@ -479,12 +531,27 @@ export function MaintenanceCard({ 进度:{summary.progress} {summary.releasedAt ? ` · 窗口已于 ${summary.releasedAt} 释放` : ''}

    + {summary.scopeNote ?

    {summary.scopeNote}

    : null} + {summary.held ? ( +

    + 窗口仍被持有:只有维护记录本身释放才算结束,其他作业的完成或失败不改变本窗口。 +

    + ) : null} + {summary.unreconciledNote ? ( +
    + 维护记录未对账 +

    {summary.unreconciledNote}

    +
    + ) : null} {summary.releasedFailure ? (
    作业失败(维护窗口已释放)

    {summary.releasedFailure}

    {summary.recoveryNote ?

    处理记录:{summary.recoveryNote}

    : null} -

    窗口已释放、入口{summary.ingress}:这里是历史失败记录,不再按 held 处置,也不提供强制成功。

    +

    + 窗口已释放,维护记录中的入口状态:{summary.ingress}(未实时探测):这里是历史失败记录,不再按 held + 处置,也不提供强制成功。 +

    ) : null} {summary.recoveryError ? ( @@ -1444,6 +1511,7 @@ export function ReleaseTargetsView(props: ViewProps) { onRestore, now, maintenance, + maintenanceOwnerJob, onRefresh, onCapture, onRecover, @@ -1642,7 +1710,13 @@ export function ReleaseTargetsView(props: ViewProps) {

    启动后先固定测试版本,再备份生产。备份失败或恢复条件不满足,不进入生产写入。

    - + {active ? ( onDrawer(true)} /> @@ -1705,6 +1779,13 @@ export function ReleaseTargets() { internal: null, external: null, }) + // 维护窗口持有作业的详情:按 owner_job_id 单独读,和 scope 最新作业无关。 + const [maintenanceJobs, setMaintenanceJobs] = useState>({ + internal: { state: 'unread' }, + external: { state: 'unread' }, + }) + // 轮询会并发多次 load:晚到的旧响应不许覆盖更新的维护窗口/作业。 + const loadSeq = useRef(0) const [scope, setScope] = useState('internal') const [drawerOpen, setDrawerOpen] = useState(false) const [expandedSnapshot, setExpandedSnapshot] = useState(null) @@ -1712,6 +1793,7 @@ export function ReleaseTargets() { const [now, setNow] = useState(() => Date.now()) const load = useCallback(async (signal?: AbortSignal) => { + const seq = ++loadSeq.current setLoading(true) try { const [snapshots, captures, internalOverview, externalOverview, internalMaintenance, externalMaintenance] = @@ -1723,17 +1805,35 @@ export function ReleaseTargets() { fetchLibraryMaintenance('internal', signal), fetchLibraryMaintenance('external', signal), ]) + // 只读既有作业详情接口,按维护记录的 owner_job_id 精确取;读不到就记下来, + // 不用 overview 的最新作业兜底(那是另一件事,会把失败窗口显示成已完成)。 + const ownerIDs = { + internal: maintenanceOwnerJobID(internalMaintenance), + external: maintenanceOwnerJobID(externalMaintenance), + } + const [internalOwnerJob, externalOwnerJob] = await Promise.all([ + ownerIDs.internal + ? fetchLibraryJobDetail(ownerIDs.internal, signal) + : Promise.resolve({ state: 'unread' }), + ownerIDs.external + ? fetchLibraryJobDetail(ownerIDs.external, signal) + : Promise.resolve({ state: 'unread' }), + ]) + // 晚回包直接丢掉:不覆盖更新的窗口,也不把旧窗口的作业挂到新窗口上。 + if (seq !== loadSeq.current) return setPage(snapshots) setJobs(captures) setOverviews({ internal: internalOverview, external: externalOverview }) setMaintenances({ internal: internalMaintenance, external: externalMaintenance }) + setMaintenanceJobs({ internal: internalOwnerJob, external: externalOwnerJob }) setNow(Date.now()) setError(null) } catch (loadError) { if ((loadError as Error).name === 'AbortError') return + if (seq !== loadSeq.current) return setError(loadError instanceof Error ? loadError.message : '加载发布状态失败') } finally { - setLoading(false) + if (seq === loadSeq.current) setLoading(false) } }, []) @@ -2001,6 +2101,7 @@ export function ReleaseTargets() { onGrantRestore={() => void grantRestore()} onRestore={() => void startRestore()} maintenance={maintenances[scope]} + maintenanceOwnerJob={maintenanceJobs[scope]} now={now} onRefresh={() => void load()} onCapture={() => void startCapture()} diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts index 54f478e..c2a62c1 100644 --- a/web/src/librarySnapshots.ts +++ b/web/src/librarySnapshots.ts @@ -531,6 +531,56 @@ export async function fetchLibraryMaintenance( return value as unknown as LibraryMaintenanceView } +/** + * 持有维护窗口的作业 id:实例级记录优先(它才是真正的互斥来源),库级记录兜底。 + * 页面只能按这个 id 去读作业详情 —— 同 scope 的最新作业可能是一次无关的封存。 + */ +export function maintenanceOwnerJobID(view: LibraryMaintenanceView | null | undefined): string { + const record = view?.instance_maintenance ?? view?.maintenance ?? null + return record?.owner_job_id ?? '' +} + +/** + * 持有作业详情的读取结果。失败必须分类,不能都缩成"不存在": + * - missing:接口明确 404 ⇒ 维护记录引用了一个未登记的作业; + * - error:网络/非 2xx/结构不符 ⇒ 只是"没读到",页面只能照实说未知; + * - unread:还没发出读取(例如刚切 scope)。 + * 把 error 当 missing 会让"读不到"看起来像一条库内结论。 + */ +export type LibraryJobLookup = + | { state: 'loaded'; job: LibraryJobRecord } + | { state: 'missing' } + | { state: 'error'; reason: string } + | { state: 'unread' } + +export async function fetchLibraryJobDetail(id: string, signal?: AbortSignal): Promise { + if (!id) return { state: 'unread' } + const response = await fetch(`/api/v1/library/jobs/${encodeURIComponent(id)}`, { + headers: { Accept: 'application/json' }, + signal, + }).catch((error: unknown) => { + if ((error as Error)?.name === 'AbortError') throw error + return null + }) + if (!response) return { state: 'error', reason: '请求失败' } + if (response.status === 404) return { state: 'missing' } + if (!response.ok) return { state: 'error', reason: `HTTP ${response.status}` } + const value = (await response.json().catch(() => null)) as unknown + const job = record(value) ? value.job : null + if ( + !record(job) || + typeof job.id !== 'string' || + job.id === '' || + typeof job.state !== 'string' || + typeof job.scope !== 'string' + ) { + return { state: 'error', reason: '响应结构不符合预期(缺少 job 的 id/state/scope)' } + } + // 身份不符说明拿到的不是这次请求的作业(晚回包/串包):宁可报读取失败,也不能拿去展示。 + if (job.id !== id) return { state: 'error', reason: `返回的作业 ${job.id} 与请求的 ${id} 不一致` } + return { state: 'loaded', job: job as unknown as LibraryJobRecord } +} + export interface LibraryRecoveryAccepted { accepted?: boolean recovery_job?: string diff --git a/web/src/releaseTargetsMaintenance.test.tsx b/web/src/releaseTargetsMaintenance.test.tsx index b7ad40f..6bc608c 100644 --- a/web/src/releaseTargetsMaintenance.test.tsx +++ b/web/src/releaseTargetsMaintenance.test.tsx @@ -1,7 +1,8 @@ import { renderToStaticMarkup } from 'react-dom/server' -import { describe, expect, it } from 'vitest' +import { afterEach, describe, expect, it } from 'vitest' import { MaintenanceCard, maintenanceSummary, wikiContributionLines } from './ReleaseTargets' +import { fetchLibraryJobDetail } from './librarySnapshots' import type { LibraryDiff, LibraryJobRecord, LibraryMaintenanceView } from './librarySnapshots' const job: LibraryJobRecord = { @@ -43,7 +44,7 @@ const heldInstance: LibraryMaintenanceView = { describe('维护级别/进度/恢复错误', () => { it('实例级持有:显示级别、入口状态、进度与恢复错误,并允许按预备份恢复', () => { - const summary = maintenanceSummary(heldInstance, job) + const summary = maintenanceSummary(heldInstance, { state: 'loaded', job }) expect(summary.level).toBe('实例级') expect(summary.held).toBe(true) expect(summary.ingress).toContain('已关闭') @@ -54,9 +55,21 @@ describe('维护级别/进度/恢复错误', () => { expect(summary.canRecover).toBe(true) const html = renderToStaticMarkup( - undefined} /> + undefined} + /> ) - for (const text of ['目标维护', '实例级', '入口 已关闭', '按预备份恢复', '写入生产 chunks 失败']) { + for (const text of [ + '目标维护', + '实例级', + '入口(维护记录,未实时探测)', + '已关闭', + '按预备份恢复', + '写入生产 chunks 失败', + ]) { expect(html).toContain(text) } }) @@ -67,7 +80,7 @@ describe('维护级别/进度/恢复错误', () => { expect(summary.held).toBe(false) expect(summary.canRecover).toBe(false) const html = renderToStaticMarkup( - undefined} /> + undefined} /> ) expect(html).toContain('暂无维护窗口') expect(html).not.toContain('按预备份恢复') @@ -85,13 +98,18 @@ describe('维护级别/进度/恢复错误', () => { ingress_state: 'open', }, } - const summary = maintenanceSummary(released, job) + const summary = maintenanceSummary(released, { state: 'loaded', job }) expect(summary.held).toBe(false) expect(summary.recoveryError).toBe('') expect(summary.releasedFailure).toContain('写入生产 chunks 失败') const html = renderToStaticMarkup( - undefined} /> + undefined} + /> ) expect(html).not.toContain('目标保持维护') expect(html).not.toContain('收尾没有完成') @@ -101,7 +119,12 @@ describe('维护级别/进度/恢复错误', () => { it('仍在持有的失败作业保留 held 诊断文案', () => { const html = renderToStaticMarkup( - undefined} /> + undefined} + /> ) expect(html).toContain('目标保持维护') expect(html).toContain('收尾没有完成') @@ -116,13 +139,242 @@ describe('维护级别/进度/恢复错误', () => { state: 'recovered', }, } - const summary = maintenanceSummary(released, job) + const summary = maintenanceSummary(released, { state: 'loaded', job }) expect(summary.held).toBe(false) expect(summary.canRecover).toBe(false) expect(summary.releasedAt).not.toBe('') }) }) +// ---- 维护窗口的作业归属(A 窗口 ≠ 该 scope 最新作业 B)---- +// +// 真实事故(2026-11-03 22:48 CST):对内维护窗口 owner_job_id=libverify-…A 仍是 +// needs_restore/ingress closed,但 scope 上最新作业是成功封存 B(libseal-…,completed/export)。 +// 页面把 B 的“导出 · 已完成”当成窗口进度,于是需要处理的窗口看起来已经完成。 +const ownerVerify: LibraryJobRecord = { + id: 'libverify-internal-A', + scope: 'internal', + kind: 'verify', + state: 'failed', + stage: 'verify', + request_digest: 'v', + queue_job_id: 'qv', + snapshot_id: '', + target_snapshot_id: '', + actor: 'admin', + error: '恢复验证失败:canary 校验不一致', + recovery: '预备份保留;按归档人工核验', + created_at: '2026-11-03T09:20:00Z', + updated_at: '2026-11-03T09:24:00Z', + finished_at: '2026-11-03T09:24:00Z', + stages: [], +} + +const latestSeal: LibraryJobRecord = { + ...ownerVerify, + id: 'libseal-lib-internal-B', + kind: 'seal', + state: 'succeeded', + stage: 'export', + error: '', + recovery: '', + finished_at: '2026-11-03T09:23:52Z', +} + +const unrelatedFailure: LibraryJobRecord = { + ...latestSeal, + id: 'libseal-lib-internal-C', + state: 'failed', + stage: 'index', + error: '封存索引导出失败:与维护窗口无关', + finished_at: '2026-11-03T09:25:00Z', +} + +const needsRestore: LibraryMaintenanceView = { + held: true, + instance: 'kgmaint-weknora', + instance_maintenance: { + instance: 'kgmaint-weknora', + owner_scope: 'internal', + scope: 'internal', + owner_job_id: 'libverify-internal-A', + level: 'instance', + services: ['app'], + ingress_state: 'closed', + state: 'needs_restore', + acquired_at: '2026-11-03T09:20:00Z', + updated_at: '2026-11-03T09:24:00Z', + released_at: null, + }, +} + +describe('维护窗口作业归属', () => { + it('持有作业 A 失败时显示 A 的进度/错误,不显示较新封存 B 的“导出 · 已完成”', () => { + const summary = maintenanceSummary(needsRestore, { state: 'loaded', job: ownerVerify }, 'internal') + expect(summary.progress).toContain('校验') + expect(summary.progress).toContain('失败') + expect(summary.progress).not.toContain('导出') + expect(summary.recoveryError).toContain('canary 校验不一致') + expect(summary.canRecover).toBe(true) + + const html = renderToStaticMarkup( + undefined} + /> + ) + expect(html).not.toContain('导出 · 已完成') + expect(html).toContain('canary 校验不一致') + expect(html).toContain('按预备份恢复') + // 入口只是维护记录里的字段,页面不得声称实时探测过服务。 + expect(html).toContain('维护记录,未实时探测') + }) + + it('调用方误把较新成功封存 B 传进来时,身份不匹配 ⇒ 明确“持有作业状态未读取”,不冒成功', () => { + const summary = maintenanceSummary(needsRestore, { state: 'loaded', job: latestSeal }, 'internal') + expect(summary.progress).not.toContain('导出') + expect(summary.progress).not.toContain('已完成') + expect(summary.progress).toContain('未读取') + expect(summary.recoveryError).toBe('') + const html = renderToStaticMarkup( + undefined} + /> + ) + expect(html).not.toContain('导出 · 已完成') + // 窗口本身仍是 needs_restore:需要处理的原窗口不能被隐藏。 + expect(html).toContain('needs_restore') + }) + + it('无关的最新失败作业不把错误串进本窗口', () => { + const summary = maintenanceSummary(needsRestore, { state: 'loaded', job: unrelatedFailure }, 'internal') + expect(summary.recoveryError).toBe('') + expect(summary.progress).not.toContain('封存索引导出失败') + }) + + it('持有作业仍在运行 ⇒ 同窗口不允许并发恢复', () => { + const running: LibraryJobRecord = { ...ownerVerify, state: 'running', stage: 'database', finished_at: null } + const summary = maintenanceSummary(needsRestore, { state: 'loaded', job: running }, 'internal') + expect(summary.progress).toContain('执行中') + expect(summary.canRecover).toBe(false) + const html = renderToStaticMarkup( + undefined} + /> + ) + expect(html).not.toContain('按预备份恢复') + }) + + it('窗口已释放的持有作业失败只留历史记录,不提供恢复', () => { + const released: LibraryMaintenanceView = { + held: false, + instance_maintenance: { + ...needsRestore.instance_maintenance!, + state: 'released', + ingress_state: 'open', + released_at: '2026-11-03T10:00:00Z', + }, + } + const summary = maintenanceSummary(released, { state: 'loaded', job: ownerVerify }, 'internal') + expect(summary.held).toBe(false) + expect(summary.canRecover).toBe(false) + expect(summary.releasedFailure).toContain('canary 校验不一致') + expect(summary.releasedAt).not.toBe('') + }) + + it('跨 scope 查看实例级窗口:不给本 scope 投递恢复', () => { + const summary = maintenanceSummary(needsRestore, { state: 'loaded', job: ownerVerify }, 'external') + expect(summary.canRecover).toBe(false) + expect(summary.scopeNote).toContain('internal') + expect(summary.scopeNote).toContain('external') + const html = renderToStaticMarkup( + undefined} + /> + ) + expect(html).not.toContain('按预备份恢复') + }) + + it('持有作业详情读取失败/不存在时明确未知,不退回最新作业也不编造成功', () => { + const failedRead = maintenanceSummary(needsRestore, { state: 'error', reason: 'HTTP 503' }, 'internal') + expect(failedRead.progress).toContain('读取失败') + expect(failedRead.progress).toContain('HTTP 503') + expect(failedRead.recoveryError).toBe('') + + const missing = maintenanceSummary(needsRestore, { state: 'missing' }, 'internal') + expect(missing.progress).toContain('不存在') + expect(missing.recoveryError).toBe('') + + const unread = maintenanceSummary(needsRestore, { state: 'unread' }, 'internal') + expect(unread.progress).toContain('未读取') + // needs_restore 是已确认的维护契约:作业详情读不到也保留恢复入口,由后端按窗口校验。 + expect(unread.canRecover).toBe(true) + }) +}) + +describe('fetchLibraryJobDetail(只读作业详情)', () => { + const originalFetch = globalThis.fetch + afterEach(() => { + globalThis.fetch = originalFetch + }) + + it('按 owner id 读取并校验结构', async () => { + let seen = '' + globalThis.fetch = (async (url: string) => { + seen = String(url) + return new Response(JSON.stringify({ available: true, job: ownerVerify }), { status: 200 }) + }) as unknown as typeof fetch + const value = await fetchLibraryJobDetail('libverify-internal-A') + expect(seen).toBe('/api/v1/library/jobs/libverify-internal-A') + expect(value.state).toBe('loaded') + expect(value.state === 'loaded' && value.job.id).toBe('libverify-internal-A') + }) + + it('id 里的特殊字符必须编码,且返回别的作业按读取失败处理', async () => { + let seen = '' + globalThis.fetch = (async (url: string) => { + seen = String(url) + return new Response(JSON.stringify({ available: true, job: ownerVerify }), { status: 200 }) + }) as unknown as typeof fetch + const value = await fetchLibraryJobDetail('libverify/internal A') + expect(seen).toBe('/api/v1/library/jobs/libverify%2Finternal%20A') + // 串包/晚回包:返回的不是请求的那个作业,不能拿去展示。 + expect(value.state).toBe('error') + }) + + it('404 是“作业不存在”,不是读取失败', async () => { + globalThis.fetch = (async () => + new Response(JSON.stringify({ available: false }), { status: 404 })) as unknown as typeof fetch + expect((await fetchLibraryJobDetail('x')).state).toBe('missing') + }) + + it('5xx 与结构不符是“读取失败”,不能吞成不存在', async () => { + globalThis.fetch = (async () => new Response('{}', { status: 503 })) as unknown as typeof fetch + const error = await fetchLibraryJobDetail('x') + expect(error.state).toBe('error') + expect(error.state === 'error' && error.reason).toContain('503') + + globalThis.fetch = (async () => + new Response(JSON.stringify({ available: true, job: { id: 'x' } }), { status: 200 })) as unknown as typeof fetch + expect((await fetchLibraryJobDetail('x')).state).toBe('error') + }) +}) + describe('Wiki 贡献级差异展示', () => { const diff: LibraryDiff = { state: 'computed',