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 }