Преглед изворни кода

按80/81图解重构线架保活/注册/换机状态机

- 已绑定地址带UID发0x80保活,仅匹配81判在线;连续2次无匹配81判离线并停0x03读卡
- 未绑定地址全0探测,收到81本地建立绑定①,自动流程废弃82/83(仅留手动调试接口)
- 重新上线/换机/新注册先经0x10重下绑定②再读卡,panel_mappings_synced保证每会话一次
- 同址不同UID:原机在线记冲突不替换,原机离线(连续2次无81)自动换架接管
- stored_devices新增conflict/conflict_uid/keepalive_miss状态;备份恢复接新状态
- 配置地址刷卡设置地址、pending优先探测;新增RS485方向脚软件控制
- 备份导出/导入完整包含port_mappings端口↔卡号映射,新增往返测试
- 前端PanelManage配置地址弹窗与API;文档按图解更新;共143测试通过
wenhongquan пре 2 недеља
родитељ
комит
e580f5659b

+ 96 - 45
AGENTS.md

@@ -18,24 +18,33 @@
   - `mosquitto.service` → 本地 MQTT Broker(:1883)
   - `nginx.service`、`mysql.service` 等
 
-## 第二块板:RK3562(192.168.31.167,Ubuntu)
+## 第二块板:RK3562(Ubuntu,当前 192.168.10.190)
 
 > 该板原为 Android 13,2026-09 已**重刷为 Ubuntu 20.04 原厂镜像**,sshd 自带可用,无需再自建 SSH。
 
 - **系统**:Ubuntu 20.04.3 LTS (Focal),内核 5.10.226 aarch64,`hostname=ido`。
-- **网络**:**wlan0** = `192.168.31.167/24`(WiFi,eth 口未启用),docker0 = `172.17.0.1`。
-- **登录**:`ssh root@192.168.31.167`,密码 `123456`,直接 root shell。
+- **网络**:**wlan0** DHCP,2026-10-27 为 `192.168.10.190/24`(曾用 `.167`/`.189`,eth 口未启用),docker0 = `172.17.0.1`。
+- **登录**:`ssh root@192.168.10.190`,密码 `123456`,直接 root shell。
 - **自带服务**:`mosquitto`(:1883)、`mysql`(:3306 仅本地)、`smbd`(:139/445)、`adbd`(:5555 网络 adb)。
 - **已部署 `dzxj_dtu`(2026-09)**:
   - 代码 `/root/dzxj_dtu/`(`backend` + `frontend/dist` + `venv`,venv 内 gpiod==1.5.4)。服务 `dzxj_dtu.service`(`/root/dzxj_dtu/venv/bin/python app.py`,WorkingDirectory `backend`,开机自启),Flask 监听 `0.0.0.0:5001`。
   - nginx 80:站点 `/etc/nginx/sites-available/dzxj_dtu.conf`(`root /var/www/html`,代理 `/api`、`/socket.io` → `:5001`);前端**同时**放了 `frontend/dist` 和 `/var/www/html`(别忘两处都更)。
+  - **2026-10-27 部署 V5 版本**:`backend/app.py`、`config.py`、`modules/modbus_rtu.py`、`modules/config_backup.py` + `frontend/dist`(同步 `/var/www/html`);部署前备份在 `/root/dzxj_dtu_deploy_backup_20261027_112650`。验证:服务 active、`/dev/ttyS8` 串口已连、`/api/panel/config_address_status` 正常、nginx 返回新 bundle(`index-7c00abba.js`)。
   - 环境变量 `/etc/default/dzxj_dtu`:本板 **DHT11 已接在 gpiochip0 line19**(GPIO0_C3_d,同 149),`DHT11_ENABLED=true`,5s 轮询;C 读取器 `backend/scripts/dht11_reader` 已编译,实测 27°C/14% 正常(偶发校验失败属正常抖动)。
-  - 串口:`serial_config.json` 指向 `/dev/ttyS8 @9600`(本板 RS485,实测在发广播轮询);串口屏端口见下方「串口屏(Nextion)接线与刷新」。
+  - 串口:`serial_config.json` 指向 `/dev/ttyS8 @9600`(本板 RS485,实测在发 0x80 地址查询轮询);串口屏端口见下方「串口屏(Nextion)接线与刷新」。
   - MQTT:`mqtt_config.json` 仍是占位(`localhost:1883`),需在网页里配 `xt.wenhq.top:8581` 之类并连接,连上后才会持久化自动重连。
 
+## 第三块板:RK 板(当前 192.168.199.174,严格 80/81 现网验证板)
+
+- **登录**:`ssh root@192.168.199.174`,密码 `123456`,`hostname=ido`。
+- **部署**:代码 `/root/dzxj_dtu/`(venv:`/root/dzxj_dtu/venv/bin/python`),服务 `dzxj_dtu.service`,串口 **`/dev/ttyUSB0 @9600`(CH340 USB-RS485)**。改代码备份命名 `app.py.bak_YYYYMMDD_HHMMSS`。
+- **2026-10-29 18:49 部署严格图解版**:`backend/app.py` + `config.py`(80/81 口径、`PANEL_KEEPALIVE_MISS_LIMIT=2`、废弃自动 82/83、每次重新上线先 0x10 再读卡、冲突防抢占);备份 `app.py.bak_20261029_184845`(前一版 `app.py.bak_20261029_184636`)。
+- **当前绑定**:`devices.json = {"510012001100004c30313356": 1}`(地址 1)。
+- **现网固件已知行为**:该线架**只回全 0 探测的 81,不回带绑定 UID 点名帧的 81**,但 0x03 读卡正常(物理卡 `ddad57f95001` 曾在端口 10/16 附近读到)。严格口径下它在服务启动约 2 个扫描周期后被判 **offline 并停读卡**(已实测:日志 1/2→2/2→离线,之后静默只发 80;`/api/modbus/stored_devices` 返回 `status=offline`)。**恢复在线的前提是升级线架固件**使其回应带 UID 的 0x80;临时回滚旧版(读卡判在线)用对应 `.bak` 文件还原后 restart。
+
 ### 串口屏(Nextion)接线与刷新(2026-10-10 重点)
 
-- **当前网络**:本板 wlan0 为 DHCP,现为 `192.168.10.189`(eth 口未启用)。
+- **当前网络**:本板 wlan0 为 DHCP,现为 `192.168.10.190`(eth 口未启用)。
 - **HMI 默认文字 ≠ 实际 IP**:屏工程默认 `t1.txt="192.168.100.123"`、`t2.txt="终端 0"`、`t4.txt="V2.0"`、`g0.txt="MQTT:OK,在线终端:10"`、`t3.txt="备注:"`。**屏上一直显示 192.168.100.123 就说明 App 从未成功写过屏**,不是 App 算错 IP。
 - **屏供电必须 5V**(VCC 接 5V,GND 与板子共地),3.3V 供电会导致屏显示正常但串口不工作。
 - **接线方案(实测)**:
@@ -182,41 +191,75 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 ## 串口 / RS485
 
 - 设备串口:`/dev/ttyS8 @ 9600`,连接配置持久化在 `/root/dzxj_dtu/backend/serial_config.json`。
+- **2026-10-29 现网状态:app 跑在 `/dev/ttyUSB0`(CH340 USB-RS485)**,因为板载 `ttyS8` 的 485 收发器实测「能发不能收」——DTU 发查询后 `tx` 涨、`rx` 一动不动,同一帧用 USB-485 从总线发就一切正常。详见下方「RS485 方向脚软件控制」。
 - 服务启动时 `auto_connect_serial()` 自动重连。
 - MODBUS-RTU 协议实现在 `backend/modules/modbus_rtu.py`;串口封装在 `backend/modules/serial_port.py`。
 - 注意:硬件通信固定 6 字节(12位) 卡号,MQTT 边界拼成 8 字节(16位) `jumper_uid`(前 4 位 DTU 号 + 后 12 位卡号),适配逻辑在 `app.py` 的 `_to_mqtt_jumper_uid` / `_from_mqtt_jumper_uid`。
 
-### V4 协议(20260813)重点
+### RS485 方向脚软件控制(2026-10-29 新增,可选)
+
+板载 TTL 转 RS485 模块若是**自动方向**且切换太慢,会出现典型症状:**DTU 发帧正常(总线上能抓到),但从机(线架)的回包一个字节都收不到**(`/proc/tty/driver/serial` 里 `tx` 涨、`rx` 不动),而同一帧用 PC 的 USB-RS485 发出去从机就正常回复。
 
-协议文档:`DTU和节点之间协议  V4(1).docx`。寄存器地址:
+- 实现:`serial_port.py` 的 `Rs485Direction` 类,把所有写路径统一收口到 `_rs485_write()`:配置了方向 GPIO 时,发送前拉 TX 电平 → `ser.write()+flush()`(tcdrain 等最后一位发完)→ 立刻切回 RX 电平。
+- 配置(环境变量,`/etc/default/dzxj_dtu`):
+  - `SERIAL_RS485_DIR_GPIO=gpiochip0:25`(格式 `chip:line`;低电平为发送态则写 `gpiochip0:25:low`)
+  - `SERIAL_RS485_DIR_PRE_DELAY=0.001`(切到发送态后等待秒数)
+  - `SERIAL_RS485_DIR_POST_DELAY=0.001`(发完等待秒数再切回接收)
+- 未配置该变量时行为与原来完全一致(不控制方向);gpiod 缺失/申请失败会自动降级,不影响串口主流程。
+- 前提:485 模块必须有可接出的 **DE/RE 脚**;纯自动流向模块(无 DE 脚)无法软件修复,只能换模块或用 USB-RS485。
+- 注意:RK3562 EVB3562 的 `ttyS8` **只复用了 TX/RX 两个脚**(`uart8m0-xfer`),RTS 没有引出来,设备树也没有 rs485 属性,所以**不能靠内核 RS485/RTS 模式**解决。
+
+### V5 协议(2026-10-23)重点
+
+协议文档:`DTU和节点之间协议  V5.docx`。寄存器地址:
 
 | 地址  | 内容         | 说明                                   |
 | ----- | ------------ | -------------------------------------- |
 | 0x0000| 网络通断     | **保留不用**(已去除)                 |
 | 0x0001| 24 个 RGB 灯 | **保留不用**(灯由配线架自己控制)     |
-| 0x0002| 批量卡号读   | 0x03 读 72 寄存器 = 144 字节,24 路×6 字节(**2026-10 起帧内携带线架 UID**,见下) |
+| 0x0002| 批量卡号读   | 标准 0x03 读 72 寄存器 = 144 字节,24 路×6 字节 |
 | 0x0003| 设置卡号     | 0x10 写 144 字节,24 路×6 字节         |
 
-**带 UID 批量读卡帧(2026-10-13 新增,注册模型基础,需线架固件同步支持!)**:
+**地址保活 / 协商(80 ↔ 81,82/83 已废弃,2026-10-29 按图解重写)**:
+
+> 权威口径见仓库外图解 `/Users/wenhongquan/Downloads/DTU与配线架通信协议图解.html`(80/81 口径)。
+> **仅保留 80 请求 ↔ 81 应答一对帧**,不发 82、83。
 
-- 请求 20B:`[addr][0x03][0x00][0x02][0x00][0x48][12字节线架UID][CRC_L][CRC_H]`
-  - UID = 该地址已绑定的线架 UID;未绑定时为 12 字节全 0(探测)
-- 响应 161B:`[addr][0x03][0x90][144字节卡数据][12字节线架UID][CRC_L][CRC_H]`
-  - UID = 线架自身 UID(探测响应时用于绑定"地址↔UID")
-- 未配置(新)线架收到 uid=0 探测帧后会**采纳该地址**并应答自身 UID(不再依赖 00 40/00 42 广播分配流程)
-- 实现:`modbus_rtu.py` 的 `build_read_cards_request(addr, uid)` 与 `read_all_antenna_cards(addr, uid=None)`;常量 `READ_WITH_UID_RESPONSE_LEN=161`
-- 兼容:旧固件 149B 响应仍可解析(`panel_uid=None`),但**不能用于绑定/换架接管**,仅是过渡期诊断
-- 旧广播流程(`00 40` 发现 / `00 42` 分配)仅在手动调试接口 `/api/modbus/broadcast_query`、`/api/modbus/auto_configure` 保留,自动流程已不使用
+- 保活请求 16B:`[addr][0x80][12字节 UID 域][CRC_L][CRC_H]`
+  - UID 域 = 绑定①(addr↔UID)的值;已绑定地址**始终带绑定 UID**,未绑定地址填 **12 字节全 0**(探测)
+- 应答 16B:`[addr][0x81][12字节线架自身 UID][CRC_L][CRC_H]`
+  - **0x81 最高位为 1,不是 MODBUS 异常帧**(解析时不能按 `fc & 0x80` 判异常)
+  - 收到 81 后本地用返回 UID 对照绑定①核对身份,**匹配即建立在线,不发确认帧**
+- **82/83 已废弃**:纸面 V5 文档里的 `[addr][0x82][UID][CRC]` / `[addr][0x83][UID][CRC]` 现场固件不用;自动注册/接管流程不再调用,仅保留 `confirm_address()` 与两个手动调试 HTTP 接口
+- 文档样例(CRC 已核对):`01 80`+12×00 → `54 01`;81 样例 `01 81 51 00 12 00 11 00 00 4C 30 31 33 56 D0 D3`
+- 实现:`modbus_rtu.py` 的 `build_address_query_request` / `parse_address_query_response`;客户端 `query_address(addr, uid=None)`。`confirm_address()`/`build_address_confirm_request` 仅留作手动调试
+
+**批量读卡恢复标准 MODBUS 0x03(帧内不再带 UID)**:
+
+- 请求 8B:`[addr][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H]`(文档样例 `01 03 00 02 00 48 E4 3C`)
+- 响应 149B:`[addr][0x03][0x90][144字节卡数据][CRC_L][CRC_H]`
+- 过渡期兼容旧 V4 的 161B 响应(帧尾多 12B UID,解析时忽略,不参与绑定)
+- 实现:`build_read_cards_request(addr)` 与 `read_all_antenna_cards(addr)`;常量 `LEGACY_UID_RESPONSE_LEN=161`
+
+**配置地址状态(刷配置卡设置线架地址,V5 新增)**:
+
+- DTU 广播进入配置地址状态:`aa b7 00 07 80 00 00 ff 00 00 02 64 03`(`CONFIG_ADDRESS_ENTER_FRAME`,硬编码)
+- 线架读到配置卡后应答 8B:`55 00 00 02 ANTLIST ADDR XOR 03`
+  - `ANTLIST` = 读到配置卡的天线号,`ADDR` = 线架采纳的新地址,`XOR` = `55^00^00^02^ANTLIST^ADDR^03`
+  - 解析时在接收缓冲里扫描有效 8 字节帧(`parse_config_address_response`),容忍前面的杂散字节
+- DTU 收到应答后把新地址记为 `pending_address`,恢复轮询后优先探测该地址并自动注册/换架接管
 
 **设置卡号协议(非标准 MODBUS 0x10,重点!)**:
 
-- 帧格式:`[addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]`
-- **无 byte count 字段**(与标准 MODBUS 0x10 不同),数量字段 `0x0090=144` 直接表示字节数
-- 24 路卡号同时发送,每路 6 字节;无卡标记 = `FF FF FF FF FF FF`
+- **实物帧格式(现网按此实现,已验证 ACK 正常)**:`[addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]`
+  - **无 byte count 字段**(与标准 MODBUS 0x10 不同),数量字段 `0x0090=144` 直接表示字节数,整帧 152B
+  - ⚠️ 图解里 0x10 帧图在数量后多画了一个 `90`(byte count),但**现网固件按无 byte count 的 152B 帧应答正常**(ACK `01 10 00 03 00 90 30 65`)。**不要**改成带 byte count,否则写卡会失败。
+- 24 路卡号同时发送,每路 6 字节;无卡/未用端口 = `FF FF FF FF FF FF`(全 FF 占位,不参与读回比对)
 - 响应帧:`[addr][0x10][0x00][0x03][0x00][0x90][CRC_L][CRC_H]`(标准 0x10 响应,8 字节)
 - 实现:`modbus_rtu.py` 的 `ModbusRTUClient.set_card_mapping(device_address, card_mappings)`
 - HTTP API:`POST /api/modbus/set_card_mapping`(支持完整 24 路或单端口模式)
 - MQTT 命令:`SYNC_PORT_MAPPING` / `SYNC_ALL_MAPPING` 更新本地期望后**自动下发硬件**
+- **下发时机(图解)**:新注册 / 换架接管 / 掉线重新上线 / DTU 重启后首次上线,都要**先经 0x10 重下绑定②,再恢复 0x03 读卡**;由 `_sync_card_mappings_once()` + `panel_mappings_synced` 保证每次在线会话只重下一次
 
 **同步卡号流程**:
 
@@ -231,41 +274,47 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 - 原「LED 调试」页面已改为**「卡号设置测试」**页面(路由 `/led-debug`,组件 `LedDebug.vue`)
 - 页面功能:选终端 + 选端口 + 输入 12 位 hex 卡号 + 设置/清除 + 读卡验证
 
-## 线架注册模型(2026-10-13 重构,重点)
+## 线架注册模型(V5,2026-10-23 重构,重点)
+
+**模型(80/81 口径,2026-10-29 按图解重写)**:DTU 按配置的**地址段**定时顺序轮询(默认 1-50,存 `dtu_config.json` 的 `address_range`)。两级绑定都存在 DTU 侧:**绑定①** addr↔UID(`devices.json`,结构 `{uid: addr}`);**绑定②** 该地址下 端口↔卡号(`dtu_config.json` 的 `port_mappings`,未用端口全 FF)。**线架地址必须现场刷配置卡设置**(管理页「配置地址」),DTU 不自动分配地址。
 
-**模型**:DTU 按配置的**地址段**顺序轮询(默认 1-50,DTU 配置页可改,存 `dtu_config.json` 的 `address_range`),读卡帧带线架 UID;未绑定地址用 uid=0 探测,设备响应后绑定"地址↔UID"(绑定表仍是 `devices.json`,结构 `{uid: addr}` 不变)。
+**扫描状态机**(`app.py` 的 `_sweep_panel_addresses()`,一轮按地址升序,已绑定/未绑定同一轮顺序发,1→N):
 
