chore: add documentation comments and stylecop rules

src/Modules/TakeoutSaaS.Module.Storage/Providers/AliyunOssStorageProvider.cs

@@ -28,6 +28,7 @@ public sealed class AliyunOssStorageProvider(IOptionsMonitor<StorageOptions> opt
     /// <inheritdoc />
     public async Task<StorageUploadResult> UploadAsync(StorageUploadRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 准备元数据
         var options = CurrentOptions;
         var metadata = new ObjectMetadata
         {
@@ -41,13 +42,16 @@ public sealed class AliyunOssStorageProvider(IOptionsMonitor<StorageOptions> opt
         }
 
         // Aliyun OSS SDK 支持异步方法，如未支持将同步封装为任务。
+        // 2. 上传对象
         await PutObjectAsync(options.AliyunOss.Bucket, request.ObjectKey, request.Content, metadata, cancellationToken)
             .ConfigureAwait(false);
 
+        // 3. 生成签名或公有 URL
         var signedUrl = request.GenerateSignedUrl
             ? await GenerateDownloadUrlAsync(request.ObjectKey, request.SignedUrlExpires, cancellationToken).ConfigureAwait(false)
             : null;
 
+        // 4. 返回上传结果
         return new StorageUploadResult
         {
             ObjectKey = request.ObjectKey,
@@ -61,10 +65,12 @@ public sealed class AliyunOssStorageProvider(IOptionsMonitor<StorageOptions> opt
     /// <inheritdoc />
     public Task<StorageDirectUploadResult> CreateDirectUploadAsync(StorageDirectUploadRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 计算过期时间并生成直传/下载链接
         var expiresAt = DateTimeOffset.UtcNow.Add(request.Expires);
         var uploadUrl = GeneratePresignedUrl(request.ObjectKey, request.Expires, SignHttpMethod.Put, request.ContentType);
         var downloadUrl = GeneratePresignedUrl(request.ObjectKey, request.Expires, SignHttpMethod.Get, null);
 
+        // 2. 返回直传参数
         var result = new StorageDirectUploadResult
         {
             UploadUrl = uploadUrl,
@@ -80,6 +86,7 @@ public sealed class AliyunOssStorageProvider(IOptionsMonitor<StorageOptions> opt
     /// <inheritdoc />
     public Task<string> GenerateDownloadUrlAsync(string objectKey, TimeSpan expires, CancellationToken cancellationToken = default)
     {
+        // 1. 生成预签名下载 URL
         var url = GeneratePresignedUrl(objectKey, expires, SignHttpMethod.Get, null);
         return Task.FromResult(url);
     }
@@ -110,6 +117,7 @@ public sealed class AliyunOssStorageProvider(IOptionsMonitor<StorageOptions> opt
     private async Task PutObjectAsync(string bucket, string key, Stream content, ObjectMetadata metadata, CancellationToken cancellationToken)
     {
         var client = EnsureClient();
+        // SDK 无异步则封装为 Task
         await Task.Run(() => client.PutObject(bucket, key, content, metadata), cancellationToken).ConfigureAwait(false);
     }
 

src/Modules/TakeoutSaaS.Module.Storage/Providers/S3StorageProviderBase.cs

@@ -65,6 +65,7 @@ public abstract class S3StorageProviderBase : IObjectStorageProvider, IDisposabl
     /// <inheritdoc />
     public virtual async Task<StorageUploadResult> UploadAsync(StorageUploadRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 构建上传请求
         var putRequest = new PutObjectRequest
         {
             BucketName = Bucket,
@@ -79,12 +80,15 @@ public abstract class S3StorageProviderBase : IObjectStorageProvider, IDisposabl
             putRequest.Metadata[kv.Key] = kv.Value;
         }
 
+        // 2. 执行上传
         await Client.PutObjectAsync(putRequest, cancellationToken).ConfigureAwait(false);
 
+        // 3. 根据需要生成签名 URL
         var signedUrl = request.GenerateSignedUrl
             ? GenerateSignedUrl(request.ObjectKey, request.SignedUrlExpires)
             : null;
 
+        // 4. 返回上传结果
         return new StorageUploadResult
         {
             ObjectKey = request.ObjectKey,
@@ -98,10 +102,12 @@ public abstract class S3StorageProviderBase : IObjectStorageProvider, IDisposabl
     /// <inheritdoc />
     public virtual Task<StorageDirectUploadResult> CreateDirectUploadAsync(StorageDirectUploadRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 计算过期时间并生成直传 URL
         var expiresAt = DateTimeOffset.UtcNow.Add(request.Expires);
         var uploadUrl = GenerateSignedUrl(request.ObjectKey, request.Expires, HttpVerb.PUT, request.ContentType);
         var signedDownload = GenerateSignedUrl(request.ObjectKey, request.Expires);
 
+        // 2. 返回直传参数
         var result = new StorageDirectUploadResult
         {
             UploadUrl = uploadUrl,
@@ -117,6 +123,7 @@ public abstract class S3StorageProviderBase : IObjectStorageProvider, IDisposabl
     /// <inheritdoc />
     public virtual Task<string> GenerateDownloadUrlAsync(string objectKey, TimeSpan expires, CancellationToken cancellationToken = default)
     {
+        // 1. 生成下载签名 URL
         var url = GenerateSignedUrl(objectKey, expires);
         return Task.FromResult(url);
     }