e34306b2db
build / build (push) Failing after 18s
发布管理: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 档案)。
322 lines
13 KiB
Go
322 lines
13 KiB
Go
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
|
||
}
|