datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0016-file-storage-and-extract.md

# 架构决策记录 - 文件存储和解压处理

## 背景

在 REQ-010-6（元数据拉取核心功能）中，我们已经实现了从 Salesforce Metadata API 拉取元数据的功能。拉取的元数据以 Zip 文件形式返回，需要对这些 Zip 文件进行存储和解压处理。

本需求面临的主要问题包括：
1. Zip 文件存储需要支持本地文件系统和 OSS 存储两种方式
2. 需要处理大文件（可能达到数百 MB），避免内存溢出
3. 文件路径管理需要防止路径遍历攻击
4. 存储空间需要监控和告警机制
5. 需要自动清理过期文件以释放存储空间

相关约束条件：
- 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
- 必须在 datai-salesforce-metadata 模块下实现
- 必须支持大文件处理，内存使用合理
- 必须验证路径安全性，防止路径遍历攻击

## 决策

### 1. 文件存储方案

**决策**: 使用策略模式实现本地文件系统和 OSS 存储的统一接口，通过配置文件动态切换存储方式。

**理由**:
- 策略模式符合开闭原则，易于扩展新的存储方式
- 统一接口简化了业务代码，降低耦合度
- 配置文件动态切换支持不同环境的灵活部署
- 本地文件系统适合开发环境，OSS 适合生产环境

**实现方案**:
- 定义 `IFileStorageService` 接口，包含存储、读取、删除等方法
- 实现 `LocalStorageService` 和 `OssStorageService` 两个策略类
- 使用 Spring 的 `@ConditionalOnProperty` 注解根据配置自动选择实现类
- 配置项：`file.storage.type`（local/oss）

### 2. 文件解压方案

**决策**: 使用 `ZipInputStream` 实现流式解压，避免一次性加载整个 Zip 文件到内存。

**理由**:
- `ZipInputStream` 支持流式处理，内存占用可控
- 可以边读取边解压，适合处理大文件
- Java 标准库，无需额外依赖
- 性能稳定，经过充分验证

**实现方案**:
- 使用 `ZipInputStream` 逐条读取 ZipEntry
- 使用 `BufferedOutputStream` 写入解压后的文件
- 支持进度回调，实时报告解压进度
- 支持取消操作，通过标志位中断解压过程

### 3. 文件路径管理方案

**决策**: 使用 Java NIO 的 `Path` API 处理路径，配合正则表达式验证路径安全性。

**理由**:
- `Path` API 提供了跨平台的路径处理能力
- `normalize()` 方法可以规范化路径，消除 `.` 和 `..`
- `startsWith()` 方法可以验证路径是否在允许的目录下
- 正则表达式可以进一步限制文件名和路径格式

**实现方案**:
- 定义 `PathValidator` 工具类，提供路径验证方法
- 使用 `path.normalize().startsWith(basePath)` 验证路径
- 使用正则表达式限制文件名（不允许包含特殊字符）
- 拒绝包含 `..` 的路径，防止路径遍历攻击

### 4. 存储空间管理方案

**决策**: 使用定时任务定期检查存储空间，当空间不足时发送告警通知。

**理由**:
- 定时任务实现简单，无需额外依赖
- 可以灵活配置检查频率和告警阈值
- 告警通知可以集成现有的通知机制
- 支持多种告警方式（邮件、短信、钉钉等）

**实现方案**:
- 使用 Spring 的 `@Scheduled` 注解实现定时任务
- 使用 `FileStore.getUsableSpace()` 获取可用空间
- 配置项：`file.storage.warning-threshold`（告警阈值，如 80%）
- 告警通知使用现有的 `INotificationService` 接口

### 5. 文件清理方案

**决策**: 使用定时任务定期清理过期文件，支持配置清理策略。

**理由**:
- 定时任务实现简单，易于维护
- 可以灵活配置清理策略（保留天数、文件大小等）
- 清理日志记录完整，便于审计
- 支持手动清理和自动清理两种方式

**实现方案**:
- 使用 Spring 的 `@Scheduled` 注解实现定时任务
- 配置项：`file.cleanup.retention-days`（保留天数）
- 清理策略：根据文件最后修改时间判断是否过期
- 清理前记录日志，清理后更新统计信息
- 提供 RESTful API 接口支持手动清理

## 备选方案

### 1. 文件存储方案备选

**备选方案 A**: 使用 Spring 的 `Resource` 抽象，通过 `ResourceLoader` 动态加载不同的存储实现。

**优点**:
- Spring 原生支持，无需额外代码
- 支持多种资源类型（classpath、file、http、ftp 等）

**缺点**:
- 不支持 OSS 存储
- 接口不够灵活，难以扩展
- 不符合本项目需求

