|
|
# 日志分表与分析设计（草案）
|
|
|
|
|
|
## 目标与范围
|
|
|
- 对采集日志实现按月分区写入，提升写入吞吐和查询历史的性能。
|
|
|
- 提供可查询的分析摘要字段，便于后台看板展示本次采集及对比分析。
|
|
|
- 不引入新的依赖，不改变现有接口接口风格，确保向后兼容。
|
|
|
|
|
|
## 设计原则
|
|
|
- 高并发写入：分区写入尽量避免锁争用，分区表应有合理的索引覆盖查询条件。
|
|
|
- 易维护：分区边界需要可扩展，提供脚本自动创建未来分区的能力。
|
|
|
- 可观测：数据结构中包括分析摘要字段，便于 API 与前端直接展示。
|
|
|
- 兼容性：尽量复用现有字段名与数据类型，避免大规模重构。
|
|
|
|
|
|
## 目标表设计（草案）
|
|
|
- 新增分区表 logs_partitioned，字段如下：
|
|
|
- id BIGINT 自增主键
|
|
|
- machine_id INT：机床唯一标识
|
|
|
- program_name VARCHAR(128)：加工程序名
|
|
|
- log_time DATETIME：日志时间点
|
|
|
- log_level VARCHAR(16)：日志等级，默认 INFO
|
|
|
- raw_payload JSON：原始日志数据
|
|
|
- analysis_summary TEXT：本次采集的分析摘要（可追溯、可回放）
|
|
|
- analysis_version VARCHAR(64)：分析逻辑版本
|
|
|
- 索引：idx_machine_time(machine_id, log_time)、idx_program_time(program_name, log_time)
|
|
|
- 分区：PARTITION BY RANGE (TO_DAYS(log_time))
|
|
|
- 示例分区：p202401, p202402, ..., p202501（按月份边界）
|
|
|
|
|
|
## 分区键与分区策略
|
|
|
- 使用 LOG_TIME 的日期维度进行分区：TO_DAYS(log_time) 作为分区区间值。
|
|
|
- 分区命名建议：按 yyyyMM 命名，如 p202401、p202402，以便直观查看。
|
|
|
- 初始覆盖期：从系统落地起，覆盖过去 24 个月及未来 12 个月的分区。
|
|
|
- 未来分区维护：提供周期性脚本（ monthly_partition_maintenance.sql ）来创建新月份分区。
|
|
|
|
|
|
## 分区维护脚本（草案）
|
|
|
- 提供简单的迁移脚本 skeleton，示例位于 database/sqls/partitioned_logs.sql 的分区创建段。
|
|
|
- 未来可将分区维护封装成 SQL store 程序或外部脚本（bash/python），自动按月扩容。
|
|
|
- 维护内容包括：创建新的分区、对旧分区归档/归档策略，及对相关日志表的清理策略。
|
|
|
|
|
|
## 数据分析字段与 API 将暴露的摘要
|
|
|
- analysis_summary 字段存放本次采集的要点、差异、以及可能的异常记录。
|
|
|
- 通过 API 提供最新采集日志及其分析摘要，便于前端看板展示与对比。
|
|
|
- 日志写入路径保持向后兼容：原有原始日志字段保留，新增分析字段仅供访问。
|
|
|
|
|
|
## API/前端对接要点
|
|
|
- 后端应提供查询接口：
|
|
|
- 根据 machine_id、时间范围筛选日志
|
|
|
- 返回最新采集日志及分析摘要
|
|
|
- 前端看板要显示：
|
|
|
- 最新日志时间、机器、程序、分析摘要要点
|
|
|
- 与历史时间点对比的分析摘要对比信息
|
|
|
|
|
|
## 验证与测试计划（草案）
|
|
|
- 基础验证：分区表创建是否成功、是否能够写入数据、是否能查询到分区信息。
|
|
|
- 功能验证：
|
|
|
- 日志写入时附带 analysis_summary 字段
|
|
|
- API 能返回最新采集日志及分析摘要
|
|
|
- 性能/压力测试：在高并发写入情况下分区表的锁争用情况、查询历史时的响应时间。
|
|
|
- 回归测试：现有日志写入路径不受影响，现有看板字段仍可访问
|
|
|
|
|
|
## 后续工作与风险
|
|
|
- 风险：分区设计对现有 ORM/DAO 层的影响，旧查询路径需兼容。
|
|
|
- 后续：与前端看板字段对齐、以及归档/清理策略的落地实现。
|
|
|
|
|
|
### 草案作者：CI 项目组
|
|
|
### 审核日期：2026-05
|
|
|
|
|
|
## 看板草案设计摘要（日志看板）
|
|
|
- 目标：展示最近采集日志、分析摘要，以及提供筛选入口，便于运维与分析人员快速定位问题。
|
|
|
- 数据字段：日志时间戳、机床ID、加工程序名、日志等级、日志摘要。以及可选的分析摘要文本。
|
|
|
- 后端端点草案：GET /api/logs/dashboard，返回数据结构包含最近日志、等级分布、总条数和可展示的分析摘要。
|
|
|
- 前端展示要点：顶部筛选区、摘要统计、最近日志表格、日志摘要截断预览。
|
|
|
- 验证要点：前端路由可打开，后端接口能返回结构化数据，字段与前端模板对齐。
|