feat(library): 恢复验证成为可页面发起的真实作业
build / build (push) Successful in 1m40s

根因:生产可恢复性只有 PRODUCTION_BACKUP_RESTORE_VERIFIED 这个手填 env 开关,
页面没有任何入口去真跑一次恢复;CLI(librarydrill)又不是 worker 能复用的实现,
所以"已验证"既证明不了跑过、也证明不了跑的是当前目标。

改动:
- 共享实现 internal/libraryverify(维护隔离→捕获→基线校验→canary→恢复→复核→关窗口),
  cmd/librarydrill 改为薄封装,CLI 与 worker 只允许一份执行体。
- verify 成为独立业务作业:kind + VerifyStages(capture/verify/canary/restore/finalize),
  与 sync/restore/baseline 共用同一把写互斥;迁移 79 加 kind 约束、重建部分唯一索引、
  新建 library_restore_verifications(按 target_id 绑定,换库/索引/桶旧证据自动失效,
  同 target+scope+job 幂等)。
- worker:admitLibraryJob + runOwnedLibraryAttempt 之后调用共享实现,阶段实时写
  library_job_stages,结束后写真实终态;通过写 passed 证据,失败写 failed+原因(不伪成功);
  中断接管按同一作业 id 收掉维护窗口。
- API:POST/GET /api/v1/library/verifications(管理员;闸口关闭/维护中拒绝;返回完整
  整库目标、最近证据、失败原因),OpenAPI 同步。
- 闸口:同步/恢复/续作的证据判断改为读当前目标证据;历史 env 仅在证据缺失时兜底,
  证据存在时以证据为准。
- 页面:生产保护与恢复面板加「恢复验证」块(完整 KB/索引/桶、状态、最近证据、失败原因、
  管理员按钮、5s 轮询),作业类型补 verify 文案。

测试:make verify 16/16 全绿(go 1387 例 + web 454 例 + 契约/迁移/密钥/依赖锁定);
新增用例覆盖证据四条件、闸口证据优先、页面无证据/失败/通过三种呈现与管理员可见性。
This commit is contained in:
姚章浩
2026-11-03 10:14:08 +08:00
parent 4421dd38ce
commit 5e1482e349
47 changed files with 2502 additions and 353 deletions
+158
View File
@@ -0,0 +1,158 @@
// 恢复验证的页面数据层:读证据 + 投递真实演练。
//
// 关键约定: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
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
history: LibraryVerificationRecord[]
running?: boolean
job_id?: 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,
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
return {
scope: text(value.scope),
target,
// 只有后端明确说 true 才算已验证:任何解析失败都退回"没有证据"。
verified: bool(value.verified),
reason: text(value.reason),
latest,
history,
running: bool(value.running),
job_id: text(value.job_id) || undefined,
}
}
export async function fetchLibraryVerification(
scope: string,
signal?: AbortSignal
): Promise<LibraryVerificationView | null> {
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
return parseVerificationView(value)
}
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 ? '已配置' : '未配置'}`,
]
}
export function verificationStatusText(view: LibraryVerificationView | null): string {
if (!view) return '还没有读到验证状态'
if (view.verified) return '已验证(当前目标)'
if (view.latest) return view.latest.status === 'failed' ? '最近一次未通过' : '未通过'
return '还没有验证记录'
}