Files
knowledge-governance/internal/releaseadapter/v071/library_source_settlement.go
T
姚章浩 c2402947a9
build / build (push) Successful in 1m26s
feat(library): 死信按精确指纹解除,保留上游记录
上游 task_dead_letters 没有解决标记,purge/DELETE 会销毁"失败过"的唯一证据。
治理侧新增解除记录(迁移 073):绑定实时行逐字节指纹、重放引用、源侧观测摘要与
操作人;行被改过、重放后又出现新死信、源侧未结清都不命中,封存照旧阻断。
指纹先压紧空白再摘要,避免 PG to_jsonb::text 与 json.Marshal 的空白差异。

试过:go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071,
platform/postgres},make verify 15 项全绿。
2026-10-29 06:55:13 +08:00

154 lines
5.5 KiB
Go

package v071
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
"github.com/jackc/pgx/v5"
"knowledge-governance/internal/librarydeadletter"
)
// A maintenance window stops a shared writer, not a single KB. Check its entire
// source database, including other tenants, deleted scopes and unknown task
// scopes. Restricting this query to the selected KB can interrupt another job.
// This only establishes recorded processing settlement, never Wiki semantics or
// the absence of unrecorded/remote work; CaptureLibrary still requires the
// deployment's ingress and background-worker readiness callback.
//
// 死信不再"存在即阻断":允许调用方带上一组精确解除指纹。每条实时行都要被逐字节
// 命中,行被改过、出现新行或没有解除记录都仍然阻断。这里不删除任何上游行。
func checkLibrarySourceSettlement(ctx context.Context, db librarySnapshotDB) error {
return checkLibrarySourceSettlementReleased(ctx, db, nil)
}
func checkLibrarySourceSettlementReleased(ctx context.Context, db librarySnapshotDB, released []string) error {
tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
if err != nil {
return errors.New("begin library source settlement")
}
defer tx.Rollback(context.WithoutCancel(ctx))
var unsettled, pending, failed int64
if err := tx.QueryRow(ctx, librarySourceSettlementSQL).Scan(&unsettled, &pending, &failed); err != nil {
return errors.New("read library source settlement")
}
if unsettled != 0 || pending != 0 {
return errors.New("library source has unfinished or failed processing")
}
if failed != 0 {
rows, err := sourceDeadLetterRows(ctx, tx, 0, "")
if err != nil {
return err
}
if err := requireReleased(rows, released); err != nil {
return err
}
}
if err := tx.Commit(ctx); err != nil {
return errors.New("commit library source settlement")
}
return nil
}
const librarySourceSettlementSQL = `SELECT /* library-source-settlement */
(SELECT count(*) FROM knowledges WHERE deleted_at IS NULL AND (parse_status IS DISTINCT FROM 'completed' OR pending_subtasks_count IS NULL OR pending_subtasks_count<>0)),
(SELECT count(*) FROM task_pending_ops),
(SELECT count(*) FROM task_dead_letters)`
// sourceDeadLetterRows 读原始行文本(to_jsonb 已规范化),指纹直接对字节求摘要。
// tenant=0 表示整库(维护窗口的粒度),否则按知识库范围。
func sourceDeadLetterRows(ctx context.Context, q interface {
Query(context.Context, string, ...any) (pgx.Rows, error)
}, tenant uint64, kb string) ([][]byte, error) {
statement := `SELECT to_jsonb(d)::text FROM task_dead_letters d`
args := []any{}
if tenant != 0 {
statement += ` WHERE d.tenant_id=$1 AND ((d.scope='knowledge_base' AND d.scope_id=$2) OR
(d.scope='knowledge' AND d.scope_id IN (SELECT id FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2)))`
args = append(args, tenant, kb)
}
statement += ` ORDER BY d.id`
rows, err := q.Query(ctx, statement, args...)
if err != nil {
return nil, errors.New("read library dead letters")
}
defer rows.Close()
var result [][]byte
for rows.Next() {
var raw []byte
if err := rows.Scan(&raw); err != nil {
return nil, errors.New("read library dead letters")
}
result = append(result, raw)
}
if rows.Err() != nil {
return nil, errors.New("read library dead letters")
}
return result, nil
}
func releasedSet(released []string) map[string]bool {
set := make(map[string]bool, len(released))
for _, fingerprint := range released {
set[fingerprint] = true
}
return set
}
func requireReleased(rows [][]byte, released []string) error {
missing, err := librarydeadletter.Unreleased(rows, releasedSet(released))
if err != nil {
return err
}
if len(missing) > 0 {
shown := missing
if len(shown) > 5 {
shown = shown[:5]
}
return fmt.Errorf("source has %d dead letter(s) without a verified release: %s", len(missing), strings.Join(shown, ", "))
}
return nil
}
// ObserveDeadLetters 生成主机侧只读观测:整库结算计数 + 每条死信原始行。
// 解除记录绑定这份观测的字节摘要,平台侧不复制"自报成功"的结论。
func ObserveDeadLetters(ctx context.Context, db librarySnapshotDB, project string, tenant uint64, kb string) ([]byte, error) {
if project == "" || kb == "" || tenant == 0 {
return nil, errors.New("observation requires project, tenant and knowledge base")
}
tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
if err != nil {
return nil, errors.New("begin dead letter observation")
}
defer tx.Rollback(context.WithoutCancel(ctx))
var unsettled, pending, failed int64
if err := tx.QueryRow(ctx, librarySourceSettlementSQL).Scan(&unsettled, &pending, &failed); err != nil {
return nil, errors.New("read library source settlement")
}
rows, err := sourceDeadLetterRows(ctx, tx, 0, "")
if err != nil {
return nil, err
}
observation := librarydeadletter.Observation{
Project: project, TenantID: tenant, KnowledgeBaseID: kb,
CapturedAt: time.Now().UTC().Truncate(time.Second),
Settlement: librarydeadletter.Settlement{Unsettled: unsettled, PendingOps: pending},
Rows: make([]json.RawMessage, 0, len(rows)),
}
for _, raw := range rows {
observation.Rows = append(observation.Rows, json.RawMessage(raw))
}
payload, err := json.Marshal(observation)
if err != nil {
return nil, errors.New("encode dead letter observation")
}
if err := tx.Commit(ctx); err != nil {
return nil, errors.New("commit dead letter observation")
}
return payload, nil
}