-**扫描状态机**(`app.py` 的 `_sweep_panel_addresses()`,一轮按地址升序):
+1. **已绑定地址(链路1 保活 → 链路2 读卡)**:发「地址+绑定 UID」的 0x80(**始终带 UID,绝不发全 0**):
+   - 收到 **匹配 81**(UID=绑定①)→ 在线,清保活失败计数。若为**重新上线/本会话还没下发过**(服务重启、掉线恢复、刚接管),**先经 0x10 重下绑定②,再发 0x03 读卡**;稳态在线则直接读卡。
+   - **连续 `PANEL_KEEPALIVE_MISS_LIMIT`(=2)次收不到匹配 81 → 判离线,立即停止该机 0x03 读卡**(地址灯/端口灯蓝闪由线架自控);离线后仍每轮发带 UID 的 80 等恢复,重新收到匹配 81 才按上一条「先 0x10 再读卡」恢复。
+   - 第 1 次保活缺失(计数=1,尚未离线)本轮仍读卡一次;读卡失败本身**不改变在线状态**(在线完全由 80/81 决定),只告警。
+   - 收到的 81 **UID 与绑定①不同**:见下方「冲突 / 换架接管」。
+2. **未绑定地址**:每轮对地址段内**全部**未绑定地址发 12 字节全 0 的 0x80 探测(不因别的线架离线而暂停)→ 收到 81(自身 UID)即**本地建立绑定①并上线,不发 82/83**,随后先 0x10 下绑定②再读卡(`_register_new_panel`)。
+3. **待探测地址**(`_panel_config_addr_state.pending_address`):配置地址成功后优先探测,命中则 `_register_new_panel(..., allow_move=True)`(允许 UID 从旧地址迁移绑定与映射)。
 
-1. **已绑定且正常**:带绑定 UID 读卡(兼作线架保活)→ 成功走既有端口事件/告警逻辑;失败累计 miss
-2. **已绑定且失败过**(miss≥1,含离线/缺失):改用 **uid=0 探测**该地址 →
-   - 回的 UID 相同 → 原线架恢复在线
-   - 回的 UID 不同 → **换架自动接管**(见下)
-   - 无响应 → 继续缺失;连续失败 ≥3(`PANEL_MISS_THRESHOLD`)标记离线并发布离线状态
-3. **未绑定地址**:每轮轮转抽查 5 个(`DEFAULT_UNBOUND_PROBE_BATCH`,游标 `_unbound_probe_cursor`)→ 有响应则注册绑定;**若任一面板处于缺失/接管状态,本轮暂停未绑定探测**(防止新线架抢占非目标地址;旧线架拆走后要清幽灵绑定请用管理页删除)
+**冲突 / 换架接管(图解第七、八节)**:
 
-**换架自动接管**(`_takeover_panel()`)——更换单台线架无需重新匹配数据:
+- **情形一 · 原机仍在线 → 真冲突,不替换**:同地址收到不同 UID 的 81,但原绑定 UID 还没连续 2 次无匹配 81(仍在线)→ **不更新绑定①、不下发绑定②、不读卡**,记 `panel_conflict[pid]=新UID` 并告警;原机本轮无匹配 81 照常累计。
+- **情形二 · 原机离线 → 自动换架接管**(`_takeover_panel()`):原绑定 UID 已连续 2 次无匹配 81(离线)后,同地址的新 UID 持续回 81 → 更新绑定①为 addr↔新UID、**panel_id 不变**(继承绑定② `port_mappings` 全部期望)、清冲突;**先经 0x10 把绑定②下发新机,再读卡**(端口状态静默对齐,不误报事件);自定义 `panel_id_mapping` 自动补新 UID→原 panel_id;不发 82/83。
+- 替换后若老机又上线(81 UID 与当前绑定不符):新机在线按冲突告警、不静默回切。
 
-- 新线架装到原地址后,DTU 探测到新 UID → 重绑地址↔新UID、**panel_id 不变**(继承 `port_mappings` 全部期望数据)
-- 自动把期望卡号 **下发到新线架硬件**(`set_card_mapping`),端口状态静默对齐(不误报事件)
-- 更新 `panel_config.panel_uid`,上报注册+面板状态(payload 含 `panel_uid`)
-- 自定义 `panel_id_mapping`(按 UID 映射)会自动补新 UID → 原 panel_id 的映射
+**关键内存状态**:`panel_keepalive_miss {pid:int}`(连续无匹配 81 次数)、`panel_mappings_synced set()`(本在线会话已重下绑定②的面板,离线/解绑/接管时清除)、`panel_conflict {pid:new_uid}`。
 
 **管理页面/API**:
 
-- 新页面「线架管理」`/panel-manage`(`PanelManage.vue`):已注册线架表格(地址/UID/状态/最后响应/端口)+ 删除绑定 + 「扫描新线架」
-- `GET /api/modbus/stored_devices`:返回 `panels[]`(含 panel_id/status=online|missing|offline/last_seen/端口统计)+ `address_range` + `scan` 状态
+- 页面「线架管理」`/panel-manage`(`PanelManage.vue`):已注册线架表格(地址/UID/状态/最后响应/端口)+ 删除绑定 + 「扫描新线架」+「配置地址」
+- 「配置地址」弹窗:步骤引导(发指令 → 刷配置卡 → 自动注册)+ 状态轮询(`config.running/antenna/address/error/raw`)
+- `GET /api/modbus/stored_devices`:返回 `panels[]`(含 panel_id/status=online|missing|offline|**conflict**/conflict_uid/keepalive_miss/last_seen/端口统计)+ `address_range` + `scan` 状态
 - `POST /api/panel/unbind {address|panel_id}`:解除绑定(**仅解除**;线架仍在总线上时下轮扫描会重新绑定)
 - `POST /api/panel/scan` / `GET /api/panel/scan_status`:手动全量扫描地址段内未绑定地址
-- 「实时状态」页「发现终端」按钮已改为调用新扫描接口
-- 已删除自动广播发现(`auto_discover_loop` / `run_discovery_sync` / `check_assigned_devices_online`);`confirm_loop`(0x44 保活,10s)**保留**(线架开机 30s 窗口需要)
+- `POST /api/panel/config_address {timeout?}` / `GET /api/panel/config_address_status`:进入配置地址状态 / 查询进度(成功返回 antenna/address)
+- `POST /api/modbus/query_address {address, uid?}`:手工 0x80 查询调试;`POST /api/modbus/confirm_address`(**0x82,已废弃,仅手工调试**,自动流程不调用)
+- 「实时状态」页「发现终端」按钮调用扫描接口
+- 已移除 V4 自动广播发现(`auto_discover_loop` / `run_discovery_sync` / `check_assigned_devices_online`)、`confirm_loop`(0x44 保活)以及 `/api/modbus/broadcast_query`、`/api/modbus/auto_configure` 接口
 
 **注意事项**:
 
-- ⚠️ **多台全新线架同时上电可能总线冲突**(都抢第一个探测地址);首次部署建议逐台上电,或等固件加随机退避
-- ⚠️ 需线架固件支持"uid=0 探测自采纳地址 + 161B 响应";旧固件只能过渡诊断(149B 响应)
+- ⚠️ **新线架地址必须刷配置卡设置**(管理页「配置地址」),DTU 不会再自动分配地址
+- ⚠️ 配置地址**一次只能配一台**:操作期间持有 `address_config.config_lock`,地址段轮询暂停,超时默认 60s(`PANEL_CONFIG_ADDRESS_TIMEOUT`,可传 `timeout` 5~300s)
+- ⚠️ 需线架固件支持:0x80/0x81 保活(**含对「带绑定 UID 的 0x80」回应匹配 81**)+ 配置地址广播应答(`55 ... 03`)。**严格图解口径下,固件若不回带 UID 的 81,会在 2 轮后被判离线并停读卡**(2026-10-29 用户确认按图解严格实现;此前那批只回全 0 探测、不回带 UID 81 的固件需升级固件才能在线)
 - 绑定之外的地址(超地址段)如有绑定仍会轮询,但不再探测新地址
-- 相关常量:`config.py` 的 `DEFAULT_ADDRESS_RANGE` / `DEFAULT_UNBOUND_PROBE_BATCH` / `PANEL_MISS_THRESHOLD` / `PANEL_PROBE_TIMEOUT`
+- 相关常量:`config.py` 的 `DEFAULT_ADDRESS_RANGE` / `PANEL_KEEPALIVE_MISS_LIMIT`(=2) / `PANEL_PROBE_TIMEOUT` / `PANEL_QUERY_TIMEOUT` / `PANEL_READ_TIMEOUT` / `PANEL_CONFIG_ADDRESS_TIMEOUT`
 
 ## 运行数据备份 / 恢复(2026-10-13)
 
@@ -310,9 +359,11 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 | 温湿度读到 0.0 或报 gpiod 错 | 确认`dht11_reader` 二进制存在且可执行;`dht11_reader gpiochip0 19` 手测                                                         |
 | easytier 组网后虚拟 IP 不通  | `--no-tun` 模式限制,虚拟 IP 不进路由表,只能走 port-forward                                                                      |
 | MQTT 重启后没自动连          | 确认`/root/dzxj_dtu/backend/mqtt_config.json` 存在;存在则看 `auto_connect_mqtt` 日志                                           |
-| 新线架扫描不到               | 检查「DTU 配置」地址段是否覆盖其地址、串口是否连接;若「线架管理」中有"缺失待接管"的线架,未绑定探测会被暂停(删除其绑定或等接管完成) |
-| 换架后未自动接管             | 看日志是否"收到旧格式(149B)响应"——线架固件需支持带 UID 读卡帧(161B 响应);再查地址段是否包含该地址                                |
+| 新线架扫描不到               | 检查「DTU 配置」地址段是否覆盖其地址、串口是否连接;新线架需先用「线架管理 → 配置地址」刷配置卡设置地址。未绑定地址现在每轮全段顺序探测(全 0),不会因别的线架缺失而暂停 |
+| 换架后未自动接管             | 严格图解口径:必须**原机先连续 2 次无匹配 81 判离线**,同地址新 UID 持续回 81 才会接管(`_takeover_panel`,先 0x10 再读卡)。看日志是否有冲突告警→「判定离线并停止读卡」→「按离线替换接管」;原机仍在线时只记冲突不替换。另查地址段是否包含该地址、固件是否回带 UID 的 81 |
+| 配置地址一直等待/超时        | 确认线架已上电、配置卡放在目标天线、串口在线;默认 60s 超时,可重试;成功后看日志"线架配置地址完成: 天线=x 地址=y"                                   |
 | 配置被改坏/丢失              | 「数据备份」页从自动快照恢复(`backend/backups/`,每类保留 20 份)                                                                  |
+| 线架上线 2 轮后变离线/不读卡 | 严格图解口径下,已绑定地址**以带 UID 的 0x80 是否收到匹配 81 为在线唯一判据**:现网这批固件只回全 0 探测、**不回带 UID 的 81**,会在连续 2 轮后被判离线并停止 0x03 读卡(即使卡读得到)。需升级线架固件使其回应「带绑定 UID 的 0x80」点名帧。物理层排查:若 81/0x03 回包都收不到(`/api/data/serial` 无 `01 03 90...`),看 `grep -E "^\s*8:" /proc/tty/driver/serial`:发查询时 `tx` 涨 `rx` 不动 = 板载 485 收不到回包 → 配 `SERIAL_RS485_DIR_GPIO` 或改用 `/dev/ttyUSB0`(USB-RS485 已验证可通) |
 
 ## 注意事项(重要)
 
@@ -322,7 +373,7 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 - 设备的 root 密码是 `123456`(本机/测试环境)。
 - 改 `app.py` 后必须重启 `dzxj_dtu` 才生效。
 - Web 管理页面端口 `5001`(Flask),前端由 nginx 提供 80 端口。
-- **线架注册/换架依赖固件**:需支持"uid=0 探测自采纳地址 + 161B 响应",旧固件只能过渡诊断。
-- **多台全新线架不要同时上电**(可能总线冲突抢地址),首次部署逐台上电。
+- **线架注册依赖固件**:需支持 V5 的 0x80/0x81 地址查询与配置地址广播应答;仅支持 V4 的旧固件无法注册。
+- **新线架地址不再自动分配**:必须用「线架管理 → 配置地址」刷配置卡设置,一次只配一台。
 - **换机流程**:旧机导出备份 → 新机导入恢复(含环境变量时重启服务),详见「运行数据备份 / 恢复」。
 - **删除绑定 ≠ 注销线架**:线架仍在总线上会被重新绑定;要停用某台请同时断电/拆线。

BIN
DTU和节点之间协议 V5.docx


Разлика између датотеке није приказан због своје велике величине
+ 515 - 274
backend/app.py


+ 18 - 7
backend/config.py

@@ -15,9 +15,17 @@ SERIAL_READ_BUFFER_SIZE = 4096  # 串口读取缓冲区大小(字节)
 
 # 串口配置
 DEFAULT_BAUDRATE = 9600  # 默认波特率
-DEFAULT_SERIAL_TIMEOUT = 1  # 默认串口超时时间(秒)
+DEFAULT_SERIAL_TIMEOUT = 0.1  # 默认串口读超时时间(秒),轮询总线用短超时
+# 配线架总线串口:板载 TTL(UART) 转 RS485 模块,默认 /dev/ttyS8
+DEFAULT_SERIAL_PORT = os.getenv('DEFAULT_SERIAL_PORT') or '/dev/ttyS8'
 SERIAL_RECONNECT_INTERVAL = 5  # 串口重连间隔(秒)
 SERIAL_RECONNECT_MAX_RETRIES = 5  # 串口最大重连次数
+# RS485 方向控制 GPIO(可选)。格式 "gpiochip0:25" 或 "gpiochip0:25:low"(low = 低电平为发送态)。
+# 用于板载 TTL 转 RS485 模块自动方向切换不可靠(发完立刻收不到回包)的场景,
+# 把模块的 DE/RE 接到该 GPIO,由软件在发送前拉 TX、发送完成后切回 RX。
+SERIAL_RS485_DIR_GPIO = (os.getenv('SERIAL_RS485_DIR_GPIO') or '').strip()
+SERIAL_RS485_DIR_PRE_DELAY = float(os.getenv('SERIAL_RS485_DIR_PRE_DELAY', '0.001'))  # 切到发送态后等待(秒)
+SERIAL_RS485_DIR_POST_DELAY = float(os.getenv('SERIAL_RS485_DIR_POST_DELAY', '0.001'))  # 发送完成后等待再切回接收(秒)
 
 # MQTT配置
 DEFAULT_MQTT_PORT = 1883  # 默认MQTT端口
@@ -119,11 +127,13 @@ DTU_BROADCAST_TOPIC = 'broadcast'
 MAX_PANELS = 8  # 最大面板数
 MAX_PORTS_PER_PANEL = 24  # 每个面板最大端口数
 
-# 线架地址段轮询 / UID 绑定(注册模型)
+# 线架地址段轮询 / UID 绑定(80/81 口径,仅 80 请求/81 应答,82/83 已废弃)
 DEFAULT_ADDRESS_RANGE = {'start': 1, 'end': 50}  # 默认轮询地址段
-DEFAULT_UNBOUND_PROBE_BATCH = 5                  # 每轮抽查的未绑定地址数量(轮转)
-PANEL_MISS_THRESHOLD = 3                         # 连续失败达阈值后改用 uid=0 探测(换架接管/原架恢复)
-PANEL_PROBE_TIMEOUT = 0.3                        # uid=0 探测超时(秒)
+PANEL_KEEPALIVE_MISS_LIMIT = 2                    # 连续 2 次收不到匹配 81 即判离线,并停止该机 0x03 读卡
+PANEL_PROBE_TIMEOUT = 0.3                         # 未绑定地址全 0 探测超时(秒)
+PANEL_QUERY_TIMEOUT = 0.5                         # 已绑定地址带 UID 的 0x80 保活查询超时(秒)
+PANEL_READ_TIMEOUT = 1.0                          # 批量读卡 0x03 超时(秒,仅在线机执行)
+PANEL_CONFIG_ADDRESS_TIMEOUT = 60                 # 配置地址状态等待刷配置卡的超时(秒),超时后自动退出
 
 # DHT11 环境传感器配置(本地 GPIO 读取)
 DHT11_ENABLED = os.getenv('DHT11_ENABLED', 'true').lower() in ('1', 'true', 'yes')
@@ -133,9 +143,10 @@ DHT11_POLL_INTERVAL = int(os.getenv('DHT11_POLL_INTERVAL', '5'))
 DHT11_SIMULATE = os.getenv('DHT11_SIMULATE', 'false').lower() in ('1', 'true', 'yes')
 DHT11_MAX_HISTORY = 1000  # 保留最近 1000 条历史记录
 
-# Nextion 串口屏配置(接 /dev/ttyS9)
+# Nextion 串口屏配置(默认接 /dev/ttyS9)
 NEXTION_ENABLED = os.getenv('NEXTION_ENABLED', 'true').lower() in ('1', 'true', 'yes')
-NEXTION_SCREEN_PORT = os.getenv('NEXTION_SCREEN_PORT', '/dev/ttyS9')
+DEFAULT_NEXTION_SCREEN_PORT = '/dev/ttyS9'  # 串口屏默认端口
+NEXTION_SCREEN_PORT = os.getenv('NEXTION_SCREEN_PORT') or DEFAULT_NEXTION_SCREEN_PORT
 NEXTION_SCREEN_BAUD = int(os.getenv('NEXTION_SCREEN_BAUD', '9600'))
 NEXTION_PANEL_NAME_PREFIX = os.getenv('NEXTION_PANEL_NAME_PREFIX', '终端')
 NEXTION_CMD_DELAY_MS = int(os.getenv('NEXTION_CMD_DELAY_MS', '25'))

+ 302 - 329
backend/modules/modbus_rtu.py

@@ -1,133 +1,244 @@
+"""MODBUS-RTU 协议实现(线架/配线架 V5 协议,20261023)。
+
+V5 关键变化(相对 V4):
+  1. 取消"广播发现 + 自动分配地址"(00 40 / 00 41 / 00 42 / 00 43) 流程;
+     地址改由现场用"配置卡"写入线架(DTU 可让线架进入配置地址状态)。
+  2. DTU 定时按固定地址查询线架:
+       0x80 查询: [add][0x80][12 字节 UID][CRC_L][CRC_H]
+         - 已绑定地址 -> 携带绑定的 UID
+         - 未绑定地址 -> UID 为 12 字节全 0(探测)
+       0x81 应答: [add][0x81][12 字节 UID][CRC_L][CRC_H](线架自身 UID)
+       0x82 确认: [add][0x82][12 字节 UID][CRC_L][CRC_H](DTU 确认绑定)
+       0x83 应答: [add][0x83][12 字节 UID][CRC_L][CRC_H]
+  3. 读卡 0x03 回归标准 MODBUS(不再在帧内携带 UID):
+       请求 8B:  [add][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H]
+       响应 149B:[add][0x03][0x90][144 数据字节][CRC_L][CRC_H]
+     每张卡 6 字节(硬件卡号,12 位十六进制);无卡标记 = FF FF FF FF FF FF
+  4. 支持让线架进入"配置地址状态"(读配置卡设置地址):
+       发送: AA B7 00 07 80 00 00 FF 00 00 02 64 03
+       应答: 55 00 00 02 [ANTLIST] [ADDR] [XOR] 03
+         ANTLIST = 读到配置卡的天线号(1~24),ADDR = 配置的地址
+         XOR = 0x55 起到 ADDR 的异或和
+
+注: 硬件通信固定 6 字节卡号;对 MQTT 的 8 字节(16 位) jumper_uid 适配在 app.py
+    边界完成(前 4 位 DTU 号 + 后 12 位卡号)。
+"""
 from typing import Optional
 import threading
