Files
knowledge-governance/internal/platform/postgres/reviews.go
T
zheromiku dcdc8d1ddd feat: 知识治理平台(含已验证发布/回滚契约)
全栈知识治理平台首次入库(P1-P10 + 发布链路模拟验证闭环):

- 治理核心:源目录/变更集/人工审核/发布批次/发布执行(fail-closed 闸口)
- 测试通道:WeKnora 测试 KB 上传/轮询/验收;poll 完成时写入
  parser_generation/index_generation,修复 manual/seed 路径发布闸口永久拦截
- 发布适配器 v071(本地 source=测试角色 / 云端 target=生产角色 模拟验证通过):
  * ES 导出/导入 mapping 自适应(.keyword 子字段、可选 tenant_id)
  * OSS locator 支持嵌套 scheme;chunks.seq_id 由目标序列分配
  * bundle 归档同身份重试原子替换;verifier 按 bundle chunk_type 计数
  * 回滚 job payload 支持 prior_execution_id(strict 解码)
- 三通道发布+回滚演练实测:publish 4/4 verified,检索命中,
  rollback 4/4 rolled_back,目标端 PG is_enabled=false、ES is_enabled=false
- 前端 A·Data-console 风格全站统一,120 用例通过
- 门禁:go vet / go test 全包通过,gofmt 干净
2026-09-30 10:54:06 +08:00

254 lines
12 KiB
Go

