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

package domain

import "time"

// EventStatus は Event のライフサイクルステータス
type EventStatus string

const (
    EventStatusDraft    EventStatus = "DRAFT"
    EventStatusActive   EventStatus = "ACTIVE"
    EventStatusArchived EventStatus = "ARCHIVED"
)

// EventCode はイベントの一意な識別子（ユーザー向け）
type EventCode struct {
    value string // 英大文字・数字・ハイフン、max 30
}

func NewEventCode(val string) (EventCode, error) {
    if len(val) == 0 || len(val) > 30 {
        return EventCode{}, fmt.Errorf("invalid length")
    }
    if !isValidEventCodeFormat(val) {
        return EventCode{}, fmt.Errorf("invalid format")
    }
    return EventCode{value: val}, nil
}

// Event ドメインエンティティ
type Event struct {
    ID              string       // ULID
    OrgID           string
    Title           string
    EventCode       EventCode
    Description     string
    StartDate       time.Time
    EndDate         time.Time
    Status          EventStatus
    CoverMediaID    *string
    CreatedBy       string // user_id
    CreatedAt       time.Time
    domainEvents    []interface{}
}

// Create ファクトリメソッド：ドメインルール適用
func NewEvent(orgID, title string, code EventCode, startDate, endDate time.Time, createdBy string) (*Event, error) {
    if startDate.After(endDate) {
        return nil, fmt.Errorf("start_date must be before end_date")
    }
    if title == "" {
        return nil, fmt.Errorf("title required")
    }

    e := &Event{
        ID:        generateULID(),
        OrgID:     orgID,
        Title:     title,
        EventCode: code,
        StartDate: startDate,
        EndDate:   endDate,
        Status:    EventStatusDraft,
        CreatedBy: createdBy,
        CreatedAt: time.Now(),
    }
    e.recordEvent(&EventCreatedEvent{
        EventID:   e.ID,
        OrgID:     orgID,
        Title:     title,
        CreatedBy: createdBy,
    })
    return e, nil
}

// Activate ドメイン操作：DRAFT → ACTIVE
func (e *Event) Activate() error {
    if e.Status != EventStatusDraft {
        return fmt.Errorf("only DRAFT events can be activated")
    }
    if e.Title == "" {
        return fmt.Errorf("title required to activate")
    }
    e.Status = EventStatusActive
    return nil
}

// Archive ドメイン操作：→ ARCHIVED（読み取り専用化）
func (e *Event) Archive() error {
    if e.Status == EventStatusArchived {
        return fmt.Errorf("already archived")
    }
    e.Status = EventStatusArchived
    e.recordEvent(&EventArchivedEvent{
        EventID:    e.ID,
        OrgID:      e.OrgID,
        ArchivedAt: time.Now(),
    })
    return nil
}

// IsReadOnly アーカイブ済みはロック
func (e *Event) IsReadOnly() bool {
    return e.Status == EventStatusArchived
}

// DomainEvents ドメインイベント取得＆クリア（集約パターン）
func (e *Event) DomainEvents() []interface{} {
    events := e.domainEvents
    e.domainEvents = []interface{}{}
    return events
}

func (e *Event) recordEvent(event interface{}) {
    e.domainEvents = append(e.domainEvents, event)
}

// InvitationStatus 招待ステータス
type InvitationStatus string

const (
    InvitationStatusPending  InvitationStatus = "PENDING"
    InvitationStatusAccepted InvitationStatus = "ACCEPTED"
    InvitationStatusDeclined InvitationStatus = "DECLINED"
    InvitationStatusExpired  InvitationStatus = "EXPIRED"
)

// EventInvitation ドメインエンティティ
type EventInvitation struct {
    ID        string
    EventID   string
    OrgID     string
    Email     string
    InvitedBy string // user_id
    Role      EventRole
    Status    InvitationStatus
    ExpiresAt time.Time
    CreatedAt time.Time
}