+import struct
+import logging
 
+logger = logging.getLogger('serial_mqtt_gateway')
 
-# ========== 地址配置协议 ==========
 
-def build_broadcast_query() -> bytes:
-    """构建广播查询指令
+# ========== CRC16 (MODBUS) ==========
 
-    DTU定时发送广播指令查询未配置地址的从机
-    格式: 00 40 00 40 00 (无CRC, 固定5字节)
-    """
-    return bytes([0x00, 0x40, 0x00, 0x40, 0x00])
+def calculate_crc16(data: bytes) -> bytes:
+    """计算Modbus CRC16校验(低字节在前)"""
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            if crc & 0x0001:
+                crc = (crc >> 1) ^ 0xA001
+            else:
+                crc >>= 1
+    return struct.pack('<H', crc)
 
 
-def parse_device_response(data: bytes, fix_crc: bool = True) -> Optional[dict]:
-    """解析从机应答
+def verify_crc16(data: bytes) -> bool:
+    """验证Modbus CRC16校验"""
+    if len(data) < 2:
+        return False
+    received_crc = struct.unpack('<H', data[-2:])[0]
+    calculated_crc = struct.unpack('<H', calculate_crc16(data[:-2]))[0]
+    return received_crc == calculated_crc
 
-    从机应答格式: 00 + 41 + 12个UID + CRC_L + CRC_H
-    例如: 00 41 18 00 40 00 14 00 00 59 59 54 30 56 AE 34
 
-    fix_crc=True: 当 CRC 不通过但帧头 + UID 有效时,重新计算正确 CRC 补帧,
-    而不是直接拒绝。用于兼容部分从机固件 CRC 计算 bug。
-    """
-    if len(data) < 16:
-        return {'error': '数据长度不足', 'raw_data': data.hex()}
+# ========== V5 地址查询 / 确认协议(0x80 / 0x81 / 0x82 / 0x83) ==========
 
-    if data[1] != 0x41:
-        return {'error': f"非预期功能码: {data[1]:#x}", 'raw_data': data.hex()}
+ADDRESS_QUERY_FC = 0x80          # DTU -> 线架:地址查询
+ADDRESS_QUERY_RESP_FC = 0x81     # 线架 -> DTU:查询应答(携带自身 UID)
+ADDRESS_CONFIRM_FC = 0x82        # DTU -> 线架:确认绑定
+ADDRESS_CONFIRM_RESP_FC = 0x83   # 线架 -> DTU:确认应答
+ADDRESS_FRAME_LEN = 16           # add(1)+fc(1)+uid(12)+crc(2)
+ZERO_UID = b'\x00' * 12          # 未绑定地址探测用 UID(12 字节全 0)
+UID_BYTES = 12
 
-    uid_bytes = data[2:14]
-    uid_hex = uid_bytes.hex()
 
-    # UID 有效性检查(CRC 之前先做,以便 CRC 失败时也能判断是否补帧)
-    from collections import Counter
-    zero_count = uid_bytes.count(0)
-    counts = Counter(uid_bytes)
-    most_common_count = counts.most_common(1)[0][1]
+def _uid_bytes(uid) -> bytes:
+    """把 UID 规范化为 12 字节。None -> 全 0;str/bytes 均可。"""
+    if uid is None:
+        return ZERO_UID
+    if isinstance(uid, str):
+        uid = uid.strip().replace(':', '').replace(' ', '').replace('-', '')
+        try:
+            uid = bytes.fromhex(uid)
+        except ValueError:
+            raise ValueError(f"UID 十六进制非法: {uid!r}")
+    if not isinstance(uid, (bytes, bytearray)):
+        raise ValueError(f"UID 类型非法: {type(uid)}")
+    if len(uid) != UID_BYTES:
+        raise ValueError(f"UID长度必须是{UID_BYTES}字节,当前: {len(uid)}")
+    return bytes(uid)
 
-    uid_looks_valid = (zero_count <= 6) and (most_common_count <= 8)
 
-    crc_ok = verify_crc16(data)
+def build_address_query_request(device_address: int, uid=None) -> bytes:
+    """构建 V5 地址查询请求(0x80,16 字节)。
 
-    if not crc_ok and fix_crc and uid_looks_valid:
-        # 补帧:重新计算正确 CRC 替换从机发出的错误 CRC
-        original_crc = data[14:16]
-        corrected_crc = calculate_crc16(data[:14])
-        data = data[:14] + corrected_crc
-        logger.warning(
-            f"广播响应 CRC 错误,已补帧修正: 原CRC={original_crc.hex()} "
-            f"→ 正确CRC={corrected_crc.hex()} (数据={data[:14].hex()})"
-        )
-    elif not crc_ok:
-        return {'error': 'CRC校验失败', 'raw_data': data.hex()}
+    格式: [add][0x80][12 字节 UID][CRC_L][CRC_H]
+    uid=None 表示 12 字节全 0(未绑定地址探测)。
+
+    文档示例: 01 80 00*12 54 01
+    """
+    data = bytes([device_address, ADDRESS_QUERY_FC]) + _uid_bytes(uid)
+    return data + calculate_crc16(data)
 
-    if not uid_looks_valid:
-        if zero_count > 6:
-            return {'error': f"UID中零字节过多({zero_count}/12)", 'raw_data': data.hex()}
-        else:
-            return {'error': f"UID中单字节重复过多({counts.most_common(1)})", 'raw_data': data.hex()}
 
+def parse_address_query_response(data: bytes) -> dict:
+    """解析 V5 地址查询应答(0x81,16 字节)。
+
+    格式: [add][0x81][12 字节 UID][CRC_L][CRC_H]
+    文档示例: 01 81 51 00 12 00 11 00 00 4C 30 31 33 56 D0 D3
+
+    返回: {'success': True, 'device_address', 'uid': '24位hex'|None, 'raw_data'}
+           UID 全 0 / 全 FF 视为无效(uid=None)。
+    """
+    if not data or len(data) < ADDRESS_FRAME_LEN:
+        return {'error': '数据长度不足',
+                'raw_data': data.hex() if data else ''}
+
+    frame = data[:ADDRESS_FRAME_LEN]
+    if frame[1] != ADDRESS_QUERY_RESP_FC:
+        return {'error': f"非预期功能码: {frame[1]:#x}", 'raw_data': frame.hex()}
+    if not verify_crc16(frame):
+        return {'error': 'CRC校验失败', 'raw_data': frame.hex()}
+
+    uid = frame[2:14]
+    valid = uid not in (b'\x00' * 12, b'\xff' * 12)
     return {
-        'function_code': 0x41,
-        'uid': uid_hex,
-        'uid_readable': ':'.join(f'{b:02x}' for b in uid_bytes),
-        'source_address': data[0],
-        'raw_data': data.hex()
+        'success': True,
+        'device_address': frame[0],
+        'uid': uid.hex() if valid else None,
+        'raw_data': frame.hex(),
     }
 
 
-def build_confirm_address(device_address: int, uid: bytes) -> bytes:
-    """构建确认地址指令
+def build_address_confirm_request(device_address: int, uid) -> bytes:
+    """构建 V5 地址确认请求(0x82,16 字节)。
 
-    DTU遍历已存储的UID和地址,如果存在匹配的UID则发送确认指令
-    格式: add + 44 + 00 + 12个UID + CRC_L + CRC_H
+    格式: [add][0x82][12 字节 UID][CRC_L][CRC_H]
+    文档示例: 01 82 51 00 12 00 11 00 00 4C 30 31 33 56 D5 10
     """
-    if len(uid) != 12:
-        raise ValueError(f"UID长度必须是12字节,当前: {len(uid)}")
-
-    data = bytes([device_address, 0x44, 0x00]) + uid
+    data = bytes([device_address, ADDRESS_CONFIRM_FC]) + _uid_bytes(uid)
     return data + calculate_crc16(data)
 
 
-def build_assign_address(uid: bytes, address: int) -> bytes:
-    """构建分配地址指令
+def parse_address_confirm_response(data: bytes) -> dict:
+    """解析 V5 地址确认应答(0x83,16 字节)。
 
-    如果DTU中没有该UID的记录,则分配新地址
-    格式: 00 + 42 + 12个UID + add + CRC_L + CRC_H
+    格式: [add][0x83][12 字节 UID][CRC_L][CRC_H]
+    文档示例: 01 83 51 00 12 00 11 00 00 4C 30 31 33 56 D7 91
     """
-    if len(uid) != 12:
-        raise ValueError(f"UID长度必须是12字节,当前: {len(uid)}")
-    if address < 1 or address > 247:
-        raise ValueError(f"设备地址必须在1-247之间,当前: {address}")
-
-    data = bytes([0x00, 0x42]) + uid + bytes([address])
-    return data + calculate_crc16(data)
+    if not data or len(data) < ADDRESS_FRAME_LEN:
+        return {'error': '数据长度不足',
+                'raw_data': data.hex() if data else ''}
+
+    frame = data[:ADDRESS_FRAME_LEN]
+    if frame[1] != ADDRESS_CONFIRM_RESP_FC:
+        return {'error': f"非预期功能码: {frame[1]:#x}", 'raw_data': frame.hex()}
+    if not verify_crc16(frame):
+        return {'error': 'CRC校验失败', 'raw_data': frame.hex()}
+
+    uid = frame[2:14]
+    valid = uid not in (b'\x00' * 12, b'\xff' * 12)
+    return {
+        'success': True,
+        'device_address': frame[0],
+        'uid': uid.hex() if valid else None,
+        'raw_data': frame.hex(),
+    }
 
 
-def parse_address_assignment_response(data: bytes) -> dict:
-    """解析地址分配响应
+# ========== V5 配置地址状态(非 MODBUS 帧,用于刷配置卡设置地址) ==========
+
+# 文档帧: aa b7 00 07 80 00 00 ff 00 00 02 64 03
+#   帧头 AA B7 + 7 字节数据 + 0x64(帧内固定校验/参数, 按文档原样发送) + 0x03 结尾
+CONFIG_ADDRESS_ENTER_FRAME = bytes.fromhex('aab70007800000ff0000026403')
+
+# 应答帧: 55 00 00 02 ANTLIST ADDR XOR 03  (8 字节)
+CONFIG_ADDRESS_RESPONSE_LEN = 8
+CONFIG_ADDRESS_HEADER = 0x55
+CONFIG_ADDRESS_TAIL = 0x03
+
+
+def build_config_address_enter_frame() -> bytes:
+    """让线架进入"配置地址状态"(等待刷配置卡)的广播帧。"""
+    return CONFIG_ADDRESS_ENTER_FRAME
+
+
+def _parse_config_address_frame(frame: bytes) -> Optional[dict]:
+    """解析单个 8 字节配置卡应答帧,失败返回 None。"""
+    if len(frame) < CONFIG_ADDRESS_RESPONSE_LEN:
+        return None
+    head = frame[0]
+    ant = frame[4]
+    addr = frame[5]
+    xor = frame[6]
+    tail = frame[7]
+    if head != CONFIG_ADDRESS_HEADER or tail != CONFIG_ADDRESS_TAIL:
+        return None
+    if not (1 <= ant <= 24) or not (0 <= addr <= 247):
+        return None
+    expect = 0
+    for b in frame[:6]:          # XOR = 0x55 起直到 ADDR
+        expect ^= b
+    if expect != xor:
+        return None
+    return {
+        'success': True,
+        'antenna': ant,
+        'address': addr,
+        'raw_data': frame.hex(),
+    }
 
-    模块应答格式: add + 43 + 00 + CRC_L + CRC_H
-    例如: 01 43 00 11 30
-    """
-    if len(data) < 5:
-        return {'error': '数据长度不足', 'raw_data': data.hex()}
 
-    device_address = data[0]
+def parse_config_address_response(data: bytes) -> dict:
+    """在收到的数据中查找配置卡应答帧。
 
-    if data[1] != 0x43:
-        return {'error': f"非预期功能码: {data[1]:#x}", 'raw_data': data.hex()}
+    格式: 55 00 00 02 [ANTLIST] [ADDR] [XOR] 03
+      ANTLIST: 读到配置卡的天线号(1 开始)
+      ADDR   : 配置的地址
+      XOR    : 0x55 起到 ADDR 的异或和
 
-    if not verify_crc16(data):
-        logger.warning(f"CRC校验失败: {data.hex()}")
+    返回 {'success': True, 'antenna', 'address', 'raw_data'} 或 {'error': ...}
+    """
+    if not data:
+        return {'error': '无数据', 'raw_data': ''}
+    if len(data) < CONFIG_ADDRESS_RESPONSE_LEN:
+        return {'error': f'数据长度不足 ({len(data)}/{CONFIG_ADDRESS_RESPONSE_LEN})',
+                'raw_data': data.hex()}
+    for i in range(len(data) - CONFIG_ADDRESS_RESPONSE_LEN + 1):
+        parsed = _parse_config_address_frame(data[i:i + CONFIG_ADDRESS_RESPONSE_LEN])
+        if parsed:
+            return parsed
+    return {'error': '未找到有效的配置卡应答帧', 'raw_data': data.hex()}
 
-    return {
-        'device_address': device_address,
-        'function_code': 0x43,
-        'raw_data': data.hex()
-    }
 
+# ========== 线架绑定表 / 总线互斥 ==========
 
 class AddressConfigProtocol:
-    """地址配置协议处理器"""
+    """线架地址↔UID 绑定表 + 总线配置互斥锁。
+
+    V5 起不再提供广播发现/自动分配地址,仅保留绑定表持久化与
+    "配置地址期间占用总线"的互斥锁。
+    """
 
     def __init__(self, serial_port):
         self.serial = serial_port
-        self.default_timeout = 5.0  # 设备广播响应可能较慢,给足时间
-        self.stored_devices = {}
-        self.config_lock = threading.RLock()  # 地址配置期间占用,避免与轮询冲突
+        self.default_timeout = 5.0
+        self.stored_devices = {}          # {uid_hex: address}
+        self.config_lock = threading.RLock()
 
     def add_stored_device(self, uid: str, address: int):
         """添加已存储的设备"""
@@ -137,156 +248,6 @@ class AddressConfigProtocol:
         """获取已存储的设备列表"""
         return self.stored_devices.copy()
 
-    def broadcast_query(self, timeout: float = None) -> list:
-        """send broadcast query and collect all valid 00 41 responses"""
-        import time
-
-        with self.config_lock:
-            request = build_broadcast_query()
-            logger.info(f"send broadcast: {request.hex()}")
-
-            timeout = timeout or self.default_timeout
-            # 先清空输入缓冲区,避免残留数据干扰
-            self.serial.flush_input()
-            time.sleep(0.05)
-
-            # 发送广播并等待响应;所有串口操作统一走发送队列,
-            # 这里不再额外直接读串口,避免在收集窗口内把后续队列命令的响应抢走。
-            response = self.serial.send_and_wait(request, timeout=timeout, min_response_bytes=16)
-
-            responses = []
-            if response and len(response) >= 16:
-                logger.info(f"got raw response ({len(response)}B): {response.hex()}")
-                # RS485 半双工会回显已发送的数据,导致 response 开头可能有 5 字节回显
-                # 在 response 中搜索所有 00 41 标记,尝试从中提取 16 字节帧解析
-                for i in range(len(response) - 15 + 1):
-                    if response[i] == 0x00 and response[i + 1] == 0x41:
-                        chunk = response[i:i + 16]
-                        if len(chunk) >= 16:
-                            parsed = parse_device_response(chunk)
-                            if "error" not in parsed:
-                                if not any(p.get('uid') == parsed['uid'] for p in responses):
-                                    responses.append(parsed)
-            else:
-                logger.info(f"no response or too short: {len(response) if response else 0}B")
-
-            logger.info(f"broadcast done, got {len(responses)} valid unique responses")
-            return responses
-
-    def _next_available_address(self) -> int:
-        """从 1~247 中找一个未被 stored_devices 占用的地址"""
-        used = set(self.stored_devices.values())
-        for addr in range(1, 248):
-            if addr not in used:
-                return addr
-        raise RuntimeError("Modbus 地址 1~247 已全部占用")
-
-    def process_responses(self, responses: list) -> list:
-        """处理广播查询响应:给每个应答设备分配地址(优先使用已记录地址)"""
-        import time
-
-        with self.config_lock:
-            results = []
-
-            for resp in responses:
-                if 'error' in resp:
-                    results.append({'status': 'error', 'message': resp['error']})
-                    continue
-
-                uid = resp['uid']
-                src_addr = resp.get('source_address', 0)
-                device_address = self.stored_devices.get(uid)
-
-                # 优先使用地址表中已保存的地址;没有则分配下一个可用地址
-                if device_address:
-                    new_address = device_address
-                    logger.info(f"UID={uid} 源地址={src_addr},地址表存在记录,分配已有地址={new_address}")
-                else:
-                    new_address = self._next_available_address()
-                    logger.info(f"UID={uid} 源地址={src_addr},地址表无记录,分配新地址={new_address}")
-
-                request = build_assign_address(bytes.fromhex(uid), new_address)
-                logger.info(f"发送分配地址帧: {request.hex()}")
-                self.serial.flush_input()
-                time.sleep(0.05)
-                success, msg = self.serial.send_raw(request)
-                if not success:
-                    logger.error(f"UID={uid} 分配地址帧发送失败: {msg}")
-                    results.append({
-                        'status': 'error',
-                        'uid': uid,
-                        'message': f"send failed: {msg}"
-                    })
-                    continue
-
-                # 等待并解析从机的 43 确认响应
-                # 用 wait_response 只读等待:不发空数据(避免前端空JSON)、不清空接收缓冲(避免冲掉43)
-                time.sleep(0.1)
-                ack = self.serial.wait_response(timeout=0.8, min_response_bytes=5)
-                ack_parsed = None
-                if ack and len(ack) >= 5:
-                    # 过滤回显/噪声,找到 43 响应帧
-                    for i in range(len(ack) - 4):
-                        if ack[i + 1] == 0x43:
-                            chunk = ack[i:i + 5]
-                            ack_parsed = parse_address_assignment_response(chunk)
-                            break
-
-                if ack_parsed and 'error' not in ack_parsed:
-                    logger.info(f"UID={uid} 地址={new_address} 已确认 (响应: {ack_parsed.get('raw_data')})")
-                    self.stored_devices[uid] = new_address
-                    results.append({
-                        'status': 'assigned',
-                        'uid': uid,
-                        'address': new_address,
-                        'request': request.hex(),
-                        'ack': ack_parsed.get('raw_data')
-                    })
-                else:
-                    # 即使未收到确认也保存地址:部分从机不返回 43,但实际已生效
-                    logger.warning(f"UID={uid} 地址={new_address} 未收到 43 确认,仍视为已分配")
-                    self.stored_devices[uid] = new_address
-                    results.append({
-                        'status': 'assigned',
-                        'uid': uid,
-                        'address': new_address,
-                        'request': request.hex(),
-                        'ack': ack.hex() if ack else None
-                    })
-
-            return results
-
-    def auto_configure(self, timeout: float = None) -> dict:
-        """自动配置所有未配置的设备"""
-        with self.config_lock:
-            logger.info("开始自动配置设备...")
-
-            responses = self.broadcast_query(timeout)
-
-            if not responses:
-                return {
-                    'success': True,
-                    'message': '未发现任何从机设备',
-                    'discovered': 0,
-                    'configured': 0,
-                    'results': []
-                }
-
-            results = self.process_responses(responses)
-
-            assigned = sum(1 for r in results if r.get('status') == 'assigned')
-            errors = sum(1 for r in results if r.get('status') == 'error')
-
-            return {
-                'success': errors == 0,
-                'discovered': len(responses),
-                'confirmed': 0,
-                'assigned': assigned,
-                'errors': errors,
-                'results': results,
-                'stored_devices': self.get_stored_devices()
-            }
-
     def save_config(self, filepath: str) -> bool:
         """保存配置到文件"""
         import json
