Files
knowledge-governance/internal/platform/postgres/version_history.go
T
姚章浩 e34306b2db
build / build (push) Failing after 18s
fix(ui): 已释放窗口不再渲染 held 文案,版本页不再把 500 说成未接线
发布管理:maintenanceSummary 只看 job.state === 'failed' 就给 held 处置文案;
窗口已 released 的旧作业(libsync-internal-1793399248431728863)因此自相矛盾。
改为仅 held 时给 recoveryError,已释放时给 releasedFailure(如实记录失败,不提供强制成功)。

版本记录:LoadVersionHistorySyncState 把可空的 finished_at 扫进 time.Time;
部署重启触发的同步在"进行中"时该列为 NULL,扫描失败使整页 500
(nginx access log:GET /api/v1/version-history?limit=30 → 500,74 字节错误体)。
改为指针接值再判空。前端同时区分"未配置/加载失败"并显示服务端 code。

RED/GREEN:新增 Go 集成用例(NULL finished_at)、两条前端用例;
make verify 16/16 通过(local 档案)。
2026-11-01 19:34:31 +08:00

322 lines
13 KiB
Go
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.
package postgres
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
"github.com/jackc/pgx/v5"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/versionhistory"
)
// 「版本记录」的持久化:提交记录 + 同步状态(migration 000046)。
//
// 事实口径(与 internal/governance、internal/versionhistory 一致):
// - commit_sha 是唯一身份;同一提交再次同步只更新自己那一行(后补 tag 靠这条生效);
// - 对外只服务**最近一次成功**的快照(snapshot_id = sync_runs.id);
// - 失败不切换快照、不清空历史。
const (
// VersionHistoryKeptSnapshots:保留最近几个成功快照供游标使用,更旧的清理。
VersionHistoryKeptSnapshots = 3
// VersionHistoryInFlightWindow:超过这个时长的 running 视为"陈旧"(进程被杀留下的),
// 不再挡住新的同步请求。
VersionHistoryInFlightWindow = 30 * time.Minute
versionHistoryDefaultLimit = 30
versionHistoryMaxLimit = 100
)
// ErrVersionHistoryCursorExpired:游标指向的快照已被清理 ⇒ 调用方返回 409 让页面刷新。
var ErrVersionHistoryCursorExpired = errors.New("version history cursor expired")
// BeginVersionHistorySync 开一次同步(status=running),返回 run id(同时就是快照 id)。
func (s *Store) BeginVersionHistorySync(ctx context.Context, repoKey, jobID, triggeredBy string, now time.Time) (int64, error) {
var id int64
err := s.db.QueryRow(ctx, `
INSERT INTO version_history_sync_runs (repo_key, job_id, status, started_at, triggered_by)
VALUES ($1, $2, 'running', $3, $4)
RETURNING id`, repoKey, jobID, now.UTC(), triggeredBy).Scan(&id)
if err != nil {
return 0, fmt.Errorf("开启版本记录同步:%w", err)
}
return id, nil
}
// VersionHistorySyncInFlight 是否有在跑的同步(陈旧 running 不算)。
func (s *Store) VersionHistorySyncInFlight(ctx context.Context, repoKey string, now time.Time) (bool, error) {
var exists bool
err := s.db.QueryRow(ctx, `
SELECT EXISTS (
SELECT 1 FROM version_history_sync_runs
WHERE repo_key = $1 AND status IN ('pending', 'running') AND started_at > $2)`,
repoKey, now.UTC().Add(-VersionHistoryInFlightWindow)).Scan(&exists)
if err != nil {
return false, fmt.Errorf("查询版本记录同步状态:%w", err)
}
return exists, nil
}
// SaveVersionHistorySnapshot 写入本次快照的全部提交记录(同一提交只更新自己那一行),
// 并清理过旧的快照(**不动本次快照**)。
func (s *Store) SaveVersionHistorySnapshot(ctx context.Context, snapshotID int64, repoKey string,
records []governance.VersionHistoryCommit, expectedCount int, complete bool, now time.Time) error {
// expectedCount/complete 由 FinishVersionHistorySync 落库(这里只写记录行)。
_, _ = expectedCount, complete
tx, err := s.db.Begin(ctx)
if err != nil {
return fmt.Errorf("写版本记录快照:%w", err)
}
defer func() { _ = tx.Rollback(ctx) }()
for _, record := range records {
parents := record.Parents
if parents == nil {
parents = []string{}
}
tags, err := json.Marshal(record.ReleaseTags)
if err != nil {
return fmt.Errorf("序列化 tag 证据:%w", err)
}
evidence, err := json.Marshal(record.VersionEvidence)
if err != nil {
return fmt.Errorf("序列化版本依据:%w", err)
}
var label *string
if record.VersionLabel != "" {
value := record.VersionLabel
label = &value
}
if _, err := tx.Exec(ctx, `
INSERT INTO version_history_commits (repo_key, commit_sha, parents, committed_at, author_display,
subject, body, version_label, version_state, record_kind, release_tags, release_notes,
commit_url, version_evidence, snapshot_id, updated_at)
VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16)
ON CONFLICT (repo_key, commit_sha) DO UPDATE SET
parents = EXCLUDED.parents, committed_at = EXCLUDED.committed_at,
author_display = EXCLUDED.author_display, subject = EXCLUDED.subject, body = EXCLUDED.body,
version_label = EXCLUDED.version_label, version_state = EXCLUDED.version_state,
record_kind = EXCLUDED.record_kind, release_tags = EXCLUDED.release_tags,
release_notes = EXCLUDED.release_notes, commit_url = EXCLUDED.commit_url,
version_evidence = EXCLUDED.version_evidence, snapshot_id = EXCLUDED.snapshot_id,
updated_at = EXCLUDED.updated_at`,
repoKey, record.CommitSHA, parents, record.CommittedAt.UTC(), record.AuthorDisplay,
record.Subject, record.Body, label, record.VersionState, record.RecordKind,
tags, record.ReleaseNotes, record.CommitURL, evidence, snapshotID, now.UTC()); err != nil {
return fmt.Errorf("写入版本记录 %s:%w", record.CommitSHA, err)
}
}
if _, err := tx.Exec(ctx, `
DELETE FROM version_history_commits
WHERE repo_key = $1 AND snapshot_id <> $2 AND snapshot_id NOT IN (
SELECT id FROM version_history_sync_runs
WHERE repo_key = $1 AND status = 'completed' ORDER BY id DESC LIMIT $3)`,
repoKey, snapshotID, VersionHistoryKeptSnapshots); err != nil {
return fmt.Errorf("清理过旧版本记录快照:%w", err)
}
if err := tx.Commit(ctx); err != nil {
return fmt.Errorf("提交版本记录快照:%w", err)
}
return nil
}
// FinishVersionHistorySync 标记同步成功(此时本次快照成为对外服务的事实)。
func (s *Store) FinishVersionHistorySync(ctx context.Context, runID int64, outcome versionhistory.SyncOutcome, now time.Time) error {
command, err := s.db.Exec(ctx, `
UPDATE version_history_sync_runs
SET status = 'completed', finished_at = $2, last_success_at = $2, complete = $3,
fetched_count = $4, expected_count = $5, source_head_sha = $6
WHERE id = $1`,
runID, now.UTC(), outcome.Complete, outcome.FetchedCount, outcome.ExpectedCount, outcome.SourceHeadSHA)
if err != nil {
return fmt.Errorf("完成版本记录同步:%w", err)
}
if command.RowsAffected() != 1 {
return fmt.Errorf("完成版本记录同步:run %d 不存在", runID)
}
return nil
}
// FailVersionHistorySync 标记同步失败并落错误码(**不切换对外快照**)。
func (s *Store) FailVersionHistorySync(ctx context.Context, runID int64, errorCode string, now time.Time) error {
_, err := s.db.Exec(ctx, `
UPDATE version_history_sync_runs
SET status = 'failed', finished_at = $2, error_code = $3
WHERE id = $1`, runID, now.UTC(), errorCode)
if err != nil {
return fmt.Errorf("标记版本记录同步失败:%w", err)
}
return nil
}
// ActiveVersionHistorySnapshot 返回对外快照(最近一次成功同步);没有 ⇒ 0。
func (s *Store) ActiveVersionHistorySnapshot(ctx context.Context, repoKey string) (int64, error) {
var id int64
err := s.db.QueryRow(ctx, `
SELECT id FROM version_history_sync_runs
WHERE repo_key = $1 AND status = 'completed' ORDER BY id DESC LIMIT 1`, repoKey).Scan(&id)
if errors.Is(err, pgx.ErrNoRows) {
return 0, nil
}
if err != nil {
return 0, fmt.Errorf("查询版本记录快照:%w", err)
}
return id, nil
}
// LoadVersionHistorySyncState 读同步状态:最新一次 run(任何终态)+ 最近一次成功时间。
func (s *Store) LoadVersionHistorySyncState(ctx context.Context, repoKey string) (governance.VersionHistorySyncRun, error) {
var run governance.VersionHistorySyncRun
var expected *int
// finished_at 在"进行中"的 run 上是 NULL(列可空)。用指针接再判空:
// 直接扫进 time.Time 会让整页 500,而部署重启本身就会触发一次同步。
var finishedAt *time.Time
err := s.db.QueryRow(ctx, `
SELECT id, job_id, status, source_head_sha, started_at, finished_at, complete,
fetched_count, expected_count, error_code, triggered_by
FROM version_history_sync_runs WHERE repo_key = $1 ORDER BY id DESC LIMIT 1`, repoKey).
Scan(&run.ID, &run.JobID, &run.Status, &run.SourceHeadSHA, &run.StartedAt, &finishedAt,
&run.Complete, &run.FetchedCount, &expected, &run.ErrorCode, &run.TriggeredBy)
if err != nil && !errors.Is(err, pgx.ErrNoRows) {
return governance.VersionHistorySyncRun{}, fmt.Errorf("查询同步状态:%w", err)
}
if errors.Is(err, pgx.ErrNoRows) {
return governance.VersionHistorySyncRun{}, nil
}
if finishedAt != nil {
run.FinishedAt = *finishedAt
}
run.ExpectedCount = expected
if snapshot, err := s.ActiveVersionHistorySnapshot(ctx, repoKey); err != nil {
return governance.VersionHistorySyncRun{}, err
} else {
run.ActiveSnapshotID = snapshot
}
var lastSuccess *time.Time
if err := s.db.QueryRow(ctx, `
SELECT last_success_at FROM version_history_sync_runs
WHERE repo_key = $1 AND status = 'completed' ORDER BY id DESC LIMIT 1`, repoKey).
Scan(&lastSuccess); err == nil && lastSuccess != nil {
run.LastSuccessAt = *lastSuccess
}
return run, nil
}
// VersionHistoryCursorBetween 偏移一页:绑定快照 + (committed_at, commit_sha) 组合游标。
func encodeVersionHistoryCursor(snapshotID int64, committedAt time.Time, sha string) string {
raw := fmt.Sprintf("%d|%s|%s", snapshotID, committedAt.UTC().Format(time.RFC3339Nano), sha)
return base64.RawURLEncoding.EncodeToString([]byte(raw))
}
func decodeVersionHistoryCursor(cursor string) (int64, time.Time, string, error) {
decoded, err := base64.RawURLEncoding.DecodeString(cursor)
if err != nil {
return 0, time.Time{}, "", fmt.Errorf("游标不是合法编码")
}
parts := strings.Split(string(decoded), "|")
if len(parts) != 3 {
return 0, time.Time{}, "", fmt.Errorf("游标结构不对")
}
var snapshotID int64
if _, err := fmt.Sscanf(parts[0], "%d", &snapshotID); err != nil || snapshotID <= 0 {
return 0, time.Time{}, "", fmt.Errorf("游标缺少快照")
}
committedAt, err := time.Parse(time.RFC3339Nano, parts[1])
if err != nil {
return 0, time.Time{}, "", fmt.Errorf("游标的提交时间不对")
}
if len(parts[2]) != 40 {
return 0, time.Time{}, "", fmt.Errorf("游标的提交标识不对")
}
return snapshotID, committedAt.UTC(), parts[2], nil
}
// LoadVersionHistoryPage 按游标读一页(只读当前快照;跨快照游标直接拒绝)。
func (s *Store) LoadVersionHistoryPage(ctx context.Context, repoKey, kind, cursor string, limit int) (
items []governance.VersionHistoryCommit, nextCursor string, hasMore bool, snapshotID int64, err error) {
if limit <= 0 {
limit = versionHistoryDefaultLimit
}
if limit > versionHistoryMaxLimit {
limit = versionHistoryMaxLimit
}
switch kind {
case "", "all", governance.RecordKindRelease, governance.RecordKindDevelopment, governance.RecordKindHistorical:
default:
return nil, "", false, 0, fmt.Errorf("未知的记录类型 %q", kind)
}
if kind == "" {
kind = "all"
}
active, err := s.ActiveVersionHistorySnapshot(ctx, repoKey)
if err != nil {
return nil, "", false, 0, err
}
var (
cursorAt *time.Time
cursorSHA *string
)
if cursor != "" {
cursorSnapshot, committedAt, sha, decodeErr := decodeVersionHistoryCursor(cursor)
if decodeErr != nil {
return nil, "", false, 0, fmt.Errorf("%w:%s", ErrVersionHistoryCursorExpired, decodeErr)
}
if cursorSnapshot != active {
return nil, "", false, active, ErrVersionHistoryCursorExpired
}
cursorAt, cursorSHA = &committedAt, &sha
}
if active == 0 {
return []governance.VersionHistoryCommit{}, "", false, 0, nil
}
rows, err := s.db.Query(ctx, `
SELECT commit_sha, parents, committed_at, author_display, subject, body, version_label,
version_state, record_kind, release_tags, release_notes, commit_url, version_evidence, snapshot_id
FROM version_history_commits
WHERE repo_key = $1 AND snapshot_id = $2 AND ($3 = 'all' OR record_kind = $3)
AND ($4::TIMESTAMPTZ IS NULL OR (committed_at, commit_sha) < ($4, $5))
ORDER BY committed_at DESC, commit_sha DESC
LIMIT $6`, repoKey, active, kind, cursorAt, cursorSHA, limit+1)
if err != nil {
return nil, "", false, active, fmt.Errorf("读取版本记录:%w", err)
}
defer rows.Close()
for rows.Next() {
var (
record governance.VersionHistoryCommit
label *string
tagsRaw []byte
evidRaw []byte
)
if err := rows.Scan(&record.CommitSHA, &record.Parents, &record.CommittedAt, &record.AuthorDisplay,
&record.Subject, &record.Body, &label, &record.VersionState, &record.RecordKind,
&tagsRaw, &record.ReleaseNotes, &record.CommitURL, &evidRaw, &record.SnapshotID); err != nil {
return nil, "", false, active, fmt.Errorf("解析版本记录:%w", err)
}
record.RepoKey = repoKey
if label != nil {
record.VersionLabel = *label
}
if len(tagsRaw) > 0 {
_ = json.Unmarshal(tagsRaw, &record.ReleaseTags)
}
if len(evidRaw) > 0 {
_ = json.Unmarshal(evidRaw, &record.VersionEvidence)
}
items = append(items, record)
}
if err := rows.Err(); err != nil {
return nil, "", false, active, fmt.Errorf("读取版本记录:%w", err)
}
if len(items) > limit {
items = items[:limit]
hasMore = true
last := items[len(items)-1]
nextCursor = encodeVersionHistoryCursor(active, last.CommittedAt, last.CommitSHA)
}
return items, nextCursor, hasMore, active, nil
}