// NewEventInvitation ファクトリメソッド
func NewEventInvitation(eventID, orgID, email, invitedBy string, role EventRole) (*EventInvitation, error) {
    if !isValidEmail(email) {
        return nil, fmt.Errorf("invalid email")
    }
    return &EventInvitation{
        ID:        generateULID(),
        EventID:   eventID,
        OrgID:     orgID,
        Email:     email,
        InvitedBy: invitedBy,
        Role:      role,
        Status:    InvitationStatusPending,
        ExpiresAt: time.Now().AddDate(0, 0, 30), // 30日有効
        CreatedAt: time.Now(),
    }, nil
}

// EvaluateExpiry ステータス評価（自動 EXPIRED へ遷移）
func (ei *EventInvitation) EvaluateExpiry() {
    if ei.Status == InvitationStatusPending && time.Now().After(ei.ExpiresAt) {
        ei.Status = InvitationStatusExpired
    }
}

// Accept 招待受け入れ
func (ei *EventInvitation) Accept() error {
    ei.EvaluateExpiry()
    if ei.Status != InvitationStatusPending {
        return fmt.Errorf("invitation not in PENDING state")
    }
    ei.Status = InvitationStatusAccepted
    return nil
}

// EventParticipant イベント参加者
type EventParticipant struct {
    EventID  string
    UserID   string
    Role     EventRole
    JoinedAt time.Time
}

// EventRole ロール（権限）
type EventRole string

const (
    EventRoleOwner  EventRole = "OWNER"
    EventRoleAdmin  EventRole = "ADMIN"
    EventRoleMember EventRole = "MEMBER"
    EventRoleGuest  EventRole = "GUEST"
)

// ドメインイベント（集約外への発行）
type EventCreatedEvent struct {
    EventID   string
    OrgID     string
    Title     string
    CreatedBy string
}

type EventArchivedEvent struct {
    EventID    string
    OrgID      string
    ArchivedAt time.Time
}

type EventInvitationSentEvent struct {
    EventID    string
    InviteeEmail string
    InvitedBy  string
}

type EventInvitationAcceptedEvent struct {
    EventID    string
    UserID     string
    OrgID      string
    AcceptedAt time.Time
}

package application

// CreateEventRequest ユースケース入力
type CreateEventRequest struct {
    OrgID       string    `json:"org_id"`
    Title       string    `json:"title"`
    Description string    `json:"description"`
    StartDate   time.Time `json:"start_date"`
    EndDate     time.Time `json:"end_date"`
    EventCode   string    `json:"event_code"`
    CoverMediaID *string  `json:"cover_media_id,omitempty"`
    CreatedBy   string    `json:"created_by"` // user_id
}

// CreateEventResponse ユースケース出力
type CreateEventResponse struct {
    EventID   string    `json:"event_id"`
    Status    string    `json:"status"`
    CreatedAt time.Time `json:"created_at"`
}

// UpdateEventRequest
type UpdateEventRequest struct {
    EventID     string     `json:"event_id"`
    Title       *string    `json:"title,omitempty"`
    Description *string    `json:"description,omitempty"`
    StartDate   *time.Time `json:"start_date,omitempty"`
    EndDate     *time.Time `json:"end_date,omitempty"`
}

// InviteMemberRequest
type InviteMemberRequest struct {
    EventID   string `json:"event_id"`
    OrgID     string `json:"org_id"`
    Email     string `json:"email"`
    Role      string `json:"role"` // MEMBER, GUEST
    InvitedBy string `json:"invited_by"` // user_id
}

// InviteMemberResponse
type InviteMemberResponse struct {
    InvitationID string    `json:"invitation_id"`
    Email        string    `json:"email"`
    ExpiresAt    time.Time `json:"expires_at"`
}

// JoinEventByCodeRequest
type JoinEventByCodeRequest struct {
    OrgID     string `json:"org_id"`
    EventCode string `json:"event_code"`
    UserID    string `json:"user_id"`
}

// JoinEventByCodeResponse
type JoinEventByCodeResponse struct {
    EventID  string `json:"event_id"`
    Title    string `json:"title"`
    JoinedAt time.Time `json:"joined_at"`
}

