Files
knowledge-governance/internal/dobotaiops/repository.go
T

308 lines
12 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 dobotaiops
import (
"context"
"encoding/json"
"fmt"
"strings"
"time"
)
// 本阶段只读查询模块(工单第 4 项)。纪律:
// - 一律绑定参数;列固定;不拼接调用方给的 SQL/排序字段;
// - 时间统一半开区间 created_at >= $start AND created_at < $end;
// - 按 turn 计次;跨租户/渠道的连接同时校验 tenant_key 与 channel;
// - 只走 REPEATABLE READ + READ ONLY 事务,口径固定在同一个 as_of 上。
const countsTotalSQL = `
SELECT count(*)::bigint
FROM turns
WHERE tenant_key = $1 AND created_at >= $2 AND created_at < $3
AND ($4 = '' OR channel = $4) AND ($5 = '' OR status = $5)`
const countsBySQL = `
SELECT %s, count(*)::bigint
FROM turns
WHERE tenant_key = $1 AND created_at >= $2 AND created_at < $3
AND ($4 = '' OR channel = $4) AND ($5 = '' OR status = $5)
GROUP BY 1
ORDER BY 1`
// QueryCounts 返回某租户在窗口内的问答总量与状态/渠道分组(按 turn 计次)。
func (c *Client) QueryCounts(ctx context.Context, window Window, filter Filter) (CountsResult, error) {
if err := filter.Validate(); err != nil {
return CountsResult{}, err
}
if err := c.validateQueryWindow(window); err != nil {
return CountsResult{}, err
}
result := CountsResult{TenantKey: window.TenantKey, Start: window.Start, End: window.End,
ByStatus: map[string]int64{}, ByChannel: map[string]int64{}}
err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
if err := q.QueryRow(ctx, countsTotalSQL, window.TenantKey, window.Start, window.End, filter.Channel, filter.Status).
Scan(&result.Total); err != nil {
return fmt.Errorf("%w: total count failed", ErrUnavailable)
}
statusRows, err := q.Query(ctx, fmt.Sprintf(countsBySQL, "status"), window.TenantKey, window.Start, window.End, filter.Channel, filter.Status)
if err != nil {
return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
}
defer statusRows.Close()
for statusRows.Next() {
var status string
var count int64
if err := statusRows.Scan(&status, &count); err != nil {
return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
}
result.ByStatus[status] = count
}
channelRows, err := q.Query(ctx, fmt.Sprintf(countsBySQL, "channel"), window.TenantKey, window.Start, window.End, filter.Channel, filter.Status)
if err != nil {
return fmt.Errorf("%w: channel grouping failed", ErrUnavailable)
}
defer channelRows.Close()
for channelRows.Next() {
var channel string
var count int64
if err := channelRows.Scan(&channel, &count); err != nil {
return fmt.Errorf("%w: channel grouping failed", ErrUnavailable)
}
result.ByChannel[channel] = count
}
if err := statusRows.Err(); err != nil {
return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
}
return channelRows.Err()
})
if err != nil {
return CountsResult{}, err
}
return result, nil
}
const coverageByVersionSQL = `
SELECT c.evaluator_version, c.verdict, c.reason_code, count(DISTINCT c.turn_id)::bigint
FROM coverage_decisions c
JOIN turns t ON t.id = c.turn_id AND t.tenant_key = c.tenant_key AND t.channel = c.channel
WHERE t.tenant_key = $1 AND t.created_at >= $2 AND t.created_at < $3
GROUP BY 1, 2, 3
ORDER BY 1, 2, 3`
const succeededTurnStatsSQL = `
SELECT count(*)::bigint,
count(*) FILTER (
WHERE NOT EXISTS (
SELECT 1 FROM coverage_decisions c
WHERE c.turn_id = t.id AND c.tenant_key = t.tenant_key AND c.channel = t.channel
)
)::bigint
FROM turns t
WHERE t.tenant_key = $1 AND t.status = 'succeeded' AND t.created_at >= $2 AND t.created_at < $3`
// QueryRuleCoverage 返回规则覆盖分组与"成功 turn 缺决策"量。
// 注意:这是 rule_coverage(规则决策),**不是** AI 正确率或正式知识覆盖率;
// 不同 evaluator_version 的口径不会混算。
func (c *Client) QueryRuleCoverage(ctx context.Context, window Window) (CoverageResult, error) {
if err := c.validateQueryWindow(window); err != nil {
return CoverageResult{}, err
}
result := CoverageResult{NotAnAccuracyMeasure: "rule_coverage 只是规则决策覆盖;v5 的 covered 含非知识响应/纯视觉识别,不能当 AI 正确率或正式知识覆盖率"}
err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
rows, err := q.Query(ctx, coverageByVersionSQL, window.TenantKey, window.Start, window.End)
if err != nil {
return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
}
defer rows.Close()
for rows.Next() {
var group CoverageGroup
if err := rows.Scan(&group.EvaluatorVersion, &group.Verdict, &group.ReasonCode, &group.Turns); err != nil {
return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
}
result.Groups = append(result.Groups, group)
}
if err := rows.Err(); err != nil {
return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
}
if err := q.QueryRow(ctx, succeededTurnStatsSQL, window.TenantKey, window.Start, window.End).
Scan(&result.SucceededTurns, &result.SucceededWithoutDecision); err != nil {
return fmt.Errorf("%w: succeeded turn stats failed", ErrUnavailable)
}
return nil
})
if err != nil {
return CoverageResult{}, err
}
return result, nil
}
const listTurnMetadataSQL = `
SELECT t.id, t.created_at, t.status, t.channel, t.agent_id, t.knowledge_searched,
CASE WHEN jsonb_typeof(t.references_json) = 'array' THEN jsonb_array_length(t.references_json) ELSE 0 END,
linked.total,
COALESCE(linked.department_missing, TRUE),
COALESCE(linked.region_missing, TRUE)
FROM turns t
LEFT JOIN LATERAL (
SELECT count(*)::int AS total,
bool_and(COALESCE(m.department_snapshot, '') = '') AS department_missing,
bool_and(COALESCE(m.region_snapshot, '') = '') AS region_missing
FROM messages m
WHERE m.tenant_key = t.tenant_key AND m.channel = t.channel
AND m.id = ANY(array_remove(ARRAY[t.request_message_id, t.answer_message_id], NULL))
) linked ON TRUE
WHERE t.tenant_key = $1 AND t.created_at >= $2 AND t.created_at < $3
AND ($4::timestamptz IS NULL OR (t.created_at, t.id) < ($4::timestamptz, $5::text))
ORDER BY t.created_at DESC, t.id DESC
LIMIT $6`
// ListTurnMetadata 用 (created_at, id) 游标稳定翻页(倒序);limit 硬上限 100。
// 返回的是元数据:不含正文、不含员工个人值;部门/区域快照为空如实标记为 missing。
func (c *Client) ListTurnMetadata(ctx context.Context, window Window, cursor string, limit int) (TurnMetadataPage, error) {
if err := c.validateQueryWindow(window); err != nil {
return TurnMetadataPage{}, err
}
if limit <= 0 {
limit = 50
}
if limit > c.config.MaxPageSize {
return TurnMetadataPage{}, fmt.Errorf("%w: limit exceeds %d", ErrInvalidQuery, c.config.MaxPageSize)
}
var decoded Cursor
var cursorTime *time.Time
if strings.TrimSpace(cursor) != "" {
value, err := DecodeCursor(cursor)
if err != nil {
return TurnMetadataPage{}, err
}
decoded = value
cursorTime = &decoded.CreatedAt
}
page := TurnMetadataPage{}
err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
rows, err := q.Query(ctx, listTurnMetadataSQL, window.TenantKey, window.Start, window.End, cursorTime, decoded.ID, limit+1)
if err != nil {
return fmt.Errorf("%w: turn listing failed", ErrUnavailable)
}
defer rows.Close()
for rows.Next() {
var item TurnMetadata
if err := rows.Scan(&item.ID, &item.CreatedAt, &item.Status, &item.Channel, &item.AgentID,
&item.KnowledgeSearched, &item.ReferenceCount, &item.LinkedMessages,
&item.DepartmentMissing, &item.RegionMissing); err != nil {
return fmt.Errorf("%w: turn listing failed", ErrUnavailable)
}
page.Items = append(page.Items, item)
}
return rows.Err()
})
if err != nil {
return TurnMetadataPage{}, err
}
if len(page.Items) > limit {
// 多取一条只为判断是否还有下一页;游标必须指向**最后一条真正返回的行**,
// 否则下一页会跳过那一条(集成测试专门钉这个边界)。
page.Items = page.Items[:limit]
page.HasMore = true
tail := page.Items[len(page.Items)-1]
page.NextCursor = EncodeCursor(Cursor{CreatedAt: tail.CreatedAt.UTC(), ID: tail.ID})
}
return page, nil
}
const authorizedTurnSQL = `
SELECT t.id, t.created_at, t.status, t.channel, t.agent_id, t.question, t.answer,
COALESCE(t.references_json::text, '[]'), t.error_message
FROM turns t
WHERE t.tenant_key = $1 AND t.id = $2`
const authorizedMessagesSQL = `
SELECT m.id, m.created_at, m.direction, m.role, m.message_type, m.status, m.text_content,
a.id IS NOT NULL,
COALESCE(a.actor_type, '')
FROM messages m
LEFT JOIN channel_actors a
-- 关联字段必须是 channel_actors.id:生产 FK 是 messages.actor_id → channel_actors(id)。
-- 用 external_actor_id 关联在生产对拍里命中 0 行(正确关联 2234 行)。
ON a.tenant_key = m.tenant_key AND a.channel = m.channel AND a.id = m.actor_id
WHERE m.tenant_key = $1 AND m.channel = $2
AND m.id = ANY(array_remove(ARRAY[$3, $4], NULL))
ORDER BY m.created_at, m.id`
// GetTurnForAuthorizedRead 按租户 + turn_id 读取正文/引用(必要时)。
// **必须**传入授权回调(返回错误即拒绝);本函数不提供"默认放行",测试输出也不应打印原文或员工个人值。
func (c *Client) GetTurnForAuthorizedRead(ctx context.Context, tenantKey, turnID string, authorize func(turnID string) error) (TurnDetail, error) {
if authorize == nil {
return TurnDetail{}, fmt.Errorf("%w: an explicit authorization callback is required", ErrInvalidQuery)
}
if strings.TrimSpace(tenantKey) == "" || strings.TrimSpace(turnID) == "" {
return TurnDetail{}, fmt.Errorf("%w: tenant and turn id are required", ErrInvalidQuery)
}
if err := authorize(turnID); err != nil {
return TurnDetail{}, fmt.Errorf("%w: turn read is not authorized", ErrInvalidQuery)
}
detail := TurnDetail{}
var references string
var requestID, answerID *string
err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
if err := q.QueryRow(ctx, authorizedTurnSQL, tenantKey, turnID).Scan(
&detail.ID, &detail.CreatedAt, &detail.Status, &detail.Channel, &detail.AgentID,
&detail.Question, &detail.Answer, &references, &detail.ErrorCode); err != nil {
return fmt.Errorf("%w: turn could not be read", ErrUnavailable)
}
detail.ReferencesJSON = []byte(references)
if !json.Valid(detail.ReferencesJSON) {
detail.ReferencesJSON = []byte("[]")
}
// request/answer 两条消息 id 需要一起取:单独查一次拿 id 列表,避免把正文带进列表接口。
if err := q.QueryRow(ctx, `SELECT request_message_id, answer_message_id FROM turns WHERE tenant_key = $1 AND id = $2`, tenantKey, turnID).
Scan(&requestID, &answerID); err != nil {
return fmt.Errorf("%w: turn could not be read", ErrUnavailable)
}
rows, err := q.Query(ctx, authorizedMessagesSQL, tenantKey, detail.Channel, requestID, answerID)
if err != nil {
return fmt.Errorf("%w: turn messages could not be read", ErrUnavailable)
}
defer rows.Close()
for rows.Next() {
var message TurnMessage
if err := rows.Scan(&message.ID, &message.CreatedAt, &message.Direction, &message.Role,
&message.MessageType, &message.Status, &message.Text, &message.ActorLinked, &message.ActorType); err != nil {
return fmt.Errorf("%w: turn messages could not be read", ErrUnavailable)
}
detail.Messages = append(detail.Messages, message)
}
return rows.Err()
})
if err != nil {
return TurnDetail{}, err
}
return detail, nil
}
// validateQueryWindow 是仓储入口的**完整**校验:不能只靠 NewWindow —— 调用方完全可以
// 自己拼一个 Window 结构体绕过它(独立探测已证明)。这里把租户、半开区间、跨度上限
// 与"不允许未来窗口"全部落实在每次查询上。
func (c *Client) validateQueryWindow(window Window) error {
if strings.TrimSpace(window.TenantKey) == "" {
return fmt.Errorf("%w: tenant key is required", ErrInvalidQuery)
}
if window.Start.IsZero() || window.End.IsZero() || !window.Start.Before(window.End) {
return fmt.Errorf("%w: window is invalid", ErrInvalidQuery)
}
limit := c.config.MaxWindow
if limit <= 0 {
limit = 90 * 24 * time.Hour
}
if window.End.Sub(window.Start) > limit {
return fmt.Errorf("%w: window exceeds the %s limit", ErrInvalidQuery, limit)
}
now := time.Now()
if c.config.Now != nil {
now = c.config.Now()
}
if window.End.After(now.Add(5 * time.Minute)) {
return fmt.Errorf("%w: window end is in the future", ErrInvalidQuery)
}
return nil
}