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

package domain

import (
    "time"
)

// MediaStatus メディアのライフサイクルステータス
type MediaStatus string

const (
    MediaStatusUploading   MediaStatus = "UPLOADING"   // アップロード中
    MediaStatusProcessing  MediaStatus = "PROCESSING"  // 処理中（HEIC→JPEG/WebP、HLSトランスコード、サムネイル生成）
    MediaStatusReady       MediaStatus = "READY"       // 配信可能
    MediaStatusFailed      MediaStatus = "FAILED"      // 処理失敗、アクセス不可
)

// MimeType メディアの MIME タイプ（ホワイトリスト）
type MimeType string

const (
    MimeTypeJPEG  MimeType = "image/jpeg"
    MimeTypePNG   MimeType = "image/png"
    MimeTypeHEIC  MimeType = "image/heic"
    MimeTypeMP4   MimeType = "video/mp4"
)

// IsImageType 画像タイプか判定
func (mt MimeType) IsImageType() bool {
    switch mt {
    case MimeTypeJPEG, MimeTypePNG, MimeTypeHEIC:
        return true
    default:
        return false
    }
}

// IsVideoType 動画タイプか判定
func (mt MimeType) IsVideoType() bool {
    return mt == MimeTypeMP4
}

// AccessPolicy ファイルのアクセス権レベル
type AccessPolicy string

const (
    AccessPolicyPrivate      AccessPolicy = "PRIVATE"       // 所有者のみ
    AccessPolicyOrgMembers   AccessPolicy = "ORG_MEMBERS"   // 組織メンバー
    AccessPolicyEventMembers AccessPolicy = "EVENT_MEMBERS" // イベント参加者
)

// StorageKey オブジェクトストレージ (Garage / OCI Object Storage) 格納位置を管理する値オブジェクト
type StorageKey struct {
    value string // org_id/media_id/type
}

func NewStorageKey(orgID, mediaID, storageType string) StorageKey {
    return StorageKey{
        value: fmt.Sprintf("%s/%s/%s", orgID, mediaID, storageType),
    }
}

func (sk StorageKey) String() string {
    return sk.value
}

// DeliveryType 配信時のファイルタイプ
type DeliveryType string

const (
    DeliveryTypeOriginal   DeliveryType = "original"   // 元のファイル
    DeliveryTypeOptimized  DeliveryType = "optimized"  // Web 最適化版（PNG 圧縮など）
    DeliveryTypeThumbnail  DeliveryType = "thumb"      // サムネイル
)

// MediaFile ドメインエンティティ
type MediaFile struct {
    ID               string
    OrgID            string
    UploaderID       string
    OriginalFilename string
    MimeType         MimeType
    FileSizeBytes    int64
    StorageKey       StorageKey           // raw/ フォルダ
    Status           MediaStatus
    AccessPolicy     AccessPolicy
    CreatedAt        time.Time
    UpdatedAt        time.Time
    domainEvents     []interface{}
}

// NewMediaFile ファクトリメソッド
func NewMediaFile(
    orgID, uploaderID, filename string,
    mimeType MimeType,
    fileSize int64,
    policy AccessPolicy,
) (*MediaFile, error) {
    // ファイルサイズ検証
    if !isValidFileSize(mimeType, fileSize) {
        return nil, fmt.Errorf("file size exceeds limit: %d bytes", fileSize)
    }

    // MIME タイプ検証
    if !isAllowedMimeType(mimeType) {
        return nil, fmt.Errorf("unsupported mime type: %s", mimeType)
    }

    mediaID := generateULID()

    mf := &MediaFile{
        ID:               mediaID,
        OrgID:            orgID,
        UploaderID:       uploaderID,
        OriginalFilename: filename,
        MimeType:         mimeType,
        FileSizeBytes:    fileSize,
        StorageKey:       NewStorageKey(orgID, mediaID, "raw"),
        Status:           MediaStatusUploading,
        AccessPolicy:     policy,
        CreatedAt:        time.Now(),
        UpdatedAt:        time.Now(),
    }

    mf.recordEvent(&MediaUploadedEvent{
        MediaID:    mediaID,
        OrgID:      orgID,
        UploaderID: uploaderID,
        MimeType:   string(mimeType),
        FileSize:   fileSize,
    })

    return mf, nil
}

