// 「整库版本」页的只读客户端:列已经封存的整库候选产物。 // // 这里没有任何写操作:封存需要维护窗口(停真实写入者)与来源凭据,只能由运维 // 命令在目标主机执行。页面只负责如实展示已封存的内容,不提供"开始同步"这类 // 没接线的假按钮。 export interface LibrarySnapshotPart { kind: string name: string sha256: string count: number bytes: number } export interface LibraryCompatibility { weknora_version: string schema_version: number retriever_engine: string embedding_model: string embedding_dimension: number index_mapping_sha256: string } export interface LibrarySnapshot { source_id?: string source_identity?: { project: string; app: string; scope: string; tenant_id: number; knowledge_base_id: string } snapshot_id: string scope: string knowledge_base_id: string tenant_id: number created_at: string validation_policy: string format: string compatibility: LibraryCompatibility parts: LibrarySnapshotPart[] logical_bytes: number unique_bytes: number shared_bytes: number totals: Record } export interface LibraryCaptureJob { job_id: string capture_job: string scope: string state: string attempt: number last_error: string requested_by: string created_at: string updated_at: string } export interface LibraryCaptureAccepted { job_id: string capture_job: string scope: string state: string // true when the idempotency key matched an existing job; the response then // reports the stored job's scope, not the requested one. reused: boolean } export interface LibrarySnapshotList { available: boolean reason: string archive_root: string snapshots: LibrarySnapshot[] // 归档级口径:content_bytes 是跨版本去重后、被版本引用的内容字节; // 其余字段是文件系统事实,都不是可回收空间。 versions: number content_bytes: number blob_file_bytes: number blob_allocated_bytes: number unreferenced_blobs: number unreferenced_bytes: number manifest_file_bytes: number manifest_allocated_bytes: number capture_note: string capture_available: boolean capture_reason: string } const record = (value: unknown): value is Record => typeof value === 'object' && value !== null && !Array.isArray(value) const text = (value: unknown) => (typeof value === 'string' ? value : '') const num = (value: unknown) => (typeof value === 'number' && Number.isFinite(value) ? value : 0) const bool = (value: unknown) => value === true function parsePart(raw: unknown): LibrarySnapshotPart | null { if (!record(raw)) return null const kind = text(raw.kind) const name = text(raw.name) if (!kind || !name) return null return { kind, name, sha256: text(raw.sha256), count: num(raw.count), bytes: num(raw.bytes) } } function parseSnapshot(raw: unknown): LibrarySnapshot | null { if (!record(raw)) return null const snapshotID = text(raw.snapshot_id) if (!snapshotID) return null const compatibility = record(raw.compatibility) ? raw.compatibility : {} const totals: Record = {} if (record(raw.totals)) { for (const [key, value] of Object.entries(raw.totals)) totals[key] = num(value) } return { snapshot_id: snapshotID, source_id: text(raw.source_id) || undefined, source_identity: record(raw.source_identity) ? { project: text(raw.source_identity.project), app: text(raw.source_identity.app), scope: text(raw.source_identity.scope), tenant_id: num(raw.source_identity.tenant_id), knowledge_base_id: text(raw.source_identity.knowledge_base_id), } : undefined, scope: text(raw.scope), knowledge_base_id: text(raw.knowledge_base_id), tenant_id: num(raw.tenant_id), created_at: text(raw.created_at), validation_policy: text(raw.validation_policy), format: text(raw.format), compatibility: { weknora_version: text(compatibility.weknora_version), schema_version: num(compatibility.schema_version), retriever_engine: text(compatibility.retriever_engine), embedding_model: text(compatibility.embedding_model), embedding_dimension: num(compatibility.embedding_dimension), index_mapping_sha256: text(compatibility.index_mapping_sha256), }, parts: Array.isArray(raw.parts) ? raw.parts.map(parsePart).filter((item): item is LibrarySnapshotPart => item !== null) : [], logical_bytes: num(raw.logical_bytes), unique_bytes: num(raw.unique_bytes), shared_bytes: num(raw.shared_bytes), totals, } } export async function fetchLibrarySnapshots(signal?: AbortSignal): Promise { const response = await fetch('/api/v1/library/snapshots', { headers: { Accept: 'application/json' }, signal, }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok && !record(value)) { throw new Error(`加载整库版本失败(HTTP ${response.status})`) } if (!record(value)) throw new Error('整库版本响应无效') const snapshots = Array.isArray(value.snapshots) ? value.snapshots.map(parseSnapshot).filter((item): item is LibrarySnapshot => item !== null) : [] return { available: bool(value.available), reason: text(value.reason), archive_root: text(value.archive_root), snapshots, versions: num(value.versions), content_bytes: num(value.content_bytes), blob_file_bytes: num(value.blob_file_bytes), blob_allocated_bytes: num(value.blob_allocated_bytes), unreferenced_blobs: num(value.unreferenced_blobs), unreferenced_bytes: num(value.unreferenced_bytes), manifest_file_bytes: num(value.manifest_file_bytes), manifest_allocated_bytes: num(value.manifest_allocated_bytes), capture_note: text(value.capture_note), capture_available: bool(value.capture_available), capture_reason: text(value.capture_reason), } } // 页面发起的封存只投递作业;停写入者、导出与恢复都在主机侧 agent 执行。 export async function enqueueLibraryCapture(scope: string): Promise { const response = await fetch('/api/v1/library/captures', { 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 (response.status === 503 && record(value)) { throw new Error(text(value.reason) || '主机侧封存 agent 未接线') } throw new Error(`发起封存失败(HTTP ${response.status})`) } if (!record(value)) throw new Error('封存作业响应无效') return { job_id: text(value.job_id), capture_job: text(value.capture_job), scope: text(value.scope), state: text(value.state), reused: bool(value.reused), } } // 恢复能不能点,由真实条件决定:双闸、这份快照的恢复授权、目标实例是否在维护。 export interface LibraryRestoreAvailability { allowed: boolean reasons: string[] scope: string snapshot_id: string authorization: LibraryAuthorizationView } export async function fetchLibraryRestoreAvailability( scope: string, snapshotID: string, signal?: AbortSignal ): Promise { const query = `scope=${encodeURIComponent(scope)}&snapshot_id=${encodeURIComponent(snapshotID)}` const response = await fetch(`/api/v1/library/restore-availability?${query}`, { headers: { Accept: 'application/json' }, signal, }) const value = (await response.json().catch(() => null)) as unknown if (!record(value)) return null return { allowed: bool(value.allowed), reasons: Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : [], scope: text(value.scope), snapshot_id: text(value.snapshot_id), authorization: record(value.authorization) ? { state: text(value.authorization.state) === 'active' ? 'active' : 'none', authorized_by: text(value.authorization.authorized_by) || undefined, expires_at: text(value.authorization.expires_at) || undefined, reason: text(value.authorization.reason) || undefined, } : { state: 'none' }, } } // 恢复整套生产知识状态:同一份快照的文档、分块、索引、资源与 Wiki 一起回放。 export interface LibraryRestoreAccepted { job_id: string scope: string reused: boolean } export async function enqueueLibraryRestore(scope: string, snapshotID: string): Promise { const response = await fetch('/api/v1/library/restores', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify({ scope, snapshot_id: snapshotID }), }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { if (response.status === 403) throw new Error('按版本恢复仅管理员可发起。') if (response.status === 503 && record(value)) { const reasons = Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : [] throw new Error(reasons.length > 0 ? reasons.join(';') : text(value.error) || '恢复条件不满足') } if (response.status === 409 && record(value)) 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), reused: bool(value.reused) } } export interface LibraryRestoreGrant { id: string authorized_by: string expires_at: string } // 同步授权与执行是两步:授权把"范围 + 目标快照 + 参数摘要"钉死并给很短的有效期。 // 它不能顶替恢复授权(摘要不同),也不自动签发 —— 必须由管理员显式点击。 export async function createLibrarySyncAuthorization( scope: string, snapshotID: string, minutes = 30 ): Promise { const response = await fetch('/api/v1/library/authorizations', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify({ scope, snapshot_id: snapshotID, action: 'sync', expires_in_minutes: minutes }), }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { if (response.status === 403) throw new Error('生产发布授权仅管理员可签发。') if (response.status === 400 && record(value)) throw new Error(text(value.error) || '授权参数不合法') throw new Error(`签发同步授权失败(HTTP ${response.status})`) } if (!record(value) || !record(value.authorization)) throw new Error('授权响应无效') return { id: text(value.authorization.id), authorized_by: text(value.authorization.authorized_by), expires_at: text(value.authorization.expires_at), } } export interface LibrarySyncAccepted { job_id: string scope: string reused: boolean } // 启动同步:闸口未齐时接口返回 503 与逐条缺项,页面照实显示,不假装已启动。 export async function enqueueLibrarySync( scope: string, targetSnapshotID: string, sourceID: string ): Promise { const response = await fetch('/api/v1/library/syncs', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify({ scope, target_snapshot_id: targetSnapshotID, source_id: sourceID }), }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { 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), reused: bool(value.reused) } } // 建立目标权威基线:目标非空又没有生效版本时的唯一入口(维护隔离 + 真实捕获 + 校验)。 export async function enqueueLibraryBaseline(scope: string): Promise { const response = await fetch('/api/v1/library/baselines', { 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) && 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), reused: bool(value.reused) } } // 恢复授权与执行是两件事:授权把"目标 + 快照 + 参数"钉死并给很短的有效期, // 同步授权不能顶替恢复授权(摘要不同)。 export async function createLibraryRestoreAuthorization( scope: string, snapshotID: string, minutes = 30 ): Promise { const response = await fetch('/api/v1/library/authorizations', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify({ scope, snapshot_id: snapshotID, action: 'restore', expires_in_minutes: minutes }), }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { if (response.status === 403) throw new Error('生产发布授权仅管理员可签发。') throw new Error(`签发恢复授权失败(HTTP ${response.status})`) } if (!record(value) || !record(value.authorization)) throw new Error('授权响应无效') return { id: text(value.authorization.id), authorized_by: text(value.authorization.authorized_by), expires_at: text(value.authorization.expires_at), } } export async function fetchLibraryCaptures(signal?: AbortSignal): Promise { const response = await fetch('/api/v1/library/captures', { headers: { Accept: 'application/json' }, signal, }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok || !record(value) || !Array.isArray(value.jobs)) return [] return value.jobs.filter(record).map((job) => ({ job_id: text(job.job_id), capture_job: text(job.capture_job), scope: text(job.scope), state: text(job.state), attempt: num(job.attempt), last_error: text(job.last_error), requested_by: text(job.requested_by), created_at: text(job.created_at), updated_at: text(job.updated_at), })) } export function formatBytes(bytes: number): string { if (!Number.isFinite(bytes) || bytes <= 0) return '0 B' const units = ['B', 'KB', 'MB', 'GB', 'TB'] let index = 0 let value = bytes while (value >= 1024 && index < units.length - 1) { value /= 1024 index += 1 } return `${value >= 10 || index === 0 ? value.toFixed(0) : value.toFixed(1)} ${units[index]}` } export function scopeLabel(scope: string): string { if (scope === 'internal') return '对内' if (scope === 'external') return '对外' return scope || '未知范围' } // ---- 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业 ---- export interface LibraryVersionRecord { id: string kind: 'test_sealed' | 'production_effective' | 'production_prebackup' snapshot_id: string version_label: string source_job_id: string evidence: Record created_by: string created_at: string superseded_at?: string | null } export interface LibraryKnown { state: 'known' | 'unknown' version?: LibraryVersionRecord reason?: string /** 只在预备份上有意义:这份备份的内容是否就是当前拟发布目标。 */ bound_to_target?: boolean } export interface LibraryDiff { state: 'unknown' | 'computed' reason?: string added: unknown[] updated: unknown[] removed: unknown[] /** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */ base_snapshot?: string target_snapshot?: string /** * Wiki 逐页贡献级差异:来源文档 / 引用分块 / 出入边 / 目录分别比。 * 语义重算发生在源侧,这里只如实反映重算后的结果——撤销一份共享贡献时 * 页面通常还是"更新",要看 pages[].sources_removed 才知道那份贡献被摘掉了。 */ wiki?: { state: 'computed' | 'unknown' reason?: string added: number updated: number removed: number sample: string[] note: string pages?: LibraryWikiPageChange[] pages_truncated?: boolean sources_added?: number sources_removed?: number base_count?: number target_count?: number } } export interface LibraryWikiPageChange { slug: string title: string page_type?: string status: 'added' | 'updated' | 'removed' changed: string[] sources_added?: string[] sources_removed?: string[] citations_before: number citations_after: number } // ---- 目标维护窗口:级别、阶段、入口状态与恢复错误 ---- export interface LibraryMaintenanceRecord { scope: string owner_job_id: string target_identity?: string level: string target_fingerprint?: string services?: string[] ingress_state: string state: string original_service_state?: string note?: string acquired_at: string updated_at: string released_at?: string | null } export interface LibraryInstanceMaintenanceRecord extends LibraryMaintenanceRecord { instance: string owner_scope: string } export interface LibraryMaintenanceView { held: boolean maintenance?: LibraryMaintenanceRecord | null instance?: string instance_maintenance?: LibraryInstanceMaintenanceRecord | null // 能力是配置事实,和"此刻有没有窗口"分开:未运行维护 ≠ 没有维护能力。 capability?: LibraryMaintenanceCapability | null } export interface LibraryMaintenanceCapability { configured: boolean missing: string[] instance?: string project?: string writers?: string[] ingress_service?: string note?: string } export async function fetchLibraryMaintenance( scope: string, signal?: AbortSignal ): Promise { const response = await fetch(`/api/v1/library/maintenance?scope=${encodeURIComponent(scope)}`, { headers: { Accept: 'application/json' }, signal, }) if (!response.ok) return null const value = (await response.json().catch(() => null)) as unknown if (!record(value)) return null return value as unknown as LibraryMaintenanceView } export interface LibraryRecoveryAccepted { accepted?: boolean recovery_job?: string state?: string code?: string error?: string } export async function enqueueLibraryRecovery(scope: string, windowJobID: string): Promise { const response = await fetch('/api/v1/library/maintenance/recover', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify({ scope, window_job_id: windowJobID }), }) const value = (await response.json().catch(() => ({}))) as unknown const body = record(value) ? (value as LibraryRecoveryAccepted) : {} if (!response.ok) { throw new Error(body.error || `恢复请求被拒绝(HTTP ${response.status})`) } return body } export interface LibraryStageRow { stage: string state: string total: number | null completed: number | null bytes_total: number | null bytes_done: number | null detail: string updated_at: string } export interface LibraryJobRecord { id: string scope: string kind: 'seal' | 'sync' | 'restore' | 'baseline' state: 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' stage: string request_digest: string queue_job_id: string snapshot_id: string target_snapshot_id: string actor: string error: string recovery: string created_at: string updated_at: string finished_at?: string | null stages: LibraryStageRow[] } /** * 已登记版本的轻量清单(不含 evidence)。 * 归档里不止"测试封存":目标基线与每次生产预备份也在同一个归档根下, * 页面必须按登记过的 kind 给每份快照写类型,不能一律写"测试封存"。 */ export interface LibraryVersionRef { id: string kind: 'test_sealed' | 'production_effective' | 'production_prebackup' | string snapshot_id: string version_label: string source_job_id: string created_at: string superseded_at?: string | null } export interface LibraryAuthorizationView { state: 'active' | 'none' authorized_by?: string expires_at?: string reason?: string } export interface LibraryGate { sync_allowed: boolean reasons: string[] } export interface LibraryExecutorView { available: boolean reason?: string instance?: string project?: string source_app?: string archive_root?: string busy: boolean degraded?: string observed_at?: string } export interface LibraryOverview { scope: string test_sealed?: LibrarySnapshot test_sealed_reason?: string production: LibraryKnown prebackup: LibraryKnown /** 已登记版本(轻量):页面据此给归档里的每份快照标类型。 */ versions?: LibraryVersionRef[] diff: LibraryDiff job?: LibraryJobRecord jobs: LibraryJobRecord[] gate: LibraryGate authorization: LibraryAuthorizationView capture_available: boolean capture_reason?: string // 执行器是 worker 的真实观测:指向哪个实例、何时观测、是否降级/在跑。 executor?: LibraryExecutorView now: string } export async function fetchLibraryOverview(scope: string, signal?: AbortSignal): Promise { const response = await fetch(`/api/v1/library/overview?scope=${encodeURIComponent(scope)}`, { headers: { Accept: 'application/json' }, signal, }) // 非 2xx 的响应体会是 {error: ...},把它 cast 成 LibraryOverview 会让页面在 // `overview.gate.sync_allowed` 上抛 TypeError(F16)。这里必须先核状态码与结构, // 结构不符就**报错**,让页面显示"读取失败"而不是崩溃或当成正常状态。 if (!response.ok) { throw new Error(`发布状态读取失败(HTTP ${response.status})`) } const value = (await response.json().catch(() => null)) as unknown if ( !record(value) || !record((value as { gate?: unknown }).gate) || !Array.isArray((value as { jobs?: unknown }).jobs) ) { throw new Error('发布状态响应结构不符合预期(缺 gate/jobs)') } return value as unknown as LibraryOverview } // ---- 存储管理:容量、保留策略、依赖保护与清理预览(只读) ---- export interface LibraryStorageVersion { id: string kind: string scope: string created_at: string protected: boolean protected_by?: string[] exclusive_bytes: number shared_bytes: number } export interface LibraryRetentionPolicy { keep_versions: number keep_days: number } export interface LibraryCleanupCandidate { id: string kind: string reason: string[] exclusive_bytes: number } export interface LibraryRetentionPlan { policy: LibraryRetentionPolicy policy_configured: boolean automatic_cleanup: boolean version_count: number total_bytes: number protected: string[] keep: string[] candidates: LibraryCleanupCandidate[] reclaim_preview_bytes: number blocked: string[] now: string } export interface LibraryCapacity { budget_bytes: number current_bytes: number required_bytes: number projected_bytes: number configured: boolean ok: boolean reason?: string } export interface LibraryStorage { available: boolean reason?: string archive_root?: string versions: LibraryStorageVersion[] content_bytes: number blob_file_bytes: number blob_allocated_bytes: number unreferenced_blobs: number unreferenced_bytes: number manifest_file_bytes: number policy: LibraryRetentionPolicy plan?: LibraryRetentionPlan capacity: LibraryCapacity automatic_cleanup: boolean notes: string[] } export async function fetchLibraryStorage(signal?: AbortSignal): Promise { const response = await fetch('/api/v1/library/storage', { headers: { Accept: 'application/json' }, signal, }) const value = (await response.json().catch(() => null)) as unknown if (!record(value)) return null return value as unknown as LibraryStorage }