// 恢复验证的页面数据层:读证据 + 投递真实演练。 // // 关键约定: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 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 { 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 { 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 { 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 { 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 || '还没有验证记录' }