クリーンアーキテクチャ設計書¶

package domain

import (
    "database/sql"
    "encoding/json"
    "time"
)

// TimelineItemType は Timeline 上の活動の種類
type TimelineItemType string

const (
    TimelineItemTypeEventCreated            TimelineItemType = "EVENT_CREATED"
    TimelineItemTypeAlbumCreated            TimelineItemType = "ALBUM_CREATED"
    TimelineItemTypeMediaAdded              TimelineItemType = "MEDIA_ADDED"
    TimelineItemTypeFriendJoined            TimelineItemType = "FRIEND_JOINED"
    TimelineItemTypeEventInvitationAccepted TimelineItemType = "EVENT_INVITATION_ACCEPTED"
    TimelineItemTypeHighlightVideoReady     TimelineItemType = "HIGHLIGHT_VIDEO_READY"
    TimelineItemTypeMemoryShared            TimelineItemType = "MEMORY_SHARED"
)

// Visibility 可視性レベル
type Visibility string

const (
    VisibilityPrivate  Visibility = "PRIVATE"   // 所有者のみ
    VisibilityFriends  Visibility = "FRIENDS"   // 接続ユーザー
    VisibilityPublic   Visibility = "PUBLIC"    // すべてのメンバー
)

// TimelinePayload item_type に応じた可変構造（MySQL/MariaDB JSON 型にシリアライズ）
type TimelinePayload struct {
    data map[string]interface{}
}

func NewTimelinePayload(itemType TimelineItemType, data map[string]interface{}) (*TimelinePayload, error) {
    if !isValidPayloadForType(itemType, data) {
        return nil, fmt.Errorf("invalid payload for item type %s", itemType)
    }
    return &TimelinePayload{data: data}, nil
}

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

func (p *TimelinePayload) UnmarshalJSON(b []byte) error {
    return json.Unmarshal(b, &p.data)
}

// FeedCursor カーソルベースのページネーション
type FeedCursor struct {
    LastSeenID string    // last_seen timeline_item id
    OccurredAt time.Time // last occurred_at timestamp
}

func NewFeedCursor(lastSeenID string, occurredAt time.Time) FeedCursor {
    return FeedCursor{
        LastSeenID: lastSeenID,
        OccurredAt: occurredAt,
    }
}

// Encode カーソルをコードに変換（API レスポンスで使用）
func (fc FeedCursor) Encode() string {
    // Base64 エンコード: "{lastSeenID}:{occurredAt.Unix()}"
    data := fmt.Sprintf("%s:%d", fc.LastSeenID, fc.OccurredAt.Unix())
    return base64.StdEncoding.EncodeToString([]byte(data))
}

// TimelineItem ドメインエンティティ
type TimelineItem struct {
    ID        string              // ULID
    UserID    *string             // 個人活動の場合のみ; NULL なら org_id が主体
    OrgID     *string             // 組織活動の場合のみ
    EventID   *string             // イベント関連活動の場合のみ
    ItemType  TimelineItemType
    Payload   *TimelinePayload    // JSON
    OccurredAt time.Time          // イベント発生時刻（イミュータブル）
    Visibility Visibility
    Hidden    bool                // soft delete フラグ
    HiddenBy  *string             // who hid it
    HiddenAt  *time.Time
    CreatedAt time.Time
    domainEvents []interface{}
}

// NewTimelineItem ファクトリメソッド
func NewTimelineItem(
    userID *string,
    orgID *string,
    eventID *string,
    itemType TimelineItemType,
    payload *TimelinePayload,
    occurredAt time.Time,
    visibility Visibility,
) (*TimelineItem, error) {
    // バリデーション：user_id か org_id いずれか必須
    if (userID == nil || *userID == "") && (orgID == nil || *orgID == "") {
        return nil, fmt.Errorf("either user_id or org_id required")
    }

    if payload == nil {
        return nil, fmt.Errorf("payload required")
    }

    item := &TimelineItem{
        ID:         generateULID(),
        UserID:     userID,
        OrgID:      orgID,
        EventID:    eventID,
        ItemType:   itemType,
        Payload:    payload,
        OccurredAt: occurredAt,
        Visibility: visibility,
        Hidden:     false,
        CreatedAt:  time.Now(),
    }

    item.recordEvent(&TimelineItemCreatedEvent{
        ItemID:    item.ID,
        UserID:    userID,
        OrgID:     orgID,
        ItemType:  itemType,
        Visibility: visibility,
        CreatedAt: time.Now(),
    })

    return item, nil
}

