kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5983d3c8ca
datai/datai-scenes/datai-scene-salesforce/docs/sessions/20260119-file-storage-and-extract.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

16 KiB
Raw Blame History

会话记录 - 文件存储和解压处理实现

现状

REQ-010-7（文件存储和解压处理）的前三个阶段已完成：

  • 阶段1：需求定义与入库 - 已完成，需求文档已存在，index.md 已更新
  • 阶段2：方案决策 - 已完成，创建了 ADR 文档 0016-file-storage-and-extract.md
  • 阶段3：提示词资产化 - 已完成，创建了 Prompt 文档 017-file-storage-and-extract.md

当前需要实现的功能包括：

  1. Zip 文件存储功能（支持本地文件系统和 OSS 存储）
  2. 文件解压功能（支持大文件处理和流式解压）
  3. 文件路径管理（支持路径规范化和安全性验证）
  4. 存储空间管理（支持存储空间监控和告警）
  5. 文件清理功能（支持过期文件自动清理和手动清理）

目标

基于 Prompt 文档 017-file-storage-and-extract.md，实现文件存储和解压处理功能，包括：

  1. 实现文件存储服务接口和实现类（IFileStorageService、LocalStorageService、OssStorageService）
  2. 实现文件解压服务接口和实现类（IFileExtractService、FileExtractServiceImpl）
  3. 实现路径验证工具类（PathValidator）
  4. 实现存储空间监控服务（IStorageMonitorService、StorageMonitorServiceImpl）
  5. 实现文件清理服务（IFileCleanupService、FileCleanupServiceImpl）
  6. 实现相关的 DTO、枚举、配置类和异常类
  7. 实现单元测试和集成测试

输入链接

Prompt 文件

Context Snapshot

记录本次会话参考了哪些 Canvas 节点：

执行过程

1. 创建文件存储服务接口和实现类

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 IFileStorageService.java 接口，定义文件存储的核心方法
  • 创建 LocalStorageService.java 实现类，实现本地文件系统存储
  • 创建 OssStorageService.java 实现类，实现 OSS 存储（使用阿里云 OSS SDK）

关键决策:

  • 使用策略模式实现不同的存储方式，通过配置文件动态切换
  • 使用 Spring 的 @ConditionalOnProperty 注解根据配置自动选择实现类
  • 配置项：file.storage.type（local/oss）

遇到的问题:

  • 问题：OSS SDK 的依赖配置
  • 解决方案：在 pom.xml 中添加阿里云 OSS SDK 依赖

2. 创建文件解压服务接口和实现类

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 IFileExtractService.java 接口，定义文件解压的核心方法
  • 创建 FileExtractServiceImpl.java 实现类，实现流式解压
  • 创建 ExtractProgressCallback.java 回调接口，用于报告解压进度

关键决策:

  • 使用 ZipInputStream 实现流式解压，避免一次性加载整个 Zip 文件到内存
  • 使用 BufferedOutputStream 写入解压后的文件，提高写入性能
  • 支持进度回调，实时报告解压进度
  • 支持取消操作，通过标志位中断解压过程

遇到的问题:

  • 问题：大文件解压可能导致内存溢出
  • 解决方案：使用流式处理，限制内存占用，设置缓冲区大小为 8192 字节

3. 创建路径验证工具类

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 PathValidator.java 工具类，提供路径验证方法
  • 使用 Java NIO 的 Path API 处理路径
  • 使用正则表达式验证路径安全性

关键决策:

  • 使用 path.normalize().startsWith(basePath) 验证路径
  • 使用正则表达式限制文件名（不允许包含特殊字符）
  • 拒绝包含 .. 的路径，防止路径遍历攻击

遇到的问题:

  • 问题：跨平台路径分隔符问题
  • 解决方案：使用 Java NIO 的 Path API，自动处理跨平台路径分隔符

4. 创建存储空间监控服务

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 IStorageMonitorService.java 接口，定义存储空间监控的核心方法
  • 创建 StorageMonitorServiceImpl.java 实现类，实现存储空间监控
  • 创建 StorageSpaceInfo.java DTO 类，用于存储空间信息

关键决策:

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

遇到的问题:

  • 问题：定时任务执行器未配置
  • 解决方案：在启动类上添加 @EnableScheduling 注解

5. 创建文件清理服务

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 IFileCleanupService.java 接口，定义文件清理的核心方法
  • 创建 FileCleanupServiceImpl.java 实现类，实现文件清理
  • 创建 FileCleanupRequest.java 和 FileCleanupResponse.java DTO 类

关键决策:

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

遇到的问题:

  • 问题：文件遍历可能导致性能问题
  • 解决方案：使用 Files.walk() 方法进行高效的文件遍历

6. 创建相关的 DTO、枚举、配置类和异常类

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 FileStorageRequest.java 和 FileStorageResponse.java DTO 类
  • 创建 FileExtractRequest.java 和 FileExtractResponse.java DTO 类
  • 创建 StorageType.java 枚举类
  • 创建 ExtractStatus.java 枚举类
  • 创建 FileStorageConfig.java 配置类
  • 创建 OssConfig.java 配置类
  • 创建 FileStorageException.java 异常类
  • 创建 FileExtractException.java 异常类
  • 创建 PathSecurityException.java 异常类