**备选方案 B**: 使用 Apache Commons VFS 实现虚拟文件系统。

**优点**:
- 支持多种文件系统（local、ftp、sftp、s3 等）
- 统一的接口，易于使用

**缺点**:
- 引入额外依赖，增加项目复杂度
- 性能不如直接实现
- 过于重量级，不符合本项目需求

### 2. 文件解压方案备选

**备选方案 A**: 使用 Apache Commons Compress 库。

**优点**:
- 支持多种压缩格式（zip、tar、gzip 等）
- 功能丰富，API 友好

**缺点**:
- 引入额外依赖
- 对于简单的 Zip 解压，Java 标准库已经足够
- 增加项目复杂度

**备选方案 B**: 先将 Zip 文件完整加载到内存，再解压。

**优点**:
- 实现简单

**缺点**:
- 内存占用高，不适合大文件
- 可能导致内存溢出
- 不符合性能要求

### 3. 文件路径管理方案备选

**备选方案 A**: 使用字符串操作处理路径。

**优点**:
- 实现简单

**缺点**:
- 容易出错，跨平台兼容性差
- 需要手动处理路径分隔符
- 安全性难以保证

**备选方案 B**: 使用第三方路径验证库。

**优点**:
- 功能丰富，安全性高

**缺点**:
- 引入额外依赖
- 增加项目复杂度
- Java NIO 的 Path API 已经足够

### 4. 存储空间管理方案备选

**备选方案 A**: 使用第三方监控工具（如 Prometheus + Grafana）。

**优点**:
- 功能强大，可视化效果好
- 支持多种告警方式

**缺点**:
- 引入额外依赖，增加运维复杂度
- 部署成本高
- 对于简单的存储空间监控，过于重量级

**备选方案 B**: 使用操作系统级别的监控（如 cron + shell 脚本）。

**优点**:
- 不依赖应用层

**缺点**:
- 与应用解耦，难以集成
- 维护成本高
- 不符合项目架构

### 5. 文件清理方案备选

**备选方案 A**: 使用操作系统的定时任务（如 cron）。

**优点**:
- 不依赖应用层

**缺点**:
- 与应用解耦，难以集成
- 维护成本高
- 不符合项目架构

**备选方案 B**: 使用文件系统的自动清理机制（如 tmpwatch）。

**优点**:
- 系统级支持，性能好

**缺点**:
- 与应用解耦，难以集成
- 配置不够灵活
- 不符合项目架构

## 影响

### 系统架构影响

1. **新增模块**: 在 `datai-salesforce-metadata` 模块下新增 `file` 包，包含文件存储、解压、路径管理等功能
2. **接口定义**: 定义 `IFileStorageService` 接口，提供统一的文件存储抽象
3. **策略模式**: 使用策略模式实现不同的存储策略，提高系统扩展性
4. **定时任务**: 新增两个定时任务（存储空间监控、文件清理），需要配置定时任务执行器

### 开发流程影响

1. **开发工作量**: 需要开发 5 个主要功能模块，预计工作量 3-5 人天
2. **测试工作量**: 需要进行单元测试、集成测试和性能测试，预计工作量 2-3 人天
3. **代码规范**: 需要遵循项目现有的代码规范和设计模式
4. **文档维护**: 需要更新接口文档和 API 文档

### 运维管理影响

1. **配置管理**: 需要新增配置项（存储类型、告警阈值、保留天数等）
2. **监控告警**: 需要配置存储空间监控和告警通知
3. **日志管理**: 需要记录文件操作日志和清理日志
4. **存储管理**: 需要定期检查存储空间使用情况

## 风险

### 技术风险

1. **大文件处理风险**: 大文件处理不当可能导致内存溢出
   - **缓解措施**: 使用流式处理，限制内存占用
   - **监控指标**: 监控 JVM 内存使用情况

2. **路径安全风险**: 路径验证不完善可能导致路径遍历攻击
   - **缓解措施**: 使用 Path API 和正则表达式双重验证
   - **监控指标**: 记录所有文件操作日志

3. **OSS 存储风险**: OSS 存储不稳定可能导致文件存储失败
   - **缓解措施**: 实现重试机制和降级策略
   - **监控指标**: 监控 OSS 存储成功率和响应时间

### 业务风险

1. **存储空间风险**: 存储空间不足可能导致文件存储失败
   - **缓解措施**: 实现存储空间监控和告警机制
   - **监控指标**: 监控存储空间使用率

2. **文件清理风险**: 文件清理策略不当可能导致重要文件被删除
   - **缓解措施**: 清理前记录日志，支持文件恢复
   - **监控指标**: 记录清理操作日志

### 实施风险