// AcceptInvitationRequest
type AcceptInvitationRequest struct {
    InvitationID string `json:"invitation_id"`
    UserID       string `json:"user_id"`
}

// ListOrgEventsRequest
type ListOrgEventsRequest struct {
    OrgID      string  `json:"org_id"`
    Status     *string `json:"status,omitempty"` // DRAFT, ACTIVE, ARCHIVED
    Limit      int     `json:"limit"`
    Offset     int     `json:"offset"`
}

// ListOrgEventsResponse
type ListOrgEventsResponse struct {
    Events []EventDTO `json:"events"`
    Total  int64      `json:"total"`
}

type EventDTO struct {
    EventID      string     `json:"event_id"`
    Title        string     `json:"title"`
    Description  string     `json:"description"`
    EventCode    string     `json:"event_code"`
    StartDate    time.Time  `json:"start_date"`
    EndDate      time.Time  `json:"end_date"`
    Status       string     `json:"status"`
    ParticipantCount int    `json:"participant_count"`
    CreatedAt    time.Time  `json:"created_at"`
}

package application

import "context"

// EventRepository イベント永続化のポート
type EventRepository interface {
    // Save イベントを保存（作成・更新両対応）
    Save(ctx context.Context, event *domain.Event) error

    // FindByID イベントを ID で検索
    FindByID(ctx context.Context, eventID string) (*domain.Event, error)

    // FindByCode イベントをコードで検索（org 内で一意）
    FindByCode(ctx context.Context, orgID, code string) (*domain.Event, error)

    // ListByOrg 組織内のイベント一覧（ページング対応）
    ListByOrg(ctx context.Context, orgID string, limit, offset int) ([]*domain.Event, int64, error)

    // ExistsByCode EventCode が既に存在するか（重複チェック用）
    ExistsByCode(ctx context.Context, orgID, code string) (bool, error)
}

// EventInvitationRepository 招待永続化のポート
type EventInvitationRepository interface {
    // Save 招待を保存
    Save(ctx context.Context, invitation *domain.EventInvitation) error

    // FindByID 招待を ID で検索
    FindByID(ctx context.Context, invitationID string) (*domain.EventInvitation, error)

    // FindByEmail イベント内で該当メールの招待を検索
    FindByEmail(ctx context.Context, eventID, email string) (*domain.EventInvitation, error)

    // ListPendingByEmail メールアドレス宛の保留中招待一覧
    ListPendingByEmail(ctx context.Context, email string) ([]*domain.EventInvitation, error)
}

// EventParticipantRepository 参加者管理のポート
type EventParticipantRepository interface {
    // Save 参加者追加
    Save(ctx context.Context, participant *domain.EventParticipant) error

    // FindByEventAndUser イベント内のユーザー参加情報取得
    FindByEventAndUser(ctx context.Context, eventID, userID string) (*domain.EventParticipant, error)

    // ListByEvent イベントの全参加者リスト
    ListByEvent(ctx context.Context, eventID string) ([]*domain.EventParticipant, error)

    // CountByEvent イベント参加者数
    CountByEvent(ctx context.Context, eventID string) (int, error)
}

package application

// EventPublisher イベント発行のポート（QueuePort 実装）
// Beta: RedisBullMQAdapter / AsynqAdapter
// Prod: OCIQueueAdapter
type EventEmitter interface {
    // Publish ドメインイベントを発行
    Publish(ctx context.Context, event interface{}) error

    // PublishBatch 複数イベントをバッチ発行
    PublishBatch(ctx context.Context, events []interface{}) error
}

// NotificationService 通知サービスのポート
type NotificationService interface {
    // SendInvitationEmail 招待メール送信
    SendInvitationEmail(ctx context.Context, inviteeEmail, eventTitle string, expiresAt time.Time) error
}

// PermissionService 権限検証のポート
type PermissionService interface {
    // CanManageEvent ユーザーがイベントを管理できるか
    CanManageEvent(ctx context.Context, userID, orgID string) (bool, error)

    // HasOrgMembership ユーザーが組織に属しているか
    HasOrgMembership(ctx context.Context, userID, orgID string) (bool, error)
}