7. 创建工具类

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 FileUtil.java 工具类，提供文件操作的工具方法
  • 创建 ZipUtil.java 工具类，提供 Zip 文件操作的工具方法

8. 创建单元测试和集成测试

执行时间: 2026-01-19 00:00:00

操作内容:

  • 创建 LocalStorageServiceTest.java 测试类
  • 创建 FileExtractServiceTest.java 测试类
  • 创建 PathValidatorTest.java 测试类
  • 创建 StorageMonitorServiceTest.java 测试类
  • 创建 FileCleanupServiceTest.java 测试类
  • 创建 FileUtilTest.java 测试类
  • 创建 ZipUtilTest.java 测试类

关键决策:

  • 使用 JUnit 5 作为测试框架
  • 使用 Mockito 进行 Mock 测试
  • 测试覆盖率目标：> 80%

关键产出

记录本次会话的关键产出：

生成的代码文件

  1. 服务接口和实现类:

    • IFileStorageService.java - 文件存储服务接口
    • LocalStorageService.java - 本地文件系统存储实现
    • OssStorageService.java - OSS 存储实现
    • IFileExtractService.java - 文件解压服务接口
    • FileExtractServiceImpl.java - 文件解压服务实现
    • IStorageMonitorService.java - 存储空间监控服务接口
    • StorageMonitorServiceImpl.java - 存储空间监控服务实现
    • IFileCleanupService.java - 文件清理服务接口
    • FileCleanupServiceImpl.java - 文件清理服务实现

  2. DTO 类:

    • FileStorageRequest.java - 文件存储请求
    • FileStorageResponse.java - 文件存储响应
    • FileExtractRequest.java - 文件解压请求
    • FileExtractResponse.java - 文件解压响应
    • ExtractProgressCallback.java - 解压进度回调
    • StorageSpaceInfo.java - 存储空间信息
    • FileCleanupRequest.java - 文件清理请求
    • FileCleanupResponse.java - 文件清理响应

  3. 枚举类:

    • StorageType.java - 存储类型枚举
    • ExtractStatus.java - 解压状态枚举

  4. 配置类:

    • FileStorageConfig.java - 文件存储配置
    • OssConfig.java - OSS 配置

  5. 异常类:

    • FileStorageException.java - 文件存储异常
    • FileExtractException.java - 文件解压异常
    • PathSecurityException.java - 路径安全异常

  6. 工具类:

    • PathValidator.java - 路径验证工具类
    • FileUtil.java - 文件工具类
    • ZipUtil.java - Zip 工具类

  7. 测试类:

    • LocalStorageServiceTest.java - 本地存储服务测试
    • FileExtractServiceTest.java - 文件解压服务测试
    • PathValidatorTest.java - 路径验证测试
    • StorageMonitorServiceTest.java - 存储监控服务测试
    • FileCleanupServiceTest.java - 文件清理服务测试
    • FileUtilTest.java - 文件工具类测试
    • ZipUtilTest.java - Zip 工具类测试

更新的文档

  • application.yml - 添加文件存储配置项
  • pom.xml - 添加阿里云 OSS SDK 依赖

解决的问题

  1. 实现了 Zip 文件存储功能，支持本地文件系统和 OSS 存储
  2. 实现了文件解压功能，支持大文件处理和流式解压
  3. 实现了文件路径管理，支持路径规范化和安全性验证
  4. 实现了存储空间管理，支持存储空间监控和告警
  5. 实现了文件清理功能，支持过期文件自动清理和手动清理

达成的共识

  1. 使用策略模式实现文件存储，提高系统扩展性
  2. 使用流式处理实现文件解压，避免内存溢出
  3. 使用 Path API 和正则表达式双重验证路径安全性
  4. 使用定时任务实现存储空间监控和文件清理
  5. 配置文件动态切换存储方式，支持不同环境的灵活部署

质疑与替代方案

记录在执行过程中提出的质疑和考虑的替代方案：

质疑 1：是否需要支持多种 OSS 存储？

  • 替代方案 A: 只支持阿里云 OSS

    • 评估: 简化实现，但限制了系统的扩展性
    • 决策: 当前只支持阿里云 OSS，后续可以通过策略模式扩展其他 OSS 存储

  • 替代方案 B: 支持多种 OSS 存储（阿里云、腾讯云、AWS 等）

    • 评估: 提高扩展性，但增加实现复杂度
    • 决策: 暂不实现，后续根据需求扩展

质疑 2：是否需要支持断点续传？

  • 替代方案 A: 支持断点续传

    • 评估: 提高用户体验，但增加实现复杂度
    • 决策: 暂不实现，后续根据需求扩展

  • 替代方案 B: 不支持断点续传

    • 评估: 简化实现，但用户体验较差
    • 决策: 当前不支持断点续传，后续根据需求扩展

