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)。
258 lines
10 KiB
Go
258 lines
10 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"net/http"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
|
|
"knowledge-governance/internal/governance"
|
|
"knowledge-governance/internal/jobs"
|
|
postgresstore "knowledge-governance/internal/platform/postgres"
|
|
"knowledge-governance/internal/version"
|
|
"knowledge-governance/internal/versionhistory"
|
|
)
|
|
|
|
// 「版本记录」页的服务面:**只读查询** + 管理员手动同步。
|
|
//
|
|
// 设计口径(见 docs/RELEASE_RUNBOOK.md 与 internal/governance/version_history.go):
|
|
// - 列表只读本库缓存(Gitea 不可达也能看),游标绑定快照 ⇒ 翻页不重不漏;
|
|
// - 同步只有一个入口,且只允许管理员触发;并发同步合并成同一个作业;
|
|
// - 「当前运行」只认构建产物注入的**完整 SHA 精确匹配**,拿不到就显示未知。
|
|
|
|
// 版本记录的作业类型(worker 侧注册同名 handler;值来自 versionhistory,避免两处写死)。
|
|
const VersionHistoryJobType = versionhistory.JobType
|
|
|
|
const (
|
|
versionHistoryDefaultPageSize = 30
|
|
versionHistoryMaxPageSize = 100
|
|
)
|
|
|
|
// VersionHistoryStore 是版本记录页需要的只读查询面(由 postgres.Store 实现)。
|
|
type VersionHistoryStore interface {
|
|
ActiveVersionHistorySnapshot(ctx context.Context, repoKey string) (int64, error)
|
|
LoadVersionHistoryPage(ctx context.Context, repoKey, kind, cursor string, limit int) (
|
|
[]governance.VersionHistoryCommit, string, bool, int64, error)
|
|
LoadVersionHistorySyncState(ctx context.Context, repoKey string) (governance.VersionHistorySyncRun, error)
|
|
VersionHistorySyncInFlight(ctx context.Context, repoKey string, now time.Time) (bool, error)
|
|
}
|
|
|
|
type versionHistoryTag struct {
|
|
Name string `json:"name"`
|
|
URL string `json:"url"`
|
|
}
|
|
|
|
type versionHistoryItem struct {
|
|
CommitSHA string `json:"commit_sha"`
|
|
ShortSHA string `json:"short_sha"`
|
|
Parents []string `json:"parents"`
|
|
CommittedAt string `json:"committed_at"`
|
|
AuthorDisplay string `json:"author_display"`
|
|
Subject string `json:"subject"`
|
|
Body string `json:"body"`
|
|
RecordKind string `json:"record_kind"`
|
|
VersionLabel string `json:"version_label"`
|
|
VersionState string `json:"version_state"`
|
|
ReleaseTags []versionHistoryTag `json:"release_tags"`
|
|
ReleaseNotes string `json:"release_notes"`
|
|
CommitURL string `json:"commit_url"`
|
|
VersionReason string `json:"version_reason"`
|
|
CurrentRunning bool `json:"is_current_running"`
|
|
}
|
|
|
|
type versionHistorySyncState struct {
|
|
Available bool `json:"available"`
|
|
Status string `json:"status"`
|
|
Complete bool `json:"complete"`
|
|
LastSuccessAt string `json:"last_success_at"`
|
|
FetchedCount int `json:"fetched_count"`
|
|
ExpectedCount *int `json:"expected_count"`
|
|
ErrorCode string `json:"error_code"`
|
|
SourceHeadSHA string `json:"source_head_sha"`
|
|
ActiveSnapshotID int64 `json:"active_snapshot_id"`
|
|
Repo string `json:"repo"`
|
|
}
|
|
|
|
type versionHistoryCurrentRunning struct {
|
|
State string `json:"state"`
|
|
CommitSHA string `json:"commit_sha"`
|
|
DisplayVersion string `json:"display_version"`
|
|
MatchedCommitSHA string `json:"matched_commit_sha"`
|
|
}
|
|
|
|
type versionHistoryResponse struct {
|
|
Items []versionHistoryItem `json:"items"`
|
|
NextCursor string `json:"next_cursor"`
|
|
HasMore bool `json:"has_more"`
|
|
Sync versionHistorySyncState `json:"sync"`
|
|
CurrentRunning versionHistoryCurrentRunning `json:"current_running"`
|
|
}
|
|
|
|
func versionHistoryError(w http.ResponseWriter, status int, code, message string) {
|
|
writeJSON(w, status, map[string]string{"error": message, "code": code})
|
|
}
|
|
|
|
// currentRunning 判定「当前运行」:只在完整 SHA 精确命中时标记,否则明确说未知。
|
|
func currentRunning(items []governance.VersionHistoryCommit) (versionHistoryCurrentRunning, string) {
|
|
info := version.Snapshot()
|
|
if !info.IdentityAvailable || info.CommitSHA == nil {
|
|
return versionHistoryCurrentRunning{State: "unknown",
|
|
DisplayVersion: info.DisplayVersion}, ""
|
|
}
|
|
sha := *info.CommitSHA
|
|
for _, item := range items {
|
|
if item.CommitSHA == sha {
|
|
return versionHistoryCurrentRunning{State: "matched", CommitSHA: sha,
|
|
DisplayVersion: info.DisplayVersion, MatchedCommitSHA: sha}, sha
|
|
}
|
|
}
|
|
state := "unknown"
|
|
if info.BuildKind == "development" {
|
|
state = "development"
|
|
}
|
|
// 开发构建:产物带完整 SHA,但它不在已同步的提交里 ⇒ 说明"当前运行"与页面记录不重合
|
|
return versionHistoryCurrentRunning{State: state, CommitSHA: sha,
|
|
DisplayVersion: info.DisplayVersion}, ""
|
|
}
|
|
|
|
func versionHistoryList(w http.ResponseWriter, r *http.Request, config Config) {
|
|
if config.VersionHistory == nil || config.VersionHistoryRepo == "" {
|
|
writeJSON(w, http.StatusOK, versionHistoryResponse{Items: []versionHistoryItem{},
|
|
Sync: versionHistorySyncState{Available: false},
|
|
CurrentRunning: func() versionHistoryCurrentRunning {
|
|
running, _ := currentRunning(nil)
|
|
return running
|
|
}()})
|
|
return
|
|
}
|
|
kind := strings.TrimSpace(r.URL.Query().Get("kind"))
|
|
if kind == "" {
|
|
kind = "all"
|
|
}
|
|
limit := versionHistoryDefaultPageSize
|
|
if raw := strings.TrimSpace(r.URL.Query().Get("limit")); raw != "" {
|
|
parsed, err := strconv.Atoi(raw)
|
|
if err != nil || parsed <= 0 || parsed > versionHistoryMaxPageSize {
|
|
versionHistoryError(w, http.StatusBadRequest, "invalid_limit",
|
|
fmt.Sprintf("limit 必须是 1..%d 的整数", versionHistoryMaxPageSize))
|
|
return
|
|
}
|
|
limit = parsed
|
|
}
|
|
cursor := strings.TrimSpace(r.URL.Query().Get("cursor"))
|
|
|
|
items, nextCursor, hasMore, _, err := config.VersionHistory.LoadVersionHistoryPage(
|
|
r.Context(), config.VersionHistoryRepo, kind, cursor, limit)
|
|
if err != nil {
|
|
if errors.Is(err, postgresstore.ErrVersionHistoryCursorExpired) {
|
|
versionHistoryError(w, http.StatusConflict, "cursor_expired",
|
|
"这次翻页依据的记录快照已被清理,请刷新页面重新加载")
|
|
return
|
|
}
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "读取版本记录失败")
|
|
return
|
|
}
|
|
if items == nil {
|
|
items = []governance.VersionHistoryCommit{}
|
|
}
|
|
state, err := config.VersionHistory.LoadVersionHistorySyncState(r.Context(), config.VersionHistoryRepo)
|
|
if err != nil {
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "读取同步状态失败")
|
|
return
|
|
}
|
|
running, matchedSHA := currentRunning(items)
|
|
payload := versionHistoryResponse{
|
|
Items: make([]versionHistoryItem, 0, len(items)),
|
|
NextCursor: nextCursor, HasMore: hasMore, CurrentRunning: running,
|
|
Sync: versionHistorySyncState{Available: true, Status: state.Status, Complete: state.Complete,
|
|
LastSuccessAt: versionHistoryTime(state.LastSuccessAt), FetchedCount: state.FetchedCount,
|
|
ExpectedCount: state.ExpectedCount, ErrorCode: state.ErrorCode,
|
|
SourceHeadSHA: state.SourceHeadSHA, ActiveSnapshotID: state.ActiveSnapshotID,
|
|
Repo: config.VersionHistoryRepo},
|
|
}
|
|
for _, item := range items {
|
|
record := versionHistoryItem{
|
|
CommitSHA: item.CommitSHA, ShortSHA: shortSHA(item.CommitSHA), Parents: item.Parents,
|
|
CommittedAt: versionHistoryTime(item.CommittedAt), AuthorDisplay: item.AuthorDisplay,
|
|
Subject: item.Subject, Body: item.Body, RecordKind: item.RecordKind,
|
|
VersionLabel: item.VersionLabel, VersionState: item.VersionState,
|
|
ReleaseNotes: item.ReleaseNotes, CommitURL: item.CommitURL,
|
|
VersionReason: item.VersionEvidence.Reason,
|
|
ReleaseTags: make([]versionHistoryTag, 0, len(item.ReleaseTags)),
|
|
CurrentRunning: matchedSHA != "" && item.CommitSHA == matchedSHA,
|
|
}
|
|
for _, tag := range item.ReleaseTags {
|
|
record.ReleaseTags = append(record.ReleaseTags, versionHistoryTag{Name: tag.Name, URL: tag.URL})
|
|
}
|
|
payload.Items = append(payload.Items, record)
|
|
}
|
|
writeJSON(w, http.StatusOK, payload)
|
|
}
|
|
|
|
func versionHistorySync(w http.ResponseWriter, r *http.Request, config Config) {
|
|
if config.VersionHistory == nil || config.VersionHistoryRepo == "" {
|
|
versionHistoryError(w, http.StatusServiceUnavailable, "version_history_unavailable",
|
|
"版本记录未接线:没有配置只读的仓库来源")
|
|
return
|
|
}
|
|
now := config.Now().UTC()
|
|
inFlight, err := config.VersionHistory.VersionHistorySyncInFlight(r.Context(), config.VersionHistoryRepo, now)
|
|
if err != nil {
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "查询同步状态失败")
|
|
return
|
|
}
|
|
if inFlight {
|
|
state, err := config.VersionHistory.LoadVersionHistorySyncState(r.Context(), config.VersionHistoryRepo)
|
|
if err != nil {
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "查询同步状态失败")
|
|
return
|
|
}
|
|
// 已经在跑:不重复入队,明确告诉调用方复用现有任务
|
|
writeJSON(w, http.StatusOK, map[string]any{"job_id": state.JobID, "sync_run_id": state.ID,
|
|
"status": state.Status, "reused": true})
|
|
return
|
|
}
|
|
triggeredBy := ""
|
|
if identity, ok := sessionFrom(r.Context()); ok {
|
|
triggeredBy = identity.Username
|
|
}
|
|
payload, err := json.Marshal(map[string]string{"repo_key": config.VersionHistoryRepo, "triggered_by": triggeredBy})
|
|
if err != nil {
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "构造同步任务失败")
|
|
return
|
|
}
|
|
requestedID := fmt.Sprintf("version-history-sync-%d", now.UnixNano())
|
|
job, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{ID: requestedID,
|
|
Type: VersionHistoryJobType, Payload: payload, AvailableAt: now, MaxAttempts: 3,
|
|
IdempotencyKey: "version-history.sync:" + config.VersionHistoryRepo}, now)
|
|
if err != nil || job == nil {
|
|
versionHistoryError(w, http.StatusInternalServerError, "version_history_unavailable", "入队同步任务失败")
|
|
return
|
|
}
|
|
writeJSON(w, http.StatusAccepted, map[string]any{"job_id": job.ID, "status": job.State,
|
|
"reused": job.ID != requestedID})
|
|
}
|
|
|
|
// buildInfo:当前运行产物的构建身份(只读;与监控接口同级可见)。
|
|
func buildInfo(w http.ResponseWriter, _ *http.Request) {
|
|
writeJSON(w, http.StatusOK, version.Snapshot())
|
|
}
|
|
|
|
func versionHistoryTime(value time.Time) string {
|
|
if value.IsZero() {
|
|
return ""
|
|
}
|
|
return value.UTC().Format(time.RFC3339)
|
|
}
|
|
|
|
func shortSHA(sha string) string {
|
|
if len(sha) > 12 {
|
|
return sha[:12]
|
|
}
|
|
return sha
|
|
}
|