@@ -309,23 +270,23 @@ class AddressConfigProtocol:
             logger.error(f"加载配置失败: {e}")
             return False
 
-# ========== Modbus RTU Client ==========
 
-# ========== V4 批量读卡协议常量 ==========
-# V4: 一次性批量读 24 路卡号;每张卡 6 字节;无卡标记 6×0xFF。
-# 注: 硬件通信固定 6 字节卡号;对 MQTT 的 8 字节(16 位)适配在 app.py 边界完成
-#     (前 4 位 DTU 号 + 后 12 位卡号)。
+# ========== V5 批量读卡 / 设置卡号协议常量 ==========
+
 CARD_REG_ADDR = 0x0002          # 批量卡号读起始寄存器
 CARD_REG_QUANTITY = 0x48        # 72 寄存器 = 144 字节
 CARD_DATA_BYTES = 144           # 24 天线 × 6 字节
 BYTES_PER_TAG = 6
 ANTENNA_COUNT = 24
-NO_TAG_BYTES = b'\xff' * 6      # V4 无卡标记
+NO_TAG_BYTES = b'\xff' * 6      # 无卡标记
 NO_TAG_HEX = 'ffffffffffff'
 BULK_BYTE_COUNT = 0x90          # 144,Modbus 响应字节计数字段
+BULK_REQUEST_LEN = 8            # addr(1)+fc(1)+start(2)+qty(2)+crc(2)
 BULK_RESPONSE_LEN = 149         # addr(1)+fc(1)+bytecount(1)+data(144)+crc(2)
+# 过渡期兼容:V4 旧固件响应尾部还带 12 字节 UID(161 字节)
+LEGACY_UID_RESPONSE_LEN = 161
 
-# V4 设置卡号协议常量(非标准 MODBUS 0x10)
+# 设置卡号协议常量(非标准 MODBUS 0x10)
 # 协议帧: [addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]
 # 注意: 与标准 MODBUS 0x10 不同,此处省略 byte count 字段,数量字段 0x0090 直接表示字节数(144)
 SET_CARD_REG_ADDR = 0x0003      # 设置卡号起始寄存器
@@ -334,59 +295,18 @@ SET_CARD_DATA_BYTES = 144       # 24 路 × 6 字节
 SET_CARD_REQUEST_LEN = 152      # addr(1)+fc(1)+start(2)+qty(2)+data(144)+crc(2)
 SET_CARD_RESPONSE_LEN = 8       # addr(1)+fc(1)+start(2)+qty(2)+crc(2)
 
-# 带 UID 读卡协议(地址段轮询 / 线架绑定)
-# 请求 20B: [addr][0x03][0x00][0x02][0x00][0x48][12 字节 UID][CRC_L][CRC_H]
-#   UID = 该地址已绑定的线架 UID;未绑定时为 12 字节全 0(uid=None 探测),
-#   未配置线架收到探测帧后采纳该地址并应答自身 UID,DTU 据此绑定"地址↔UID"。
-# 响应 161B: [addr][0x03][0x90][144 字节卡数据][12 字节 UID][CRC_L][CRC_H]
-#   UID = 线架自身 UID(探测响应时用于绑定)。
-READ_WITH_UID_REQUEST_LEN = 20
-READ_WITH_UID_RESPONSE_LEN = 161
-ZERO_UID = b'\x00' * 12
-
 # 天线地址映射表(天线编号 -> Modbus寄存器地址)
-# V4: 所有天线共享寄存器 0x0002,由 read_all_antenna_cards 一次批量读出
+# 所有天线共享寄存器 0x0002,由 read_all_antenna_cards 一次批量读出
 ANTENNA_ADDRESSES = {i: CARD_REG_ADDR for i in range(1, 25)}
 
-import struct
-import logging
-
-logger = logging.getLogger('serial_mqtt_gateway')
 
+def build_read_cards_request(device_address: int) -> bytes:
+    """构建 V5 批量读卡请求(标准 MODBUS 0x03,8 字节)。
 
-def calculate_crc16(data: bytes) -> bytes:
-    """计算Modbus CRC16校验"""
-    crc = 0xFFFF
-    for byte in data:
-        crc ^= byte
-        for _ in range(8):
-            if crc & 0x0001:
-                crc = (crc >> 1) ^ 0xA001
-            else:
-                crc >>= 1
-    return struct.pack('<H', crc)
-
-
-def verify_crc16(data: bytes) -> bool:
-    """验证Modbus CRC16校验"""
-    if len(data) < 2:
-        return False
-    received_crc = struct.unpack('<H', data[-2:])[0]
-    calculated_crc = struct.unpack('<H', calculate_crc16(data[:-2]))[0]
-    return received_crc == calculated_crc
-
-
-def build_read_cards_request(device_address: int, uid: Optional[bytes] = None) -> bytes:
-    """构建带 UID 的 V4 批量读卡请求(20 字节)。
-
-    格式: [addr][0x03][0x00][0x02][0x00][0x48][12 字节 UID][CRC_L][CRC_H]
-    uid=None 表示 12 字节全 0 探测(未绑定地址;未配置线架会采纳该地址)。
+    格式: [add][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H]
+    文档示例: 01 03 00 02 00 48 E4 3C
     """
-    if uid is None:
-        uid = ZERO_UID
-    if len(uid) != 12:
-        raise ValueError(f"UID长度必须是12字节,当前: {len(uid)}")
-    data = bytes([device_address, 0x03]) + struct.pack('>HH', CARD_REG_ADDR, CARD_REG_QUANTITY) + bytes(uid)
+    data = bytes([device_address, 0x03]) + struct.pack('>HH', CARD_REG_ADDR, CARD_REG_QUANTITY)
     return data + calculate_crc16(data)
 
 
@@ -397,7 +317,7 @@ class ModbusRTUClient:
         self.serial = serial_port
         self.default_timeout = 2.0
         self.test_cards = None  # 测试注入:非 None 时 read_all_antenna_cards 返回构造数据
-        self.test_panel_uids = None  # 测试注入:{addr: 'hex24'} 模拟线架自身 UID
+        self.test_panel_uids = None  # 测试注入:{addr: 'hex24'} 模拟线架自身 UID(query_address 用)
 
     def _build_request(self, device_address: int, function_code: int, data: bytes = b'') -> bytes:
         """构建Modbus请求帧"""
@@ -428,26 +348,87 @@ class ModbusRTUClient:
             "raw_data": response.hex()
         }
 
-    def read_all_antenna_cards(self, device_address: int, uid: Optional[bytes] = None, timeout: float = None) -> dict:
-        """V4+: 带 UID 的批量读取全部 24 路天线卡号。
+    # ----- V5 地址查询 / 确认 -----
+
+    def query_address(self, device_address: int, uid=None, timeout: float = None) -> dict:
+        """V5 地址查询(0x80)。
+
+        Args:
+            device_address: 要查询的固定地址
+            uid: 已绑定的 UID(str/bytes);None -> 12 字节全 0 探测
+        Returns:
+            {'success': True, 'device_address', 'uid': '24位hex'|None, 'raw_data'}
+            或 {'error': ...}
+        """
+        if self.test_panel_uids is not None:
+            # 测试注入:按地址返回模拟线架 UID(未列出的地址视为无应答)
+            simulated = self.test_panel_uids.get(device_address)
+            if simulated is None:
+                return {"error": "response timeout or too short", "raw_data": ""}
+            return {
+                "success": True,
+                "device_address": device_address,
+                "uid": str(simulated).lower(),
+                "raw_data": "TEST_INJECTED",
+            }
+
+        timeout = timeout or self.default_timeout
+        if not self.serial.ser:
+            return {"error": "serial not connected"}
+
+        try:
+            request = build_address_query_request(device_address, uid)
+        except ValueError as e:
+            return {"error": str(e)}
+
+        response = self.serial.send_and_wait(
+            request, timeout=timeout, min_response_bytes=ADDRESS_FRAME_LEN
+        )
+        if not response:
+            return {"error": "response timeout or too short", "raw_data": ""}
+        return parse_address_query_response(response)
+
+    def confirm_address(self, device_address: int, uid, timeout: float = None) -> dict:
+        """V5 地址确认(0x82):DTU 确认"地址↔UID"绑定。"""
+        if self.test_panel_uids is not None:
+            return {"success": True, "device_address": device_address,
+                    "uid": str(uid).lower() if uid else None, "raw_data": "TEST_INJECTED"}
+
+        timeout = timeout or self.default_timeout
+        if not self.serial.ser:
+            return {"error": "serial not connected"}
+
+        try:
+            request = build_address_confirm_request(device_address, uid)
+        except ValueError as e:
+            return {"error": str(e)}
+
+        response = self.serial.send_and_wait(
+            request, timeout=timeout, min_response_bytes=ADDRESS_FRAME_LEN
+        )
+        if not response:
+            return {"error": "response timeout or too short", "raw_data": ""}
+        return parse_address_confirm_response(response)
+
+    # ----- V5 批量读卡 -----
+
+    def read_all_antenna_cards(self, device_address: int, timeout: float = None) -> dict:
+        """V5: 批量读取全部 24 路天线卡号(标准 MODBUS 0x03)。
 
         寄存器 0x0002,数量 0x48(72 寄存器 = 144 字节)。
-        请求 20B: [addr][0x03][0x00][0x02][0x00][0x48][12 字节 UID][CRC_L][CRC_H]
-          uid=None 表示 12 字节全 0 探测(未绑定地址探测/换架接管用)。
-        响应 161B: [addr][0x03][0x90][144 数据字节][12 字节 UID][CRC_L][CRC_H]
-          响应 UID = 线架自身 UID(未绑定/换架时用于绑定)。
+        请求 8B:  [addr][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H]
+        响应 149B:[addr][0x03][0x90][144 数据字节][CRC_L][CRC_H]
         每张卡 6 字节(硬件卡号,12 位十六进制);无卡标记 = 6×0xFF。
-        MQTT 侧的 8 字节(16 位) jumper_uid 适配在 app.py 边界完成。
 
-        过渡期兼容: 旧固件 149B 响应仍可解析(panel_uid=None 仅作诊断),不能用于绑定。
+        过渡期兼容: V4 旧固件 161B 响应(尾部多 12 字节 UID)仍可解析,
+        UID 字段在此层忽略(地址↔UID 绑定走 0x80/0x82 查询确认)。
 
         返回:
             {'success': True, 'device_address', 'function_code': 0x03,
              'cards': [{'antenna', 'card_str', 'present', 'uid'}, ...24],
-             'panel_uid': '24位hex'|None, 'raw_data'}
+             'raw_data'}
         """
         # 测试注入: test_cards = {addr: {port_id: 'hex12'|None, ...}, ...}
-        #           test_panel_uids = {addr: 'hex24'}(可选, 模拟线架自身 UID)
         if self.test_cards is not None:
             panel_map = self.test_cards.get(device_address)
             if panel_map is not None:
@@ -472,7 +453,6 @@ class ModbusRTUClient:
                     "device_address": device_address,
                     "function_code": 0x03,
                     "cards": cards,
-                    "panel_uid": (self.test_panel_uids or {}).get(device_address),
                     "raw_data": "TEST_INJECTED"
                 }
 
@@ -481,14 +461,9 @@ class ModbusRTUClient:
         if not self.serial.ser:
             return {"error": "serial not connected"}
 
-        try:
-            request = build_read_cards_request(device_address, uid)
-        except ValueError as e:
-            return {"error": str(e)}
-
-        # 直调 send_and_wait 并要求完整 161 字节(或旧格式 149 字节)
+        request = build_read_cards_request(device_address)
         response = self.serial.send_and_wait(
-            request, timeout=timeout, min_response_bytes=READ_WITH_UID_RESPONSE_LEN
+            request, timeout=timeout, min_response_bytes=BULK_RESPONSE_LEN
         )
 
         if not response or len(response) < 5:
@@ -500,22 +475,21 @@ class ModbusRTUClient:
             return {"error": f"Modbus exception: {response[2]:#x}",
                     "raw_data": response.hex()}
 
-        panel_uid = None
-        if len(response) >= READ_WITH_UID_RESPONSE_LEN:
-            frame = response[:READ_WITH_UID_RESPONSE_LEN]
-            raw_uid = frame[3 + CARD_DATA_BYTES:3 + CARD_DATA_BYTES + 12]
-            panel_uid = raw_uid.hex() if raw_uid != ZERO_UID else None
-        elif len(response) >= BULK_RESPONSE_LEN:
-            # 过渡期兼容:旧固件 149B 响应(无 UID 字段)
-            logger.warning("收到旧格式(149B)批量读卡响应,无 UID 字段,无法用于线架绑定")
+        frame = None
+        if (len(response) >= BULK_RESPONSE_LEN
+                and response[1] == 0x03 and response[2] == BULK_BYTE_COUNT
+                and verify_crc16(response[:BULK_RESPONSE_LEN])):
+            frame = response[:BULK_RESPONSE_LEN]
+        elif len(response) >= LEGACY_UID_RESPONSE_LEN and verify_crc16(
+                response[:LEGACY_UID_RESPONSE_LEN]):
+            # 过渡期兼容:V4 旧固件 161B 响应(无 UID 使用价值,仅解析卡数据)
+            logger.debug("收到旧格式(161B)批量读卡响应,UID 字段已忽略")
             frame = response[:BULK_RESPONSE_LEN]
         else:
-            return {"error": f"response too short ({len(response)}/{READ_WITH_UID_RESPONSE_LEN})",
-                    "raw_data": response.hex()}
-
-        if not verify_crc16(frame):
-            logger.warning(f"CRC check failed: {frame.hex()}")
-            return {"error": "CRC check failed", "raw_data": frame.hex()}
+            if len(response) < BULK_RESPONSE_LEN:
+                return {"error": f"response too short ({len(response)}/{BULK_RESPONSE_LEN})",
+                        "raw_data": response.hex()}
+            return {"error": "CRC check failed", "raw_data": response.hex()}
 
         if frame[1] != 0x03 or frame[2] != BULK_BYTE_COUNT:
             return {"error": f"unexpected response: fc={frame[1]:#x} count={frame[2]:#x}",
@@ -539,15 +513,14 @@ class ModbusRTUClient:
             "device_address": frame[0],
             "function_code": 0x03,
             "cards": cards,
-            "panel_uid": panel_uid,
             "raw_data": frame.hex()
         }
 
     def read_antenna_card(self, device_address: int, antenna_num: int, timeout: float = None) -> dict:
-        """读取单根天线卡号(V4: 由批量读提取,不再发 V2 逐天线帧)。
+        """读取单根天线卡号(由批量读提取,不再发逐天线帧)。
 
         调用 read_all_antenna_cards 后提取指定天线,返回兼容 schema。