// Hide soft delete
func (ti *TimelineItem) Hide(hiddenBy string) error {
    if ti.Hidden {
        return fmt.Errorf("already hidden")
    }
    ti.Hidden = true
    ti.HiddenBy = &hiddenBy
    now := time.Now()
    ti.HiddenAt = &now

    ti.recordEvent(&TimelineItemHiddenEvent{
        ItemID:   ti.ID,
        HiddenBy: hiddenBy,
        HiddenAt: now,
    })

    return nil
}

// IsVisibleTo 可視性チェック（アクセス制御）
func (ti *TimelineItem) IsVisibleTo(viewerID string, isConnected bool) bool {
    if ti.Hidden {
        return false
    }

    // 所有者には常に見える
    if ti.UserID != nil && *ti.UserID == viewerID {
        return true
    }

    switch ti.Visibility {
    case VisibilityPrivate:
        return ti.UserID != nil && *ti.UserID == viewerID
    case VisibilityFriends:
        return isConnected
    case VisibilityPublic:
        return true
    default:
        return false
    }
}

// DomainEvents ドメインイベント取得＆クリア
func (ti *TimelineItem) DomainEvents() []interface{} {
    events := ti.domainEvents
    ti.domainEvents = []interface{}{}
    return events
}

func (ti *TimelineItem) recordEvent(event interface{}) {
    ti.domainEvents = append(ti.domainEvents, event)
}

// ドメインイベント
type TimelineItemCreatedEvent struct {
    ItemID     string
    UserID     *string
    OrgID      *string
    ItemType   TimelineItemType
    Visibility Visibility
    CreatedAt  time.Time
}

type TimelineItemHiddenEvent struct {
    ItemID   string
    HiddenBy string
    HiddenAt time.Time
}

// ペイロード構造の例（item_type ごと）
func EventCreatedPayload(eventID, eventTitle, createdBy string) map[string]interface{} {
    return map[string]interface{}{
        "event_id":  eventID,
        "title":     eventTitle,
        "created_by": createdBy,
    }
}

func AlbumCreatedPayload(albumID, albumName, eventID string) map[string]interface{} {
    return map[string]interface{}{
        "album_id":  albumID,
        "name":      albumName,
        "event_id":  eventID,
    }
}

package application

// CreateTimelineItemRequest QueuePort メッセージペイロード
type CreateTimelineItemRequest struct {
    EventType   string                 `json:"event_type"` // EventCreated, AlbumCreated など
    UserID      *string                `json:"user_id,omitempty"`
    OrgID       *string                `json:"org_id,omitempty"`
    EventID     *string                `json:"event_id,omitempty"`
    Payload     map[string]interface{} `json:"payload"`
    OccurredAt  time.Time              `json:"occurred_at"`
    Visibility  string                 `json:"visibility"` // PUBLIC, FRIENDS, PRIVATE
}

// CreateTimelineItemResponse
type CreateTimelineItemResponse struct {
    ItemID    string    `json:"item_id"`
    ItemType  string    `json:"item_type"`
    CreatedAt time.Time `json:"created_at"`
}

// GetUserTimelineRequest
type GetUserTimelineRequest struct {
    UserID string  `json:"user_id"`
    Limit  int     `json:"limit"`       // default: 20, max: 100
    Cursor *string `json:"cursor,omitempty"` // base64 encoded
}

// GetUserTimelineResponse
type GetUserTimelineResponse struct {
    Items      []TimelineItemDTO `json:"items"`
    NextCursor *string           `json:"next_cursor,omitempty"`
    Total      int64             `json:"total"`
}