// StartProcessing ステータス遷移：UPLOADING → PROCESSING
func (mf *MediaFile) StartProcessing() error {
    if mf.Status != MediaStatusUploading {
        return fmt.Errorf("only UPLOADING files can start processing")
    }
    mf.Status = MediaStatusProcessing
    mf.UpdatedAt = time.Now()
    return nil
}

// MarkReady 処理完了：PROCESSING → READY
func (mf *MediaFile) MarkReady(optimizedKey, thumbnailKey string) error {
    if mf.Status != MediaStatusProcessing {
        return fmt.Errorf("only PROCESSING files can be marked ready")
    }
    mf.Status = MediaStatusReady
    mf.UpdatedAt = time.Now()

    mf.recordEvent(&MediaReadyEvent{
        MediaID:       mf.ID,
        OrgID:         mf.OrgID,
        OptimizedKey:  optimizedKey,
        ThumbnailKey:  thumbnailKey,
    })
    return nil
}

// MarkFailed 処理失敗：→ FAILED
func (mf *MediaFile) MarkFailed(errorMsg string) error {
    mf.Status = MediaStatusFailed
    mf.UpdatedAt = time.Now()

    mf.recordEvent(&MediaProcessingFailedEvent{
        MediaID:   mf.ID,
        ErrorMsg:  errorMsg,
    })
    return nil
}

// IsReadyForDelivery 配信可能か
func (mf *MediaFile) IsReadyForDelivery() bool {
    return mf.Status == MediaStatusReady
}

// CanBeAccessedBy アクセス権チェック
func (mf *MediaFile) CanBeAccessedBy(userID string, isMember bool, isEventMember bool) bool {
    switch mf.AccessPolicy {
    case AccessPolicyPrivate:
        return mf.UploaderID == userID
    case AccessPolicyOrgMembers:
        return isMember
    case AccessPolicyEventMembers:
        return isEventMember
    default:
        return false
    }
}

// MediaChunk チャンク式アップロード用
type MediaChunk struct {
    ID          string
    MediaID     string
    ChunkIndex  int    // 0-based
    StorageKey  string // オブジェクトストレージ (Garage / OCI OSS) のキー
    SizeBytes   int64
    UploadedAt  time.Time
}

// NewMediaChunk チャンク作成
func NewMediaChunk(mediaID string, chunkIndex int, storageKey string, size int64) *MediaChunk {
    return &MediaChunk{
        ID:         generateULID(),
        MediaID:    mediaID,
        ChunkIndex: chunkIndex,
        StorageKey: storageKey,
        SizeBytes:  size,
        UploadedAt: time.Now(),
    }
}

// ProcessingJob 非同期処理ジョブ
type ProcessingJobType string

const (
    ProcessingJobTypeHEICConvert  ProcessingJobType = "HEIC_CONVERT"   // libheif で HEIC→JPEG/WebP
    ProcessingJobTypeHLSTranscode ProcessingJobType = "HLS_TRANSCODE"  // FFmpeg で 360p/720p/1080p, 6秒セグメント
    ProcessingJobTypeLivePhotoPair ProcessingJobType = "LIVE_PHOTO_PAIR" // HEIC+MOV を asset_identifier でペアリング
    ProcessingJobTypeThumbnailGen ProcessingJobType = "THUMBNAIL_GEN"
)

type ProcessingJobStatus string

const (
    ProcessingJobStatusPending ProcessingJobStatus = "PENDING"
    ProcessingJobStatusRunning ProcessingJobStatus = "RUNNING"
    ProcessingJobStatusDone    ProcessingJobStatus = "DONE"
    ProcessingJobStatusFailed  ProcessingJobStatus = "FAILED"
)

type ProcessingJob struct {
    ID        string
    MediaID   string
    JobType   ProcessingJobType
    Status    ProcessingJobStatus
    ErrorMsg  *string
    CreatedAt time.Time
    UpdatedAt time.Time
}

// NewProcessingJob ジョブ作成
func NewProcessingJob(mediaID string, jobType ProcessingJobType) *ProcessingJob {
    return &ProcessingJob{
        ID:        generateULID(),
        MediaID:   mediaID,
        JobType:   jobType,
        Status:    ProcessingJobStatusPending,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }
}

// MarkDone ジョブ完了
func (pj *ProcessingJob) MarkDone() {
    pj.Status = ProcessingJobStatusDone
    pj.UpdatedAt = time.Now()
}