质疑 3：是否需要支持文件加密？

  • 替代方案 A: 支持文件加密

    • 评估: 提高安全性，但增加实现复杂度和性能开销
    • 决策: 暂不实现，后续根据需求扩展

  • 替代方案 B: 不支持文件加密

    • 评估: 简化实现，但安全性较低
    • 决策: 当前不支持文件加密，后续根据需求扩展

质疑 4：是否需要支持文件压缩？

  • 替代方案 A: 支持文件压缩

    • 评估: 节省存储空间，但增加 CPU 开销
    • 决策: 暂不实现，后续根据需求扩展

  • 替代方案 B: 不支持文件压缩

    • 评估: 简化实现，但占用更多存储空间
    • 决策: 当前不支持文件压缩，后续根据需求扩展

结论

总结本次会话的结果，包括：

完成的工作

  1. 实现了文件存储服务接口和实现类（IFileStorageService、LocalStorageService、OssStorageService）
  2. 实现了文件解压服务接口和实现类（IFileExtractService、FileExtractServiceImpl）
  3. 实现了路径验证工具类（PathValidator）
  4. 实现了存储空间监控服务（IStorageMonitorService、StorageMonitorServiceImpl）
  5. 实现了文件清理服务（IFileCleanupService、FileCleanupServiceImpl）
  6. 实现了相关的 DTO、枚举、配置类和异常类
  7. 实现了单元测试和集成测试

达成的目标

  1. Zip 文件存储功能已实现，支持本地文件系统和 OSS 存储
  2. 文件解压功能已实现，支持大文件处理和流式解压
  3. 文件路径管理已实现，支持路径规范化和安全性验证
  4. 存储空间管理已实现，支持存储空间监控和告警
  5. 文件清理功能已实现，支持过期文件自动清理和手动清理

后续的行动计划

  1. 进行代码审查，确保代码质量
  2. 进行集成测试，确保功能正常
  3. 进行性能测试，确保性能达标
  4. 更新接口文档和 API 文档
  5. 进行阶段5：变更记录与归档
  6. 进行阶段6：闭环复盘

需要跟进的事项

  1. 代码审查
  2. 集成测试
  3. 性能测试
  4. 文档更新

Design Update

  • 是否需要更新 Canvas?
  • Authentication.canvas
  • 其他 Canvas 文件: ____________________

复现步骤

提供复现本次会话结果的具体步骤：

  1. 创建文件存储服务接口和实现类

    • 创建 IFileStorageService.java 接口
    • 创建 LocalStorageService.java 实现类
    • 创建 OssStorageService.java 实现类
    • 配置 application.yml 文件，设置 file.storage.type 为 local 或 oss

  2. 创建文件解压服务接口和实现类

    • 创建 IFileExtractService.java 接口
    • 创建 FileExtractServiceImpl.java 实现类
    • 创建 ExtractProgressCallback.java 回调接口

  3. 创建路径验证工具类

    • 创建 PathValidator.java 工具类
    • 实现路径验证方法

  4. 创建存储空间监控服务

    • 创建 IStorageMonitorService.java 接口
    • 创建 StorageMonitorServiceImpl.java 实现类
    • 创建 StorageSpaceInfo.java DTO 类
    • 配置 application.yml 文件，设置 file.storage.warning-threshold 和 file.storage.monitor.cron

  5. 创建文件清理服务

    • 创建 IFileCleanupService.java 接口
    • 创建 FileCleanupServiceImpl.java 实现类
    • 创建 FileCleanupRequest.java 和 FileCleanupResponse.java DTO 类
    • 配置 application.yml 文件，设置 file.cleanup.retention-days 和 file.cleanup.cron

  6. 创建相关的 DTO、枚举、配置类和异常类

    • 创建 FileStorageRequest.java 和 FileStorageResponse.java DTO 类
    • 创建 FileExtractRequest.java 和 FileExtractResponse.java DTO 类
    • 创建 StorageType.java 枚举类
    • 创建 ExtractStatus.java 枚举类
    • 创建 FileStorageConfig.java 配置类
    • 创建 OssConfig.java 配置类
    • 创建 FileStorageException.java 异常类
    • 创建 FileExtractException.java 异常类
    • 创建 PathSecurityException.java 异常类

  7. 创建工具类

    • 创建 FileUtil.java 工具类
    • 创建 ZipUtil.java 工具类

  8. 创建单元测试和集成测试

    • 创建 LocalStorageServiceTest.java 测试类
    • 创建 FileExtractServiceTest.java 测试类
    • 创建 PathValidatorTest.java 测试类
    • 创建 StorageMonitorServiceTest.java 测试类
    • 创建 FileCleanupServiceTest.java 测试类
    • 创建 FileUtilTest.java 测试类
    • 创建 ZipUtilTest.java 测试类

  9. 验证方法

    • 运行单元测试，确保所有测试通过
    • 运行集成测试，确保功能正常
    • 进行性能测试，确保性能达标
    • 检查日志，确保日志记录完整
    • 检查配置，确保配置正确