// TimelineItemDTO プレゼンテーション用
type TimelineItemDTO struct {
    ID         string                 `json:"id"`
    ItemType   string                 `json:"item_type"`
    Payload    map[string]interface{} `json:"payload"`
    OccurredAt time.Time              `json:"occurred_at"`
    Visibility string                 `json:"visibility"`
    CreatedAt  time.Time              `json:"created_at"`
}

// GetOrgTimelineRequest
type GetOrgTimelineRequest struct {
    OrgID  string  `json:"org_id"`
    Limit  int     `json:"limit"`
    Cursor *string `json:"cursor,omitempty"`
}

// HideTimelineItemRequest
type HideTimelineItemRequest struct {
    ItemID  string `json:"item_id"`
    HiddenBy string `json:"hidden_by"` // user_id
}

// GetUserFeedRequest（拡張フィード：友人活動含む）
type GetUserFeedRequest struct {
    UserID string `json:"user_id"`
    Limit  int    `json:"limit"`
    Offset int    `json:"offset"`
}

// GetUserFeedResponse
type GetUserFeedResponse struct {
    Items []TimelineItemDTO `json:"items"` // マージ済み、時系列順
    Total int64             `json:"total"`
}

package application

import "context"

// TimelineItemRepository Timeline Item 永続化のポート
type TimelineItemRepository interface {
    // Save TimelineItem を保存
    Save(ctx context.Context, item *domain.TimelineItem) error

    // FindByID ID で検索
    FindByID(ctx context.Context, itemID string) (*domain.TimelineItem, error)

    // ListByUser ユーザーの timeline（ページング）
    ListByUser(ctx context.Context, userID string, limit int, cursor *domain.FeedCursor) ([]*domain.TimelineItem, *domain.FeedCursor, error)

    // ListByOrg 組織の timeline（ページング）
    ListByOrg(ctx context.Context, orgID string, limit int, cursor *domain.FeedCursor) ([]*domain.TimelineItem, *domain.FeedCursor, error)

    // ListByEvent イベント関連アイテム
    ListByEvent(ctx context.Context, eventID string) ([]*domain.TimelineItem, error)

    // Update アイテム更新（Hidden フラグなど）
    Update(ctx context.Context, item *domain.TimelineItem) error

    // CountByUser ユーザーのアイテム総数
    CountByUser(ctx context.Context, userID string) (int64, error)
}

// FeedCacheRepository フィードキャッシュのポート（Redis）
type FeedCacheRepository interface {
    // GetUserFeed ユーザーフィード取得（Redis sorted set）
    GetUserFeed(ctx context.Context, userID string, start, stop int) ([]string, error)

    // InvalidateUserFeed ユーザーフィードキャッシュ無効化
    InvalidateUserFeed(ctx context.Context, userID string) error

    // InvalidateOrgFeed 組織フィードキャッシュ無効化
    InvalidateOrgFeed(ctx context.Context, orgID string) error
}

package application

// PermissionService アクセス制御のポート（gRPC）
type PermissionService interface {
    // IsUserConnected ユーザー間の接続状態チェック
    IsUserConnected(ctx context.Context, userID1, userID2 string) (bool, error)

    // CanViewItem ユーザーがアイテムを見られるか
    CanViewItem(ctx context.Context, viewerID string, item *domain.TimelineItem) (bool, error)
}

// NotificationService 通知サービスのポート
type NotificationService interface {
    // NotifyFeedUpdate フィード更新通知
    NotifyFeedUpdate(ctx context.Context, userID, itemID string) error
}

// QueueMessageConsumer キューコンシューマのポート (Beta: Redis+BullMQ/asynq / Prod: OCI Queue)
type QueueMessageConsumer interface {
    // Listen QueuePort メッセージリスニング開始
    Listen(ctx context.Context, handler func(ctx context.Context, message interface{}) error) error
}

package adapter

// TimelinePresenter ドメインモデル → HTTP レスポンス
type TimelinePresenter struct {
    cache *feedCacheProvider
}

