feat(release): 建批时冻结 + 验收通过自动批准 —— 把"每份文档 8 步"砍掉两步并去掉两次卡死

背景:发布管理把"逐条核验"的仪式强加给每一份文档。实测一份文档要 9~11 次交互,
且有两处顺序陷阱(冻结后批准 → 建批 422;生成即固化 → 批准被永久钉住)。

P0-1 建批时冻结:
- CreateReleaseBatch 在未指定版本时,自己把当前实时计划冻结成一份**已确认**版本并绑定
  (同一事务;同摘要复用最近版本,planned 或 confirmed 都可复用,因此同一份计划不堆版本)。
- 语义不变:批一旦建立,清单/摘要/验收轮次/目标库绑定全部不可变、回滚按它走;变的只是
  "谁在什么时候按固化键"——从操作员的手动两步变成建批这一下。
- 效果:去掉「生成新版本」「确认冻结」两步;消灭"批准晚于冻结 → 422"这类顺序陷阱;
  前端不再传版本 id,也不再有"所选知识不在冻结清单里"的阻断。
- 计划→清单项的映射抽成 ChangeSetItemsFromPlan 供两处共用,否则两处算出的摘要不同,
  "同一计划复用同一版本"永远不命中。

P0-2 验收通过自动批准:
- 验收三项结论达发布门槛(knowledge_exists/chunks_present=passed,retrieval_hit 与门槛同
  口径)时,由 worker 写入 reviewer_ref='system:auto' 的批准记录,替代"每份文档点一次批准"。
- 策略 TEST_AUTO_REVIEW_POLICY = off | internal(默认,仅对内)| all;值不认识拒绝启动。
  只影响审核这一步:生产授权、双闸与发布前快照门禁不受影响。界面上只读展示当前策略。
- 安全边界(写死在审核 SQL 里):系统只允许写"第一条"审核——人工一旦表过态,机器不得用一条
  更晚的 approved 把人工结论翻回去;人工随时可再审。集成测试去掉该约束即 FAIL(已实测)。
- 自动批准自身的任何失败都不影响验收结论,只上报。

顺带(P1-1 前半,已被 P0-1 取代的部分已删除):
- 写操作失败把服务端 {"error": ...} 的原因带出来,并对已知原因给出下一步(不再只给 HTTP 状态码)。
- 当前的"不在已冻结清单里"标注与就地修复按钮随 P0-1 一起移除(该失败模式已不存在)。

