- 新增 library_versions:测试封存、生产生效、生产预备份三类分开登记,
生产生效版本唯一(旧版本必须先 supersede),测试快照不能顶替生产版本
- 新增 library_jobs + library_job_stages:业务作业身份、阶段、错误与恢复说明,
分项计数用 NULL 表示"总量未知";互斥与幂等由数据库唯一索引保证
- 新增 GET /api/v1/library/overview、/jobs、/jobs/{id};POST /syncs 闸口未齐
返回 503 缺项且不建作业
- 封存作业落库:先建业务作业再入队,worker 推进 export 阶段并登记 test_sealed
- 发布管理读真实状态:生产未知不再顶替、差异 unknown、启动同步按缺项禁用、
同步明细/四类分项来自持久阶段;阶段勾选只认当前作业证据
- 准备信息标注封存时间与范围,不声称实时测试库已就绪
This commit is contained in:
@@ -3,12 +3,14 @@ package httpapi
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"knowledge-governance/internal/governance"
|
||||
"knowledge-governance/internal/jobs"
|
||||
)
|
||||
|
||||
@@ -62,6 +64,39 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
|
||||
return
|
||||
}
|
||||
now := time.Now().UTC()
|
||||
// 业务作业先建:互斥由 library_jobs 的唯一索引保证,这样不会出现"队列里排着两个封存"。
|
||||
// 队列投递失败或请求冲突时把业务作业取消,不留下永远 pending 的占位。
|
||||
libraryJobID := "libseal-" + captureJob
|
||||
createdSealJob := false
|
||||
if store, ok := libraryStore(config); ok {
|
||||
digest, digestErr := governance.LibraryRequestDigest(request.Scope, governance.LibraryJobSeal,
|
||||
map[string]any{"capture_job": captureJob})
|
||||
if digestErr == nil {
|
||||
sealJob, reusedSeal, sealErr := store.CreateLibraryJob(r.Context(), governance.LibraryJob{
|
||||
ID: libraryJobID, Scope: request.Scope, Kind: governance.LibraryJobSeal,
|
||||
IdempotencyKey: "library.seal:" + captureJob, RequestDigest: digest, Actor: requestedBy,
|
||||
}, governance.SealStages(), now)
|
||||
switch {
|
||||
case errors.Is(sealErr, governance.ErrLibraryJobActive):
|
||||
writeJSON(w, http.StatusConflict, map[string]any{
|
||||
"code": "library_seal_active", "error": "该目标已有在飞的封存作业,等它结束再发起",
|
||||
})
|
||||
return
|
||||
case errors.Is(sealErr, governance.ErrLibraryJobIdempotencyConflict):
|
||||
writeJSON(w, http.StatusConflict, map[string]any{
|
||||
"code": "library_seal_scope_conflict", "error": "同一作业号已按另一个范围封存",
|
||||
})
|
||||
return
|
||||
case sealErr != nil:
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create seal job"})
|
||||
return
|
||||
case !reusedSeal:
|
||||
createdSealJob = true
|
||||
default:
|
||||
libraryJobID = sealJob.ID
|
||||
}
|
||||
}
|
||||
}
|
||||
requestedID := fmt.Sprintf("library-capture-%s-%d", request.Scope, now.UnixNano())
|
||||
// The idempotency key is the capture job id: the same logical capture must map
|
||||
// to one queue row. Binding the scope into the key would silently create a
|
||||
@@ -76,9 +111,18 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
|
||||
IdempotencyKey: "library.capture:" + captureJob,
|
||||
}, now)
|
||||
if err != nil || job == nil {
|
||||
if store, ok := libraryStore(config); ok && createdSealJob {
|
||||
_ = store.CancelLibraryJob(r.Context(), libraryJobID, "队列投递失败,未开始封存", now)
|
||||
}
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue capture job"})
|
||||
return
|
||||
}
|
||||
if store, ok := libraryStore(config); ok {
|
||||
if attachErr := store.AttachLibraryQueueJob(r.Context(), libraryJobID, job.ID, now); attachErr != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot attach capture job"})
|
||||
return
|
||||
}
|
||||
}
|
||||
// Enqueue returns the existing row for a reused key. Answer from that row, not
|
||||
// from the current request: a reused job id with another scope must be refused
|
||||
// instead of being reported as a job for the new scope.
|
||||
@@ -87,7 +131,13 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
|
||||
CaptureJob string `json:"capture_job"`
|
||||
RequestedBy string `json:"requested_by"`
|
||||
}
|
||||
cancelSeal := func(reason string) {
|
||||
if store, ok := libraryStore(config); ok && createdSealJob {
|
||||
_ = store.CancelLibraryJob(r.Context(), libraryJobID, reason, now)
|
||||
}
|
||||
}
|
||||
if err = json.Unmarshal(job.Payload, &stored); err != nil || stored.CaptureJob != captureJob {
|
||||
cancelSeal("请求冲突,未开始封存")
|
||||
writeJSON(w, http.StatusConflict, map[string]any{
|
||||
"code": "library_capture_conflict", "error": "该作业号已被另一个封存请求占用",
|
||||
"existing_scope": stored.Scope, "requested_scope": request.Scope,
|
||||
@@ -95,6 +145,7 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
|
||||
return
|
||||
}
|
||||
if stored.Scope != request.Scope {
|
||||
cancelSeal("同一作业号已按另一个范围投递")
|
||||
writeJSON(w, http.StatusConflict, map[string]any{
|
||||
"code": "library_capture_scope_conflict", "error": "同一作业号已按另一个范围投递",
|
||||
"existing_scope": stored.Scope, "requested_scope": request.Scope,
|
||||
|
||||
@@ -0,0 +1,337 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"knowledge-governance/internal/governance"
|
||||
)
|
||||
|
||||
// 整库版本/状态/差异读取契约 + 生产同步的 fail-closed 入口。
|
||||
//
|
||||
// 三类版本严格分开,不能互相顶替:
|
||||
// - 测试封存(archive 里的 sealed 产物)——只证明测试库有一份完整版本;
|
||||
// - 生产当前生效(library_versions.kind=production_effective)——必须有生产验证证据;
|
||||
// - 生产预备份(kind=production_prebackup)——每次生产写入前的独立备份。
|
||||
// 生产未建立权威版本时返回 unknown,不拿最新测试快照冒充。
|
||||
|
||||
type libraryVersionView struct {
|
||||
ID string `json:"id"`
|
||||
Kind string `json:"kind"`
|
||||
SnapshotID string `json:"snapshot_id"`
|
||||
VersionLabel string `json:"version_label"`
|
||||
SourceJobID string `json:"source_job_id"`
|
||||
Evidence map[string]any `json:"evidence"`
|
||||
CreatedBy string `json:"created_by"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
SupersededAt *time.Time `json:"superseded_at,omitempty"`
|
||||
}
|
||||
|
||||
type libraryKnownView struct {
|
||||
State string `json:"state"` // known | unknown
|
||||
Version *libraryVersionView `json:"version,omitempty"`
|
||||
Reason string `json:"reason,omitempty"`
|
||||
}
|
||||
|
||||
type libraryDiffView struct {
|
||||
State string `json:"state"` // unknown | computed
|
||||
Reason string `json:"reason,omitempty"`
|
||||
Added []any `json:"added"`
|
||||
Updated []any `json:"updated"`
|
||||
Removed []any `json:"removed"`
|
||||
}
|
||||
|
||||
type libraryGateView struct {
|
||||
SyncAllowed bool `json:"sync_allowed"`
|
||||
Reasons []string `json:"reasons"`
|
||||
}
|
||||
|
||||
type libraryOverview struct {
|
||||
Scope string `json:"scope"`
|
||||
TestSealed *librarySnapshotView `json:"test_sealed,omitempty"`
|
||||
TestSealedReason string `json:"test_sealed_reason,omitempty"`
|
||||
Production libraryKnownView `json:"production"`
|
||||
Prebackup libraryKnownView `json:"prebackup"`
|
||||
Diff libraryDiffView `json:"diff"`
|
||||
Job *governance.LibraryJob `json:"job,omitempty"`
|
||||
Jobs []governance.LibraryJob `json:"jobs"`
|
||||
Gate libraryGateView `json:"gate"`
|
||||
CaptureAvailable bool `json:"capture_available"`
|
||||
CaptureReason string `json:"capture_reason,omitempty"`
|
||||
Now time.Time `json:"now"`
|
||||
}
|
||||
|
||||
type libraryJobStore interface {
|
||||
CreateLibraryJob(ctx context.Context, job governance.LibraryJob, stages []string, now time.Time) (governance.LibraryJob, bool, error)
|
||||
LibraryJob(ctx context.Context, id string) (governance.LibraryJob, error)
|
||||
ListLibraryJobs(ctx context.Context, scope string, limit int) ([]governance.LibraryJob, error)
|
||||
RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error
|
||||
LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error)
|
||||
UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error
|
||||
AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error
|
||||
AttachLibraryQueueJob(ctx context.Context, jobID, queueJobID string, now time.Time) error
|
||||
CancelLibraryJob(ctx context.Context, jobID, reason string, now time.Time) error
|
||||
}
|
||||
|
||||
func libraryStore(config Config) (libraryJobStore, bool) {
|
||||
store, ok := config.Store.(libraryJobStore)
|
||||
return store, ok
|
||||
}
|
||||
|
||||
func scopeFromQuery(r *http.Request) (string, error) {
|
||||
scope := strings.TrimSpace(r.URL.Query().Get("scope"))
|
||||
if scope == "" {
|
||||
scope = "internal"
|
||||
}
|
||||
if scope != "internal" && scope != "external" {
|
||||
return "", errors.New("scope must be internal or external")
|
||||
}
|
||||
return scope, nil
|
||||
}
|
||||
|
||||
func libraryVersionViewOf(item governance.LibraryVersion) libraryVersionView {
|
||||
return libraryVersionView{ID: item.ID, Kind: string(item.Kind), SnapshotID: item.SnapshotID,
|
||||
VersionLabel: item.VersionLabel, SourceJobID: item.SourceJobID, Evidence: item.Evidence,
|
||||
CreatedBy: item.CreatedBy, CreatedAt: item.CreatedAt, SupersededAt: item.SupersededAt}
|
||||
}
|
||||
|
||||
// librarySyncGate 只依据真实存在的证据判断能不能写生产:闸口、生产端点、
|
||||
// 生产权威版本、目标快照的预备份。任何一项缺失都给出具体原因,不默认放行。
|
||||
func librarySyncGate(config Config, production libraryKnownView, prebackup libraryKnownView, target string) libraryGateView {
|
||||
gate := libraryGateView{SyncAllowed: false, Reasons: []string{}}
|
||||
if !config.ProductionReleaseRequestsEnabled {
|
||||
gate.Reasons = append(gate.Reasons, "生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)")
|
||||
}
|
||||
if !config.ProductionBackupRestoreVerified {
|
||||
gate.Reasons = append(gate.Reasons, "没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)")
|
||||
}
|
||||
if strings.TrimSpace(config.ProductionWeKnoraBaseURL) == "" {
|
||||
gate.Reasons = append(gate.Reasons, "生产端点未配置,无法核验生产当前版本")
|
||||
}
|
||||
if production.State != "known" {
|
||||
gate.Reasons = append(gate.Reasons, "生产当前权威版本未知,不能启动写入")
|
||||
}
|
||||
if target == "" {
|
||||
gate.Reasons = append(gate.Reasons, "还没有可同步的测试封存版本")
|
||||
}
|
||||
if prebackup.State != "known" {
|
||||
gate.Reasons = append(gate.Reasons, "本次目标快照还没有生产预备份")
|
||||
}
|
||||
gate.SyncAllowed = len(gate.Reasons) == 0
|
||||
return gate
|
||||
}
|
||||
|
||||
func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
scope, err := scopeFromQuery(r)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
store, ok := libraryStore(config)
|
||||
if !ok {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false,
|
||||
"reason": "版本登记存储不可用"})
|
||||
return
|
||||
}
|
||||
now := time.Now().UTC()
|
||||
overview := libraryOverview{Scope: scope, Jobs: []governance.LibraryJob{}, Now: now,
|
||||
CaptureAvailable: strings.TrimSpace(config.LibraryAgentSocket) != "",
|
||||
Gate: libraryGateView{Reasons: []string{}},
|
||||
Diff: libraryDiffView{State: "unknown", Reason: "生产与测试的文档级差异读取未接线", Added: []any{}, Updated: []any{}, Removed: []any{}}}
|
||||
if !overview.CaptureAvailable {
|
||||
overview.CaptureReason = "主机侧封存 agent 未接线"
|
||||
}
|
||||
|
||||
// 测试封存来自归档:它只是测试侧事实。
|
||||
snapshots, snapErr := readLibrarySnapshots(config.LibraryArchiveRoot)
|
||||
if snapErr != nil {
|
||||
overview.TestSealedReason = "归档不可读"
|
||||
} else if !snapshots.Available {
|
||||
overview.TestSealedReason = snapshots.Reason
|
||||
} else {
|
||||
for index := range snapshots.Snapshots {
|
||||
if snapshots.Snapshots[index].Scope == scope {
|
||||
overview.TestSealed = &snapshots.Snapshots[index]
|
||||
break
|
||||
}
|
||||
}
|
||||
if overview.TestSealed == nil {
|
||||
overview.TestSealedReason = "还没有该目标的测试封存"
|
||||
}
|
||||
}
|
||||
|
||||
// 生产生效 / 预备份 / 作业来自持久登记。
|
||||
versions, err := store.LibraryVersions(r.Context(), scope, 50)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
|
||||
return
|
||||
}
|
||||
overview.Production = libraryKnownView{State: "unknown", Reason: "还没有生产验证通过的生效版本记录"}
|
||||
overview.Prebackup = libraryKnownView{State: "unknown", Reason: "本次目标快照还没有生产预备份"}
|
||||
target := ""
|
||||
if overview.TestSealed != nil {
|
||||
target = overview.TestSealed.SnapshotID
|
||||
}
|
||||
for index := range versions {
|
||||
item := versions[index]
|
||||
view := libraryVersionViewOf(item)
|
||||
switch item.Kind {
|
||||
case governance.LibraryVersionProductionEffective:
|
||||
if item.SupersededAt == nil {
|
||||
overview.Production = libraryKnownView{State: "known", Version: &view}
|
||||
}
|
||||
case governance.LibraryVersionProductionPrebackup:
|
||||
// 只有与目标快照绑定的预备份才算"这次同步前的备份"。
|
||||
if target != "" && item.SnapshotID == target {
|
||||
overview.Prebackup = libraryKnownView{State: "known", Version: &view}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
recent, err := store.ListLibraryJobs(r.Context(), scope, 20)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library jobs"})
|
||||
return
|
||||
}
|
||||
overview.Jobs = recent
|
||||
for index := range recent {
|
||||
if recent[index].State == governance.LibraryJobPending || recent[index].State == governance.LibraryJobRunning {
|
||||
overview.Job = &recent[index]
|
||||
break
|
||||
}
|
||||
}
|
||||
if overview.Job == nil && len(recent) > 0 {
|
||||
overview.Job = &recent[0]
|
||||
}
|
||||
|
||||
overview.Gate = librarySyncGate(config, overview.Production, overview.Prebackup, target)
|
||||
writeJSON(w, http.StatusOK, overview)
|
||||
}
|
||||
|
||||
func libraryJobsHandler(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
scope, err := scopeFromQuery(r)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
store, ok := libraryStore(config)
|
||||
if !ok {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, "reason": "版本登记存储不可用", "jobs": []any{}})
|
||||
return
|
||||
}
|
||||
items, err := store.ListLibraryJobs(r.Context(), scope, 20)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library jobs"})
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]any{"available": true, "jobs": items})
|
||||
}
|
||||
|
||||
func libraryJobDetailHandler(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
store, ok := libraryStore(config)
|
||||
if !ok {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{"available": false, "reason": "版本登记存储不可用"})
|
||||
return
|
||||
}
|
||||
id := strings.TrimSpace(r.PathValue("id"))
|
||||
if id == "" {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "job id required"})
|
||||
return
|
||||
}
|
||||
job, err := store.LibraryJob(r.Context(), id)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusNotFound, map[string]any{"available": false, "reason": "作业不存在"})
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]any{"available": true, "job": job})
|
||||
}
|
||||
|
||||
// librarySyncEnqueue 是生产同步的唯一入口:闸口未齐时**不建作业**,直接说明缺项。
|
||||
// 这样按钮永远不会假接通,也不会留下一个永远失败的空作业。
|
||||
func librarySyncEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
if r.Method != http.MethodPost {
|
||||
writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
|
||||
return
|
||||
}
|
||||
store, ok := libraryStore(config)
|
||||
if !ok {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_sync_unavailable", "reasons": []string{"版本登记存储不可用"}})
|
||||
return
|
||||
}
|
||||
var request struct {
|
||||
Scope string `json:"scope"`
|
||||
Target string `json:"target_snapshot_id"`
|
||||
}
|
||||
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
|
||||
return
|
||||
}
|
||||
if request.Scope != "internal" && request.Scope != "external" {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "scope must be internal or external"})
|
||||
return
|
||||
}
|
||||
overview := libraryOverview{Scope: request.Scope}
|
||||
versions, err := store.LibraryVersions(r.Context(), request.Scope, 50)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
|
||||
return
|
||||
}
|
||||
overview.Production = libraryKnownView{State: "unknown"}
|
||||
overview.Prebackup = libraryKnownView{State: "unknown"}
|
||||
for index := range versions {
|
||||
item := versions[index]
|
||||
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
|
||||
view := libraryVersionViewOf(item)
|
||||
overview.Production = libraryKnownView{State: "known", Version: &view}
|
||||
}
|
||||
if item.Kind == governance.LibraryVersionProductionPrebackup && request.Target != "" && item.SnapshotID == request.Target {
|
||||
view := libraryVersionViewOf(item)
|
||||
overview.Prebackup = libraryKnownView{State: "known", Version: &view}
|
||||
}
|
||||
}
|
||||
gate := librarySyncGate(config, overview.Production, overview.Prebackup, request.Target)
|
||||
if !gate.SyncAllowed {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{
|
||||
"code": "library_sync_blocked", "reasons": gate.Reasons,
|
||||
"production": overview.Production, "prebackup": overview.Prebackup,
|
||||
})
|
||||
return
|
||||
}
|
||||
|
||||
// 走到这里说明闸口与证据都齐了才真正建作业;互斥与幂等由数据库索引保证。
|
||||
digest, err := governance.LibraryRequestDigest(request.Scope, governance.LibraryJobSync,
|
||||
map[string]any{"target_snapshot_id": request.Target})
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot digest request"})
|
||||
return
|
||||
}
|
||||
actor := ""
|
||||
if identity, ok := sessionFrom(r.Context()); ok {
|
||||
actor = identity.Username
|
||||
}
|
||||
now := time.Now().UTC()
|
||||
jobID := fmt.Sprintf("libsync-%s-%d", request.Scope, now.UnixNano())
|
||||
job, reused, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{
|
||||
ID: jobID, Scope: request.Scope, Kind: governance.LibraryJobSync,
|
||||
IdempotencyKey: "library.sync:" + request.Scope + ":" + request.Target, RequestDigest: digest,
|
||||
TargetSnapshotID: request.Target, Actor: actor,
|
||||
}, governance.SyncStages(), now)
|
||||
if errors.Is(err, governance.ErrLibraryJobActive) {
|
||||
writeJSON(w, http.StatusConflict, map[string]any{"code": "library_sync_active", "error": "该目标已有在飞的同步作业"})
|
||||
return
|
||||
}
|
||||
if errors.Is(err, governance.ErrLibraryJobIdempotencyConflict) {
|
||||
writeJSON(w, http.StatusConflict, map[string]any{"code": "library_sync_conflict", "error": "同一幂等键对应了不同的请求"})
|
||||
return
|
||||
}
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create library sync job"})
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": reused})
|
||||
}
|
||||
@@ -0,0 +1,230 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"knowledge-governance/internal/governance"
|
||||
)
|
||||
|
||||
// 生产闸口与整库状态契约的针对性测试:不做数据库集成,只验证
|
||||
// "证据不齐就不建作业" 与 "三类版本不互相顶替" 这两条硬规则。
|
||||
|
||||
// 复用既有 fakeJobStore 提供 Store 的其余方法,只覆盖整库作业这几个。
|
||||
type fakeLibraryStore struct {
|
||||
fakeJobStore
|
||||
versions []governance.LibraryVersion
|
||||
jobs []governance.LibraryJob
|
||||
createN int
|
||||
lastJob governance.LibraryJob
|
||||
lastState governance.LibraryJobState
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) CreateLibraryJob(_ context.Context, job governance.LibraryJob, _ []string, _ time.Time) (governance.LibraryJob, bool, error) {
|
||||
f.createN++
|
||||
f.lastJob = job
|
||||
return job, false, nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) LibraryJob(_ context.Context, id string) (governance.LibraryJob, error) {
|
||||
return governance.LibraryJob{ID: id}, nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) ListLibraryJobs(_ context.Context, scope string, _ int) ([]governance.LibraryJob, error) {
|
||||
result := make([]governance.LibraryJob, 0, len(f.jobs))
|
||||
for _, job := range f.jobs {
|
||||
if job.Scope == scope {
|
||||
result = append(result, job)
|
||||
}
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) RecordLibraryVersion(_ context.Context, version governance.LibraryVersion) error {
|
||||
f.versions = append(f.versions, version)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) LibraryVersions(_ context.Context, scope string, _ int) ([]governance.LibraryVersion, error) {
|
||||
result := make([]governance.LibraryVersion, 0, len(f.versions))
|
||||
for _, version := range f.versions {
|
||||
if version.Scope == scope {
|
||||
result = append(result, version)
|
||||
}
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) UpdateLibraryStage(_ context.Context, _, _, _ string, _, _, _, _ *int64, _ string, _ time.Time) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState, _, _, _, _, _ string, _ time.Time) error {
|
||||
f.lastState = state
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) AttachLibraryQueueJob(_ context.Context, _, _ string, _ time.Time) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
func (f *fakeLibraryStore) CancelLibraryJob(_ context.Context, _, _ string, _ time.Time) error {
|
||||
f.lastState = governance.LibraryJobCancelled
|
||||
return nil
|
||||
}
|
||||
|
||||
func TestLibrarySyncGateRequiresEveryPieceOfEvidence(t *testing.T) {
|
||||
known := libraryKnownView{State: "known", Version: &libraryVersionView{ID: "v1"}}
|
||||
cases := []struct {
|
||||
name string
|
||||
config Config
|
||||
production libraryKnownView
|
||||
prebackup libraryKnownView
|
||||
target string
|
||||
allowed bool
|
||||
reason string
|
||||
}{
|
||||
{
|
||||
name: "default installation is closed",
|
||||
config: Config{},
|
||||
production: libraryKnownView{State: "unknown"},
|
||||
prebackup: libraryKnownView{State: "unknown"},
|
||||
target: "snap-1",
|
||||
allowed: false,
|
||||
reason: "生产写入闸口关闭",
|
||||
},
|
||||
{
|
||||
name: "flags on but restore evidence missing",
|
||||
config: Config{ProductionReleaseRequestsEnabled: true,
|
||||
ProductionWeKnoraBaseURL: "http://prod.invalid"},
|
||||
production: known,
|
||||
prebackup: known,
|
||||
target: "snap-1",
|
||||
allowed: false,
|
||||
reason: "没有已核验的生产恢复演练证据",
|
||||
},
|
||||
{
|
||||
name: "everything present",
|
||||
config: Config{ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true,
|
||||
ProductionWeKnoraBaseURL: "http://prod.invalid"},
|
||||
production: known,
|
||||
prebackup: known,
|
||||
target: "snap-1",
|
||||
allowed: true,
|
||||
},
|
||||
}
|
||||
for _, testCase := range cases {
|
||||
t.Run(testCase.name, func(t *testing.T) {
|
||||
gate := librarySyncGate(testCase.config, testCase.production, testCase.prebackup, testCase.target)
|
||||
if gate.SyncAllowed != testCase.allowed {
|
||||
t.Fatalf("sync_allowed = %v, want %v (%v)", gate.SyncAllowed, testCase.allowed, gate.Reasons)
|
||||
}
|
||||
if testCase.reason != "" {
|
||||
joined := strings.Join(gate.Reasons, "|")
|
||||
if !strings.Contains(joined, testCase.reason) {
|
||||
t.Fatalf("reasons %v missing %q", gate.Reasons, testCase.reason)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 闸口关闭时 POST /api/v1/library/syncs 必须直接拒绝,并且**不创建**作业:
|
||||
// 不能留下一个永远失败的空作业,也不能让按钮看起来接通了。
|
||||
func TestLibrarySyncEnqueueRefusesWithoutCreatingJob(t *testing.T) {
|
||||
store := &fakeLibraryStore{}
|
||||
config := Config{Store: store}
|
||||
request := httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs",
|
||||
strings.NewReader(`{"scope":"internal","target_snapshot_id":"snap-1"}`))
|
||||
recorder := httptest.NewRecorder()
|
||||
librarySyncEnqueue(recorder, request, config)
|
||||
if recorder.Code != http.StatusServiceUnavailable {
|
||||
t.Fatalf("status = %d, want 503", recorder.Code)
|
||||
}
|
||||
if store.createN != 0 {
|
||||
t.Fatalf("created %d jobs while gate is closed", store.createN)
|
||||
}
|
||||
var body struct {
|
||||
Code string `json:"code"`
|
||||
Reasons []string `json:"reasons"`
|
||||
}
|
||||
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
|
||||
t.Fatalf("decode body: %v", err)
|
||||
}
|
||||
if body.Code != "library_sync_blocked" || len(body.Reasons) == 0 {
|
||||
t.Fatalf("unexpected refusal body: %s", recorder.Body.String())
|
||||
}
|
||||
}
|
||||
|
||||
// 即使闸口打开,缺少与目标快照绑定的预备份也必须拒绝。
|
||||
func TestLibrarySyncEnqueueRequiresPrebackupForTarget(t *testing.T) {
|
||||
store := &fakeLibraryStore{versions: []governance.LibraryVersion{{
|
||||
ID: "ver-prod-1", Scope: "internal", Kind: governance.LibraryVersionProductionEffective,
|
||||
SnapshotID: "prod-snap", VersionLabel: "prod-2026.10", CreatedAt: time.Now().UTC(),
|
||||
}}}
|
||||
config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true,
|
||||
ProductionWeKnoraBaseURL: "http://prod.invalid"}
|
||||
request := httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs",
|
||||
strings.NewReader(`{"scope":"internal","target_snapshot_id":"snap-1"}`))
|
||||
recorder := httptest.NewRecorder()
|
||||
librarySyncEnqueue(recorder, request, config)
|
||||
if recorder.Code != http.StatusServiceUnavailable {
|
||||
t.Fatalf("status = %d, want 503", recorder.Code)
|
||||
}
|
||||
if !strings.Contains(recorder.Body.String(), "预备份") {
|
||||
t.Fatalf("refusal must name the missing prebackup: %s", recorder.Body.String())
|
||||
}
|
||||
if store.createN != 0 {
|
||||
t.Fatalf("created %d jobs without a prebackup", store.createN)
|
||||
}
|
||||
}
|
||||
|
||||
// 三类版本必须分开读:production_effective 才是生产当前,测试封存不能顶替。
|
||||
func TestLibraryOverviewKeepsVersionKindsSeparate(t *testing.T) {
|
||||
now := time.Now().UTC()
|
||||
store := &fakeLibraryStore{versions: []governance.LibraryVersion{
|
||||
{ID: "ver-test", Scope: "internal", Kind: governance.LibraryVersionTestSealed, SnapshotID: "snap-1", CreatedAt: now},
|
||||
{ID: "ver-prod", Scope: "internal", Kind: governance.LibraryVersionProductionEffective,
|
||||
SnapshotID: "prod-snap", VersionLabel: "prod-2026.10", CreatedAt: now},
|
||||
{ID: "ver-backup-other", Scope: "internal", Kind: governance.LibraryVersionProductionPrebackup,
|
||||
SnapshotID: "other-snap", CreatedAt: now},
|
||||
}}
|
||||
config := Config{Store: store, LibraryArchiveRoot: t.TempDir()}
|
||||
request := httptest.NewRequest(http.MethodGet, "/api/v1/library/overview?scope=internal", nil)
|
||||
recorder := httptest.NewRecorder()
|
||||
libraryOverviewHandler(recorder, request, config)
|
||||
if recorder.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d: %s", recorder.Code, recorder.Body.String())
|
||||
}
|
||||
var body struct {
|
||||
Production libraryKnownView `json:"production"`
|
||||
Prebackup libraryKnownView `json:"prebackup"`
|
||||
Diff struct {
|
||||
State string `json:"state"`
|
||||
} `json:"diff"`
|
||||
Gate struct {
|
||||
SyncAllowed bool `json:"sync_allowed"`
|
||||
} `json:"gate"`
|
||||
}
|
||||
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
|
||||
t.Fatalf("decode overview: %v", err)
|
||||
}
|
||||
if body.Production.State != "known" || body.Production.Version == nil || body.Production.Version.ID != "ver-prod" {
|
||||
t.Fatalf("production must be the effective version, got %+v", body.Production)
|
||||
}
|
||||
// 预备份只对匹配目标快照的那一份生效;这里目标为空(归档不可用),所以是未知。
|
||||
if body.Prebackup.State != "unknown" {
|
||||
t.Fatalf("prebackup must stay unknown without a matching target snapshot: %+v", body.Prebackup)
|
||||
}
|
||||
if body.Diff.State != "unknown" {
|
||||
t.Fatalf("diff must be unknown until the comparison is wired, got %q", body.Diff.State)
|
||||
}
|
||||
if body.Gate.SyncAllowed {
|
||||
t.Fatal("gate must stay closed")
|
||||
}
|
||||
}
|
||||
@@ -405,6 +405,20 @@ func NewHandler(config Config) (http.Handler, error) {
|
||||
mux.HandleFunc("GET /api/v1/library/captures", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryCaptureJobs(w, r, config)
|
||||
})
|
||||
// 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业。
|
||||
mux.HandleFunc("GET /api/v1/library/overview", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryOverviewHandler(w, r, config)
|
||||
})
|
||||
mux.HandleFunc("GET /api/v1/library/jobs", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryJobsHandler(w, r, config)
|
||||
})
|
||||
mux.HandleFunc("GET /api/v1/library/jobs/{id}", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryJobDetailHandler(w, r, config)
|
||||
})
|
||||
// 生产同步唯一入口:闸口未齐不建作业,返回缺项而不是假 Accepted。
|
||||
mux.HandleFunc("POST /api/v1/library/syncs", func(w http.ResponseWriter, r *http.Request) {
|
||||
librarySyncEnqueue(w, r, config)
|
||||
})
|
||||
// 全部 main 提交时间线(读本库缓存,不直接打 Gitea)
|
||||
mux.HandleFunc("GET /api/v1/version-history", func(w http.ResponseWriter, r *http.Request) {
|
||||
versionHistoryList(w, r, config)
|
||||
|
||||
Reference in New Issue
Block a user