-        无卡时 card_number_str 为空串(V2 是 '0000000000000000')。
+        无卡时 card_number_str 为空串。
         """
         if antenna_num < 1 or antenna_num > ANTENNA_COUNT:
             return {"error": f"invalid antenna number: {antenna_num}, must be 1-{ANTENNA_COUNT}"}
@@ -583,7 +556,7 @@ class ModbusRTUClient:
         }
 
     def set_card_mapping(self, device_address: int, card_mappings: dict, timeout: float = None) -> dict:
-        """V4: 设置24路天线卡号(0x10 写 0x0003,144字节,非标准MODBUS无bytecount)。
+        """设置24路天线卡号(0x10 写 0x0003,144字节,非标准MODBUS无bytecount)。
 
         协议帧(发送): [addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]
         协议帧(响应): [addr][0x10][0x00][0x03][0x00][0x90][CRC_L][CRC_H]

+ 201 - 6
backend/modules/serial_port.py

@@ -28,6 +28,151 @@ class SerialConfig:
     rtscts: bool = False
     dsrdtr: bool = False
 
+
+class Rs485Direction:
+    """RS485 收发方向 GPIO 控制(可选)。
+
+    仅当配置了 SERIAL_RS485_DIR_GPIO(如 "gpiochip0:25")时启用。
+    典型用途:板载 TTL 转 RS485 模块为"自动方向"且切换太慢时,会把从机
+    立刻返回的应答压掉(表现为:发送正常、rx 计数完全不动)。把模块的
+    DE/RE 引到空闲 GPIO 上,由本类在发送前拉高、发送完成后拉低即可解决。
+
+    任何异常都会让本类自动降级为"不控制方向",绝不影响串口主流程。
+    """
+
+    def __init__(self, spec: str, pre_delay: float = 0.001, post_delay: float = 0.001):
+        self.spec = (spec or '').strip()
+        self.pre_delay = max(0.0, float(pre_delay or 0))
+        self.post_delay = max(0.0, float(post_delay or 0))
+        self.chip_name = ''
+        self.line_offset = -1
+        self.active_low = False      # True 表示低电平为"发送态"
+        self.ready = False
+        self._line = None
+        self._chip = None
+
+    def _parse(self) -> bool:
+        parts = [p.strip() for p in self.spec.split(':') if p.strip()]
+        if len(parts) < 2:
+            logger.warning(f"RS485 方向 GPIO 配置无效(应为 gpiochip0:25[:low]): {self.spec!r}")
+            return False
+        self.chip_name = parts[0]
+        try:
+            self.line_offset = int(parts[1], 0)
+        except ValueError:
+            logger.warning(f"RS485 方向 GPIO line 号无效: {parts[1]!r}")
+            return False
+        self.active_low = len(parts) >= 3 and parts[2].lower() in ('low', 'active_low', '0')
+        return True
+
+    def open(self) -> bool:
+        """打开并申请 GPIO 输出线,成功后 ready=True"""
+        if not self.spec:
+            return False
+        if not self._parse():
+            return False
+        try:
+            import gpiod  # 延迟导入:没装 gpiod 的机器不受影响
+        except Exception as e:
+            logger.warning(f"RS485 方向 GPIO 不可用(gpiod 未安装): {e}")
+            return False
+
+        try:
+            chip_cls = getattr(gpiod, 'Chip', None) or getattr(gpiod, 'chip', None)
+            if chip_cls is None:
+                logger.warning("RS485 方向 GPIO 不可用:当前 gpiod 版本不支持 Chip/chip API")
+                return False
+            self._chip = chip_cls(self.chip_name)
+            self._line = self._chip.get_line(self.line_offset)
+            if not self._request_output(gpiod):
+                return False
+            # 上电默认处于接收态
+            self._set(False)
+            self.ready = True
+            logger.info(
+                f"RS485 方向控制已启用: {self.spec}({'低' if self.active_low else '高'}电平为发送态,"
+                f"前置 {self.pre_delay*1000:.1f}ms / 后置 {self.post_delay*1000:.1f}ms)"
+            )
+            return True
+        except Exception as e:
+            logger.warning(f"RS485 方向 GPIO 打开失败,将不控制方向: {e}")
+            self._line = None
+            self._chip = None
+            self.ready = False
+            return False
+
+    def _request_output(self, gpiod) -> bool:
+        """兼容 gpiod 1.4/1.5/2.x 的申请输出写法"""
+        attempts = []
+        # 1.5.x:line_request 对象
+        if hasattr(gpiod, 'line_request'):
+            try:
+                req = gpiod.line_request()
+                req.consumer = 'dzxj_dtu_rs485_dir'
+                req.request_type = getattr(gpiod.line_request, 'DIRECTION_OUTPUT',
+                                           getattr(gpiod, 'LINE_REQ_DIR_OUT', 2))
+                attempts.append(lambda: self._line.request(req))
+            except Exception:
+                pass
+        # 1.4.x:名称参数
+        attempts.append(lambda: self._line.request(
+            consumer='dzxj_dtu_rs485_dir',
+            type=getattr(gpiod, 'LINE_REQ_DIR_OUT', 2)))
+        # 2.x:位置参数
+        attempts.append(lambda: self._line.request('dzxj_dtu_rs485_dir', 2, 0))
+
+        last_err = None
+        for fn in attempts:
+            try:
+                fn()
+                return True
+            except Exception as e:
+                last_err = e
+        logger.warning(f"RS485 方向 GPIO 申请失败: {last_err}")
+        return False
+
+    def _set(self, is_tx: bool):
+        if self._line is None:
+            return
+        value = (0 if is_tx else 1) if self.active_low else (1 if is_tx else 0)
+        try:
+            self._line.set_value(value)
+        except Exception as e:
+            logger.warning(f"RS485 方向 GPIO 置位失败,停止方向控制: {e}")
+            self.ready = False
+
+    def to_tx(self):
+        """切换到发送态"""
+        if not self.ready:
+            return
+        self._set(True)
+        if self.pre_delay:
+            time.sleep(self.pre_delay)
+
+    def to_rx(self):
+        """切回接收态(必须在最后一位真正发完之后调用)"""
+        if not self.ready:
+            return
+        if self.post_delay:
+            time.sleep(self.post_delay)
+        self._set(False)
+
+    def close(self):
+        self.ready = False
+        try:
+            if self._line is not None:
+                self._line.release()
+        except Exception:
+            pass
+        try:
+            if self._chip is not None and hasattr(self._chip, 'close'):
+                self._chip.close()
+        except Exception:
+            pass
+        self._line = None
+        self._chip = None
+
+
 class SerialPort:
     """串口通信类,提供串口连接、读写和状态管理功能"""
     
@@ -42,6 +187,7 @@ class SerialPort:
         self.status_callback = None
         self.error_callback = None
         self.current_config = None
+        self._rs485_dir = None        # RS485 方向控制(可选)
         self.reconnect_attempts = 0
         self.max_reconnect_attempts = 3
         self.raw_response_buffer = []
@@ -105,14 +251,58 @@ class SerialPort:
 
         logger.info("串口发送队列工作线程结束")
 
+    def _init_rs485_dir(self):
+        """按配置初始化 RS485 方向控制 GPIO(未配置则不启用)"""
+        self._close_rs485_dir()
+        try:
+            import config as app_config
+            spec = getattr(app_config, 'SERIAL_RS485_DIR_GPIO', '') or ''
+            pre = getattr(app_config, 'SERIAL_RS485_DIR_PRE_DELAY', 0.001)
+            post = getattr(app_config, 'SERIAL_RS485_DIR_POST_DELAY', 0.001)
+        except Exception:
+            return
+        if not spec:
+            return
+        direction = Rs485Direction(spec, pre_delay=pre, post_delay=post)
+        if direction.open():
+            self._rs485_dir = direction
+        else:
+            self._rs485_dir = None
+
+    def _close_rs485_dir(self):
+        if self._rs485_dir is not None:
+            try:
+                self._rs485_dir.close()
+            except Exception:
+                pass
+            self._rs485_dir = None
+
+    def _rs485_write(self, data: bytes) -> int:
+        """写串口并 flush(tcdrain)。
+
+        配置了方向 GPIO 时:发送前切到发送态,最后一位发完后立刻切回接收态,
+        避免板载 485 模块方向切换滞后把从机应答压掉。
+        """
+        direction = self._rs485_dir
+        if direction is not None and direction.ready:
+            direction.to_tx()
+            try:
+                sent = self.ser.write(data)
+                self.ser.flush()
+            finally:
+                direction.to_rx()
+            return sent
+        sent = self.ser.write(data)
+        self.ser.flush()
+        return sent
+
     def _do_send_raw(self, data: bytes):
         """实际执行 send_raw(在队列工作线程中调用)"""
         try:
             with self.lock:
                 if not self.is_connected or not self.ser or not self.ser.is_open:
                     return False, "serial port not connected"
-                bytes_sent = self.ser.write(data)
-                self.ser.flush()
+                bytes_sent = self._rs485_write(data)
             if self.send_callback and data:
                 self.send_callback(data.hex())
             return True, "send ok"
@@ -143,8 +333,7 @@ class SerialPort:
                 else:
                     raise TypeError("数据必须是字符串或字节类型")
 
-                bytes_sent = self.ser.write(bytes_data)
-                self.ser.flush()
+                bytes_sent = self._rs485_write(bytes_data)
 
                 logger.debug(f"发送数据到串口: {bytes_data.hex()[:50]}... (共{bytes_sent}字节)")
                 return True, "发送成功"
@@ -181,8 +370,7 @@ class SerialPort:
                     return b''
                 self.raw_response_buffer.clear()
                 self.ser.reset_input_buffer()
-                self.ser.write(data)
-                self.ser.flush()
+                self._rs485_write(data)
                 # 485 半双工:等最后字节发完并给收发器一点切换方向的时间
                 time.sleep(0.03)
 
@@ -382,6 +570,9 @@ class SerialPort:
                 self.current_config = config
                 self.reconnect_attempts = 0
 
+                # RS485 方向控制 GPIO(可选,未配置则跳过)
+                self._init_rs485_dir()
+
                 # 启动读取线程
                 self.read_thread = threading.Thread(target=self._read_loop, daemon=True)
                 self.read_thread.start()
@@ -406,6 +597,9 @@ class SerialPort:
         try:
             logger.info("断开串口连接")
 
+            # 释放 RS485 方向控制 GPIO
+            self._close_rs485_dir()
+
             # 阶段 0:清空发送队列中待执行的指令,避免断开后再发数据
             try:
                 while not self._cmd_queue.empty():
@@ -493,6 +687,7 @@ class SerialPort:
 
     def _close_on_error(self):
         """读取异常时关闭串口并触发状态回调,但不直接重连"""
+        self._close_rs485_dir()
         with self.lock:
             if self.ser and self.ser.is_open:
                 try:

+ 44 - 0
backend/tests/test_app.py

@@ -390,5 +390,49 @@ class TestApp:
                 app_module.screen_current_panel_index = orig_index
 
 
+class TestDefaultSerialConfig:
+    """默认串口:S8 接配线架总线(TTL 转 RS485),S9 接 Nextion 串口屏"""
+
+    def test_default_ports(self):
+        import config as config_module
+        assert config_module.DEFAULT_SERIAL_PORT == '/dev/ttyS8'
+        assert config_module.DEFAULT_NEXTION_SCREEN_PORT == '/dev/ttyS9'
+
+    def test_missing_file_returns_default(self, tmp_path):
+        import app as app_module
+        missing = tmp_path / 'serial_config.json'
+        with patch.object(app_module, 'SERIAL_CONFIG_FILE', str(missing)):
+            cfg = app_module.load_serial_config()
+        assert cfg['port'] == '/dev/ttyS8'
+        assert cfg['baudrate'] == 9600
+        assert cfg['bytesize'] == 8
+        assert cfg['parity'] == 'N'
+        assert cfg['stopbits'] == 1
+
+    def test_corrupt_file_without_snapshot_returns_default(self, tmp_path):
+        import app as app_module
+        broken = tmp_path / 'serial_config.json'
+        broken.write_text('{not json', encoding='utf-8')
+        with patch.object(app_module, 'SERIAL_CONFIG_FILE', str(broken)), \
+                patch.object(app_module.config_backup, 'latest_snapshot_content',
+                             return_value=(None, None)):
+            cfg = app_module.load_serial_config()
+        assert cfg['port'] == '/dev/ttyS8'
+
+    def test_empty_env_falls_back_to_defaults(self, monkeypatch):
+        import importlib
+        import config as config_module
+        monkeypatch.setenv('NEXTION_SCREEN_PORT', '')
+        monkeypatch.setenv('DEFAULT_SERIAL_PORT', '')
+        reloaded = importlib.reload(config_module)
+        try:
+            assert reloaded.NEXTION_SCREEN_PORT == '/dev/ttyS9'
+            assert reloaded.DEFAULT_SERIAL_PORT == '/dev/ttyS8'
+        finally:
+            monkeypatch.delenv('NEXTION_SCREEN_PORT', raising=False)
+            monkeypatch.delenv('DEFAULT_SERIAL_PORT', raising=False)
+            importlib.reload(config_module)
+
+
 if __name__ == "__main__":
     pytest.main(["-v", __file__])

+ 84 - 0
backend/tests/test_backup_restore.py

@@ -0,0 +1,84 @@
+"""运行数据备份/恢复:端口↔卡号映射(绑定②)必须随备份导出/导入保留。"""
+import sys
+import os
+from unittest.mock import patch
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import app as app_module  # noqa: E402
+
+
+UID = '510012001100004c30313356'
+PANEL_ID = 'PANEL_dtu_001_1'  # dtu_id=dtu_001 + 地址 1 派生,与 devices.json 的 addr 对齐
+
+PORT_MAPPINGS = {
+    PANEL_ID: {
+        '5': '112233445566',
+        '10': 'DDAD57F95001',
+        '1': None,  # 显式清除也要保留,不能被丢弃
+    },
+}
+
+
+class TestBackupPortMappings:
+    def setup_method(self):
+        self._saved_pm = app_module.dtu_config.get('port_mappings')
+        self._saved_devices = dict(app_module.address_config.stored_devices)
+
+    def teardown_method(self):
+        patch.stopall()
+        if self._saved_pm is None:
+            app_module.dtu_config.pop('port_mappings', None)
+        else:
+            app_module.dtu_config['port_mappings'] = self._saved_pm
+        app_module.address_config.stored_devices.clear()
+        app_module.address_config.stored_devices.update(self._saved_devices)
+
+    def test_export_contains_port_mappings(self):
+        """导出包的 dtu_config 必须携带 port_mappings(绑定②)。"""
+        dtu_on_disk = {
+            'dtu_id': 'dtu_001',
+            'address_range': {'start': 1, 'end': 5},
+            'port_mappings': PORT_MAPPINGS,
+        }
+
+        def fake_read(path):
+            if path == app_module.DTU_CONFIG_FILE:
+                return dtu_on_disk
+            if path == app_module.DEVICE_CONFIG_FILE:
+                return {UID: 1}
+            return None
+
+        with patch.object(app_module.config_backup, 'read_json_file', side_effect=fake_read), \
+                patch.object(app_module.os.path, 'exists', return_value=True), \
+                patch.object(app_module, '_read_system_env', return_value=None):
+            files = app_module._collect_backup_files()
+
+        assert files['dtu_config']['port_mappings'] == PORT_MAPPINGS
+        assert files['devices'] == {UID: 1}
+
+    def test_import_restores_port_mappings_and_keeps_panel_key(self):
+        """导入备份后 port_mappings 落内存并触发保存;panel_id 与恢复出的地址一致。"""
+        bundle = {
+            'files': {
+                'dtu_config': {
+                    'dtu_id': 'dtu_001',
+                    'address_range': {'start': 1, 'end': 5},
+                    'port_mappings': PORT_MAPPINGS,
+                },
+                'devices': {UID: 1},
+            }
+        }
+        with patch.object(app_module, 'save_dtu_config') as mock_save, \
+                patch.object(app_module, '_save_config_file', return_value=True), \
+                patch.object(app_module, 'sync_panel_config'):
+            summary = app_module._apply_backup_bundle(bundle)
+
+        assert 'dtu_config' in summary['applied']
+        assert 'devices' in summary['applied']
+        # 绑定②完整恢复(含 None 清除标记)
+        assert app_module.dtu_config['port_mappings'] == PORT_MAPPINGS
+        mock_save.assert_called()
+        # 绑定①恢复后,地址 1 派生出的 panel_id 正是 port_mappings 的键(换机后能对上)
+        assert app_module.address_config.stored_devices.get(UID) == 1
+        assert app_module._panel_id_for_address(1) == PANEL_ID

+ 248 - 163
backend/tests/test_modbus_rtu.py

@@ -1,16 +1,21 @@
-"""V4+ 带 UID 批量读卡协议 (modbus_rtu) 单元测试。
-
-协议 V4+ (地址段轮询/线架绑定):
-  请求 20B: [addr][0x03][0x00][0x02][0x00][0x48][12 字节 UID][CRC_L][CRC_H]
-    UID = 已绑定线架 UID;uid=None 时为 12 字节全 0(探测未绑定地址)
-  响应 161B: [addr][0x03][0x90][144 数据字节][12 字节 UID][CRC_L][CRC_H]
-    UID = 线架自身 UID(用于绑定)
-  每张卡 6 字节(硬件卡号,12 位十六进制); 无卡标记 = FF FF FF FF FF FF
-
-过渡期兼容: 旧固件 149B 响应(无 UID 字段)可解析但 panel_uid=None。
-
-注: 硬件通信固定 6 字节卡号;对 MQTT 的 8 字节(16 位) jumper_uid 适配在 app.py 边界完成
-    (前 4 位 DTU 号 + 后 12 位卡号),本测试只覆盖硬件通信层。
+"""V5 协议 (modbus_rtu) 单元测试。
+
+V5 (20261023) 相对 V4 的变化:
+  1. 取消广播发现/自动分配地址,地址由配置卡写入线架。
+  2. 地址查询握手(16 字节):
+       0x80 查询: [add][0x80][12 字节 UID][CRC_L][CRC_H]
+         - 已绑定地址 -> 携带绑定 UID;未绑定地址 -> 12 字节全 0
+       0x81 应答: [add][0x81][12 字节 UID][CRC_L][CRC_H](线架自身 UID)
+       0x82 确认: [add][0x82][12 字节 UID][CRC_L][CRC_H]
+       0x83 应答: [add][0x83][12 字节 UID][CRC_L][CRC_H]
+  3. 批量读卡回归标准 MODBUS 0x03(帧内不再带 UID):
+       请求 8B:   [add][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H]
+       响应 149B: [add][0x03][0x90][144 数据字节][CRC_L][CRC_H]
+       每张卡 6 字节;无卡标记 = FF FF FF FF FF FF
+  4. 配置地址状态: 发送 AA B7 00 07 80 00 00 FF 00 00 02 64 03,
+     应答 55 00 00 02 [ANTLIST] [ADDR] [XOR] 03。
+
+注: 过渡期兼容 V4 旧固件 161B 批量读响应(尾部多 12 字节 UID,UID 忽略)。
 """
 import sys
 import os
@@ -25,125 +30,231 @@ from modules.modbus_rtu import (  # noqa: E402
     calculate_crc16,
     verify_crc16,
     build_read_cards_request,
+    build_address_query_request,
+    parse_address_query_response,
+    build_address_confirm_request,
+    parse_address_confirm_response,
+    build_config_address_enter_frame,
+    parse_config_address_response,
     CARD_REG_ADDR,
     CARD_REG_QUANTITY,
     CARD_DATA_BYTES,
-    BYTES_PER_TAG,
     ANTENNA_COUNT,
     NO_TAG_BYTES,
     BULK_RESPONSE_LEN,
+    BULK_REQUEST_LEN,
     BULK_BYTE_COUNT,
-    ANTENNA_ADDRESSES,
-    READ_WITH_UID_REQUEST_LEN,
-    READ_WITH_UID_RESPONSE_LEN,
+    ADDRESS_FRAME_LEN,
     ZERO_UID,
+    CONFIG_ADDRESS_ENTER_FRAME,
+    ANTENNA_ADDRESSES,
 )
 
-# 协议文档示例 UID: 18 00 40 00 14 00 00 59 59 54 30 56
-PANEL_UID = bytes([0x18, 0x00, 0x40, 0x00, 0x14, 0x00, 0x00, 0x59, 0x59, 0x54, 0x30, 0x56])
+# 协议文档示例 UID: 51 00 12 00 11 00 00 4C 30 31 33 56
+PANEL_UID = bytes.fromhex('510012001100004c30313356')
+PANEL_UID_HEX = PANEL_UID.hex()
 
+# 文档示例帧
+DOC_QUERY_ZERO = bytes.fromhex('0180' + '00' * 12 + '5401')
+DOC_QUERY_RESP = bytes.fromhex('0181510012001100004c30313356d0d3')
+DOC_CONFIRM_REQ = bytes.fromhex('0182510012001100004c30313356d510')
+DOC_CONFIRM_RESP = bytes.fromhex('0183510012001100004c30313356d791')
+DOC_READ_REQ = bytes.fromhex('010300020048e43c')
+DOC_CONFIG_ENTER = bytes.fromhex('aab70007800000ff0000026403')
 
-def build_bulk_response(addr: int, tag_data: bytes, uid: bytes = PANEL_UID) -> bytes:
-    """构造合法的 161 字节 V4+ 批量读响应帧(带线架 UID)。"""
+
+def build_bulk_response(addr: int, tag_data: bytes) -> bytes:
+    """构造合法的 149 字节 V5 批量读响应帧。"""
     assert len(tag_data) == CARD_DATA_BYTES, f"tag_data 必须 {CARD_DATA_BYTES} 字节"
-    assert len(uid) == 12, "uid 必须 12 字节"
-    frame = bytes([addr, 0x03, BULK_BYTE_COUNT]) + tag_data + uid
+    frame = bytes([addr, 0x03, BULK_BYTE_COUNT]) + tag_data
     return frame + calculate_crc16(frame)
 
 
-def build_legacy_bulk_response(addr: int, tag_data: bytes) -> bytes:
-    """构造旧固件 149 字节响应帧(无 UID 字段)。"""
+def build_legacy_uid_bulk_response(addr: int, tag_data: bytes, uid: bytes = PANEL_UID) -> bytes:
+    """构造 V4 旧固件 161 字节响应帧(尾部多 12 字节 UID)。"""
     assert len(tag_data) == CARD_DATA_BYTES
