Files
knowledge-governance/web/src/releaseTargetsMaintenance.test.tsx
T
姚章浩 017765763a
build / build (push) Successful in 1m45s
fix(library): 维护卡只展示 owner_job_id 匹配的作业详情
问题:维护窗口 record.owner_job_id 指向失败/待恢复的作业 A,但页面把同 scope
最新作业(更新的成功封存 B)当窗口进度,needs_restore 被显示成“导出 · 已完成”,
需要处理的原窗口因此看起来已经结束。

改法:
- maintenanceSummary 只接受“按 owner_job_id 读到的持有作业”,id 不一致一律按
  未读取处理;进度/错误/恢复说明只来自该作业,不拿最新作业兜底。
- 新增 fetchLibraryJobDetail 读取既有只读接口 GET /api/v1/library/jobs/{id},
  明确区分 loaded / missing(404) / error(非2xx、结构不符、id 串包) / unread,
  不把读取失败吞成“不存在”。
- 恢复可用性只由“维护仍持有 + 本窗口作业未收口 + 当前 scope 等于 owner_scope”
  决定;running/pending 不并发恢复,已释放/无记录不提供恢复,跨 scope 给切换提示。
- 入口状态明确标注“维护记录,未实时探测”;held 时说明只有维护记录释放才算结束;
  held 但持有作业已完成时写“维护记录未对账”,不提供强制成功。
- load 增加请求代次守卫,晚回包不覆盖更新的窗口;作业详情返回的 id 与请求不符
  按读取失败处理。

未改后端准入、网关协议或任何维护记录;未部署。
2026-11-03 23:02:00 +08:00

