# Protocol（二进制协议层）

## 设计思想

`csm-protocol` 是 Server 和 Client 共享的协议定义 crate。核心设计决策：

1. **零拷贝编解码** — `Frame::encode()` / `Frame::decode()` 直接操作字节切片，无中间分配
2. **类型安全** — `MessageType` 枚举确保所有消息类型在编译期可见，`TryFrom<u8>` 处理未知类型
3. **JSON payload** — 网络传输用 JSON（`serde`），兼顾可调试性和跨语言兼容性
4. **payload 上限 4MB** — `MAX_PAYLOAD_SIZE` 防止恶意帧耗尽内存

二进制帧格式：`MAGIC(4B "CSM\0") + VERSION(1B) + TYPE(1B) + LENGTH(4B big-endian) + PAYLOAD(变长 JSON)`

## 代码逻辑

### 帧生命周期

```
发送方: T → Frame::new_json(mt, &data) → Frame::encode() → Vec<u8> → TCP stream
接收方: TCP bytes → Frame::decode(&buf) → Option<Frame> → Frame::decode_payload::<T>()
```

### MessageType 分块规划

| 范围 | 插件 | 方向 |
|------|------|------|
| 0x01-0x0F | Core（心跳/注册/状态/资产） | 双向 |
| 0x10-0x1F | Core Server→Client（策略/配置/任务） | S→C |
| 0x20-0x2F | Web Filter | C→S 日志, S→C 规则 |
| 0x30-0x3F | Usage Timer | C→S 报告 |
| 0x40-0x4F | Software Blocker | C→S 违规, S→C 黑名单 |
| 0x50-0x5F | Popup Blocker | C→S 统计, S→C 规则 |
| 0x60-0x6F | USB File Audit | C→S 操作记录 |
| 0x70-0x7F | Watermark + USB Policy | S→C 配置 |
| 0x80-0x8F | Plugin Control | S→C 启停命令 |
| 0x90-0x9F | Disk Encryption / Print / Clipboard | 混合 |
| 0xA0-0xAF | Patch Management | C→S 状态, S→C 配置 |
| 0xB0-0xBF | Behavior Metrics | C→S 指标 |

### 关键类型

- `Frame` — 帧结构（version + msg_type + payload bytes）
- `FrameError` — 解码错误枚举（InvalidMagic / UnknownMessageType / PayloadTooLarge / Io）
- 每个 MessageType 对应一个 payload struct（如 `WebAccessLogEntry`, `HeartbeatPayload`）

## 关联模块

- [[server]] — TCP 接入层调用 `Frame::decode()` 解析客户端帧，调用 `push_to_targets()` 推送配置帧
- [[client]] — 通过 `Frame::new_json()` 构造上报帧，通过 `Frame::decode()` 解析服务器下发的帧
- [[plugins]] — 每个插件定义自己的 payload struct 在此 crate 中

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/protocol/src/message.rs` | MessageType 枚举、Frame 编解码、所有 payload struct |
| `crates/protocol/src/device.rs` | DeviceStatus、ProcessInfo、HardwareAsset、UsbEvent 等设备相关类型 |
| `crates/protocol/src/lib.rs` | Re-export 所有公开类型 |