4d43a9386a
build / build (push) Successful in 1m5s
真实数据发现(本机 p1 实例第一次同步后核对):
- **缺陷**:tag `v0.1.0` 之前的 20 个提交,提交内 CHANGELOG 顶部**也已经**是 0.1.0(旧分支遗留条目),
而它们的祖先集合被那个**更晚才打**的 tag 全覆盖 ⇒ 按提交数算得 0 ⇒ 被错标成「0.1.0 开发版」。
它们的正确判定是「历史提交」:那个 tag 是后来才打的,当时还没有发布基线。
- **修复**:基线 tag 必须是该提交的**祖先(或就是该提交)**,否则不给号;新增原因码
`release_tag_created_later`(页面文案:'该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag')。
回归用例两条:`TestDeriveVersionsDoesNotNumberCommitsThatPredateTheTag`、
`TestDeriveVersionsSideBranchWithoutTagStaysHistorical`(不含 tag 的侧分支同样不给号)。
- **部署脚本注入构建身份**:`scripts/deploy-api-web.sh` 原先不传 `-ldflags -X`,产物 `CommitSHA=unknown`
⇒ 页面只能显示"当前运行版本未知"(契约上诚实,但没用)。现在按 `scripts/version.py --identity`
(唯一来源,与 Makefile/CI 同规则)注入 VERSION/RELEASE_VERSION/BUILD_KIND/COMMITS_SINCE_RELEASE/
COMMIT_SHA/BUILD_TIME;取不到身份**拒绝继续**(宁可不上线,也不上线一个认不出自己的产物),
并在收尾核对注入的 SHA 真的进了产物。
- compose.yaml:把 VERSION_HISTORY_* 五项接进应用环境(api/worker 共享锚点),留空即未接线。
验证:真实仓库复验(114 条对账一致)⇒ 正式 1 / 开发 4 / 历史 109(原来错的 19 条现在都是
`release_tag_created_later`);p1 实例重新同步后当前快照分布一致,带号的记录只剩 1 正式 + 4 开发
(含真实存在的「同号不同 SHA」:950c1b4 与 3a1d32d 都是 0.1.1,各占一行);
make verify 15/15 success;前端 18 用例 + typecheck 通过。
196 lines
7.4 KiB
TypeScript
196 lines
7.4 KiB
TypeScript
// 「版本记录」页的客户端:只读查询 + 管理员手动同步。
|
||
// 页面读的是本库缓存(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('这次翻页依据的记录快照已被清理,请刷新页面重新加载。')
|
||
}
|
||
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<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),
|
||
}
|
||
}
|