1. **性能风险**: 文件解压和清理可能影响系统性能
   - **缓解措施**: 使用异步处理，限制并发数
   - **监控指标**: 监控系统 CPU 和内存使用情况

2. **兼容性风险**: 不同操作系统的路径处理可能存在兼容性问题
   - **缓解措施**: 使用 Java NIO 的 Path API，保证跨平台兼容性
   - **监控指标**: 在不同操作系统上进行测试

## 回滚策略

### 1. 文件存储回滚策略

如果 OSS 存储出现问题，可以立即切换回本地文件系统：
1. 修改配置文件 `file.storage.type=local`
2. 重启应用
3. 将已存储到 OSS 的文件复制到本地文件系统

### 2. 文件解压回滚策略

如果流式解压出现问题，可以临时使用完整加载方式：
1. 修改代码，使用 `ZipFile` 替代 `ZipInputStream`
2. 限制文件大小，避免内存溢出
3. 优化后重新切换回流式解压

### 3. 文件清理回滚策略

如果文件清理出现问题，可以立即停止清理任务：
1. 修改配置文件，禁用定时任务
2. 恢复被误删的文件（如果有备份）
3. 修复清理策略后重新启用

### 4. 整体回滚策略

如果整个功能出现问题，可以回滚到 REQ-010-6 的状态：
1. 停止使用文件存储和解压功能
2. 将 Zip 文件临时存储在内存中
3. 修复问题后重新启用

## 验收标准

### 功能验收标准

1. **Zip 文件存储**
   - [ ] 本地文件系统存储成功
   - [ ] OSS 存储成功
   - [ ] 存储路径正确
   - [ ] 文件完整性验证通过
   - [ ] 支持配置动态切换

2. **文件解压**
   - [ ] 文件解压成功
   - [ ] 支持大文件处理（> 100MB）
   - [ ] 支持流式解压
   - [ ] 内存使用合理（< 512MB）
   - [ ] 解压文件结构正确
   - [ ] 支持进度回调
   - [ ] 支持取消操作

3. **文件路径管理**
   - [ ] 文件路径管理正常工作
   - [ ] 支持路径规范化
   - [ ] 支持路径验证
   - [ ] 路径格式正确
   - [ ] 路径安全性验证通过
   - [ ] 防止路径遍历攻击

4. **存储空间管理**
   - [ ] 存储空间管理正常工作
   - [ ] 支持存储空间监控
   - [ ] 支持存储空间告警
   - [ ] 存储空间信息准确
   - [ ] 告警通知及时

5. **文件清理**
   - [ ] 文件清理功能正常工作
   - [ ] 支持过期文件自动清理
   - [ ] 支持手动清理
   - [ ] 清理策略可配置
   - [ ] 清理日志记录完整

### 性能验收标准

1. **文件存储性能**
   - [ ] 本地文件系统存储速度 > 50MB/s
   - [ ] OSS 存储速度 > 20MB/s
   - [ ] 并发存储 10 个文件无性能下降

2. **文件解压性能**
   - [ ] 解压速度 > 30MB/s
   - [ ] 内存使用 < 512MB
   - [ ] 并发解压 5 个文件无性能下降

3. **存储空间监控性能**
   - [ ] 监控任务执行时间 < 1s
   - [ ] 不影响系统正常运行

4. **文件清理性能**
   - [ ] 清理任务执行时间 < 5s
   - [ ] 不影响系统正常运行

### 安全性验收标准

1. **路径安全**
   - [ ] 防止路径遍历攻击
   - [ ] 防止文件名注入攻击
   - [ ] 防止符号链接攻击

2. **存储安全**
   - [ ] 文件存储权限正确
   - [ ] OSS 存储访问权限正确
   - [ ] 文件完整性验证通过

### 代码质量验收标准

1. **代码规范**
   - [ ] 代码符合项目编码规范
   - [ ] 有清晰的注释
   - [ ] 通过代码审查

2. **测试覆盖**
   - [ ] 单元测试覆盖率 > 80%
   - [ ] 集成测试覆盖主要场景
   - [ ] 性能测试通过

3. **文档完整**
   - [ ] 接口文档完整
   - [ ] API 文档完整
   - [ ] 使用文档完整

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

1. [REQ-010-7.md](../requirements/REQ-010-7.md) - 文件存储和解压处理需求文档
2. [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
3. [file/index.md](../api-docs/file/index.md) - 文件模块 API 文档索引
4. Java NIO Path API 文档: https://docs.oracle.com/javase/8/docs/api/java/nio/file/Path.html
5. Spring Boot 文件上传文档: https://docs.spring.io/spring-boot/docs/current/reference/html/web.html#web.servlet.spring-multipart
6. Apache Commons Compress 文档: https://commons.apache.org/proper/commons-compress/