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

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

// AuditEntry: 不変監査ログエントリ
type AuditEntry struct {
    ID           uuid.UUID
    ActorID      string         // ユーザ/サービス ID
    ActorType    ActorType      // USER, SERVICE, SYSTEM
    Action       AuditAction    // READ, WRITE, DELETE, ...
    ResourceType ResourceType   // USER, ORG, MEDIA, ...
    ResourceID   string         // 対象リソース ID
    Result       AuditResult    // ALLOWED, DENIED, ERROR
    IPAddress    string         // リクエスト元 IP
    UserAgent    string         // HTTP User-Agent
    Metadata     map[string]interface{} // 追加コンテキスト JSON
    OccurredAt   time.Time      // UTC タイムスタンプ
    CreatedAt    time.Time      // レコード作成時刻
}

// IsImmutable: エンティティ変更禁止検査
func (ae *AuditEntry) IsImmutable() bool {
    return ae.ID != uuid.Nil && !ae.CreatedAt.IsZero()
}

// RetentionPolicy: 保持期間ポリシー
type RetentionPolicy struct {
    ID           uuid.UUID
    EventType    string    // "login", "data_change", "admin_action"
    RetentionDays int      // 何日保持するか
    CreatedAt    time.Time
}

// ArchivalJob: アーカイバル実行ジョブ
type ArchivalJob struct {
    ID                uuid.UUID
    BatchID           string           // バッチ識別子
    Status            ArchivalStatus   // PENDING, RUNNING, SUCCESS, FAILED
    RowsCount         int
    ArchivePath       string           // 互換: オブジェクトストレージ上の論理パス（bucket/key）
    ObjectStoragePath string           // Beta: Garage 上のフルパス / Prod: OCI Object Storage 上のフルパス
    ArchivedAt        *time.Time
    CreatedAt         time.Time
    UpdatedAt         time.Time
}

// GDPRAnonymization: GDPR 削除追跡
type GDPRAnonymization struct {
    ID             uuid.UUID
    UserID         string       // 削除対象ユーザ
    RequestedAt    time.Time
    AnonymizedAt   *time.Time
    Status         string       // PENDING, COMPLETED, FAILED
    ErrorMessage   string
}

// Value Objects
type AuditAction string

const (
    ActionRead            AuditAction = "READ"
    ActionWrite           AuditAction = "WRITE"
    ActionDelete          AuditAction = "DELETE"
    ActionLogin           AuditAction = "LOGIN"
    ActionLogout          AuditAction = "LOGOUT"
    ActionPermissionCheck AuditAction = "PERMISSION_CHECK"
    ActionAdminAction     AuditAction = "ADMIN_ACTION"
)

type ResourceType string

const (
    ResourceUser    ResourceType = "USER"
    ResourceOrg     ResourceType = "ORG"
    ResourceMedia   ResourceType = "MEDIA"
    ResourceAlbum   ResourceType = "ALBUM"
    ResourceEvent   ResourceType = "EVENT"
    ResourceMessage ResourceType = "MESSAGE"
)

type ActorType string

const (
    ActorUser    ActorType = "USER"
    ActorService ActorType = "SERVICE"
    ActorSystem  ActorType = "SYSTEM"
)

type AuditResult string

const (
    ResultAllowed AuditResult = "ALLOWED"
    ResultDenied  AuditResult = "DENIED"
    ResultError   AuditResult = "ERROR"
)

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

// RecordAuditEntryInput
type RecordAuditEntryInput struct {
    ActorID      string `json:"actor_id" validate:"required"`
    ActorType    string `json:"actor_type" validate:"required,oneof=USER SERVICE SYSTEM"`
    Action       string `json:"action" validate:"required"`
    ResourceType string `json:"resource_type" validate:"required"`
    ResourceID   string `json:"resource_id" validate:"required"`
    Result       string `json:"result" validate:"required,oneof=ALLOWED DENIED ERROR"`
    IPAddress    string `json:"ip_address" validate:"required,ip"`
    UserAgent    string `json:"user_agent"`
    Metadata     map[string]interface{} `json:"metadata"`
    OccurredAt   string `json:"occurred_at" validate:"required,datetime=2006-01-02T15:04:05Z"`
}

