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

// ドメイン層: エンティティ定義

// Album: イベント内のアルバム集約ルート
type Album struct {
    ID            ulid.ULID            // ULID: Universally Unique Lexicographically Sortable Identifier
    EventID       *string              // optional: イベント ID (nil = org-level album)
    OrgID         string               // 組織 ID
    Title         string               // アルバムタイトル
    CoverMediaID  *string              // カバー画像 media ID (Storage ref)
    CreatedBy     string               // 作成ユーザ ID
    Status        AlbumStatus          // ACTIVE, ARCHIVED
    MediaCount    int                  // メディア数
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

// IsEditable: アルバム編集可能判定
func (a *Album) IsEditable() bool {
    return a.Status == AlbumStatusActive
}

// CanAddMedia: メディア追加可能判定
func (a *Album) CanAddMedia() bool {
    return a.IsEditable() && a.MediaCount < 10000 // 上限設定
}

// ハイライトビデオはユーザー指定のみ、自動生成しない。
// ポリシーにより MediaCount に基づく自動トリガーや ML による推薦は行わない。

// Archive: アルバムをアーカイブ
func (a *Album) Archive() error {
    if a.Status == AlbumStatusArchived {
        return ErrAlreadyArchived
    }
    a.Status = AlbumStatusArchived
    a.UpdatedAt = time.Now()
    return nil
}

// AlbumMedia: アルバム内メディア参照
type AlbumMedia struct {
    ID         uuid.UUID   // Media レコード ID
    AlbumID    ulid.ULID   // 親アルバム ID
    MediaID    string      // Storage Service 内 media ID（参照のみ）
    UploaderID string      // アップロードユーザ ID
    Caption    *string     // メディアキャプション（optional）
    Position   int         // ソート位置（0-indexed）
    AddedAt    time.Time
}

// UpdatePosition: ポジション更新（リシャッフル用）
func (am *AlbumMedia) UpdatePosition(newPos int) error {
    if newPos < 0 {
        return ErrInvalidPosition
    }
    am.Position = newPos
    return nil
}

// AlbumComment: メディア/アルバム上のコメント
type AlbumComment struct {
    ID       uuid.UUID
    AlbumID  ulid.ULID
    MediaID  *uuid.UUID  // optional: 特定メディアへのコメント
    UserID   string
    Body     CommentBody // 値オブジェクト（max 1000 chars）
    CreatedAt time.Time
}

// Validate: コメント内容バリデーション
func (ac *AlbumComment) Validate() error {
    if len(ac.Body) == 0 {
        return ErrEmptyComment
    }
    if len(ac.Body) > 1000 {
        return ErrCommentTooLong
    }
    return nil
}

// HighlightVideo: ハイライトビデオ
type HighlightVideo struct {
    ID           uuid.UUID
    AlbumID      ulid.ULID
    VideoMediaID string                // Storage Service 内 video media ID
    DurationSecs int
    Status       HighlightVideoStatus  // DRAFT, ACTIVE, PRIVATE
    SettedAt    time.Time
}


// Value Objects

type AlbumStatus string

const (
    AlbumStatusActive   AlbumStatus = "ACTIVE"
    AlbumStatusArchived AlbumStatus = "ARCHIVED"
)

type MediaPosition int

const (
    MinMediaPosition MediaPosition = 0
    MaxMediaPosition MediaPosition = 10000
)

type CommentBody string

func NewCommentBody(body string) (CommentBody, error) {
    if len(body) == 0 || len(body) > 1000 {
        return "", ErrInvalidCommentBody
    }
    return CommentBody(body), nil
}

// ユースケース層: 入出力DTO

// GetEventAlbumInput
type GetEventAlbumInput struct {
    OrgID   string `validate:"required,uuid"`
    EventID string `validate:"required,uuid"`
}

// AlbumMediaDTO
type AlbumMediaDTO struct {
    ID         string `json:"id"`
    MediaID    string `json:"media_id"`
    Caption    string `json:"caption,omitempty"`
    Position   int    `json:"position"`
    UploaderID string `json:"uploader_id"`
    MediaURL   string `json:"media_url"`      // Storage から取得
    MediaType  string `json:"media_type"`     // image, video
    AddedAt    string `json:"added_at"`
}

// HighlightVideoDTO
type HighlightVideoDTO struct {
    ID           string `json:"id"`
    VideoMediaID string `json:"video_media_id"`
    Status       string `json:"status"`
    SettedAt  string `json:"setted_at,omitempty"`
    VideoURL     string `json:"video_url"`      // Storage から取得
}

// GetEventAlbumOutput
type GetEventAlbumOutput struct {
    Album          *AlbumDTO            `json:"album"`
    Medias         []*AlbumMediaDTO     `json:"medias"`
    HighlightVideo *HighlightVideoDTO   `json:"highlight_video,omitempty"`
    CommentsCount  int                  `json:"comments_count"`
}

// CreateAlbumInput
type CreateAlbumInput struct {
    OrgID     string `json:"org_id" validate:"required,uuid"`
    Title     string `json:"title" validate:"required,max=255"`
    CreatedBy string `json:"created_by" validate:"required,uuid"`
    EventID   string `json:"event_id,omitempty" validate:"omitempty,uuid"`
}

// CreateAlbumOutput
type CreateAlbumOutput struct {
    AlbumID   string `json:"album_id"`
    OrgID     string `json:"org_id"`
    EventID   string `json:"event_id,omitempty"`
    Title     string `json:"title"`
    CreatedAt string `json:"created_at"`
}

// AddMediaToAlbumInput
type AddMediaToAlbumInput struct {
    AlbumID    string `json:"album_id" validate:"required,ulid"`
    MediaID    string `json:"media_id" validate:"required"`
    UploaderID string `json:"uploader_id" validate:"required,uuid"`
    Caption    string `json:"caption,omitempty" validate:"max=500"`
}

// AddMediaToAlbumOutput
type AddMediaToAlbumOutput struct {
    AlbumMediaID string `json:"album_media_id"`
    Position     int    `json:"position"`
    AddedAt      string `json:"added_at"`
}

// AddCommentInput
type AddCommentInput struct {
    AlbumID  string `json:"album_id" validate:"required,ulid"`
    MediaID  string `json:"media_id,omitempty" validate:"omitempty,uuid"`
    UserID   string `json:"user_id" validate:"required,uuid"`
    Body     string `json:"body" validate:"required,max=1000"`
}

// AddCommentOutput
type AddCommentOutput struct {
    CommentID string `json:"comment_id"`
    CreatedAt string `json:"created_at"`
}

// ArchiveAlbumInput
type ArchiveAlbumInput struct {
    AlbumID string `validate:"required,ulid"`
}

// ArchiveAlbumOutput
type ArchiveAlbumOutput struct {
    AlbumID   string `json:"album_id"`
    Status    string `json:"status"`
    ArchivedAt string `json:"archived_at"`
}

// ユースケース層: ポートインターフェース

// AlbumRepository: アルバム永続化ポート
type AlbumRepository interface {
    // Create: 新規アルバムを作成
    Create(ctx context.Context, album *domain.Album) error

    // FindByID: ID でアルバムを取得
    FindByID(ctx context.Context, id ulid.ULID) (*domain.Album, error)

    // FindByEventID: event_id でアルバムを取得（1:1 関係）
    FindByEventID(ctx context.Context, eventID string) (*domain.Album, error)

    // Update: アルバムを更新
    Update(ctx context.Context, album *domain.Album) error

    // FindMediaByAlbumID: アルバム内の全メディアを取得（ソート済み）
    FindMediaByAlbumID(ctx context.Context, albumID ulid.ULID) ([]*domain.AlbumMedia, error)

    // AddMedia: メディア参照を追加
    AddMedia(ctx context.Context, media *domain.AlbumMedia) error

    // RemoveMedia: メディア参照を削除
    RemoveMedia(ctx context.Context, albumID ulid.ULID, mediaID uuid.UUID) error

    // UpdateMediaPosition: ポジションを更新（リシャッフル用）
    UpdateMediaPosition(ctx context.Context, albumID ulid.ULID, mediaID uuid.UUID, newPos int) error

    // FindCommentsByAlbumID: アルバム内コメントを取得
    FindCommentsByAlbumID(ctx context.Context, albumID ulid.ULID) ([]*domain.AlbumComment, error)

    // AddComment: コメントを追加
    AddComment(ctx context.Context, comment *domain.AlbumComment) error
}

// StorageService: メディア Storage ポート
type StorageService interface {
    // GetMediaMetadata: media_id からメディア情報を取得
    GetMediaMetadata(ctx context.Context, mediaID string) (*domain.MediaMetadata, error)

    // GetMediaURL: media_id から取得 URL を生成
    GetMediaURL(ctx context.Context, mediaID string, expiryMinutes int) (string, error)

    // CreateHighlightVideo: ハイライトビデオを作成（オブジェクトストレージの署名付き URL 返却）
    // ハイライトビデオはユーザー指定のみ、自動生成しない。
    // mediaIDs はユーザーが選択した HLS 素材。FFmpeg でセグメントを結合して再生成する。
    CreateHighlightVideo(ctx context.Context, highlightID uuid.UUID, mediaIDs []string) (string, error)
}

// EventService: イベント情報ポート
type EventService interface {
    // GetEvent: event_id からイベント情報を取得
    GetEvent(ctx context.Context, eventID string) (*domain.EventInfo, error)

    // IsEventActive: イベントが active か判定
    IsEventActive(ctx context.Context, eventID string) (bool, error)
}

// PermissionService: アクセス権チェックポート
type PermissionService interface {
    // CheckOrgAccess: ユーザが org にアクセス可能か
    CheckOrgAccess(ctx context.Context, userID, orgID string) (bool, error)

    // CheckEventAccess: ユーザが event にアクセス可能か
    CheckEventAccess(ctx context.Context, userID, eventID string) (bool, error)

    // CheckAlbumOwner: ユーザがアルバム所有者か
    CheckAlbumOwner(ctx context.Context, userID string, albumID ulid.ULID) (bool, error)

    // CheckContributor: ユーザが contributor 権限か
    CheckContributor(ctx context.Context, userID, orgID string) (bool, error)
}

// CacheService: キャッシュポート
type CacheService interface {
    // GetAlbumMediaList: キャッシュからメディアリスト取得
    GetAlbumMediaList(ctx context.Context, albumID ulid.ULID) ([]*domain.AlbumMedia, error)

    // SetAlbumMediaList: メディアリストをキャッシュ
    SetAlbumMediaList(ctx context.Context, albumID ulid.ULID, medias []*domain.AlbumMedia, ttl time.Duration) error

    // InvalidateAlbumCache: アルバムキャッシュを無効化
    InvalidateAlbumCache(ctx context.Context, albumID ulid.ULID) error
}

// QueuePort: 非同期ジョブキューポート
// Beta: RedisBullMQAdapter / AsynqAdapter
// Prod: OCIQueueAdapter
type JobQueue interface {
    // EnqueueHighlightGenerationJob: メディアコンバートジョブをエンキュー
    EnqueueOptimizationFileGenerationJob(ctx context.Context, albumID ulid.ULID) (jobID string, err error)
}

// EventPublisher: イベント発行ポート
type EventPublisher interface {
    // PublishAlbumCreated: AlbumCreated イベント発行 → QueuePort (Beta: Redis, Prod: OCI Queue)
    PublishAlbumCreated(ctx context.Context, event *domain.AlbumCreatedEvent) error

    // PublishMediaAdded: MediaAdded イベント発行
    PublishMediaAdded(ctx context.Context, event *domain.MediaAddedEvent) error

    // PublishOptimizationFileReady: メディア変換完了イベント発行
    // (FFmpeg HLS 変換 / libheif HEIC→JPEG/WebP 変換完了時。AWS MediaConvert は使用しない)
    PublishOptimizationFileReady(ctx context.Context, event *domain.MediaTranscodeReadyEvent) error
}

// インターフェース適配層: プレゼンター

type AlbumPresenter struct{}

// PresentGetEventAlbum: GetEventAlbumOutput → HTTP 200 JSON
func (p *AlbumPresenter) PresentGetEventAlbum(output *application.GetEventAlbumOutput) *http.Response {
    return &http.Response{
        StatusCode: 200,
        Body:       json.Marshal(output),
    }
}

// PresentCreateAlbum: CreateAlbumOutput → HTTP 201 JSON
func (p *AlbumPresenter) PresentCreateAlbum(output *application.CreateAlbumOutput) *http.Response {
    return &http.Response{
        StatusCode: 201,
        Body:       json.Marshal(output),
    }
}

// PresentError: Error → HTTP エラーレスポンス
func (p *AlbumPresenter) PresentError(err error) *http.Response {
    statusCode, message := p.mapErrorToHTTP(err)
    return &http.Response{
        StatusCode: statusCode,
        Body:       json.Marshal(map[string]string{"error": message}),
    }
}

func (p *AlbumPresenter) mapErrorToHTTP(err error) (int, string) {
    switch err.(type) {
    case *domain.ValidationError:
        return 400, "Invalid input"
    case *domain.NotFoundError:
        return 404, "Resource not found"
    case *domain.UnauthorizedError:
        return 403, "Access denied"
    case *domain.AlreadyArchivedError:
        return 409, "Album already archived"
    default:
        return 500, "Internal server error"
    }
}

// マッパー: DTO ↔ Entity 相互変換

type AlbumMapper struct{}

// MapInputToEntity: CreateAlbumInput → Album
func (m *AlbumMapper) MapInputToEntity(input *application.CreateAlbumInput) (*domain.Album, error) {
    return &domain.Album{
        ID:        ulid.Make(),
        EventID:   &input.EventID,
        OrgID:     input.OrgID,
        Title:     input.Title,
        CreatedBy: input.CreatedBy,
        Status:    domain.AlbumStatusActive,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }, nil
}

// MapEntityToDTO: Album → AlbumDTO
func (m *AlbumMapper) MapEntityToDTO(album *domain.Album) *application.AlbumDTO {
    eventID := ""
    if album.EventID != nil {
        eventID = *album.EventID
    }
    return &application.AlbumDTO{
        ID:        album.ID.String(),
        EventID:   eventID,
        OrgID:     album.OrgID,
        Title:     album.Title,
        Status:    string(album.Status),
        CreatedBy: album.CreatedBy,
        CreatedAt: album.CreatedAt.Format(time.RFC3339),
    }
}

// MapMediaToDTO: AlbumMedia + Storage metadata → AlbumMediaDTO
func (m *AlbumMapper) MapMediaToDTO(media *domain.AlbumMedia, storageMetadata *domain.MediaMetadata) *application.AlbumMediaDTO {
    return &application.AlbumMediaDTO{
        ID:         media.ID.String(),
        MediaID:    media.MediaID,
        Caption:    *media.Caption,
        Position:   media.Position,
        UploaderID: media.UploaderID,
        MediaURL:   storageMetadata.URL,
        MediaType:  storageMetadata.Type,
        AddedAt:    media.AddedAt.Format(time.RFC3339),
    }
}

// インフラストラクチャ層: DI 設定 (uber-go/fx)

package infrastructure

import (
    "database/sql"
    "go.uber.org/fx"
    _ "github.com/go-sql-driver/mysql"
    "github.com/redis/go-redis/v9"
    "github.com/hibiken/asynq"
)

// FX モジュール: 依存関係の登録
var AlbumModule = fx.Module("album",
    fx.Provide(
        // インフラストラクチャ提供者
        provideMySQLDB,
        provideRedis,
        provideQueueAdapter, // Beta: RedisBullMQAdapter / Prod: OCIQueueAdapter

        // リポジトリ実装
        repository.NewMySQLAlbumRepository,
        repository.NewRedisAlbumCacheRepository,

        // ユースケース
        usecase.NewGetEventAlbumUsecase,
        usecase.NewCreateAlbumUsecase,
        usecase.NewAddMediaToAlbumUsecase,
        usecase.NewRemoveMediaFromAlbumUsecase,
        usecase.NewAddCommentUsecase,
        usecase.NewCreateHighlightVideoUsecase, // ユーザー指定のみ、自動生成しない
        usecase.NewArchiveAlbumUsecase,

        // ハンドラ
        handler.NewGetEventAlbumHandler,
        handler.NewCreateAlbumHandler,
        handler.NewAddMediaHandler,
        handler.NewRemoveMediaHandler,
        handler.NewAddCommentHandler,
        handler.NewCreateHighlightVideoHandler, // ユーザー指定のみ
        handler.NewArchiveAlbumHandler,

        // プレゼンター、マッパー
        handler.NewAlbumPresenter,
        handler.NewAlbumMapper,
    ),
)

// provideMySQLDB: MySQL / MariaDB コネクションプール
// Beta: self-hosted MySQL 8 (MariaDB 互換) / Prod: OCI MySQL HeatWave
func provideMySQLDB(cfg *config.Config) (*sql.DB, error) {
    db, err := sql.Open("mysql", cfg.DatabaseDSN)
    if err != nil {
        return nil, err
    }
    db.SetMaxOpenConns(cfg.DBMaxOpenConns)
    return db, nil
}

// provideRedis: Redis クライアント (Beta: self-hosted / Prod: OCI Cache with Redis)
func provideRedis(cfg *config.Config) *redis.Client {
    return redis.NewClient(&redis.Options{
        Addr: cfg.RedisAddr,
    })
}

// provideQueueAdapter: QueuePort 実装をプロバイダ設定から解決する
//   queue.provider = "redis-bullmq"  → RedisBullMQAdapter (Beta, asynq ベース)
//   queue.provider = "oci-queue"     → OCIQueueAdapter (Prod)
func provideQueueAdapter(cfg *config.Config, redis *redis.Client) application.QueuePort {
    switch cfg.QueueProvider {
    case "redis-bullmq":
        return adapter.NewRedisBullMQAdapter(asynq.NewClient(asynq.RedisClientOpt{Addr: cfg.RedisAddr}))
    case "oci-queue":
        return adapter.NewOCIQueueAdapter(cfg.OCIQueueOCID, cfg.OCIRegion)
    default:
        panic("unsupported queue.provider: " + cfg.QueueProvider)
    }
}

// main.go での使用
func main() {
    app := fx.New(
        AlbumModule,
        fx.Provide(config.LoadConfig),
        fx.Invoke(startServer),
    )
    app.Run()
}

func startServer(
    getAlbumHandler *handler.GetEventAlbumHandler,
    createAlbumHandler *handler.CreateAlbumHandler,
    createHighlightHandler *handler.CreateHighlightVideoHandler,
    queueWorker *worker.AlbumQueueWorker,
) {
    e := echo.New()

    // RESTful ルート
    e.GET("/api/orgs/:org_id/events/:event_id/album", getAlbumHandler.Handle)
    e.POST("/api/orgs/:org_id/albums", createAlbumHandler.Handle)
    // ハイライトビデオはユーザー指定の mediaIDs で生成（自動生成しない）
    e.POST("/api/albums/:album_id/highlight", createHighlightHandler.Handle)

    // QueuePort ワーカー起動 (Beta: Redis+BullMQ / Prod: OCI Queue)
    go queueWorker.Start()

    e.Start(":8080")
}

// domain/album_test.go: ドメインテスト
package domain_test

import (
    "testing"
    "time"
    "github.com/stretchr/testify/assert"
    "github.com/oklog/ulid"
    "recuerdo/album/domain"
)

func TestAlbumIsEditable(t *testing.T) {
    album := &domain.Album{
        ID:     ulid.Make(),
        Status: domain.AlbumStatusActive,
    }
    assert.True(t, album.IsEditable())

    album.Status = domain.AlbumStatusArchived
    assert.False(t, album.IsEditable())
}

// ハイライトビデオはユーザー指定のみ、自動生成しない。
// 旧 ShouldGenerateHighlight() は廃止された。代わりに、ユーザーが明示的に選んだ
// mediaIDs を渡す CreateHighlightVideo ユースケースをテストする。
func TestCreateHighlightVideo_RequiresUserSelectedMedia(t *testing.T) {
    uc := application.NewCreateHighlightVideoUsecase(...)
    _, err := uc.Execute(context.Background(), application.CreateHighlightVideoInput{
        AlbumID:  ulid.Make(),
        MediaIDs: []string{}, // 空
    })
    assert.ErrorIs(t, err, application.ErrNoMediaSelected)
}

// application/get_event_album_usecase_test.go: ユースケーステスト
package application_test

import (
    "context"
    "testing"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/mock"
    "github.com/oklog/ulid"
    "recuerdo/album/application"
    "recuerdo/album/domain"
)

type MockAlbumRepository struct {
    mock.Mock
}

func (m *MockAlbumRepository) FindByEventID(ctx context.Context, eventID string) (*domain.Album, error) {
    args := m.Called(ctx, eventID)
    if args.Get(0) == nil {
        return nil, args.Error(1)
    }
    return args.Get(0).(*domain.Album), args.Error(1)
}

type MockStorageService struct {
    mock.Mock
}

func (m *MockStorageService) GetMediaURL(ctx context.Context, mediaID string, expiryMinutes int) (string, error) {
    args := m.Called(ctx, mediaID, expiryMinutes)
    return args.String(0), args.Error(1)
}

func TestGetEventAlbumUsecase(t *testing.T) {
    mockRepo := new(MockAlbumRepository)
    mockStorage := new(MockStorageService)

    album := &domain.Album{
        ID:        ulid.Make(),
        OrgID:     "org-123",
        Title:     "Summer Reunion",
        Status:    domain.AlbumStatusActive,
        CreatedAt: time.Now(),
    }

    mockRepo.On("FindByEventID", mock.Anything, "event-456").Return(album, nil)
    mockStorage.On("GetMediaURL", mock.Anything, mock.Anything, 60).Return("https://storage.example.com/media/123", nil)

    usecase := application.NewGetEventAlbumUsecase(mockRepo, mockStorage)

    input := &application.GetEventAlbumInput{
        OrgID:   "org-123",
        EventID: "event-456",
    }

    output, err := usecase.Execute(context.Background(), input)

    assert.NoError(t, err)
    assert.NotNil(t, output)
    assert.Equal(t, "Summer Reunion", output.Album.Title)
    mockRepo.AssertExpectations(t)
}

// adapter/MySQL_album_repository_test.go: 統合テスト
package adapter_test

import (
    "context"
    "testing"
    "github.com/stretchr/testify/assert"
    "testcontainers"
    "recuerdo/album/adapter/repository"
    "recuerdo/album/domain"
)

func TestMySQLAlbumRepository_Create(t *testing.T) {
    if testing.Short() {
        t.Skip("skipping integration test")
    }

    MySQL := testcontainers.NewMySQLContainer(t)
    defer MySQL.Terminate(context.Background())

    pool := MySQL.Pool()
    repo := repository.NewMySQLAlbumRepository(pool)

    album := &domain.Album{
        ID:        ulid.Make(),
        OrgID:     "org-123",
        Title:     "New Album",
        CreatedBy: "user-456",
        Status:    domain.AlbumStatusActive,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }

    err := repo.Create(context.Background(), album)
    assert.NoError(t, err)

    retrieved, err := repo.FindByID(context.Background(), album.ID)
    assert.NoError(t, err)
    assert.Equal(t, album.Title, retrieved.Title)
}

type ValidationError struct{ Message string }
type NotFoundError struct{ ResourceID string }
type AlreadyArchivedError struct{ AlbumID string }
type ImmutableViolationError struct{ Message string }