Quellcode durchsuchen

新增读卡兜底兼容:81缺失时0x03有应答仍判在线

- config新增PANEL_READ_FALLBACK_KEEPALIVE(默认true,env同名)
- 81连续缺失将判离线/已离线等恢复时,先补发0x03读卡:成功判在线并清计数
  (离线恢复仍先0x10重下绑定②),读卡也失败才判离线;不同UID的81仍按严格冲突
- 置false即回纯图解口径(在线完全由80/81决定)
- 新增兼容模式用例,严格用例显式关闭开关,共145测试通过
wenhongquan vor 2 Wochen
Ursprung
Commit
1e036ff69f
4 geänderte Dateien mit 106 neuen und 9 gelöschten Zeilen
  1. 6 4
      AGENTS.md
  2. 40 1
      backend/app.py
  3. 6 0
      backend/config.py
  4. 54 4
      backend/tests/test_panel_registration.py

+ 6 - 4
AGENTS.md

@@ -40,7 +40,8 @@
 - **部署**:代码 `/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。
+- **2026-10-29 19:11 部署读卡兜底兼容版**:在严格图解版基础上加 `config.py` `PANEL_READ_FALLBACK_KEEPALIVE`(默认 true);备份 `app.py.bak_20261029_191143`(config 同名)。
+- **现网状态(19:13 后)**:现场网页先进入「配置地址」、又调 `POST /api/panel/unbind` 把绑定清空(`devices.json={}`);随后 pyserial 绕过 App 直发原始帧,地址 1 的 80 探测/03 读卡**均 0 字节回包**、地址 2–5 也全超时——`/dev/ttyUSB0` connected、CH340 在、能发不能收,判为**物理层/线架侧无响应**(线架断电/485 A-B 松脱或接反/停在配置地址态)。线架恢复应答后未绑定全 0 探测会自动重新注册。
 
 ### 串口屏(Nextion)接线与刷新(2026-10-10 重点)
 
@@ -312,9 +313,10 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 
 - ⚠️ **新线架地址必须刷配置卡设置**(管理页「配置地址」),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 的固件需升级固件才能在线)
+- ⚠️ 需线架固件支持:0x80/0x81 保活(**含对「带绑定 UID 的 0x80」回应匹配 81**)+ 配置地址广播应答(`55 ... 03`)。**现网这批固件不回带 UID 的 81,靠兼容开关救活(见下)**;纯图解严格口径需升级固件。
+- 🔧 **读卡兜底兼容开关**(`config.py` `PANEL_READ_FALLBACK_KEEPALIVE`,环境变量同名,**默认 true**):开启后,81 连续缺失即将判离线 / 已离线等恢复时,**先补发一次 0x03 读卡探测——读卡有应答即判在线并清零保活计数(离线恢复时仍先经 0x10 重下绑定②),读卡也无应答才判/维持离线**。这样现网「不回带 UID 81、但读卡正常」的固件可正常在线;同地址回**不同 UID 的 81 仍按严格冲突处理**(不做读卡兜底)。将来固件支持点名 81 后,置 false 即回到纯图解口径(在线完全由 80/81 决定)。
 - 绑定之外的地址(超地址段)如有绑定仍会轮询,但不再探测新地址
-- 相关常量:`config.py` 的 `DEFAULT_ADDRESS_RANGE` / `PANEL_KEEPALIVE_MISS_LIMIT`(=2) / `PANEL_PROBE_TIMEOUT` / `PANEL_QUERY_TIMEOUT` / `PANEL_READ_TIMEOUT` / `PANEL_CONFIG_ADDRESS_TIMEOUT`
+- 相关常量:`config.py` 的 `DEFAULT_ADDRESS_RANGE` / `PANEL_KEEPALIVE_MISS_LIMIT`(=2) / `PANEL_READ_FALLBACK_KEEPALIVE`(默认 true,读卡兜底兼容) / `PANEL_PROBE_TIMEOUT` / `PANEL_QUERY_TIMEOUT` / `PANEL_READ_TIMEOUT` / `PANEL_CONFIG_ADDRESS_TIMEOUT`
 
 ## 运行数据备份 / 恢复(2026-10-13)
 
@@ -363,7 +365,7 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 | 换架后未自动接管             | 严格图解口径:必须**原机先连续 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 已验证可通) |
+| 线架不回带 UID 的 81 | 默认开启读卡兜底(`PANEL_READ_FALLBACK_KEEPALIVE=true`):81 连续缺失时补发 0x03 读卡,**读卡有应答即判在线**,故现网这批只回全 0 探测、不回点名 81 但读卡正常的固件可正常使用;仅当读卡也无应答才判离线。要切纯图解口径(在线完全靠 81)把该开关置 false(需固件支持点名 81)。若 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 已验证可通) |
 
 ## 注意事项(重要)
 

+ 40 - 1
backend/app.py

@@ -56,6 +56,7 @@ from config import (
     DEFAULT_SERIAL_TIMEOUT,
     DEFAULT_ADDRESS_RANGE,
     PANEL_KEEPALIVE_MISS_LIMIT,
+    PANEL_READ_FALLBACK_KEEPALIVE,
     PANEL_PROBE_TIMEOUT,
     PANEL_QUERY_TIMEOUT,
     PANEL_READ_TIMEOUT,
@@ -770,6 +771,20 @@ def _read_cards_if_online(panel_id, cfg, addr):
     _handle_panel_read_success(panel_id, cfg, addr, result)
 
 
+def _probe_online_by_cards(panel_id, cfg, addr):
+    """81 缺失时的兼容探测(PANEL_READ_FALLBACK_KEEPALIVE):补发一次 0x03 读卡。
+
+    - 读卡有正常应答 -> 视为在线(兼容不回带 UID 81 的现网固件),顺带处理端口状态,返回 True;
+    - 读卡也无应答 -> 返回 False,由调用方判离线。
+    本函数只负责探测/处理读卡结果,不改在线状态、不清计数(交由调用方)。
+    """
+    result = modbus_client.read_all_antenna_cards(addr, timeout=PANEL_READ_TIMEOUT)
+    if 'error' in result:
+        return False
+    _handle_panel_read_success(panel_id, cfg, addr, result)
+    return True
+
+
 def _maybe_refresh_screen_panel(panel_id):
     """该面板若正显示在串口屏上,触发一次刷新"""
     try:
@@ -1105,7 +1120,31 @@ def _sweep_panel_addresses():
                 online += 1
                 continue
 
-            # 未收到 81(超时/空应答):累计保活失败
+            # 未收到匹配 81(超时/空应答)
+            was_offline = cfg.get('status') == 'offline'
+            if PANEL_READ_FALLBACK_KEEPALIVE:
+                # 兼容现网固件(不回带 UID 的 81,但 0x03 读卡正常):
+                # 判离线前 / 离线等待恢复时,先发一次 0x03 读卡探测——有应答即判在线。
+                if _probe_online_by_cards(panel_id, cfg, addr):
+                    if was_offline:
+                        logger.info(f"面板 {panel_id}(地址={addr}) 81 缺失但读卡有应答,"
+                                    f"兼容判定在线(先经 0x10 重下绑定②)")
+                        _sync_card_mappings_once(panel_id, addr, reason='读卡兜底恢复: ')
+                    # 读卡有应答 -> 在线并清零保活计数
+                    panel_keepalive_miss.pop(panel_id, None)
+                    panel_conflict.pop(panel_id, None)
+                    cfg['status'] = 'online'
+                    online += 1
+                    continue
+                # 读卡也无应答:累计保活失败,达阈值才判离线
+                _note_keepalive_miss(panel_id, addr, cfg)
+                if cfg.get('status') == 'offline':
+                    offline += 1
+                else:
+                    online += 1  # 第 1 次缺失尚未达阈值,仍按在线计
+                continue
+
+            # 严格图解口径:连续无匹配 81 计数;达 PANEL_KEEPALIVE_MISS_LIMIT 判离线停读卡
             went_offline = _note_keepalive_miss(panel_id, addr, cfg)
             if went_offline or cfg.get('status') == 'offline':
                 # 离线:停止该机 0x03 读卡

+ 6 - 0
backend/config.py

@@ -130,6 +130,12 @@ MAX_PORTS_PER_PANEL = 24  # 每个面板最大端口数
 # 线架地址段轮询 / UID 绑定(80/81 口径,仅 80 请求/81 应答,82/83 已废弃)
 DEFAULT_ADDRESS_RANGE = {'start': 1, 'end': 50}  # 默认轮询地址段
 PANEL_KEEPALIVE_MISS_LIMIT = 2                    # 连续 2 次收不到匹配 81 即判离线,并停止该机 0x03 读卡
+# 兼容现网固件:部分线架对「带绑定 UID 的 0x80 点名」不回 81,但 0x03 读卡正常。
+# 开启后,81 连续缺失即将判离线 / 已离线等待恢复时,先补发一次 0x03 读卡探测:
+#   读卡成功 -> 判在线并清零保活计数(兼容救活);读卡也失败 -> 才判/维持离线。
+# 将来线架固件支持点名 81 后,置 False 即回到纯图解严格口径(在线完全由 80/81 决定)。
+PANEL_READ_FALLBACK_KEEPALIVE = os.getenv(
+    'PANEL_READ_FALLBACK_KEEPALIVE', 'true').lower() in ('1', 'true', 'yes')
 PANEL_PROBE_TIMEOUT = 0.3                         # 未绑定地址全 0 探测超时(秒)
 PANEL_QUERY_TIMEOUT = 0.5                         # 已绑定地址带 UID 的 0x80 保活查询超时(秒)
 PANEL_READ_TIMEOUT = 1.0                          # 批量读卡 0x03 超时(秒,仅在线机执行)

+ 54 - 4
backend/tests/test_panel_registration.py

@@ -55,6 +55,7 @@ class TestPanelRegistration:
             '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),
+            'read_fallback': app_module.PANEL_READ_FALLBACK_KEEPALIVE,
         }
         self.mock_modbus = patch.object(app_module, 'modbus_client').start()
         self.mock_save_dev = patch.object(app_module, 'save_device_config').start()
@@ -102,6 +103,7 @@ class TestPanelRegistration:
             app_module.dtu_config.pop('port_mappings', None)
         else:
             app_module.dtu_config['port_mappings'] = self._saved['port_mappings']
+        app_module.PANEL_READ_FALLBACK_KEEPALIVE = self._saved['read_fallback']
 
     def _query_map(self, uid_by_addr):
         """按地址返回 0x80 查询结果(不在 map 中的地址视为无应答)"""
@@ -194,7 +196,8 @@ class TestPanelRegistration:
         assert last_set < last_read
 
     def test_one_miss_still_reads_two_miss_offline_stops_read(self):
-        """81 口径:第1次无81仍读卡并计1;连续第2次无81判离线、停止读卡。"""
+        """严格模式:第1次无81仍读卡并计1;连续第2次无81(读卡也失败)判离线、停止读卡。"""
+        app_module.PANEL_READ_FALLBACK_KEEPALIVE = False
         uid = 'ab' * 12
         pid = 'PANEL_dtu_001_7'
         app_module.dtu_config['address_range'] = {'start': 7, 'end': 7}
@@ -204,7 +207,7 @@ class TestPanelRegistration:
 
         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)
+        self.mock_modbus.read_all_antenna_cards.return_value = {'error': 'read timeout'}
 
         # 第 1 次:仍在线,本轮仍读卡,计数=1
         app_module._sweep_panel_addresses()
@@ -218,8 +221,54 @@ class TestPanelRegistration:
         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_fallback_read_ok_keeps_panel_online_without_81(self):
+        """兼容模式(默认开):从不回 81,但 0x03 读卡持续成功 -> 始终在线、不累计离线。"""
+        uid = 'b0' * 12
+        pid = 'PANEL_dtu_001_20'
+        app_module.dtu_config['address_range'] = {'start': 20, 'end': 20}
+        app_module.address_config.stored_devices[uid] = 20
+        app_module.panel_config[pid] = {'address': 20, 'position': 20, 'panel_uid': uid, 'status': 'online'}
+        app_module.panel_mappings_synced.add(pid)
+        assert app_module.PANEL_READ_FALLBACK_KEEPALIVE is True
+
+        self.mock_modbus.query_address.return_value = {'error': 'no 81', 'raw_data': ''}
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=20)
+
+        for _ in range(4):  # 远超 2 次阈值
+            app_module._sweep_panel_addresses()
+
+        assert app_module.panel_config[pid]['status'] == 'online'
+        assert app_module.panel_keepalive_miss.get(pid, 0) == 0
+
+    def test_fallback_read_fail_then_recover_by_read(self):
+        """兼容模式:读卡也连续失败会判离线;之后读卡恢复即救回在线(先 0x10 再处理)。"""
+        uid = 'b1' * 12
+        pid = 'PANEL_dtu_001_21'
+        app_module.dtu_config['address_range'] = {'start': 21, 'end': 21}
+        app_module.dtu_config['port_mappings'] = {pid: {'1': 'AAAAAAAAAAAAAAAA'}}
+        app_module.address_config.stored_devices[uid] = 21
+        app_module.panel_config[pid] = {'address': 21, 'position': 21, 'panel_uid': uid, 'status': 'online'}
+        app_module.panel_mappings_synced.add(pid)
+
+        self.mock_modbus.query_address.return_value = {'error': 'no 81', 'raw_data': ''}
+
+        # 连续 2 轮读卡也失败 -> 离线
+        self.mock_modbus.read_all_antenna_cards.return_value = {'error': 'read timeout'}
+        app_module._sweep_panel_addresses()
+        app_module._sweep_panel_addresses()
+        assert app_module.panel_config[pid]['status'] == 'offline'
+
+        # 第 3 轮:81 仍缺失,但读卡恢复 -> 兼容救回在线
+        self.mock_modbus.read_all_antenna_cards.return_value = read_result(make_cards({}), addr=21)
+        app_module._sweep_panel_addresses()
+        assert app_module.panel_config[pid]['status'] == 'online'
+        assert app_module.panel_keepalive_miss.get(pid, 0) == 0
+        # 离线恢复先经 0x10 重下绑定②
+        assert self.mock_modbus.set_card_mapping.called
+
     def test_offline_keeps_polling_80_but_never_reads(self):
-        """已离线机:继续发带 UID 的 80 探测恢复,但在收到匹配 81 前不再读卡。"""
+        """严格模式:已离线机继续发带 UID 的 80 探测恢复,但在收到匹配 81 前不再读卡。"""
+        app_module.PANEL_READ_FALLBACK_KEEPALIVE = False
         uid = 'ae' * 12
         pid = 'PANEL_dtu_001_10'
         app_module.dtu_config['address_range'] = {'start': 10, 'end': 10}
@@ -279,7 +328,8 @@ class TestPanelRegistration:
         assert self.mock_save_dev.called
 
     def test_offline_panel_still_probes_unbound(self):
-        """即使有绑定线架离线,地址段内未绑定地址仍照常全 0 顺序探测。"""
+        """严格模式:即使有绑定线架离线,地址段内未绑定地址仍照常全 0 顺序探测。"""
+        app_module.PANEL_READ_FALLBACK_KEEPALIVE = False
         old_uid = 'e5' * 12
         pid = 'PANEL_dtu_001_2'
         app_module.dtu_config['address_range'] = {'start': 2, 'end': 3}