// RecordAuditEntryOutput
type RecordAuditEntryOutput struct {
    AuditEntryID string `json:"audit_entry_id"`
    RecordedAt   string `json:"recorded_at"`
}

// QueryAuditLogsInput
type QueryAuditLogsInput struct {
    DateFrom   string `query:"date_from" validate:"datetime=2006-01-02T15:04:05Z"`
    DateTo     string `query:"date_to" validate:"datetime=2006-01-02T15:04:05Z"`
    ActorID    string `query:"actor_id"`
    Action     string `query:"action"`
    ResourceID string `query:"resource_id"`
    Limit      int    `query:"limit" validate:"max=1000"`
    Offset     int    `query:"offset"`
}

// AuditLogDTO
type AuditLogDTO struct {
    ID           string                 `json:"id"`
    ActorID      string                 `json:"actor_id"`
    ActorType    string                 `json:"actor_type"`
    Action       string                 `json:"action"`
    ResourceType string                 `json:"resource_type"`
    ResourceID   string                 `json:"resource_id"`
    Result       string                 `json:"result"`
    IPAddress    string                 `json:"ip_address"`
    Metadata     map[string]interface{} `json:"metadata"`
    OccurredAt   string                 `json:"occurred_at"`
}

// QueryAuditLogsOutput
type QueryAuditLogsOutput struct {
    Logs       []AuditLogDTO `json:"logs"`
    Total      int           `json:"total"`
    Limit      int           `json:"limit"`
    Offset     int           `json:"offset"`
}

// ExportAuditLogsInput
type ExportAuditLogsInput struct {
    DateFrom   string `json:"date_from" validate:"datetime=2006-01-02T15:04:05Z"`
    DateTo     string `json:"date_to" validate:"datetime=2006-01-02T15:04:05Z"`
    ActorID    string `json:"actor_id"`
    Format     string `json:"format" validate:"oneof=csv json"`
}

// ExportAuditLogsOutput
type ExportAuditLogsOutput struct {
    DownloadURL string `json:"download_url"`
    RowsCount   int    `json:"rows_count"`
}

// AnonymizeGDPRDataInput
type AnonymizeGDPRDataInput struct {
    UserID          string `validate:"required,uuid"`
    GDPRRequestID   string `validate:"required,uuid"`
}

// AnonymizeGDPRDataOutput
type AnonymizeGDPRDataOutput struct {
    AnonymizedCount int    `json:"anonymized_count"`
    Status          string `json:"status"`
    CompletedAt     string `json:"completed_at"`
}

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

// AuditRepository: 監査ログ永続化ポート
type AuditRepository interface {
    // Save: 新規 AuditEntry を保存（不変）
    Save(ctx context.Context, entry *domain.AuditEntry) error

    // FindByID: ID で監査ログを取得
    FindByID(ctx context.Context, id uuid.UUID) (*domain.AuditEntry, error)

    // Query: 条件で監査ログをクエリ
    Query(ctx context.Context, filter *domain.AuditFilter) ([]*domain.AuditEntry, int, error)

    // CountByDateRange: 日付範囲のエントリ件数
    CountByDateRange(ctx context.Context, from, to time.Time) (int, error)

    // FindOlderThan: 指定日付より古いエントリを取得（アーカイバル用）
    FindOlderThan(ctx context.Context, cutoffDate time.Time, limit int) ([]*domain.AuditEntry, error)

    // DeleteByID: 物理削除（GDPR のみ、エントリ自体は保持、PII 匿名化）
    AnonymizePII(ctx context.Context, userID string) error
}

