# 前端开发规则

本文件适用于 `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`，检查控制台和网络请求；完成后说明仍依赖模拟数据的页面。