-    frame = bytes([addr, 0x03, BULK_BYTE_COUNT]) + tag_data
+    assert len(uid) == 12
+    frame = bytes([addr, 0x03, BULK_BYTE_COUNT]) + tag_data + uid
     return frame + calculate_crc16(frame)
 
 
-def build_exception_response(addr: int, exception_code: int) -> bytes:
+def build_exception_response(addr: int, function_code: int, exception_code: int) -> bytes:
     """构造 Modbus 异常响应帧 (5 字节)。"""
-    frame = bytes([addr, 0x83, exception_code])
+    frame = bytes([addr, function_code | 0x80, exception_code])
     return frame + calculate_crc16(frame)
 
 
-class TestReadAllAntennaCards:
-    """V4 批量读解析。"""
+def build_config_response(antenna: int, addr: int, prefix: bytes = b'', suffix: bytes = b'') -> bytes:
+    """构造配置卡应答帧 55 00 00 02 ANTLIST ADDR XOR 03。"""
+    head = bytes([0x55, 0x00, 0x00, 0x02, antenna, addr])
+    xor = 0
+    for b in head:
+        xor ^= b
+    return prefix + head + bytes([xor, 0x03]) + suffix
+
+
+class TestAddressQueryProtocol:
+    """0x80 / 0x81 地址查询。"""
+
+    def test_build_query_zero_uid_matches_doc(self):
+        """未绑定地址探测: 01 80 + 12×00 + CRC(54 01)。"""
+        assert build_address_query_request(0x01, None) == DOC_QUERY_ZERO
+        assert build_address_query_request(0x01) == DOC_QUERY_ZERO
+
+    def test_build_query_with_uid(self):
+        frame = build_address_query_request(0x01, PANEL_UID_HEX)
+        assert len(frame) == ADDRESS_FRAME_LEN
+        assert frame[:2] == bytes([0x01, 0x80])
+        assert frame[2:14] == PANEL_UID
+        assert frame[14:] == calculate_crc16(frame[:14])
+
+    def test_parse_query_response_matches_doc(self):
+        result = parse_address_query_response(DOC_QUERY_RESP)
+        assert 'error' not in result
+        assert result['success'] is True
+        assert result['device_address'] == 0x01
+        assert result['uid'] == PANEL_UID_HEX
+
+    def test_parse_query_response_zero_uid_is_invalid(self):
+        frame = bytes([0x01, 0x81]) + ZERO_UID
+        result = parse_address_query_response(frame + calculate_crc16(frame))
+        assert result['success'] is True
+        assert result['uid'] is None
+
+    def test_parse_query_response_all_ff_uid_is_invalid(self):
+        frame = bytes([0x01, 0x81]) + b'\xff' * 12
+        result = parse_address_query_response(frame + calculate_crc16(frame))
+        assert result['uid'] is None
+
+    def test_parse_query_response_crc_failure(self):
+        bad = bytearray(DOC_QUERY_RESP)
+        bad[-1] ^= 0xFF
+        result = parse_address_query_response(bytes(bad))
+        assert 'error' in result
+        assert 'CRC' in result['error']
+
+    def test_parse_query_response_wrong_function_code(self):
+        frame = bytes([0x01, 0x82]) + PANEL_UID
+        result = parse_address_query_response(frame + calculate_crc16(frame))
+        assert 'error' in result
+
+    def test_parse_query_response_exception(self):
+        result = parse_address_query_response(build_exception_response(0x01, 0x80, 0x02))
+        assert 'error' in result
+
+    def test_parse_query_response_short(self):
+        assert 'error' in parse_address_query_response(b'')
+        assert 'error' in parse_address_query_response(DOC_QUERY_RESP[:8])
+
+
+class TestAddressConfirmProtocol:
+    """0x82 / 0x83 地址确认。"""
+
+    def test_build_confirm_matches_doc(self):
+        assert build_address_confirm_request(0x01, PANEL_UID_HEX) == DOC_CONFIRM_REQ
+
+    def test_parse_confirm_matches_doc(self):
+        result = parse_address_confirm_response(DOC_CONFIRM_RESP)
+        assert 'error' not in result
+        assert result['success'] is True
+        assert result['device_address'] == 0x01
+        assert result['uid'] == PANEL_UID_HEX
+
+    def test_parse_confirm_wrong_function_code(self):
+        frame = bytes([0x01, 0x81]) + PANEL_UID
+        result = parse_address_confirm_response(frame + calculate_crc16(frame))
+        assert 'error' in result
+
+
+class TestModbusClientAddressOps:
+    """ModbusRTUClient 的 0x80/0x82 客户端方法。"""
 
     def setup_method(self):
         self.client = ModbusRTUClient(MagicMock())
-
-    def _mock_response(self, response_bytes: bytes):
         self.client.serial.ser = MagicMock()
-        self.client.serial.send_and_wait.return_value = response_bytes
 
-    def test_request_frame_with_zero_uid(self):
-        """uid=None(探测): 20 字节请求,UID 段全 0。"""
-        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
-        self.client.read_all_antenna_cards(0x01)
+    def test_query_address_sends_doc_frame(self):
+        self.client.serial.send_and_wait.return_value = DOC_QUERY_RESP
+
+        result = self.client.query_address(0x01, uid=None)
 
+        assert 'error' not in result
+        assert result['uid'] == PANEL_UID_HEX
         sent = self.client.serial.send_and_wait.call_args[0][0]
-        assert len(sent) == READ_WITH_UID_REQUEST_LEN
-        assert sent[:6] == bytes([0x01, 0x03, 0x00, 0x02, 0x00, 0x48])
-        assert sent[6:18] == ZERO_UID
-        assert sent[18:] == calculate_crc16(sent[:18])
+        assert sent == DOC_QUERY_ZERO
+        assert self.client.serial.send_and_wait.call_args.kwargs['min_response_bytes'] == ADDRESS_FRAME_LEN
+
+    def test_confirm_address_sends_doc_frame(self):
+        self.client.serial.send_and_wait.return_value = DOC_CONFIRM_RESP
 
-    def test_request_frame_with_bound_uid(self):
-        """传入绑定 UID: 请求帧尾部携带该 UID。"""
-        self._mock_response(build_bulk_response(0x02, NO_TAG_BYTES * ANTENNA_COUNT))
-        self.client.read_all_antenna_cards(0x02, uid=PANEL_UID)
+        result = self.client.confirm_address(0x01, PANEL_UID_HEX)
 
+        assert 'error' not in result
+        assert result['uid'] == PANEL_UID_HEX
         sent = self.client.serial.send_and_wait.call_args[0][0]
-        assert len(sent) == READ_WITH_UID_REQUEST_LEN
-        assert sent[6:18] == PANEL_UID
-        assert sent[18:] == calculate_crc16(sent[:18])
+        assert sent == DOC_CONFIRM_REQ
 
-    def test_build_read_cards_request_helper(self):
-        assert build_read_cards_request(0x01) == build_read_cards_request(0x01, ZERO_UID)
-        with pytest.raises(ValueError):
-            build_read_cards_request(0x01, b'\x00' * 11)
+    def test_query_address_invalid_uid(self):
+        result = self.client.query_address(0x01, uid=b'\x00' * 11)
+        assert 'error' in result
 
-    def test_min_response_bytes_is_full_frame(self):
-        """必须要求完整 161 字节,避免截断。"""
-        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
-        self.client.read_all_antenna_cards(0x01)
+    def test_query_address_serial_not_connected(self):
+        self.client.serial.ser = None
+        assert 'error' in self.client.query_address(0x01)
 
-        kwargs = self.client.serial.send_and_wait.call_args.kwargs
-        assert kwargs.get('min_response_bytes') == READ_WITH_UID_RESPONSE_LEN
+    def test_query_address_timeout(self):
+        self.client.serial.send_and_wait.return_value = b''
+        result = self.client.query_address(0x01)
+        assert 'error' in result
 
-    def test_panel_uid_extracted(self):
-        """161B 响应中的线架自身 UID 必须被提取(用于绑定)。"""
-        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT, uid=PANEL_UID))
 
-        result = self.client.read_all_antenna_cards(0x01)
+class TestReadAllAntennaCards:
+    """V5 标准 MODBUS 0x03 批量读。"""
 
-        assert 'error' not in result
-        assert result['panel_uid'] == PANEL_UID.hex()
+    def setup_method(self):
+        self.client = ModbusRTUClient(MagicMock())
+        self.client.serial.ser = MagicMock()
 
-    def test_zero_uid_response_gives_none(self):
-        """响应的 UID 段全 0(无效) -> panel_uid=None。"""
-        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT, uid=ZERO_UID))
+    def _mock_response(self, response_bytes: bytes):
+        self.client.serial.send_and_wait.return_value = response_bytes
 
-        result = self.client.read_all_antenna_cards(0x01)
+    def test_request_frame_matches_doc(self):
+        """请求固定 8 字节: 01 03 00 02 00 48 E4 3C。"""
+        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
+        self.client.read_all_antenna_cards(0x01)
 
-        assert 'error' not in result
-        assert result['panel_uid'] is None
+        sent = self.client.serial.send_and_wait.call_args[0][0]
+        assert sent == DOC_READ_REQ
+        assert len(sent) == BULK_REQUEST_LEN
+        assert build_read_cards_request(0x01) == DOC_READ_REQ
+
+    def test_min_response_bytes_is_149(self):
+        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
+        self.client.read_all_antenna_cards(0x01)
 
-    def test_legacy_149_response_parsed_without_uid(self):
-        """过渡期: 旧固件 149B 响应可解析,但 panel_uid=None。"""
-        self._mock_response(build_legacy_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
+        kwargs = self.client.serial.send_and_wait.call_args.kwargs
+        assert kwargs.get('min_response_bytes') == BULK_RESPONSE_LEN
+
+    def test_no_panel_uid_in_v5_result(self):
+        """V5 读卡结果不再包含 panel_uid(UID 走 0x80 查询)。"""
+        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
+        result = self.client.read_all_antenna_cards(0x01)
+        assert 'error' not in result
+        assert 'panel_uid' not in result
 
+    def test_legacy_161_response_tolerated(self):
+        """过渡期: V4 旧固件 161B 响应仍可解析,UID 忽略。"""
+        self._mock_response(build_legacy_uid_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
         result = self.client.read_all_antenna_cards(0x01)
 
         assert 'error' not in result
-        assert result['panel_uid'] is None
         assert len(result['cards']) == ANTENNA_COUNT
+        assert 'panel_uid' not in result
 
     def test_no_tag_response(self):
-        """24 路全无卡 (FF*144)。"""
-        tag_data = NO_TAG_BYTES * ANTENNA_COUNT  # 144 字节 0xFF
-        self._mock_response(build_bulk_response(0x01, tag_data))
-
+        self._mock_response(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
         result = self.client.read_all_antenna_cards(0x01)
 
-        assert 'error' not in result
         assert result['success'] is True
         assert result['device_address'] == 0x01
         assert result['function_code'] == 0x03
@@ -155,39 +266,31 @@ class TestReadAllAntennaCards:
             assert card['uid'] == ''
 
     def test_tag_on_antenna_24(self):
-        """24 号天线有卡 ED9A57F95001,其余无卡。"""
         tag = bytes([0xED, 0x9A, 0x57, 0xF9, 0x50, 0x01])
-        tag_data = NO_TAG_BYTES * 23 + tag  # 138 + 6 = 144
+        tag_data = NO_TAG_BYTES * 23 + tag
         self._mock_response(build_bulk_response(0x03, tag_data))
 
         result = self.client.read_all_antenna_cards(0x03)
 
-        assert 'error' not in result
         cards = result['cards']
         assert len(cards) == 24
-        for i in range(23):
-            assert cards[i]['present'] is False
-        assert cards[23]['antenna'] == 24
+        assert all(not c['present'] for c in cards[:23])
         assert cards[23]['present'] is True
         assert cards[23]['card_str'] == 'ed9a57f95001'
         assert cards[23]['uid'] == 'ed:9a:57:f9:50:01'
 
     def test_tag_on_antenna_1(self):
-        """1 号天线有卡,其余无卡。"""
         tag = bytes([0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF])
-        tag_data = tag + NO_TAG_BYTES * 23
-        self._mock_response(build_bulk_response(0x01, tag_data))
+        self._mock_response(build_bulk_response(0x01, tag + NO_TAG_BYTES * 23))
 
         result = self.client.read_all_antenna_cards(0x01)
 
         assert result['cards'][0]['present'] is True
         assert result['cards'][0]['card_str'] == 'aabbccddeeff'
-        assert result['cards'][0]['uid'] == 'aa:bb:cc:dd:ee:ff'
         for i in range(1, 24):
             assert result['cards'][i]['present'] is False
 
     def test_multiple_tags(self):
-        """1/12/24 号天线同时有卡。"""
         tag1 = bytes([0x11, 0x22, 0x33, 0x44, 0x55, 0x66])
         tag12 = bytes([0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC])
         tag24 = bytes([0xDD, 0xEE, 0xFF, 0x00, 0x11, 0x22])
@@ -205,10 +308,9 @@ class TestReadAllAntennaCards:
         assert result['cards'][1]['present'] is False
 
     def test_crc_failure(self):
-        """CRC 篡改 -> error。"""
-        response = build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT)
-        response = response[:-1] + bytes([response[-1] ^ 0xFF])  # 改 CRC 末字节
-        self._mock_response(response)
+        response = bytearray(build_bulk_response(0x01, NO_TAG_BYTES * ANTENNA_COUNT))
+        response[-1] ^= 0xFF
+        self._mock_response(bytes(response))
 
         result = self.client.read_all_antenna_cards(0x01)
 
@@ -216,46 +318,27 @@ class TestReadAllAntennaCards:
         assert 'CRC' in result['error']
 
     def test_short_frame(self):
-        """截断响应 (<149) -> error。"""
         self._mock_response(bytes([0x01, 0x03, 0x90] + [0xFF] * 7))
-
-        result = self.client.read_all_antenna_cards(0x01)
-
-        assert 'error' in result
+        assert 'error' in self.client.read_all_antenna_cards(0x01)
 
     def test_exception_response(self):
-        """Modbus 异常帧 (0x83) -> error 含 exception。"""
-        self._mock_response(build_exception_response(0x01, 0x02))
-
+        self._mock_response(build_exception_response(0x01, 0x03, 0x02))
         result = self.client.read_all_antenna_cards(0x01)
-
         assert 'error' in result
         assert 'exception' in result['error'].lower()
 
     def test_unexpected_function_code(self):
-        """非 0x03 响应 -> error。"""
         frame = bytes([0x01, 0x04, BULK_BYTE_COUNT]) + NO_TAG_BYTES * ANTENNA_COUNT
         self._mock_response(frame + calculate_crc16(frame))
-
-        result = self.client.read_all_antenna_cards(0x01)
-
-        assert 'error' in result
+        assert 'error' in self.client.read_all_antenna_cards(0x01)
 
     def test_serial_not_connected(self):
-        """串口未连接 -> error。"""
         self.client.serial.ser = None
-
-        result = self.client.read_all_antenna_cards(0x01)
-
-        assert 'error' in result
+        assert 'error' in self.client.read_all_antenna_cards(0x01)
 
     def test_empty_response(self):
-        """空响应 -> error。"""
         self._mock_response(b'')
-
-        result = self.client.read_all_antenna_cards(0x01)
-
-        assert 'error' in result
+        assert 'error' in self.client.read_all_antenna_cards(0x01)
 
 
 class TestReadAntennaCardSingle:
@@ -267,8 +350,8 @@ class TestReadAntennaCardSingle:
 
     def test_extract_antenna_1_with_tag(self):
         tag = bytes([0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01])
-        tag_data = tag + NO_TAG_BYTES * 23
-        self.client.serial.send_and_wait.return_value = build_bulk_response(0x01, tag_data)
+        self.client.serial.send_and_wait.return_value = build_bulk_response(
+            0x01, tag + NO_TAG_BYTES * 23)
 
         result = self.client.read_antenna_card(0x01, 1)
 
@@ -280,41 +363,22 @@ class TestReadAntennaCardSingle:
         assert result['card_number_hex'] == f'0x{int.from_bytes(tag, "big"):012x}'
 
     def test_extract_antenna_no_tag(self):
-        """无卡时 card_number_str 为空串(V2 是 16 个 0)。"""
         self.client.serial.send_and_wait.return_value = build_bulk_response(
             0x01, NO_TAG_BYTES * 24)
 
         result = self.client.read_antenna_card(0x01, 5)
 
-        assert 'error' not in result
         assert result['antenna'] == 5
         assert result['card_number_str'] == ''
         assert result['uid'] == ''
 
-    def test_extract_antenna_24_with_tag(self):
-        tag = bytes([0xED, 0x9A, 0x57, 0xF9, 0x50, 0x01])
-        tag_data = NO_TAG_BYTES * 23 + tag
-        self.client.serial.send_and_wait.return_value = build_bulk_response(0x03, tag_data)
-
-        result = self.client.read_antenna_card(0x03, 24)
-
-        assert 'error' not in result
-        assert result['antenna'] == 24
-        assert result['card_number_str'] == 'ed9a57f95001'
-
     def test_invalid_antenna_number(self):
-        result = self.client.read_antenna_card(0x01, 25)
-        assert 'error' in result
-        result = self.client.read_antenna_card(0x01, 0)
-        assert 'error' in result
+        assert 'error' in self.client.read_antenna_card(0x01, 25)
+        assert 'error' in self.client.read_antenna_card(0x01, 0)
 
     def test_bulk_error_propagates(self):
-        """批量读失败时,单卡读透传 error。"""
         self.client.serial.send_and_wait.return_value = b''
-
-        result = self.client.read_antenna_card(0x01, 1)
-
-        assert 'error' in result
+        assert 'error' in self.client.read_antenna_card(0x01, 1)
 
     def test_does_not_send_v2_frame(self):
         """单卡读不得发 V2 逐天线帧 (0x0002+(n-1)*4)。"""
@@ -323,40 +387,61 @@ class TestReadAntennaCardSingle:
         self.client.read_antenna_card(0x01, 10)
 
         sent = self.client.serial.send_and_wait.call_args[0][0]
-        # 必须是 V4 批量帧 01 03 00 02 00 48 ...
-        assert sent[1] == 0x03
-        assert sent[2:4] == bytes([0x00, 0x02])
-        assert sent[4:6] == bytes([0x00, 0x48])
-        # V2 第 10 天线会是 0x0026,不得出现
+        assert sent == DOC_READ_REQ
         assert sent[2:4] != bytes([0x00, 0x26])
 
 
-class TestAntennaAddressesMapping:
-    """V4 天线地址映射。"""
+class TestConfigAddressProtocol:
+    """配置地址状态(刷配置卡设置地址)。"""
+
+    def test_enter_frame_matches_doc(self):
+        assert CONFIG_ADDRESS_ENTER_FRAME == DOC_CONFIG_ENTER
+        assert build_config_address_enter_frame() == DOC_CONFIG_ENTER
+        assert len(DOC_CONFIG_ENTER) == 13
+
+    def test_parse_response_with_garbage_prefix(self):
+        frame = build_config_response(antenna=3, addr=12)
+        result = parse_config_address_response(b'\x00\xff' + frame + b'\x99')
+        assert 'error' not in result
+        assert result['antenna'] == 3
+        assert result['address'] == 12
+        assert result['raw_data'] == frame.hex()
+
+    def test_parse_response_checks_xor(self):
+        frame = bytearray(build_config_response(antenna=1, addr=5))
+        frame[6] ^= 0xFF
+        result = parse_config_address_response(bytes(frame))
+        assert 'error' in result
+
+    def test_parse_response_rejects_bad_antenna(self):
+        assert 'error' in parse_config_address_response(build_config_response(0, 5))
+        assert 'error' in parse_config_address_response(build_config_response(25, 5))
 
+    def test_parse_response_short(self):
+        assert 'error' in parse_config_address_response(b'')
+        assert 'error' in parse_config_address_response(b'\x55\x00\x00\x02')
+
+
+class TestAntennaAddressesMapping:
     def test_all_antennas_share_card_register(self):
-        """V4 下所有天线共享 0x0002。"""
         for ant in range(1, 25):
             assert ANTENNA_ADDRESSES[ant] == CARD_REG_ADDR
-
-    def test_no_v2_per_antenna_addresses(self):
-        """不得残留 V2 的逐天线地址 (0x0006/0x000A/...)。"""
-        for ant in range(1, 25):
-            assert ANTENNA_ADDRESSES[ant] != 0x0002 + (ant - 1) * 4 or ant == 1
+        assert CARD_REG_QUANTITY == 0x48
+        assert CARD_DATA_BYTES == 144
 
 
 class TestCrcHelpers:
-    """CRC 辅助函数 (回归)。"""
-
     def test_request_crc_matches_doc(self):
         """文档示例请求帧 (01 03 00 02 00 48) CRC = E4 3C。"""
-        req = bytes([0x01, 0x03, 0x00, 0x02, 0x00, 0x48])
-        assert calculate_crc16(req) == bytes([0xE4, 0x3C])
+        assert calculate_crc16(bytes([0x01, 0x03, 0x00, 0x02, 0x00, 0x48])) == bytes([0xE4, 0x3C])
 
-    def test_no_tag_crc_is_not_doc_typo(self):
-        """无标签响应 CRC 实为 8F 44,文档的 C9 A2 是笔误。"""
-        frame = bytes([0x01, 0x03, 0x90]) + b'\xff' * 144
-        assert calculate_crc16(frame) == bytes([0x8F, 0x44])
+    def test_query_zero_uid_crc_matches_doc(self):
+        frame = bytes([0x01, 0x80]) + ZERO_UID
+        assert calculate_crc16(frame) == bytes([0x54, 0x01])
+
+    def test_confirm_crc_matches_doc(self):
+        frame = bytes([0x01, 0x82]) + PANEL_UID
+        assert calculate_crc16(frame) == bytes([0xD5, 0x10])
 
     def test_verify_crc16_valid_frame(self):
         frame = bytes([0x01, 0x03, 0x90]) + b'\xff' * 144

+ 292 - 34
backend/tests/test_panel_registration.py

@@ -1,6 +1,15 @@
-"""线架注册模型(地址段扫描 / UID 绑定 / 换架自动接管)单元测试。"""
+"""线架注册模型(80/81 口径:保活/两级绑定/换架接管/冲突防抢占)单元测试。
+
+图解口径(严格):
+  - 已绑定地址: 0x80 保活带绑定 UID -> 收到匹配 81 才在线
+  - 连续 PANEL_KEEPALIVE_MISS_LIMIT(=2) 次无匹配 81 -> 离线并停止 0x03 读卡
+  - 重新上线/换机/新注册: 先经 0x10 重下绑定②,再恢复读卡
+  - 同址不同 UID: 原机在线=冲突不替换;原机离线=自动换架接管
+  - 未绑定地址: 全 0 的 0x80 探测 -> 收到 81 本地建立绑定①(不发 82/83)
+"""
 import sys
 import os
+import time
 from unittest.mock import patch
 
 import pytest
@@ -25,10 +34,11 @@ def make_cards(port_map):
     return cards
 
 
-def read_result(cards, panel_uid=None):
+def read_result(cards, addr=1):
+    """V5 批量读结果(不再包含 panel_uid)。"""
     return {
-        'success': True, 'device_address': 1, 'function_code': 3,
-        'cards': cards, 'panel_uid': panel_uid, 'raw_data': 'TEST',
+        'success': True, 'device_address': addr, 'function_code': 3,
+        'cards': cards, 'raw_data': 'TEST',
     }
 
 
@@ -38,10 +48,13 @@ class TestPanelRegistration:
             'stored': dict(app_module.address_config.stored_devices),
             'panel_config': dict(app_module.panel_config),
             'port_state': dict(app_module.port_state),
-            'fail': dict(app_module.panel_fail_count),
+            'ka_miss': dict(app_module.panel_keepalive_miss),
+            'synced': set(app_module.panel_mappings_synced),
+            'conflict': dict(app_module.panel_conflict),
             'address_range': app_module.dtu_config.get('address_range'),
             'port_mappings': app_module.dtu_config.get('port_mappings'),
             'last_seen': dict(app_module.device_last_seen),
+            'config_addr': dict(app_module._panel_config_addr_state),
         }
         self.mock_modbus = patch.object(app_module, 'modbus_client').start()
         self.mock_save_dev = patch.object(app_module, 'save_device_config').start()
@@ -49,11 +62,19 @@ class TestPanelRegistration:
         self.mock_register = patch.object(app_module, 'dtu_register').start()
         self.mock_panel_status = patch.object(app_module, 'dtu_publish_panel_status').start()
 
+        # 读卡默认无卡;写卡默认成功(82/83 已废弃,自动流程不再调用 confirm_address)
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}))
+        self.mock_modbus.set_card_mapping.return_value = {'success': True}
+
         app_module.address_config.stored_devices.clear()
         app_module.panel_config.clear()
         app_module.port_state.clear()
