# 后端开发规则

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

## 模块边界

- `ruoyi-device` 负责厂商无关设备接口、BTS 协议实现、模拟器契约和采集调度。协议 XML、TCP 帧、固定地址和厂商枚举停留在该模块内部。
- `ruoyi-system` 负责测试业务、状态聚合、事务、持久化和审计；它依赖设备抽象，不解析 BTS XML。
- `ruoyi-admin` 只负责应用装配及 REST/SSE 控制器，不承载采集或状态机业务。
- 第一阶段打包为一个后端进程，并明确保持单采集实例。适配器租约字段只为后续高可用预留。

## 设备路径

- 每个设备适配器实例从数据库读取名称、类型、主机、端口、启停、轮询周期、时区和能力，不在代码中固定连接参数。
- 每个实例只有一个串行请求队列；一次 `inquire` 批量查询需监测通道。状态查询默认每 5 秒，历史下载使用较低优先级。
- 连接拒绝、最长约 30 秒响应超时、断线和后端重启均进入对账与恢复流程。恢复时重新查询设备事实并从持久化游标补采，不推断设备已停止。
- 历史补采按测试结束时间和通道公平轮转，每批最多 1000 条；数据保存成功后才推进数据库游标。
- 解析器拒绝 DOCTYPE/外部实体，限制响应大小，并显式处理缺字段、非法数值和未知枚举。
- 协议报文压缩保存到文件系统，数据库仅保存索引、校验值和解析结果；普通报文保留 30 天，解析失败或冲突报文保留 180 天。

## 业务事务

- 开始监测在一个事务内锁定全部绑定通道；任一通道不可用则整体失败。数据库唯一约束必须阻止并发占用。
- 未观测运行前，负责人或管理员可以取消等待并释放通道；已观测运行后走异常处理或终止流程。
- 所有通道正常结束后先进入内部“完成确认中”；只有补采完成且没有未解释数据缺口，才聚合为“检测完成”。
- “检测完成”和“已终止”是不可恢复终态。异常恢复、数据缺口处置、终止和负责人转交都追加审计。
- 相同“测试 + 通道 + 异常类型”在未恢复期间聚合首次时间、最近时间和次数；恢复后关闭，再次发生创建新事件。

## 数据库迁移

- 开发数据库是 WSL 内 Docker 的 MySQL 8，通过 Windows 端口映射 `127.0.0.1:3307/battery_detection` 访问。连接配置保留可覆盖能力，部署环境通过参数提供凭据。
- 已应用的 `V1`、`V2`、`V3` 迁移是不可变基线。任何结构或种子变化新增下一个 `V<n>__description.sql`，不要改写已应用脚本或整库导出文件。
- 迁移必须可从空库顺序执行，并可在已迁移库重复启动。迁移不得导入演示设备、演示测试、采样数据或历史日志。
- 项目排除了默认 `DataSourceAutoConfiguration`；Flyway 在 `FlywayMigrationConfig` 中使用独立 JDBC 连接，并且 `dynamicDataSource` 必须等待迁移完成。
- 修改迁移前先只读检查目标库和 `flyway_schema_history`。清库、覆盖或修复迁移历史需要用户明确授权。

## API 与实时流

- 普通提交和历史区间查询使用 REST；实时快照、状态变化和异常使用 `SseEmitter`。
- SSE 只保留每测试每通道最新快照。状态变化和异常不可合并；发送失败关闭连接。重连先发当前快照，历史由 REST 查询。
- 权限由后端统一执行。创建人、负责人和管理员是独立字段和角色；不要依赖前端隐藏按钮实现授权。
- API 时间输出 ISO 8601 带时区，测量值同时返回明确单位。

## 验证

- 设备协议或调度改动至少覆盖正常多通道、拒绝连接、断线恢复、超时、畸形 XML、重复/乱序/缺失历史和重启补采中受影响的场景。
- 运行设备模块测试：`mvn -pl ruoyi-device test`。
- 跨模块改动运行全量测试：`mvn test`。
- 验证可执行包：`mvn -pl ruoyi-admin -am package -DskipTests`。启动验证时使用可写的 `LOG_PATH`，完成后停止临时进程。