package adapter

// EventPresenter ドメインモデル → HTTP レスポンスへのマッピング
type EventPresenter struct {
    cache cacheProvider // Redis キャッシュ
}

// PresentEventDTO Event ドメイン → EventDTO
func (p *EventPresenter) PresentEventDTO(event *domain.Event) *EventDTO {
    return &EventDTO{
        EventID:      event.ID,
        Title:        event.Title,
        Description:  event.Description,
        EventCode:    event.EventCode.String(),
        StartDate:    event.StartDate,
        EndDate:      event.EndDate,
        Status:       string(event.Status),
        CreatedAt:    event.CreatedAt,
    }
}

// PresentListResponse リスト レスポンス構築
func (p *EventPresenter) PresentListResponse(events []*domain.Event, total int64) *ListOrgEventsResponse {
    dtos := make([]EventDTO, len(events))
    for i, e := range events {
        dtos[i] = *p.PresentEventDTO(e)
    }
    return &ListOrgEventsResponse{
        Events: dtos,
        Total:  total,
    }
}

// PresentErrorResponse エラー応答
func PresentErrorResponse(err error) (statusCode int, body map[string]string) {
    if errors.Is(err, ErrUnauthorized) {
        return http.StatusForbidden, map[string]string{"error": "unauthorized"}
    }
    if errors.Is(err, ErrEventCodeAlreadyExists) {
        return http.StatusConflict, map[string]string{"error": "event_code_duplicate"}
    }
    return http.StatusInternalServerError, map[string]string{"error": "internal_error"}
}

package adapter

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

// ToEntity SQL 結果 → ドメイン Event
func (m *EventMapper) ToEntity(row *EventRow) (*domain.Event, error) {
    code, err := domain.NewEventCode(row.EventCode)
    if err != nil {
        return nil, err
    }
    return &domain.Event{
        ID:           row.ID,
        OrgID:        row.OrgID,
        Title:        row.Title,
        EventCode:    code,
        Description:  row.Description,
        StartDate:    row.StartDate,
        EndDate:      row.EndDate,
        Status:       domain.EventStatus(row.Status),
        CoverMediaID: row.CoverMediaID,
        CreatedBy:    row.CreatedBy,
        CreatedAt:    row.CreatedAt,
    }, nil
}

// ToPersistence ドメイン Event → DB 挿入用
func (m *EventMapper) ToPersistence(event *domain.Event) *EventRow {
    return &EventRow{
        ID:           event.ID,
        OrgID:        event.OrgID,
        Title:        event.Title,
        EventCode:    event.EventCode.String(),
        Description:  event.Description,
        StartDate:    event.StartDate,
        EndDate:      event.EndDate,
        Status:       string(event.Status),
        CoverMediaID: event.CoverMediaID,
        CreatedBy:    event.CreatedBy,
        CreatedAt:    event.CreatedAt,
    }
}

package infra

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

// Module Events Service 全体の fx Module
func Module() fx.Option {
    return fx.Module("events-service",
        // インフラストラクチャプロバイダ
        fx.Provide(
            provideMySQLDB,                // MySQL 8.x / MariaDB 互換
            provideRedisClient,
            provideQueueAdapter,           // Beta: RedisBullMQAdapter / Prod: OCIQueueAdapter
            provideGinEngine,
        ),
        // リポジトリプロバイダ（アダプタ）
        fx.Provide(
            func(db *sql.DB) adapter.EventRepository {
                return adapter.NewMySQLEventRepository(db)
            },
            func(db *sql.DB) adapter.EventInvitationRepository {
                return adapter.NewMySQLEventInvitationRepository(db)
            },
            func(db *sql.DB) adapter.EventParticipantRepository {
                return adapter.NewMySQLEventParticipantRepository(db)
            },
        ),
        // 外部サービスアダプタ（QueuePort → EventPublisher）
        fx.Provide(
            func(q application.QueuePort) application.EventPublisher {
                return adapter.NewQueueEventPublisher(q)
            },
        ),
        // ユースケース（アプリケーション層）
        fx.Provide(
            func(
                eventRepo adapter.EventRepository,
                publisher application.EventPublisher,
                permSvc application.PermissionService,
            ) application.CreateEventUseCase {
                return application.NewCreateEventUseCase(eventRepo, publisher, permSvc)
            },
            // その他のユースケース...
        ),
        // ハンドラ登録
        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,
        Password: cfg.Password,
    })
}

