feat(vd960DBN): offlog 协议导出命令分发 — log_stat/log_query/log_clear 落地

协议先行 (08893d5, MQTT V1.06 + TCP JSON V1.02) 的固件侧实现:
- offlog 新增导出 API: enabled/seq_last/type_str/evt_to_json
  (seq_first=seq_last-count+1, idx=start_seq-seq_first, count≤4)
- MQTT iot_handle_publish 三分支: log_stat/log_query/log_clear
  (log_query 响应 static buf 防大栈; log_clear 阻塞~2.8s 主循环可接受)
- TCP JSON 三 handler + cmd 表 (需鉴权)
- 单测新增 test_export_json (8 例全过): boot rst 大端/coil sub/evt_retry/data:null/seq 公式
- devlog V3.9

vd960DBN/docs/devlog.md

@@ -6,6 +6,43 @@
 
 ---
 
+## 2026-08-05 — offlog 协议导出命令分发落地 (MQTT V1.06 + TCP JSON V1.02)
+
+### 背景
+
+协议文档先行（MQTT V1.06 / TCP JSON V1.02，commit 08893d5）新增 `log_stat` / `log_query` / `log_clear` 三命令规范，固件命令分发未接。本次补齐 P1.3：offlog 底层 API 已就绪（count/read_idx/clear），差协议层接线。
+
+### offlog 导出 API（两侧共用，放 offlog 模块避免两协议层重复）
+
+| API | 作用 |
+|------|------|
+| `offlog_enabled()` | 日志功能是否启用（Flash 初始化成功） |
+| `offlog_seq_last()` | 最新一条记录全局序号（`_wr_seq - 1`，0=空） |
+| `offlog_type_str(type)` | 事件类型数字 → 协议字符串名（10 类 + unknown） |
+| `offlog_evt_to_json()` | 单条记录 → JSON 对象（data 按事件类型组装，无参数事件 data=null） |
+| `OFFLOG_MAX_QUERY_RECORDS` | 分页上限 4（MQTT ≤500B 发布限制） |
+
+payload 大端解析（`offlog_payload_u32`）与写入侧 `offlog_boot/offlog_coil` 完全一致；coil sub 映射 1=car_enter 2=car_leave 3=loop_cut 4=loop_restore。
+
+### 命令分发
+
+- **MQTT**（`iot_handle_publish` 三分支）：`log_stat`（enabled/boot_seq/count/capacity/seq_first/seq_last）、`log_query`（按全局序号分页，`idx = start_seq - seq_first` 映射 offlog_read_idx，越界返回空 records，响应用 `static resp[IOT_MQTT_SEND_BUF_LEN]` 防大栈）、`log_clear`
+- **TCP JSON**（三 handler + cmd 表 3 条目，全部需鉴权）：同上，`data_json[TCP_JSON_DATA_BUF_LEN]` 组装后 `json_send_ok`
+
+### 关键决策与坑
+
+1. **`log_clear` 阻塞 ~2.8s**（63 扇区擦除 × ~45ms）：SPI 擦除只能在主循环上下文（中断写 SPI 会炸栈），三命令 handler 均在主循环 poll 链上调用，可接受；MQTT 侧 60s keepalive、TCP 有状态重传均能吸收。注释已标注。
+2. **`seq_first = seq_last - count + 1`**（count=0 时置 0）：环形覆盖后 count < capacity 是正确语义，分页定位按全局序号不按时间（未同步段时间不可靠）。
+3. **CRLF 二进制编辑**：四个 C 源文件 UTF-8+CRLF，用 Python rb/wb 精确替换，每处校验 count==1；gcc 全文件括号/引号平衡检查通过。
+
+### 验证
+
+- `test_offlog.c` 新增测试8 `test_export_json`：enabled/seq_last/type_str/evt_to_json（boot rst 大端、coil sub/ch/value、evt_retry msg_id+retry、无参数 data:null、seq_first 公式）
+- gcc 隔离单测 **8 例全过**（含既有 7 例回归）
+- CRLF/UTF-8 编码零漂移（file 复核）
+
+---
+
 ## 2026-07-15 — 🔴 loop_data 陈旧快照: 事件与缓存不同源 (帧竞争)
 
 ### 现象 (现场测试: 长车过双线圈)
@@ -719,6 +756,7 @@ TCP 超时要等 ~2 分钟才触发 `SINT_STAT_TIM_OUT`,
 
 | 版本 | 时间 | 说明 |
 |------|------|------|
+| V3.9 | 2026-08-05 | offlog 协议导出命令分发: log_stat/log_query/log_clear 落地 MQTT V1.06 + TCP JSON V1.02 (seq_first/seq_last 计算、idx 映射、OFFLOG_MAX_QUERY_RECORDS=4、log_clear 阻塞~2.8s) |
 | V3.8 | 2026-08-04 | offlog: TIME_ANCHOR 严格用平台下发 unix_ts (offlog_evt_ts), 单测 7 例 | 
 | V3.7 | 2026-08-04 | tcp_json_srv 缓冲宏化: data_json[2048]→TCP_JSON_DATA_BUF_LEN(1024), 省栈1KB×3 | 
 | V3.6 | 2026-08-04 | 脱机事件日志系统: W25Q32 256KB 环形(8064条) + BOOT/网络/事件/线圈/时钟锚点 8 类事件 + 掉电恢复 + gcc 单测 6 例 |