0974d8dfa2
build / build (push) Successful in 57s
按已确认的契约实现(口径见 docs/VERSION_HISTORY.md):
- **版本号口径(只给有证据的)**:注释 tag + tag 指向该提交 + 该提交内 CHANGELOG 顶部三者一致 ⇒ 正式版本;
tag 之后的提交按 `<主>.<次>.<自该 tag 的提交数>` 显示开发号(与 scripts/version.py **同规则**);
证据不足 ⇒ 「历史提交 · 短SHA」+ 原因码,**不补造版本号**。完整 SHA 是唯一身份、版本号不是唯一键
(tag 之后两条并行分支各自的第 1 个提交都算 0.1.1 ⇒ 两条都保留,用短 SHA 区分)。
- **迁移 000046**:version_history_commits(提交记录,主键 repo_key+commit_sha)+ version_history_sync_runs
(同步状态)。快照 = 一次同步:抓完并与 X-Total-Count 对账通过才切换;失败不切换快照、不清空历史、
last_success_at 不动(页面显示"上次同步失败(原因)· 仍展示上次成功数据");「同步成功」≠「历史完整」。
- **只读客户端(匿名,不使用任何凭据)**:白名单 origin + 固定仓库、拒绝任意 URL 与跨主机重定向、
响应上限 5MB / 超时 15s、仅 5xx/429 退避重试(最多 3 次);逐页抓到短页为止;每次全量扫 tag
⇒ 旧提交后补的 tag 会更新既有记录(不新增第二行)。
- **接口**(三个都登记进 api/openapi.yaml):GET /api/v1/build-info(viewer)、
GET /api/v1/version-history(viewer;游标绑定快照,过期返回 409 cursor_expired;不返回伪造 total)、
POST /api/v1/version-history/sync(admin;并发同步复用同一作业,靠 IdempotencyKey)。
- **「当前运行」只认精确匹配**:产物注入的完整 SHA 命中某条记录才标该条;开发构建显式标注"开发构建";
没有可用标识 ⇒ "当前运行版本未知";**不拿最新 main / 最新 tag 顶替**,CI 成功不等于已部署。
- **前端**:一级菜单第 5 项(版本记录)+ 时间线页面(全部/正式/开发/历史四段筛选、正文展开、
加载更多、760px 单列无横向溢出、提交正文与变更记录按纯文本渲染);无打 tag / 发布 / 部署入口。
新增配置(留空即未接线,页面降级):VERSION_HISTORY_GITEA_BASE_URL / _REPO / _ALLOWED_ORIGINS /
_HTTP_TIMEOUT / _MAX_PAGES。
验证:`make verify` 15/15 success(tests-go 578 通过 / 0 失败;tests-web 209 通过 / 0 失败);
新增 Go 用例 30(版本口径与图遍历 12、客户端守卫 6、同步编排 5、接口 7);前端新增 18(组件 10 + 客户端 8);
真实仓库匿名快照拉取(`VERSION_HISTORY_LIVE_BASE_URL=… go test -run TestLiveSyncAgainstRealRepository`):
抓到 113 条与 X-Total-Count 一致、v0.1.0 是注释 tag 且目标与 `git rev-parse v0.1.0^{commit}` 一致、
开发号逐个等于 `git rev-list --count v0.1.0..<sha>`(正式 1 / 开发 22 / 历史 90)。
141 lines
4.8 KiB
TypeScript
141 lines
4.8 KiB
TypeScript
import { afterEach, describe, expect, it, vi } from 'vitest'
|
|
import { fetchBuildInfo, fetchVersionHistory, reasonLabel, syncVersionHistory } from './versionHistory'
|
|
|
|
const jsonResponse = (body: unknown, status = 200) =>
|
|
Promise.resolve({ ok: status >= 200 && status < 300, status, json: () => Promise.resolve(body) } as Response)
|
|
|
|
afterEach(() => vi.unstubAllGlobals())
|
|
|
|
const pageBody = {
|
|
items: [
|
|
{
|
|
commit_sha: 'a'.repeat(40),
|
|
short_sha: 'aaaaaaaaaaaa',
|
|
parents: [],
|
|
committed_at: '2026-10-13T10:00:00Z',
|
|
author_display: '姚章浩',
|
|
subject: 'feat: 甲',
|
|
body: '正文',
|
|
record_kind: 'development',
|
|
version_label: '0.1.2',
|
|
version_state: 'verified',
|
|
release_tags: [],
|
|
release_notes: '',
|
|
commit_url: 'https://gitea.example/commit/aaa',
|
|
version_reason: 'counted_commits_since_base_tag',
|
|
is_current_running: false,
|
|
},
|
|
],
|
|
next_cursor: 'next-cursor',
|
|
has_more: true,
|
|
sync: {
|
|
available: true,
|
|
status: 'completed',
|
|
complete: true,
|
|
last_success_at: '2026-10-13T12:00:00Z',
|
|
fetched_count: 111,
|
|
expected_count: 111,
|
|
error_code: '',
|
|
source_head_sha: 'a'.repeat(40),
|
|
active_snapshot_id: 3,
|
|
repo: 'Weknora/knowledge-governance',
|
|
},
|
|
current_running: {
|
|
state: 'development',
|
|
commit_sha: 'b'.repeat(40),
|
|
display_version: '0.1.2',
|
|
matched_commit_sha: '',
|
|
},
|
|
}
|
|
|
|
describe('versionHistory client', () => {
|
|
it('loads a page, keeps the cursor and reads sync/current-running facts', async () => {
|
|
const fetchMock = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) => jsonResponse(pageBody))
|
|
vi.stubGlobal('fetch', fetchMock)
|
|
const page = await fetchVersionHistory({ kind: 'all', cursor: '' })
|
|
expect(fetchMock).toHaveBeenCalledOnce()
|
|
const url = String(fetchMock.mock.calls[0][0])
|
|
expect(url).toContain('/api/v1/version-history?')
|
|
expect(url).not.toContain('kind=all')
|
|
expect(url).toContain('limit=30')
|
|
expect(page.items[0].version_label).toBe('0.1.2')
|
|
expect(page.next_cursor).toBe('next-cursor')
|
|
expect(page.has_more).toBe(true)
|
|
expect(page.sync.expected_count).toBe(111)
|
|
expect(page.current_running.state).toBe('development')
|
|
})
|
|
|
|
it('passes the kind filter and cursor through', async () => {
|
|
const fetchMock = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) =>
|
|
jsonResponse({ ...pageBody, items: [], has_more: false })
|
|
)
|
|
vi.stubGlobal('fetch', fetchMock)
|
|
await fetchVersionHistory({ kind: 'historical', cursor: 'c-1', limit: 50 })
|
|
const url = String(fetchMock.mock.calls[0][0])
|
|
expect(url).toContain('kind=historical')
|
|
expect(url).toContain('cursor=c-1')
|
|
expect(url).toContain('limit=50')
|
|
})
|
|
|
|
it('explains an expired cursor instead of showing a raw error', async () => {
|
|
vi.stubGlobal(
|
|
'fetch',
|
|
vi.fn(() => jsonResponse({ code: 'cursor_expired' }, 409))
|
|
)
|
|
await expect(fetchVersionHistory({ kind: 'all', cursor: 'stale' })).rejects.toThrow('已被清理')
|
|
})
|
|
|
|
it('rejects malformed payloads instead of rendering half-truths', async () => {
|
|
vi.stubGlobal(
|
|
'fetch',
|
|
vi.fn(() => jsonResponse({ items: 'nope' }))
|
|
)
|
|
await expect(fetchVersionHistory({ kind: 'all', cursor: '' })).rejects.toThrow('响应无效')
|
|
})
|
|
|
|
it('posts the sync request and reports reuse', async () => {
|
|
const fetchMock = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) =>
|
|
jsonResponse({ job_id: 'job-1', status: 'running', reused: true })
|
|
)
|
|
vi.stubGlobal('fetch', fetchMock)
|
|
const accepted = await syncVersionHistory()
|
|
expect(String(fetchMock.mock.calls[0][0])).toBe('/api/v1/version-history/sync')
|
|
expect(fetchMock.mock.calls[0][1]).toMatchObject({ method: 'POST' })
|
|
expect(accepted.reused).toBe(true)
|
|
})
|
|
|
|
it('says admin-only when the sync is refused', async () => {
|
|
vi.stubGlobal(
|
|
'fetch',
|
|
vi.fn(() => jsonResponse({ code: 'forbidden_role' }, 403))
|
|
)
|
|
await expect(syncVersionHistory()).rejects.toThrow('只有管理员')
|
|
})
|
|
|
|
it('never fabricates a build identity when injection is missing', async () => {
|
|
vi.stubGlobal(
|
|
'fetch',
|
|
vi.fn(() =>
|
|
jsonResponse({
|
|
release_version: '',
|
|
build_kind: 'development',
|
|
commit_sha: null,
|
|
display_version: 'dev',
|
|
built_at: '',
|
|
identity_available: false,
|
|
})
|
|
)
|
|
)
|
|
const info = await fetchBuildInfo()
|
|
expect(info.commit_sha).toBeNull()
|
|
expect(info.identity_available).toBe(false)
|
|
})
|
|
|
|
it('maps every evidence reason to a human explanation', () => {
|
|
expect(reasonLabel('lightweight_tag')).toContain('轻量 tag')
|
|
expect(reasonLabel('no_baseline')).toContain('发布基线')
|
|
expect(reasonLabel('shallow_or_incomplete_graph')).toContain('提交图不完整')
|
|
expect(reasonLabel('something_new')).toBe('版本号未能核验')
|
|
})
|
|
})
|