# 采集日志-规范

本规范用于管理后台「采集日志」模块的前端实现，覆盖组件选用、数据表格定义、查询筛选、分页、时间选择、标签颜色映射及操作按钮等方面的设计约定，确保UI风格统一、交互清晰、数据结构对齐后端接口。以下规范与现有模块风格保持一致，参考文档：界面变更执行规范、前端全局规范等。

## 1. 组件规范
- 数据展示：使用 Element Plus 的 el-table 及 el-table-column。
- 查询区域：使用 el-form、el-form-item、el-input、el-select、el-date-picker、el-time-picker（如需）等。
- 选项卡：el-tabs、el-tab-pane，分别承载分析记录、采集周期与原始数据三大区域。
- 弹窗与详情：el-dialog 展示分析详情及原始日志原文等。
- 按钮与标签：el-button、el-tag、el-tooltip 提供操作入口及信息提示。
- 提示与对齐：使用 el-message、el-notification 提供反馈，表格列对齐统一采用左对齐。
- 加载与空态：使用 el-skeleton、empty 组件作为加载与无数据态的占位显示。

## 2. 数据表格列定义
### Tab1：分析记录 表格列
| 字段名 | 展示含义 | 注意事项 |
|---|---|---|
| time | 日志分析时间 | 日期时间格式统一为 yyyy-MM-dd HH:mm:ss |
| address | 采集地址 | 全局唯一识别码或名称 |
| machine | 机床 | 机器编号/名称 |
| type | 分析类型 | 参考下方标签颜色映射 |
| previousProgram | 前程序 | 准确的程序名 |
| currentProgram | 当前程序 | 当前正在执行的程序名 |
| yieldDelta | 产量变化 | 数值变化量，单位需一致 |
| summary | 摘要 | 简短描述分析结果 |
| actions | 操作 | 查看详情按钮等 |

### Tab2：采集周期 表格列
| 字段名 | 展示含义 | 备注 |
|---|---|---|
| time | 周期开始时间 | 统一时间格式 |
| address | 采集地址 | |
| totalMachines | 总机床数 | 统计口径一致 |
| success | 成功次数 | |
| failure | 失败次数 | |
| anomaly | 异常次数 | |
| distribution | 数据分布摘要 | 摘要字段，方便快速浏览 |
| summary | 摘要 | 简要描述周期信息 |

### Tab3：原始数据 表格列
| 字段名 | 展示含义 | 备注 |
|---|---|---|
| rawId | 日志原始ID | |
| logTime | 日志时间 | 解析时间戳 |
| contentPreview | 内容预览 | 仅显示摘要片段 |
| sourceAddress | 数据来源地址 | |

> 注：表格列定义仅为前端展现的约束，实际字段名称以后端接口返回字段为准。

## 3. 查询筛选条件
- 时间范围筛选：使用 el-date-picker 的 date 范围选择，格式 yyyy-MM-dd HH:mm:ss，范围值作为请求的 startTime/endTime。
- 采集地址：下拉或输入框筛选，支持模糊匹配地址名称。
- 机床：下拉选择框，按可选机床列出。
- 分析类型：多选筛选，UI 采用 el-tag 形式展示筛选条件。
- 程序名：文本输入，用于匹配前程序或当前程序。
- 分页参数：page、pageSize，pageSize 默认为 20，支持切换 [20, 50, 100]。
- 备注：筛选条件应可组合使用，且具备清空按钮重置。

## 4. 分页规范
- pageSize 选项：20、50、100
- 分页控件样式：el-pagination，显示总条数、每页条数、页码跳转
- 数据加载时，应显示加载中状态，切换分页时防重复请求，避免并发冲突。

## 5. API 响应格式
- 前端对接后端 API 的统一响应格式为：
```
{ code: 0, message: "success", data: ... }
```
- 当 code 非 0 时，展示错误信息 message，必要时提供可复现的错误提示。

## 6. 时间选择器规范
- 使用 el-date-picker，类型为 daterange，时间格式统一为 yyyy-MM-dd HH:mm:ss，value-format 亦为 yyyy-MM-dd HH:mm:ss。
- 时间筛选优先级高于别的筛选条件；在无时区信息情况下以服务器时区为准。
- Tab1 的时间范围应以分析时间为准，Tab2 的时间范围以周期起止时间为准。

## 7. 分析类型标签颜色映射
- NORMAL_UNCHANGED -> info
- PART_COUNT_INCREASE -> success
- PROGRAM_SWITCH -> warning
- MANUAL_RESET -> warning
- DEVICE_ONLINE -> success
- DEVICE_OFFLINE -> danger
- NEW_DEVICE_FOUND -> danger
- DATA_ANOMALY -> danger
- COLLECTION_FAILED -> danger

## 8. 操作按钮规范
- 行级操作：查看详情按钮，点击后弹出详情弹窗，展示分析详情或原始数据片段。
- 关联跳转：若需要跳转到关联页面，提供跳转按钮，并在按钮上标注目标路径或模块名称。
- 只在需要的场景启用导出、复制等辅助按钮，避免界面拥挤。
- 按钮颜色使用 Element Plus 默认颜色方案，确保与全局主题一致。

## 9. 路由与权限（简要）
- 路由路径：/collect-log（遵循现有路由命名约定）
- 页面权限：遵循统一的路由权限策略，必要时标注只读/编辑权限。

## 10. 错误处理与空态
- 网络异常、接口返回错误应给出清晰的错误信息提示。
- 数据为空时展示空态组件，辅以引导文本。

## 11. 视觉与可访问性
- 保持列宽一致，避免列数据溢出，必要时显示省略号并悬浮显示完整内容。
- 表格行高、文本颜色、对比度符合无障碍要求，确保在常用屏幕下可读。

## 12. 性能与缓存
- 大数据分页时采用服务端分页，前端仅请求当前页数据。
- 尽量使用简化字段，减少表格渲染开销。

## 13. 安全与数据脱敏
- 脱敏处理涉及敏感字段的展示，必要时对字段进行脱敏或隐藏。
- 请求应携带适用的鉴权信息，后端返回的数据不可直接暴露敏感字段。

## 14. 版本与兼容性
- 文档版本随代码同步更新，保持与后端接口版本一致。
- 如后端接口变更，及时在前端更新字段映射及展示逻辑。

## 15. 兼容性与国际化
- 支持简体中文显示，未来如扩展到多语言需提供翻译资源。
- UI 组件需要兼容主流浏览器，与公司统一浏览器兼容性要求一致。

## 16. 维护与扩展点
- 行为和字段若增加，必须更新对应的索引与页面文档。
- 新增字段应通过后端接口文档对齐，并同步 Mock 数据结构。

## 17. 附加说明
- 本规范仅定义前端展示层的通用原则，具体字段名称以后端接口返回字段为准。
- 如遇特殊场景，需与后端对接团队共同确认后再实现。

---

备注：如需对照其他模块的设计风格，请参考文档：`docs/02-功能清单/07-告警管理/`等的规范表述。