| | |
|---|
| | | |
|---|
| | | ## 模块边界 |
|---|
| | | |
|---|
| | | - `ruoyi-device` 负责厂商无关设备接口、BTS 协议实现、模拟器契约和采集调度。协议 XML、TCP 帧、固定地址和厂商枚举停留在该模块内部。 |
|---|
| | | - `ruoyi-system` 负责测试业务、状态聚合、事务、持久化和审计；它依赖设备抽象，不解析 BTS XML。 |
|---|
| | | - `battery-business` 负责测试业务、状态聚合、事务、持久化、修订和异常；它只依赖 `battery-device-api`，不解析 BTS XML 或依赖 Redis/模拟器。 |
|---|
| | | - `battery-device-api` 提供厂商无关观测模型；`battery-device-bts` 封装协议；直连厂商存储的实现放在 `battery-device-neware`，读本项目落地表的推式实现放在 `battery-business`（开发模拟器模块已按 Ticket04 整体拆除）。协议 XML、TCP 帧和厂商枚举停留在 BTS 模块内部。 |
|---|
| | | - `ruoyi-admin` 只负责应用装配及 REST/SSE 控制器，不承载采集或状态机业务。 |
|---|
| | | - 第一阶段打包为一个后端进程，并明确保持单采集实例。适配器租约字段只为后续高可用预留。 |
|---|
| | | - 第一阶段打包为一个后端进程，并明确保持单采集实例；最终业务基线不建立适配器租约模型。 |
|---|
| | | |
|---|
| | | ## 设备路径 |
|---|
| | | |
|---|
| | |
|---|
| | | - 每个实例只有一个串行请求队列；一次 `inquire` 批量查询需监测通道。状态查询默认每 5 秒。 |
|---|
| | | - 连接拒绝、响应超时、断线和后端重启只记录设备/请求异常并继续观测，不自动恢复或追回历史数据。 |
|---|
| | | - 解析器拒绝 DOCTYPE/外部实体，限制响应大小，并显式处理缺字段、非法数值和未知枚举。 |
|---|
| | | - 协议报文压缩保存到文件系统，数据库仅保存索引、校验值和解析结果；普通报文保留 30 天，解析失败或冲突报文保留 180 天。 |
|---|
| | | - 不持久化协议原始报文、报文索引或压缩文件；适配器只输出结构化观测，遵循 ADR-0045。 |
|---|
| | | |
|---|
| | | ## 业务事务 |
|---|
| | | |
|---|
| | | - 开始接收在一个事务内校验全部检测柜和采集器在线可观测及必填映射完整；任一条件失败则整体回滚。暂停接收停止该测试的数据请求，继续接收恢复请求，停止测试进入不可恢复终态并释放业务占用。 |
|---|
| | | - 检测柜通道允许运行中接入；同一次设备运行可依次服务多个测试，数据归属按测试级动作时间判断，不建立来源接收区间约束。 |
|---|
| | | - 开始接收在一个事务内校验设备登记、启用状态和必填映射完整，不把当前在线状态作为前置条件。暂停接收停止该测试的数据请求，继续接收恢复请求，停止测试进入检测完成并释放业务占用。 |
|---|
| | | - 检测柜通道允许运行中接入；同一次设备运行可依次服务多个测试，只有请求期间成功接收且可可靠归属的数据写入测试。 |
|---|
| | | - 停止测试或设备自然结束后直接进入“检测完成”；成功接收的数据追加保存，缺失、序号跳跃和采样间隔异常只作为可见事实。 |
|---|
| | | - “检测完成”和“已终止”是不可恢复终态。异常恢复、数据缺口处置、终止和负责人转交都追加审计。 |
|---|
| | | - 相同“测试 + 通道 + 异常类型”在未恢复期间聚合首次时间、最近时间和次数；恢复后关闭，再次发生创建新事件。 |
|---|
| | | - “检测完成”是新流程唯一不可恢复终态；异常处理和负责人转交追加领域记录或应用日志，不使用已废止的 `t_test_audit` 表。测试整体删除按 ADR-0047 不写日志或修订记录，数据缺失不进入系统恢复责任。 |
|---|
| | | - 相同“测试 + 字段 + 阈值规则”在人工关闭前聚合为一条开放测试预警异常；正常观测不自动关闭，关闭后再次超限创建新异常。 |
|---|
| | | |
|---|
| | | ## 数据库迁移 |
|---|
| | | |
|---|
| | | - 开发数据库是 WSL 内 Docker 的 MySQL 8，通过 Windows 端口映射 `127.0.0.1:3307/battery_detection` 访问。连接配置保留可覆盖能力，部署环境通过参数提供凭据。 |
|---|
| | | - 已应用的 `V1`、`V2`、`V3` 迁移是不可变基线。任何结构或种子变化新增下一个 `V<n>__description.sql`，不要改写已应用脚本或整库导出文件。 |
|---|
| | | - 开发数据库是 WSL 内 Docker 的 MySQL 8，通过 Windows 端口映射 `127.0.0.1:6134/battery_detection_refactor` 访问。连接配置保留可覆盖能力，部署环境通过参数提供凭据。 |
|---|
| | | - 旧库的 `V1`–`V<n>` 迁移和整库导出仅作不可变历史；架构重构使用新的最终业务基线初始化空库，不迁移当前测试数据。基线变更不得改写旧脚本。 |
|---|
| | | - 迁移必须可从空库顺序执行，并可在已迁移库重复启动。迁移不得导入演示设备、演示测试、采样数据或历史日志。 |
|---|
| | | - 项目排除了默认 `DataSourceAutoConfiguration`；Flyway 在 `FlywayMigrationConfig` 中使用独立 JDBC 连接，并且 `dynamicDataSource` 必须等待迁移完成。 |
|---|
| | | - 修改迁移前先只读检查目标库和 `flyway_schema_history`。清库、覆盖或修复迁移历史需要用户明确授权。 |
|---|
| | |
|---|
| | | - 普通提交和历史数据查询使用 REST；实时快照、状态变化和异常使用 `SseEmitter`。 |
|---|
| | | - SSE 只保留每测试每数据来源最新快照。设备状态、接收状态、测试状态和异常变化不可合并；发送失败关闭连接。重连先发当前事实，历史由 REST 查询。 |
|---|
| | | - 权限由后端统一执行。创建人、负责人和管理员是独立字段和角色；不要依赖前端隐藏按钮实现授权。 |
|---|
| | | - API 时间输出 ISO 8601 带时区，测量值同时返回明确单位。 |
|---|
| | | - `battery-*` 业务 DTO/VO 时间统一输出 Unix epoch 毫秒；RuoYi 平台接口可保持既有格式，测量值同时返回明确单位。 |
|---|
| | | |
|---|
| | | ## 验证 |
|---|
| | | |
|---|
| | | - 设备协议或调度改动至少覆盖正常多通道、拒绝连接、断线、超时、畸形 XML 和实时数据幂等冲突等受影响场景。 |
|---|
| | | - 运行设备模块测试：`mvn -pl ruoyi-device test`。 |
|---|
| | | - 跨模块改动运行全量测试：`mvn test`。 |
|---|
| | | - 运行受影响 `battery-*` 模块测试；跨模块契约变更运行全量测试 `mvn test`。 |
|---|
| | | - 验证可执行包：`mvn -pl ruoyi-admin -am package -DskipTests`。启动验证时使用可写的 `LOG_PATH`，完成后停止临时进程。 |
|---|
| | | - 浏览器主接缝由前端仓库 `npm run test:e2e:ticket04` 编排隔离 MySQL 8、Redis、完整可执行包和模拟器；不得连接共享开发库或复用已有服务端口。 |
|---|
| | | - 浏览器主接缝由前端仓库 `npm run test:e2e:ticket04` 编排隔离 MySQL 8、Redis、完整可执行包；不得连接共享开发库或复用已有服务端口。**该编排原本还会启动开发模拟器，模拟器已按 Ticket04 整体拆除**，`tests/e2e/` 下依赖模拟器页面与端点的用例在按真实来源重写之前跑不通（见 `docs/KNOWN-GAPS.md`）。 |
|---|
