antissoft / lvqianmeiye_ERP

  # 图片上传改造方案梳理
  
  **文档日期**：2025年1月  
  **改造目标**：将图片上传流程改为"先上传到服务器本地，再上传到OSS"
  
  ---
  
  ## 一、当前实现（备份方法）
  
  ### 1.1 当前流程
  
  **标准文件上传**（`Uploader_bak`）：
  1. 验证文件类型
  2. 生成文件路径和文件名
  3. **直接上传到OSS**（`UploadFileByType_bak`）
  4. 获取OSS访问URL
  5. 返回结果
  
  **Base64图片上传**（`UploadBase64Image_bak`）：
  1. 解析Base64数据
  2. 验证图片格式
  3. 生成文件路径和文件名
  4. **直接上传到OSS**
  5. 获取OSS访问URL
  6. 返回结果
  
  **问题**：
  - ❌ 如果OSS上传失败，没有本地备份
  - ❌ 如果OSS服务不可用，无法提供服务
  - ❌ 无法进行本地验证和预览
  
  ---
  
  ## 二、改造方案
  
  ### 2.1 改造后的流程
  
  **标准文件上传**（`Uploader`）：
  1. 验证文件类型
  2. 生成文件路径和文件名
  3. **先上传到服务器本地**
  4. **从服务器本地上传到OSS**
  5. **OSS上传成功 → 删除本地文件**
  6. **OSS上传失败 → 保留本地文件**
  7. 获取访问URL（OSS成功用OSS URL，失败用本地URL）
  8. 返回结果
  
  **Base64图片上传**（`UploadBase64Image`）：
  1. 解析Base64数据
  2. 验证图片格式
  3. 生成文件路径和文件名
  4. **先保存到服务器本地**
  5. **从服务器本地上传到OSS**
  6. **OSS上传成功 → 删除本地文件**
  7. **OSS上传失败 → 保留本地文件**
  8. 获取访问URL（OSS成功用OSS URL，失败用本地URL）
  9. 返回结果
  
  ---
  
  ## 三、详细改造逻辑
  
  ### 3.1 Uploader 方法改造逻辑
  
  **改造前**：
  ```csharp
  // 直接上传到OSS
  await UploadFileByType(file, uploadFilePath, _fileName, forceStoreType);
  ```
  
  **改造后**：
  ```csharp
  // 1. 先上传到服务器本地
  var localFilePath = GetPathByType(type);  // 获取本地存储路径
  var localFileName = _fileName;
  var localFullPath = Path.Combine(localFilePath, localFileName);
  
  // 确保目录存在
  if (!Directory.Exists(localFilePath))
  {
      Directory.CreateDirectory(localFilePath);
  }
  
  // 保存到本地
  using (var localStream = File.Create(localFullPath))
  {
      await file.CopyToAsync(localStream);
  }
  
  // 2. 从服务器本地上传到OSS
  bool ossUploadSuccess = false;
  string fileUrl;
  
  try
  {
      if (type == "annexpic" || forceStoreType == "aliyun-oss")
      {
          // 读取本地文件并上传到OSS
          var bucketName = KeyVariable.BucketName;
          var ossPath = $"{uploadFilePath.TrimEnd('/').TrimEnd('\\')}/{_fileName}";
          
          using (var localFileStream = File.OpenRead(localFullPath))
          {
              await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, ossPath, localFileStream);
          }
          
          ossUploadSuccess = true;
          
          // 3. OSS上传成功，删除本地文件
          if (File.Exists(localFullPath))
          {
              File.Delete(localFullPath);
          }
          
          // 获取OSS访问URL
          fileUrl = await GetOSSAccessUrl(uploadFilePath, _fileName);
      }
      else
      {
          // 非OSS类型，使用本地URL
          fileUrl = string.Format("/api/File/Image/{0}/{1}", type, _fileName);
          ossUploadSuccess = true;  // 本地存储视为成功
      }
  }
  catch (Exception ossEx)
  {
      // 4. OSS上传失败，保留本地文件
      ossUploadSuccess = false;
      
      // 使用本地URL作为降级方案
      fileUrl = string.Format("/api/File/Image/{0}/{1}", type, _fileName);
      
      // 记录错误日志（可选）
      // _logger.LogError(ossEx, "OSS上传失败，使用本地文件作为降级方案");
  }
  ```
  
  ---
  
  ### 3.2 UploadBase64Image 方法改造逻辑
  
  **改造前**：
  ```csharp
  // 直接上传到OSS
  using (var stream = new MemoryStream(imageData))
  {
      await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, ossPath, stream);
  }
  ```
  
  **改造后**：
  ```csharp
  // 1. 先保存到服务器本地
  var localFilePath = GetPathByType(imageType);
  var localFileName = fileName;
  var localFullPath = Path.Combine(localFilePath, localFileName);
  
  // 确保目录存在
  if (!Directory.Exists(localFilePath))
  {
      Directory.CreateDirectory(localFilePath);
  }
  
  // 保存Base64数据到本地
  await File.WriteAllBytesAsync(localFullPath, imageData);
  
  // 2. 从服务器本地上传到OSS
  bool ossUploadSuccess = false;
  string accessUrl;
  
  try
  {
      var bucketName = KeyVariable.BucketName;
      var ossPath = $"{uploadFilePath.TrimEnd('/').TrimEnd('\\')}/{fileName}";
      
      // 读取本地文件并上传到OSS
      using (var localFileStream = File.OpenRead(localFullPath))
      {
          await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, ossPath, localFileStream);
      }
      
      ossUploadSuccess = true;
      
      // 3. OSS上传成功，删除本地文件
      if (File.Exists(localFullPath))
      {
          File.Delete(localFullPath);
      }
      
      // 获取OSS访问URL
      accessUrl = await GetOSSAccessUrl(uploadFilePath, fileName);
  }
  catch (Exception ossEx)
  {
      // 4. OSS上传失败，保留本地文件
      ossUploadSuccess = false;
      
      // 使用本地URL作为降级方案
      accessUrl = string.Format("/api/File/Image/{0}/{1}", imageType, fileName);
      
      // 记录错误日志（可选）
      // _logger.LogError(ossEx, "OSS上传失败，使用本地文件作为降级方案");
  }
  ```
  
  ---
  
  ### 3.3 UploadFileByType 方法改造逻辑
  
  **说明**：`UploadFileByType` 方法需要改造，但改造方式取决于调用场景：
  
  **方案A：保持方法签名不变，内部实现改造**
  - 优点：调用方不需要修改
  - 缺点：方法职责不清晰（既要处理本地又要处理OSS）
  
  **方案B：创建新方法 `UploadFileToLocalThenOSS`**
  - 优点：职责清晰，不影响现有逻辑
  - 缺点：需要修改调用方
  
  **推荐方案B**：创建新方法，保留原方法作为备份
  
  ```csharp
  /// <summary>
  /// 先上传到本地，再上传到OSS（改造后的方法）
  /// </summary>
  [NonAction]
  public async Task<(bool OssSuccess, string LocalPath, string OssPath)> UploadFileToLocalThenOSS(
      IFormFile file, 
      string localFilePath, 
      string ossFilePath, 
      string fileName, 
      string forceStoreType = null)
  {
      var localFullPath = Path.Combine(localFilePath, fileName);
      bool ossUploadSuccess = false;
      string ossPath = null;
      
      try
      {
          // 1. 先保存到本地
          if (!Directory.Exists(localFilePath))
          {
              Directory.CreateDirectory(localFilePath);
          }
          
          using (var localStream = File.Create(localFullPath))
          {
              await file.CopyToAsync(localStream);
          }
          
          // 2. 判断是否需要上传到OSS
          var fileStoreType = !string.IsNullOrEmpty(forceStoreType) ? forceStoreType : KeyVariable.FileStoreType;
          
          if (fileStoreType == "aliyun-oss")
          {
              // 3. 从本地文件上传到OSS
              var bucketName = KeyVariable.BucketName;
              ossPath = $"{ossFilePath.TrimEnd('/').TrimEnd('\\')}/{fileName}";
              
              using (var localFileStream = File.OpenRead(localFullPath))
              {
                  await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, ossPath, localFileStream);
              }
              
              ossUploadSuccess = true;
              
              // 4. OSS上传成功，删除本地文件
              if (File.Exists(localFullPath))
              {
                  File.Delete(localFullPath);
              }
          }
          else
          {
              // 非OSS类型，本地存储视为成功
              ossUploadSuccess = true;
          }
          
          return (ossUploadSuccess, localFullPath, ossPath);
      }
      catch (Exception ex)
      {
          // OSS上传失败，保留本地文件
          ossUploadSuccess = false;
          
          // 记录错误日志
          // _logger.LogError(ex, $"文件上传到OSS失败，保留本地文件: {localFullPath}");
          
          return (ossUploadSuccess, localFullPath, null);
      }
  }
  ```
  
  ---
  
  ## 四、改造要点总结
  
  ### 4.1 关键步骤
  
  1. **先保存到本地**
     - 使用 `File.Create` 或 `File.WriteAllBytesAsync` 保存文件
     - 确保目录存在（`Directory.CreateDirectory`）
  
  2. **从本地上传到OSS**
     - 使用 `File.OpenRead` 读取本地文件
     - 使用 `PutObjectAsync` 上传到OSS
  
  3. **OSS上传成功处理**
     - 删除本地文件（`File.Delete`）
     - 返回OSS访问URL
  
  4. **OSS上传失败处理**
     - 保留本地文件
     - 返回本地访问URL（降级方案）
     - 记录错误日志（可选）
  
  ---
  
  ### 4.2 异常处理
  
  **异常场景**：
  1. **本地保存失败**：直接抛出异常，不继续OSS上传
  2. **OSS上传失败**：捕获异常，保留本地文件，返回本地URL
  3. **OSS上传成功但删除本地文件失败**：记录警告日志，但不影响返回结果
  
  **异常处理代码结构**：
  ```csharp
  try
  {
      // 1. 保存到本地
      // ...
      
      // 2. 上传到OSS
      try
      {
          // OSS上传逻辑
          // ...
          
          // 3. 删除本地文件
          if (File.Exists(localFullPath))
          {
              File.Delete(localFullPath);
          }
      }
      catch (Exception ossEx)
      {
          // OSS上传失败，保留本地文件
          // 返回本地URL
      }
  }
  catch (Exception localEx)
  {
      // 本地保存失败，抛出异常
      throw NCCException.Oh($"文件保存到本地失败: {localEx.Message}", localEx);
  }
  ```
  
  ---
  
  ### 4.3 文件路径处理
  
  **本地路径**：
  - 使用 `GetPathByType(type)` 获取本地存储路径
  - 使用 `Path.Combine(localFilePath, fileName)` 组合完整路径
  - 确保使用系统路径分隔符
  
  **OSS路径**：
  - 使用正斜杠 `/`，不使用 `Path.Combine`
  - 格式：`{uploadFilePath}/{fileName}`
  
  **路径示例**：
  ```csharp
  // 本地路径（Windows: D:\Files\annexpic\20250123_123.jpg）
  var localPath = Path.Combine("D:\\Files\\annexpic", "20250123_123.jpg");
  
  // OSS路径（2025/01/23/20250123_123.jpg）
  var ossPath = "2025/01/23/20250123_123.jpg";
  ```
  
  ---
  
  ### 4.4 URL返回逻辑
  
  **OSS上传成功**：
  - 返回OSS访问URL（带签名）
  - 使用 `GetOSSAccessUrl` 方法生成
  
  **OSS上传失败**：
  - 返回本地访问URL
  - 格式：`/api/File/Image/{type}/{fileName}`
  - 通过 `GetImg` 方法提供访问
  
  ---
  
  ## 五、改造影响分析
  
  ### 5.1 优点
  
  ✅ **数据安全**：
  - 本地有备份，即使OSS失败也能提供服务
  - 可以定期清理本地文件
  
  ✅ **可维护性**：
  - 可以本地验证文件是否正确
  - 便于调试和问题排查
  
  ✅ **降级方案**：
  - OSS服务不可用时，自动降级到本地存储
  - 不影响业务连续性
  
  ---
  
  ### 5.2 缺点
  
  ⚠️ **存储空间**：
  - 需要额外的本地存储空间
  - 如果OSS上传失败，本地文件会累积
  
  ⚠️ **性能影响**：
  - 需要两次写入（本地 + OSS）
  - 可能略微增加上传时间
  
  ⚠️ **清理机制**：
  - 需要定期清理OSS上传失败后保留的本地文件
  - 需要监控本地存储空间
  
  ---
  
  ### 5.3 风险点
  
  1. **本地存储空间不足**：
     - 风险：如果本地磁盘空间不足，可能导致上传失败
     - 缓解：定期清理、监控磁盘空间
  
  2. **OSS上传失败后本地文件累积**：
     - 风险：如果OSS长期不可用，本地文件会大量累积
     - 缓解：定期清理机制、监控本地文件数量
  
  3. **并发问题**：
     - 风险：多线程同时操作同一文件
     - 缓解：文件名使用唯一ID，避免冲突
  
  ---
  
  ## 六、改造实施步骤
  
  ### 6.1 第一步：接口备份 ✅
  
  - ✅ 已完成：`Uploader_bak`、`UploadBase64Image_bak`、`UploadFileByType_bak`
  
  ### 6.2 第二步：梳理逻辑 ✅
  
  - ✅ 已完成：本文档
  
  ### 6.3 第三步：创建新方法（可选）
  
  - 创建 `UploadFileToLocalThenOSS` 方法
  - 或直接改造 `UploadFileByType` 方法
  
  ### 6.4 第四步：改造 Uploader 方法
  
  - 修改 `Uploader` 方法，使用新的上传逻辑
  - 测试标准文件上传功能
  
  ### 6.5 第五步：改造 UploadBase64Image 方法
  
  - 修改 `UploadBase64Image` 方法，使用新的上传逻辑
  - 测试Base64图片上传功能
  
  ### 6.6 第六步：测试验证
  
  - 测试OSS上传成功场景
  - 测试OSS上传失败场景（模拟OSS服务不可用）
  - 测试本地文件删除逻辑
  - 测试降级方案（返回本地URL）
  
  ### 6.7 第七步：清理机制（可选）
  
  - 实现定期清理OSS上传失败后保留的本地文件
  - 添加监控和告警
  
  ---
  
  ## 七、代码结构建议
  
  ### 7.1 方法组织
  
  ```csharp
  // 备份方法（保持不变）
  Uploader_bak
  UploadBase64Image_bak
  UploadFileByType_bak
  
  // 改造后的方法
  Uploader  // 使用新的上传逻辑
  UploadBase64Image  // 使用新的上传逻辑
  UploadFileToLocalThenOSS  // 新的核心上传方法（可选）
  ```
  
  ### 7.2 辅助方法
  
  可能需要添加的辅助方法：
  - `SaveFileToLocal`：保存文件到本地
  - `UploadLocalFileToOSS`：从本地上传到OSS
  - `DeleteLocalFile`：删除本地文件（带异常处理）
  - `GetFileUrl`：根据OSS上传结果返回URL
  
  ---
  
  ## 八、注意事项
  
  ### 8.1 文件权限
  
  - 确保应用有本地文件写入权限
  - 确保应用有本地文件删除权限
  
  ### 8.2 路径安全
  
  - 验证文件路径，防止路径遍历攻击
  - 使用 `Path.GetFullPath` 规范化路径
  
  ### 8.3 资源释放
  
  - 确保文件流正确释放（使用 `using` 语句）
  - 避免文件句柄泄漏
  
  ### 8.4 日志记录
  
  - 记录OSS上传成功/失败日志
  - 记录本地文件删除成功/失败日志
  - 便于问题排查和监控
  
  ---
  
  ## 九、测试用例
  
  ### 9.1 正常流程测试
  
  1. **OSS上传成功**：
     - 文件保存到本地 ✅
     - 文件上传到OSS ✅
     - 本地文件被删除 ✅
     - 返回OSS URL ✅
  
  2. **非OSS类型**：
     - 文件保存到本地 ✅
     - 不进行OSS上传 ✅
     - 返回本地URL ✅
  
  ### 9.2 异常流程测试
  
  1. **OSS上传失败**：
     - 文件保存到本地 ✅
     - OSS上传失败（模拟） ✅
     - 本地文件保留 ✅
     - 返回本地URL ✅
  
  2. **本地保存失败**：
     - 本地保存失败（模拟磁盘满） ✅
     - 抛出异常，不进行OSS上传 ✅
  
  3. **OSS上传成功但删除本地文件失败**：
     - 文件上传到OSS ✅
     - 删除本地文件失败（模拟） ✅
     - 记录警告日志 ✅
     - 返回OSS URL ✅
  
  ---
  
  ## 十、总结
  
  ### 10.1 改造核心
  
  1. **先本地后OSS**：确保数据安全
  2. **成功删除本地**：节省存储空间
  3. **失败保留本地**：提供降级方案
  4. **异常处理完善**：保证系统稳定
  
  ### 10.2 改造收益
  
  - ✅ 提高数据安全性
  - ✅ 提供降级方案
  - ✅ 便于问题排查
  - ✅ 不影响现有功能（有备份）
  
  ### 10.3 后续优化
  
  - 定期清理机制
  - 监控和告警
  - 性能优化（如需要）
  
  ---
  
  **文档完成时间**：2025年1月  
  **文档状态**：✅ **逻辑梳理完成，等待实施**