// provideQueueAdapter: ポリシーに従い Beta/Prod でアダプタを差し替える。
// AWS SQS / SNS は使用しない。
func provideQueueAdapter(cfg *config.QueueConfig, redis *redis.Client) application.QueuePort {
    switch cfg.Provider {
    case "redis-bullmq":
        return adapter.NewRedisBullMQAdapter(redis)
    case "oci-queue":
        return adapter.NewOCIQueueAdapter(cfg.OCIQueueOCID, cfg.OCIRegion)
    default:
        panic("unsupported queue.provider: " + cfg.Provider)
    }
}

func provideGinEngine() *gin.Engine {
    engine := gin.New()
    engine.Use(gin.Recovery())
    return engine
}

func registerHandlers(
    engine *gin.Engine,
    createEventUC application.CreateEventUseCase,
    // 他のユースケース...
) {
    api := engine.Group("/api")
    {
        events := api.Group("/events")
        {
            events.POST("", func(c *gin.Context) {
                handler := adapter.NewCreateEventHandler(createEventUC)
                handler.Handle(c)
            })
            // 他のハンドラ登録...
        }
    }
}

// 許可されないインポートの例（linter で検出）
// adapter/handler.go から domain 内のリポジトリ型への直接インポートは禁止
import "events-svc/internal/adapter/persistence" // ✗ 禁止
import "events-svc/internal/application"         // ✓ 許可

// golangci-lint depguard 設定
// .golangci.yml
depguard:
  rules:
    main:
      deny:
        - pkg: "events-svc/internal/adapter/persistence"
          desc: "Do not import persistence adapters in domain layer"

package domain_test

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

// ユニットテスト：ドメインエンティティ
func TestNewEvent_Success(t *testing.T) {
    // Arrange
    code, _ := domain.NewEventCode("PARTY-2026")
    startDate := time.Now().AddDate(0, 1, 0)
    endDate := startDate.AddDate(0, 0, 7)

    // Act
    event, err := domain.NewEvent(
        "org-123",
        "Summer Party",
        code,
        startDate,
        endDate,
        "user-456",
    )

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, "org-123", event.OrgID)
    assert.Equal(t, domain.EventStatusDraft, event.Status)
    assert.Len(t, event.DomainEvents(), 1)
}

func TestNewEvent_InvalidDates(t *testing.T) {
    code, _ := domain.NewEventCode("PARTY-2026")
    startDate := time.Now().AddDate(0, 1, 0)
    endDate := startDate.AddDate(0, 0, -1) // end < start

    _, err := domain.NewEvent(
        "org-123",
        "Summer Party",
        code,
        startDate,
        endDate,
        "user-456",
    )

    assert.Error(t, err)
    assert.Contains(t, err.Error(), "start_date must be before end_date")
}

func TestEventCode_InvalidFormat(t *testing.T) {
    _, err := domain.NewEventCode("invalid code!")
    assert.Error(t, err)
}

// 統合テスト：ユースケース + リポジトリ
package application_test

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