// PresentTimelineItemDTO TimelineItem → DTO
func (p *TimelinePresenter) PresentTimelineItemDTO(item *domain.TimelineItem) *TimelineItemDTO {
    return &TimelineItemDTO{
        ID:         item.ID,
        ItemType:   string(item.ItemType),
        Payload:    item.Payload.Data(),
        OccurredAt: item.OccurredAt,
        Visibility: string(item.Visibility),
        CreatedAt:  item.CreatedAt,
    }
}

// PresentUserTimelineResponse ユーザーフィード レスポンス
func (p *TimelinePresenter) PresentUserTimelineResponse(
    items []*domain.TimelineItem,
    nextCursor *domain.FeedCursor,
    total int64,
) *GetUserTimelineResponse {
    dtos := make([]TimelineItemDTO, len(items))
    for i, item := range items {
        dtos[i] = *p.PresentTimelineItemDTO(item)
    }

    var cursorStr *string
    if nextCursor != nil {
        encoded := nextCursor.Encode()
        cursorStr = &encoded
    }

    return &GetUserTimelineResponse{
        Items:      dtos,
        NextCursor: cursorStr,
        Total:      total,
    }
}

package adapter

// TimelineItemMapper DB ↔ ドメインエンティティ
type TimelineItemMapper struct{}

// ToEntity SQL 結果 → ドメイン TimelineItem
func (m *TimelineItemMapper) ToEntity(row *TimelineItemRow) (*domain.TimelineItem, error) {
    payload, err := domain.NewTimelinePayload(
        domain.TimelineItemType(row.ItemType),
        row.PayloadJSON,
    )
    if err != nil {
        return nil, err
    }

    return &domain.TimelineItem{
        ID:         row.ID,
        UserID:     row.UserID,
        OrgID:      row.OrgID,
        EventID:    row.EventID,
        ItemType:   domain.TimelineItemType(row.ItemType),
        Payload:    payload,
        OccurredAt: row.OccurredAt,
        Visibility: domain.Visibility(row.Visibility),
        Hidden:     row.Hidden,
        HiddenBy:   row.HiddenBy,
        HiddenAt:   row.HiddenAt,
        CreatedAt:  row.CreatedAt,
    }, nil
}

// ToPersistence ドメイン TimelineItem → DB 挿入用
func (m *TimelineItemMapper) ToPersistence(item *domain.TimelineItem) *TimelineItemRow {
    payloadJSON, _ := json.Marshal(item.Payload)
    return &TimelineItemRow{
        ID:          item.ID,
        UserID:      item.UserID,
        OrgID:       item.OrgID,
        EventID:     item.EventID,
        ItemType:    string(item.ItemType),
        PayloadJSON: payloadJSON,
        OccurredAt:  item.OccurredAt,
        Visibility:  string(item.Visibility),
        Hidden:      item.Hidden,
        HiddenBy:    item.HiddenBy,
        HiddenAt:    item.HiddenAt,
        CreatedAt:   item.CreatedAt,
    }
}

// QueueMessageMapper QueuePort JSON → CreateTimelineItemRequest
func QueueMessageToRequest(message []byte) (*CreateTimelineItemRequest, error) {
    var req CreateTimelineItemRequest
    err := json.Unmarshal(message, &req)
    return &req, err
}

package infra

import (
    "go.uber.org/fx"
    "github.com/gin-gonic/gin"
    _ "github.com/go-sql-driver/mysql"
    "database/sql"
)

