优化后端和前端

docs/CAN1控制指令白名单.md

@@ -0,0 +1,74 @@
+# CAN1 控制指令白名单
+
+- 适用项目：`Cognitive_Agent`
+- 适用分支：`feature/N7Web`
+- 核对日期：2026-08-24
+- 验证层级：自然语言解析、精确指令解析和 CAN1 白名单编译通过；未在本次核对中发送真实 CAN 帧。
+
+“发送逻辑”列以当前执行器代码为准。有线模式按该顺序直接提交 CAN1 帧；无线 MQTT 模式将每个原始 CAN 帧分别封装为 1 条 `n7/n7-headunit/can/command` 消息（默认 QoS 1）。因此表中“3 帧，间隔 100 ms”在无线模式下表示后端连续发布 3 条 MQTT 消息，每条消息内部仍为 `repeat: 1`、`intervalMs: 0`。MQTT 客户端或 Broker 接受消息只代表已提交，车辆是否完成动作仍以状态话题的反馈帧为准。
+
+## 有效白名单
+
+| 类别 | 有效指令 | 参数约束 | 发送逻辑 |
+| --- | --- | --- | --- |
+| 后排门锁 | `door rear <lock\|unlock>` | 仅后排门锁 | `0x32B` 经典 CAN，发送 1 帧；反馈 ID `0x407` |
+| 车窗动作 | `window <all\|front\|rear\|front-left\|front-right\|rear-left\|rear-right> <open\|close\|stop>` | 目标和动作必须使用列出的枚举值 | `0x431` CAN FD+BRS，连续 3 帧，相邻帧间隔 100 ms；反馈 ID `0x388` |
+| 单窗位置 | `window <front-left\|front-right\|rear-left\|rear-right> position <0-100>` | 仅支持单个车窗，位置为整数百分比 | 先等待最长 2500 ms 的有效 `0x388`；已在目标 ±3% 内则发送 0 帧。否则用 `0x431` CAN FD+BRS 发送 3 帧启动命令（间隔 100 ms），最长闭环监听 `0x388` 12 s；无论到位或超时，最后强制发送 3 帧停止命令（间隔 100 ms） |
+| 空调电源 | `ac <on\|off>` | 整车 HVAC 电源 | `0x1DE` 经典 CAN，连续 3 帧，间隔 100 ms；反馈 ID `0x404` |
+| 空调风量 | `ac fan <1-7>` | 只接受 1–7 的整数 | `0x1DE` 经典 CAN，连续 3 帧，间隔 100 ms；反馈 ID `0x404` |
+| 出风模式 | `ac mode <face\|face-feet\|feet\|feet-defrost\|defrost\|face-feet-defrost\|face-defrost>` | 仅接受列出的 7 种模式 | `0x1DE` 经典 CAN，连续 3 帧，间隔 100 ms；反馈 ID `0x404` |
+| 空调温度 | `ac temp <driver\|passenger\|rear> <18-32>` | 温度只接受 18–32 的整数 | `0x1DE` 经典 CAN；`driver`/`passenger` 各发 3 帧（间隔 100 ms），`rear` 发 1 帧；反馈 ID `0x404` |
+| 空调控制模式 | `ac control <manual\|auto>` | 手动或自动 | `0x1DE` 经典 CAN，连续 3 帧，间隔 100 ms；反馈 ID `0x404` |
+| 空调循环 | `ac cycle <internal\|external>` | 内循环或外循环 | `0x1DE` 经典 CAN，连续 3 帧，间隔 100 ms；反馈 ID `0x404` |
+| 风口百分比 | `outlet <driver-left\|driver-right\|passenger-left\|passenger-right> percent <0-100> <0-100>` | 依次为左右、上下整数百分比 | `0x4EF` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x2F5`/`0x37B` |
+| 风口标定坐标 | `outlet <区域> position <左右坐标> <上下坐标>` | 必须同时满足通用有符号范围和对应风口标定范围 | `0x4EF` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x2F5`/`0x37B` |
+| 主驾座椅通风/加热 | `seat driver <vent\|heat> <off\|low\|high>` | `front-left` 可作为主驾输入兼容别名，规范输出仍为 `driver` | `0x431` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x4FA` |
+| 主驾座椅按摩关闭 | `seat driver massage off` | 仅关闭动作 | `0x4C1` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x4FA` |
+| 主驾座椅按摩强度 | `seat driver massage strength <weak\|medium\|strong>` | `1\|2\|3` 也可作为输入兼容别名，规范输出为单词枚举 | `0x4C1` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x4FA` |
+| 主驾座椅按摩模式 | `seat driver massage mode <wave\|pulse\|stretch\|slack\|relax>` | 仅接受列出的 5 种模式 | `0x4C1` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x4FA` |
+| 主驾座椅水平调节 | `seat driver horizontal <forward\|backward> [duration-ms]` | `duration-ms` 为 100–2000；省略时默认 500 ms | `0x4C1` CAN FD+BRS；动作帧数为 `ceil(duration-ms/100)`，间隔 100 ms，最后一帧后额外保持 100 ms；随后强制发送 3 帧 STOP（间隔 100 ms）；反馈 ID `0x494` |
+| 主驾座椅高度调节 | `seat driver height <up\|down> [duration-ms]` | `duration-ms` 为 100–2000；省略时默认 500 ms | `0x4C1` CAN FD+BRS；动作帧数为 `ceil(duration-ms/100)`，间隔 100 ms，最后一帧后额外保持 100 ms；随后强制发送 3 帧 STOP（间隔 100 ms）；反馈 ID `0x494` |
+| 主驾座椅靠背调节 | `seat driver backrest <forward\|backward> [duration-ms]` | `duration-ms` 为 100–2000；省略时默认 500 ms | `0x4C1` CAN FD+BRS；动作帧数为 `ceil(duration-ms/100)`，间隔 100 ms，最后一帧后额外保持 100 ms；随后强制发送 3 帧 STOP（间隔 100 ms）；反馈 ID `0x494` |
+| 主驾座椅坐盆调节 | `seat driver basin <up\|down> [duration-ms]` | `duration-ms` 为 100–2000；省略时默认 500 ms | `0x4C1` CAN FD+BRS；动作帧数为 `ceil(duration-ms/100)`，间隔 100 ms，最后一帧后额外保持 100 ms；随后强制发送 3 帧 STOP（间隔 100 ms）；反馈 ID `0x494` |
+| 主驾座椅停止 | `seat driver <horizontal\|height\|backrest\|basin> stop` | `stop` 后不允许附加持续时间 | `0x4C1` CAN FD+BRS，直接连续发送 3 帧 STOP，间隔 100 ms；反馈 ID `0x494` |
+| 主驾座椅记忆 | `seat driver position <1-3>` | 需要先由操作员完成 PAD 只读学习 | `0x4C1` CAN FD+BRS；下发前最长等待 2500 ms 的新鲜 `0x494`，且四轴初始化均为真；然后将已学习的 `0x16 → 0x15` 交替序列发送 10 轮，共 20 帧，间隔 50 ms；发送后最长等待 1200 ms 的 `0x494` |
+| 主驾座椅记忆兼容别名 | `seat driver memory recall <1-3>` | 与 `seat driver position <1-3>` 使用同一已学习帧序列 | 发送逻辑与 `seat driver position <1-3>` 完全相同：`0x4C1` CAN FD+BRS，四轴初始化门禁通过后发送 20 帧 `0x16/0x15` 交替序列，间隔 50 ms |
+| 室内灯总开关 | `light indoor <on\|off>` | 整车室内灯总开关 | `0x4F5` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x42E` |
+| 全部阅读灯 | `light reading all <on\|off>` | CAN1 仅验证 `all` 目标 | `0x4F5` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x42E` |
+| 氛围灯开关 | `light ambient <on\|off>` | 氛围灯总开关 | `0x3FC` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x42E` |
+| 氛围灯颜色 | `light ambient color <1-127>` | 车型颜色索引，只接受整数 | `0x3FC` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x42E` |
+| 氛围灯亮度 | `light ambient brightness <1-5>` | 只接受 1–5 的整数档位 | `0x3FC` CAN FD+BRS，连续 3 帧，间隔 100 ms；反馈 ID `0x42E` |
+| 遮阳帘动作 | `shade <open\|close\|half\|stop>` | 0/50/100 位置与已验证预设动作复用 | `0x431` 经典 CAN；`open/close/half` 先发 1 帧预设命令，最长监听 `0x41A` 15 s，在匹配目标位置但仍在运动时追加 1 帧 STOP 并确认停止；`stop` 发 1 帧 STOP 并等待停止反馈 |
+| 遮阳帘位置 | `shade position <0-100>` | 中间位置使用状态反馈闭环并自动停止 | 0/50/100 按上述预设逻辑发送。其他位置先等待最长 2500 ms 的新鲜 `0x41A`；已在目标 ±2% 内且停止则发 0 帧，已到位但仍运动则发 1 帧 STOP。否则用 `0x431` 经典 CAN 发 1 帧开/关启动命令，最长监听 15 s，并在 `finally` 中强制发 1 帧 STOP，再确认位置与停止状态 |
+
+## 风口标定坐标范围
+
+| 风口 | 左右范围 | 上下范围 |
+| --- | ---: | ---: |
+| `driver-left` | -25–40 | -40–30 |
+| `driver-right` | -40–30 | -40–30 |
+| `passenger-left` | -10–40 | -40–30 |
+| `passenger-right` | -40–5 | -40–30 |
+
+风口原始坐标语法层的通用范围为 -128–126，但只有同时落在上表对应风口实际标定范围内才能通过编译。
+
+## 能力层扩展与非白名单入口
+
+| 指令/能力 | 当前状态 | 发送逻辑 |
+| --- | --- | --- |
+| `ac compressor <on\|off>` | `climate.set_ac` 在后端能力层可编译，但当前没有对应的直接精确文本解析入口 | 若由受信能力层调用：`0x1DE` 经典 CAN，3 帧，间隔 100 ms，反馈 ID `0x404`；但本项不是直接指令白名单入口 |
+| `door vehicle <lock\|unlock>` | 可解析，但当前 CH1 实车验证未观察到有效整车门锁动作，因此会被安全拒绝，不属于可下发白名单 | 安全门禁拒绝，发送 0 帧 |
+| `ac defrost <on\|off>` | 存在旧解析入口，但当前 CAN1 运行时未实现；前除霜应使用 `ac mode defrost` | 编译门禁拒绝，发送 0 帧 |
+
+## CAN0 边界
+
+本文档只描述 CAN1 车身控制白名单。CAN0 只用于副驾座椅，其状态、轴位置、热舒适和动态模式控制必须依据 `seat-ota` 协议独立处理，不得使用本 CAN1 白名单生成或猜测 CAN0 帧。
+
+## 实现与回归测试
+
+- 精确命令和自然语言匹配：`src/cognitive_agent/application/native_can_intent.py`
+- 能力、参数及 CAN 帧编译门禁：`src/cognitive_agent/application/native_can_runtime.py`
+- 风口标定范围：`platforms/t2g_cabin_bench/calibration/body_can.yaml`
+- 完整白名单回归测试：`tests/unit/test_can1_semantic_whitelist.py`
+
+白名单回归测试展开覆盖 119 条有效命令，并验证越界、非整数、非法枚举和超出风口标定范围的指令不能通过白名单门禁。