backend/pkg/notification/domain/usecase/notification.go

package usecase

// Import necessary packages
import (
	"context"
)

type NotificationUseCase interface {
	EventUseCase
	UserNotificationUseCase
	CursorUseCase
}
type NotificationEvent struct {
	EventType  string // POST_PUBLISHED / COMMENT_ADDED / MENTIONED ...
	ActorUID   string // 觸發者 UID
	ObjectType string // POST / COMMENT / USER ...
	ObjectID   string // 對應物件 ID（post_id 等）
	Title      string // 顯示用標題
	Body       string // 顯示用內容 / 摘要
	Payload    string // JSON string（額外欄位，例如 {"postId": "..."}）
	Priority   string //  critical, high, normal, low
}

type NotificationEventResp struct {
	EventID    string `json:"event_id"`
	EventType  string `json:"event_type"`
	ActorUID   string `json:"actor_uid"`
	ObjectType string `json:"object_type"`
	ObjectID   string `json:"object_id"`
	Title      string `json:"title"`
	Body       string `json:"body"`
	Payload    string `json:"payload"`
	Priority   string `json:"priority"`
	CreatedAt  string `json:"created_at"`
}

type QueryNotificationEventParam struct {
	ObjectID   *string
	ObjectType *string
	Limit      *int
}

type EventUseCase interface {
	// CreateEvent creates a new notification event.
	CreateEvent(ctx context.Context, e *NotificationEvent) error

	// GetEventByID retrieves an event by its ID.
	GetEventByID(ctx context.Context, id string) (*NotificationEventResp, error)

	// ListEventsByObject lists events related to a specific object.
	ListEventsByObject(ctx context.Context, param QueryNotificationEventParam) ([]*NotificationEventResp, error)
}

type UserNotification struct {
	UserID  string `json:"user_id"`  // 收通知的人
	EventID string `json:"event_id"` // 對應 notification_event.event_id
	TTL     int    `json:"ttl"`
}

type ListLatestOptions struct {
	UserID  string
	Buckets []string // e.g. []string{"202511", "202510"}
	Limit   int      // 建議在 service 層限制最大值，例如 <= 100
}

type UserNotificationResponse struct {
	UserID  string  `json:"user_id"`           // 收通知的人
	Bucket  string  `json:"bucket"`            // 分桶，例如 '2025-11' 或 '2025-11-17'
	TS      string  `json:"ts"`                // 通知時間，用 now() 產生，排序用(UTC0)
	EventID string  `json:"event_id"`          // 對應 notification_event.event_id
	Status  string  `json:"status"`            // UNREAD / READ / ARCHIVED
	ReadAt  *string `json:"read_at,omitempty"` // 已讀時間（非必填）
}

// UserNotificationUseCase  handles user-specific notification operations.
type UserNotificationUseCase interface {
	// CreateUserNotification creates a notification for a single user.
	CreateUserNotification(ctx context.Context, n *UserNotification) error

	// BulkCreateNotifications creates multiple notifications in batch.
	BulkCreateNotifications(ctx context.Context, list []*UserNotification) error

	// ListLatestNotifications lists the latest notifications for a user.
	ListLatestNotifications(ctx context.Context, opt ListLatestOptions) ([]*UserNotificationResponse, error)

	// MarkAsRead marks a single notification as read.
	MarkAsRead(ctx context.Context, userID, bucket string, ts string) error

	// MarkAllAsRead marks all notifications in specified buckets as read.
	MarkAllAsRead(ctx context.Context, userID string, buckets []string) error

	// CountUnread approximates the count of unread notifications.
	CountUnread(ctx context.Context, userID string, buckets []string) (int64, error)
}

type NotificationCursor struct {
	UID        string
	LastSeenTS string
	UpdatedAt  string
}

type UpdateNotificationCursorParam struct {
	UID        string
	LastSeenTS string
}

// CursorUseCase  handles notification cursor operations for efficient reading.
type CursorUseCase interface {
	// GetCursor retrieves the notification cursor for a user.
	GetCursor(ctx context.Context, userID string) (*NotificationCursor, error)

	// UpdateCursor updates or inserts the cursor for a user.
	UpdateCursor(ctx context.Context, cursor *UpdateNotificationCursorParam) error
}