knowledge-governance/internal/httpapi/library_storage.go

package httpapi

import (
	"context"
	"net/http"
	"sort"
	"strings"
	"time"

	"knowledge-governance/internal/governance"
	"knowledge-governance/internal/libraryretention"
	"knowledge-governance/internal/librarysnapshot"
)

// 存储管理接口：容量、保留策略、依赖保护与清理预览。
//
// 全部只读：没有删除动作，自动清理恒为关闭。候选版本只是"按策略如果清理会考虑这些"，
// 受保护版本（生产生效、每库最近封存、每次生产预备份、在飞作业引用）永不进入候选。
type storageVersionView struct {
	ID             string    `json:"id"`
	Kind           string    `json:"kind"`
	Scope          string    `json:"scope"`
	CreatedAt      time.Time `json:"created_at"`
	Protected      bool      `json:"protected"`
	ProtectedBy    []string  `json:"protected_by,omitempty"`
	ExclusiveBytes int64     `json:"exclusive_bytes"`
	SharedBytes    int64     `json:"shared_bytes"`
}

type libraryStorageResponse struct {
	Available          bool                      `json:"available"`
	Reason             string                    `json:"reason,omitempty"`
	ArchiveRoot        string                    `json:"archive_root,omitempty"`
	Versions           []storageVersionView      `json:"versions"`
	ContentBytes       int64                     `json:"content_bytes"`
	BlobFileBytes      int64                     `json:"blob_file_bytes"`
	BlobAllocatedBytes int64                     `json:"blob_allocated_bytes"`
	UnreferencedBlobs  int                       `json:"unreferenced_blobs"`
	UnreferencedBytes  int64                     `json:"unreferenced_bytes"`
	ManifestFileBytes  int64                     `json:"manifest_file_bytes"`
	Policy             libraryretention.Policy   `json:"policy"`
	Plan               *libraryretention.Plan    `json:"plan,omitempty"`
	Capacity           libraryretention.Capacity `json:"capacity"`
	AutomaticCleanup   bool                      `json:"automatic_cleanup"`
	Notes              []string                  `json:"notes"`
	// 容量/保留计数是清单级口径：真实去重、每次重算，但"被引用字节是否完好"
	// 只在实际执行（同步/恢复）时逐部件复核，这两件事不能混成一句"已验证"。
	Verification     string `json:"verification"`
	VerificationNote string `json:"verification_note"`
}

