139 lines
5.3 KiB
Go
139 lines
5.3 KiB
Go
package audit
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"time"
|
|
)
|
|
|
|
var (
|
|
ErrNotFound = errors.New("turn not found")
|
|
ErrInvalidArgument = errors.New("invalid audit query")
|
|
)
|
|
|
|
// TurnStatus represents the status of a turn.
|
|
type TurnStatus string
|
|
|
|
const (
|
|
StatusProcessing TurnStatus = "processing"
|
|
StatusSucceeded TurnStatus = "succeeded"
|
|
StatusFailed TurnStatus = "failed"
|
|
StatusCancelled TurnStatus = "cancelled"
|
|
)
|
|
|
|
// TurnSummary is a lightweight representation of a turn for list views.
|
|
// It must never contain full question/answer text, error_message, WeKnora
|
|
// session/request IDs, or provider_message_id.
|
|
type TurnSummary struct {
|
|
ID string `json:"id"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
Channel string `json:"channel"`
|
|
Status TurnStatus `json:"status"`
|
|
ConversationType string `json:"conversation_type"`
|
|
ConversationTitle string `json:"conversation_title,omitempty"`
|
|
ActorExternalID string `json:"actor_external_id,omitempty"`
|
|
ActorDisplayName string `json:"actor_display_name,omitempty"`
|
|
QuestionSummary string `json:"question_summary"`
|
|
AnswerSummary string `json:"answer_summary"`
|
|
ReferenceCount int `json:"reference_count"`
|
|
AnswerDeliveryStatus string `json:"answer_delivery_status,omitempty"`
|
|
AnswerDeliveryMethod string `json:"answer_delivery_method,omitempty"`
|
|
FeedbackUpCount int `json:"feedback_up_count"`
|
|
FeedbackDownCount int `json:"feedback_down_count"`
|
|
FeedbackUnresolvedCount int `json:"feedback_unresolved_count"`
|
|
}
|
|
|
|
// SafeReference is a reference with only safe fields exposed.
|
|
// Content and Raw are never included.
|
|
type SafeReference struct {
|
|
ID string `json:"id"`
|
|
KnowledgeID string `json:"knowledge_id"`
|
|
KnowledgeTitle string `json:"knowledge_title"`
|
|
Score float64 `json:"score"`
|
|
}
|
|
|
|
// SafeMedia is a media audit entry with only safe metadata.
|
|
type SafeMedia struct {
|
|
Type string `json:"type"`
|
|
MIMEType string `json:"mime_type"`
|
|
SizeBytes int64 `json:"size_bytes"`
|
|
Width int `json:"width"`
|
|
Height int `json:"height"`
|
|
}
|
|
|
|
// MessageMeta provides request/answer message metadata.
|
|
type MessageMeta struct {
|
|
ID string `json:"id"`
|
|
Direction string `json:"direction"`
|
|
Role string `json:"role"`
|
|
MessageType string `json:"message_type"`
|
|
Status string `json:"status"`
|
|
ActorName string `json:"actor_name,omitempty"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
DeliveredAt *time.Time `json:"delivered_at,omitempty"`
|
|
DeliveryMethod string `json:"delivery_method,omitempty"`
|
|
FailureCode string `json:"failure_code,omitempty"`
|
|
}
|
|
|
|
// AnswerFeedback is the safe current feedback state for one actor. Provider
|
|
// tracking IDs, internal IDs and raw callback fields are intentionally absent.
|
|
type AnswerFeedback struct {
|
|
ActorExternalID string `json:"actor_external_id"`
|
|
ActorDisplayName string `json:"actor_display_name,omitempty"`
|
|
Value string `json:"value"`
|
|
ReasonCode string `json:"reason_code"`
|
|
UpdatedAt time.Time `json:"updated_at"`
|
|
}
|
|
|
|
// TurnDetail is the full detail view of a turn. It must never include
|
|
// error_message, WeKnora session/request ID, provider_message_id,
|
|
// sessionWebhook, tokens, raw API/error, or Reference.Content/Raw.
|
|
type TurnDetail struct {
|
|
ID string `json:"id"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
Channel string `json:"channel"`
|
|
Status TurnStatus `json:"status"`
|
|
ConversationType string `json:"conversation_type"`
|
|
ConversationTitle string `json:"conversation_title,omitempty"`
|
|
ActorExternalID string `json:"actor_external_id,omitempty"`
|
|
ActorDisplayName string `json:"actor_display_name,omitempty"`
|
|
Question string `json:"question"`
|
|
Answer string `json:"answer"`
|
|
References []SafeReference `json:"references,omitempty"`
|
|
Media []SafeMedia `json:"media,omitempty"`
|
|
RequestMessage *MessageMeta `json:"request_message,omitempty"`
|
|
AnswerMessage *MessageMeta `json:"answer_message,omitempty"`
|
|
ReferenceCount int `json:"reference_count"`
|
|
AnswerDeliveryStatus string `json:"answer_delivery_status,omitempty"`
|
|
AnswerDeliveryMethod string `json:"answer_delivery_method,omitempty"`
|
|
Feedback []AnswerFeedback `json:"feedback,omitempty"`
|
|
}
|
|
|
|
// ListTurnsRequest is the input for listing turns.
|
|
type ListTurnsRequest struct {
|
|
Limit int
|
|
Cursor string
|
|
Channel string
|
|
Status TurnStatus
|
|
}
|
|
|
|
// ListTurnsResult is the output of a list turns query.
|
|
type ListTurnsResult struct {
|
|
Items []TurnSummary `json:"items"`
|
|
NextCursor string `json:"next_cursor,omitempty"`
|
|
}
|
|
|
|
type ListQuery struct {
|
|
Limit int
|
|
Channel string
|
|
Status TurnStatus
|
|
BeforeCreatedAt *time.Time
|
|
BeforeID string
|
|
}
|
|
|
|
// TurnRepository is the data access interface for audit queries.
|
|
type TurnRepository interface {
|
|
ListTurns(ctx context.Context, tenantKey string, query ListQuery) ([]TurnSummary, error)
|
|
GetTurn(ctx context.Context, tenantKey, turnID string) (TurnDetail, error)
|
|
}
|