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

126 lines
4.1 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 (
"errors"
"fmt"
"time"
)
// ErrInvalidQuery:调用方给的参数不合法(租户、时间范围、游标、分页、通道/状态枚举)。
// 这类错误绝不触发任何重试,也不应该被当成"外部库不可用"。
var ErrInvalidQuery = errors.New("invalid dobotai read query")
// Filter 是统计/列举的可选过滤条件。通道与状态只做白名单校验 + 绑定参数,不拼接 SQL。
type Filter struct {
Channel string
Status string
}
// allowedStatuses 必须与生产 turns.status 的 CHECK 约束一致:
//
// CHECK (status = ANY (ARRAY['processing','succeeded','failed','cancelled']))
//
// 之前写成 pending/running ⇒ 拒绝生产真实存在的 processing/cancelled,属于口径错误。
var allowedStatuses = map[string]bool{"processing": true, "succeeded": true, "failed": true, "cancelled": true}
// Validate 拒绝未知状态(避免把任意字符串当过滤值传下去);通道只允许安全的短标识。
func (f Filter) Validate() error {
if f.Status != "" && !allowedStatuses[f.Status] {
return fmt.Errorf("%w: unknown status", ErrInvalidQuery)
}
if f.Channel != "" {
if len(f.Channel) > 32 {
return fmt.Errorf("%w: channel too long", ErrInvalidQuery)
}
for _, r := range f.Channel {
switch {
case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_' || r == '-' || r == '.':
default:
return fmt.Errorf("%w: channel contains unsupported characters", ErrInvalidQuery)
}
}
}
return nil
}
// CountsResult:某一时间窗内某租户的问答总量与状态/渠道分组(半开区间,按 turn 计次)。
type CountsResult struct {
TenantKey string
Start time.Time
End time.Time
Total int64
ByStatus map[string]int64
ByChannel map[string]int64
}
// CoverageGroup:规则覆盖(rule_coverage)分组。注意 evaluator_version 必须保留 —— 不同版本口径不可混算。
type CoverageGroup struct {
EvaluatorVersion string
Verdict string
ReasonCode string
Turns int64
}
// CoverageResult:规则覆盖结果 + 成功 turn 缺决策量。
// 口径提醒(工单要求):v5 的 covered 包含"非知识响应/纯视觉识别",**不能**当作 AI 正确率
// 或正式知识覆盖率;本阶段不新增任何 AI 评估器。
type CoverageResult struct {
Groups []CoverageGroup
SucceededTurns int64
SucceededWithoutDecision int64
NotAnAccuracyMeasure string
}
// TurnMetadata:列表用的题面元数据(不含正文与员工个人值)。
type TurnMetadata struct {
ID string
CreatedAt time.Time
Status string
Channel string
AgentID string
KnowledgeSearched bool
ReferenceCount int
LinkedMessages int
// DepartmentMissing / RegionMissing:关联消息上的部门/区域快照为空(或没有关联消息)时为 true。
// 生产当前这两列为空 ⇒ 如实返回 unknown,不补写、不猜。
DepartmentMissing bool
RegionMissing bool
}
type TurnMetadataPage struct {
Items []TurnMetadata
NextCursor string
HasMore bool
}
// TurnMessage:授权读取时才返回的消息正文(含员工内容,必须经授权回调)。
type TurnMessage struct {
ID string
CreatedAt time.Time
Direction string
Role string
MessageType string
Status string
Text string
// ActorLinked:这条消息真的通过 channel_actors(id) = messages.actor_id 关联到了 actor;
// ActorType 只带类型,不带 display_name(避免把员工个人值撒出去)。
// 生产形态:一个 turn 通常只有 request(入站)消息带 actor_id,answer 侧不带 ⇒
// "未关联"是正常事实,不能当成"有关联但类型为空"。
ActorLinked bool
ActorType string
}
// TurnDetail:按租户 + turn_id 的授权读取结果。
type TurnDetail struct {
ID string
CreatedAt time.Time
Status string
Channel string
AgentID string
Question string
Answer string
ReferencesJSON []byte
ErrorCode string
Messages []TurnMessage
}