// 「版本记录」页的客户端:只读查询 + 管理员手动同步。 // 页面读的是本库缓存(Gitea 不可达也能看),同步动作只允许管理员触发。 export type VersionRecordKind = 'release' | 'development' | 'historical' export type VersionState = 'verified' | 'unknown' export type CurrentRunningState = 'matched' | 'development' | 'unknown' export interface VersionHistoryTag { name: string url: string } export interface VersionHistoryItem { commit_sha: string short_sha: string parents: string[] committed_at: string author_display: string subject: string body: string record_kind: VersionRecordKind version_label: string version_state: VersionState release_tags: VersionHistoryTag[] release_notes: string commit_url: string version_reason: string is_current_running: boolean } export interface VersionHistorySyncState { available: boolean status: string complete: boolean last_success_at: string fetched_count: number expected_count: number | null error_code: string source_head_sha: string active_snapshot_id: number repo: string } export interface VersionHistoryCurrentRunning { state: CurrentRunningState commit_sha: string display_version: string matched_commit_sha: string } export interface VersionHistoryPage { items: VersionHistoryItem[] next_cursor: string has_more: boolean sync: VersionHistorySyncState current_running: VersionHistoryCurrentRunning } export interface BuildInfo { release_version: string build_kind: string commit_sha: string | null display_version: string built_at: string identity_available: boolean } export interface SyncAccepted { job_id: string status: string reused: boolean } const record = (value: unknown): value is Record => typeof value === 'object' && value !== null const text = (value: unknown): string => (typeof value === 'string' ? value : '') const bool = (value: unknown): boolean => value === true const count = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0) // 「版本号未能核验」的原因码 → 页面文案(不补造版本号,只解释为什么没有号)。 export const reasonLabels: Record = { annotated_tag_and_changelog_top_match: '注释 tag 与提交内版本记录一致', counted_commits_since_base_tag: '按发布基线数出来的开发号', lightweight_tag: '该提交上的 tag 是轻量 tag,不作为正式版本证据', no_changelog_top: '该提交内没有已发布版本的变更记录', changelog_top_mismatch: 'tag 版本与该提交内的变更记录不一致', no_release_tag_for_commit: '没有指向该提交的正式 tag', no_baseline: '找不到可核验的发布基线(该版本没有对应的 tag)', shallow_or_incomplete_graph: '提交图不完整(检出被截断),提交数算不准', release_tag_created_later: '该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag', } export const reasonLabel = (reason: string): string => reasonLabels[reason] ?? '版本号未能核验' const parseItem = (value: unknown): VersionHistoryItem => { if (!record(value)) throw new Error('版本记录条目无效') return { commit_sha: text(value.commit_sha), short_sha: text(value.short_sha), parents: Array.isArray(value.parents) ? value.parents.filter((item): item is string => typeof item === 'string') : [], committed_at: text(value.committed_at), author_display: text(value.author_display), subject: text(value.subject), body: text(value.body), record_kind: (text(value.record_kind) || 'historical') as VersionRecordKind, version_label: text(value.version_label), version_state: (text(value.version_state) || 'unknown') as VersionState, release_tags: Array.isArray(value.release_tags) ? value.release_tags.filter(record).map((tag) => ({ name: text(tag.name), url: text(tag.url) })) : [], release_notes: text(value.release_notes), commit_url: text(value.commit_url), version_reason: text(value.version_reason), is_current_running: bool(value.is_current_running), } } export async function fetchVersionHistory( params: { kind: string; cursor: string; limit?: number }, signal?: AbortSignal ): Promise { const query = new URLSearchParams() if (params.kind && params.kind !== 'all') query.set('kind', params.kind) if (params.cursor) query.set('cursor', params.cursor) query.set('limit', String(params.limit ?? 30)) const response = await fetch(`/api/v1/version-history?${query.toString()}`, { headers: { Accept: 'application/json' }, signal, }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { const code = record(value) ? text(value.code) : '' if (response.status === 409 || code === 'cursor_expired') { throw new Error('这次翻页依据的记录快照已被清理,请刷新页面重新加载。') } throw new Error(`加载版本记录失败(HTTP ${response.status})`) } if (!record(value) || !Array.isArray(value.items) || !record(value.sync) || !record(value.current_running)) { throw new Error('版本记录响应无效') } const sync = value.sync const running = value.current_running const expected = typeof sync.expected_count === 'number' ? sync.expected_count : null return { items: value.items.map(parseItem), next_cursor: text(value.next_cursor), has_more: bool(value.has_more), sync: { available: bool(sync.available), status: text(sync.status), complete: bool(sync.complete), last_success_at: text(sync.last_success_at), fetched_count: count(sync.fetched_count), expected_count: expected, error_code: text(sync.error_code), source_head_sha: text(sync.source_head_sha), active_snapshot_id: count(sync.active_snapshot_id), repo: text(sync.repo), }, current_running: { state: (text(running.state) || 'unknown') as CurrentRunningState, commit_sha: text(running.commit_sha), display_version: text(running.display_version), matched_commit_sha: text(running.matched_commit_sha), }, } } export async function syncVersionHistory(): Promise { const response = await fetch('/api/v1/version-history/sync', { method: 'POST', headers: { Accept: 'application/json' }, }) const value = (await response.json().catch(() => null)) as unknown if (!response.ok) { throw new Error(response.status === 403 ? '只有管理员能触发同步。' : `触发同步失败(HTTP ${response.status})`) } if (!record(value)) throw new Error('同步响应无效') return { job_id: text(value.job_id), status: text(value.status), reused: bool(value.reused) } } export async function fetchBuildInfo(signal?: AbortSignal): Promise { const response = await fetch('/api/v1/build-info', { headers: { Accept: 'application/json' }, signal }) if (!response.ok) throw new Error(`读取当前运行版本失败(HTTP ${response.status})`) const value = (await response.json()) as unknown if (!record(value)) throw new Error('构建身份响应无效') return { release_version: text(value.release_version), build_kind: text(value.build_kind), commit_sha: typeof value.commit_sha === 'string' ? value.commit_sha : null, display_version: text(value.display_version), built_at: text(value.built_at), identity_available: bool(value.identity_available), } }