// RetentionPolicyRepository: 保持ポリシーリポジトリ
type RetentionPolicyRepository interface {
    FindAll(ctx context.Context) ([]*domain.RetentionPolicy, error)
    FindByEventType(ctx context.Context, eventType string) (*domain.RetentionPolicy, error)
    Save(ctx context.Context, policy *domain.RetentionPolicy) error
}

// ArchivalJobRepository: アーカイバルジョブリポジトリ
type ArchivalJobRepository interface {
    Save(ctx context.Context, job *domain.ArchivalJob) error
    Update(ctx context.Context, job *domain.ArchivalJob) error
    FindByID(ctx context.Context, id uuid.UUID) (*domain.ArchivalJob, error)
    FindByStatus(ctx context.Context, status string) ([]*domain.ArchivalJob, error)
}

// GDPRAnonymizationRepository: GDPR 追跡リポジトリ
type GDPRAnonymizationRepository interface {
    Save(ctx context.Context, req *domain.GDPRAnonymization) error
    Update(ctx context.Context, req *domain.GDPRAnonymization) error
    FindByID(ctx context.Context, id uuid.UUID) (*domain.GDPRAnonymization, error)
}

// ArchivalService: オブジェクトストレージ アーカイバルポート
// 実装:
//   - Beta: GarageObjectStorageArchivalAdapter (S3 互換 API)
//   - Prod: OCIObjectStorageArchivalAdapter
type ArchivalService interface {
    // ArchiveEntries: エントリリストをオブジェクトストレージへアーカイブ
    // archivePath はバケット内の論理パス（例: audits/2026/01/batch-xxxx.parquet）
    ArchiveEntries(ctx context.Context, entries []*domain.AuditEntry, archivePath string) (objectStoragePath string, err error)

    // DeleteFromDB: アーカイブ済みエントリを DB から削除
    DeleteFromDB(ctx context.Context, entryIDs []uuid.UUID) error
}

// CacheService: キャッシュ（Redis）ポート
type CacheService interface {
    Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
    Get(ctx context.Context, key string) (interface{}, error)
    InvalidatePattern(ctx context.Context, pattern string) error
}

// NotificationService: 通知ポート（GDPR 完了通知）
type NotificationService interface {
    SendGDPRCompletionNotification(ctx context.Context, userID string, count int) error
}

// EventPublisher: ドメインイベント発行ポート
type EventPublisher interface {
    PublishAuditEntryRecorded(ctx context.Context, event *domain.AuditEntryRecordedEvent) error
    PublishArchivalCompleted(ctx context.Context, event *domain.ArchivalCompletedEvent) error
}

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

type AuditPresenter struct{}

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

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

// PresentError: Error → HTTP エラーレスポンス
func (p *AuditPresenter) 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 *AuditPresenter) 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, "Unauthorized"
    default:
        return 500, "Internal server error"
    }
}

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

type AuditMapper struct{}

// MapQueueEventToInput: QueuePort メッセージ (JSON) → RecordAuditEntryInput
func (m *AuditMapper) MapQueueEventToInput(event *queue.Message) (*application.RecordAuditEntryInput, error) {
    var input application.RecordAuditEntryInput
    err := json.Unmarshal([]byte(event.Body), &input)
    if err != nil {
        return nil, fmt.Errorf("failed to unmarshal queue message: %w", err)
    }
    return &input, nil
}

// MapInputToEntity: RecordAuditEntryInput → AuditEntry
func (m *AuditMapper) MapInputToEntity(input *application.RecordAuditEntryInput) (*domain.AuditEntry, error) {
    occurredAt, err := time.Parse(time.RFC3339, input.OccurredAt)
    if err != nil {
        return nil, fmt.Errorf("invalid occurred_at: %w", err)
    }

    return &domain.AuditEntry{
        ID:           uuid.New(),
        ActorID:      input.ActorID,
        ActorType:    domain.ActorType(input.ActorType),
        Action:       domain.AuditAction(input.Action),
        ResourceType: domain.ResourceType(input.ResourceType),
        ResourceID:   input.ResourceID,
        Result:       domain.AuditResult(input.Result),
        IPAddress:    input.IPAddress,
        UserAgent:    input.UserAgent,
        Metadata:     input.Metadata,
        OccurredAt:   occurredAt,
        CreatedAt:    time.Now(),
    }, nil
}

