haoliang-net/docs/02-功能清单/01-采集日志/日志分表与分析设计.md

日志分表与分析设计（草案）

目标与范围

• 对采集日志实现按月分区写入，提升写入吞吐和查询历史的性能。
• 提供可查询的分析摘要字段，便于后台看板展示本次采集及对比分析。
• 不引入新的依赖，不改变现有接口接口风格，确保向后兼容。

设计原则

• 高并发写入：分区写入尽量避免锁争用，分区表应有合理的索引覆盖查询条件。
• 易维护：分区边界需要可扩展，提供脚本自动创建未来分区的能力。
• 可观测：数据结构中包括分析摘要字段，便于 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，返回数据结构包含最近日志、等级分布、总条数和可展示的分析摘要。
• 前端展示要点：顶部筛选区、摘要统计、最近日志表格、日志摘要截断预览。
• 验证要点：前端路由可打开，后端接口能返回结构化数据，字段与前端模板对齐。