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 } if queue, ok := config.Store.(interface { EnqueueVersionHistorySync(context.Context, string, string, string, time.Time) (*jobs.Job, error) }); ok { target := "" info := version.Snapshot() if info.IdentityAvailable && info.CommitSHA != nil { target = *info.CommitSHA } job, e := queue.EnqueueVersionHistorySync(r.Context(), config.VersionHistoryRepo, triggeredBy, target, now) if e != nil || job == nil { versionHistoryError(w, 500, "version_history_unavailable", "入队同步任务失败") return } writeJSON(w, 202, map[string]any{"job_id": job.ID, "status": job.State}) 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 + ":" + requestedID}, 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 }