// Module Timeline Service fx Module
func Module() fx.Option {
    return fx.Module("timeline-service",
        // インフラプロバイダ
        fx.Provide(
            provideMySQLDB,
            provideRedisClient,
            provideQueueAdapter, // QueuePort (Beta: Redis+BullMQ / Prod: OCI Queue)
            provideGinEngine,
        ),
        // リポジトリプロバイダ
        fx.Provide(
            func(db *sql.DB) adapter.TimelineItemRepository {
                return adapter.NewMySQLTimelineItemRepository(db)
            },
            func(redis *redis.Client) adapter.FeedCacheRepository {
                return adapter.NewRedisTimelineItemCache(redis)
            },
        ),
        // 外部サービスアダプタ
        fx.Provide(
            func(grpcConn *grpc.ClientConn) application.PermissionService {
                return adapter.NewPermissionServiceClient(grpcConn)
            },
            func(q application.QueuePort) application.QueueMessageConsumer {
                // Beta: RedisBullMQConsumerAdapter / Prod: OCIQueueConsumerAdapter を q から構築
                return adapter.NewQueueMessageConsumerAdapter(q)
            },
        ),
        // ユースケース
        fx.Provide(
            func(
                itemRepo adapter.TimelineItemRepository,
                feedCache adapter.FeedCacheRepository,
                permSvc application.PermissionService,
            ) application.CreateTimelineItemUseCase {
                return application.NewCreateTimelineItemUseCase(itemRepo, feedCache, permSvc)
            },
            func(
                itemRepo adapter.TimelineItemRepository,
                feedCache adapter.FeedCacheRepository,
                permSvc application.PermissionService,
            ) application.GetUserTimelineUseCase {
                return application.NewGetUserTimelineUseCase(itemRepo, feedCache, permSvc)
            },
            // その他...
        ),
        // ハンドラ登録
        fx.Invoke(registerHandlers),
    )
}

func provideMySQLDB(cfg *config.DatabaseConfig) (*sql.DB, error) {
    // go-sql-driver/mysql DSN (MySQL 8.x / MariaDB 10.6+ 互換)
    connStr := fmt.Sprintf(
        "%s:%s@tcp(%s:%d)/%s?parseTime=true&charset=utf8mb4&tls=preferred",
        cfg.User, cfg.Password, cfg.Host, cfg.Port, cfg.Database,
    )
    return sql.Open("mysql", connStr)
}

// provideQueueAdapter は QueuePort の実装を選択する
func provideQueueAdapter(cfg *config.QueueConfig) (application.QueuePort, error) {
    switch cfg.Provider {
    case "redis-bullmq":
        return adapter.NewRedisBullMQAdapter(cfg.RedisAddr), nil
    case "oci-queue":
        return adapter.NewOCIQueueAdapter(cfg.OCIQueueID)
    default:
        return nil, fmt.Errorf("unknown queue provider: %s", cfg.Provider)
    }
}

func provideRedisClient(cfg *config.RedisConfig) *redis.Client {
    return redis.NewClient(&redis.Options{
        Addr: cfg.Address,
    })
}

func registerHandlers(
    engine *gin.Engine,
    createItemUC application.CreateTimelineItemUseCase,
    getUserTimelineUC application.GetUserTimelineUseCase,
    hideItemUC application.HideTimelineItemUseCase,
) {
    api := engine.Group("/api")
    {
        timelines := api.Group("/timelines")
        {
            timelines.GET("/users/:id", func(c *gin.Context) {
                handler := adapter.NewGetUserTimelineHandler(getUserTimelineUC)
                handler.Handle(c)
            })
        }
        items := api.Group("/timeline-items")
        {
            items.DELETE("/:id", func(c *gin.Context) {
                handler := adapter.NewHideTimelineItemHandler(hideItemUC)
                handler.Handle(c)
            })
        }
    }
}

package domain_test

import (
    "testing"
    "time"
    "github.com/stretchr/testify/assert"
    "timeline-svc/internal/domain"
)

func TestNewTimelineItem_Success(t *testing.T) {
    // Arrange
    userID := "user-123"
    itemType := domain.TimelineItemTypeEventCreated
    payload, _ := domain.NewTimelinePayload(
        itemType,
        map[string]interface{}{"event_id": "evt-456", "title": "Party"},
    )

    // Act
    item, err := domain.NewTimelineItem(
        &userID,
        nil, // no org
        nil, // no event
        itemType,
        payload,
        time.Now(),
        domain.VisibilityPublic,
    )

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, &userID, item.UserID)
    assert.False(t, item.Hidden)
    assert.Len(t, item.DomainEvents(), 1)
}

