chore: add documentation comments and stylecop rules

src/Application/TakeoutSaaS.Application/Storage/Contracts/DirectUploadRequest.cs

@@ -10,8 +10,6 @@ namespace TakeoutSaaS.Application.Storage.Contracts;
 /// </remarks>
 public sealed class DirectUploadRequest(UploadFileType fileType, string fileName, string contentType, long contentLength, string? requestOrigin)
 {
-
-
     /// <summary>
     /// 文件类型。
     /// </summary>

src/Application/TakeoutSaaS.Application/Storage/Contracts/UploadFileRequest.cs

@@ -17,8 +17,6 @@ public sealed class UploadFileRequest(
     long contentLength,
     string? requestOrigin)
 {
-
-
     /// <summary>
     /// 文件分类。
     /// </summary>

src/Application/TakeoutSaaS.Application/Storage/Services/FileStorageService.cs

@@ -35,11 +35,13 @@ public sealed class FileStorageService(
     /// <inheritdoc />
     public async Task<FileUploadResponse> UploadAsync(UploadFileRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 校验请求
         if (request is null)
         {
             throw new BusinessException(ErrorCodes.BadRequest, "上传请求不能为空");
         }
 
+        // 2. 读取安全配置并校验来源/大小/类型
         var options = optionsMonitor.CurrentValue;
         var security = options.Security;
         ValidateOrigin(request.RequestOrigin, security);
@@ -50,15 +52,18 @@ public sealed class FileStorageService(
         var contentType = NormalizeContentType(request.ContentType, extension);
         ResetStream(request.Content);
 
+        // 3. 生成对象键与元数据
         var objectKey = BuildObjectKey(request.FileType, extension);
         var metadata = BuildMetadata(request.FileType);
         var expires = TimeSpan.FromMinutes(Math.Max(1, security.DefaultUrlExpirationMinutes));
         var provider = providerResolver.Resolve();
 
+        // 4. 上传到对象存储
         var uploadResult = await provider.UploadAsync(
             new StorageUploadRequest(objectKey, request.Content, contentType, request.ContentLength, true, expires, metadata),
             cancellationToken).ConfigureAwait(false);
 
+        // 5. 追加防盗链签名并返回
         var finalUrl = AppendAntiLeechToken(uploadResult.SignedUrl ?? uploadResult.Url, objectKey, expires, security);
         logger.LogInformation("文件上传成功：{ObjectKey} ({Size} bytes)", objectKey, request.ContentLength);
 
@@ -73,11 +78,13 @@ public sealed class FileStorageService(
     /// <inheritdoc />
     public async Task<DirectUploadResponse> CreateDirectUploadAsync(DirectUploadRequest request, CancellationToken cancellationToken = default)
     {
+        // 1. 校验请求
         if (request is null)
         {
             throw new BusinessException(ErrorCodes.BadRequest, "直传请求不能为空");
         }
 
+        // 2. 校验来源/大小/类型
         var options = optionsMonitor.CurrentValue;
         var security = options.Security;
         ValidateOrigin(request.RequestOrigin, security);
@@ -87,14 +94,17 @@ public sealed class FileStorageService(
         ValidateExtension(request.FileType, extension, security);
         var contentType = NormalizeContentType(request.ContentType, extension);
 
+        // 3. 构建直传参数
         var objectKey = BuildObjectKey(request.FileType, extension);
         var provider = providerResolver.Resolve();
         var expires = TimeSpan.FromMinutes(Math.Max(1, security.DefaultUrlExpirationMinutes));
 
+        // 4. 向存储获取直传凭证
         var directResult = await provider.CreateDirectUploadAsync(
             new StorageDirectUploadRequest(objectKey, contentType, request.ContentLength, expires),
             cancellationToken).ConfigureAwait(false);
 
+        // 5. 构造直传结果并追加防盗链
         var finalDownloadUrl = directResult.SignedDownloadUrl != null
             ? AppendAntiLeechToken(directResult.SignedDownloadUrl, objectKey, expires, security)
             : null;