# 13-01 采集日志页面

_
本文档按照20项模板撰写，用于前端实现“采集日志页面”的设计与交互规范。页面在管理后台中放置于 /collect-log 路由下，包含三个标签页：分析记录、采集周期、原始数据。_

## 1. 页面基本信息
- 模块：管理后台 -> 采集日志
- 页面名称：采集日志页面
- 路由：/collect-log
- 版本：v1.0
- 作者：设计/前端团队
- 依赖：Element Plus、Vue 3、TypeScript

## 2. 布局结构
- 顶部区域：查询条件区域（时间范围、地址、机床、分析类型、程序名等）
- 中部区域：Tabs 切换，包含三个 Tab：分析记录、采集周期、原始数据
- 各 Tab 之下为各自的表格 + 分页控件
- 底部/弹窗区域：查看详情弹窗、关联跳转入口

## 3. 数据表格列定义
- 分析记录（Tab1）列：时间、地址、机床、分析类型、前程序、当前程序、产量变化、摘要、操作
- 采集周期（Tab2）列：时间、地址、总机床、成功、失败、异常、分布、摘要
- 原始数据（Tab3）列：原始日志ID、时间、内容摘要、来源地址

## 4. 查询条件字段
- 时间范围：日期时间范围选择器，格式 yyyy-MM-dd HH:mm:ss
- 采集地址：下拉或文本输入，支持模糊匹配
- 机床：下拉选择
- 分析类型：多选过滤标签
- 程序名：文本输入
- 提交触发：查询按钮，重置按钮
- 每页显示条数：分页组件控制

## 5. API端点定义
- GET /api/admin/collect-log/analysis
- GET /api/admin/collect-log/analysis/{id}
- GET /api/admin/collect-log/analysis/by-raw/{rawLogId}
- GET /api/admin/collect-log/cycle
- GET /api/admin/collect-log/raw

## 6. Mock数据结构
- 分析记录列表 Mock：数组对象包含 time、address、machine、type、previousProgram、currentProgram、yieldDelta、summary
- 分析详情 Mock：含 detail 字段、difference 和对比数据
- 周期数据 Mock：time、address、totalMachines、success、failure、anomaly、distribution、summary
- 原始数据 Mock：rawId、logTime、contentPreview、sourceAddress

## 7. 交互行为
- 标签页切换：切换时重新加载对应表格数据
- 分页：点击页码、切换每页条数时加载对应页数据
- 查看详情弹窗：选中行后弹出，展示分析详情或对比信息
- 关联跳转：点击相关行的跳转按钮，跳转至对应的关联页面
- 原始数据查看：点击原始数据行，弹出 JSON 原始数据预览

## 8. 组件树
- 组件树示例：CollectLogPage -> (QueryForm, ElTabs -> (AnalysisTab, CycleTab, RawTab) -> (ElTable, ElPagination)) -> DetailDialog
- 表单控件（QueryForm）：el-form、el-form-item、el-date-picker、el-input、el-select、el-tag
- 表格与分页：el-table、el-table-column、el-pagination
- 弹窗：el-dialog
- 细化的子组件：AnalysisTable、CycleTable、RawTable、DetailDialog（可复用）

## 9. 路由配置
- 路由路径：/collect-log
- 路由组件：CollectLogPage
- 路由守卫：同其他管理后台页面的权限控制
- 嵌套路由（若有需要）：/collect-log/analysis、/collect-log/cycle、/collect-log/raw

## 10. 数据校验与错误处理
- 搜索条件必填项的格式校验：时间范围格式、文本字段长度等
- API 请求失败时，展示友好错误信息并保留上一次有效数据展示
- 弹窗中的对比信息若数据为空，显示空态提示

## 11. 性能与优化点
- 分页按需加载，避免一次性加载所有数据
- 表格列尽量避免使用复杂自定义渲染，必要时使用虚拟滚动
- 原始数据区域对大文本使用内容摘要展示，点击展开查看全文

## 12. 国际化与无障碍
- 暂定中文显示，未来支持多语言资源
- 组件具备基础无障碍特性，表格可读性良好

## 13. 数据引用与结构（接口关联）
- 参考后端 API 端点，数据结构需与后端返回字段严格对齐
- 需在页面中以常量形式存放端点引用及字段映射，便于维护

## 14. 组件样式与风格
- 遵循全局主题，表格列宽可自适应，必要时固定宽度以确保对齐
- 按钮、标签、弹窗风格与全局规范保持一致

## 15. 版本与变更记录
- 每次变更需记录版本号和变更摘要，便于回溯
- 与模块索引、总览文档保持同步

## 16. 技术实现概要
- 主要使用 Vue 3 + TypeScript + Element Plus，按项目的前端全局规范实现
- 数据获取走统一的 API 调用封装，错误统一处理
- UI 组件具有可复用性，便于其他模块复用

## 17. 数据流与状态管理
- 页面局部状态通过 Vue 的响应式系统管理
- 表格数据、筛选条件和分页状态保持在组件状态中，必要时通过 Store/Pinia 共享

## 18. 测试用例设计
- 基本渲染测试：页面渲染、表格列正确显示
- 筛选与分页功能测试
- 弹窗查看详情测试
- 跳转与联动测试

## 19. 部署与运行
- 本地调试：确保 /collect-log 路由可访问，接口 Mock/测试环境数据正常
- 与后端联调时保持端点一致，返回字段映射不变

## 20. 变更记录
- 记录本页面文档的变更时间、版本和修改内容，便于团队追踪

---

备注：本文档遵循文档结构规范，确保与其他模块文档风格一致，如需对齐请参考 `docs/02-功能清单/02-文件夹创建规范.md` 与 `docs/02-界面变更执行规范.md`。