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 }