Timeline Module (recerdo-timeline)¶

// Timeline Item - コア entity
type TimelineItem struct {
    ID         ULID
    UserID     *string           // item owner (可能性あり)
    OrgID      *string           // item 対象 org (可能性あり)
    EventID    *string           // 参照先 event (可能性あり)
    MediaID    *string           // 参照先 media (可能性あり)
    ItemType   TimelineItemType  // enum: EVENT_CREATED, ALBUM_CREATED, ...
    Payload    TimelinePayload   // JSON、item_type に応じた schema
    OccurredAt time.Time         // 実際に起きた時刻（immutable）
    CreatedAt  time.Time         // DB insert 時刻
    Visibility Visibility        // PUBLIC / FRIENDS / PRIVATE
    HiddenAt   *time.Time        // NULL = visible, non-NULL = hidden (soft delete)
}

func (t *TimelineItem) IsVisible(requestingUserID *string, permissionPort PermissionPort) (bool, error) {
    // PRIVATE: owner_id == requesting_user_id のみ
    if t.Visibility == VisibilityPRIVATE {
        if requestingUserID == nil || *requestingUserID != *t.UserID {
            return false, nil
        }
        return true, nil
    }
    // FRIENDS: friendship check via PermissionPort
    if t.Visibility == VisibilityFRIENDS {
        if requestingUserID == nil {
            return false, nil
        }
        ok, err := permissionPort.CheckFriendship(context.Background(), *requestingUserID, *t.UserID)
        if err != nil {
            return false, err
        }
        return ok, nil
    }
    // PUBLIC: 全員表示
    return true, nil
}

func (t *TimelineItem) Validate() error {
    if !t.ID.IsValid() {
        return ErrInvalidTimelineItemID
    }
    if t.ItemType == "" {
        return ErrInvalidItemType
    }
    if err := t.validatePayloadSchema(); err != nil {
        return err
    }
    if t.Visibility == "" {
        return ErrInvalidVisibility
    }
    if t.OccurredAt.After(time.Now()) {
        return ErrFutureOccurredAt
    }
    return nil
}

