Files
knowledge-governance/web/src/restoreVerification.ts
T
姚章浩 b81fcd07e3
build / build (push) Successful in 1m57s
fix(release): 修复tableState文本身份与快照统计归属
tableState 非 resources 分支恢复直接扫描 text 身份,避免 queryRows 把普通
doc id/UUID/复合键/数字 id 当 JSON canonical 校验而失败;resources 仍使用
F01 精确引用闭包。隔离 PG 覆盖字符串、UUID、复合键与数字 ID。

F11:快照 HTTP 投影补 bindings/wiki_log_entries;作业统计按本作业
target_snapshot_id/snapshot_id 取对应快照,取不到显示未知,不借最新封存;
running/pending/failed/unknown 不再在无 detail 时显示完成。

F03:verifications 支持 snapshot_id 精确查询,返回 snapshot_latest 并只按
该快照回答 verified;抽屉“查看校验记录”按选中快照加载,不借用最新记录。

F08:显示主机探测时间;无真实 next-run 时说明尚未核验下一次执行;最近成功
单列未知,不以最近运行冒充。

验证:Go/前端全量、隔离 PG tableState/F01 对拍与 make verify 17 项通过。
实际 Current→Prepare→Verify ES 集成被共享 ES 磁盘 watermark 阻塞,未冒充。
2026-11-05 13:19:27 +08:00