// MarkFailed ジョブ失敗
func (pj *ProcessingJob) MarkFailed(errMsg string) {
    pj.Status = ProcessingJobStatusFailed
    pj.ErrorMsg = &errMsg
    pj.UpdatedAt = time.Now()
}

// ドメインイベント
type MediaUploadedEvent struct {
    MediaID    string
    OrgID      string
    UploaderID string
    MimeType   string
    FileSize   int64
}

type MediaReadyEvent struct {
    MediaID      string
    OrgID        string
    OptimizedKey string
    ThumbnailKey string
}

type MediaProcessingFailedEvent struct {
    MediaID  string
    ErrorMsg string
}

// DomainEvents インターフェース
func (mf *MediaFile) DomainEvents() []interface{} {
    events := mf.domainEvents
    mf.domainEvents = []interface{}{}
    return events
}

func (mf *MediaFile) recordEvent(event interface{}) {
    mf.domainEvents = append(mf.domainEvents, event)
}

package application

// UploadMediaSingleRequest
type UploadMediaSingleRequest struct {
    FileBody     []byte // multipart form body
    OriginalName string
    MimeType     string
    FileSize     int64
    OrgID        string
    UploaderID   string
    AccessPolicy string // PRIVATE, ORG_MEMBERS, EVENT_MEMBERS
}

// UploadMediaSingleResponse
type UploadMediaSingleResponse struct {
    MediaID string    `json:"media_id"`
    Status  string    `json:"status"`
    OrgID   string    `json:"org_id"`
    SavedAt time.Time `json:"saved_at"`
}

// InitChunkedUploadRequest
type InitChunkedUploadRequest struct {
    OriginalName string `json:"original_name"`
    MimeType     string `json:"mime_type"`
    FileSizeBytes int64 `json:"file_size_bytes"`
    ChunkSizeBytes int64 `json:"chunk_size_bytes"` // 推奨 5MB
    OrgID        string `json:"org_id"`
    UploaderID   string `json:"uploader_id"`
    AccessPolicy string `json:"access_policy"`
}

// InitChunkedUploadResponse
type InitChunkedUploadResponse struct {
    MediaID         string `json:"media_id"`
    ChunkCount      int    `json:"chunk_count"`
    ChunkSizeBytes  int64  `json:"chunk_size_bytes"`
    ExpiresAt       time.Time `json:"expires_at"`
}

// UploadChunkRequest
type UploadChunkRequest struct {
    MediaID    string `json:"media_id"`
    ChunkIndex int    `json:"chunk_index"`
    ChunkBody  []byte // multipart form body
    ChunkSize  int64  `json:"chunk_size"`
}

// UploadChunkResponse
type UploadChunkResponse struct {
    MediaID    string `json:"media_id"`
    ChunkIndex int    `json:"chunk_index"`
    UploadedAt time.Time `json:"uploaded_at"`
}

// MergeChunksRequest
type MergeChunksRequest struct {
    MediaID string `json:"media_id"`
    OrgID   string `json:"org_id"`
}

// MergeChunksResponse
type MergeChunksResponse struct {
    MediaID string    `json:"media_id"`
    Status  string    `json:"status"` // PROCESSING
    JobID   string    `json:"job_id"`
}

// DeliverMediaRequest
type DeliverMediaRequest struct {
    MediaID      string `json:"media_id"`
    DeliveryType string `json:"delivery_type"` // original, optimized, thumb
    ViewerID     string `json:"viewer_id"`
}

// DeliverMediaResponse
type DeliverMediaResponse struct {
    PresignedURL string    `json:"presigned_url"`
    ExpiresAt    time.Time `json:"expires_at"`
}

// DeleteMediaRequest
type DeleteMediaRequest struct {
    MediaID  string `json:"media_id"`
    OrgID    string `json:"org_id"`
    RequestBy string `json:"request_by"` // user_id
}

// DeleteMediaResponse
type DeleteMediaResponse struct {
    MediaID   string    `json:"media_id"`
    DeletedAt time.Time `json:"deleted_at"`
}

package application

import "context"

// MediaFileRepository MediaFile 永続化のポート
type MediaFileRepository interface {
    // Save メディアファイル保存
    Save(ctx context.Context, media *domain.MediaFile) error

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

    // ListByOrg 組織内メディア一覧
    ListByOrg(ctx context.Context, orgID string, limit, offset int) ([]*domain.MediaFile, int64, error)

    // Delete メディア削除
    Delete(ctx context.Context, mediaID string) error

    // Update メディア更新（ステータス変更など）
    Update(ctx context.Context, media *domain.MediaFile) error
}