func (t *TimelineItem) validatePayloadSchema() error {
    switch t.ItemType {
    case ItemTypeEventCreated:
        required := []string{"event_id", "event_name", "description"}
        for _, field := range required {
            if !t.Payload.Has(field) {
                return ErrMissingPayloadField
            }
        }
    case ItemTypeAlbumCreated:
        required := []string{"album_id", "album_name", "album_thumbnail_url"}
        for _, field := range required {
            if !t.Payload.Has(field) {
                return ErrMissingPayloadField
            }
        }
    case ItemTypeMediaAdded:
        required := []string{"media_id", "media_url", "media_type"}
        for _, field := range required {
            if !t.Payload.Has(field) {
                return ErrMissingPayloadField
            }
    }
    // ... other item types
    return nil
}

// Visibility - Value Object
type Visibility string

const (
    VisibilityPUBLIC   Visibility = "PUBLIC"
    VisibilityFRIENDS  Visibility = "FRIENDS"
    VisibilityPRIVATE  Visibility = "PRIVATE"
)

func (v Visibility) IsValid() bool {
    return v == VisibilityPUBLIC || v == VisibilityFRIENDS || v == VisibilityPRIVATE
}

// FeedCursor - Value Object for pagination
type FeedCursor struct {
    LastSeenID       ULID
    LastSeenTimestamp int64 // unix seconds
}

func (c *FeedCursor) Encode() string {
    data := fmt.Sprintf("%s:%d", c.LastSeenID.String(), c.LastSeenTimestamp)
    return base64.StdEncoding.EncodeToString([]byte(data))
}

func DecodeFeedCursor(encoded string) (*FeedCursor, error) {
    data, err := base64.StdEncoding.DecodeString(encoded)
    if err != nil {
        return nil, ErrInvalidCursorFormat
    }
    parts := strings.Split(string(data), ":")
    if len(parts) != 2 {
        return nil, ErrInvalidCursorFormat
    }
    id, err := ParseULID(parts[0])
    if err != nil {
        return nil, ErrInvalidCursorID
    }
    ts, err := strconv.ParseInt(parts[1], 10, 64)
    if err != nil {
        return nil, ErrInvalidCursorTimestamp
    }
    return &FeedCursor{LastSeenID: id, LastSeenTimestamp: ts}, nil
}

// TimelinePayload - Value Object (JSON wrapper)
type TimelinePayload struct {
    data map[string]interface{}
}

func (p *TimelinePayload) Has(field string) bool {
    _, ok := p.data[field]
    return ok
}

func (p *TimelinePayload) Get(field string) (interface{}, error) {
    val, ok := p.data[field]
    if !ok {
        return nil, ErrPayloadFieldNotFound
    }
    return val, nil
}

func (p *TimelinePayload) Marshal() ([]byte, error) {
    return json.Marshal(p.data)
}

// TimelineItemType - enum
type TimelineItemType string

const (
    ItemTypeEventCreated               TimelineItemType = "EVENT_CREATED"
    ItemTypeAlbumCreated               TimelineItemType = "ALBUM_CREATED"
    ItemTypeMediaAdded                 TimelineItemType = "MEDIA_ADDED"
    ItemTypeFriendJoined               TimelineItemType = "FRIEND_JOINED"
    ItemTypeEventInvitationAccepted    TimelineItemType = "EVENT_INVITATION_ACCEPTED"
    ItemTypeHighlightVideoReady        TimelineItemType = "HIGHLIGHT_VIDEO_READY"
    ItemTypeMemoryShared               TimelineItemType = "MEMORY_SHARED"
)

func (t TimelineItemType) IsValid() bool {
    validTypes := map[TimelineItemType]bool{
        ItemTypeEventCreated:            true,
        ItemTypeAlbumCreated:            true,
        ItemTypeMediaAdded:              true,
        ItemTypeFriendJoined:            true,
        ItemTypeEventInvitationAccepted: true,
        ItemTypeHighlightVideoReady:     true,
        ItemTypeMemoryShared:            true,
    }
    return validTypes[t]
}

// UserFeed - aggregate root
type UserFeed struct {
    UserID    string
    Items     []TimelineItem
    Cursor    *FeedCursor
    HasMore   bool
}

func (f *UserFeed) AddItem(item TimelineItem) error {
    if !item.IsValid() {
        return ErrInvalidTimelineItem
    }
    f.Items = append(f.Items, item)
    return nil
}

// OrgTimeline - aggregate root
type OrgTimeline struct {
    OrgID      string
    Items      []TimelineItem
    ItemCount  int
    UpdatedAt  time.Time
}

func (o *OrgTimeline) AddItem(item TimelineItem) error {
    // org timeline には PUBLIC / FRIENDS items のみ許可
    if item.Visibility == VisibilityPRIVATE {
        return ErrPrivateItemsNotAllowedInOrgTimeline
    }
    o.Items = append(o.Items, item)
    o.ItemCount++
    o.UpdatedAt = time.Now()
    return nil
}

// Repository Ports
type TimelineItemRepository interface {
    // Create
    Create(ctx context.Context, item *TimelineItem) (ULID, error)

    // Query
    QueryUserTimeline(ctx context.Context, userID string, cursor *FeedCursor, limit int) ([]TimelineItem, error)
    QueryOrgTimeline(ctx context.Context, orgID string, cursor *FeedCursor, limit int) ([]TimelineItem, error)
    QueryUserFeed(ctx context.Context, userID string, friendIDs []string, cursor *FeedCursor, limit int) ([]TimelineItem, error)
    QueryByEventID(ctx context.Context, eventID string) ([]TimelineItem, error)
    QueryByItemType(ctx context.Context, itemType TimelineItemType) ([]TimelineItem, error)

    // Update
    Hide(ctx context.Context, timelineItemID ULID, reason string) error

    // Batch
    HideBatch(ctx context.Context, itemIDs []ULID, reason string) error
}

type FeedCacheRepository interface {
    // Redis cache for user feed (last 100 items)
    GetFeed(ctx context.Context, userID string) ([]TimelineItem, error)
    SetFeed(ctx context.Context, userID string, items []TimelineItem, ttl time.Duration) error
    InvalidateFeed(ctx context.Context, userID string) error
}

type OrgTimelineRepository interface {
    GetTimeline(ctx context.Context, orgID string, cursor *FeedCursor, limit int) (*OrgTimeline, error)
    UpdateTimeline(ctx context.Context, orgTimeline *OrgTimeline) error
}

// Service Ports
type PermissionPort interface {
    CheckFriendship(ctx context.Context, userID1, userID2 string) (bool, error)
    GetUser(ctx context.Context, userID string) (*User, error)
    GetFriendsOfUser(ctx context.Context, userID string) ([]string, error)
}

type EventServicePort interface {
    // QueuePort（Beta: Redis+BullMQ/asynq、本番: OCI Queue Service）consumer 経由で EventDeleted event 受け取り
    // → HideTimelineItem cascade
}

type ULIDGeneratorPort interface {
    Generate() ULID
}

type EventPublisherPort interface {
    PublishTimelineItemCreated(ctx context.Context, event TimelineItemCreated) error
    PublishTimelineItemHidden(ctx context.Context, event TimelineItemHidden) error
    PublishUserTimelineUpdated(ctx context.Context, event UserTimelineUpdated) error
}

// Controller / Handler Ports
type HTTPTimelineHandler interface {
    GetUserTimeline(w http.ResponseWriter, r *http.Request)
    GetOrgTimeline(w http.ResponseWriter, r *http.Request)
    GetUserFeed(w http.ResponseWriter, r *http.Request)
}

// QueueEventConsumerPort は QueuePort（Beta: Redis+BullMQ/asynq、本番: OCI Queue Service）から
// メッセージを取得して各 Consume ユースケースにディスパッチする。
type QueueEventConsumerPort interface {
    ConsumeEventServiceEvent(ctx context.Context, msg port.Job) error
    ConsumeFriendshipEvent(ctx context.Context, msg port.Job) error
    ConsumeEventDeletedEvent(ctx context.Context, msg port.Job) error
}

fx.Provide(
    // Repositories
    NewMySQLTimelineItemRepository,  // → TimelineItemRepository
    NewRedisFeedCacheRepository,          // → FeedCacheRepository
    NewMySQLOrgTimelineRepository,   // → OrgTimelineRepository

    // Service Adapters
    NewPermissionServiceGRPCAdapter,      // → PermissionPort
    NewQueueEventPublisher,               // → EventPublisherPort (Beta: Redis+BullMQ/asynq、本番: OCI Queue)
    NewQueueEventConsumer,                // → QueueEventConsumerPort

    // Utilities
    NewULIDGenerator,                     // → ULIDGeneratorPort

    // UseCases
    NewGetUserTimelineUseCase,
    NewGetOrgTimelineUseCase,
    NewGetUserFeedUseCase,
    NewCreateTimelineItemUseCase,
    NewHideTimelineItemUseCase,
    NewConsumeEventServiceEventUseCase,
    NewConsumeFriendshipEventUseCase,

    // Handlers
    NewHTTPTimelineHandler,
    NewQueueEventConsumer,
)

// Entity Test
func TestTimelineItem_IsVisible_PrivateItemOwnersOnly(t *testing.T) {
    item := &TimelineItem{
        ID:         generateULID(),
        UserID:     stringPtr("user-1"),
        ItemType:   ItemTypeEventCreated,
        Visibility: VisibilityPRIVATE,
        OccurredAt: time.Now(),
    }

    // owner が閲覧 → visible
    ok, err := item.IsVisible(stringPtr("user-1"), nil)
    assert.NoError(t, err)
    assert.True(t, ok)

    // non-owner が閲覧 → invisible
    ok, err = item.IsVisible(stringPtr("user-2"), nil)
    assert.NoError(t, err)
    assert.False(t, ok)

    // anonymous が閲覧 → invisible
    ok, err = item.IsVisible(nil, nil)
    assert.NoError(t, err)
    assert.False(t, ok)
}

func TestTimelineItem_IsVisible_FriendsItemRequiresRelation(t *testing.T) {
    item := &TimelineItem{
        ID:         generateULID(),
        UserID:     stringPtr("user-1"),
        ItemType:   ItemTypeEventCreated,
        Visibility: VisibilityFRIENDS,
        OccurredAt: time.Now(),
    }

    mockPerm := new(MockPermissionPort)
    mockPerm.On("CheckFriendship", context.Background(), "user-2", "user-1").Return(true, nil)

    ok, err := item.IsVisible(stringPtr("user-2"), mockPerm)
    assert.NoError(t, err)
    assert.True(t, ok)
    mockPerm.AssertCalled(t, "CheckFriendship", context.Background(), "user-2", "user-1")
}

func TestTimelineItem_IsVisible_PublicItemsVisible(t *testing.T) {
    item := &TimelineItem{
        ID:         generateULID(),
        UserID:     stringPtr("user-1"),
        ItemType:   ItemTypeEventCreated,
        Visibility: VisibilityPUBLIC,
        OccurredAt: time.Now(),
    }

    // anyone can view
    ok, err := item.IsVisible(stringPtr("user-2"), nil)
    assert.NoError(t, err)
    assert.True(t, ok)

    ok, err = item.IsVisible(nil, nil)
    assert.NoError(t, err)
    assert.True(t, ok)
}

func TestTimelineItem_Validate_InvalidPayloadSchema(t *testing.T) {
    item := &TimelineItem{
        ID:       generateULID(),
        ItemType: ItemTypeEventCreated,
        Payload: TimelinePayload{
            data: map[string]interface{}{
                // missing required "event_name"
                "event_id": "evt-123",
            },
        },
        OccurredAt: time.Now(),
        Visibility: VisibilityFRIENDS,
    }

    err := item.Validate()
    assert.ErrorIs(t, err, ErrMissingPayloadField)
}

func TestFeedCursor_EncodeDecode_RoundTrip(t *testing.T) {
    original := &FeedCursor{
        LastSeenID:        generateULID(),
        LastSeenTimestamp: time.Now().Unix(),
    }

    encoded := original.Encode()
    assert.NotEmpty(t, encoded)

    decoded, err := DecodeFeedCursor(encoded)
    assert.NoError(t, err)
    assert.Equal(t, original.LastSeenID, decoded.LastSeenID)
    assert.Equal(t, original.LastSeenTimestamp, decoded.LastSeenTimestamp)
}

func TestFeedCursor_Decode_InvalidFormat(t *testing.T) {
    _, err := DecodeFeedCursor("not-base64!!!")
    assert.ErrorIs(t, err, ErrInvalidCursorFormat)

    _, err = DecodeFeedCursor(base64.StdEncoding.EncodeToString([]byte("missing-colon")))
    assert.ErrorIs(t, err, ErrInvalidCursorFormat)

    _, err = DecodeFeedCursor(base64.StdEncoding.EncodeToString([]byte("invalid-ulid:not-timestamp")))
    assert.ErrorIs(t, err, ErrInvalidCursorTimestamp)
}

// UseCase Test
func TestGetUserTimelineUseCase_HappyPath(t *testing.T) {
    mockRepo := new(MockTimelineItemRepository)
    mockCache := new(MockFeedCacheRepository)
    mockPerm := new(MockPermissionPort)

    // cache miss
    mockCache.On("GetFeed", context.Background(), "user-1").Return(nil, redis.Nil)

    // query from DB
    items := []TimelineItem{
        {
            ID:         generateULID(),
            UserID:     stringPtr("user-1"),
            ItemType:   ItemTypeEventCreated,
            Visibility: VisibilityPUBLIC,
            OccurredAt: time.Now().Add(-1 * time.Hour),
        },
    }
    mockRepo.On("QueryUserTimeline", context.Background(), "user-1", nil, 21).Return(items, nil)

    // friendship check for FRIENDS items
    mockPerm.On("CheckFriendship", context.Background(), "user-1", "user-1").Return(true, nil)

    // cache write
    mockCache.On("SetFeed", context.Background(), "user-1", mock.Anything, 5*time.Minute).Return(nil)

    uc := NewGetUserTimelineUseCase(mockRepo, mockCache, mockPerm)
    output, err := uc.Execute(context.Background(), GetUserTimelineInput{
        UserID:           "user-1",
        RequestingUserID: stringPtr("user-1"),
        Cursor:           nil,
        Limit:            20,
    })

    assert.NoError(t, err)
    assert.Len(t, output.Items, 1)
    assert.False(t, output.HasMore)
    mockCache.AssertCalled(t, "SetFeed", context.Background(), "user-1", mock.Anything, 5*time.Minute)
}

func TestGetUserTimelineUseCase_CursorPagination(t *testing.T) {
    mockRepo := new(MockTimelineItemRepository)
    mockCache := new(MockFeedCacheRepository)
    mockPerm := new(MockPermissionPort)

    // cache miss
    mockCache.On("GetFeed", context.Background(), "user-1").Return(nil, redis.Nil)

    // cursor 指定：21 item fetch（has_more 判定用）
    cursor := &FeedCursor{
        LastSeenID:        generateULID(),
        LastSeenTimestamp: time.Now().Unix(),
    }

    // generate 21 items
    var items []TimelineItem
    for i := 0; i < 21; i++ {
        items = append(items, TimelineItem{
            ID:         generateULID(),
            UserID:     stringPtr("user-1"),
            ItemType:   ItemTypeEventCreated,
            Visibility: VisibilityPUBLIC,
            OccurredAt: time.Now().Add(-1 * time.Duration(i) * time.Hour),
        })
    }

    mockRepo.On("QueryUserTimeline", context.Background(), "user-1", cursor, 21).Return(items, nil)
    mockPerm.On("CheckFriendship", context.Background(), "user-1", "user-1").Return(true, nil)
    mockCache.On("SetFeed", context.Background(), "user-1", mock.Anything, 5*time.Minute).Return(nil)

    uc := NewGetUserTimelineUseCase(mockRepo, mockCache, mockPerm)
    output, err := uc.Execute(context.Background(), GetUserTimelineInput{
        UserID:           "user-1",
        RequestingUserID: stringPtr("user-1"),
        Cursor:           cursor,
        Limit:            20,
    })

    assert.NoError(t, err)
    assert.Len(t, output.Items, 20)
    assert.True(t, output.HasMore)
    assert.NotNil(t, output.NextCursor)
}

// Integration Test: HTTP Handler
func TestGetUserTimelineHandler_Integration(t *testing.T) {
    // setup: real repo (testcontainers) + real cache
    pgContainer := setupMySQLContainer(t)
    defer pgContainer.Terminate(context.Background())

    redisContainer := setupRedisContainer(t)
    defer redisContainer.Terminate(context.Background())

    // insert test data
    item := &TimelineItem{
        ID:         generateULID(),
        UserID:     stringPtr("user-1"),
        ItemType:   ItemTypeEventCreated,
        Visibility: VisibilityPUBLIC,
        Payload: TimelinePayload{data: map[string]interface{}{
            "event_id":   "evt-123",
            "event_name": "Reunion 2024",
        }},
        OccurredAt: time.Now(),
    }
    repo.Create(context.Background(), item)

    // mock permission service
    mockPerm := new(MockPermissionPort)
    mockPerm.On("CheckFriendship", context.Background(), "user-1", "user-1").Return(true, nil)

    handler := NewHTTPTimelineHandler(repo, cache, mockPerm)

    // HTTP request
    req := httptest.NewRequest("GET", "/api/users/user-1/timeline", nil)
    req.Header.Set("X-User-Id", "user-1")
    w := httptest.NewRecorder()

    handler.GetUserTimeline(w, req)

    assert.Equal(t, http.StatusOK, w.Code)

    var resp GetUserTimelineResponse
    err := json.NewDecoder(w.Body).Decode(&resp)
    assert.NoError(t, err)
    assert.Len(t, resp.Items, 1)
    assert.Equal(t, "user-1", *resp.Items[0].UserID)
}

// Integration Test: Queue Consumer（Beta: Redis+BullMQ/asynq、本番: OCI Queue Service）
func TestConsumeEventServiceEvent_Integration(t *testing.T) {
    // setup: real MySQL 8.0 / MariaDB 10.11 + Redis（BullMQ / asynq 用）
    dbContainer := setupMySQLContainer(t) // MySQL 8.0 または MariaDB 10.11
    redisContainer := setupRedisContainer(t)

    // QueuePort 経由でメッセージを投入（Beta: asynq、テストでは redis-backed な testcontainer）
    queuePort := newAsynqQueueAdapter(redisContainer.Addr())

    event := map[string]interface{}{
        "event_id":    "evt-456",
        "event_name":  "Team Gathering",
        "event_type":  "EVENT_CREATED",
        "user_id":     "user-2",
        "occurred_at": time.Now().Unix(),
        "description": "Annual team gathering",
    }
    eventJSON, _ := json.Marshal(event)

    _ = queuePort.Enqueue(context.Background(), port.Job{
        ID:      "job-1",
        Topic:   "recuerdo.events.service.published",
        Payload: eventJSON,
    })

    // run consumer
    consumer := NewQueueEventConsumer(repo, cache, queuePort)
    err := consumer.ConsumeEventServiceEvent(context.Background(), port.Job{
        ID:      "job-1",
        Topic:   "recuerdo.events.service.published",
        Payload: eventJSON,
    })

    assert.NoError(t, err)

    // verify: timeline_item inserted
    items, err := repo.QueryByEventID(context.Background(), "evt-456")
    assert.NoError(t, err)
    assert.Len(t, items, 1)
    assert.Equal(t, ItemTypeEventCreated, items[0].ItemType)
}