datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0024-logging.md

架构决策记录 - 详细日志记录和查询

背景

在实现 Salesforce 元数据拉取和部署功能后，需要记录作业的详细执行日志，支持日志查询和导出。当前系统缺乏详细日志记录和查询功能，无法追溯作业的执行过程，无法及时发现和处理作业执行中的问题。

面临的问题：

1. 无法记录作业的详细执行日志
2. 无法查询作业的执行日志
3. 无法导出作业的执行日志
4. 无法分析作业的执行日志

约束条件：

1. 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
2. 必须遵循 Authentication.canvas 中定义的架构和调用关系
3. 必须在 datai-salesforce-metadata 模块下实现
4. 必须使用 MyBatis Plus 作为持久层框架
5. 日志记录和查询性能必须满足要求，不能影响作业执行

相关的业务需求：

1. 日志记录 - 记录作业的详细执行日志
2. 日志查询 - 查询作业的执行日志
3. 日志导出 - 导出作业的执行日志
4. 日志分析 - 分析作业的执行日志

决策

1. 日志记录方案

决策: 使用异步日志记录，使用日志框架记录日志。

理由:

• 异步日志记录可以避免阻塞主线程，不影响作业执行性能
• 日志框架（如 Log4j2、SLF4J）提供了丰富的日志功能，易于使用和维护
• 支持多种日志级别（INFO、WARN、ERROR），便于日志分类和管理
• 支持日志格式化和日志输出到多种目标（文件、数据库、消息队列等）

实现方案:

• 创建 LogLevel 枚举，定义日志级别（INFO、WARN、ERROR）
• 创建 OperationLog 实体类，存储操作日志信息
• 创建 OperationLogMapper 接口，使用 MyBatis Plus 的 BaseMapper
• 创建 IOperationLogService 服务接口
• 创建 OperationLogServiceImpl 服务实现
• 使用异步日志记录，使用 @Async 注解实现异步
• 使用日志框架记录日志，使用 SLF4J 和 Log4j2
• 支持记录拉取作业日志、部署作业日志、Quick Deploy 作业日志、Destructive Changes 作业日志
• 支持记录日志级别、日志内容、日志时间、作业ID等信息

2. 日志查询方案

决策: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页。

理由:

• MyBatis Plus 的 QueryWrapper 提供了丰富的查询方法，简化多条件查询逻辑
• 分页插件可以方便地实现分页查询
• 支持多种查询条件，包括按作业ID、时间范围、日志级别、关键词等查询
• 查询性能良好，满足查询性能要求

实现方案:

• 创建 ILogQueryService 服务接口
• 创建 LogQueryServiceImpl 服务实现
• 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询
• 使用 MyBatis Plus 的分页插件实现分页查询
• 支持按作业ID查询日志
• 支持按时间范围查询日志
• 支持按日志级别查询日志
• 支持按关键词查询日志
• 支持分页查询

3. 日志导出方案

决策: 使用文件导出库实现日志导出，使用流式处理大文件导出。

理由:

• 文件导出库（如 Apache POI、EasyExcel）提供了丰富的文件导出功能，易于使用和维护
• 支持多种文件格式（文本文件、Excel 文件、CSV 文件）
• 流式处理可以避免内存溢出，支持大文件导出
• 导出性能良好，满足导出性能要求

实现方案:

• 创建 ILogExportService 服务接口
• 创建 LogExportServiceImpl 服务实现
• 使用 Apache POI 实现 Excel 文件导出
• 使用 EasyExcel 实现 Excel 文件导出（推荐，性能更好）
• 使用 Java IO 实现文本文件和 CSV 文件导出
• 使用流式处理大文件导出，避免内存溢出
• 支持导出为文本文件
• 支持导出为 Excel 文件
• 支持导出为 CSV 文件

4. 日志分析方案

决策: 使用聚合查询实现日志统计，使用图表展示分析结果。

理由:

• 聚合查询可以快速统计日志数量，提高查询性能
• 图表可以直观展示分析结果，便于用户理解
• 支持多种分析维度，包括按时间、按日志级别、按作业类型等分析
• 分析结果准确，满足分析准确性要求

实现方案:

• 创建 ILogAnalysisService 服务接口
• 创建 LogAnalysisServiceImpl 服务实现
• 使用 MyBatis Plus 的聚合查询实现日志统计
• 使用 ECharts 或其他图表库展示分析结果
• 支持统计错误日志数量
• 支持统计警告日志数量
• 支持统计信息日志数量
• 支持分析作业执行趋势
• 支持按时间分析日志
• 支持按日志级别分析日志
• 支持按作业类型分析日志

备选方案

方案 1: 使用 ELK Stack 实现日志管理

优点:

• ELK Stack（Elasticsearch、Logstash、Kibana）提供了强大的日志管理和分析功能
• 支持实时日志查询和分析
• 支持大规模日志存储和查询

缺点:

• 实现复杂，需要部署和维护 ELK Stack
• 增加系统复杂度
• 需要额外的服务器资源

评估: 不采用，实现复杂，增加系统复杂度

方案 2: 使用消息队列实现日志收集

优点:

• 消息队列可以异步收集日志，不影响作业执行
• 可以解耦日志记录和日志存储
• 支持分布式日志收集

缺点:

• 实现复杂，需要维护消息队列
• 增加系统复杂度
• 可能出现消息丢失或重复消费

评估: 不采用，实现复杂，增加系统复杂度

方案 3: 使用数据库存储日志

优点:

• 数据库存储简单，易于实现和维护
• 支持结构化查询
• 支持事务和索引

缺点:

• 数据库性能可能受到影响
• 存储空间占用较大
• 不适合大规模日志存储

评估: 采用，结合异步日志记录和分表存储，可以满足需求

影响

系统架构影响

• 新增 log 包，包含日志记录和查询相关的服务、控制器、DTO、实体、Mapper、工具类
• 新增 OperationLog 实体类，新增 operation_log 数据库表
• 新增 IOperationLogService、ILogQueryService、ILogExportService、ILogAnalysisService 服务接口
• 新增 OperationLogServiceImpl、LogQueryServiceImpl、LogExportServiceImpl、LogAnalysisServiceImpl 服务实现
• 新增 LogQueryController、LogExportController、LogAnalysisController 控制器

开发流程影响

• 需要开发日志记录和查询相关的服务、控制器、DTO、实体、Mapper、工具类
• 需要创建数据库表和索引
• 需要配置日志框架和异步日志记录
• 需要编写单元测试和集成测试

运维管理影响

• 需要监控日志记录情况
• 需要定期清理过期的日志
• 需要监控日志存储空间
• 需要监控日志查询性能

风险

技术风险

• 日志记录性能风险: 日志记录性能不佳可能影响作业执行
  • 缓解措施: 使用异步日志记录，使用日志框架，优化日志记录频率
• 查询性能风险: 日志查询性能不佳可能影响用户体验
  • 缓解措施: 使用索引优化查询，使用分页查询，使用缓存提高查询性能
• 存储空间风险: 日志过多可能占用大量存储空间
  • 缓解措施: 定期清理过期的日志，使用日志压缩，使用日志归档
• 导出性能风险: 日志导出性能不佳可能导致导出失败
  • 缓解措施: 使用流式处理大文件导出，使用分批导出，使用异步导出
• 分析准确性风险: 日志分析不准确可能导致误判
  • 缓解措施: 使用聚合查询，验证分析结果，提供分析结果导出

业务风险

• 日志记录失败风险: 日志记录失败可能导致日志信息丢失
  • 缓解措施: 使用异步日志记录，记录日志记录失败日志，支持日志记录重试
• 日志查询失败风险: 日志查询失败可能导致无法追溯作业执行过程
  • 缓解措施: 监控日志查询服务，支持日志查询服务重启，记录日志查询日志

实施风险

• 开发周期风险: 日志记录和查询功能开发周期可能较长
  • 缓解措施: 分阶段实施，优先实现核心功能，逐步完善
• 测试风险: 日志记录和查询功能测试可能较为复杂
  • 缓解措施: 编写详细的测试用例，使用自动化测试，进行充分的测试

回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. 禁用日志记录功能: 通过配置文件禁用日志记录功能，不影响作业执行
2. 回滚日志记录代码: 回滚日志记录相关的代码，恢复到之前的版本
3. 回滚数据库表: 删除日志记录相关的数据库表，恢复到之前的数据库结构
4. 回滚配置文件: 回滚日志记录相关的配置文件，恢复到之前的配置

验收标准

定义验证该决策有效性的具体标准和测试方法：

1. 功能完整性: 所有日志记录和查询功能能够正常工作

   • 测试方法: 手动测试日志记录、日志查询、日志导出、日志分析

2. 性能指标: 日志记录和查询性能满足要求，不影响作业执行

   • 测试方法: 性能测试，监控日志记录和查询性能，确保不影响作业执行

3. 完整性: 日志信息完整详细，能够追溯作业执行过程

   • 测试方法: 手动测试日志记录，确保日志信息完整详细

4. 代码规范性: 代码符合项目编码规范，有清晰的注释

   • 测试方法: 代码审查，检查代码规范和注释

5. 可维护性: 代码结构清晰，易于扩展和维护

   • 测试方法: 代码审查，检查代码结构和可维护性

6. 可测试性: 代码易于单元测试和集成测试

   • 测试方法: 单元测试和集成测试，确保测试覆盖率高

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

• Authentication.canvas - 相关架构图
• 具体节点: 集成核心 - 提供与Salesforce的各种连接方式
• 快照时间: 2026-01-19 00:00:00

Status

• Draft
• Accepted
• Superceded

参考资料

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

• REQ-010-15.md - 详细日志记录和查询需求文档
• REQ-010.md - Salesforce元数据拉取和部署主需求文档
• REQ-010-6.md - 元数据拉取核心功能需求文档
• REQ-010-8.md - 元数据部署核心功能需求文档
• REQ-010-14.md - 作业执行监控需求文档
• metadata-module.md - Salesforce Metadata API 模块说明（唯一真源）
• index.md - Salesforce SOAP API Java 客户端参考文档（唯一真源）