// MediaChunkRepository チャンク永続化のポート
type MediaChunkRepository interface {
    // Save チャンク記録
    Save(ctx context.Context, chunk *domain.MediaChunk) error

    // ListByMedia メディアの全チャンク
    ListByMedia(ctx context.Context, mediaID string) ([]*domain.MediaChunk, error)

    // DeleteExpired 24時間以上経過したチャンク削除
    DeleteExpired(ctx context.Context) error
}

// ProcessingJobRepository ジョブ管理のポート
type ProcessingJobRepository interface {
    // Save ジョブ保存
    Save(ctx context.Context, job *domain.ProcessingJob) error

    // FindByID ジョブ検索
    FindByID(ctx context.Context, jobID string) (*domain.ProcessingJob, error)

    // ListPending ペンディングジョブ取得
    ListPending(ctx context.Context, limit int) ([]*domain.ProcessingJob, error)

    // Update ジョブ更新
    Update(ctx context.Context, job *domain.ProcessingJob) error
}

package application

// StoragePort オブジェクトストレージ操作のポート（Beta: Garage / Prod: OCI Object Storage）
type StoragePort interface {
    // Upload ファイルをオブジェクトストレージに保存
    Upload(ctx context.Context, key string, data []byte) error

    // UploadStream ストリーム形式でアップロード（大容量対応）
    UploadStream(ctx context.Context, key string, reader io.Reader, size int64) error

    // Download オブジェクトストレージ からダウンロード
    Download(ctx context.Context, key string) ([]byte, error)

    // GeneratePresignedURL 署名付き URL 生成（配信用）
    GeneratePresignedURL(ctx context.Context, key string, expirySeconds int64) (string, error)

    // Delete オブジェクトストレージ からファイル削除
    Delete(ctx context.Context, key string) error

    // ListObjects キー プレフィックス配下のオブジェクト列挙
    ListObjects(ctx context.Context, prefix string) ([]string, error)
}

// MediaTranscoderPort メディア変換（画像・動画・Live Photo）のポート
// 実装:
//   - LibheifImageAdapter: HEIC → JPEG/WebP（libheif）
//   - FFmpegHLSAdapter: MP4 → HLS 360p/720p/1080p（FFmpeg, 6秒セグメント）
type MediaTranscoderPort interface {
    // ConvertHEICToOptimized HEIC を JPEG/WebP に変換（libheif）
    ConvertHEICToOptimized(ctx context.Context, heicBytes []byte, target ImageFormat) ([]byte, error)

    // GenerateThumbnail サムネイル生成（≤1280px）
    GenerateThumbnail(ctx context.Context, imageBytes []byte, maxWidth int) ([]byte, error)

    // OptimizeImage Web 用に最適化（圧縮、リサイズ）
    OptimizeImage(ctx context.Context, imageBytes []byte) ([]byte, error)

    // TranscodeVideoToHLS MP4 を HLS マルチビットレートに変換（360p/720p/1080p, 6s seg）
    TranscodeVideoToHLS(ctx context.Context, in TranscodeInput) (TranscodeOutput, error)

    // PairLivePhoto HEIC + MOV を asset_identifier でペアリング
    PairLivePhoto(ctx context.Context, heicKey, movKey, assetIdentifier string) error
}

// QueuePort 非同期ジョブキューのポート
// 実装:
//   - Beta: RedisBullMQAdapter / AsynqAdapter
//   - Prod: OCIQueueAdapter
type QueuePort interface {
    // Enqueue ジョブをキューに入れる
    Enqueue(ctx context.Context, queue string, payload []byte, opts ...EnqueueOption) error
}

// EventPublisher ドメインイベント発行のポート（QueuePort 上に実装）
type EventPublisher interface {
    // Publish ドメインイベント発行
    Publish(ctx context.Context, event interface{}) error
}

package adapter

// MediaPresenter ドメインモデル → HTTP レスポンス
type MediaPresenter struct{}

// PresentUploadResponse アップロード レスポンス
func (p *MediaPresenter) PresentUploadResponse(media *domain.MediaFile) *UploadMediaSingleResponse {
    return &UploadMediaSingleResponse{
        MediaID: media.ID,
        Status:  string(media.Status),
        OrgID:   media.OrgID,
        SavedAt: media.CreatedAt,
    }
}

