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

88 lines
2.9 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 (
"encoding/base64"
"fmt"
"strings"
"time"
)
// Window 是一次只读统计/列举的时间范围,语义固定为**半开区间**:
// created_at >= Start AND created_at < End(工单要求)。
type Window struct {
TenantKey string
Start time.Time
End time.Time
}
// NewWindow 解析并校验调用方给的租户与时间范围:
// - 租户非空、长度受限(不做任何 SQL 拼接,只作为绑定参数);
// - 时间是 RFC3339(允许带时区),必须有 start < end;
// - 窗口跨度不超过上限(默认 90 天)、不允许跑到未来太远。
func NewWindow(tenantKey, startRaw, endRaw string, limit time.Duration, now time.Time) (Window, error) {
tenantKey = strings.TrimSpace(tenantKey)
if tenantKey == "" || len(tenantKey) > 128 {
return Window{}, fmt.Errorf("%w: tenant key is required", ErrInvalidQuery)
}
start, err := parseInstant(startRaw)
if err != nil {
return Window{}, err
}
end, err := parseInstant(endRaw)
if err != nil {
return Window{}, err
}
if !start.Before(end) {
return Window{}, fmt.Errorf("%w: start must be before end", ErrInvalidQuery)
}
if limit <= 0 {
limit = 90 * 24 * time.Hour
}
if end.Sub(start) > limit {
return Window{}, fmt.Errorf("%w: window exceeds the %s limit", ErrInvalidQuery, limit)
}
if end.After(now.Add(5 * time.Minute)) {
return Window{}, fmt.Errorf("%w: end is in the future", ErrInvalidQuery)
}
return Window{TenantKey: tenantKey, Start: start.UTC(), End: end.UTC()}, nil
}
func parseInstant(raw string) (time.Time, error) {
raw = strings.TrimSpace(raw)
if raw == "" {
return time.Time{}, fmt.Errorf("%w: time is required", ErrInvalidQuery)
}
parsed, err := time.Parse(time.RFC3339, raw)
if err != nil {
return time.Time{}, fmt.Errorf("%w: time must be RFC3339 (with offset)", ErrInvalidQuery)
}
return parsed.UTC(), nil
}
// Cursor 是 (created_at, id) 复合游标:与工单要求一致 —— 稳定、确定性、翻页不漏不重。
type Cursor struct {
CreatedAt time.Time
ID string
}
// EncodeCursor / DecodeCursor 只做无损编解码,不做业务判断;非法游标一律报 ErrInvalidQuery。
func EncodeCursor(cursor Cursor) string {
return base64.RawURLEncoding.EncodeToString([]byte(cursor.CreatedAt.UTC().Format(time.RFC3339Nano) + "|" + cursor.ID))
}
func DecodeCursor(raw string) (Cursor, error) {
decoded, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(raw))
if err != nil {
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
}
parts := strings.SplitN(string(decoded), "|", 2)
if len(parts) != 2 || parts[1] == "" {
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
}
createdAt, err := time.Parse(time.RFC3339Nano, parts[0])
if err != nil {
return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
}
return Cursor{CreatedAt: createdAt.UTC(), ID: parts[1]}, nil
}