func TestTimelineItem_IsVisibleTo(t *testing.T) {
    userID := "user-123"
    otherUserID := "user-999"
    payload, _ := domain.NewTimelinePayload(
        domain.TimelineItemTypeEventCreated,
        map[string]interface{}{},
    )

    tests := []struct {
        name        string
        visibility  domain.Visibility
        viewerID    string
        isConnected bool
        expected    bool
    }{
        {
            name:        "Private visible to owner",
            visibility:  domain.VisibilityPrivate,
            viewerID:    userID,
            isConnected: false,
            expected:    true,
        },
        {
            name:        "Private not visible to others",
            visibility:  domain.VisibilityPrivate,
            viewerID:    otherUserID,
            isConnected: false,
            expected:    false,
        },
        {
            name:        "Friends visible to connected",
            visibility:  domain.VisibilityFriends,
            viewerID:    otherUserID,
            isConnected: true,
            expected:    true,
        },
        {
            name:        "Public visible to all",
            visibility:  domain.VisibilityPublic,
            viewerID:    "anyone",
            isConnected: false,
            expected:    true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            item, _ := domain.NewTimelineItem(
                &userID, nil, nil,
                domain.TimelineItemTypeEventCreated,
                payload,
                time.Now(),
                tt.visibility,
            )

            result := item.IsVisibleTo(tt.viewerID, tt.isConnected)
            assert.Equal(t, tt.expected, result)
        })
    }
}

// 統合テスト
package application_test

import (
    "context"
    "testing"
    "github.com/stretchr/testify/assert"
    "timeline-svc/internal/application"
)

func TestCreateTimelineItemUseCase_Integration(t *testing.T) {
    ctx := context.Background()

    // testcontainers で MySQL セットアップ
    db, cleanup := setupTestDB(t)
    defer cleanup()

    itemRepo := adapter.NewMySQLTimelineItemRepository(db)
    cacheRepo := &mockFeedCacheRepository{}
    permSvc := &mockPermissionService{connected: true}

    uc := application.NewCreateTimelineItemUseCase(itemRepo, cacheRepo, permSvc)

    // Act
    resp, err := uc.Execute(ctx, &application.CreateTimelineItemRequest{
        EventType:  "EVENT_CREATED",
        UserID:     strPtr("user-123"),
        Payload:    map[string]interface{}{"event_id": "evt-456"},
        OccurredAt: time.Now(),
        Visibility: "PUBLIC",
    })

    // Assert
    assert.NoError(t, err)
    assert.NotEmpty(t, resp.ItemID)
    assert.Equal(t, 1, cacheRepo.invalidateCount)
}

// Mock 実装
type mockFeedCacheRepository struct {
    invalidateCount int
}

func (m *mockFeedCacheRepository) GetUserFeed(ctx context.Context, userID string, start, stop int) ([]string, error) {
    return []string{}, nil
}

func (m *mockFeedCacheRepository) InvalidateUserFeed(ctx context.Context, userID string) error {
    m.invalidateCount++
    return nil
}

func (m *mockFeedCacheRepository) InvalidateOrgFeed(ctx context.Context, orgID string) error {
    return nil
}

package domain

var (
    ErrInvalidVisibility     = errors.New("invalid visibility")
    ErrInvalidItemType       = errors.New("invalid item type")
    ErrInvalidPayload        = errors.New("payload invalid for item type")
    ErrUserAndOrgBothSet     = errors.New("either user or org required, not both")
    ErrAlreadyHidden         = errors.New("item already hidden")
)

package application

var (
    ErrTimelineItemNotFound      = errors.New("timeline item not found")
    ErrUnauthorizedToHide        = errors.New("not authorized to hide item")
    ErrPersistenceFailed         = errors.New("failed to persist item")
    ErrInvalidMessage            = errors.New("invalid Queue message")
    ErrCursorInvalid             = errors.New("invalid cursor")
)