func TestCreateEventUseCase_Integration(t *testing.T) {
    // Arrange: testcontainers で MySQL スピンアップ
    ctx := context.Background()
    req := testcontainers.GenericContainerRequest{
        ContainerRequest: testcontainers.ContainerRequest{
            Image:        "MySQL:15-alpine",
            ExposedPorts: []string{"5432/tcp"},
            Env: map[string]string{
                "MySQL_DB":       "test_events",
                "MySQL_PASSWORD": "testpass",
            },
            WaitingFor: wait.ForLog("database system is ready to accept connections"),
        },
        Started: true,
    }
    container, _ := testcontainers.GenericContainer(ctx, req)
    defer container.Terminate(ctx)

    // テーブル作成、リポジトリ初期化...
    db, _ := setupTestDB(container)
    eventRepo := adapter.NewMySQLEventRepository(db)
    emitter := &mockEventEmitter{}
    permSvc := &mockPermissionService{canManage: true}

    uc := application.NewCreateEventUseCase(eventRepo, emitter, permSvc)

    // Act
    resp, err := uc.Execute(ctx, &application.CreateEventRequest{
        OrgID:     "org-123",
        Title:     "Test Event",
        EventCode: "TEST-2026",
        StartDate: time.Now().AddDate(0, 1, 0),
        EndDate:   time.Now().AddDate(0, 1, 7),
        CreatedBy: "user-456",
    })

    // Assert
    assert.NoError(t, err)
    assert.NotEmpty(t, resp.EventID)
    assert.Equal(t, "DRAFT", resp.Status)

    // 発行されたイベント検証
    assert.Len(t, emitter.publishedEvents, 1)
}

// Mock 実装
type mockEventEmitter struct {
    publishedEvents []interface{}
}

func (m *mockEventEmitter) Publish(ctx context.Context, event interface{}) error {
    m.publishedEvents = append(m.publishedEvents, event)
    return nil
}

func (m *mockEventEmitter) PublishBatch(ctx context.Context, events []interface{}) error {
    m.publishedEvents = append(m.publishedEvents, events...)
    return nil
}

type mockPermissionService struct {
    canManage bool
}

func (m *mockPermissionService) CanManageEvent(ctx context.Context, userID, orgID string) (bool, error) {
    return m.canManage, nil
}

func (m *mockPermissionService) HasOrgMembership(ctx context.Context, userID, orgID string) (bool, error) {
    return true, nil
}

package domain

// ドメインレベルのエラー定義（値オブジェクト、エンティティのバリデーション）
var (
    ErrInvalidEventCode = errors.New("invalid event code format")
    ErrInvalidEmail     = errors.New("invalid email address")
    ErrInvalidDateRange = errors.New("start_date must be before end_date")
    ErrEmptyTitle       = errors.New("event title cannot be empty")
    ErrInvitationExpired = errors.New("invitation has expired")
)

package application

// ユースケースレベルのエラー定義（リポジトリ、外部サービス）
var (
    ErrEventNotFound           = errors.New("event not found")
    ErrEventCodeAlreadyExists  = errors.New("event code already exists in organization")
    ErrUnauthorized            = errors.New("user not authorized to perform this action")
    ErrInvitationNotFound      = errors.New("invitation not found")
    ErrEventArchived           = errors.New("cannot modify archived event")
    ErrUserAlreadyParticipant  = errors.New("user is already a participant")
    ErrOrgMembershipRequired   = errors.New("user must be organization member")
)

package adapter

// HTTP エラーマッパー
func mapErrorToHTTP(err error) (statusCode int, errorBody ErrorResponse) {
    switch {
    case errors.Is(err, domain.ErrInvalidEventCode):
        return http.StatusBadRequest, ErrorResponse{Error: "invalid_event_code"}
    case errors.Is(err, application.ErrEventCodeAlreadyExists):
        return http.StatusConflict, ErrorResponse{Error: "event_code_duplicate"}
    case errors.Is(err, application.ErrEventNotFound):
        return http.StatusNotFound, ErrorResponse{Error: "not_found"}
    case errors.Is(err, application.ErrUnauthorized):
        return http.StatusForbidden, ErrorResponse{Error: "unauthorized"}
    case errors.Is(err, application.ErrEventArchived):
        return http.StatusUnprocessableEntity, ErrorResponse{Error: "archived_event"}
    default:
        return http.StatusInternalServerError, ErrorResponse{Error: "internal_error"}
    }
}

type ErrorResponse struct {
    Error   string `json:"error"`
    Message string `json:"message,omitempty"`
}