package postgres
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"github.com/jackc/pgx/v5"
"knowledge-governance/internal/governance"
)
var (
ErrInvalidReviewFilter = errors.New("invalid review candidate filter")
ErrInvalidPublicationReview = errors.New("invalid publication review")
ErrPublicationReviewNotEligible = errors.New("publication review is not eligible")
)
const reviewCandidatesCTE = `
WITH acceptance_run_summary AS (
SELECT publication_id, run_id, MAX(observed_at) AS observed_at,
COALESCE(MAX(state) FILTER (WHERE check_type = 'knowledge_exists'), '') AS knowledge_exists,
COALESCE(MAX(state) FILTER (WHERE check_type = 'chunks_present'), '') AS chunks_present,
COALESCE(MAX(state) FILTER (WHERE check_type = 'retrieval_hit'), '') AS retrieval_hit
FROM acceptance_results
GROUP BY publication_id, run_id
), latest_acceptance AS (
SELECT DISTINCT ON (publication_id)
publication_id, run_id, knowledge_exists, chunks_present, retrieval_hit, observed_at
FROM acceptance_run_summary
ORDER BY publication_id, observed_at DESC, run_id DESC
), candidates AS (
SELECT p.id AS publication_id, i.title, connection.source_type,
COALESCE(item_scope.visibility, directory_scope.visibility, i.visibility) AS current_visibility,
acceptance.run_id AS acceptance_run_id,
acceptance.knowledge_exists, acceptance.chunks_present, acceptance.retrieval_hit,
CASE
WHEN p.ingest_state <> 'uploaded' OR p.processing_state <> 'completed' OR p.retrieval_state <> 'unpublished' THEN 'blocked'
WHEN version.revision <> i.revision OR i.source_change IN ('deleted', 'unavailable') THEN 'blocked'
WHEN acceptance.knowledge_exists = 'failed' OR acceptance.chunks_present = 'failed' OR acceptance.retrieval_hit = 'failed' THEN 'blocked'
WHEN acceptance.knowledge_exists <> 'passed' OR acceptance.chunks_present <> 'passed'
OR acceptance.retrieval_hit NOT IN ('passed', 'manual_required') THEN 'blocked'
ELSE 'ready'
END AS gate_status,
CASE
WHEN p.ingest_state <> 'uploaded' OR p.processing_state <> 'completed' OR p.retrieval_state <> 'unpublished' THEN 'publication_not_ready'
WHEN version.revision <> i.revision OR i.source_change IN ('deleted', 'unavailable') THEN 'source_not_current'
WHEN acceptance.knowledge_exists = 'failed' OR acceptance.chunks_present = 'failed' OR acceptance.retrieval_hit = 'failed' THEN 'acceptance_failed'
WHEN acceptance.knowledge_exists <> 'passed' OR acceptance.chunks_present <> 'passed'
OR acceptance.retrieval_hit NOT IN ('passed', 'manual_required') THEN 'acceptance_incomplete'
ELSE 'ready'
END AS gate_code,
CASE
WHEN review.id IS NOT NULL AND review.acceptance_run_id = acceptance.run_id
AND review.publication_updated_at = p.updated_at THEN review.decision
ELSE 'pending'
END AS review_state,
CASE WHEN review.id IS NOT NULL AND review.acceptance_run_id = acceptance.run_id
AND review.publication_updated_at = p.updated_at THEN review.decided_visibility ELSE '' END AS decided_visibility,
CASE WHEN review.id IS NOT NULL AND review.acceptance_run_id = acceptance.run_id
AND review.publication_updated_at = p.updated_at THEN review.decision_code ELSE '' END AS decision_code,
CASE WHEN review.id IS NOT NULL AND review.acceptance_run_id = acceptance.run_id
AND review.publication_updated_at = p.updated_at THEN review.reviewer_ref ELSE '' END AS reviewer_ref,
CASE WHEN review.id IS NOT NULL AND review.acceptance_run_id = acceptance.run_id
AND review.publication_updated_at = p.updated_at THEN review.created_at ELSE NULL END AS reviewed_at,
p.updated_at
FROM test_publications AS p
JOIN source_item_versions AS version ON version.id = p.source_item_version_id
JOIN source_items AS i ON i.id = version.source_item_id
JOIN source_connections AS connection ON connection.id = i.source_connection_id
LEFT JOIN source_item_scope_overrides AS item_scope ON item_scope.source_item_id = i.id
LEFT JOIN LATERAL (
SELECT rule.visibility
FROM directory_scope_rules AS rule
WHERE rule.source_connection_id = i.source_connection_id
AND (
rule.directory_path = ''
OR i.normalized_path = rule.directory_path
OR LEFT(i.normalized_path, LENGTH(rule.directory_path) + 1) = rule.directory_path || '/'
)
ORDER BY LENGTH(rule.directory_path) DESC
LIMIT 1
) AS directory_scope ON TRUE
JOIN latest_acceptance AS acceptance ON acceptance.publication_id = p.id
LEFT JOIN LATERAL (
SELECT id, decision, decided_visibility, decision_code, reviewer_ref,
acceptance_run_id, publication_updated_at, created_at
FROM publication_reviews
WHERE publication_id = p.id
ORDER BY created_at DESC, id DESC
LIMIT 1
) AS review ON TRUE
)
`
const countReviewCandidatesSQL = reviewCandidatesCTE + `
SELECT COUNT(*)::INTEGER
FROM candidates
WHERE $1 = '' OR review_state = $1
`
const listReviewCandidatesSQL = reviewCandidatesCTE + `
SELECT publication_id, title, source_type, current_visibility,
acceptance_run_id, knowledge_exists, chunks_present, retrieval_hit,
gate_status, gate_code, review_state, decided_visibility,
decision_code, reviewer_ref, reviewed_at, updated_at
FROM candidates
WHERE $1 = '' OR review_state = $1
ORDER BY updated_at DESC, publication_id
LIMIT $2 OFFSET $3
`
const reviewPublicationSQL = reviewCandidatesCTE + `
INSERT INTO publication_reviews (
id, publication_id, decision, decided_visibility, reviewer_ref,
decision_code, acceptance_run_id, publication_updated_at, created_at
)
SELECT $1::varchar, publication_id, $3::varchar, $4::varchar, $5::varchar, $6::varchar,
acceptance_run_id, updated_at, $7::timestamptz
FROM candidates
WHERE publication_id = $2::varchar
AND ($3::varchar = 'rejected' OR gate_status = 'ready')
ON CONFLICT (
publication_id, acceptance_run_id, publication_updated_at,
reviewer_ref, decision, decided_visibility, decision_code
) DO UPDATE SET id = publication_reviews.id
RETURNING id, publication_id, decision, decided_visibility, reviewer_ref,
decision_code, acceptance_run_id, publication_updated_at, created_at
`
func (s *Store) ListReviewCandidates(ctx context.Context, filter governance.ReviewCandidateFilter) (governance.ReviewCandidatePage, error) {
if filter.Limit < 1 || filter.Limit > 100 || filter.Offset < 0 || filter.Offset > 1000000 ||
filter.ReviewState != "" && filter.ReviewState != string(governance.ReviewPending) &&
filter.ReviewState != string(governance.ReviewApproved) && filter.ReviewState != string(governance.ReviewRejected) {
return governance.ReviewCandidatePage{}, ErrInvalidReviewFilter
}
page := governance.ReviewCandidatePage{Items: []governance.ReviewCandidate{}, Limit: filter.Limit, Offset: filter.Offset}
if err := s.db.QueryRow(ctx, countReviewCandidatesSQL, filter.ReviewState).Scan(&page.Total); err != nil {
return governance.ReviewCandidatePage{}, fmt.Errorf("count review candidates: %w", err)
}
rows, err := s.db.Query(ctx, listReviewCandidatesSQL, filter.ReviewState, filter.Limit, filter.Offset)
if err != nil {
return governance.ReviewCandidatePage{}, fmt.Errorf("list review candidates: %w", err)
}
defer rows.Close()
for rows.Next() {
var item governance.ReviewCandidate
var sourceType, visibility, knowledgeState, chunksState, retrievalState, gateStatus, reviewState string
if err := rows.Scan(
&item.PublicationID, &item.Title, &sourceType, &visibility,
&item.AcceptanceRunID, &knowledgeState, &chunksState, &retrievalState,
&gateStatus, &item.GateCode, &reviewState, &item.DecidedVisibility,
&item.DecisionCode, &item.ReviewerRef, &item.ReviewedAt, &item.PublicationUpdated,
); err != nil {
return governance.ReviewCandidatePage{}, fmt.Errorf("scan review candidate: %w", err)
}
item.SourceType = governance.SourceType(sourceType)
item.CurrentVisibility = governance.Visibility(visibility)
item.KnowledgeExists = governance.AcceptanceState(knowledgeState)
item.ChunksPresent = governance.AcceptanceState(chunksState)
item.RetrievalHit = governance.AcceptanceState(retrievalState)
item.GateStatus = governance.ReviewGateStatus(gateStatus)
item.ReviewState = governance.ReviewState(reviewState)
if !item.SourceType.Valid() || !item.GateStatus.Valid() || !item.ReviewState.Valid() ||
!item.KnowledgeExists.Valid() || !item.ChunksPresent.Valid() || !item.RetrievalHit.Valid() ||
item.CurrentVisibility != governance.VisibilityInternal && item.CurrentVisibility != governance.VisibilityExternal {
return governance.ReviewCandidatePage{}, errors.New("invalid review candidate row")
}
page.Items = append(page.Items, item)
}
if err := rows.Err(); err != nil {
return governance.ReviewCandidatePage{}, fmt.Errorf("iterate review candidates: %w", err)
}
return page, nil
}
func (s *Store) ReviewPublicationWithOperation(ctx context.Context, request governance.ReviewPublicationRequest, operationID string) (governance.PublicationReview, bool, error) {
fingerprint, err := operationFingerprint(struct {
PublicationID string `json:"publication_id"`
Decision governance.ReviewState `json:"decision"`
Visibility governance.Visibility `json:"decided_visibility"`
ReviewerRef string `json:"reviewer_ref"`
Code string `json:"decision_code"`
}{request.PublicationID, request.Decision, request.DecidedVisibility, request.ReviewerRef, request.DecisionCode})
if err != nil {
return governance.PublicationReview{}, false, err
}
raw, replayed, err := s.executeOperation(ctx, "publication.review", operationID, fingerprint, request.Now, func(tx pgx.Tx) (json.RawMessage, error) {
review, err := NewStore(tx).ReviewPublication(ctx, request)
if err != nil {
return nil, err
}
return json.Marshal(review)
})
if err != nil {
return governance.PublicationReview{}, false, err
}
var review governance.PublicationReview
if err := json.Unmarshal(raw, &review); err != nil {
return governance.PublicationReview{}, false, fmt.Errorf("decode stored review result: %w", err)
}
return review, replayed, nil
}
func (s *Store) ReviewPublication(ctx context.Context, request governance.ReviewPublicationRequest) (governance.PublicationReview, error) {
if !validPublicationReview(request) {
return governance.PublicationReview{}, ErrInvalidPublicationReview
}
reviewID, err := newOpaqueID("rv-")
if err != nil {
return governance.PublicationReview{}, err
}
var review governance.PublicationReview
var decision, visibility string
err = s.db.QueryRow(ctx, reviewPublicationSQL,
reviewID, request.PublicationID, string(request.Decision), string(request.DecidedVisibility),
request.ReviewerRef, request.DecisionCode, request.Now,
).Scan(
&review.ID, &review.PublicationID, &decision, &visibility, &review.ReviewerRef,
&review.DecisionCode, &review.AcceptanceRunID, &review.PublicationUpdated, &review.CreatedAt,
)
if errors.Is(err, pgx.ErrNoRows) {
return governance.PublicationReview{}, ErrPublicationReviewNotEligible
}
if err != nil {
return governance.PublicationReview{}, fmt.Errorf("review publication: %w", err)
}
review.Decision = governance.ReviewState(decision)
review.DecidedVisibility = governance.Visibility(visibility)
return review, nil
}
func validPublicationReview(request governance.ReviewPublicationRequest) bool {
if !validShortID(request.PublicationID) || request.Now.IsZero() ||
request.DecidedVisibility != governance.VisibilityInternal && request.DecidedVisibility != governance.VisibilityExternal ||
!validReviewerRef(request.ReviewerRef) {
return false
}
switch request.Decision {
case governance.ReviewApproved:
return request.DecisionCode == "approved_for_release"
case governance.ReviewRejected:
return request.DecisionCode == "needs_correction" || request.DecisionCode == "classification_changed" || request.DecisionCode == "acceptance_rejected"
default:
return false
}
}
func validReviewerRef(value string) bool {
return value == strings.TrimSpace(value) && value != "" && len(value) <= 128 && !strings.ContainsAny(value, "\x00\r\n ")
}