func libraryStorageHandler(w http.ResponseWriter, r *http.Request, config Config) {
	response := libraryStorageResponse{Versions: []storageVersionView{}, Notes: []string{}, AutomaticCleanup: false,
		Policy:       libraryretention.Policy{KeepVersions: int(config.LibraryRetentionVersions), KeepDays: int(config.LibraryRetentionDays)},
		Verification: libraryVerificationManifest, VerificationNote: libraryVerificationNote}
	if strings.TrimSpace(config.LibraryArchiveRoot) == "" {
		response.Reason = "未接线：LIBRARY_ARCHIVE_ROOT 未配置，没有可统计的归档"
		writeJSON(w, http.StatusServiceUnavailable, response)
		return
	}
	archive, err := librarysnapshot.Open(config.LibraryArchiveRoot, 256*1024*1024)
	if err != nil {
		response.Reason = "归档根不可用"
		writeJSON(w, http.StatusServiceUnavailable, response)
		return
	}
	defer archive.Close()
	total, err := archive.ContentUsage()
	if err != nil {
		response.Reason = "归档用量不可读"
		writeJSON(w, http.StatusServiceUnavailable, response)
		return
	}
	response.Available = true
	response.ArchiveRoot = config.LibraryArchiveRoot
	response.ContentBytes = total.ContentBytes
	response.BlobFileBytes = total.BlobFileBytes
	response.BlobAllocatedBytes = total.BlobAllocatedBytes
	response.UnreferencedBlobs = total.UnreferencedBlobs
	response.UnreferencedBytes = total.UnreferencedBytes
	response.ManifestFileBytes = total.ManifestFileBytes

	usage, err := archive.UsageFromManifests()
	if err != nil {
		response.Reason = "归档逐版本用量不可读"
		writeJSON(w, http.StatusServiceUnavailable, response)
		return
	}
	usageByID := map[string]librarysnapshot.Usage{}
	ids := make([]string, 0, len(usage))
	for _, item := range usage {
		usageByID[item.VersionID] = item
		ids = append(ids, item.VersionID)
	}
	sort.Strings(ids)

	// 版本类型与保护依据来自持久登记与在飞作业，不靠文件时间猜。
	kinds := map[string]governance.LibraryVersion{}
	protectedBy := map[string][]string{}
	protectionUnknown := false
	store, storeOK := libraryStore(config)
	if storeOK {
		// 类型与保护依据只认**持久登记**的精确查询：分页窗口（最近 100 个版本/20 个作业）
		// 一旦被历史挤满，需要恢复的旧预备份与 failed-but-held 作业就会被读成"可删除候选"（F10）。
		for _, scope := range []string{"internal", "external"} {
			versions, listErr := store.LibraryVersions(r.Context(), scope, 100)
			if listErr != nil {
				protectionUnknown = true
				continue
			}
			for _, item := range versions {
				kinds[item.SnapshotID] = item
			}
			if current, found, currentErr := store.LibraryCurrentVersion(r.Context(), scope); currentErr == nil && found {
				if _, seen := kinds[current.SnapshotID]; !seen {
					kinds[current.SnapshotID] = current
				}
			} else if currentErr != nil {
				protectionUnknown = true
			}
		}
		if protector, ok := config.Store.(interface {
			LibraryProtection(ctx context.Context) (map[string][]string, error)
		}); ok {
			if reasons, protectErr := protector.LibraryProtection(r.Context()); protectErr == nil {
				for snapshot, items := range reasons {
					for _, reason := range items {
						protectedBy[snapshot] = appendUnique(protectedBy[snapshot], reason)
					}
				}
			} else {
				protectionUnknown = true
				response.Notes = append(response.Notes, "保护依据读取失败（"+protectErr.Error()+"）：本次不生成可删除候选")
			}
		} else {
			protectionUnknown = true
			response.Notes = append(response.Notes, "存储不支持全量保护查询：本次不生成可删除候选")
		}
	} else {
		protectionUnknown = true
		response.Notes = append(response.Notes, "版本登记存储不可用：只按归档文件统计，无法识别受保护版本")
	}

	versions := make([]libraryretention.Version, 0, len(ids))
	latestSealed := map[string]time.Time{}
	var requiredBytes int64
	// 版本元数据走清单级读取：这里只做容量/保留盘点，不执行任何版本。
	// 需要动某个版本时（同步/恢复）仍然整版复核字节。
	manifests, err := libraryManifests(r.Context(), archive, ids)
	if err != nil {
		status, reason := libraryArchiveErrorStatus(err, "归档清单不可读")
		response.Reason = reason
		writeJSON(w, status, response)
		return
	}
	for index, id := range ids {
		manifest := manifests[index]
		// 备份类型只能来自显式登记：非空 ValidationPolicy 也被生产预备份使用，
		// 拿它猜类型会把生产预备份显示成测试封存（F10）。
		kind := "unregistered"
		if record, ok := kinds[id]; ok {
			kind = string(record.Kind)
		}
		if kind == "test_sealed" {
			// 每库最近一次封存受保护：它是最新可发布的测试版本。
			if current, seen := latestSealed[manifest.Scope]; !seen || manifest.CreatedAt.After(current) {
				latestSealed[manifest.Scope] = manifest.CreatedAt
			}
		}
		item := usageByID[id]
		view := storageVersionView{ID: id, Kind: kind, Scope: manifest.Scope, CreatedAt: manifest.CreatedAt,
			ExclusiveBytes: item.ExclusiveBytes, SharedBytes: item.SharedBytes}
		versions = append(versions, libraryretention.Version{ID: id, Kind: kind, CreatedAt: manifest.CreatedAt,
			ExclusiveBytes: item.ExclusiveBytes, SharedBytes: item.SharedBytes})
		response.Versions = append(response.Versions, view)
	}
	// 用与上面相同的清单再定位一次最新测试封存，避免把时间映射回 ID 时出错。
	for index, id := range ids {
		manifest := manifests[index]
		if kindOf := kinds[id].Kind; kindOf == governance.LibraryVersionTestSealed {
			if manifest.CreatedAt.Equal(latestSealed[manifest.Scope]) {
				protectedBy[id] = appendUnique(protectedBy[id], "最近测试封存（"+manifest.Scope+"）")
			}
		}
	}

	if protectionUnknown {
		// 保护依据未知 ⇒ 不许产出"可删除候选"：不确定的东西不能按可删处理（fail closed）。
		for index := range versions {
			protectedBy[versions[index].ID] = appendUnique(protectedBy[versions[index].ID], "保护依据未知（拒绝生成可删候选）")
		}
	}
	for index := range versions {
		if reasons := protectedBy[versions[index].ID]; len(reasons) > 0 {
			versions[index].Protected = true
			versions[index].ProtectedBy = reasons
		}
	}
	for index := range response.Versions {
		if reasons := protectedBy[response.Versions[index].ID]; len(reasons) > 0 {
			response.Versions[index].Protected = true
			response.Versions[index].ProtectedBy = reasons
		}
	}

	now := time.Now().UTC()
	plan := libraryretention.Build(versions, total.ContentBytes, response.Policy, now)
	response.Plan = &plan
	response.Notes = append(response.Notes, "候选版本只是清理预览；共享 blob 不会因删除单个版本释放")
	response.Notes = append(response.Notes, "自动清理关闭，页面不提供删除动作；实际回收需要单独授权")
	if !plan.PolicyConfigured {
		response.Notes = append(response.Notes, "保留数量/天数未设置（LIBRARY_RETENTION_VERSIONS / LIBRARY_RETENTION_DAYS）")
	}

	for index := range response.Versions {
		item := response.Versions[index]
		if item.Kind == "test_sealed" && item.CreatedAt.Equal(latestSealed[item.Scope]) {
			requiredBytes = item.ExclusiveBytes + item.SharedBytes
			break
		}
	}
	response.Capacity = libraryretention.CheckCapacity(total.ContentBytes, requiredBytes, config.LibraryCapacityBudgetBytes)
	writeJSON(w, http.StatusOK, response)
}

// appendUnique 只追加还没出现过的标签：同一条版本可能同时被展示窗口与精确查询命中，
// 重复标签会让"保护依据"看起来像两条不同理由。
func appendUnique(labels []string, value string) []string {
	for _, item := range labels {
		if item == value {
			return labels
		}
	}
	return append(labels, value)
}