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

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

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