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)。
169 lines
5.4 KiB
Go
169 lines
5.4 KiB
Go
package versionhistory
|
||
|
||
import (
|
||
"context"
|
||
"os"
|
||
"os/exec"
|
||
"strings"
|
||
"testing"
|
||
"time"
|
||
)
|
||
|
||
// 真实仓库的只读同步用例:**匿名抓取**内部可达的 Gitea,并把算出的版本号与本地 git 交叉核对
|
||
// (`git rev-list --count v0.1.0..<sha>`)—— 两套实现(Go 图遍历 vs git)必须给出同一个号。
|
||
//
|
||
// 未设 VERSION_HISTORY_LIVE_BASE_URL 即按设计 SKIP(已在 scripts/test-scope.json 声明理由);
|
||
// 本用例**不读任何凭据**、只读远端仓库,不写任何东西。
|
||
func TestLiveSyncAgainstRealRepository(t *testing.T) {
|
||
base := strings.TrimSpace(os.Getenv("VERSION_HISTORY_LIVE_BASE_URL"))
|
||
if base == "" {
|
||
t.Skip("VERSION_HISTORY_LIVE_BASE_URL 未设置:跳过真实仓库的只读同步用例")
|
||
}
|
||
if _, err := exec.LookPath("git"); err != nil {
|
||
t.Skip("本地没有 git:无法与 git 交叉核对")
|
||
}
|
||
repo := strings.TrimSpace(os.Getenv("VERSION_HISTORY_LIVE_REPO"))
|
||
if repo == "" {
|
||
repo = "Weknora/knowledge-governance"
|
||
}
|
||
client, err := NewGiteaClient(GiteaConfig{BaseURL: base, AllowedBaseURLs: []string{base}, Repo: repo})
|
||
if err != nil {
|
||
t.Fatalf("构造只读客户端:%v", err)
|
||
}
|
||
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
|
||
defer cancel()
|
||
|
||
commits, total := []RawCommit{}, 0
|
||
for page := 1; page <= 10; page++ {
|
||
pageCommits, pageTotal, err := client.ListCommits(ctx, page, 50)
|
||
if err != nil {
|
||
t.Fatalf("第 %d 页抓取失败:%v", page, err)
|
||
}
|
||
if pageTotal > 0 {
|
||
total = pageTotal
|
||
}
|
||
commits = append(commits, pageCommits...)
|
||
if len(pageCommits) < 50 {
|
||
break
|
||
}
|
||
}
|
||
seen := map[string]bool{}
|
||
for _, commit := range commits {
|
||
if seen[commit.SHA] {
|
||
t.Fatalf("分页出现重复提交 %s", commit.SHA)
|
||
}
|
||
seen[commit.SHA] = true
|
||
}
|
||
if total == 0 || len(commits) != total {
|
||
t.Fatalf("分页与 X-Total-Count 不一致:抓到 %d,远端宣称 %d", len(commits), total)
|
||
}
|
||
tags, err := client.ListTags(ctx)
|
||
if err != nil {
|
||
t.Fatalf("读 tag:%v", err)
|
||
}
|
||
|
||
// 与本地 git 交叉核对:注释 tag 指向的提交必须与 `git rev-parse` 一致
|
||
var releaseTag RawTag
|
||
foundRelease := false
|
||
for _, tag := range tags {
|
||
if tag.Name == "v0.1.0" {
|
||
releaseTag, foundRelease = tag, true
|
||
}
|
||
}
|
||
if !foundRelease || !releaseTag.Annotated {
|
||
t.Fatalf("真实仓库里应有注释 tag v0.1.0,实际:%+v", tags)
|
||
}
|
||
if local := localGit(t, "rev-parse", "v0.1.0^{commit}"); local != releaseTag.TargetSHA {
|
||
t.Fatalf("tag 目标与本地 git 不一致:接口 %s,本地 %s", releaseTag.TargetSHA, local)
|
||
}
|
||
|
||
derived := DeriveVersions(DeriveInput{RepoKey: repo, CommitURLBase: client.CommitURLBase(),
|
||
Commits: commits, Tags: tags,
|
||
Changelog: func(sha string) (string, error) { return client.ReadFile(ctx, sha, "CHANGELOG.md") }})
|
||
if !derived.GraphComplete {
|
||
t.Fatalf("真实仓库的提交图应当完整,缺父提交 %v", derived.MissingParents)
|
||
}
|
||
|
||
releases, development, historical := 0, 0, 0
|
||
for _, record := range derived.Records {
|
||
switch record.RecordKind {
|
||
case "release":
|
||
releases++
|
||
if record.CommitSHA == releaseTag.TargetSHA {
|
||
if record.VersionLabel != "0.1.0" || record.ReleaseNotes == "" {
|
||
t.Fatalf("正式版本记录不完整:%+v", record)
|
||
}
|
||
}
|
||
case "development":
|
||
development++
|
||
case "historical":
|
||
historical++
|
||
if record.VersionLabel != "" {
|
||
t.Fatalf("历史提交不许有版本号:%+v", record)
|
||
}
|
||
}
|
||
}
|
||
if releases != 1 {
|
||
t.Fatalf("正式版本条数 = %d,期望 1(只有 v0.1.0)", releases)
|
||
}
|
||
|
||
// 交叉核对开发号:Go 的图遍历 vs 本地 git 的 rev-list --count
|
||
checked := 0
|
||
for _, record := range derived.Records {
|
||
if record.RecordKind != "development" || checked >= 8 {
|
||
continue
|
||
}
|
||
if _, err := exec.Command("git", "cat-file", "-e", record.CommitSHA).Output(); err != nil {
|
||
continue // 本地没有这个提交(远端有新提交)⇒ 跳过交叉核对
|
||
}
|
||
count := localGit(t, "rev-list", "--count", "v0.1.0.."+record.CommitSHA)
|
||
want := "0.1." + count
|
||
if record.VersionLabel != want {
|
||
t.Fatalf("提交 %s 的号 = %q,git 算出来是 %q", record.CommitSHA[:12], record.VersionLabel, want)
|
||
}
|
||
checked++
|
||
}
|
||
if checked == 0 {
|
||
t.Fatal("没有交叉核对任何开发号 —— 证据不足")
|
||
}
|
||
|
||
head := derived.Records[0]
|
||
t.Logf("真实仓库 %s:远端 main 可达 %d 条提交(对账一致)|正式 %d|开发 %d|历史 %d|tag %d 个(注释 %v 个)",
|
||
repo, len(commits), releases, development, historical, len(tags), countAnnotated(tags))
|
||
for index, record := range derived.Records {
|
||
if index >= 6 {
|
||
break
|
||
}
|
||
label := record.VersionLabel
|
||
if label == "" {
|
||
label = "历史提交 · " + record.CommitSHA[:12]
|
||
}
|
||
t.Logf(" %s|%s|%s|%s", label, record.CommitSHA[:12], record.RecordKind, record.Subject)
|
||
}
|
||
if head.VersionLabel == "" && head.RecordKind != "historical" {
|
||
t.Fatalf("HEAD 记录异常:%+v", head)
|
||
}
|
||
if want := "0.1." + localGit(t, "rev-list", "--count", "v0.1.0.."+head.CommitSHA); head.VersionLabel != want {
|
||
t.Fatalf("HEAD 的号 = %q,git 算出来是 %q", head.VersionLabel, want)
|
||
}
|
||
}
|
||
|
||
func countAnnotated(tags []RawTag) int {
|
||
annotated := 0
|
||
for _, tag := range tags {
|
||
if tag.Annotated {
|
||
annotated++
|
||
}
|
||
}
|
||
return annotated
|
||
}
|
||
|
||
func localGit(t *testing.T, args ...string) string {
|
||
t.Helper()
|
||
output, err := exec.Command("git", args...).Output()
|
||
if err != nil {
|
||
t.Fatalf("本地 git %s 失败:%v", strings.Join(args, " "), err)
|
||
}
|
||
return strings.TrimSpace(string(output))
|
||
}
|