航行日志分析程序改进方案（对照协议故障表）
| 项 | 内容 |
|---|---|
| 版本 | v1.0 |
| 日期 | 2026-05-31 |
| 依据 | 协议说明截图（故障位 / 故障详情 / 状态 / 告警） |
| 对照代码 | trajectory-log-analyzer/tla/esc_faults.py、fault_engine.py、session_analyzer.py |
| 当前分析器版本 | 1.0.2 |
1. 结论：有没有调整价值？
有，且建议分阶段做。 协议表把「故障 / 告警 / 状态」分层写清楚了，而当前分析程序仍是数据驱动反推码表 + 少量 ESC/ECU/BMS 掩码，与 App/协议展示存在三类差距：
- 码表不完整：协议里十几种故障，分析器只稳定识别 4 个 ESC + 3 个 ECU + 4 个 BMS 掩码。
- 「板体失控」口径未固化：研发三条（堵转 / 0x400000 / 转速超范围）未合成独立字段，报表只能猜。
- 语义存在固件分支差异：
0x400000在协议/App 与feature_motorstuck固件里可能不是同一含义（见 §3）。
不做调整的风险：后台「故障会话」与 App 弹窗、研发复盘口径继续不一致；版本监控和失控案例筛选漏检/误报。
2. 协议表与日志字段的关系（先对齐层级）
2.1 日志里实际有的字段（分析器已用）
| 轨迹点字段 | 用途 |
|---|---|
escEventCode |
ESC 上报事件（running_error << 16 等合成） |
ecuEventCode |
ECU 侧故障/通信类 |
bmsEventCode |
BMS 侧故障 |
motorSpeed |
主机侧转速反馈（含冻结、脏包、超范围） |
throttleLeverQuantity |
油门 |
electricCurrent |
电流 |
mode |
模式（如 99 断驱等） |
2.2 协议表里的分层（截图）
| 层级 | 示例 | 分析器现状 |
|---|---|---|
| 故障位 bit0.1–0.25 | stall_fault、fall_fault、motor_fault… |
未按协议索引建模 |
| 故障详情 1–24 | 过流、堵转、通讯超时、蓝牙、IMU、倾斜、跌落、碰撞、急停… | 部分掩码可对应，多数未命名 |
| 状态 | standby / running / charging / fault / ota | 未入库（可从 mode 推导） |
| 告警 | 低电量、高温、超速、偏航 | 未单独统计（与故障混淆） |
重要： 协议「故障序号」≠ 日志 escEventCode 的 bit 位置，需一张对照表由研发确认后写进 esc_faults.py，不能仅靠截图序号硬猜。
3. 「板体失控」三条条件 — 对照协议与代码
研发口径（你方确认）：
| # | 条件 | 日志检测方式 | 当前程序 |
|---|---|---|---|
| 1 | 堵转 0x20000 | escEventCode & 0x20000 |
✅ stall_points |
| 2 | 0x400000 | escEventCode & 0x400000 |
✅ overvoltage_points（命名按过压） |
| 3 | 转速 < -20000（固件亦含 ≥20000） | motorSpeed 超范围 |
❌ 未实现（仅有 D4A081 脏包 corrupt_speed_points） |
3.1 关于 0x400000 的语义风险（必须和研发确认）
| 来源 | 对 0x400000 的解释 |
|---|---|
| 当前分析器 / JetWave.xml | 过压保护 ESC_FAULT_OVERVOLTAGE_PROTECTION |
| 协议截图（bit0.22 / 部分行） | 有资料写成 跌落 fall_fault 等 |
feature_motorstuck 固件 |
异常转速误置 runningError bit6 → 上报成 0x400000（语义错误，非真过压） |
建议： 分析器保留掩码检测，但展示名改为中性 ESC_EVENT_0x400000，并在报表/tooltip 注明「可能是过压 / 固件误映射 / 协议跌落位，需结合转速与电流判断」。
确认后再决定是否改名为 fall_fault 或拆成两列。
3.2 第 3 条应与固件一致
固件（15265 报告）：
if (escSpeedInfo->speed <= -20000 || escSpeedInfo->speed >= 20000)
分析器应新增（与 D4A081 脏包并列）：
def is_invalid_motor_speed(motor_speed) -> bool:
v = int(motor_speed)
return v <= -20000 or v >= 20000
统计 → invalid_speed_points（或 speed_out_of_range_points）。
4. 协议故障表 vs 当前码表差距矩阵
| 协议/常见含义 | 建议日志掩码（待研发签字） | 分析器 v1.0.2 |
|---|---|---|
| 过流 over_current | 0x10000? |
❌ |
| 过温 over_temp | 0x40000? |
❌ |
| 堵转 stall_fault | 0x20000 |
✅ |
| 通讯超时 comm_timeout | ECU 0x40000000? 或 ESC 其他位 |
部分（仅 ECU 计数） |
| 蓝牙 bt_fault | mode/连接状态，未必在 escEvent |
❌ |
| IMU imu_fault | 待确认 BMS/ECU/ESC | ❌ |
| 倾斜 tilt_fault | 待确认 | ❌ |
| 跌落 fall_fault | 0x400000? |
⚠️ 当作过压统计 |
| 碰撞 collision_fault | 待确认 | ❌ |
| 急停 emergency_stop | 待确认 | ❌ |
| 过压（真过压） | 与 0x400000 可能冲突 | ⚠️ 同上 |
| 空转 / 其他 | 0x800000 等高频未知 |
仅 unknown 名 |
BMS 侧（协议未逐条列出但数据很多）： 0x10/0x20/0x400/0x1000 已统计，但 has_fault=1 常仅因 BMS，导致「故障会话」很多 severity=none（如 8668），报表易误解。
5. 现状问题（结合报表与协议）
| 问题 | 影响 |
|---|---|
无 has_board_out_of_control |
无法按研发三条 OR 一键筛失控案例 |
无 invalid_speed_points |
漏检「超范围转速」；与 D4A081 脏包混淆 |
has_fault 过宽 |
BMS 轻微码也算故障，和 App「红色故障」不一致 |
severity 与协议故障等级无关 |
自研打分，难对应「故障 / 告警」 |
| 故障命名绑定错误语义 | 0x400000 标成过压，motorstuck 分支下误导 |
| 告警未建模 | 低电量、高温、超速等无法和故障分栏 |
| 状态未建模 | running/fault/ota 无法过滤分析任务 |
6. 改进目标
- 与协议/App 展示同源：故障名、图标类别可映射。
- 板体失控可复现：三条条件固化为字段 + 报表筛选。
- 可演进码表：研发更新协议时只改
esc_faults.yaml/ 表，不改核心逻辑。 - 向后兼容：旧
stall_points等保留，新增字段增量迁移。
7. 方案设计
7.1 码表外置（P0）
新增 trajectory-log-analyzer/tla/fault_catalog.yaml（或 DB 表 surf_fault_code_dict）：
esc:
- code: ESC_FAULT_STALL_PROTECTION
mask: 0x20000
protocol_name: stall_fault
display_zh: 电机堵转
board_out_of_control: true
- code: ESC_EVENT_0x400000
mask: 0x400000
protocol_name: TBD # fall_fault | overvoltage
display_zh: ESC事件0x400000
board_out_of_control: true
notes: motorstuck 分支可能为异常转速误映射
motor_speed:
- rule: out_of_range
min: -20000
max: 20000
board_out_of_control: true
- rule: corrupt_d4a081
field: motorSpeed
board_out_of_control: false # 归类为通信/数据异常
esc_faults.py 改为加载 YAML，生成 match_* 与 fault_detail 行。
7.2 板体失控合成字段（P0）
会话级：
board_out_of_control = (
stall_points > 0
or esc_0x400000_points > 0 # 重命名 overvoltage_points 或双写
or invalid_speed_points > 0
)
入库：
ALTER TABLE surf_motion_trajectory_analysis
ADD COLUMN invalid_speed_points INT NOT NULL DEFAULT 0 COMMENT '|motorSpeed|>=20000 点数',
ADD COLUMN has_board_out_of_control TINYINT(1) NOT NULL DEFAULT 0 COMMENT '板体失控(研发三条OR)',
ADD COLUMN fault_domain_primary VARCHAR(16) NULL COMMENT 'esc|ecu|bms|motor|comm 主因';
analyzer_version → 1.0.3，触发旧数据重算。
7.3 故障 / 告警 / 异常 三分（P1）
| 类型 | 判定 | 报表 |
|---|---|---|
| 协议故障 | 协议掩码表命中 ESC/ECU/BMS | 对齐 App 故障图标 |
| 告警 | 电量/温度/超速阈值（点级或会话级） | 黄色告警栏 |
| 数据异常 | D4A081、trajectory_gaps、空轨迹 | 研发向，不进「用户故障」 |
新增 has_protocol_fault、has_warning，has_fault 改为 OR 关系且可配置。
7.4 扩展 ESC/ECU 掩码（P1，需研发确认）
优先补充（日志已见高频 0x800000 等）：
| 掩码 | 临时名 | 协议候选 |
|---|---|---|
0x10000 |
ESC_OVERCURRENT | over_current |
0x40000 |
ESC_OVERTEMP | over_temp |
0x800000 |
ESC_UNKNOWN_800000 | 待命名 |
0x1000000 |
ESC_UNKNOWN_1000000 | 待命名 |
ECU 0x40000000 |
ECU_COMM_FAULT | comm_timeout |
7.5 严重度与评分（P2）
- critical：
has_board_out_of_control且 (stall_ratio>50% 或 invalid_speed 连续段 或 ECU comm 后仍有大电流) - high：任一协议故障 > 阈值
- medium：仅告警或 BMS 非致命码
- none：仅数据异常或无命中
stall_score 保留，改为辅助排序，不作为唯一严重度来源。
7.6 报表 / API（P1）
| 筛选项 | SQL 条件 |
|---|---|
| 板体失控 | has_board_out_of_control = 1 |
| 堵转 | stall_points > 0 |
| ESC 0x400000 | esc_0x400000_points > 0 |
| 转速异常 | invalid_speed_points > 0 |
| 脏包转速 | corrupt_speed_points > 0 |
| 仅 BMS | has_fault=1 AND stall_points=0 AND ... |
会话列表增加列：has_board_out_of_control、invalid_speed_points、fault_domain_primary。
8. 实施计划
| 阶段 | 内容 | 工作量 | 产出 |
|---|---|---|---|
| P0 | invalid_speed_points + has_board_out_of_control；0x400000 中性命名；analyzer_version=1.0.3 |
1–2 天 | 可筛失控三条 |
| P0 | 研发确认《日志掩码 ↔ 协议故障表》对照页（1 页纸） | 依赖研发 | 避免误映射 |
| P1 | fault_catalog.yaml + 扩展 5–8 个掩码 |
2–3 天 | 故障明细与 App 对齐 |
| P1 | has_protocol_fault / has_warning 拆分 |
1 天 | 报表统计口径清晰 |
| P2 | 告警阈值（电量/温度/超速） | 2 天 | 对齐协议「告警」区 |
| P2 | 日聚合表增加 session_board_out_of_control 计数 |
0.5 天 | 版本/设备趋势 |
9. 建议研发确认清单（阻塞 P1）
- 日志
escEventCode每个已知 bit 与协议表 1–24 的一一映射。 - 0x400000 在量产权 App 协议里究竟是过压、跌落还是「ECU 误映射位」。
motorSpeed单位是否与固件speed一致（0.1 rpm？），-20000阈值是否直接用于日志。ecuEventCode=0x40000000是否对应「通讯超时 / 板体失控」类。- 蓝牙断链看
mode=255还是独立故障位？ - 告警（低电量、高温）是否写入
bmsEventCode/escEventCode还是仅 App 本地？
10. 改完后如何验证
| 用例 | 期望 |
|---|---|
| 15265 / 14873 | stall_points>0，has_board_out_of_control=1 |
| 含 D4A081 脏包 | corrupt_speed_points>0，invalid_speed_points 可能为 0 |
| 含 -25000 转速（非 D4A081） | invalid_speed_points>0 |
| 仅 BMS 0x20 | has_fault=1 但 has_board_out_of_control=0（若配置排除 BMS） |
| 8668 类会话 | 报表可区分「BMS 故障」与「板体失控」 |
11. 是否建议立刻改？
| 场景 | 建议 |
|---|---|
| 马上要上线定时分析 | 先上 P0（三条失控 + 新字段），码表扩展可下一版 |
| 报表已给用户看 | 同步改前端筛选与图例，注明 0x400000 待确认 |
| 仅内部研发复盘 | P0 + 研发确认清单并行 |
不建议在未确认 0x400000 语义前，把 overvoltage_points 直接改名为 fall_fault 或仅保留过压文案。
12. 相关文件（改动触点）
trajectory-log-analyzer/
tla/esc_faults.py # 码表扩展 / YAML 加载
tla/fault_engine.py # 评分与 domain 主因
tla/session_analyzer.py # 新字段汇总
sql/migrations/ # ALTER 新列
sql/surf_motion_trajectory_analysis.sql
analysis/
esc_faults.py # 与 tla 同步
附录 A：板体失控推荐 SQL（P0 后）
SELECT trajectory_id, remote_sn, session_date,
stall_points, overvoltage_points AS esc_0x400000_points,
invalid_speed_points, corrupt_speed_points,
has_board_out_of_control, severity
FROM surf_motion_trajectory_analysis
WHERE has_board_out_of_control = 1
ORDER BY session_date DESC;
附录 B：当前已覆盖掩码（v1.0.2）
ESC： 0x20000 0x400000 0x800000 0x1000000 0x2000000 0x4
ECU： 0x40000000 0x80000000 0x8000000
BMS： 0x20 0x10 0x1000 0x400
转速： 仅 0xD4A081xx 脏包（非 ±20000）