321 lines
12 KiB
Markdown
321 lines
12 KiB
Markdown
# 会话记录 - 详细日志记录和查询
|
||
|
||
## 现状
|
||
|
||
当前项目已经实现了元数据拉取核心功能（REQ-010-6）、元数据部署核心功能（REQ-010-8）和作业执行监控功能（REQ-010-14），需要在此基础上实现详细日志记录和查询功能，以便记录作业的详细执行日志，支持日志查询和导出，支持日志分析。
|
||
|
||
## 目标
|
||
|
||
实现详细日志记录和查询功能，包括日志记录、日志查询、日志导出、日志分析。支持记录拉取和部署作业的详细执行日志，支持日志查询和导出，支持日志分析。
|
||
|
||
## 输入链接
|
||
|
||
- [REQ-010-15.md](../requirements/REQ-010-15.md) - 详细日志记录和查询需求文档
|
||
- [0024-logging.md](../decisions/adr/0024-logging.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 客户端参考文档（唯一真源）
|
||
|
||
## Prompt 文件
|
||
|
||
- [025-logging.md](../prompts/025-logging.md) - 详细日志记录和查询实现提示词
|
||
|
||
## Context Snapshot
|
||
|
||
记录本次会话参考了哪些 Canvas 节点：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **参考节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
## 执行过程
|
||
|
||
### 1. 创建日志级别枚举
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 LogLevel 枚举，定义日志级别（INFO、WARN、ERROR）
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用枚举管理日志级别，提高代码的可读性和可维护性
|
||
|
||
### 2. 创建操作日志实体类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 OperationLog 实体类，存储操作日志信息
|
||
- 使用 MyBatis Plus 的 @TableName、@TableId 注解
|
||
- 使用 Lombok 的 @Data 注解
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的 @TableName、@TableId 注解，简化数据库操作
|
||
- 使用 Lombok 的 @Data 注解，简化代码
|
||
|
||
### 3. 创建操作日志服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 IOperationLogService 服务接口
|
||
- 创建 OperationLogServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现操作日志服务
|
||
- 使用异步日志记录，使用 @Async 注解实现异步
|
||
- 使用日志框架记录日志，使用 SLF4J 和 Log4j2
|
||
- 支持保存日志、异步保存日志、查询日志、按作业ID查询日志、按日志级别查询日志、删除日志、批量删除日志
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用异步日志记录，避免阻塞主线程，不影响作业执行性能
|
||
- 使用日志框架记录日志，使用 SLF4J 和 Log4j2
|
||
|
||
### 4. 创建日志查询服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ILogQueryService 服务接口
|
||
- 创建 LogQueryServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询
|
||
- 使用 MyBatis Plus 的分页插件实现分页查询
|
||
- 支持查询日志列表、查询日志列表（按条件）、查询日志列表（按时间范围）、查询日志列表（按作业ID）
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，简化查询逻辑
|
||
- 使用 MyBatis Plus 的分页插件实现分页查询，提高查询性能
|
||
|
||
### 5. 创建日志导出服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ILogExportService 服务接口
|
||
- 创建 LogExportServiceImpl 服务实现
|
||
- 使用 Apache POI 实现 Excel 文件导出
|
||
- 使用 EasyExcel 实现 Excel 文件导出（推荐，性能更好）
|
||
- 使用 Java IO 实现文本文件和 CSV 文件导出
|
||
- 使用流式处理大文件导出，避免内存溢出
|
||
- 支持导出为文本文件、导出为 Excel 文件、导出为 CSV 文件
|
||
- 支持按条件导出
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 EasyExcel 实现 Excel 文件导出，性能更好
|
||
- 使用流式处理大文件导出，避免内存溢出
|
||
|
||
### 6. 创建日志分析服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ILogAnalysisService 服务接口
|
||
- 创建 LogAnalysisServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的聚合查询实现日志统计
|
||
- 使用 ECharts 或其他图表库展示分析结果
|
||
- 支持分析日志（按作业ID）、分析日志（按时间范围）、分析日志（按日志级别）、分析日志趋势、分析日志统计
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的聚合查询实现日志统计，提高查询性能
|
||
- 使用 ECharts 展示分析结果，直观展示分析结果
|
||
|
||
### 7. 创建控制器
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 LogQueryController 控制器，提供 4 个 RESTful API 接口
|
||
- 创建 LogExportController 控制器，提供 6 个 RESTful API 接口
|
||
- 创建 LogAnalysisController 控制器，提供 5 个 RESTful API 接口
|
||
- 使用 Swagger 的 @Tag、@Operation 注解
|
||
- 使用 Lombok 的 @RequiredArgsConstructor 注解
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 RESTful API 接口，保持接口一致性
|
||
- 使用 Swagger 的 @Tag、@Operation 注解，生成 API 文档
|
||
- 使用 Lombok 的 @RequiredArgsConstructor 注解，简化代码
|
||
|
||
### 8. 创建 Mapper 接口
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 OperationLogMapper 接口，使用 MyBatis Plus 的 BaseMapper
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的 BaseMapper，简化数据库操作
|
||
|
||
### 9. 创建单元测试
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 OperationLogServiceImplTest 单元测试
|
||
- 创建 LogQueryServiceImplTest 单元测试
|
||
- 创建 LogExportServiceImplTest 单元测试
|
||
- 创建 LogAnalysisServiceImplTest 单元测试
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 Spring Boot Test 框架，简化测试代码
|
||
|
||
### 10. 创建数据库表
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 datai_operation_log 表，存储操作日志信息
|
||
- 为 job_execution_id、log_level、log_time 字段创建索引
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 为常用查询字段创建索引，提高查询性能
|
||
|
||
### 11. 更新配置文件
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 更新 application.yml，添加日志框架配置
|
||
- 添加 logging 配置项，包括日志级别、日志输出路径、日志格式等
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 添加日志框架配置，支持多种日志级别和日志输出方式
|
||
|
||
## 关键产出
|
||
|
||
记录本次会话的关键产出，例如：
|
||
|
||
- 生成的代码文件:
|
||
- LogLevel 枚举 - 日志级别枚举
|
||
- OperationLog 实体类 - 操作日志实体类
|
||
- OperationLogMapper 接口 - 操作日志 Mapper 接口
|
||
- IOperationLogService 服务接口 - 操作日志服务接口
|
||
- OperationLogServiceImpl 服务实现 - 操作日志服务实现
|
||
- ILogQueryService 服务接口 - 日志查询服务接口
|
||
- LogQueryServiceImpl 服务实现 - 日志查询服务实现
|
||
- ILogExportService 服务接口 - 日志导出服务接口
|
||
- LogExportServiceImpl 服务实现 - 日志导出服务实现
|
||
- ILogAnalysisService 服务接口 - 日志分析服务接口
|
||
- LogAnalysisServiceImpl 服务实现 - 日志分析服务实现
|
||
- LogQueryController 控制器 - 日志查询控制器
|
||
- LogExportController 控制器 - 日志导出控制器
|
||
- LogAnalysisController 控制器 - 日志分析控制器
|
||
- 单元测试 - OperationLogServiceImplTest、LogQueryServiceImplTest、LogExportServiceImplTest、LogAnalysisServiceImplTest
|
||
- 更新的文档:
|
||
- index.md
|
||
- 创建的文档:
|
||
- 0024-logging.md
|
||
- 025-logging.md
|
||
- 20260119-logging.md
|
||
- 解决的问题:
|
||
- 日志记录问题 - 使用异步日志记录，使用日志框架记录日志
|
||
- 日志查询问题 - 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页
|
||
- 日志导出问题 - 使用文件导出库实现日志导出，使用流式处理大文件导出
|
||
- 日志分析问题 - 使用聚合查询实现日志统计，使用图表展示分析结果
|
||
- 达成的共识:
|
||
- 使用异步日志记录，使用日志框架记录日志
|
||
- 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页
|
||
- 使用文件导出库实现日志导出，使用流式处理大文件导出
|
||
- 使用聚合查询实现日志统计，使用图表展示分析结果
|
||
|
||
## 质疑与替代方案
|
||
|
||
记录在执行过程中提出的质疑和考虑的替代方案：
|
||
|
||
- 质疑：是否需要使用 ELK Stack 实现日志管理？
|
||
- 替代方案：使用 ELK Stack 实现日志管理
|
||
- 评估：ELK Stack 提供了强大的日志管理和分析功能，支持实时日志查询和分析，支持大规模日志存储和查询，但实现复杂，需要部署和维护 ELK Stack，增加系统复杂度，需要额外的服务器资源，不采用
|
||
|
||
- 质疑：是否需要使用消息队列实现日志收集？
|
||
- 替代方案：使用消息队列实现日志收集
|
||
- 评估：消息队列可以异步收集日志，不影响作业执行，可以解耦日志记录和日志存储，支持分布式日志收集，但实现复杂，需要维护消息队列，增加系统复杂度，可能出现消息丢失或重复消费，不采用
|
||
|
||
- 质疑：是否需要使用数据库存储日志？
|
||
- 替代方案：使用数据库存储日志
|
||
- 评估：数据库存储简单，易于实现和维护，支持结构化查询，支持事务和索引，但数据库性能可能受到影响，存储空间占用较大，不适合大规模日志存储，采用，结合异步日志记录和分表存储，可以满足需求
|
||
|
||
## 结论
|
||
|
||
总结本次会话的结果，包括：
|
||
|
||
- 完成的工作:
|
||
- 实现了日志记录功能
|
||
- 实现了日志查询功能
|
||
- 实现了日志导出功能
|
||
- 实现了日志分析功能
|
||
- 创建了完整的单元测试
|
||
- 创建了数据库表
|
||
- 更新了配置文件
|
||
- 达成的目标:
|
||
- 所有日志记录和查询功能均已实现
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 代码结构清晰，易于扩展和维护
|
||
- 代码易于单元测试和集成测试
|
||
- 后续的行动计划:
|
||
- 进行集成测试，确保功能正常
|
||
- 进行性能测试，确保性能满足要求
|
||
- 编写用户文档，说明如何使用日志记录和查询功能
|
||
- 需要跟进的事项:
|
||
- 监控日志记录情况
|
||
- 定期清理过期的日志
|
||
- 监控日志存储空间
|
||
- 监控日志查询性能
|
||
|
||
## Design Update
|
||
|
||
- [x] 是否需要更新 Canvas?
|
||
- [ ] Authentication.canvas - 需要添加详细日志记录和查询功能相关的节点
|
||
- [ ] 其他 Canvas 文件: 无
|
||
|
||
## 复现步骤
|
||
|
||
提供复现本次会话结果的具体步骤：
|
||
|
||
1. 创建 LogLevel 枚举
|
||
2. 创建 OperationLog 实体类
|
||
3. 创建 OperationLogMapper 接口
|
||
4. 创建 IOperationLogService 服务接口和 OperationLogServiceImpl 服务实现
|
||
5. 创建 ILogQueryService 服务接口和 LogQueryServiceImpl 服务实现
|
||
6. 创建 ILogExportService 服务接口和 LogExportServiceImpl 服务实现
|
||
7. 创建 ILogAnalysisService 服务接口和 LogAnalysisServiceImpl 服务实现
|
||
8. 创建 LogQueryController、LogExportController、LogAnalysisController 控制器
|
||
9. 创建单元测试
|
||
10. 创建数据库表 datai_operation_log
|
||
11. 更新配置文件 application.yml
|
||
12. 运行单元测试，确保所有测试通过
|
||
13. 进行集成测试，确保功能正常
|
||
14. 进行性能测试，确保性能满足要求
|