You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

6.4 KiB

Raw Blame History Unescape Escape

采集日志-规范

本规范用于管理后台「采集日志」模块的前端实现，覆盖组件选用、数据表格定义、查询筛选、分页、时间选择、标签颜色映射及操作按钮等方面的设计约定，确保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. 附加说明

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

6.4 KiB Raw Blame History Unescape Escape