-        app_module.panel_fail_count.clear()
+        app_module.panel_keepalive_miss.clear()
+        app_module.panel_mappings_synced.clear()
+        app_module.panel_conflict.clear()
         app_module.device_last_seen.clear()
+        app_module._panel_config_addr_state.update(
+            {'pending_address': None, 'pending_until': None})
 
     def teardown_method(self):
         patch.stopall()
@@ -63,10 +84,16 @@ class TestPanelRegistration:
         app_module.panel_config.update(self._saved['panel_config'])
         app_module.port_state.clear()
         app_module.port_state.update(self._saved['port_state'])
-        app_module.panel_fail_count.clear()
-        app_module.panel_fail_count.update(self._saved['fail'])
+        app_module.panel_keepalive_miss.clear()
+        app_module.panel_keepalive_miss.update(self._saved['ka_miss'])
+        app_module.panel_mappings_synced.clear()
+        app_module.panel_mappings_synced.update(self._saved['synced'])
+        app_module.panel_conflict.clear()
+        app_module.panel_conflict.update(self._saved['conflict'])
         app_module.device_last_seen.clear()
         app_module.device_last_seen.update(self._saved['last_seen'])
+        app_module._panel_config_addr_state.clear()
+        app_module._panel_config_addr_state.update(self._saved['config_addr'])
         if self._saved['address_range'] is None:
             app_module.dtu_config.pop('address_range', None)
         else:
@@ -76,8 +103,18 @@ class TestPanelRegistration:
         else:
             app_module.dtu_config['port_mappings'] = self._saved['port_mappings']
 
+    def _query_map(self, uid_by_addr):
+        """按地址返回 0x80 查询结果(不在 map 中的地址视为无应答)"""
+        def fake(addr, uid=None, timeout=None):
+            value = uid_by_addr.get(addr)
+            if value is None:
+                return {'error': 'response timeout or too short', 'raw_data': ''}
+            return {'success': True, 'device_address': addr, 'uid': value,
+                    'raw_data': 'TEST'}
+        self.mock_modbus.query_address.side_effect = fake
+
     def test_takeover_rebinds_uid_and_inherits_mappings(self):
-        """换架: 原地址探测到新 UID -> 重绑地址、保留 panel_id/映射、自动下发卡号。"""
+        """换架(原机离线): 81 回新 UID -> 重绑地址、保留 panel_id/映射;先 0x10 再读卡,不发 82。"""
         old_uid = 'a1' * 12
         new_uid = 'b2' * 12
         pid = 'PANEL_dtu_001_5'
@@ -85,11 +122,11 @@ class TestPanelRegistration:
         app_module.dtu_config['port_mappings'] = {pid: {'3': 'AABBCCDDEEFF'}}
         app_module.address_config.stored_devices[old_uid] = 5
         app_module.panel_config[pid] = {'address': 5, 'position': 5, 'panel_uid': old_uid, 'status': 'offline'}
-        app_module.panel_fail_count[pid] = 3
+        app_module.panel_keepalive_miss[pid] = 2
 
+        self._query_map({5: new_uid})
         self.mock_modbus.read_all_antenna_cards.return_value = read_result(
-            make_cards({3: 'aabbccddeeff'}), panel_uid=new_uid)
-        self.mock_modbus.set_card_mapping.return_value = {'success': True}
+            make_cards({3: 'aabbccddeeff'}), addr=5)
 
         app_module._sweep_panel_addresses()
 
@@ -98,76 +135,256 @@ class TestPanelRegistration:
         assert old_uid not in devices
         assert app_module.panel_config[pid]['panel_uid'] == new_uid
         assert app_module.panel_config[pid]['status'] == 'online'
-        assert pid not in app_module.panel_fail_count
-        # 期望卡号已下发到硬件(继承原面板数据)
+        assert pid not in app_module.panel_keepalive_miss
+        # 82/83 已废弃:自动接管不得发 confirm_address
+        assert self.mock_modbus.confirm_address.called is False
+        # 先 0x10 下发绑定②(继承原面板数据),再读卡
         args, _ = self.mock_modbus.set_card_mapping.call_args
         assert args[0] == 5
         assert args[1].get(3) == 'AABBCCDDEEFF'
+        assert self.mock_modbus.read_all_antenna_cards.called
         assert self.mock_save_dev.called
         assert self.mock_register.called
 
