feat(qa-ops): 完成复检留档与人工复核闭环

治理侧保存输入观测版本、自动复检及人工复核历史,输入变化失效、版本冲突和幂等重放不覆盖人工记录。批量质量数量使用完整筛选元数据,未采集原文不伪造快照,延迟旧扫描不回退新输入。

验证:全仓 make verify 退出码0,Go656及前端253通过;五包竞态、源/组织/质量隔离PG、真实只读源和隔离网页读回复核通过。默认91个可选集成跳过不计通过。未接AI模型,不写DobotAI源库,未推送、未合并、未部署。
This commit is contained in:
姚章浩
2026-10-17 22:37:26 +08:00
parent 9556db1ef0
commit 4b3aaff321
30 changed files with 2483 additions and 30 deletions
+8
View File
@@ -104,6 +104,10 @@ func listQAOpsRecords(w http.ResponseWriter, r *http.Request, config Config) {
return
}
enrichQAPage(&page, projection)
if err := enrichQAQualityPage(r.Context(), config, &page); err != nil {
writeQualityError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": page})
}
@@ -130,6 +134,10 @@ func getQAOpsRecord(w http.ResponseWriter, r *http.Request, config Config) {
return
}
enrichQARecord(&item, projection)
if err := enrichQAQualityRecord(r.Context(), config, &item); err != nil {
writeQualityError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": item})
}
+5 -2
View File
@@ -17,8 +17,11 @@ type QAOrgSyncStore interface {
}
func authorizeQAOrganizationWrite(w http.ResponseWriter, r *http.Request) bool {
if r.Header.Get("X-Governance-Action") != "qa-organization" || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
writeJSON(w, 403, map[string]string{"error": "区域配置需要同源操作意图"})
return authorizeQAIntent(w, r, "qa-organization")
}
func authorizeQAIntent(w http.ResponseWriter, r *http.Request, intent string) bool {
if r.Header.Get("X-Governance-Action") != intent || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
writeJSON(w, 403, map[string]string{"error": "此操作需要同源操作意图"})
return false
}
// Fetch Metadata survives same-origin proxies that rewrite Host; untrusted
+264
View File
@@ -0,0 +1,264 @@
package httpapi
import (
"bytes"
"context"
"encoding/json"
"errors"
"io"
"knowledge-governance/internal/dobotaiops"
"knowledge-governance/internal/qaopsquality"
"net/http"
"strconv"
"time"
)
type QAQualityStore interface {
ObserveKeys(context.Context, []dobotaiops.QualityKey) (map[string]qaopsquality.View, error)
Observe(context.Context, []dobotaiops.Record) (map[string]qaopsquality.View, error)
Save(context.Context, dobotaiops.Record, qaopsquality.SaveRequest, string) (qaopsquality.Receipt, error)
Columns(context.Context, []dobotaiops.QualityKey) ([]string, error)
History(context.Context, string, int64, int64) (qaopsquality.History, error)
Snapshot(context.Context, string, int64) (qaopsquality.Snapshot, error)
}
type qaQualityReader interface {
ReadQualityScope(context.Context, dobotaiops.RecordQuery) (dobotaiops.QualityScope, error)
}
func writeQualityError(w http.ResponseWriter, err error) {
status, code, message := 503, "quality_unavailable", "质量留档/复核存储不可用,未将失败伪装为空值或零统计"
switch {
case errors.Is(err, qaopsquality.ErrInvalid) || errors.Is(err, dobotaiops.ErrInvalidQuery):
status, code, message = 400, "invalid_quality_request", "质量操作参数无效:请核对结论、理由、版本和筛选范围(最多5000条/32MiB)"
case errors.Is(err, qaopsquality.ErrConflict):
status, code, message = 409, "quality_conflict", "原始问答或人工复核版本已变化,请重新读取问答后核对;未覆盖现有结论"
case errors.Is(err, qaopsquality.ErrSnapshotMissing):
status, code, message = 409, "quality_input_metadata_only", "此版本仅留存指纹与复检元数据,未采集原文;未编造空问题或空答案"
case errors.Is(err, qaopsquality.ErrNotFound):
status, code, message = 404, "quality_input_not_found", "未找到当前授权范围的输入版本"
}
writeJSON(w, status, map[string]string{"error": message, "code": code})
}
func enrichQAQualityRecord(ctx context.Context, c Config, item *dobotaiops.Record) error {
if c.QAQuality == nil {
return nil
}
views, err := c.QAQuality.Observe(ctx, []dobotaiops.Record{*item})
if err != nil {
return err
}
v, ok := views[item.ID]
if !ok {
return qaopsquality.ErrUnavailable
}
item.Quality, err = json.Marshal(v)
return err
}
func enrichQAQualityPage(ctx context.Context, c Config, page *dobotaiops.RecordPage) error {
if c.QAQuality == nil {
return nil
}
views, err := c.QAQuality.Observe(ctx, page.Items)
if err != nil {
return err
}
for i := range page.Items {
v, ok := views[page.Items[i].ID]
if !ok {
return qaopsquality.ErrUnavailable
}
page.Items[i].Quality, err = json.Marshal(v)
if err != nil {
return err
}
}
columns, err := c.QAQuality.Columns(ctx, page.ScopeQuality)
if err != nil {
return err
}
dobotaiops.AddRecordColumns(page, columns...)
return nil
}
func walkQualityJSON(d *json.Decoder) error {
token, err := d.Token()
if err != nil {
return err
}
if token == nil {
return qaopsquality.ErrInvalid
}
if delimiter, ok := token.(json.Delim); ok {
if delimiter != '{' && delimiter != '[' {
return qaopsquality.ErrInvalid
}
keys := map[string]bool{}
for d.More() {
if delimiter == '{' {
key, e := d.Token()
name, ok := key.(string)
if e != nil || !ok || keys[name] {
return qaopsquality.ErrInvalid
}
keys[name] = true
}
if walkQualityJSON(d) != nil {
return qaopsquality.ErrInvalid
}
}
_, err = d.Token()
return err
}
return nil
}
func decodeQualityJSON(w http.ResponseWriter, r *http.Request, target any, required ...string) error {
if r.URL.RawQuery != "" {
return qaopsquality.ErrInvalid
}
raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 64<<10))
if err != nil || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
return qaopsquality.ErrInvalid
}
var top map[string]json.RawMessage
if json.Unmarshal(raw, &top) != nil || top == nil {
return qaopsquality.ErrInvalid
}
for _, key := range required {
if _, ok := top[key]; !ok {
return qaopsquality.ErrInvalid
}
}
check := json.NewDecoder(bytes.NewReader(raw))
if walkQualityJSON(check) != nil {
return qaopsquality.ErrInvalid
}
var extra any
if check.Decode(&extra) != io.EOF {
return qaopsquality.ErrInvalid
}
d := json.NewDecoder(bytes.NewReader(raw))
d.DisallowUnknownFields()
if d.Decode(target) != nil || d.Decode(&extra) != io.EOF {
return qaopsquality.ErrInvalid
}
return nil
}
func qaQualityReview(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-quality") {
return
}
var request qaopsquality.SaveRequest
if decodeQualityJSON(w, r, &request, "input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason") != nil || qaopsquality.Validate(request) != nil {
writeQualityError(w, qaopsquality.ErrInvalid)
return
}
if c.QAQuality == nil || c.QAOps == nil || c.QAOpsTenantKey == "" {
writeQualityError(w, qaopsquality.ErrUnavailable)
return
}
record, err := c.QAOps.GetRecord(r.Context(), c.QAOpsTenantKey, r.PathValue("id"))
if err != nil {
qaOpsError(w, err)
return
}
identity, _ := sessionFrom(r.Context())
receipt, err := c.QAQuality.Save(r.Context(), record, request, identity.Username)
if err != nil {
writeQualityError(w, err)
return
}
writeJSON(w, 200, map[string]any{"data": receipt})
}
func qaQualityQuery(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-quality") {
return
}
var request struct {
Start string `json:"start"`
End string `json:"end"`
Keyword string `json:"keyword"`
}
if decodeQualityJSON(w, r, &request) != nil {
writeQualityError(w, qaopsquality.ErrInvalid)
return
}
window, err := dobotaiops.NewWindow(c.QAOpsTenantKey, request.Start, request.End, 90*24*time.Hour, c.Now())
if err != nil {
writeQualityError(w, err)
return
}
reader, ok := c.QAOps.(qaQualityReader)
if !ok || c.QAQuality == nil {
writeQualityError(w, qaopsquality.ErrUnavailable)
return
}
scope, err := reader.ReadQualityScope(r.Context(), dobotaiops.RecordQuery{Window: window, Keyword: request.Keyword})
if err != nil {
qaOpsError(w, err)
return
}
views, err := c.QAQuality.ObserveKeys(r.Context(), scope.Keys)
if err != nil || len(views) != len(scope.Keys) {
if err == nil {
err = qaopsquality.ErrUnavailable
}
writeQualityError(w, err)
return
}
writeJSON(w, 200, map[string]any{"data": map[string]any{"summary": qaopsquality.Summarize(views), "start": window.Start, "end": window.End, "keyword": request.Keyword, "as_of": scope.AsOf, "ai_state": "not_configured", "scope": "whole_filter"}})
}
func qaQualityHistory(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
if c.QAQuality == nil {
writeQualityError(w, qaopsquality.ErrUnavailable)
return
}
values := r.URL.Query()
for key, v := range values {
if (key != "review_before" && key != "check_before") || len(v) != 1 {
writeQualityError(w, qaopsquality.ErrInvalid)
return
}
}
cursors := map[string]int64{}
for _, key := range []string{"review_before", "check_before"} {
raw := values.Get(key)
if raw == "" {
continue
}
n, err := strconv.ParseInt(raw, 10, 64)
if err != nil || n < 1 {
writeQualityError(w, qaopsquality.ErrInvalid)
return
}
cursors[key] = n
}
value, err := c.QAQuality.History(r.Context(), r.PathValue("id"), cursors["review_before"], cursors["check_before"])
if err != nil {
writeQualityError(w, err)
return
}
writeJSON(w, 200, map[string]any{"data": value})
}
func qaQualitySnapshot(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
epoch, err := strconv.ParseInt(r.PathValue("epoch"), 10, 64)
if err != nil || epoch < 1 || r.URL.RawQuery != "" {
writeQualityError(w, qaopsquality.ErrInvalid)
return
}
if c.QAQuality == nil {
writeQualityError(w, qaopsquality.ErrUnavailable)
return
}
value, err := c.QAQuality.Snapshot(r.Context(), r.PathValue("id"), epoch)
if err != nil {
writeQualityError(w, err)
return
}
writeJSON(w, 200, map[string]any{"data": value})
}
+171
View File
@@ -0,0 +1,171 @@
package httpapi
import (
"context"
"encoding/json"
"knowledge-governance/internal/dobotaiops"
"knowledge-governance/internal/qaopsquality"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
)
type qualityFake struct {
actor string
calls int
fail bool
}
func (s *qualityFake) Observe(_ context.Context, records []dobotaiops.Record) (map[string]qaopsquality.View, error) {
s.calls++
if s.fail {
return nil, qaopsquality.ErrUnavailable
}
out := map[string]qaopsquality.View{}
for _, r := range records {
e, _ := qaopsquality.EvidenceFor(r)
out[r.ID] = qaopsquality.Project(e.Hash, 1, 0, qaopsquality.Check{InputEpoch: 1, InputHash: e.Hash, Result: dobotaiops.CheckAnswerCoverage(r.Answer)}, nil)
}
return out, nil
}
func (s *qualityFake) ObserveKeys(_ context.Context, keys []dobotaiops.QualityKey) (map[string]qaopsquality.View, error) {
s.calls++
out := map[string]qaopsquality.View{}
for _, key := range keys {
out[key.ID] = qaopsquality.Project(key.InputHash, 1, 0, qaopsquality.Check{Result: dobotaiops.CheckMarkerCoverage(key.Marker)}, nil)
}
return out, nil
}
func (s *qualityFake) Save(_ context.Context, r dobotaiops.Record, q qaopsquality.SaveRequest, actor string) (qaopsquality.Receipt, error) {
s.actor = actor
v := qaopsquality.Project(q.InputHash, 1, 1, qaopsquality.Check{Result: dobotaiops.CheckAnswerCoverage(r.Answer)}, &qaopsquality.Review{InputEpoch: 1, InputHash: q.InputHash, Fields: q.Fields, Reason: q.Reason, Reviewer: actor})
return qaopsquality.Receipt{View: v, SavedRevision: 1}, nil
}
func (s *qualityFake) Columns(_ context.Context, keys []dobotaiops.QualityKey) ([]string, error) {
return []string{"is_correct", "product_category"}, nil
}
func (s *qualityFake) History(context.Context, string, int64, int64) (qaopsquality.History, error) {
return qaopsquality.History{Reviews: []qaopsquality.Review{}, Checks: []qaopsquality.Check{}}, nil
}
func (s *qualityFake) Snapshot(context.Context, string, int64) (qaopsquality.Snapshot, error) {
return qaopsquality.Snapshot{}, qaopsquality.ErrNotFound
}
type qualitySource struct {
attributedReader
record dobotaiops.Record
tenant string
scopeCalls int
}
func (s *qualitySource) GetRecord(_ context.Context, tenant, id string) (dobotaiops.Record, error) {
s.tenant = tenant
return s.record, nil
}
func (s *qualitySource) ListRecords(_ context.Context, q dobotaiops.RecordQuery) (dobotaiops.RecordPage, error) {
return dobotaiops.RecordPage{Items: []dobotaiops.Record{s.record}, Columns: []string{"question"}, Total: 2, AsOf: time.Now()}, nil
}
func (s *qualitySource) ReadQualityScope(_ context.Context, q dobotaiops.RecordQuery) (dobotaiops.QualityScope, error) {
s.scopeCalls++
s.tenant = q.Window.TenantKey
second := s.record
second.ID = "second-turn"
keys := []dobotaiops.QualityKey{}
for _, r := range []dobotaiops.Record{s.record, second} {
e, _ := qaopsquality.EvidenceFor(r)
keys = append(keys, dobotaiops.QualityKey{ID: r.ID, InputHash: e.Hash, Marker: e.Result.Verdict == "uncovered", Source: r.SourceCoverage})
}
return dobotaiops.QualityScope{Keys: keys, AsOf: time.Now()}, nil
}
func qualityTestHandler(t *testing.T) (http.Handler, *qualityFake, *qualitySource) {
t.Helper()
store := &qualityFake{}
source := &qualitySource{record: dobotaiops.Record{ID: "fixture-turn", Status: "succeeded", Question: "示例", Answer: "暂无已发布"}}
auth := newFakeAuthStore()
auth.sessions["quality-admin"] = "usr-boss"
auth.sessions["quality-viewer"] = "usr-eye"
h, e := NewHandler(Config{Store: &fakeJobStore{}, Auth: &AuthConfig{Store: auth}, QAOps: source, QAOpsTenantKey: "fixed", QAQuality: store, Now: func() time.Time { return time.Date(2026, 10, 17, 0, 0, 0, 0, time.UTC) }})
if e != nil {
t.Fatal(e)
}
return h, store, source
}
func qualityRequest(h http.Handler, method, path, token, body string) *httptest.ResponseRecorder {
r := httptest.NewRequest(method, path, strings.NewReader(body))
r.Header.Set("Content-Type", "application/json")
r.Header.Set("X-Governance-Action", "qa-quality")
if token != "" {
r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: token})
}
w := httptest.NewRecorder()
h.ServeHTTP(w, r)
return w
}
func TestQAQualityDetailListAndWholeScopeCounts(t *testing.T) {
h, store, source := qualityTestHandler(t)
w := qualityRequest(h, "GET", "/api/v1/qa-ops/records/fixture-turn", "quality-admin", "")
if w.Code != 200 || !strings.Contains(w.Body.String(), `"quality"`) {
t.Fatal("persisted quality absent in detail", w.Code)
}
w = qualityRequest(h, "GET", "/api/v1/qa-ops/records?start=2026-10-14T00:00:00Z&end=2026-10-15T00:00:00Z", "quality-admin", "")
if w.Code != 200 || !strings.Contains(w.Body.String(), `"is_correct"`) {
t.Fatal("whole-filter quality columns absent")
}
w = qualityRequest(h, "POST", "/api/v1/qa-ops/quality/query", "quality-admin", `{"start":"2026-10-14T00:00:00Z","end":"2026-10-15T00:00:00Z","keyword":""}`)
if w.Code != 200 || !strings.Contains(w.Body.String(), `"unreviewed":2`) || source.scopeCalls != 1 || source.tenant != "fixed" || store.calls < 2 {
t.Fatal("quality summary estimated from page instead of scope", w.Code, w.Body.String())
}
store.fail = true
w = qualityRequest(h, "GET", "/api/v1/qa-ops/records/fixture-turn", "quality-admin", "")
if w.Code != 503 || !strings.Contains(w.Body.String(), "quality_unavailable") {
t.Fatal("quality storage failure presented as empty success")
}
}
func TestQAQualityReviewUsesSessionActorAndStrictReadOnlySourceBoundary(t *testing.T) {
h, store, source := qualityTestHandler(t)
e, _ := qaopsquality.EvidenceFor(source.record)
q := qaopsquality.SaveRequest{InputHash: e.Hash, InputEpoch: 1, Nonce: strings.Repeat("n", 32), Fields: qaopsquality.Fields{Coverage: "uncovered", Correctness: "pending"}, Reason: "人工核对"}
raw, _ := json.Marshal(q)
path := "/api/v1/qa-ops/records/fixture-turn/reviews"
w := qualityRequest(h, "POST", path, "quality-admin", string(raw))
if w.Code != 200 || store.actor != "boss" || source.tenant != "fixed" {
t.Fatal("manual review failed or actor came from request", w.Code, store.actor)
}
for _, tc := range []struct {
token, body string
status int
}{{"", string(raw), 401}, {"quality-viewer", string(raw), 403}, {"quality-admin", strings.TrimSuffix(string(raw), "}") + `,"reviewer":"forged"}`, 400}, {"quality-admin", `null`, 400}, {"quality-admin", string(raw) + `{}`, 400}, {"quality-admin", `{"nonce":"a","nonce":"b"}`, 400}} {
w = qualityRequest(h, "POST", path, tc.token, tc.body)
if w.Code != tc.status {
t.Fatal("review boundary failed", w.Code, tc.status)
}
}
r := httptest.NewRequest("POST", path, strings.NewReader(string(raw)))
r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "quality-admin"})
r.Header.Set("X-Governance-Action", "qa-quality")
r.Header.Set("Sec-Fetch-Site", "cross-site")
w = httptest.NewRecorder()
h.ServeHTTP(w, r)
if w.Code != 403 {
t.Fatal("cross-site review accepted")
}
w = qualityRequest(h, "GET", path+"/invalid", "quality-admin", "")
if w.Code != 404 {
t.Fatal("unknown endpoint silently accepted")
}
}
func TestQAQualityReviewRejectsMissingRevisionAndNestedNull(t *testing.T) {
h, _, source := qualityTestHandler(t)
e, _ := qaopsquality.EvidenceFor(source.record)
q := qaopsquality.SaveRequest{InputHash: e.Hash, InputEpoch: 1, Nonce: strings.Repeat("n", 32), Fields: qaopsquality.Fields{Coverage: "pending", Correctness: "pending"}, Reason: "示例复核"}
raw, _ := json.Marshal(q)
for _, body := range []string{strings.Replace(string(raw), `"base_revision":0,`, "", 1), strings.Replace(string(raw), `"base_revision":0`, `"base_revision":null`, 1), strings.Replace(string(raw), `"product_category":""`, `"product_category":null`, 1)} {
w := qualityRequest(h, "POST", "/api/v1/qa-ops/records/fixture-turn/reviews", "quality-admin", body)
if w.Code != 400 {
t.Fatal("missing/null version or field silently became a default", w.Code)
}
}
}
+6
View File
@@ -102,6 +102,7 @@ type Store interface {
}
type Config struct {
QAQuality QAQualityStore
QAOrgSync QAOrgSyncStore
QAOrgSyncEnabled bool
QAOrg QAOrgStore
@@ -175,6 +176,11 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
mux.HandleFunc("POST /api/v1/qa-ops/quality/query", func(w http.ResponseWriter, r *http.Request) { qaQualityQuery(w, r, config) })
mux.HandleFunc("POST /api/v1/qa-ops/records/{id}/reviews", func(w http.ResponseWriter, r *http.Request) { qaQualityReview(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/records/{id}/quality/history", func(w http.ResponseWriter, r *http.Request) { qaQualityHistory(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/records/{id}/quality/inputs/{epoch}", func(w http.ResponseWriter, r *http.Request) { qaQualitySnapshot(w, r, config) })
mux.HandleFunc("POST /api/v1/qa-ops/usage/people", func(w http.ResponseWriter, r *http.Request) { qaMonthlyPeople(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/usage", func(w http.ResponseWriter, r *http.Request) { qaOpsUsage(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })