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

## 背景

在实现 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](../../Authentication.canvas) - 相关架构图
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **快照时间**: 2026-01-19 00:00:00

### Status

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

## 参考资料

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

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