六角形架構（Ports & Adapters）在 .NET 的實作：讓圖片從本機換到 S3 不用改一行業務程式

// 核心：定義 Port（介面放在 UseCase 專案中）
public interface IImageStorage
{
    Task<string> SaveAsync(string fileName, Stream content, CancellationToken cancellationToken);
}

// 核心：UseCase 只依賴 Port
public class AddImageMessageService
{
    private readonly IImageStorage _imageStorage;
    private readonly IChatRoomRepository _repository;

    public AddImageMessageService(IImageStorage imageStorage, IChatRoomRepository repository)
    {
        _imageStorage = imageStorage;
        _repository = repository;
    }

    public async Task HandleAsync(Guid chatRoomId, string prompt, Stream image, CancellationToken ct)
    {
        var chatRoom = await _repository.GetAsync(chatRoomId, ct);
        var url = await _imageStorage.SaveAsync($"{Guid.NewGuid()}.png", image, ct);

        chatRoom.AddImageMessage(prompt, url);   // 商業規則在聚合根裡
        await _repository.SaveAsync(chatRoom, ct);
    }
}

// Adapter：本機檔案系統（開發、測試環境）
public class LocalImageStorage : IImageStorage
{
    private readonly string _root;
    public LocalImageStorage(IOptions<LocalStorageOptions> options) => _root = options.Value.Path;

    public async Task<string> SaveAsync(string fileName, Stream content, CancellationToken ct)
    {
        var path = Path.Combine(_root, fileName);
        await using var file = File.Create(path);
        await content.CopyToAsync(file, ct);
        return $"/images/{fileName}";
    }
}

// Adapter：AWS S3（正式環境）
public class S3ImageStorage : IImageStorage
{
    private readonly IAmazonS3 _s3;
    private readonly string _bucket;

    public S3ImageStorage(IAmazonS3 s3, IOptions<S3StorageOptions> options)
    {
        _s3 = s3;
        _bucket = options.Value.Bucket;
    }

    public async Task<string> SaveAsync(string fileName, Stream content, CancellationToken ct)
    {
        await _s3.PutObjectAsync(new PutObjectRequest
        {
            BucketName = _bucket,
            Key = fileName,
            InputStream = content
        }, ct);
        return $"https://{_bucket}.s3.amazonaws.com/{fileName}";
    }
}

if (builder.Configuration["AWS_BUCKET"] is not null)
    builder.Services.AddS3ImageStorage(builder.Configuration);
else
    builder.Services.AddLocalImageStorage(builder.Configuration);

NexusGPT.Entities                         ← Domain：聚合根、領域事件（不參考任何專案）
NexusGPT.UseCase                          ← Application：UseCase + Port 介面（只參考 Entities）
NexusGPT.Adapter.Out                      ← Driven Adapter：EF Core Repository（參考 UseCase）
NexusGPT.Adapter.Out.ImageStorage.Local   ← Driven Adapter：本機圖片儲存
NexusGPT.Adapter.Out.ImageStorage.S3      ← Driven Adapter：S3 圖片儲存
NexusGPT.WebApplication                   ← Driving Adapter + 組裝：Controller、Hub、DI 註冊

[Fact]
public async Task HandleAsync_圖片訊息_訊息會帶有儲存後的圖片網址()
{
    var storage = Substitute.For<IImageStorage>();
    storage.SaveAsync(default!, default!, default).ReturnsForAnyArgs("https://img/1.png");
    var repository = new InMemoryChatRoomRepository(ChatRoom.Create("新對話"));

    var sut = new AddImageMessageService(storage, repository);
    await sut.HandleAsync(repository.Id, "一隻貓", Stream.Null, CancellationToken.None);

    repository.Saved.Messages.Last().ImageUrl.Should().Be("https://img/1.png");
}