// PresentDeliverResponse 配信レスポンス
func (p *MediaPresenter) PresentDeliverResponse(presignedURL string, expiryTime time.Time) *DeliverMediaResponse {
    return &DeliverMediaResponse{
        PresignedURL: presignedURL,
        ExpiresAt:    expiryTime,
    }
}

// PresentErrorResponse エラー応答
func PresentErrorResponse(err error) (statusCode int, body map[string]string) {
    if errors.Is(err, ErrFileTooLarge) {
        return http.StatusRequestEntityTooLarge, map[string]string{"error": "file_too_large"}
    }
    if errors.Is(err, ErrUnsupportedMimeType) {
        return http.StatusBadRequest, map[string]string{"error": "unsupported_mime_type"}
    }
    if errors.Is(err, ErrUnauthorized) {
        return http.StatusForbidden, map[string]string{"error": "unauthorized"}
    }
    return http.StatusInternalServerError, map[string]string{"error": "internal_error"}
}

package adapter

// MediaFileMapper DB ↔ ドメイン
type MediaFileMapper struct{}

// ToEntity SQL 結果 → ドメイン MediaFile
func (m *MediaFileMapper) ToEntity(row *MediaFileRow) (*domain.MediaFile, error) {
    storageKey := domain.NewStorageKey(row.OrgID, row.ID, "raw")

    return &domain.MediaFile{
        ID:               row.ID,
        OrgID:            row.OrgID,
        UploaderID:       row.UploaderID,
        OriginalFilename: row.OriginalFilename,
        MimeType:         domain.MimeType(row.MimeType),
        FileSizeBytes:    row.FileSizeBytes,
        StorageKey:       storageKey,
        Status:           domain.MediaStatus(row.Status),
        AccessPolicy:     domain.AccessPolicy(row.AccessPolicy),
        CreatedAt:        row.CreatedAt,
        UpdatedAt:        row.UpdatedAt,
    }, nil
}

// ToPersistence ドメイン MediaFile → DB 挿入
func (m *MediaFileMapper) ToPersistence(media *domain.MediaFile) *MediaFileRow {
    return &MediaFileRow{
        ID:               media.ID,
        OrgID:            media.OrgID,
        UploaderID:       media.UploaderID,
        OriginalFilename: media.OriginalFilename,
        MimeType:         string(media.MimeType),
        FileSizeBytes:    media.FileSizeBytes,
        StorageKey:       media.StorageKey.String(),
        Status:           string(media.Status),
        AccessPolicy:     string(media.AccessPolicy),
        CreatedAt:        media.CreatedAt,
        UpdatedAt:        media.UpdatedAt,
    }
}

package infra

import (
    "go.uber.org/fx"
    "github.com/gin-gonic/gin"
    "github.com/lib/pq"
    "database/sql"
)

