Files
knowledge-governance/web/src/versionHistory.ts
T
姚章浩 30686dd288
build / build (push) Successful in 1m21s
fix(ui): 版本记录错误详情复用已解析响应体,不再二次读 Body
父复核发现的确定缺陷:fetchVersionHistory 在 130 行已 await response.json(),
错误分支又读一次,真实 Response 抛 TypeError(Body already read),被 catch 吞掉,
用户仍只看到状态码。

改为复用已解析的 value(error/code);同时把 code 从错误分支里重复声明去掉。
测试用真实 Response 构造 500:伪 mock 可重复 json() 会把 double-read 掩盖成绿。
2026-11-01 19:59:28 +08:00

200 lines
7.8 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.
// 「版本记录」页的客户端:只读查询 + 管理员手动同步。
// 页面读的是本库缓存(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<string, unknown> => 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<string, string> = {
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<VersionHistoryPage> {
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('这次翻页依据的记录快照已被清理,请刷新页面重新加载。')
}
// 正文在上面已经解析进 value 了;再调一次 response.json() 会抛 TypeError
// (Body already read),被吞掉后用户只能看到状态码。直接复用 value。
const message = record(value) ? text(value.error) : ''
const detail = message || code ? `:${message || '无错误描述'}${code ? `(${code})` : ''}` : ''
throw new Error(`加载版本记录失败(HTTP ${response.status})${detail}`)
}
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<SyncAccepted> {
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<BuildInfo> {
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),
}
}