前端开发规则

本文件适用于 batteryDetection-web。同时遵守父目录 AGENTS.md 的项目不变量。

状态所有权

• 后端响应是测试、通道、监测、异常、采样、用户、权限和审计的正式状态。前端 store 只保存当前会话的展示缓存和临时表单。
• 新代码不使用 localStorage 保存业务记录。触及已有本地模拟 store 时，将当前流程迁移到后端 API；不要求顺带重写无关页面。
• localStorage 可保存认证令牌、记住的用户名和纯展示偏好。可恢复表单草稿必须明确是草稿，提交成功后清除，且不能参与权限或状态判断。
• 页面按钮可按权限改善体验，但每个受限操作都以服务端授权结果为准。

测试与监测界面

• 正式测试状态只展示：待测试、检测中、暂停、检测完成。完成确认中、检测中（异常）和已终止不属于新流程状态，历史值仅作兼容展示。
• 设备状态和接收状态单独并列展示。接收状态使用：未开始接收、接收中、暂停接收、已结束接收；不要把设备、接收和测试三套状态合并到一个字段或筛选项。
• 开始、暂停、继续和停止测试的页面动作只改变系统数据请求，不表示控制 BTS 或采集器。确认文案必须明确不控制设备；暂停期间停止实时请求且不显示实时采集参数，已持久化历史仍可查询，停止后进入“检测完成”。
• 实时快照与成功接收数据在类型、接口和页面文案上分开；数据列表和图表使用当前有效数据。
• 第一版每个测试电池号必须选择一个已登记采集器，以及主温度、正电位和负电位通道；可选次要通道和动态测量项保持现有交互。S-01...S-N 仅属于演示合同。

API 与 SSE

• HTTP 请求复用 src/api/request.ts 的鉴权和错误处理；按业务域在 src/api 中维护带类型的接口，不在视图内散落 URL。
• SSE 使用 fetch 流式读取 text/event-stream 并携带 Authorization 请求头。JWT 不放入 URL，不使用原生 EventSource 绕开现有鉴权。
• SSE 重连后用服务端当前快照替换本地快照；成功接收数据和当前有效数据按测试查询接口读取。不要把 SSE 当作可靠消息队列或在浏览器累积所有采样点。
• battery-* 业务 API 时间按 Unix epoch 毫秒解析并以用户本地时区展示；平台接口可保持原有格式。单位换算只发生在展示或导入边界，并保留接口返回的原始单位。

交互与数据安全

• 运行中测试禁用导入。导入结果逐行展示校验信息，并明确分组成功与失败记录；导入和编辑统一生成数据修订，不能覆盖原始设备事实或数据。单条删除按物理删除规则生成数据修订，整体删除测试不生成日志或修订记录。
• 终态测试不提供重启入口。修订和单条删除以新操作提交并展示修订结果；当前有效数据使用修订后的值，删除前内容从修订记录追溯。
• SSE 断开、REST 失败和权限拒绝要有可见错误状态；不得乐观地把正式测试状态改为成功。
• 延续现有 Element Plus 布局与组件习惯，确保桌面和常用窄屏下按钮、状态文本和表格操作不重叠。

验证

• 修改 API 类型、状态映射或实时流时，检查加载、空数据、断线、重连、无权限和后端异常状态。
• 完成前运行 npm run build。若新增测试脚本，再同时运行受影响测试。
• 设备登记浏览器主接缝运行 npm run test:e2e:ticket04；该命令必须使用隔离端口和临时 MySQL/Redis，结束后不得遗留进程或容器。**注意：该编排原本还会启动开发模拟器（后端 dev-simulator profile 与 /dev/bts-simulator 页面），模拟器已按 Ticket04（2026-10-08）整体拆除**，tests/e2e/ 下依赖模拟器页面与端点的用例（含设备登记与采集器登记的旧流程）在按真实来源重写之前跑不通，见 docs/KNOWN-GAPS.md。
• 需要浏览器交互验证时启动 npm run dev，检查控制台和网络请求；完成后说明仍依赖模拟数据的页面。