Files
knowledge-governance/internal/releaseadapter/v071/verifier.go
T
姚章浩 eabe55b432 fix(release): wiki 校验与写入的归属口径不一致导致跨环境发布必然失败
端到端验收实测(2026-10-10):文件型文档(docx)跨环境发布时,写入侧按设计保留了
目标库外来源 wiki 页(日志 in_scope=0 foreign=8 untouched=1 degraded=true),
但校验侧 VerifyWiki 仍要求"生产页 slug 集合与包内快照完全相等",必然误判,项级
报 release_verification_failed,批次随后被判失败单项失败。

- verifier.go: 归属判定与写入侧 replaceWiki 共用 packageWikiOwners;
  校验改为"快照内页必须都存在 + 多出来的页只有在不属于本包时才放行",
  保留原有牙齿:本包拥有却缺失/残留的页仍判失败;撤权仍禁止任何页引用被撤权文档
- wiki_channel_test.go: 用例改为 外来源多余页放行 / 本包拥有残留页拒绝 / 缺页拒绝
- 实测:同一批次重排后完成(done=1/1 item=verified 生产可用),回滚 rolled_back
  这也是 wiki 归属门禁上线后第一次真实跨环境发布
2026-10-10 10:22:06 +08:00

240 lines
8.4 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package v071
import (
"context"
"encoding/json"
"errors"
"strings"
"unicode/utf8"
"knowledge-governance/internal/platform/weknora"
releaseworkflow "knowledge-governance/internal/workflows/release"
)
type WeKnoraVerificationClient interface {
GetKnowledge(ctx context.Context, knowledgeID string) (weknora.Knowledge, error)
ListChunks(ctx context.Context, knowledgeID string, page, pageSize int, chunkTypes []string) ([]weknora.Chunk, int64, error)
SearchKnowledge(ctx context.Context, request weknora.SearchRequest) ([]weknora.SearchResult, error)
ListWikiPages(ctx context.Context, knowledgeBaseID string, page, pageSize int) ([]weknora.WikiPageSummary, int64, error)
}
type WeKnoraVerifier struct {
client WeKnoraVerificationClient
}
func NewWeKnoraVerifier(client WeKnoraVerificationClient) (*WeKnoraVerifier, error) {
if client == nil {
return nil, errors.New("WeKnora verification client is required")
}
return &WeKnoraVerifier{client: client}, nil
}
func (verifier *WeKnoraVerifier) Verify(ctx context.Context, item releaseworkflow.PlanItem, bundle *DocumentBundle) error {
if bundle == nil || validateDocumentBundle(bundle) != nil || bundle.Manifest.Contract.KnowledgeID != item.KnowledgeID || bundle.Manifest.Contract.KnowledgeBaseID != item.TestKnowledgeBaseID {
return errors.New("invalid WeKnora verification bundle")
}
knowledge, err := verifier.client.GetKnowledge(ctx, item.KnowledgeID)
if err != nil || knowledge.ID != item.KnowledgeID || knowledge.KnowledgeBaseID != item.TargetBase() || knowledge.ParseStatus != "completed" {
return errors.New("production WeKnora knowledge verification failed")
}
_, chunkTotal, err := verifier.client.ListChunks(ctx, item.KnowledgeID, 1, 1, bundleChunkTypes(bundle))
expectedChunks := bundle.Postgres.Table("chunks").RowCount
if err != nil || expectedChunks < 1 || chunkTotal != int64(expectedChunks) {
return errors.New("production WeKnora chunk verification failed")
}
query := bundleProbeQuery(bundle)
if query == "" {
return errors.New("production WeKnora retrieval probe is unavailable")
}
results, err := verifier.client.SearchKnowledge(ctx, weknora.SearchRequest{Query: query, KnowledgeIDs: []string{item.KnowledgeID}})
if err != nil {
return errors.New("production WeKnora retrieval verification failed")
}
for _, result := range results {
if result.KnowledgeID == item.KnowledgeID {
return nil
}
}
return errors.New("production WeKnora retrieval verification failed")
}
func (verifier *WeKnoraVerifier) VerifyDisabled(ctx context.Context, item releaseworkflow.PlanItem) error {
if !validSearchIdentifier(item.KnowledgeID) {
return errors.New("invalid disabled WeKnora verification plan")
}
results, err := verifier.client.SearchKnowledge(ctx, weknora.SearchRequest{
Query: "governance retrieval disable verification sentinel",
KnowledgeIDs: []string{item.KnowledgeID},
})
if err != nil {
return errors.New("disabled WeKnora retrieval verification failed")
}
for _, result := range results {
if result.KnowledgeID == item.KnowledgeID {
return errors.New("disabled WeKnora knowledge remains retrievable")
}
}
return nil
}
// bundleChunkTypes lists the distinct chunk_type values sealed in the bundle.
// WeKnora's chunk list endpoint defaults to text-only results, so verification
// must ask for exactly the types the released document contains.
func bundleChunkTypes(bundle *DocumentBundle) []string {
seen := map[string]bool{}
types := make([]string, 0, 3)
for _, raw := range bundle.Postgres.Table("chunks").Rows {
var row struct {
ChunkType string `json:"chunk_type"`
}
if json.Unmarshal(raw, &row) != nil {
continue
}
chunkType := strings.TrimSpace(row.ChunkType)
if chunkType == "" || seen[chunkType] || !validSearchIdentifier(chunkType) {
continue
}
seen[chunkType] = true
types = append(types, chunkType)
}
return types
}
func bundleProbeQuery(bundle *DocumentBundle) string {
for _, document := range bundle.Search.Documents {
var value map[string]any
if json.Unmarshal(document.Source, &value) != nil {
continue
}
for _, key := range []string{"content", "question", "answer", "title"} {
if text, ok := value[key].(string); ok {
if query := boundedProbeText(text); query != "" {
return query
}
}
}
}
for _, row := range bundle.Postgres.Table("knowledges").Rows {
var value struct {
Title string `json:"title"`
}
if json.Unmarshal(row, &value) == nil {
if query := boundedProbeText(value.Title); query != "" {
return query
}
}
}
return ""
}
func boundedProbeText(value string) string {
value = strings.Join(strings.Fields(value), " ")
if value == "" {
return ""
}
if utf8.RuneCountInString(value) <= 128 {
return value
}
runes := []rune(value)
return string(runes[:128])
}
// VerifyWiki 校验生产端 wiki 与本次快照一致:
// - 快照里的页面 slug 必须都存在于生产端(少一个算失败);
// - 生产端多出来的页面,只有"不属于本包"时才放行:跨来源共库时写入侧
// (replaceWiki)会按设计保留外来源页面(degraded 模式,日志 foreign=N),
// 校验侧若按"集合完全相等"验就会误判——2026-10-10 跨环境发布实测:
// in_scope=0 / foreign=8 的文件型发布被 release_verification_failed 拦死。
// 仍然会被拦下的是"本包拥有却多出来或少了"的页面;
// - 撤权(delete)时生产 wiki 任何页面都不得再引用被撤权的文档。
//
// 老包 / 未启用 wiki 的库不携带 wiki 快照,直接跳过(生产 wiki 保持原样)。
func (verifier *WeKnoraVerifier) VerifyWiki(ctx context.Context, item releaseworkflow.PlanItem, bundle *DocumentBundle) error {
if bundle == nil || validateDocumentBundle(bundle) != nil {
return errors.New("invalid WeKnora wiki verification bundle")
}
if !hasWikiSnapshot(bundle.Postgres) {
return nil
}
// 本包拥有的知识(与写入侧 replaceWiki 用同一套判定):目标库页面若引用了
// 这些知识,就是本包页面;否则属于其他来源,写入侧会保留它们。
owners, ownersErr := packageWikiOwners(bundle.Postgres)
if ownersErr != nil {
owners = map[string]bool{}
if validSearchIdentifier(item.KnowledgeID) {
owners[item.KnowledgeID] = true
}
}
expected := map[string]bool{}
for _, raw := range bundle.Postgres.Table("wiki_pages").Rows {
var row struct {
Slug string `json:"slug"`
}
if json.Unmarshal(raw, &row) != nil || strings.TrimSpace(row.Slug) == "" {
return errors.New("invalid WeKnora wiki verification bundle")
}
expected[row.Slug] = true
}
const pageSize = 20
const maxPageBudget = 1000
seen := map[string]bool{}
owned := map[string]bool{}
scanned := 0
for page := 1; ; page++ {
pages, total, err := verifier.client.ListWikiPages(ctx, item.TargetBase(), page, pageSize)
if err != nil {
return errors.New("production WeKnora wiki verification failed")
}
for _, wikiPage := range pages {
if strings.TrimSpace(wikiPage.Slug) == "" {
continue
}
seen[wikiPage.Slug] = true
if pageOwnedByPackage(wikiPage, owners) {
owned[wikiPage.Slug] = true
}
if item.Action != "delete" {
continue
}
for _, reference := range wikiPage.SourceRefs {
if referencesKnowledge(reference, item.KnowledgeID) {
return errors.New("production WeKnora wiki still references the withdrawn document")
}
}
}
scanned += len(pages)
if len(pages) == 0 || int64(scanned) >= total {
break
}
if page >= maxPageBudget {
return errors.New("production WeKnora wiki verification exceeded its page budget")
}
}
for slug := range expected {
if !seen[slug] {
return errors.New("production WeKnora wiki page set mismatch")
}
}
// 生产端多出来的页面:外来源页面是写入侧明确保留的,不算失败;
// 本包自己的页面多出来(例如撤权后仍残留)仍然判失败。
for slug := range seen {
if expected[slug] || !owned[slug] {
continue
}
return errors.New("production WeKnora wiki page set mismatch")
}
return nil
}
// pageOwnedByPackage 判断目标库某页面是否属于本包:页面任一 source_ref 指向本包知识。
func pageOwnedByPackage(page weknora.WikiPageSummary, owners map[string]bool) bool {
for _, reference := range page.SourceRefs {
if owner := referenceOwner(reference); owner != "" && owners[owner] {
return true
}
}
return false
}
var _ ProductionVerifier = (*WeKnoraVerifier)(nil)