-    def test_probe_same_uid_marks_back_online(self):
-        """缺失探测回应原 UID -> 恢复在线,不改变绑定。"""
+    def test_healthy_query_same_uid_reads_cards(self):
+        """正常轮次: 「地址+绑定 UID」80 -> 匹配 81 -> 0x03 读卡,绑定不变,稳态不再重发 0x10。"""
+        uid = 'aa' * 12
+        pid = 'PANEL_dtu_001_6'
+        app_module.dtu_config['address_range'] = {'start': 6, 'end': 6}
+        app_module.address_config.stored_devices[uid] = 6
+        app_module.panel_config[pid] = {'address': 6, 'position': 6, 'panel_uid': uid, 'status': 'online'}
+        app_module.panel_mappings_synced.add(pid)  # 本会话已下发过绑定②
+
+        self._query_map({6: uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=6)
+
+        app_module._sweep_panel_addresses()
+
+        assert app_module.address_config.stored_devices == {uid: 6}
+        assert self.mock_modbus.confirm_address.called is False
+        assert self.mock_modbus.set_card_mapping.called is False  # 稳态在线不重发 0x10
+        assert self.mock_modbus.query_address.call_count == 1
+        query_args, query_kwargs = self.mock_modbus.query_address.call_args
+        assert query_args[0] == 6
+        assert query_kwargs.get('uid') == uid
+        assert self.mock_modbus.read_all_antenna_cards.called
+
+    def test_first_online_pushes_mapping_before_read(self):
+        """服务重启后首次匹配 81(cfg=online 但本会话未同步)-> 先 0x10 再读卡。"""
+        uid = 'ad' * 12
+        pid = 'PANEL_dtu_001_9'
+        app_module.dtu_config['address_range'] = {'start': 9, 'end': 9}
+        app_module.address_config.stored_devices[uid] = 9
+        app_module.panel_config[pid] = {'address': 9, 'position': 9, 'panel_uid': uid, 'status': 'online'}
+        app_module.dtu_config['port_mappings'] = {pid: {'1': '111111111111'}}
+
+        self._query_map({9: uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=9)
+
+        app_module._sweep_panel_addresses()
+
+        # 下发 0x10 与业务读卡都发生
+        assert self.mock_modbus.set_card_mapping.called
+        # 顺序:最后一次 set_card_mapping(0x10) 在最后一次业务 read(0x03) 之前
+        # (_hardware_card_base 取硬件基底的那次 read 不计,它在 set_card_mapping 之前)
+        names = [c[0] for c in self.mock_modbus.method_calls]
+        last_set = len(names) - 1 - names[::-1].index('set_card_mapping')
+        last_read = len(names) - 1 - names[::-1].index('read_all_antenna_cards')
+        assert last_set > names.index('read_all_antenna_cards')
+        assert last_set < last_read
+
+    def test_one_miss_still_reads_two_miss_offline_stops_read(self):
+        """81 口径:第1次无81仍读卡并计1;连续第2次无81判离线、停止读卡。"""
+        uid = 'ab' * 12
+        pid = 'PANEL_dtu_001_7'
+        app_module.dtu_config['address_range'] = {'start': 7, 'end': 7}
+        app_module.address_config.stored_devices[uid] = 7
+        app_module.panel_config[pid] = {'address': 7, 'position': 7, 'panel_uid': uid, 'status': 'online'}
+        app_module.panel_mappings_synced.add(pid)
+
+        self.mock_modbus.query_address.return_value = {
+            'error': 'response timeout or too short', 'raw_data': ''}
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=7)
+
+        # 第 1 次:仍在线,本轮仍读卡,计数=1
+        app_module._sweep_panel_addresses()
+        assert app_module.panel_keepalive_miss[pid] == 1
+        assert app_module.panel_config[pid]['status'] == 'online'
+        assert self.mock_modbus.read_all_antenna_cards.call_count == 1
+
+        # 第 2 次:判离线,停止读卡(读卡调用数不再增加)
+        app_module._sweep_panel_addresses()
+        assert app_module.panel_config[pid]['status'] == 'offline'
+        assert self.mock_modbus.read_all_antenna_cards.call_count == 1
+        self.mock_panel_status.assert_any_call(pid, 7, None, online=False)
+
+    def test_offline_keeps_polling_80_but_never_reads(self):
+        """已离线机:继续发带 UID 的 80 探测恢复,但在收到匹配 81 前不再读卡。"""
+        uid = 'ae' * 12
+        pid = 'PANEL_dtu_001_10'
+        app_module.dtu_config['address_range'] = {'start': 10, 'end': 10}
+        app_module.address_config.stored_devices[uid] = 10
+        app_module.panel_config[pid] = {'address': 10, 'position': 10, 'panel_uid': uid, 'status': 'offline'}
+        app_module.panel_keepalive_miss[pid] = 2
+
+        self.mock_modbus.query_address.return_value = {'error': 'timeout', 'raw_data': ''}
+        app_module._sweep_panel_addresses()
+
+        assert self.mock_modbus.query_address.call_count == 1
+        assert self.mock_modbus.query_address.call_args.kwargs.get('uid') == uid
+        assert self.mock_modbus.read_all_antenna_cards.called is False
+        assert app_module.panel_config[pid]['status'] == 'offline'
+
+    def test_recovery_pushes_mapping_then_reads(self):
+        """离线后重新收到匹配 81 -> 恢复在线;先 0x10 重下绑定②再读卡,查询仍带绑定 UID。"""
         uid = 'c3' * 12
         pid = 'PANEL_dtu_001_2'
         app_module.dtu_config['address_range'] = {'start': 2, 'end': 2}
+        app_module.dtu_config['port_mappings'] = {pid: {'2': '222222222222'}}
         app_module.address_config.stored_devices[uid] = 2
         app_module.panel_config[pid] = {'address': 2, 'position': 2, 'panel_uid': uid, 'status': 'offline'}
-        app_module.panel_fail_count[pid] = 3
+        app_module.panel_keepalive_miss[pid] = 2
 
-        self.mock_modbus.read_all_antenna_cards.return_value = read_result(
-            make_cards({}), panel_uid=uid)
+        self._query_map({2: uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=2)
 
         app_module._sweep_panel_addresses()
 
         assert app_module.address_config.stored_devices == {uid: 2}
         assert app_module.panel_config[pid]['status'] == 'online'
-        assert pid not in app_module.panel_fail_count
-
-    def test_unbound_probe_registers_new_panel(self):
-        """未绑定地址探测到新线架 -> 绑定地址↔UID。"""
+        assert pid not in app_module.panel_keepalive_miss
+        assert self.mock_modbus.query_address.call_count == 1
+        assert self.mock_modbus.query_address.call_args.kwargs.get('uid') == uid
+        # 重新上线先 0x10 再业务读卡(基底 read 不计)
+        names = [c[0] for c in self.mock_modbus.method_calls]
+        last_set = len(names) - 1 - names[::-1].index('set_card_mapping')
+        last_read = len(names) - 1 - names[::-1].index('read_all_antenna_cards')
+        assert last_set > names.index('read_all_antenna_cards')
+        assert last_set < last_read
+
+    def test_unbound_probe_registers_new_panel_without_confirm(self):
+        """未绑定地址全 0 探测收到 81 -> 本地建立绑定①并上线;不发 82,先 0x10 再读卡。"""
         new_uid = 'd4' * 12
         app_module.dtu_config['address_range'] = {'start': 4, 'end': 4}
-        self.mock_modbus.read_all_antenna_cards.return_value = read_result(
-            make_cards({}), panel_uid=new_uid)
+        self._query_map({4: new_uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=4)
 
         app_module._sweep_panel_addresses()
 
         assert app_module.address_config.stored_devices.get(new_uid) == 4
         assert 'PANEL_dtu_001_4' in app_module.panel_config
+        assert self.mock_modbus.confirm_address.called is False
+        # 注册时探测用全 0
+        assert self.mock_modbus.query_address.call_args.kwargs.get('uid') is None
         assert self.mock_save_dev.called
 
-    def test_missing_panel_suspends_unbound_probe(self):
-        """有面板处于缺失/接管状态时,本轮不抽查未绑定地址。"""
+    def test_offline_panel_still_probes_unbound(self):
+        """即使有绑定线架离线,地址段内未绑定地址仍照常全 0 顺序探测。"""
         old_uid = 'e5' * 12
         pid = 'PANEL_dtu_001_2'
         app_module.dtu_config['address_range'] = {'start': 2, 'end': 3}
         app_module.address_config.stored_devices[old_uid] = 2
         app_module.panel_config[pid] = {'address': 2, 'position': 2, 'panel_uid': old_uid, 'status': 'offline'}
-        app_module.panel_fail_count[pid] = 1
+        app_module.panel_keepalive_miss[pid] = 2
+        self._query_map({})  # 所有地址无应答
         self.mock_modbus.read_all_antenna_cards.return_value = {'error': 'timeout'}
 
         app_module._sweep_panel_addresses()
 
-        probed = [c.args[0] for c in self.mock_modbus.read_all_antenna_cards.call_args_list]
-        assert probed == [2]
+        probed = [c.args[0] for c in self.mock_modbus.query_address.call_args_list]
+        # 绑定地址 2 带 UID 查询,未绑定地址 3 也必须探测(顺序 2、3)
+        assert probed == [2, 3]
+        assert self.mock_modbus.query_address.call_args_list[0].kwargs.get('uid') == old_uid
+        assert self.mock_modbus.query_address.call_args_list[1].kwargs.get('uid') is None
+        # 离线机不读卡
+        assert self.mock_modbus.read_all_antenna_cards.called is False
 
-    def test_read_failure_threshold_marks_offline(self):
-        """连续失败达到阈值 -> 标记离线(并发布离线状态)。"""
+    def test_keepalive_miss_limit_marks_offline(self):
+        """连续 PANEL_KEEPALIVE_MISS_LIMIT 次无匹配 81 -> 离线并发布离线状态。"""
         uid = 'f6' * 12
         pid = 'PANEL_dtu_001_3'
         app_module.dtu_config['address_range'] = {'start': 3, 'end': 3}
         app_module.address_config.stored_devices[uid] = 3
         app_module.panel_config[pid] = {'address': 3, 'position': 3, 'panel_uid': uid, 'status': 'online'}
+        app_module.panel_mappings_synced.add(pid)
+        self.mock_modbus.query_address.return_value = {'error': 'timeout'}
         self.mock_modbus.read_all_antenna_cards.return_value = {'error': 'timeout'}
 
-        for _ in range(app_module.PANEL_MISS_THRESHOLD):
+        for _ in range(app_module.PANEL_KEEPALIVE_MISS_LIMIT):
             app_module._sweep_panel_addresses()
 
         assert app_module.panel_config[pid]['status'] == 'offline'
-        assert app_module.panel_fail_count[pid] == app_module.PANEL_MISS_THRESHOLD
+        assert app_module.panel_keepalive_miss[pid] == app_module.PANEL_KEEPALIVE_MISS_LIMIT
         self.mock_panel_status.assert_any_call(pid, 3, None, online=False)
 
+    def test_conflict_does_not_replace_while_old_online(self):
+        """原机仍在线(首次探测到不同 UID,原机未离线)-> 冲突:不替换/不下发/不读卡。"""
+        old_uid = '11' * 12
+        new_uid = '22' * 12
+        pid = 'PANEL_dtu_001_11'
+        app_module.dtu_config['address_range'] = {'start': 11, 'end': 11}
+        app_module.address_config.stored_devices[old_uid] = 11
+        app_module.panel_config[pid] = {'address': 11, 'position': 11, 'panel_uid': old_uid, 'status': 'online'}
+        app_module.dtu_config['port_mappings'] = {pid: {'1': '333333333333'}}
+
+        self._query_map({11: new_uid})  # 同地址回了不同 UID,原机计数=0(仍在线)
+        app_module._sweep_panel_addresses()
+
+        # 绑定①不变
+        assert app_module.address_config.stored_devices.get(old_uid) == 11
+        assert new_uid not in app_module.address_config.stored_devices
+        assert app_module.panel_config[pid]['panel_uid'] == old_uid
+        # 记冲突
+        assert app_module.panel_conflict.get(pid) == new_uid
+        # 不下发绑定②、不读卡
+        assert self.mock_modbus.set_card_mapping.called is False
+        assert self.mock_modbus.read_all_antenna_cards.called is False
+        assert app_module.panel_keepalive_miss[pid] == 1
+
+    def test_conflict_then_old_offline_triggers_takeover(self):
+        """冲突中:新 UID 持续应答、原机连续2次无匹配81 -> 第2次离线后立即接管新 UID。"""
+        old_uid = '44' * 12
+        new_uid = '55' * 12
+        pid = 'PANEL_dtu_001_12'
+        app_module.dtu_config['address_range'] = {'start': 12, 'end': 12}
+        app_module.address_config.stored_devices[old_uid] = 12
+        app_module.panel_config[pid] = {'address': 12, 'position': 12, 'panel_uid': old_uid, 'status': 'online'}
+        app_module.dtu_config['port_mappings'] = {pid: {'1': '666666666666'}}
+
+        self._query_map({12: new_uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=12)
+
+        app_module._sweep_panel_addresses()  # 第1次:冲突,原机 miss=1
+        assert app_module.panel_config[pid]['panel_uid'] == old_uid
+        app_module._sweep_panel_addresses()  # 第2次:原机离线 -> 接管新 UID
+
+        assert app_module.address_config.stored_devices.get(new_uid) == 12
+        assert old_uid not in app_module.address_config.stored_devices
+        assert app_module.panel_config[pid]['panel_uid'] == new_uid
+        assert app_module.panel_config[pid]['status'] == 'online'
+        assert pid not in app_module.panel_conflict
+        assert self.mock_modbus.set_card_mapping.called  # 接管先 0x10
+
+    def test_pending_config_address_probed_even_when_offline(self):
+        """配置地址后的新地址优先全 0 探测(即使有其他绑定线架离线)。"""
+        old_uid = 'e6' * 12
+        new_uid = 'f7' * 12
+        pid = 'PANEL_dtu_001_2'
+        app_module.dtu_config['address_range'] = {'start': 2, 'end': 8}
+        app_module.address_config.stored_devices[old_uid] = 2
+        app_module.panel_config[pid] = {'address': 2, 'position': 2, 'panel_uid': old_uid, 'status': 'offline'}
+        app_module.panel_keepalive_miss[pid] = 2
+        app_module._panel_config_addr_state['pending_address'] = 8
+        app_module._panel_config_addr_state['pending_until'] = time.time() + 60
+
+        self._query_map({8: new_uid})
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=8)
+
+        app_module._sweep_panel_addresses()
+
+        assert app_module.address_config.stored_devices.get(new_uid) == 8
+        assert app_module._panel_config_addr_state['pending_address'] is None
+
     def test_panel_unbind_api(self):
         """解绑 API: 移除绑定与面板配置。"""
         client = app.test_client()
@@ -184,6 +401,47 @@ class TestPanelRegistration:
         assert pid not in app_module.panel_config
         assert self.mock_save_dev.called
 
+    def test_query_address_api(self):
+        """V5 查询 API: 返回线架 UID 与原始帧。"""
+        client = app.test_client()
+        self.mock_modbus.query_address.return_value = {
+            'success': True, 'device_address': 5, 'uid': 'aa' * 12, 'raw_data': 'TEST'}
+        with patch.object(app_module, '_serial_connected', return_value=True):
+            resp = client.post('/api/modbus/query_address', json={'address': 5})
+        data = resp.get_json()
+        assert resp.status_code == 200
+        assert data['success'] is True
+        assert data['uid'] == 'aa' * 12
+        assert self.mock_modbus.query_address.call_args[0][0] == 5
+
+    def test_confirm_address_api_bind(self):
+        """V5 确认 API: bind=true 时同时写入本地绑定表。"""
+        client = app.test_client()
+        uid = 'ab' * 12
+        self.mock_modbus.confirm_address.return_value = {'success': True, 'uid': uid, 'raw_data': 'TEST'}
+        with patch.object(app_module, '_serial_connected', return_value=True):
+            resp = client.post('/api/modbus/confirm_address',
+                               json={'address': 6, 'uid': uid, 'bind': True})
+        data = resp.get_json()
+        assert resp.status_code == 200 and data['success'] is True
+        assert app_module.address_config.stored_devices.get(uid) == 6
+        assert self.mock_save_dev.called
+
+    def test_config_address_api_requires_serial(self):
+        """串口未连接时配置地址接口返回 400。"""
+        client = app.test_client()
+        with patch.object(app_module, '_serial_connected', return_value=False):
+            resp = client.post('/api/panel/config_address', json={})
+        assert resp.status_code == 400
+        assert resp.get_json()['success'] is False
+
+    def test_config_address_status_api(self):
+        client = app.test_client()
+        resp = client.get('/api/panel/config_address_status')
+        data = resp.get_json()
+        assert resp.status_code == 200 and data['success'] is True
+        assert 'config' in data
+
     def test_update_dtu_config_address_range(self):
         """DTU 配置 API: 地址段写入并校验。"""
         client = app.test_client()

+ 11 - 3
frontend/src/api/apiService.js

@@ -77,8 +77,10 @@ const apiService = {
       return apiClient.get('/modbus/led_status', { params })
     },
     scan: (params) => apiClient.post('/modbus/scan', params),
-    broadcastQuery: (params) => apiClient.post('/modbus/broadcast_query', params),
-    autoConfigure: (params) => apiClient.post('/modbus/auto_configure', params),
+    // V5 地址查询(0x80)/ 确认(0x82)
+    queryAddress: (params) => apiClient.post('/modbus/query_address', params),
+    confirmAddress: (params) => apiClient.post('/modbus/confirm_address', params),
+    confirmDevices: () => apiClient.post('/modbus/confirm_devices'),
     getStoredDevices: () => apiClient.get('/modbus/stored_devices'),
     addStoredDevice: (params) => apiClient.post('/modbus/stored_devices', params),
   },
@@ -146,7 +148,13 @@ const apiService = {
     scan: () => apiClient.post('/panel/scan'),
 
     // 查询扫描进度/结果
-    getScanStatus: () => apiClient.get('/panel/scan_status')
+    getScanStatus: () => apiClient.get('/panel/scan_status'),
+
+    // 让线架进入"配置地址状态"(刷配置卡设置地址)
+    configAddress: (params) => apiClient.post('/panel/config_address', params),
+
+    // 查询配置地址进度/结果
+    getConfigAddressStatus: () => apiClient.get('/panel/config_address_status')
   },
 
   // 运行数据备份/恢复API

+ 190 - 2
frontend/src/views/PanelManage.vue

@@ -37,6 +37,9 @@
                 <a-button size="small" :loading="loading" @click="refreshData">
                   <reload-outlined /> 刷新
                 </a-button>
+                <a-button size="small" @click="openConfigAddress">
+                  <setting-outlined /> 配置地址
+                </a-button>
                 <a-button size="small" type="primary" :loading="scanning" @click="scanNewPanels">
                   <search-outlined /> 扫描新线架
                 </a-button>
@@ -48,7 +51,7 @@
             show-icon
             style="margin-top: 12px"
             message="线架注册说明"
-            description="DTU 顺序轮询地址段内的地址:已绑定线架带 UID 查询;未绑定地址自动探测,新线架接入后会采纳该地址并自动绑定。更换单台线架时,新线架自动接管原地址并继承全部端口映射数据,无需重新匹配。删除绑定仅解除注册;线架若仍在总线上,下一轮扫描会重新绑定。"
+            description="DTU 按地址段定时查询:已绑定地址带线架 UID 查询(同时作为保活),未绑定地址用 UID 全 0 探测;线架不会自动分配地址,新线架地址需现场刷配置卡设置(点「配置地址」)。换架时新线架自动接管原地址并继承全部端口映射数据,无需重新匹配。删除绑定仅解除注册;线架若仍在总线上,下一轮扫描会重新绑定。"
           />
         </a-card>
       </a-col>
@@ -97,13 +100,76 @@
         </a-card>
       </a-col>
     </a-row>
+
+    <!-- 配置地址(刷配置卡设置线架地址) -->
+    <a-modal
+      v-model:open="configModalOpen"
+      title="配置线架地址"
+      :footer="null"
+      width="640px"
+      @cancel="closeConfigAddress"
+    >
+      <a-alert
+        type="warning"
+        show-icon
+        style="margin-bottom: 16px"
+        message="一次只能配置一台线架"
+        description="发送指令后,地址段轮询会暂停,线架进入「配置地址状态」;请把配置卡放到目标线架的天线上完成地址设置,线架回复新地址后自动恢复轮询并尝试注册。"
+      />
+      <a-steps
+        size="small"
+        direction="vertical"
+        :current="configStep"
+        style="margin-bottom: 16px"
+      >
+        <a-step title="发送配置地址指令" description="点击下方按钮,DTU 会广播让线架进入配置地址状态" />
+        <a-step title="刷配置卡" description="把配置卡放到目标线架的天线上,线架读取后回复天线号与新地址" />
+        <a-step title="自动注册" description="DTU 收到应答后探测新地址并完成绑定(换架自动接管原映射)" />
+      </a-steps>
+      <a-descriptions bordered size="small" :column="1" style="margin-bottom: 16px">
+        <a-descriptions-item label="状态">
+          <a-tag :color="configStatusColor">{{ configStatusText }}</a-tag>
+          <span v-if="configStatus.timeout" style="margin-left: 8px; color: #999">
+            超时 {{ configStatus.timeout }}s
+          </span>
+        </a-descriptions-item>
+        <a-descriptions-item label="读取天线">
+          {{ configStatus.antenna != null ? configStatus.antenna : '--' }}
+        </a-descriptions-item>
+        <a-descriptions-item label="新地址">
+          {{ configStatus.address != null ? configStatus.address : '--' }}
+        </a-descriptions-item>
+        <a-descriptions-item v-if="configStatus.error" label="错误">
+          <span style="color: #cf1322">{{ configStatus.error }}</span>
+        </a-descriptions-item>
+        <a-descriptions-item v-if="configStatus.raw" label="原始应答">
+          <span class="mono">{{ configStatus.raw }}</span>
+        </a-descriptions-item>
+      </a-descriptions>
+      <a-space>
+        <a-button
+          type="primary"
+          :loading="configStarting || configRunning"
+          :disabled="configRunning"
+          @click="startConfigAddress"
+        >
+          {{ configRunning ? '等待刷配置卡...' : '开始配置地址' }}
+        </a-button>
+        <a-button @click="closeConfigAddress">关闭</a-button>
+      </a-space>
+    </a-modal>
   </div>
 </template>
 
 <script setup>
 import { ref, computed, onMounted, onUnmounted } from 'vue'
 import { message } from 'ant-design-vue'
-import { ReloadOutlined, SearchOutlined, QuestionCircleOutlined } from '@ant-design/icons-vue'
+import {
+  ReloadOutlined,
+  SearchOutlined,
+  QuestionCircleOutlined,
+  SettingOutlined
+} from '@ant-design/icons-vue'
 import apiService from '../api/apiService'
 
 const loading = ref(false)
@@ -113,6 +179,22 @@ const addressRange = ref({ start: 1, end: 50 })
 const lastUpdate = ref('')
 let pollTimer = null
 
+// 配置地址(刷配置卡)
+const configModalOpen = ref(false)
+const configStarting = ref(false)
+const configRunning = ref(false)
+const configStatus = ref({
+  running: false,
+  started_at: null,
+  finished_at: null,
+  timeout: null,
+  antenna: null,
+  address: null,
+  raw: '',
+  error: null
+})
+let configPollTimer = null
+
 const columns = [
   { title: '地址', key: 'address', width: 80 },
   { title: '面板ID', dataIndex: 'panel_id', key: 'panel_id', width: 200 },
@@ -127,6 +209,30 @@ const onlineCount = computed(() => panels.value.filter(p => p.status === 'online
 const missingCount = computed(() => panels.value.filter(p => p.status === 'missing').length)
 const offlineCount = computed(() => panels.value.filter(p => p.status === 'offline').length)
 
+const configStep = computed(() => {
+  const st = configStatus.value
+  if (st.address != null) return 3
+  if (st.running) return 1
+  return 0
+})
+
+const configStatusText = computed(() => {
+  const st = configStatus.value
+  if (st.running) return '等待刷配置卡'
+  if (st.address != null) return '配置成功'
+  if (st.error) return '失败'
+  if (st.finished_at) return '已结束'
+  return '未开始'
+})
+
+const configStatusColor = computed(() => {
+  const st = configStatus.value
+  if (st.running) return 'processing'
+  if (st.address != null) return 'green'
+  if (st.error) return 'red'
+  return 'default'
+})
+
 function statusLabel(status) {
   return { online: '在线', missing: '缺失待接管', offline: '离线' }[status] || status
 }
@@ -200,6 +306,87 @@ async function scanNewPanels() {
   }
 }
 
+async function openConfigAddress() {
+  configModalOpen.value = true
+  try {
+    const res = await apiService.panel.getConfigAddressStatus()
+    if (res.data.success) {
+      configStatus.value = res.data.config || configStatus.value
+      configRunning.value = !!configStatus.value.running
+      if (configRunning.value) startConfigPolling(true)
+    }
+  } catch (e) {
+    console.error('get config address status error:', e)
+  }
+}
+
+function startConfigPolling(silent = false) {
+  if (configPollTimer) return
+  if (!silent) configRunning.value = true
+  configPollTimer = setInterval(pollConfigStatus, 1000)
+}
+
+async function pollConfigStatus() {
+  try {
+    const res = await apiService.panel.getConfigAddressStatus()
+    if (!res.data.success) return
+    configStatus.value = res.data.config || {}
+    configRunning.value = !!configStatus.value.running
+    if (!configRunning.value) {
+      stopConfigPolling()
+      if (configStatus.value.address != null) {
+        message.success(`配置成功:天线 ${configStatus.value.antenna} → 地址 ${configStatus.value.address}`)
+        await refreshData()
+      } else if (configStatus.value.error) {
+        message.error(configStatus.value.error)
+      }
+    }
+  } catch (e) {
+    console.error('poll config address status error:', e)
+  }
+}
+
+function stopConfigPolling() {
+  if (configPollTimer) {
+    clearInterval(configPollTimer)
+    configPollTimer = null
+  }
+  configRunning.value = false
+}
+
+async function startConfigAddress() {
+  configStarting.value = true
+  try {
+    const res = await apiService.panel.configAddress({ timeout: 60 })
+    if (!res.data.success) {
+      message.warning(res.data.message || '发送配置地址指令失败')
+      return
+    }
+    message.info(res.data.message || '已发送配置地址指令,请刷配置卡')
+    configStatus.value = {
+      running: true,
+      timeout: res.data.timeout,
+      antenna: null,
+      address: null,
+      raw: '',
+      error: null
+    }
+    startConfigPolling()
+  } catch (e) {
+    message.error(
+      (e.response && e.response.data && e.response.data.message) || '发送配置地址指令失败,请检查串口连接'
+    )
+  } finally {
+    configStarting.value = false
+  }
+}
+
+function closeConfigAddress() {
+  configModalOpen.value = false
+  // 若仍在等待线架应答,后台继续轮询,结束后仍会提示结果
+  if (!configRunning.value) stopConfigPolling()
+}
+
 async function unbindPanel(record) {
   try {
     const res = await apiService.panel.unbind({ address: record.address })
@@ -221,6 +408,7 @@ onMounted(async () => {
 
 onUnmounted(() => {
   if (pollTimer) clearInterval(pollTimer)
+  if (configPollTimer) clearInterval(configPollTimer)
 })
 </script>
 

Неке датотеке нису приказане због велике количине промена