// MapEntityToDTO: AuditEntry → AuditLogDTO
func (m *AuditMapper) MapEntityToDTO(entry *domain.AuditEntry) *application.AuditLogDTO {
    return &application.AuditLogDTO{
        ID:           entry.ID.String(),
        ActorID:      entry.ActorID,
        ActorType:    string(entry.ActorType),
        Action:       string(entry.Action),
        ResourceType: string(entry.ResourceType),
        ResourceID:   entry.ResourceID,
        Result:       string(entry.Result),
        IPAddress:    entry.IPAddress,
        Metadata:     entry.Metadata,
        OccurredAt:   entry.OccurredAt.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"
)

// FX モジュール: 依存関係の登録
var AuditModule = fx.Module("audit",
    fx.Provide(
        // インフラストラクチャ提供者
        provideMySQLDB,                   // MySQL 8.x / MariaDB 互換
        provideRedis,
        provideObjectStorageArchiver,     // Beta: Garage / Prod: OCI OSS
        provideQueueAdapter,              // Beta: Redis+BullMQ / Prod: OCI Queue

        // リポジトリ実装
        repository.NewMySQLAuditRepository,
        repository.NewMySQLRetentionPolicyRepository,
        repository.NewMySQLArchivalJobRepository,

        // ユースケース
        usecase.NewRecordAuditEntryUsecase,
        usecase.NewQueryAuditLogsUsecase,
        usecase.NewArchiveOldLogsUsecase,
        usecase.NewAnonymizeGDPRDataUsecase,

        // ハンドラ
        handler.NewQueueEventHandler,     // QueuePort 経由でイベント消費
        handler.NewGetAuditLogsHandler,
        handler.NewExportAuditLogsHandler,

        // プレゼンター
        handler.NewAuditPresenter,
    ),
)

// provideMySQLDB: MySQL/MariaDB コネクションプール
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,
    })
}

// provideObjectStorageArchiver: ArchivalService のアダプタ選択
//   storage.provider = "garage"   → GarageObjectStorageArchivalAdapter (S3互換APIクライアント)
//   storage.provider = "oci-oss"  → OCIObjectStorageArchivalAdapter
func provideObjectStorageArchiver(cfg *config.Config) application.ArchivalService {
    switch cfg.StorageProvider {
    case "garage":
        return adapter.NewGarageObjectStorageArchivalAdapter(cfg.StorageEndpoint, cfg.StorageBucket, cfg.StorageAccessKey, cfg.StorageSecretKey)
    case "oci-oss":
        return adapter.NewOCIObjectStorageArchivalAdapter(cfg.OCINamespace, cfg.OCIBucket, cfg.OCIRegion)
    default:
        panic("unsupported storage.provider: " + cfg.StorageProvider)
    }
}

// provideQueueAdapter: QueuePort アダプタ選択
//   queue.provider = "redis-bullmq" → Beta
//   queue.provider = "oci-queue"    → Prod
func provideQueueAdapter(cfg *config.Config, redis *redis.Client) application.QueuePort {
    switch cfg.QueueProvider {
    case "redis-bullmq":
        return adapter.NewRedisBullMQAdapter(redis)
    case "oci-queue":
        return adapter.NewOCIQueueAdapter(cfg.OCIQueueOCID, cfg.OCIRegion)
    default:
        panic("unsupported queue.provider: " + cfg.QueueProvider)
    }
}

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

func startServer(
    handler *handler.GetAuditLogsHandler,
    queueHandler *handler.QueueEventHandler,
) {
    e := echo.New()
    e.GET("/api/audits", handler.Handle)

    go queueHandler.StartConsumer()

    e.Start(":8080")
}

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

