knowledge-governance/internal/httpapi/library_capture.go

package httpapi

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"regexp"
	"strings"
	"time"

	"knowledge-governance/internal/governance"
	"knowledge-governance/internal/jobs"
)

// 页面发起封存：只投递一个作业，真正的停机/导出/恢复发生在主机侧 agent。
// 这里没有任何 Docker 访问，也没有来源凭据 —— 调用方只能选择范围与作业号。
const libraryCaptureJobType = "library.capture"

var libraryCaptureJobPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)

type libraryCaptureRequest struct {
	Scope string `json:"scope"`
	Job   string `json:"job"`
}

func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
	if config.LibraryAgentSocket == "" {
		writeJSON(w, http.StatusServiceUnavailable, map[string]any{
			"code":   "library_capture_unwired",
			"reason": "未接线：主机侧封存 agent 没有挂载，页面无法发起封存",
		})
		return
	}
	var request libraryCaptureRequest
	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
	}
	// The job id is the idempotency key handed to the agent: repeating the same
	// scope+job returns the already sealed version instead of sealing twice.
	captureJob := strings.TrimSpace(request.Job)
	if captureJob == "" {
		captureJob = "lib-" + request.Scope + "-" + time.Now().UTC().Format("20060102T150405")
	}
	if !libraryCaptureJobPattern.MatchString(captureJob) {
		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid job id"})
		return
	}
	requestedBy := ""
	if identity, ok := sessionFrom(r.Context()); ok {
		requestedBy = identity.Username
	}
	payload, err := json.Marshal(map[string]string{
		"scope": request.Scope, "capture_job": captureJob, "requested_by": requestedBy,
	})
	if err != nil {
		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot build capture job"})
		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
	// second job instead of reporting a conflicting request, so the conflict is
	// detected by comparing the stored payload below.
	job, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{
		ID:             requestedID,
		Type:           libraryCaptureJobType,
		Payload:        payload,
		AvailableAt:    now,
		MaxAttempts:    2,
		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.
	var stored struct {
		Scope       string `json:"scope"`
		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,
		})
		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,
		})
		return
	}
	writeJSON(w, http.StatusAccepted, map[string]any{
		"job_id": job.ID, "capture_job": stored.CaptureJob, "scope": stored.Scope,
		"state": job.State, "reused": job.ID != requestedID, "requested_by": stored.RequestedBy,
	})
}

// libraryCaptureJobs lists recent capture jobs so the page can show real state
// instead of an optimistic spinner. It reads the queue, not the archive.
func libraryCaptureJobs(w http.ResponseWriter, r *http.Request, config Config) {
	// Ask the store for this type only. Reading the global queue and filtering in
	// the handler would hide capture jobs behind unrelated traffic and make the
	// page claim "idle" while a capture is still queued.
	byType, ok := config.Store.(interface {
		ListByType(ctx context.Context, jobType string, limit int) ([]jobs.Job, error)
	})
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"available": false,
			"reason": "任务存储不支持按类型查询，页面不会据此判断空闲", "jobs": []any{}})
		return
	}
	queue, err := byType.ListByType(r.Context(), libraryCaptureJobType, 20)
	if err != nil {
		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read capture jobs"})
		return
	}
	views := make([]map[string]any, 0, len(queue))
	for _, job := range queue {
		var payload struct {
			Scope       string `json:"scope"`
			CaptureJob  string `json:"capture_job"`
			RequestedBy string `json:"requested_by"`
		}
		_ = json.Unmarshal(job.Payload, &payload)
		views = append(views, map[string]any{"job_id": job.ID, "capture_job": payload.CaptureJob,
			"scope": payload.Scope, "state": job.State, "attempt": job.Attempt,
			"last_error": job.LastError, "requested_by": payload.RequestedBy,
			"created_at": job.CreatedAt, "updated_at": job.UpdatedAt})
	}
	writeJSON(w, http.StatusOK, map[string]any{"available": true, "jobs": views})
}