308 lines
12 KiB
Go
308 lines
12 KiB
Go
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
|
||
}
|