426 lines
15 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { renderToStaticMarkup } from 'react-dom/server'
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 = {
id: 'libsync-internal-1',
scope: 'internal',
kind: 'sync',
state: 'failed',
stage: 'rollback',
request_digest: 'x',
queue_job_id: 'q1',
snapshot_id: '',
target_snapshot_id: '',
actor: 'admin',
error: '写入生产 chunks 失败:连接被拒绝',
recovery: '已按预备份回滚并校验',
created_at: '2026-10-29T04:00:00Z',
updated_at: '2026-10-29T04:02:00Z',
finished_at: '2026-10-29T04:02:00Z',
stages: [],
}
const heldInstance: LibraryMaintenanceView = {
held: true,
instance: 'kgmaint-weknora',
instance_maintenance: {
instance: 'kgmaint-weknora',
owner_scope: 'internal',
scope: 'internal',
owner_job_id: 'libsync-internal-1',
level: 'instance',
services: ['app'],
ingress_state: 'closed',
state: 'held',
acquired_at: '2026-10-29T04:00:00Z',
updated_at: '2026-10-29T04:02:00Z',
released_at: null,
},
}
describe('维护级别/进度/恢复错误', () => {
it('实例级持有:显示级别、入口状态、进度与恢复错误,并允许按预备份恢复', () => {
const summary = maintenanceSummary(heldInstance, { state: 'loaded', job })
expect(summary.level).toBe('实例级')
expect(summary.held).toBe(true)
expect(summary.ingress).toContain('已关闭')
expect(summary.progress).toContain('回滚')
expect(summary.progress).toContain('失败')
expect(summary.recoveryError).toContain('写入生产 chunks 失败')
expect(summary.recoveryNote).toContain('按预备份回滚')
expect(summary.canRecover).toBe(true)
const html = renderToStaticMarkup(
<MaintenanceCard
maintenance={heldInstance}
ownerJob={{ state: 'loaded', job }}
canWrite
onRecover={() => undefined}
/>
)
for (const text of [
'目标维护',
'实例级',
'入口(维护记录,未实时探测)',
'已关闭',
'按预备份恢复',
'写入生产 chunks 失败',
]) {
expect(html).toContain(text)
}
})
it('没有窗口时如实说没有,不画成"已就绪"', () => {
const summary = maintenanceSummary(null, undefined)
expect(summary.level).toBe('未接入')
expect(summary.held).toBe(false)
expect(summary.canRecover).toBe(false)
const html = renderToStaticMarkup(
<MaintenanceCard maintenance={null} ownerJob={{ state: 'unread' }} canWrite onRecover={() => undefined} />
)
expect(html).toContain('暂无维护窗口')
expect(html).not.toContain('按预备份恢复')
})
it('窗口已释放的失败作业不再说"目标保持维护、入口未开"', () => {
// 真实案例:libsync-internal-1793399248431728863 失败后窗口已 released、入口已开,
// 页面却照样渲染 held 诊断文案(只按 failed 渲染),与维护状态自相矛盾。
const released: LibraryMaintenanceView = {
held: false,
instance_maintenance: {
...heldInstance.instance_maintenance!,
released_at: '2026-11-01T03:40:00Z',
state: 'released',
ingress_state: 'open',
},
}
const summary = maintenanceSummary(released, { state: 'loaded', job })
expect(summary.held).toBe(false)
expect(summary.recoveryError).toBe('')
expect(summary.releasedFailure).toContain('写入生产 chunks 失败')
const html = renderToStaticMarkup(
<MaintenanceCard
maintenance={released}
ownerJob={{ state: 'loaded', job }}
canWrite
onRecover={() => undefined}
/>
)
expect(html).not.toContain('目标保持维护')
expect(html).not.toContain('收尾没有完成')
expect(html).toContain('窗口已释放')
expect(html).toContain('写入生产 chunks 失败')
})
it('仍在持有的失败作业保留 held 诊断文案', () => {
const html = renderToStaticMarkup(
<MaintenanceCard
maintenance={heldInstance}
ownerJob={{ state: 'loaded', job }}
canWrite
onRecover={() => undefined}
/>
)
expect(html).toContain('目标保持维护')
expect(html).toContain('收尾没有完成')
})
it('已释放的窗口不再提供恢复入口', () => {
const released: LibraryMaintenanceView = {
held: false,
instance_maintenance: {
...heldInstance.instance_maintenance!,
released_at: '2026-10-29T04:05:00Z',
state: 'recovered',
},
}
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(
<MaintenanceCard
maintenance={needsRestore}
ownerJob={{ state: 'loaded', job: ownerVerify }}
scope="internal"
canWrite
onRecover={() => 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(
<MaintenanceCard
maintenance={needsRestore}
ownerJob={{ state: 'loaded', job: latestSeal }}
scope="internal"
canWrite
onRecover={() => 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(
<MaintenanceCard
maintenance={needsRestore}
ownerJob={{ state: 'loaded', job: running }}
scope="internal"
canWrite
onRecover={() => 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(
<MaintenanceCard
maintenance={needsRestore}
ownerJob={{ state: 'loaded', job: ownerVerify }}
scope="external"
canWrite
onRecover={() => 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',
added: [],
updated: [],
removed: [],
wiki: {
state: 'computed',
added: 0,
updated: 1,
removed: 1,
sample: [],
note: '逐页比对',
sources_removed: 2,
pages: [
{
slug: 'entity/fa-bu-zha-men',
title: '发布闸门',
status: 'updated',
changed: ['正文', '来源文档', '引用分块'],
sources_removed: ['doc-a'],
citations_before: 2,
citations_after: 1,
},
{
slug: 'entity/tu-pu-hui-tian-fu-wu',
title: '图谱回填服务',
status: 'removed',
changed: ['整页撤销'],
citations_before: 1,
citations_after: 0,
},
],
},
}
it('共享页被更新时列出来源减少与引用变化,而不是只说"更新 1 页"', () => {
const lines = wikiContributionLines(diff)
expect(lines[0]).toContain('发布闸门')
expect(lines[0]).toContain('来源 -1')
expect(lines[0]).toContain('引用 2→1')
expect(lines[1]).toContain('整页撤销')
})
it('没有逐页明细时不编造明细', () => {
expect(wikiContributionLines({ state: 'unknown', added: [], updated: [], removed: [] })).toEqual([])
})
})