feat(library): 整库版本/作业持久化与状态读取契约,生产同步默认拒绝
build / build (push) Failing after 17s

- 新增 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:
姚章浩
2026-10-28 13:58:51 +08:00
parent 58d0483d44
commit dc9e827656
14 changed files with 1902 additions and 126 deletions
+15
View File
@@ -1,5 +1,20 @@
# Changelog
## 开发快照 snapshot/v0.1.114 - 2026-10-28
### Added
- 整库版本与持久作业:新增 `library_versions`(test_sealed / production_effective / production_prebackup 三类分开登记,生产生效版本唯一)、`library_jobs`(业务作业身份、阶段、错误与恢复说明)与 `library_job_stages`(分项计数,NULL 表示总量未知)。互斥与幂等由数据库唯一索引保证,不依赖前端禁用或单 worker。
- 读接口:`GET /api/v1/library/overview`(三类版本 + 差异 + 作业 + 启动缺项)、`GET /api/v1/library/jobs`、`GET /api/v1/library/jobs/{id}`。
- 写接口:`POST /api/v1/library/syncs`,闸口、生产恢复演练证据、生产权威版本、本次预备份缺一即 503 并逐条给出原因,且**不创建**作业。
- 封存作业落库:发起封存先建业务作业(同一目标只能一个在飞),worker 推进 export 阶段、成功登记 test_sealed 版本、失败同时记录阶段与作业状态。
- 发布管理改为读取真实状态:生产当前来自生产生效版本(没有就显示未知)、目标来自测试封存、差异未接线保持 unknown、启动同步按缺项禁用、同步明细与四类分项来自持久阶段。
### Fixed
- 没有当前作业时不再把历史测试封存当作「固定测试版本」已完成:阶段勾选只来自当前作业的阶段证据,并提示「已有测试封存(历史)/ 本次作业尚未开始」。
- 准备信息注明依据哪次封存快照与范围,明确「不代表实时测试库已就绪」,没有放宽任何完整性检查。
## 开发快照 snapshot/v0.1.113 - 2026-10-28
### Changed
+167
View File
@@ -898,6 +898,173 @@
}
}
},
"/api/v1/library/overview": {
"get": {
"tags": [
"Runtime"
],
"operationId": "getLibraryOverview",
"summary": "整库状态:测试封存 / 生产生效 / 生产预备份三类版本分开返回,差异未接线时为 unknown,并给出启动同步的缺项",
"parameters": [
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"internal",
"external"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"description": "整库版本登记存储不可用"
}
}
}
},
"/api/v1/library/jobs": {
"get": {
"tags": [
"Runtime"
],
"operationId": "listLibraryJobs",
"summary": "列出该目标最近的整库作业(测试封存与生产同步分开,含阶段与结果;重启后仍可读)",
"parameters": [
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"internal",
"external"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/library/jobs/{id}": {
"get": {
"tags": [
"Runtime"
],
"operationId": "getLibraryJob",
"summary": "读取单个整库作业的阶段、计数、错误与恢复说明",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"description": "作业不存在"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/library/syncs": {
"post": {
"tags": [
"Runtime"
],
"operationId": "startLibrarySync",
"summary": "启动生产同步:闸口、生产恢复演练证据、生产权威版本或本次预备份缺一即拒绝,且不创建作业",
"parameters": [
{
"name": "X-Governance-Action",
"in": "header",
"required": false,
"schema": {
"const": "library-sync"
}
}
],
"responses": {
"202": {
"description": "已创建同步作业(互斥与幂等由数据库唯一索引保证)"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"409": {
"description": "该目标已有在飞同步作业,或同一幂等键对应不同请求"
},
"500": {
"$ref": "#/components/responses/InternalError"
},
"503": {
"description": "闸口或证据未齐,返回具体缺项且不创建作业"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"target_snapshot_id"
],
"properties": {
"scope": {
"type": "string",
"enum": [
"internal",
"external"
]
},
"target_snapshot_id": {
"type": "string"
}
}
}
}
}
}
}
},
"/api/v1/library/snapshots/{id}": {
"get": {
"tags": [
+64
View File
@@ -3,11 +3,13 @@ package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"log"
"os"
"os/signal"
"path/filepath"
"strings"
"syscall"
"time"
@@ -29,6 +31,9 @@ import (
// libraryCaptureJobType is shared with the API which enqueues it.
const libraryCaptureJobType = "library.capture"
// librarySyncJobType 是生产同步作业的队列类型;与封存严格分开,状态不共用。
const librarySyncJobType = "library.sync"
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
@@ -144,15 +149,74 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
if err := json.Unmarshal(job.Payload, &payload); err != nil || (payload.Scope != "internal" && payload.Scope != "external") || payload.CaptureJob == "" {
return fmt.Errorf("invalid library capture payload")
}
// 持久作业:页面读的是这里写的阶段与结果,worker 重启后仍能如实展示。
libraryJobID := "libseal-" + payload.CaptureJob
startedAt := time.Now().UTC()
if advanceErr := store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobRunning, "export", "", "", "", "", startedAt); advanceErr != nil {
log.Printf("library seal job %s cannot be advanced: %v", libraryJobID, advanceErr)
}
if stageErr := store.UpdateLibraryStage(ctx, libraryJobID, "export", "running", nil, nil, nil, nil,
"主机侧正在暂停写入者、导出并恢复", startedAt); stageErr != nil {
log.Printf("library seal job %s stage update failed: %v", libraryJobID, stageErr)
}
result, err := libraryagent.Capture(ctx, agentConfig, payload.Scope, payload.CaptureJob)
finishedAt := time.Now().UTC()
if err != nil {
// 导出失败时阶段与作业都要留痕;恢复责任在 agent,不会因为作业失败而假装来源已恢复。
_ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, err.Error(), finishedAt)
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", err.Error(),
"agent 已执行恢复检查;确认来源 healthy 后可重试同一作业号", "", "", finishedAt)
log.Printf("library capture failed scope=%s capture_job=%s: %v", payload.Scope, payload.CaptureJob, err)
return err
}
// 封存产物成版本记录:只登记"测试封存",绝不写成生产生效版本。
versionErr := store.RecordLibraryVersion(ctx, governance.LibraryVersion{
ID: "libver-" + payload.Scope + "-" + result.SnapshotID, Scope: payload.Scope,
Kind: governance.LibraryVersionTestSealed, SnapshotID: result.SnapshotID, SourceJobID: libraryJobID,
Evidence: map[string]any{"capture_job": payload.CaptureJob, "replay": result.Replay,
"requested_by": payload.RequestedBy, "agent_result": json.RawMessage(result.Payload)},
CreatedBy: payload.RequestedBy, CreatedAt: finishedAt,
})
if versionErr != nil {
log.Printf("library seal job %s cannot record version: %v", libraryJobID, versionErr)
}
_ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "succeeded", nil, nil, nil, nil,
"已封存快照 "+result.SnapshotID, finishedAt)
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobSucceeded, "export", "", "",
result.SnapshotID, "", finishedAt)
log.Printf("library capture completed scope=%s capture_job=%s snapshot=%s replay=%v requested_by=%s",
payload.Scope, payload.CaptureJob, result.SnapshotID, result.Replay, payload.RequestedBy)
return nil
}
// 生产同步:唯一入口在 API(闸口未齐不建作业)。这里仍实现执行器,
// 但默认 fail-closed:没有闸口证据就明确失败,绝不向生产写入半个字节。
handlers[librarySyncJobType] = func(ctx context.Context, job jobs.Job) error {
var payload struct {
LibraryJobID string `json:"library_job_id"`
Scope string `json:"scope"`
TargetSnapshotID string `json:"target_snapshot_id"`
}
if err := json.Unmarshal(job.Payload, &payload); err != nil || payload.LibraryJobID == "" {
return fmt.Errorf("invalid library sync payload")
}
now := time.Now().UTC()
reasons := make([]string, 0, 3)
if !config.ProductionReleaseRequestsEnabled {
reasons = append(reasons, "生产写入闸口关闭")
}
if !config.ProductionBackupRestoreVerified {
reasons = append(reasons, "没有已核验的生产恢复演练证据")
}
// 生产写入适配与预备份实现之前,执行链本身就是缺项:直接拒绝而不是空转。
reasons = append(reasons, "生产预备份与写入适配尚未实现")
message := "生产同步执行链未接通:" + strings.Join(reasons, ";")
_ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "prebackup", "", "", "", "", now)
_ = store.UpdateLibraryStage(ctx, payload.LibraryJobID, "prebackup", "failed", nil, nil, nil, nil, message, now)
_ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "prebackup", message,
"未对生产执行任何写入,无需恢复", "", "", now)
log.Printf("library sync refused job=%s scope=%s: %s", payload.LibraryJobID, payload.Scope, message)
return errors.New(message)
}
// A crash can leave the source writer stopped: recover before taking work,
// and keep the failure visible instead of pretending the worker is ready.
go func() {
+117
View File
@@ -0,0 +1,117 @@
package governance
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"time"
)
// 整库版本与作业的领域类型:与队列(jobs)分开——队列负责租约与重试,
// 这里负责业务身份、阶段与结果,重启后仍能如实展示。
type LibraryVersionKind string
const (
// LibraryVersionTestSealed 是测试库封存产物:只证明一份完整测试版本被封存,
// 不代表生产生效,也不代表做过生产恢复演练。
LibraryVersionTestSealed LibraryVersionKind = "test_sealed"
// LibraryVersionProductionEffective 是生产当前权威版本:只有生产验证通过并
// 记录证据后才能写入,测试快照不能顶替它。
LibraryVersionProductionEffective LibraryVersionKind = "production_effective"
// LibraryVersionProductionPrebackup 是每次生产写入前的独立预备份。
LibraryVersionProductionPrebackup LibraryVersionKind = "production_prebackup"
)
type LibraryJobKind string
const (
LibraryJobSeal LibraryJobKind = "seal"
LibraryJobSync LibraryJobKind = "sync"
)
type LibraryJobState string
const (
LibraryJobPending LibraryJobState = "pending"
LibraryJobRunning LibraryJobState = "running"
LibraryJobSucceeded LibraryJobState = "succeeded"
LibraryJobFailed LibraryJobState = "failed"
LibraryJobCancelled LibraryJobState = "cancelled"
)
// ErrLibraryJobActive:同一目标同一类作业已有在飞作业(数据库级互斥)。
var ErrLibraryJobActive = errors.New("library job already active for this target")
// ErrLibraryJobIdempotencyConflict:同一幂等键对应了不同的请求体。
var ErrLibraryJobIdempotencyConflict = errors.New("library job idempotency key reused with a different request")
type LibraryStage struct {
Stage string `json:"stage"`
State string `json:"state"`
// Total/Completed/BytesTotal/BytesDone 为 nil 表示该维度没有可靠数据,
// 界面必须显示"未知",不得当 0 或据此算百分比。
Total *int64 `json:"total"`
Completed *int64 `json:"completed"`
BytesTotal *int64 `json:"bytes_total"`
BytesDone *int64 `json:"bytes_done"`
Detail string `json:"detail"`
UpdatedAt time.Time `json:"updated_at"`
}
type LibraryJob struct {
ID string `json:"id"`
Scope string `json:"scope"`
Kind LibraryJobKind `json:"kind"`
State LibraryJobState `json:"state"`
Stage string `json:"stage"`
IdempotencyKey string `json:"-"`
RequestDigest string `json:"request_digest"`
QueueJobID string `json:"queue_job_id"`
SnapshotID string `json:"snapshot_id"`
TargetSnapshotID string `json:"target_snapshot_id"`
Actor string `json:"actor"`
Error string `json:"error"`
Recovery string `json:"recovery"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
FinishedAt *time.Time `json:"finished_at"`
Stages []LibraryStage `json:"stages"`
}
type LibraryVersion struct {
ID string `json:"id"`
Scope string `json:"scope"`
Kind LibraryVersionKind `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"`
}
// LibraryRequestDigest 绑定一次请求的确切含义:同键不同体必须被拒绝,而不是
// 复用旧作业。只覆盖会影响执行结果的字段;actor 不参与摘要。
func LibraryRequestDigest(scope string, kind LibraryJobKind, payload map[string]any) (string, error) {
canonical := map[string]any{"scope": scope, "kind": string(kind), "payload": payload}
raw, err := json.Marshal(canonical)
if err != nil {
return "", err
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:]), nil
}
// SyncStages 是生产同步作业的固定阶段顺序:先备份并核验恢复条件,再写生产,
// 最后验证;失败时走恢复而不是把作业标成功。
func SyncStages() []string {
return []string{"prebackup", "database", "resources", "index", "wiki", "verify", "rollback"}
}
// SealStages 是封存作业的阶段:导出是原子操作,没有分项进度。
func SealStages() []string {
return []string{"export"}
}
+51
View File
@@ -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,
+337
View File
@@ -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})
}
+230
View File
@@ -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")
}
}
+14
View File
@@ -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)
+276
View File
@@ -0,0 +1,276 @@
package postgres
import (
"context"
"encoding/json"
"errors"
"fmt"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgconn"
"knowledge-governance/internal/governance"
)
// 整库作业与版本:队列(jobs)负责租约重试,本文件负责业务身份、阶段与结果。
// 互斥与幂等都由数据库唯一索引保证,不依赖前端或单 worker 部署。
func (s *Store) CreateLibraryJob(ctx context.Context, job governance.LibraryJob, stages []string, now time.Time) (governance.LibraryJob, bool, error) {
request := job.RequestDigest
if request == "" {
return governance.LibraryJob{}, false, errors.New("library job requires a request digest")
}
rawRequest, err := json.Marshal(map[string]any{"digest": request, "kind": string(job.Kind), "scope": job.Scope})
if err != nil {
return governance.LibraryJob{}, false, err
}
var id string
err = s.db.QueryRow(ctx, `
INSERT INTO library_jobs (id, scope, kind, state, stage, idempotency_key, request_digest, request,
queue_job_id, snapshot_id, target_snapshot_id, actor, error, recovery, created_at, updated_at)
VALUES ($1,$2,$3,'pending','',$4,$5,$6,$7,$8,$9,$10,'','',$11,$11)
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id`,
job.ID, job.Scope, string(job.Kind), job.IdempotencyKey, request, rawRequest,
job.QueueJobID, job.SnapshotID, job.TargetSnapshotID, job.Actor, now.UTC()).Scan(&id)
if err != nil {
var pgErr *pgconn.PgError
if errors.As(err, &pgErr) && pgErr.Code == "23505" {
if pgErr.ConstraintName == "library_jobs_active" {
return governance.LibraryJob{}, false, governance.ErrLibraryJobActive
}
}
if !errors.Is(err, pgx.ErrNoRows) {
return governance.LibraryJob{}, false, fmt.Errorf("create library job: %w", err)
}
// 幂等键已存在:必须返回**已存**作业,并核对请求体是否一致。
existing, loadErr := s.libraryJobByKey(ctx, job.IdempotencyKey)
if loadErr != nil {
return governance.LibraryJob{}, false, loadErr
}
if existing.RequestDigest != request {
return existing, false, governance.ErrLibraryJobIdempotencyConflict
}
return existing, true, nil
}
for _, stage := range stages {
if _, err := s.db.Exec(ctx, `
INSERT INTO library_job_stages (job_id, stage, state, detail, updated_at)
VALUES ($1,$2,'pending','',$3)
ON CONFLICT (job_id, stage) DO NOTHING`, id, stage, now.UTC()); err != nil {
return governance.LibraryJob{}, false, fmt.Errorf("create library job stage: %w", err)
}
}
created, err := s.LibraryJob(ctx, id)
return created, false, err
}
func (s *Store) libraryJobByKey(ctx context.Context, key string) (governance.LibraryJob, error) {
var id string
if err := s.db.QueryRow(ctx, `SELECT id FROM library_jobs WHERE idempotency_key=$1`, key).Scan(&id); err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return governance.LibraryJob{}, errors.New("library job idempotency key not found")
}
return governance.LibraryJob{}, fmt.Errorf("load library job by key: %w", err)
}
return s.LibraryJob(ctx, id)
}
func (s *Store) LibraryJob(ctx context.Context, id string) (governance.LibraryJob, error) {
var job governance.LibraryJob
var kind, state string
var finished *time.Time
if err := s.db.QueryRow(ctx, `
SELECT id, scope, kind, state, stage, idempotency_key, request_digest, queue_job_id, snapshot_id,
target_snapshot_id, actor, error, recovery, created_at, updated_at, finished_at
FROM library_jobs WHERE id=$1`, id).Scan(&job.ID, &job.Scope, &kind, &state, &job.Stage, &job.IdempotencyKey,
&job.RequestDigest, &job.QueueJobID, &job.SnapshotID, &job.TargetSnapshotID, &job.Actor, &job.Error,
&job.Recovery, &job.CreatedAt, &job.UpdatedAt, &finished); err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return governance.LibraryJob{}, err
}
return governance.LibraryJob{}, fmt.Errorf("load library job: %w", err)
}
job.Kind, job.State, job.FinishedAt = governance.LibraryJobKind(kind), governance.LibraryJobState(state), finished
stages, err := s.libraryStages(ctx, id)
if err != nil {
return governance.LibraryJob{}, err
}
job.Stages = stages
return job, nil
}
func (s *Store) libraryStages(ctx context.Context, id string) ([]governance.LibraryStage, error) {
rows, err := s.db.Query(ctx, `
SELECT stage, state, total, completed, bytes_total, bytes_done, detail, updated_at
FROM library_job_stages WHERE job_id=$1 ORDER BY updated_at, stage`, id)
if err != nil {
return nil, fmt.Errorf("load library job stages: %w", err)
}
defer rows.Close()
result := make([]governance.LibraryStage, 0, 7)
for rows.Next() {
var stage governance.LibraryStage
if err := rows.Scan(&stage.Stage, &stage.State, &stage.Total, &stage.Completed, &stage.BytesTotal,
&stage.BytesDone, &stage.Detail, &stage.UpdatedAt); err != nil {
return nil, fmt.Errorf("scan library job stage: %w", err)
}
result = append(result, stage)
}
return result, rows.Err()
}
// ListLibraryJobs 返回某目标最近的作业(按创建时间倒序),供页面在重启后恢复展示。
func (s *Store) ListLibraryJobs(ctx context.Context, scope string, limit int) ([]governance.LibraryJob, error) {
if limit < 1 || limit > 50 {
return nil, errors.New("library job list limit out of range")
}
rows, err := s.db.Query(ctx, `SELECT id FROM library_jobs WHERE scope=$1 ORDER BY created_at DESC, id DESC LIMIT $2`, scope, limit)
if err != nil {
return nil, fmt.Errorf("list library jobs: %w", err)
}
defer rows.Close()
ids := make([]string, 0, limit)
for rows.Next() {
var id string
if err := rows.Scan(&id); err != nil {
return nil, fmt.Errorf("scan library job id: %w", err)
}
ids = append(ids, id)
}
if err := rows.Err(); err != nil {
return nil, err
}
result := make([]governance.LibraryJob, 0, len(ids))
for _, id := range ids {
job, err := s.LibraryJob(ctx, id)
if err != nil {
return nil, err
}
result = append(result, job)
}
return result, nil
}
// UpdateLibraryStage 只改调用方给了值的维度:nil 表示"这一维还没有可靠数据",
// 保持 NULL,绝不写成 0。
func (s *Store) UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error {
tag, err := s.db.Exec(ctx, `
UPDATE library_job_stages SET
state = CASE WHEN $3='' THEN state ELSE $3 END,
total = COALESCE($4, total),
completed = COALESCE($5, completed),
bytes_total = COALESCE($6, bytes_total),
bytes_done = COALESCE($7, bytes_done),
detail = CASE WHEN $8='' THEN detail ELSE $8 END,
updated_at = $9
WHERE job_id=$1 AND stage=$2`, jobID, stage, state, total, completed, bytesTotal, bytesDone, detail, now.UTC())
if err != nil {
return fmt.Errorf("update library stage: %w", err)
}
if tag.RowsAffected() != 1 {
return errors.New("library stage not found")
}
return nil
}
// AttachLibraryQueueJob 把队列作业号写到已建的业务作业上(两步创建,避免先入队后才发现互斥冲突)。
func (s *Store) AttachLibraryQueueJob(ctx context.Context, jobID, queueJobID string, now time.Time) error {
tag, err := s.db.Exec(ctx, `UPDATE library_jobs SET queue_job_id=$2, updated_at=$3 WHERE id=$1`, jobID, queueJobID, now.UTC())
if err != nil {
return fmt.Errorf("attach library queue job: %w", err)
}
if tag.RowsAffected() != 1 {
return errors.New("library job not found")
}
return nil
}
func (s *Store) CancelLibraryJob(ctx context.Context, jobID, reason string, now time.Time) error {
return s.AdvanceLibraryJob(ctx, jobID, governance.LibraryJobCancelled, "", reason, "", "", "", now)
}
func (s *Store) AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error {
finished := any(nil)
if state == governance.LibraryJobSucceeded || state == governance.LibraryJobFailed || state == governance.LibraryJobCancelled {
finished = now.UTC()
}
tag, err := s.db.Exec(ctx, `
UPDATE library_jobs SET
state=$2,
stage = CASE WHEN $3='' THEN stage ELSE $3 END,
error = CASE WHEN $4='' THEN error ELSE $4 END,
recovery = CASE WHEN $5='' THEN recovery ELSE $5 END,
snapshot_id = CASE WHEN $6='' THEN snapshot_id ELSE $6 END,
target_snapshot_id = CASE WHEN $7='' THEN target_snapshot_id ELSE $7 END,
updated_at=$8,
finished_at=COALESCE($9, finished_at)
WHERE id=$1`, jobID, string(state), stage, message, recovery, snapshotID, targetSnapshotID, now.UTC(), finished)
if err != nil {
return fmt.Errorf("advance library job: %w", err)
}
if tag.RowsAffected() != 1 {
return errors.New("library job not found")
}
return nil
}
// RecordLibraryVersion 写入一个版本记录。生产生效版本必须先把旧的 supersede 掉,
// 否则唯一索引会拒绝——这正是"不许两个生效版本并存"的保证。
func (s *Store) RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error {
evidence, err := json.Marshal(version.Evidence)
if err != nil {
return fmt.Errorf("encode library version evidence: %w", err)
}
tx, err := s.db.Begin(ctx)
if err != nil {
return fmt.Errorf("begin library version: %w", err)
}
defer func() { _ = tx.Rollback(ctx) }()
if version.Kind == governance.LibraryVersionProductionEffective {
if _, err := tx.Exec(ctx, `
UPDATE library_versions SET superseded_at=$2
WHERE scope=$1 AND kind='production_effective' AND superseded_at IS NULL`, version.Scope, version.CreatedAt.UTC()); err != nil {
return fmt.Errorf("supersede library version: %w", err)
}
}
if _, err := tx.Exec(ctx, `
INSERT INTO library_versions (id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at)
VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
ON CONFLICT (id) DO NOTHING`,
version.ID, version.Scope, string(version.Kind), version.SnapshotID, version.VersionLabel,
version.SourceJobID, evidence, version.CreatedBy, version.CreatedAt.UTC()); err != nil {
return fmt.Errorf("record library version: %w", err)
}
return tx.Commit(ctx)
}
func (s *Store) LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error) {
if limit < 1 || limit > 100 {
return nil, errors.New("library version limit out of range")
}
rows, err := s.db.Query(ctx, `
SELECT id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at, superseded_at
FROM library_versions WHERE scope=$1 ORDER BY created_at DESC, id DESC LIMIT $2`, scope, limit)
if err != nil {
return nil, fmt.Errorf("list library versions: %w", err)
}
defer rows.Close()
result := make([]governance.LibraryVersion, 0, limit)
for rows.Next() {
var item governance.LibraryVersion
var kind string
var evidence []byte
if err := rows.Scan(&item.ID, &item.Scope, &kind, &item.SnapshotID, &item.VersionLabel, &item.SourceJobID,
&evidence, &item.CreatedBy, &item.CreatedAt, &item.SupersededAt); err != nil {
return nil, fmt.Errorf("scan library version: %w", err)
}
item.Kind = governance.LibraryVersionKind(kind)
if len(evidence) > 0 {
_ = json.Unmarshal(evidence, &item.Evidence)
}
result = append(result, item)
}
return result, rows.Err()
}
@@ -0,0 +1,3 @@
DROP TABLE IF EXISTS library_job_stages;
DROP TABLE IF EXISTS library_jobs;
DROP TABLE IF EXISTS library_versions;
@@ -0,0 +1,57 @@
-- 整库版本与作业:把"测试封存 / 生产生效 / 生产预备份"三种版本与持久作业分开记录。
-- 现有 jobs 表是队列与租约;这里记录业务身份、阶段与结果,重启后仍可读。
CREATE TABLE library_versions (
id VARCHAR(64) PRIMARY KEY,
scope VARCHAR(16) NOT NULL CHECK (scope IN ('internal','external')),
kind VARCHAR(24) NOT NULL CHECK (kind IN ('test_sealed','production_effective','production_prebackup')),
snapshot_id VARCHAR(64) NOT NULL DEFAULT '',
version_label VARCHAR(64) NOT NULL DEFAULT '',
source_job_id VARCHAR(64) NOT NULL DEFAULT '',
evidence JSONB NOT NULL DEFAULT '{}'::jsonb,
created_by VARCHAR(128) NOT NULL DEFAULT '',
created_at TIMESTAMPTZ NOT NULL,
superseded_at TIMESTAMPTZ
);
CREATE INDEX library_versions_scope_kind ON library_versions(scope, kind, created_at DESC, id DESC);
-- 每个目标只有一个"当前生产生效版本";写入新版本时旧的必须先被 supersede。
CREATE UNIQUE INDEX library_versions_effective ON library_versions(scope)
WHERE kind = 'production_effective' AND superseded_at IS NULL;
CREATE TABLE library_jobs (
id VARCHAR(64) PRIMARY KEY,
scope VARCHAR(16) NOT NULL CHECK (scope IN ('internal','external')),
kind VARCHAR(16) NOT NULL CHECK (kind IN ('seal','sync')),
state VARCHAR(16) NOT NULL CHECK (state IN ('pending','running','succeeded','failed','cancelled')),
stage VARCHAR(32) NOT NULL DEFAULT '',
idempotency_key VARCHAR(255) NOT NULL,
request_digest VARCHAR(64) NOT NULL,
request JSONB NOT NULL DEFAULT '{}'::jsonb,
queue_job_id VARCHAR(64) NOT NULL DEFAULT '',
snapshot_id VARCHAR(64) NOT NULL DEFAULT '',
target_snapshot_id VARCHAR(64) NOT NULL DEFAULT '',
actor VARCHAR(128) NOT NULL DEFAULT '',
error TEXT NOT NULL DEFAULT '',
recovery VARCHAR(255) NOT NULL DEFAULT '',
created_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL,
finished_at TIMESTAMPTZ
);
CREATE UNIQUE INDEX library_jobs_idempotency ON library_jobs(idempotency_key);
-- 同一目标同一类作业只能有一个在飞:互斥由数据库保证,不依赖前端或单 worker 部署。
CREATE UNIQUE INDEX library_jobs_active ON library_jobs(scope, kind)
WHERE state IN ('pending','running');
CREATE INDEX library_jobs_recent ON library_jobs(scope, created_at DESC, id DESC);
CREATE TABLE library_job_stages (
job_id VARCHAR(64) NOT NULL REFERENCES library_jobs(id) ON DELETE CASCADE,
stage VARCHAR(32) NOT NULL,
state VARCHAR(16) NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','running','succeeded','failed','skipped')),
-- NULL 表示"总量未知":绝不能当成 0,也不据此算百分比。
total BIGINT,
completed BIGINT,
bytes_total BIGINT,
bytes_done BIGINT,
detail TEXT NOT NULL DEFAULT '',
updated_at TIMESTAMPTZ NOT NULL,
PRIMARY KEY (job_id, stage)
);
+98 -7
View File
@@ -1,7 +1,13 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, expect, it, vi } from 'vitest'
import { ReleaseTargetsView } from './ReleaseTargets'
import type { LibraryCaptureJob, LibrarySnapshot, LibrarySnapshotList } from './librarySnapshots'
import type {
LibraryCaptureJob,
LibraryJobRecord,
LibraryOverview,
LibrarySnapshot,
LibrarySnapshotList,
} from './librarySnapshots'
const internalSnapshot: LibrarySnapshot = {
snapshot_id: 'f992d64ea45bf737a0721a465b5aef2b150ef7757157eb84f3aaf8b6972d98f9',
@@ -67,11 +73,69 @@ const page: LibrarySnapshotList = {
capture_reason: '',
}
// 真实接口形状:生产段未知、闸口未开、没有持久作业。
const overview: LibraryOverview = {
scope: 'internal',
test_sealed: internalSnapshot,
production: { state: 'unknown', reason: '还没有生产验证通过的生效版本记录' },
prebackup: { state: 'unknown', reason: '本次目标快照还没有生产预备份' },
diff: {
state: 'unknown',
reason: '生产与测试的文档级差异读取未接线',
added: [],
updated: [],
removed: [],
},
jobs: [],
gate: {
sync_allowed: false,
reasons: [
'生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)',
'没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)',
'生产当前权威版本未知,不能启动写入',
'本次目标快照还没有生产预备份',
],
},
capture_available: true,
now: '2026-10-28T03:40:00Z',
}
const persistedSeal: LibraryJobRecord = {
id: 'libseal-lib-internal-20261028T033457',
scope: 'internal',
kind: 'seal',
state: 'running',
stage: 'export',
request_digest: 'd'.repeat(64),
queue_job_id: 'library-capture-internal-1',
snapshot_id: '',
target_snapshot_id: '',
actor: 'yaozhanghao',
error: '',
recovery: '',
created_at: '2026-10-28T03:34:50Z',
updated_at: '2026-10-28T03:34:55Z',
finished_at: null,
stages: [
{
stage: 'export',
state: 'running',
total: null,
completed: null,
bytes_total: null,
bytes_done: null,
detail: '主机侧正在暂停写入者、导出并恢复',
updated_at: '2026-10-28T03:34:55Z',
},
],
}
type ViewProps = Parameters<typeof ReleaseTargetsView>[0]
const base: ViewProps = {
page,
jobs: [],
overview,
loading: false,
error: null,
notice: null,
@@ -102,20 +166,41 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).not.toContain('对外知识库 · 尚无')
})
it('未接入项显示“未接入”,不用 0 / 无变化冒充', () => {
it('未接入项显示“未接入/未知”,不用 0 / 无变化冒充', () => {
const html = render()
expect(html).toContain('生产当前')
// 生产没有权威版本时必须写未知,不能拿测试快照顶替
expect(html).toContain('未知(尚未建立权威版本)')
expect(html).toContain('尚无记录 · 生产与测试的文档级差异读取未接线')
expect(html).toContain('未接入')
expect(html).toContain('尚无记录 · 变更清单来自生产与测试版本对比')
})
it('“启动同步”保持禁用并说明原因,不把封存当成同步', () => {
it('“启动同步”保持禁用并逐条说明缺项,不把封存当成同步', () => {
const html = render()
expect(html).toMatch(/<button[^>]*class="rel-primary"[^>]*disabled/)
expect(html).toContain('生产同步未接线')
expect(html).toContain('生产写入闸口关闭')
expect(html).toContain('没有已核验的生产恢复演练证据')
expect(html).toContain('本次目标快照还没有生产预备份')
expect(html).toContain('封存测试版本')
})
it('没有当前作业时不把历史封存当成阶段完成', () => {
const html = render()
// 阶段条第一段必须是 idle(○),"✓" 只允许出现在准备清单,不出现在阶段条
const stageBar = html.slice(html.indexOf('aria-label="作业阶段"'), html.indexOf('rel-steps-note'))
expect(stageBar).not.toContain('✓')
expect(stageBar).toContain('本次作业尚未开始')
expect(html).toContain('已有测试封存')
expect(html).toContain('没有当前作业证据时不会把历史封存当作阶段完成')
})
it('准备信息注明快照时间与范围,不声称实时测试库已就绪', () => {
const html = render()
expect(html).toContain('依据 10/28 11:34 封存的测试库全库快照,不代表实时测试库已就绪')
expect(html).toContain('同一份封存快照,不是实时 Wiki 队列状态')
expect(html).toContain('封存时的逐项校验和,重新封存才会更新')
})
it('版本与快照抽屉按 scope 列出全部历史并区分测试封存/不可直接恢复', () => {
const html = render({ drawerOpen: true, expandedSnapshot: internalSnapshot.snapshot_id })
expect(html).toContain('版本与快照')
@@ -135,8 +220,11 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
})
it('同步中布局显示四类数据卡与明细,且不编造百分比', () => {
const html = render({ jobs: [runningJob] })
expect(html).toContain('正在封存测试版本')
const html = render({
jobs: [runningJob],
overview: { ...overview, job: persistedSeal, jobs: [persistedSeal] },
})
expect(html).toContain('测试库封存作业')
expect(html).toContain('数据库 · 文档与分块')
expect(html).toContain('原文件 · 图片 · 附件')
expect(html).toContain('检索索引 · 向量')
@@ -146,6 +234,9 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html.match(/[1-9]\d*%/g) ?? []).toEqual(['100%'])
expect(html).toContain('文件传输 100% ≠ 作业完成')
expect(html).toContain('不编造百分比')
// 没有真实总量时只写"未知总量",不画百分比
expect(html).toContain('未知总量')
expect(html).toContain('主机侧正在暂停写入者、导出并恢复')
})
it('无权限时不给封存入口,未接线时说明通道状态', () => {
+386 -118
View File
@@ -2,12 +2,16 @@ import { useCallback, useEffect, useState } from 'react'
import {
enqueueLibraryCapture,
fetchLibraryCaptures,
fetchLibraryOverview,
fetchLibrarySnapshots,
formatBytes,
scopeLabel,
type LibraryCaptureJob,
type LibraryJobRecord,
type LibraryOverview,
type LibrarySnapshot,
type LibrarySnapshotList,
type LibraryStageRow,
} from './librarySnapshots'
import { useOptionalAuth } from './auth'
import './releaseTargets.css'
@@ -57,6 +61,10 @@ interface ScopeView {
history: LibrarySnapshot[]
activeJob?: LibraryCaptureJob
lastJob?: LibraryCaptureJob
// 持久作业与三类版本:来自 /api/v1/library/overview,重启后仍可读。
overview?: LibraryOverview | null
job?: LibraryJobRecord
syncJob?: LibraryJobRecord
}
interface ViewProps {
@@ -74,28 +82,44 @@ interface ViewProps {
pendingCapture: boolean
canCapture: boolean
canWrite: boolean
overview: LibraryOverview | null
now: number
onRefresh: () => void
onCapture: () => void
}
function scopeView(page: LibrarySnapshotList | null, jobs: LibraryCaptureJob[], scope: Scope): ScopeView {
function scopeView(
page: LibrarySnapshotList | null,
jobs: LibraryCaptureJob[],
scope: Scope,
overview: LibraryOverview | null,
): ScopeView {
const history = (page?.snapshots ?? []).filter((item) => item.scope === scope)
const scoped = jobs.filter((job) => job.scope === scope)
const persisted = overview?.jobs ?? []
const job =
overview?.job ?? persisted.find((item) => item.state === 'pending' || item.state === 'running') ?? persisted[0]
return {
scope,
snapshot: history[0],
history,
activeJob: scoped.find((job) => ACTIVE_STATES.includes(job.state)),
lastJob: scoped[0],
overview,
job,
syncJob: persisted.find((item) => item.kind === 'sync'),
}
}
const scopeName = (scope: Scope) => (scope === 'internal' ? '对内知识库' : '对外知识库')
function statusOf(view: ScopeView) {
if (view.activeJob) return { text: '封存中', tone: 'blue' as const }
if (view.snapshot) return { text: '已有封存', tone: 'green' as const }
const job = view.job
if (job && (job.state === 'running' || job.state === 'pending')) {
return { text: job.kind === 'seal' ? '封存中' : '同步中', tone: 'blue' as const }
}
if (view.overview?.production.state === 'known') return { text: '生产已记录版本', tone: 'green' as const }
if (view.overview?.test_sealed || view.snapshot) return { text: '已有封存', tone: 'green' as const }
return { text: '尚无封存', tone: 'gray' as const }
}
@@ -103,27 +127,110 @@ const jstate = (state?: string) =>
state === 'failed' ? '封存失败,可在版本与快照里查看原因' : state ? '封存已完成,生产段未接入' : '尚无作业'
// 五个阶段对应原稿:固定测试版本 → 备份生产 → 同步数据与 Wiki → 生产验证 → 新版本生效。
// 只有第一段有真实实现;其余按"未接入"显示,不画成进行中或已完成。
// 勾选只能来自**当前这次作业**的阶段证据;历史封存记录不代表本次作业推进过,
// 所以没有作业时全部是"本次作业尚未开始",不再把旧快照打勾。
function stageOf(job: LibraryJobRecord | undefined, name: string): LibraryStageRow | undefined {
return job?.stages.find((item) => item.stage === name)
}
function worstState(rows: LibraryStageRow[]): 'succeeded' | 'running' | 'failed' | 'pending' {
if (rows.some((row) => row.state === 'failed')) return 'failed'
if (rows.some((row) => row.state === 'running')) return 'running'
if (rows.length > 0 && rows.every((row) => row.state === 'succeeded' || row.state === 'skipped')) return 'succeeded'
return 'pending'
}
type StepState = 'done' | 'live' | 'fail' | 'idle'
function toState(value: 'succeeded' | 'running' | 'failed' | 'pending'): StepState {
return value === 'succeeded' ? 'done' : value === 'running' ? 'live' : value === 'failed' ? 'fail' : 'idle'
}
function jobStateText(job: LibraryJobRecord): string {
const map: Record<string, string> = {
pending: '排队中',
running: '执行中',
succeeded: '已完成',
failed: '失败',
cancelled: '已取消',
}
return map[job.state] ?? job.state
}
function StageBar({ view }: { view: ScopeView }) {
const sealed = Boolean(view.snapshot)
const capturing = Boolean(view.activeJob)
const stages = [
const job = view.job
const sealJob = job?.kind === 'seal' ? job : undefined
const syncJob = job?.kind === 'sync' ? job : undefined
let first: { state: StepState; hint: string }
if (sealJob) {
const exportStage = stageOf(sealJob, 'export')
first = {
state: toState(
sealJob.state === 'succeeded' ? 'succeeded' : sealJob.state === 'failed' ? 'failed' : 'running',
),
hint:
sealJob.state === 'succeeded'
? `本次作业已封存 ${stamp(sealJob.finished_at ?? exportStage?.updated_at ?? sealJob.updated_at)}`
: sealJob.state === 'running'
? '本次封存执行中'
: sealJob.state === 'pending'
? '已排队,等待 worker'
: '本次封存未完成',
}
} else if (syncJob) {
first = { state: 'done', hint: '已绑定的测试版本' }
} else {
first = { state: 'idle', hint: '本次作业尚未开始' }
}
const prebackup = syncJob ? stageOf(syncJob, 'prebackup') : undefined
const dataStages = syncJob
? ['database', 'resources', 'index', 'wiki']
.map((name) => stageOf(syncJob, name))
.filter((row): row is LibraryStageRow => Boolean(row))
: []
const verifyStage = syncJob ? stageOf(syncJob, 'verify') : undefined
const stages: { label: string; state: StepState; hint: string }[] = [
{ label: '固定测试版本', ...first },
{
label: '固定测试版本',
state: capturing ? 'live' : sealed ? 'done' : 'idle',
hint: capturing ? '封存执行中' : sealed ? `最近封存 ${stamp(view.snapshot!.created_at)}` : '尚未封存',
label: '备份生产',
state: prebackup ? toState(worstState([prebackup])) : 'idle',
hint: prebackup
? prebackup.state === 'succeeded'
? '已完成生产预备份'
: prebackup.state === 'running'
? '正在备份生产'
: prebackup.state === 'failed'
? '预备份失败'
: '未开始'
: '未接入',
},
{
label: '同步数据与 Wiki',
state: dataStages.length > 0 ? toState(worstState(dataStages)) : 'idle',
hint: dataStages.length > 0 ? '按数据库 / 资源 / 索引 / Wiki 分项上报' : '未接入',
},
{
label: '生产验证',
state: verifyStage ? toState(worstState([verifyStage])) : 'idle',
hint: verifyStage ? (verifyStage.state === 'succeeded' ? '校验通过' : '未完成') : '未接入',
},
{
label: '新版本生效',
state: syncJob && syncJob.state === 'succeeded' ? 'done' : 'idle',
hint: syncJob && syncJob.state === 'succeeded' ? '生产已生效' : '未接入',
},
{ label: '备份生产', state: 'idle', hint: '未接入' },
{ label: '同步数据与 Wiki', state: 'idle', hint: '未接入' },
{ label: '生产验证', state: 'idle', hint: '未接入' },
{ label: '新版本生效', state: 'idle', hint: '未接入' },
]
return (
<>
<ol className="rel-steps" aria-label="作业阶段">
{stages.map((stage, index) => (
<li key={stage.label} className={`rel-step ${stage.state}`}>
<span className="rel-step-mark">{stage.state === 'done' ? '✓' : stage.state === 'live' ? '●' : '○'}</span>
<span className="rel-step-mark">
{stage.state === 'done' ? '✓' : stage.state === 'live' ? '●' : stage.state === 'fail' ? '!' : '○'}
</span>
<strong>{stage.label}</strong>
<small>{stage.hint}</small>
{index < stages.length - 1 ? <span className="rel-step-arrow">→</span> : null}
@@ -131,15 +238,27 @@ function StageBar({ view }: { view: ScopeView }) {
))}
</ol>
<p className="rel-steps-note">
{capturing
? '封存是停写入者后的原子导出,没有分项进度上报;导出完成后才会出现新版本。'
: '运行时展开各类数据的数量、字节进度及 Wiki 快照进度;不把提交成功当作版本生效。'}
{job
? `作业 ${job.id} · ${job.kind === 'seal' ? '测试封存' : '生产同步'} · ${jobStateText(job)}${
job.error ? ` · ${job.error}` : ''
}`
: view.snapshot
? `已有测试封存 ${stamp(view.snapshot.created_at)}(历史记录),但本次作业尚未开始;没有当前作业证据时不会把历史封存当作阶段完成。`
: '本次作业尚未开始。'}
</p>
</>
)
}
function ChangeTable() {
function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) {
const computed = diff.state === 'computed'
const rows = computed
? [
...diff.added.map((item) => ({ action: '新增', item })),
...diff.updated.map((item) => ({ action: '更新', item })),
...diff.removed.map((item) => ({ action: '删除', item })),
]
: []
return (
<div className="rel-panel rel-changes">
<header className="rel-panel-head">
@@ -147,7 +266,7 @@ function ChangeTable() {
<h2>本次变更</h2>
<p>整库版本同步,不单独勾选文件</p>
</div>
<span className="rel-pill gray">未接入</span>
<span className={`rel-pill ${computed ? 'green' : 'gray'}`}>{computed ? `${rows.length} 条` : '未接入'}</span>
</header>
<table>
<thead>
@@ -157,34 +276,71 @@ function ChangeTable() {
</tr>
</thead>
<tbody>
<tr>
<td colSpan={2} className="rel-table-empty">
尚无记录 · 变更清单来自生产与测试版本对比,这项数据还没有接入
</td>
</tr>
{rows.length === 0 ? (
<tr>
<td colSpan={2} className="rel-table-empty">
{computed
? '生产与测试版本没有文档差异'
: `尚无记录 · ${diff.reason || '变更清单来自生产与测试版本对比,这项数据还没有接入'}`}
</td>
</tr>
) : (
rows.map((row, index) => (
<tr key={`${row.action}-${index}`}>
<td>{row.action}</td>
<td>{typeof row.item === 'string' ? row.item : JSON.stringify(row.item)}</td>
</tr>
))
)}
</tbody>
</table>
</div>
)
}
function ProtectionCard({ onOpen }: { onOpen: () => void }) {
function ProtectionCard({
production,
prebackup,
gate,
onOpen,
}: {
production: LibraryOverview['production']
prebackup: LibraryOverview['prebackup']
gate: LibraryOverview['gate']
onOpen: () => void
}) {
const backupKnown = prebackup.state === 'known' && prebackup.version
return (
<aside className="rel-panel rel-protection">
<header className="rel-panel-head">
<h2>生产保护与恢复</h2>
<span className="rel-pill gray">尚未创建</span>
<span className={`rel-pill ${backupKnown ? 'green' : 'gray'}`}>{backupKnown ? '已有预备份' : '尚未创建'}</span>
</header>
<dl>
<dt>本次同步前备份</dt>
<dd>未接入</dd>
<dd>
{backupKnown
? `${stamp(prebackup.version!.created_at)} · ${prebackup.version!.version_label || prebackup.version!.snapshot_id.slice(0, 12)}`
: '未接入(还没有与目标快照绑定的预备份)'}
</dd>
<dt>生产当前版本</dt>
<dd>未接入</dd>
<dd>
{production.state === 'known' && production.version
? production.version.version_label || production.version.snapshot_id.slice(0, 12)
: '未知(生产还没有权威版本记录)'}
</dd>
<dt>备份范围</dt>
<dd>数据库 / 资源 / 索引 / Wiki</dd>
<dt>恢复条件</dt>
<dd>备份完成后核验</dd>
<dd>{gate.reasons.length === 0 ? '已满足' : `缺 ${gate.reasons.length} 项`}</dd>
</dl>
{gate.reasons.length > 0 ? (
<ul className="rel-gate" aria-label="恢复与启动条件">
{gate.reasons.map((reason) => (
<li key={reason}>{reason}</li>
))}
</ul>
) : null}
<p className="rel-hint">同步启动后,这里显示本次生产恢复点及备份进度,可直接查看对应快照。</p>
<button type="button" className="rel-secondary" onClick={onOpen}>
查看已有版本与快照 ›
@@ -196,6 +352,10 @@ function ProtectionCard({ onOpen }: { onOpen: () => void }) {
interface ReadyProps {
view: ScopeView
diff: LibraryOverview['diff']
production: LibraryOverview['production']
prebackup: LibraryOverview['prebackup']
gate: LibraryOverview['gate']
canCapture: boolean
canWrite: boolean
pendingCapture: boolean
@@ -203,13 +363,24 @@ interface ReadyProps {
onOpen: () => void
}
function ReadyBody({ view, canCapture, canWrite, pendingCapture, onCapture, onOpen }: ReadyProps) {
function ReadyBody({
view,
diff,
production,
prebackup,
gate,
canCapture,
canWrite,
pendingCapture,
onCapture,
onOpen,
}: ReadyProps) {
const snapshot = view.snapshot
return (
<>
<div className="rel-grid">
<ChangeTable />
<ProtectionCard onOpen={onOpen} />
<ChangeTable diff={diff} />
<ProtectionCard production={production} prebackup={prebackup} gate={gate} onOpen={onOpen} />
</div>
<div className="rel-panel rel-jobbar">
<header className="rel-panel-head">
@@ -245,36 +416,67 @@ function ReadyBody({ view, canCapture, canWrite, pendingCapture, onCapture, onOp
}
function ProgressBody({ view, now, onOpen }: { view: ScopeView; now: number; onOpen: () => void }) {
const job = view.activeJob ?? view.lastJob
const running = Boolean(view.activeJob)
const job = view.job
const sealJob = job?.kind === 'seal' ? job : undefined
const syncJob = job?.kind === 'sync' ? job : undefined
const running = job?.state === 'running' || job?.state === 'pending'
const stage = (name: string) => syncJob?.stages.find((item) => item.stage === name)
const cards = [
{ title: '数据库 · 文档与分块', note: '封存导出为原子操作,尚无分项上报' },
{ title: '原文件 · 图片 · 附件', note: '封存导出为原子操作,尚无分项上报' },
{ title: '检索索引 · 向量', note: '复用测试端产物;生产不重新解析(未接入)' },
{ title: 'Wiki · 完整快照', note: 'Wiki 随整库快照导出;生产写入未接入' },
]
{ title: '数据库 · 文档与分块', row: stage('database'), axis: '文档 / 分块' },
{ title: '原文件 · 图片 · 附件', row: stage('resources'), axis: '对象 / 字节' },
{ title: '检索索引 · 向量', row: stage('index'), axis: '索引文档' },
{ title: 'Wiki · 完整快照', row: stage('wiki'), axis: 'Wiki 页' },
].map((card) => ({
...card,
// 只有真实的 total 才画进度;没有 total 就是"未知总量",绝不按 0 或 100% 画。
percent:
card.row && card.row.total && card.row.total > 0
? Math.min(100, Math.round(((card.row.completed ?? 0) / card.row.total) * 100))
: null,
count:
card.row && card.row.total != null
? `${card.row.completed ?? '—'} / ${card.row.total}`
: '— / 未知总量',
}))
return (
<>
<div className="rel-panel rel-progress-head">
<div className="rel-between">
<h2>
正在封存测试版本
{sealJob ? '测试库封存作业' : syncJob ? '生产同步作业' : '本次作业'}
<span className="rel-version">
当前 <b>{view.snapshot ? view.snapshot.snapshot_id.slice(0, 12) : '未接入'}</b> → 目标{' '}
<b>本次封存产物</b>
测试封存 <b>{view.overview?.test_sealed?.snapshot_id.slice(0, 12) ?? '未接入'}</b> → 生产当前{' '}
<b>
{view.overview?.production.state === 'known' && view.overview.production.version
? view.overview.production.version.version_label ||
view.overview.production.version.snapshot_id.slice(0, 12)
: '未知'}
</b>
</span>
</h2>
<span className={`rel-pill ${running ? 'blue' : job?.state === 'failed' ? 'red' : 'green'}`}>
{job ? `${jobStateLabel[job.state] ?? job.state} · 已用时 ${elapsed(job.created_at, now)}` : '无作业'}
<span className={`rel-pill ${running ? 'blue' : job?.state === 'failed' ? 'red' : job ? 'green' : 'gray'}`}>
{job ? `${jobStateText(job)} · 已用时 ${elapsed(job.created_at, now)}` : '无作业'}
</span>
</div>
<p className="rel-jobmeta">
作业 <code>{job?.capture_job ?? '未接入'}</code> · 操作人 {job?.requested_by || '—'} · 最近进展{' '}
{job ? stamp(job.updated_at) : '—'}
作业 <code>{job?.id ?? '未接入'}</code> · 类型 {job ? (job.kind === 'seal' ? '测试封存' : '生产同步') : '—'} ·
操作人 {job?.actor || '—'} · 最近进展 {job ? stamp(job.updated_at) : '—'}
{job?.recovery ? ` · 恢复:${job.recovery}` : ''}
</p>
<StageBar view={view} />
<div className="rel-between rel-progress-foot">
<span>当前:{running ? '导出数据库、索引、对象与 Wiki 快照' : jstate(job?.state)}</span>
<span>
当前:
{job?.state === 'running'
? job.stage || '执行中'
: job?.state === 'failed'
? job.error || '失败'
: job
? jobStateText(job)
: '本次作业尚未开始'}
</span>
<button type="button" className="rel-link" onClick={onOpen}>
查看版本与快照 ↗
</button>
@@ -291,15 +493,31 @@ function ProgressBody({ view, now, onOpen }: { view: ScopeView; now: number; onO
<article key={card.title} className="rel-datacard">
<header>
<h3>{card.title}</h3>
<span className="rel-pill gray">未接入</span>
<span className={`rel-pill ${card.row?.state === 'succeeded' ? 'green' : card.row?.state === 'failed' ? 'red' : card.row?.state === 'running' ? 'blue' : 'gray'}`}>
{card.row
? card.row.state === 'succeeded'
? '已完成'
: card.row.state === 'running'
? '执行中'
: card.row.state === 'failed'
? '失败'
: '等待'
: '未接入'}
</span>
</header>
<p className="rel-datacount">
<strong>—</strong> / 未接入
<strong>{card.count}</strong> · {card.axis}
</p>
<div className="rel-progress" aria-hidden="true">
<span style={{ width: '0%' }} />
<div className="rel-progress" aria-hidden={card.percent === null ? 'true' : undefined}>
<span style={{ width: `${card.percent ?? 0}%` }} />
</div>
<p className="rel-datadetail">{card.note}</p>
<p className="rel-datadetail">
{card.row?.detail
? card.row.detail
: syncJob
? '该分项还没有上报数据'
: '生产同步执行链未接通,分项不会产生数据'}
</p>
</article>
))}
</div>
@@ -308,67 +526,63 @@ function ProgressBody({ view, now, onOpen }: { view: ScopeView; now: number; onO
<div className="rel-panel rel-details">
<header className="rel-panel-head">
<h2>同步明细</h2>
<div className="rel-filters">
<button type="button" className="chosen">
全部
</button>
<button type="button">正在执行</button>
<button type="button">失败</button>
</div>
<span className="rel-hint">行来自持久作业阶段,worker 重启后仍可读</span>
</header>
<table>
<thead>
<tr>
<th>任务 / 对象</th>
<th>数据类型</th>
<th>阶段</th>
<th>进度</th>
<th>状态</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>测试库封存 {job ? job.capture_job : ''}</td>
<td>数据库 / 资源 / 索引 / Wiki</td>
<td>{job ? jobStateLabel[job.state] : '—'}</td>
<td>{running ? '执行中' : job?.state === 'failed' ? '失败' : job ? '已完成' : '未接入'}</td>
<td>
{job?.last_error ? job.last_error : running ? '导出完成前无分项数据' : '封存结束后恢复测试写入者'}
</td>
</tr>
<tr>
<td>生产恢复备份</td>
<td>数据库 / 资源 / 索引 / Wiki</td>
<td>未接入</td>
<td>未接入</td>
<td>生产预备份还没有接线</td>
</tr>
<tr>
<td>本次变更文档</td>
<td>文档 / 分块 / 资源关联</td>
<td>未接入</td>
<td>未接入</td>
<td>差异清单还没有接入</td>
</tr>
<tr>
<td>生产 Wiki 快照</td>
<td>Wiki 页面 / 关联数据</td>
<td>未接入</td>
<td>未接入</td>
<td>生产不重新生成 Wiki;写入未接线</td>
</tr>
{(job?.stages ?? []).length === 0 ? (
<tr>
<td colSpan={5} className="rel-table-empty">
尚无阶段记录
</td>
</tr>
) : (
job!.stages.map((row) => (
<tr key={row.stage}>
<td>{row.stage}</td>
<td>{row.stage === 'export' ? '测试封存' : row.stage}</td>
<td>
{row.total != null ? `${row.completed ?? '—'} / ${row.total}` : '未知总量'}
{row.bytes_total != null ? ` · ${formatBytes(row.bytes_done ?? 0)} / ${formatBytes(row.bytes_total)}` : ''}
</td>
<td>
{row.state === 'succeeded'
? '已完成'
: row.state === 'running'
? '执行中'
: row.state === 'failed'
? '失败'
: row.state === 'skipped'
? '已跳过'
: '等待'}
</td>
<td>{row.detail || '—'}</td>
</tr>
))
)}
</tbody>
</table>
<footer className="rel-log">
<span>
最近事件:
{job?.last_error
? `封存作业报错(${job.last_error.slice(0, 60)})`
{job?.error
? job.error.slice(0, 120)
: running
? '封存作业执行中;无错误。'
? '作业执行中;无错误。'
: job
? '封存作业已结束;无错误。'
: '尚无作业记录。'}
? `作业${jobStateText(job)};无错误。`
: sealJob
? '封存作业已结束。'
: '尚无作业记录。'}
</span>
<span>文件传输 100% ≠ 作业完成;生产验证通过前不显示“完成”。</span>
</footer>
@@ -559,13 +773,26 @@ function Drawer({ view, page, now, open, expanded, onExpand, onClose, canCapture
export function ReleaseTargetsView(props: ViewProps) {
const {
page, jobs, loading, error, notice, scope, onScope, drawerOpen, onDrawer, expandedSnapshot, onExpandSnapshot,
pendingCapture, canCapture, canWrite, now, onRefresh, onCapture,
page, jobs, overview, loading, error, notice, scope, onScope, drawerOpen, onDrawer, expandedSnapshot,
onExpandSnapshot, pendingCapture, canCapture, canWrite, now, onRefresh, onCapture,
} = props
const internal = scopeView(page, jobs, 'internal')
const external = scopeView(page, jobs, 'external')
const internal = scopeView(page, jobs, 'internal', overview?.scope === 'internal' ? overview : null)
const external = scopeView(page, jobs, 'external', overview?.scope === 'external' ? overview : null)
const view = scope === 'internal' ? internal : external
const active = Boolean(view.activeJob)
const active =
Boolean(view.activeJob) || view.job?.state === 'running' || view.job?.state === 'pending'
// 三类版本严格分开:target 是测试封存,production 是生产权威版本,prebackup 是本次预备份。
const target = view.overview?.test_sealed
const production = view.overview?.production ?? { state: 'unknown' as const }
const prebackup = view.overview?.prebackup ?? { state: 'unknown' as const }
const diff = view.overview?.diff ?? {
state: 'unknown' as const,
reason: '生产与测试的文档级差异读取未接线',
added: [],
updated: [],
removed: [],
}
const gate = view.overview?.gate ?? { sync_allowed: false, reasons: ['整库状态接口不可用'] }
return (
<section className="release-targets" aria-label="发布管理">
@@ -630,50 +857,79 @@ export function ReleaseTargetsView(props: ViewProps) {
<button
type="button"
className="rel-primary"
disabled
title="生产同步未接线:没有生产预备份、生产授权与同步协调器,点击不会写入生产"
disabled={!gate.sync_allowed}
title={
gate.sync_allowed
? '生产同步执行链尚未接线,按钮不会启用'
: `暂不能启动同步:${gate.reasons.join(';')}`
}
>
▶ 启动同步
</button>
</div>
</div>
<p className="rel-versionline">
生产当前 <b className="rel-unknown">未接入</b> → 拟发布{' '}
<b>{view.snapshot ? `封存 ${view.snapshot.snapshot_id.slice(0, 12)}` : '未接入'}</b> · 尚未启动,不修改生产
生产当前{' '}
{production.state === 'known' && production.version ? (
<b>{production.version.version_label || `生效 ${production.version.snapshot_id.slice(0, 12)}`}</b>
) : (
<b className="rel-unknown">未知(尚未建立权威版本)</b>
)}{' '}
→ 拟发布{' '}
<b>{target ? `封存 ${target.snapshot_id.slice(0, 12)} · ${stamp(target.created_at)}` : '还没有测试封存'}</b> ·
尚未启动,不修改生产
</p>
<dl className="rel-metrics">
<div>
<dt>新增文档</dt>
<dd className="rel-unknown">未接入</dd>
<dd className={diff.state === 'computed' ? '' : 'rel-unknown'}>
{diff.state === 'computed' ? diff.added.length : '未接入'}
</dd>
</div>
<div>
<dt>更新文档</dt>
<dd className="rel-unknown">未接入</dd>
<dd className={diff.state === 'computed' ? '' : 'rel-unknown'}>
{diff.state === 'computed' ? diff.updated.length : '未接入'}
</dd>
</div>
<div>
<dt>删除文档</dt>
<dd className="rel-unknown">未接入</dd>
<dd className={diff.state === 'computed' ? '' : 'rel-unknown'}>
{diff.state === 'computed' ? diff.removed.length : '未接入'}
</dd>
</div>
<div>
<dt>Wiki 发布方式</dt>
<dd>{view.snapshot ? '完整快照' : '未接入'}</dd>
<dd>{target ? '完整快照' : '未接入'}</dd>
</div>
</dl>
<ul className="rel-checklist">
<li className={view.snapshot ? 'ok' : 'unknown'}>
{view.snapshot
? `✓ 文档解析与索引完整(${view.snapshot.totals.chunks ?? 0} 分块 / ${view.snapshot.totals.index_documents ?? 0} 索引)`
<li className={target ? 'ok' : 'unknown'}>
{target
? `✓ 文档解析与索引完整(${target.totals.chunks ?? 0} 分块 / ${target.totals.index_documents ?? 0} 索引)`
: '○ 文档解析与索引:未接入'}
{target ? <em className="rel-scope">依据 {stamp(target.created_at)} 封存的测试库全库快照,不代表实时测试库已就绪</em> : null}
</li>
<li className={view.snapshot ? 'ok' : 'unknown'}>
{view.snapshot ? `✓ Wiki 快照完整(${view.snapshot.totals.wiki_pages ?? 0} 页)` : '○ Wiki 快照:未接入'}
<li className={target ? 'ok' : 'unknown'}>
{target ? `✓ Wiki 快照完整(${target.totals.wiki_pages ?? 0} 页)` : '○ Wiki 快照:未接入'}
{target ? <em className="rel-scope">同一份封存快照,不是实时 Wiki 队列状态</em> : null}
</li>
<li className={view.snapshot ? 'ok' : 'unknown'}>
{view.snapshot ? `✓ 数据完整性:${view.snapshot.parts.length} 项摘要逐项一致` : '○ 数据完整性:尚无封存可核验'}
<li className={target ? 'ok' : 'unknown'}>
{target
? `✓ 数据完整性:${target.parts.length} 项摘要逐项一致`
: '○ 数据完整性:尚无封存可核验'}
{target ? <em className="rel-scope">封存时的逐项校验和,重新封存才会更新</em> : null}
</li>
</ul>
{gate.reasons.length > 0 ? (
<ul className="rel-gate" aria-label="启动同步的缺项">
{gate.reasons.map((reason) => (
<li key={reason}>{reason}</li>
))}
</ul>
) : null}
<p className="rel-footnote">
启动后先固定测试版本,再备份生产。备份失败或恢复条件不满足,不进入生产写入。启动同步这一步当前未接线。
启动后先固定测试版本,再备份生产。备份失败或恢复条件不满足,不进入生产写入。
</p>
</div>
@@ -682,6 +938,10 @@ export function ReleaseTargetsView(props: ViewProps) {
) : (
<ReadyBody
view={view}
diff={diff}
production={production}
prebackup={prebackup}
gate={gate}
canCapture={canCapture}
canWrite={canWrite}
pendingCapture={pendingCapture}
@@ -710,6 +970,10 @@ export function ReleaseTargets() {
const auth = useOptionalAuth()
const [page, setPage] = useState<LibrarySnapshotList | null>(null)
const [jobs, setJobs] = useState<LibraryCaptureJob[]>([])
const [overviews, setOverviews] = useState<Record<Scope, LibraryOverview | null>>({
internal: null,
external: null,
})
const [loading, setLoading] = useState(true)
const [error, setError] = useState<string | null>(null)
const [notice, setNotice] = useState<string | null>(null)
@@ -722,12 +986,15 @@ export function ReleaseTargets() {
const load = useCallback(async (signal?: AbortSignal) => {
setLoading(true)
try {
const [snapshots, captures] = await Promise.all([
const [snapshots, captures, internalOverview, externalOverview] = await Promise.all([
fetchLibrarySnapshots(signal),
fetchLibraryCaptures(signal),
fetchLibraryOverview('internal', signal),
fetchLibraryOverview('external', signal),
])
setPage(snapshots)
setJobs(captures)
setOverviews({ internal: internalOverview, external: externalOverview })
setNow(Date.now())
setError(null)
} catch (loadError) {
@@ -780,6 +1047,7 @@ export function ReleaseTargets() {
<ReleaseTargetsView
page={page}
jobs={jobs}
overview={overviews[scope]}
loading={loading}
error={error}
notice={notice}
+87 -1
View File
@@ -221,4 +221,90 @@ export function scopeLabel(scope: string): string {
if (scope === 'internal') return '对内'
if (scope === 'external') return '对外'
return scope || '未知范围'
}
}
// ---- 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业 ----
export interface LibraryVersionRecord {
id: string
kind: 'test_sealed' | 'production_effective' | 'production_prebackup'
snapshot_id: string
version_label: string
source_job_id: string
evidence: Record<string, unknown>
created_by: string
created_at: string
superseded_at?: string | null
}
export interface LibraryKnown {
state: 'known' | 'unknown'
version?: LibraryVersionRecord
reason?: string
}
export interface LibraryDiff {
state: 'unknown' | 'computed'
reason?: string
added: unknown[]
updated: unknown[]
removed: unknown[]
}
export interface LibraryStageRow {
stage: string
state: string
total: number | null
completed: number | null
bytes_total: number | null
bytes_done: number | null
detail: string
updated_at: string
}
export interface LibraryJobRecord {
id: string
scope: string
kind: 'seal' | 'sync'
state: 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
stage: string
request_digest: string
queue_job_id: string
snapshot_id: string
target_snapshot_id: string
actor: string
error: string
recovery: string
created_at: string
updated_at: string
finished_at?: string | null
stages: LibraryStageRow[]
}
export interface LibraryGate {
sync_allowed: boolean
reasons: string[]
}
export interface LibraryOverview {
scope: string
test_sealed?: LibrarySnapshot
test_sealed_reason?: string
production: LibraryKnown
prebackup: LibraryKnown
diff: LibraryDiff
job?: LibraryJobRecord
jobs: LibraryJobRecord[]
gate: LibraryGate
capture_available: boolean
capture_reason?: string
now: string
}
export async function fetchLibraryOverview(scope: string, signal?: AbortSignal): Promise<LibraryOverview | null> {
const response = await fetch(`/api/v1/library/overview?scope=${encodeURIComponent(scope)}`, {
headers: { Accept: 'application/json' },
signal,
})
const value = (await response.json().catch(() => null)) as unknown
if (!record(value)) return null
return value as unknown as LibraryOverview
}