017765763a
build / build (push) Successful in 1m45s
问题:维护窗口 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 与请求不符
按读取失败处理。
未改后端准入、网关协议或任何维护记录;未部署。
426 lines
15 KiB
TypeScript
426 lines
15 KiB
TypeScript
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([])
|
||
})
|
||
})
|