// Module Storage Service fx Module
func Module() fx.Option {
    return fx.Module("storage-service",
        // インフラプロバイダ
        fx.Provide(
            provideMySQLDB,
            provideRedisClient,
            provideObjectStorageClient,   // Beta: Garage (S3-compatible) / Prod: OCI OSS
            provideQueueClient,           // Beta: Redis / Prod: OCI Queue
            provideGinEngine,
        ),
        // 外部サービスプロバイダ（ポート → アダプタ）
        fx.Provide(
            // StoragePort
            func(cfg *config.StorageConfig, s3c ObjectStorageClient) application.StoragePort {
                switch cfg.Provider {
                case "garage":
                    return adapter.NewGarageStorageAdapter(s3c, cfg.Bucket)
                case "oci-oss":
                    return adapter.NewOCIObjectStorageAdapter(s3c, cfg.Bucket)
                default:
                    panic("unsupported storage.provider: " + cfg.Provider)
                }
            },
            // MediaTranscoderPort
            func() application.MediaTranscoderPort {
                return adapter.NewCompositeTranscoder(
                    adapter.NewLibheifImageAdapter(),
                    adapter.NewFFmpegHLSAdapter(),
                )
            },
            // QueuePort
            func(cfg *config.QueueConfig, redis *redis.Client, ociQ OCIQueueClient) application.QueuePort {
                switch cfg.Provider {
                case "redis-bullmq":
                    return adapter.NewRedisBullMQAdapter(redis)
                case "oci-queue":
                    return adapter.NewOCIQueueAdapter(ociQ)
                default:
                    panic("unsupported queue.provider: " + cfg.Provider)
                }
            },
        ),
        // リポジトリプロバイダ
        fx.Provide(
            func(db *sql.DB) adapter.MediaFileRepository {
                return adapter.NewMySQLMediaFileRepository(db)
            },
            func(db *sql.DB) adapter.MediaChunkRepository {
                return adapter.NewMySQLMediaChunkRepository(db)
            },
            func(db *sql.DB) adapter.ProcessingJobRepository {
                return adapter.NewMySQLProcessingJobRepository(db)
            },
        ),
        // ユースケース
        fx.Provide(
            func(
                mediaRepo adapter.MediaFileRepository,
                storage application.StoragePort,
                jobQueue application.QueuePort,
                emitter application.EventPublisher,
            ) application.UploadMediaSingleUseCase {
                return application.NewUploadMediaSingleUseCase(mediaRepo, storage, jobQueue, emitter)
            },
            func(
                mediaRepo adapter.MediaFileRepository,
                chunkRepo adapter.MediaChunkRepository,
                jobRepo adapter.ProcessingJobRepository,
                storage application.StoragePort,
                transcoder application.MediaTranscoderPort,
                jobQueue application.QueuePort,
            ) application.ProcessMediaUseCase {
                return application.NewProcessMediaUseCase(mediaRepo, chunkRepo, jobRepo, storage, transcoder, jobQueue)
            },
            // その他のユースケース...
        ),
        // ハンドラ登録
        fx.Invoke(registerHandlers),
    )
}

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

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

// provideObjectStorageClient は Beta (Garage) では AWS S3 互換クライアント、
// Prod (OCI Object Storage) では OCI Go SDK クライアントを返す
func provideObjectStorageClient(cfg *config.StorageConfig) ObjectStorageClient {
    switch cfg.Provider {
    case "garage":
        // Garage は S3 互換 API、AWS SDK for Go v2 を流用
        return adapter.NewS3CompatibleClient(cfg.Endpoint, cfg.AccessKey, cfg.SecretKey, cfg.Region)
    case "oci-oss":
        return adapter.NewOCIObjectStorageClient(cfg.OCITenancy, cfg.OCINamespace, cfg.OCIRegion)
    default:
        panic("unsupported storage.provider: " + cfg.Provider)
    }
}

// provideQueueClient は Beta で Redis、Prod で OCI Queue クライアントを返す
func provideQueueClient(cfg *config.QueueConfig, redis *redis.Client) QueueClient {
    switch cfg.Provider {
    case "redis-bullmq":
        return adapter.NewRedisQueueClient(redis)
    case "oci-queue":
        return adapter.NewOCIQueueClient(cfg.OCIQueueOCID, cfg.OCIRegion)
    default:
        panic("unsupported queue.provider: " + cfg.Provider)
    }
}

func provideGinEngine() *gin.Engine {
    engine := gin.New()
    engine.Use(gin.Recovery())
    // Multipart size limit: 510MB (image 100MB + video 500MB + overhead)
    engine.MaxMultipartMemory = 510 << 20
    return engine
}

func registerHandlers(
    engine *gin.Engine,
    uploadSingleUC application.UploadMediaSingleUseCase,
    deliverUC application.DeliverMediaUseCase,
    deleteUC application.DeleteMediaUseCase,
) {
    api := engine.Group("/api/media")
    {
        api.POST("", func(c *gin.Context) {
            handler := adapter.NewUploadMediaSingleHandler(uploadSingleUC)
            handler.Handle(c)
        })
        api.GET("/:id/download", func(c *gin.Context) {
            handler := adapter.NewDeliverMediaHandler(deliverUC)
            handler.Handle(c)
        })
        api.DELETE("/:id", func(c *gin.Context) {
            handler := adapter.NewDeleteMediaHandler(deleteUC)
            handler.Handle(c)
        })
    }
}

package domain_test

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

func TestNewMediaFile_Success(t *testing.T) {
    // Arrange
    mimeType := domain.MimeTypeJPEG

    // Act
    media, err := domain.NewMediaFile(
        "org-123",
        "user-456",
        "photo.jpg",
        mimeType,
        50_000_000, // 50MB
        domain.AccessPolicyPrivate,
    )

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, domain.MediaStatusUploading, media.Status)
    assert.Equal(t, domain.AccessPolicyPrivate, media.AccessPolicy)
    assert.Len(t, media.DomainEvents(), 1)
}