测试:bind_time_freeze_integration_test.go(绑定已确认版本/同计划复用/冻结后不可变/
动作不符仍 NotEligible)、auto_review_integration_test.go(系统只写第一条、人工可再审)、
validate_test.go(对内自动/对外不自动/策略关闭/验收未过不批/自身失败不影响验收)、
auto_review_test.go、config_test 及前端能力解析测试。
实测耗时:本机 Go 全量 26 包通过、前端 178 条通过。
This commit is contained in:
姚章浩
2026-10-10 15:05:20 +08:00
parent 32450a7c7b
commit acf053faf3
21 changed files with 630 additions and 44 deletions
@@ -0,0 +1,79 @@
package postgres
import (
"context"
"errors"
"os"
"testing"
"time"
"github.com/jackc/pgx/v5/pgxpool"
"knowledge-governance/internal/governance"
)
// 系统自动批准只能写"第一条"审核:人工一旦表过态,机器不得用一条更晚的 approved
// 把人工结论翻回去(重跑验收时尤其危险)。人工审核不受限,随时可再审。
func TestAutoReviewNeverOverridesHumanDecisions(t *testing.T) {
databaseURL := isolatedIntegrationDatabaseURL(t, os.Getenv("TEST_DATABASE_URL"))
if databaseURL == "" {
t.Skip("TEST_DATABASE_URL is not set")
}
ctx := context.Background()
pool, err := pgxpool.New(ctx, databaseURL)
if err != nil {
t.Fatal(err)
}
defer pool.Close()
if err := ApplyMigrations(ctx, pool); err != nil {
t.Fatal(err)
}
store := NewStore(pool)
now := time.Date(2026, 10, 10, 12, 0, 0, 0, time.UTC)
if _, err := pool.Exec(ctx, `INSERT INTO source_connections (id, source_type, name) VALUES ('conn-manual', 'manual', 'Manual')`); err != nil {
t.Fatal(err)
}
insertReviewFixture(t, ctx, pool, 10, "tp-auto-first", now)
insertReviewFixture(t, ctx, pool, 11, "tp-auto-rejected", now)
// 还没有任何审核:系统可以写第一条。
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-auto-first", Decision: governance.ReviewApproved,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "system:auto",
DecisionCode: "approved_for_release", Now: now.Add(time.Minute),
}); err != nil {
t.Fatalf("first auto review must be allowed: %v", err)
}
// 人工先驳回:系统再也不能自动批准这一条。
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-auto-rejected", Decision: governance.ReviewRejected,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "admin",
DecisionCode: "needs_correction", Now: now.Add(time.Minute),
}); err != nil {
t.Fatalf("human rejection must succeed: %v", err)
}
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-auto-rejected", Decision: governance.ReviewApproved,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "system:auto",
DecisionCode: "approved_for_release", Now: now.Add(2 * time.Minute),
}); !errors.Is(err, ErrPublicationReviewNotEligible) {
t.Fatalf("auto review over a human decision error=%v, want ErrPublicationReviewNotEligible", err)
}
var decision, reviewer string
if err := pool.QueryRow(ctx, `SELECT decision, reviewer_ref FROM publication_reviews WHERE publication_id='tp-auto-rejected' ORDER BY created_at DESC, id DESC LIMIT 1`).Scan(&decision, &reviewer); err != nil {
t.Fatal(err)
}
if decision != "rejected" || reviewer != "admin" {
t.Fatalf("latest review = %q by %q, want rejected by admin", decision, reviewer)
}
// 人工仍可再审(例如改判为批准)。
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-auto-rejected", Decision: governance.ReviewApproved,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "admin",
DecisionCode: "approved_for_release", Now: now.Add(3 * time.Minute),
}); err != nil {
t.Fatalf("human re-review must still be allowed: %v", err)
}
}
@@ -0,0 +1,118 @@
package postgres
import (
"context"
"errors"
"os"
"testing"
"time"
"github.com/jackc/pgx/v5/pgxpool"
"knowledge-governance/internal/governance"
)
// P0-1「建批时冻结」:操作员不必先"生成新版本 + 确认冻结",清单在建批那一刻固化。
// 这里固化的三件事:批一定绑定一份已确认版本;同一份计划复用同一版本;冻结之后不可变。
func TestBindTimeFreezeCreatesAndReusesConfirmedManifest(t *testing.T) {
databaseURL := isolatedIntegrationDatabaseURL(t, os.Getenv("TEST_DATABASE_URL"))
if databaseURL == "" {
t.Skip("TEST_DATABASE_URL is not set")
}
ctx := context.Background()
pool, err := pgxpool.New(ctx, databaseURL)
if err != nil {
t.Fatal(err)
}
defer pool.Close()
if err := ApplyMigrations(ctx, pool); err != nil {
t.Fatal(err)
}
store := NewStore(pool)
now := time.Date(2026, 10, 10, 14, 0, 0, 0, time.UTC)
if _, err := pool.Exec(ctx, `INSERT INTO source_connections (id, source_type, name) VALUES ('conn-manual', 'manual', 'Manual')`); err != nil {
t.Fatal(err)
}
insertReviewFixture(t, ctx, pool, 12, "tp-p01-a", now)
insertReviewFixture(t, ctx, pool, 13, "tp-p01-b", now)
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-p01-a", Decision: governance.ReviewApproved,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "engineer-1",
DecisionCode: "approved_for_release", Now: now.Add(time.Minute),
}); err != nil {
t.Fatal(err)
}
// 建批不带版本 id:服务端自己冻结一份已确认版本并绑定。
first, err := store.CreateReleaseBatch(ctx, governance.CreateReleaseBatchRequest{
Name: "P0-1 自动冻结", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-p01-a"}, Now: now.Add(2 * time.Minute),
})
if err != nil {
t.Fatalf("bind-time freeze must let the batch through: %v", err)
}
if first.ReleaseChangeSetID == "" {
t.Fatal("batch must be bound to a frozen release change set")
}
var state, manifest string
var itemCount int
if err := pool.QueryRow(ctx, `SELECT state, manifest_sha256, item_count FROM release_change_sets WHERE id=$1`, first.ReleaseChangeSetID).Scan(&state, &manifest, &itemCount); err != nil {
t.Fatal(err)
}
if state != "confirmed" {
t.Fatalf("frozen set state = %q, want confirmed", state)
}
if len(manifest) != 64 {
t.Fatalf("manifest digest = %q, want 64 hex chars", manifest)
}
var covered bool
var canRelease bool
if err := pool.QueryRow(ctx, `SELECT TRUE, can_release FROM release_change_set_items WHERE change_set_id=$1 AND publication_id='tp-p01-a'`, first.ReleaseChangeSetID).Scan(&covered, &canRelease); err != nil {
t.Fatalf("frozen manifest must cover the requested publication: %v", err)
}
if !canRelease {
t.Fatal("covered item must be marked releasable")
}
// 计划没变 → 复用同一份版本,不堆版本。
second, err := store.CreateReleaseBatch(ctx, governance.CreateReleaseBatchRequest{
Name: "P0-1 自动冻结 2", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-p01-a"}, Now: now.Add(3 * time.Minute),
})
if err != nil {
t.Fatal(err)
}
if second.ReleaseChangeSetID != first.ReleaseChangeSetID {
t.Fatalf("unchanged plan must reuse the frozen version: %q vs %q", second.ReleaseChangeSetID, first.ReleaseChangeSetID)
}
// 冻结之后不可变:之后又批准一条,也不改变已建批次绑定的那份清单。
if _, err := store.ReviewPublication(ctx, governance.ReviewPublicationRequest{
PublicationID: "tp-p01-b", Decision: governance.ReviewApproved,
DecidedVisibility: governance.VisibilityInternal, ReviewerRef: "engineer-1",
DecisionCode: "approved_for_release", Now: now.Add(4 * time.Minute),
}); err != nil {
t.Fatal(err)
}
var stateAfter, manifestAfter string
var itemCountAfter int
if err := pool.QueryRow(ctx, `SELECT state, manifest_sha256, item_count FROM release_change_sets WHERE id=$1`, first.ReleaseChangeSetID).Scan(&stateAfter, &manifestAfter, &itemCountAfter); err != nil {
t.Fatal(err)
}
if stateAfter != state || manifestAfter != manifest || itemCountAfter != itemCount {
t.Fatalf("frozen manifest changed after later approvals: %q/%q/%d", stateAfter, manifestAfter, itemCountAfter)
}
// 没有审核结论的条目依然进不了批次(放到新冻结里也不行)。
if _, err := store.CreateReleaseBatch(ctx, governance.CreateReleaseBatchRequest{
Name: "P0-1 未审核条目", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-p01-c"}, Now: now.Add(5 * time.Minute),
}); err == nil {
t.Fatal("an unknown publication must not be accepted into a batch")
}
// 请求的动作与计划不符(把"新增"当"删除"发)→ 门禁不通过,且必须是可读的错误码。
_, err = store.CreateReleaseBatch(ctx, governance.CreateReleaseBatchRequest{
Name: "P0-1 动作不符", CreatedBy: "engineer-1", DeletePublicationIDs: []string{"tp-p01-a"}, Now: now.Add(6 * time.Minute),
})
if !errors.Is(err, ErrReleaseBatchNotEligible) {
t.Fatalf("action mismatch error=%v, want ErrReleaseBatchNotEligible", err)
}
}
@@ -77,7 +77,16 @@ FROM release_executions e JOIN release_item_executions i ON i.release_execution_
if state != "completed" {
t.Fatalf("unbound success must stay completed, got %q", state)
}
if len(sealed) != 64 || sealed != ComputeReleaseExecutionManifest("publish", "", []string{publicationID + "|" + bundleSHA + "|" + revision}) {
// P0-1 之后建批必然绑定一份已冻结版本,执行摘要因此包含该版本清单的摘要。
var frozenManifest string
if err := pool.QueryRow(ctx, `SELECT change_set.manifest_sha256
FROM release_executions execution
JOIN release_batches batch ON batch.id = execution.release_batch_id
JOIN release_change_sets change_set ON change_set.id = batch.release_change_set_id
WHERE execution.id=$1`, executionID).Scan(&frozenManifest); err != nil {
t.Fatal(err)
}
if len(sealed) != 64 || sealed != ComputeReleaseExecutionManifest("publish", frozenManifest, []string{publicationID + "|" + bundleSHA + "|" + revision}) {
t.Fatalf("manifest not sealed/deterministic: %q", sealed)
}
// Re-seal must be a no-op (immutable once set).
@@ -15,6 +15,40 @@ import (
const releaseGatePolicyVersion = "release-gate-v1"
// ensureFrozenChangeSetForPlan 把当前实时计划冻结为一份已确认的不可变版本,返回其 id。
// 复用规则:与当前计划摘要完全一致的最近版本(planned 或 confirmed)直接复用并确认
// (对已确认版本 Confirm 是幂等重放),因此同一份计划不会每个批次都堆一版;计划变了才新建。
func (s *Store) ensureFrozenChangeSetForPlan(ctx context.Context, request governance.CreateReleaseBatchRequest) (string, error) {
plan, err := s.ListReleasePlan(ctx)
if err != nil {
return "", err
}
if len(plan.Items) == 0 {
return "", ErrReleaseChangeSetEmpty
}
manifest := ComputeReleaseChangeSetManifest(ChangeSetItemsFromPlan(plan.Items))
existing, err := s.findReusableByManifest(ctx, manifest)
switch {
case err == nil:
confirmed, confirmErr := s.ConfirmReleaseChangeSet(ctx, governance.ConfirmReleaseChangeSetRequest{ChangeSetID: existing.ID, ConfirmedBy: request.CreatedBy, Now: request.Now})
if confirmErr != nil {
return "", confirmErr
}
return confirmed.ID, nil
case !errors.Is(err, pgx.ErrNoRows):
return "", err
}
generated, err := s.GenerateReleaseChangeSet(ctx, governance.GenerateReleaseChangeSetRequest{Name: "批次冻结 · " + request.Name, CreatedBy: request.CreatedBy, Now: request.Now})
if err != nil {
return "", err
}
confirmed, err := s.ConfirmReleaseChangeSet(ctx, governance.ConfirmReleaseChangeSetRequest{ChangeSetID: generated.ID, ConfirmedBy: request.CreatedBy, Now: request.Now})
if err != nil {
return "", err
}
return confirmed.ID, nil
}
var (
ErrInvalidReleaseBatch = errors.New("invalid release batch")
ErrInvalidReleaseBatchFilter = errors.New("invalid release batch filter")
@@ -300,6 +334,17 @@ func (s *Store) CreateReleaseBatch(ctx context.Context, request governance.Creat
if !validCreateReleaseBatch(request) {
return governance.ReleaseBatch{}, ErrInvalidReleaseBatch
}
if strings.TrimSpace(request.ReleaseChangeSetID) == "" {
// P0-1「建批时冻结」:操作员不再需要先"生成新版本 + 确认冻结"。
// 冻结发生在"这一批要发什么"已经确定的时刻——建批这一下;建立之后清单不可变,
// 来源刷新与后续批准都不会改变它(回滚、审计都按它走)。语义与手工冻结完全一致,
// 只是把"按固化键的人"从操作员换成了建批动作本身。
frozenID, err := s.ensureFrozenChangeSetForPlan(ctx, request)
if err != nil {
return governance.ReleaseBatch{}, err
}
request.ReleaseChangeSetID = frozenID
}
batchID, err := newOpaqueID("rb-")
if err != nil {
return governance.ReleaseBatch{}, err
@@ -16,8 +16,10 @@ import (
func TestCreateReleaseBatchAtomicallyLocksOnlyApprovedCurrentItems(t *testing.T) {
now := time.Date(2026, 9, 6, 9, 0, 0, 0, time.UTC)
db := &recordingDB{row: releaseBatchRow{id: "rb-safe", name: "Synthetic batch", state: "draft", policy: "release-gate-v1", createdBy: "engineer-1", itemCount: 3, createdAt: now}}
// 显式传入已确认版本:这个用例检查的是建批 SQL 的门禁条件,桩 db 不提供实时计划查询;
// "不带版本 id → 服务端自动冻结"的路径由 bind_time_freeze_integration_test.go 用真库覆盖。
batch, err := NewStore(db).CreateReleaseBatch(context.Background(), governance.CreateReleaseBatchRequest{
Name: "Synthetic batch", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-a", "tp-b"}, DeletePublicationIDs: []string{"tp-c"}, Now: now,
Name: "Synthetic batch", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-a", "tp-b"}, DeletePublicationIDs: []string{"tp-c"}, ReleaseChangeSetID: "rcs-safe", Now: now,
})
if err != nil {
t.Fatalf("CreateReleaseBatch() error = %v", err)
@@ -58,13 +60,15 @@ func TestCreateReleaseBatchRejectsInvalidOrDuplicateInput(t *testing.T) {
}
}
func TestCreateReleaseBatchReturnsNotEligibleWhenAnyItemFailsGate(t *testing.T) {
// 桩 db 查不到"已确认版本",建批必须拒绝——这条守卫是"批次只能绑定已确认清单"的入口。
// 「门禁不通过 → ErrReleaseBatchNotEligible」的映射由 bind_time_freeze_integration_test.go 用真库钉住。
func TestCreateReleaseBatchRejectsUnconfirmedChangeSet(t *testing.T) {
db := &recordingDB{row: sourceScanErrorRow{err: pgx.ErrNoRows}}
_, err := NewStore(db).CreateReleaseBatch(context.Background(), governance.CreateReleaseBatchRequest{
Name: "Batch", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-a"}, Now: time.Now(),
Name: "Batch", CreatedBy: "engineer-1", PublicationIDs: []string{"tp-a"}, ReleaseChangeSetID: "rcs-safe", Now: time.Now(),
})
if !errors.Is(err, ErrReleaseBatchNotEligible) {
t.Fatalf("error=%v, want ErrReleaseBatchNotEligible", err)
if !errors.Is(err, ErrReleaseChangeSetUnconfirmed) {
t.Fatalf("error=%v, want ErrReleaseChangeSetUnconfirmed", err)
}
}
@@ -66,6 +66,16 @@ func ComputeReleaseChangeSetManifest(items []governance.ReleaseChangeSetItem) st
return hex.EncodeToString(digest[:])
}
// ChangeSetItemsFromPlan 把实时计划的条目映射成清单项。生成版本与"建批时冻结"共用它,
// 两处必须算出字节相同的摘要,否则"同一份计划复用同一版本"的判断永远不命中。
func ChangeSetItemsFromPlan(planItems []governance.ReleasePlanItem) []governance.ReleaseChangeSetItem {
items := make([]governance.ReleaseChangeSetItem, 0, len(planItems))
for index, planItem := range planItems {
items = append(items, governance.ReleaseChangeSetItem{Seq: index + 1, PublicationID: planItem.PublicationID, Title: planItem.Title, TargetScope: planItem.TargetScope, Action: planItem.Action, TestState: planItem.TestState, ProductionState: planItem.ProductionState, CanRelease: planItem.CanRelease, Blocker: planItem.Blocker})
}
return items
}
// GenerateReleaseChangeSet freezes the current live plan into an immutable
// versioned set. Repeated generation with an identical plan reuses the latest
// PLANNED set (dedup), so concurrent generation cannot create duplicates.
@@ -78,10 +88,7 @@ func (s *Store) GenerateReleaseChangeSet(ctx context.Context, request governance
if err != nil {
return governance.ReleaseChangeSet{}, err
}
items := make([]governance.ReleaseChangeSetItem, 0, len(plan.Items))
for index, planItem := range plan.Items {
items = append(items, governance.ReleaseChangeSetItem{Seq: index + 1, PublicationID: planItem.PublicationID, Title: planItem.Title, TargetScope: planItem.TargetScope, Action: planItem.Action, TestState: planItem.TestState, ProductionState: planItem.ProductionState, CanRelease: planItem.CanRelease, Blocker: planItem.Blocker})
}
items := ChangeSetItemsFromPlan(plan.Items)
if len(items) == 0 {
return governance.ReleaseChangeSet{}, ErrReleaseChangeSetEmpty
}
@@ -191,6 +198,12 @@ func (s *Store) findPlannedByManifest(ctx context.Context, manifest string) (gov
return scanReleaseChangeSet(s.db.QueryRow(ctx, `SELECT `+releaseChangeSetColumns+` FROM release_change_sets WHERE manifest_sha256=$1 AND state='planned' ORDER BY number DESC LIMIT 1`, manifest))
}
// findReusableByManifest 找与当前计划摘要一致的最近版本(planned 或 confirmed)。
// 建批时冻结用它复用:同一份计划不必因为每个批次都新建一版。
func (s *Store) findReusableByManifest(ctx context.Context, manifest string) (governance.ReleaseChangeSet, error) {
return scanReleaseChangeSet(s.db.QueryRow(ctx, `SELECT `+releaseChangeSetColumns+` FROM release_change_sets WHERE manifest_sha256=$1 AND state IN ('planned','confirmed') ORDER BY number DESC LIMIT 1`, manifest))
}
// ConfirmReleaseChangeSet freezes a planned set for batching. Re-confirming an
// already-confirmed set replays the stored confirmation (immutability).
func (s *Store) ConfirmReleaseChangeSet(ctx context.Context, request governance.ConfirmReleaseChangeSetRequest) (governance.ReleaseChangeSet, error) {
+6
View File
@@ -122,6 +122,12 @@ SELECT $1::varchar, publication_id, $3::varchar, $4::varchar, $5::varchar, $6::v
FROM candidates
WHERE publication_id = $2::varchar
AND ($3::varchar = 'rejected' OR gate_status = 'ready')
-- 系统自动批准(reviewer_ref='system:auto')只允许写"第一条"审核:人工一旦表过态,
-- 机器不得再用一条更晚的 approved 把人工结论静默翻回去(重跑验收时尤其危险)。
-- 人工审核不受此限,随时可再审。
AND ($5::varchar <> 'system:auto' OR NOT EXISTS (
SELECT 1 FROM publication_reviews existing
WHERE existing.publication_id = candidates.publication_id))
ON CONFLICT (
publication_id, acceptance_run_id, publication_updated_at,
reviewer_ref, decision, decided_visibility, decision_code
@@ -58,6 +58,9 @@ type PublicationForValidation struct {
ID string
TestKBID string
KnowledgeID string
// TargetScope 决定这条知识发到哪个生产库(对内/对外)。自动批准策略依赖它:
// 默认只自动批准"对内","对外"仍要人工。
TargetScope string
}
type LegacyVerificationCandidate struct {
@@ -94,7 +97,7 @@ WHERE id = $1
`
const loadPublicationForValidationSQL = `
SELECT id, test_kb_id, knowledge_id
SELECT id, test_kb_id, knowledge_id, target_scope
FROM test_publications
WHERE id = $1
AND ingest_state = 'uploaded'
@@ -443,6 +446,7 @@ func (s *Store) LoadPublicationForValidation(ctx context.Context, publicationID
&publication.ID,
&publication.TestKBID,
&publication.KnowledgeID,
&publication.TargetScope,
)
if errors.Is(err, pgx.ErrNoRows) {
return PublicationForValidation{}, ErrPublicationStateConflict