import (
    "testing"
    "time"
    "github.com/stretchr/testify/assert"
    "github.com/google/uuid"
    "recuerdo/audit/domain"
)

func TestAuditEntryImmutability(t *testing.T) {
    entry := &domain.AuditEntry{
        ID:        uuid.New(),
        ActorID:   "user-123",
        Action:    domain.ActionWrite,
        CreatedAt: time.Now(),
    }

    // エンティティは作成後 immutable
    assert.True(t, entry.IsImmutable())
}

func TestRecordAuditEntryValidation(t *testing.T) {
    tests := []struct {
        name    string
        input   *domain.AuditEntry
        wantErr bool
    }{
        {
            name: "valid audit entry",
            input: &domain.AuditEntry{
                ID:           uuid.New(),
                ActorID:      "user-123",
                ActorType:    domain.ActorUser,
                Action:       domain.ActionWrite,
                ResourceType: domain.ResourceMedia,
                ResourceID:   "media-456",
                Result:       domain.ResultAllowed,
                IPAddress:    "192.168.1.1",
                OccurredAt:   time.Now().UTC(),
                CreatedAt:    time.Now().UTC(),
            },
            wantErr: false,
        },
        {
            name: "missing actor_id",
            input: &domain.AuditEntry{
                ID:        uuid.New(),
                ActorID:   "",
                CreatedAt: time.Now(),
            },
            wantErr: true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := tt.input.Validate()
            if tt.wantErr {
                assert.Error(t, err)
            } else {
                assert.NoError(t, err)
            }
        })
    }
}

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

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

type MockAuditRepository struct {
    mock.Mock
}

func (m *MockAuditRepository) Save(ctx context.Context, entry *domain.AuditEntry) error {
    args := m.Called(ctx, entry)
    return args.Error(0)
}

func TestRecordAuditEntryUsecase(t *testing.T) {
    mockRepo := new(MockAuditRepository)
    mockRepo.On("Save", mock.Anything, mock.MatchedBy(func(e *domain.AuditEntry) bool {
        return e.ActorID == "user-123" && e.Action == domain.ActionWrite
    })).Return(nil)

    usecase := application.NewRecordAuditEntryUsecase(mockRepo)

    input := &application.RecordAuditEntryInput{
        ActorID:      "user-123",
        ActorType:    "USER",
        Action:       "WRITE",
        ResourceType: "MEDIA",
        ResourceID:   "media-456",
        Result:       "ALLOWED",
        IPAddress:    "192.168.1.1",
        OccurredAt:   "2026-04-13T10:00:00Z",
    }

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

    assert.NoError(t, err)
    assert.NotNil(t, output)
    assert.NotEmpty(t, output.AuditEntryID)
    mockRepo.AssertExpectations(t)
}

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

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

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

    // MySQL コンテナ起動
    MySQL := testcontainers.NewMySQLContainer(t)
    defer MySQL.Terminate(context.Background())

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

    entry := &domain.AuditEntry{
        ID:           uuid.New(),
        ActorID:      "user-123",
        ActorType:    domain.ActorUser,
        Action:       domain.ActionWrite,
        ResourceType: domain.ResourceMedia,
        ResourceID:   "media-456",
        Result:       domain.ResultAllowed,
        IPAddress:    "192.168.1.1",
        OccurredAt:   time.Now().UTC(),
        CreatedAt:    time.Now().UTC(),
    }

    err := repo.Save(context.Background(), entry)
    assert.NoError(t, err)

    // 検証: DB から取得
    retrieved, err := repo.FindByID(context.Background(), entry.ID)
    assert.NoError(t, err)
    assert.Equal(t, entry.ActorID, retrieved.ActorID)
}

type ValidationError struct {
    Message string
}

type ImmutableViolationError struct {
    Message string
}

type NotFoundError struct {
    ResourceID string
}