213 lines
8.9 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.
// 恢复验证的页面数据层:读证据 + 投递真实演练。
//
// 关键约定:verified 只由后端证据回答(当前目标 + scope 的最近一次真实演练)。
// 页面不提供任何"我确认已验证"的开关——那正是旧实现的问题(一个可手填的 env)。
export type LibraryVerificationStatus = 'passed' | 'failed'
export interface LibraryVerificationRecord {
id: string
scope: string
status: LibraryVerificationStatus
snapshot_id: string
job_id: string
failure?: string
report?: Record<string, unknown>
started_at: string
finished_at: string
}
export interface LibraryVerificationTarget {
instance: string
project: string
internal_kb: string
external_kb: string
index: string
s3_bucket: string
tenant_id: number
database_configured: boolean
}
export interface LibraryVerificationView {
scope: string
target: LibraryVerificationTarget
verified: boolean
reason: string
latest?: LibraryVerificationRecord | null
snapshot_latest?: LibraryVerificationRecord | null
history: LibraryVerificationRecord[]
running?: boolean
job_id?: string
state?: string
stage?: string
}
function record(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null
}
function text(value: unknown): string {
return typeof value === 'string' ? value : ''
}
function bool(value: unknown): boolean {
return value === true
}
export function parseVerificationTarget(value: unknown): LibraryVerificationTarget | null {
if (!record(value)) return null
return {
instance: text(value.instance),
project: text(value.project),
internal_kb: text(value.internal_kb),
external_kb: text(value.external_kb),
index: text(value.index),
s3_bucket: text(value.s3_bucket),
tenant_id: typeof value.tenant_id === 'number' ? value.tenant_id : 0,
database_configured: bool(value.database_configured),
}
}
export function parseVerificationRecord(value: unknown): LibraryVerificationRecord | null {
if (!record(value)) return null
const status = text(value.status)
if (status !== 'passed' && status !== 'failed') return null
return {
id: text(value.id),
scope: text(value.scope),
status,
snapshot_id: text(value.snapshot_id),
job_id: text(value.job_id),
failure: text(value.failure) || undefined,
report: record(value.report) ? value.report : undefined,
started_at: text(value.started_at),
finished_at: text(value.finished_at),
}
}
export function parseVerificationView(value: unknown): LibraryVerificationView | null {
if (!record(value)) return null
const target = parseVerificationTarget(value.target)
if (!target) return null
const history = Array.isArray(value.history)
? value.history.map(parseVerificationRecord).filter((item): item is LibraryVerificationRecord => item !== null)
: []
const latest = parseVerificationRecord(value.latest) ?? null
const snapshotLatest = parseVerificationRecord(value.snapshot_latest) ?? null
return {
scope: text(value.scope),
target,
// 只有后端明确说 true 才算已验证:任何解析失败都退回"没有证据"。
verified: bool(value.verified),
reason: text(value.reason),
latest,
snapshot_latest: snapshotLatest,
history,
running: bool(value.running),
job_id: text(value.job_id) || undefined,
state: text(value.state) || undefined,
stage: text(value.stage) || undefined,
}
}
// fetchLibraryVerification 只返回**这份 scope** 的观测:
// HTTP 非 2xx、响应不可解析、或响应 scope 与请求不一致都抛错。
// 调用方据此把"读失败"和"没有证据"分开显示,不能拿旧绿色遮住失败(审核 B5)。
// F03: exact snapshot report. Never fall back to the scope's latest record.
export async function fetchSnapshotVerification(
scope: string,
snapshotID: string,
signal?: AbortSignal
): Promise<LibraryVerificationView> {
const query = `scope=${encodeURIComponent(scope)}&snapshot_id=${encodeURIComponent(snapshotID)}`
const response = await fetch(`/api/v1/library/verifications?${query}`, {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) throw new Error(`读取该快照的恢复验证记录失败(HTTP ${response.status})`)
const parsed = parseVerificationView(value)
if (!parsed) throw new Error('读取该快照的恢复验证记录失败:响应不可解析')
if (parsed.scope !== scope) throw new Error('读取该快照的恢复验证记录失败:scope 不一致')
return parsed
}
export async function fetchLibraryVerification(scope: string, signal?: AbortSignal): Promise<LibraryVerificationView> {
const response = await fetch(`/api/v1/library/verifications?scope=${encodeURIComponent(scope)}`, {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (record(value) && text(value.reason)) throw new Error(`读取验证状态失败:${text(value.reason)}`)
throw new Error(`读取验证状态失败(HTTP ${response.status})`)
}
const parsed = parseVerificationView(value)
if (!parsed) throw new Error('读取验证状态失败:响应不可解析')
if (parsed.scope !== scope)
throw new Error(`读取验证状态失败:响应 scope=${parsed.scope || '空'} 与请求 ${scope} 不一致`)
return parsed
}
export interface LibraryVerificationAccepted {
job_id: string
scope: string
}
// 投递一次真实恢复验证。失败时把后端的逐条拒绝原因原样显示,
// 不把它包装成"稍后再试"——否则用户不知道是闸口、维护还是目标不可达。
export async function enqueueLibraryVerification(scope: string): Promise<LibraryVerificationAccepted> {
const response = await fetch('/api/v1/library/verifications', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ scope }),
})
const value = (await response.json().catch(() => null)) as unknown
if (!response.ok) {
if (response.status === 403) throw new Error('恢复验证仅管理员可发起。')
if (record(value) && Array.isArray(value.reasons)) {
const reasons = value.reasons.map(text).filter(Boolean)
if (reasons.length > 0) throw new Error(`恢复验证被拒绝:${reasons.join(';')}`)
}
if (record(value) && text(value.error)) throw new Error(text(value.error))
throw new Error(`投递恢复验证失败(HTTP ${response.status})`)
}
if (!record(value) || !record(value.job)) throw new Error('恢复验证作业响应无效')
return { job_id: text(value.job.id), scope: text(value.job.scope) }
}
// 目标展示:整库目标必须显示完整 ID 与端点,避免"看着像 2074 文档库"这类误读。
export function verificationTargetLines(target: LibraryVerificationTarget, scope: string): string[] {
const kb = scope === 'internal' ? target.internal_kb : target.external_kb
return [
`实例 ${target.instance || '未配置'} · 项目 ${target.project || '未配置'}`,
`知识库 ${kb || '未配置'}`,
`索引 ${target.index || '未配置'} · 桶 ${target.s3_bucket || '未配置'}`,
`租户 ${target.tenant_id || '未配置'} · 数据库${target.database_configured ? '已配置' : '未配置'}`,
]
}
// verificationStatusText 只在**当前 scope 的新鲜观测**上允许说"已验证"。
// stale 表示这次刷新失败、显示的是上一次结果:它既不是当前结论,也不能是绿灯。
export function verificationStatusText(view: LibraryVerificationView | null, stale = false): string {
if (!view) return '还没有读到验证状态'
if (stale) return '上次观测已过期(刷新失败)'
if (view.running) return '验证执行中'
if (view.verified) return '已验证(当前目标)'
if (view.latest) return view.latest.status === 'failed' ? '最近一次未通过' : '未通过'
return '还没有验证记录'
}
// F03: when the API has a passed record, its reason is empty by design. The
// panel must not fall back to "还没有读到验证状态" and contradict the green
// status. This also keeps loading/error/never-verified distinct.
export function verificationReasonText(view: LibraryVerificationView | null, stale = false): string {
if (!view) return '还没有读到验证状态'
if (stale) return '刷新失败:这是上次成功读取的证据,当前目标是否仍可恢复未知'
if (view.running) return view.reason || `验证作业 ${view.job_id || ''} 正在执行(${view.stage || '执行中'})`
if (view.verified)
return `当前目标的最近一次真实恢复验证已通过${view.latest ? `(快照 ${view.latest.snapshot_id.slice(0, 12)})` : ''}`
if (view.latest) return view.reason || view.latest.failure || '最近一次恢复验证未通过'
return view.reason || '还没有验证记录'
}