func TestNewMediaFile_FileTooLarge(t *testing.T) {
    // 画像が 100MB を超える場合
    _, err := domain.NewMediaFile(
        "org-123",
        "user-456",
        "huge.jpg",
        domain.MimeTypeJPEG,
        200_000_000, // 200MB
        domain.AccessPolicyPrivate,
    )

    assert.Error(t, err)
    assert.Contains(t, err.Error(), "file size exceeds limit")
}

func TestMediaFile_CanBeAccessedBy(t *testing.T) {
    media, _ := domain.NewMediaFile(
        "org-123",
        "user-456",
        "photo.jpg",
        domain.MimeTypeJPEG,
        10_000_000,
        domain.AccessPolicyOrgMembers,
    )

    tests := []struct {
        name          string
        userID        string
        isMember      bool
        isEventMember bool
        expected      bool
    }{
        {
            name:     "Uploader can access PRIVATE",
            userID:   "user-456",
            isMember: false,
            expected: true,
        },
        {
            name:     "Other member can access ORG_MEMBERS",
            userID:   "user-789",
            isMember: true,
            expected: true,
        },
        {
            name:     "Non-member cannot access ORG_MEMBERS",
            userID:   "user-999",
            isMember: false,
            expected: false,
        },
    }

    // Policy を ORG_MEMBERS に更新して再テスト
    media.AccessPolicy = domain.AccessPolicyOrgMembers

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := media.CanBeAccessedBy(tt.userID, tt.isMember, tt.isEventMember)
            assert.Equal(t, tt.expected, result)
        })
    }
}

// 統合テスト
package application_test

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

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

    // Setup: MySQL (MariaDB 互換), Garage (ローカル), Redis Queue
    db, cleanup := setupTestDB(t)
    defer cleanup()

    s3Mock := &mockStorageService{}
    jobQueueMock := &mockJobQueue{}
    mediaRepo := adapter.NewMySQLMediaFileRepository(db)
    emitterMock := &mockEventEmitter{}

    uc := application.NewUploadMediaSingleUseCase(mediaRepo, s3Mock, jobQueueMock, emitterMock)

    // Act
    resp, err := uc.Execute(ctx, &application.UploadMediaSingleRequest{
        FileBody:     []byte("fake jpeg data"),
        OriginalName: "photo.jpg",
        MimeType:     "image/jpeg",
        FileSize:     1_000_000,
        OrgID:        "org-123",
        UploaderID:   "user-456",
        AccessPolicy: "PRIVATE",
    })

    // Assert
    assert.NoError(t, err)
    assert.NotEmpty(t, resp.MediaID)
    assert.Equal(t, "UPLOADING", resp.Status)

    // オブジェクトストレージにアップロードされたか確認
    assert.Equal(t, 1, s3Mock.uploadCount)

    // Queue にジョブが投入されたか確認
    assert.Equal(t, 2, jobQueueMock.enqueueCount) // HEIC_CONVERT + THUMBNAIL_GEN (不要な場合は 1)

    // イベントが発行されたか確認
    assert.Equal(t, 1, emitterMock.publishCount)
}

// Mock 実装
type mockStorageService struct {
    uploadCount int
}

func (m *mockStorageService) Upload(ctx context.Context, key string, data []byte) error {
    m.uploadCount++
    return nil
}

func (m *mockStorageService) UploadStream(ctx context.Context, key string, reader io.Reader, size int64) error {
    return nil
}

func (m *mockStorageService) Download(ctx context.Context, key string) ([]byte, error) {
    return []byte{}, nil
}

func (m *mockStorageService) GeneratePresignedURL(ctx context.Context, key string, expirySeconds int64) (string, error) {
    return "https://fake-presigned.url", nil
}

func (m *mockStorageService) Delete(ctx context.Context, key string) error {
    return nil
}

func (m *mockStorageService) ListObjects(ctx context.Context, prefix string) ([]string, error) {
    return []string{}, nil
}

type mockJobQueue struct {
    enqueueCount int
}

func (m *mockQueue) Enqueue(ctx context.Context, queue string, payload []byte, opts ...application.EnqueueOption) error {
    m.enqueueCount++
    return nil
}