# Plugin System（插件体系）

## 设计思想

CSM 的核心扩展机制，采用**端到端插件化**设计：
- Client 端每个插件独立 tokio task，负责数据采集/策略执行
- Server 端每个插件有独立的 API handler 模块和数据库表
- Protocol 层每个插件有专属 MessageType 范围和 payload struct
- Frontend 端每个插件有独立页面组件

三级配置推送：`global` → `group` → `device`，优先级递增。

## 代码逻辑

### 插件全链路（以 Web Filter 为例）

```
1. API: POST /api/plugins/web-filter/rules → server/api/plugins/web_filter.rs
2. Server 存储 → db.rs → INSERT INTO web_filter_rules
3. 推送 → push_to_targets(db, clients, WebFilterRuleUpdate, payload, scope, target_id)
4. TCP → Client network/mod.rs handle_server_message() → web_filter_tx.send()
5. Client → web_filter/mod.rs config_rx.changed() → 更新本地规则 → 采集上报
6. Client → Frame::new_json(WebAccessLog, entry) → data_tx → network → TCP → server
7. Server → tcp.rs process_frame(WebAccessLog) → db.rs → INSERT INTO web_access_logs
8. Frontend → GET /api/plugins/web-filter/log → 展示
```

### 现有插件一览

| 插件 | 消息类型范围 | 方向 | 功能 |
|------|-------------|------|------|
| Web Filter | 0x2x | S→C 规则, C→S 日志 | URL 黑白名单、访问日志 |
| Usage Timer | 0x3x | C→S 报告 | 每日使用时长、应用使用统计 |
| Software Blocker | 0x4x | S→C 黑名单, C→S 违规 | 禁止安装软件、违规上报 |
| Popup Blocker | 0x5x | S→C 规则, C→S 统计 | 弹窗拦截规则、拦截统计 |
| USB File Audit | 0x6x | C→S 记录 | U盘文件操作审计 |
| Watermark | 0x70 | S→C 配置 | 屏幕水印显示配置 |
| USB Policy | 0x71 | S→C 策略 | U盘管控（全阻/白名单/黑名单） |
| Plugin Control | 0x80-0x81 | S→C 命令 | 远程启停插件 |
| Disk Encryption | 0x90, 0x93 | C→S 状态, S→C 配置 | 磁盘加密状态检测 |
| Print Audit | 0x91 | C→S 事件 | 打印操作审计 |
| Clipboard Control | 0x94-0x95 | S→C 规则, C→S 违规 | 剪贴板操作管控（仅上报元数据） |
| Patch Management | 0xA0-0xA2 | 双向 | 系统补丁扫描与安装 |
| Behavior Metrics | 0xB0 | C→S 指标 | 行为指标采集（异常检测输入） |

### 新增插件必改文件清单

| # | 文件 | 改动 |
|---|------|------|
| 1 | `crates/protocol/src/message.rs` | 添加 MessageType 枚举值 + payload struct |
| 2 | `crates/protocol/src/lib.rs` | re-export 新类型 |
| 3 | `crates/client/src/<plugin>/mod.rs` | 创建插件实现 |
| 4 | `crates/client/src/main.rs` | `mod <plugin>`, watch channel, PluginChannels 字段, spawn |
| 5 | `crates/client/src/network/mod.rs` | PluginChannels 字段, handle_server_message 分支 |
| 6 | `crates/server/src/api/plugins/<plugin>.rs` | 创建 API handler |
| 7 | `crates/server/src/api/plugins/mod.rs` | mod 声明 + 路由注册 |
| 8 | `crates/server/src/tcp.rs` | process_frame 新分支 + push_all_plugin_configs |
| 9 | `crates/server/src/db.rs` | 新增 DB 操作方法 |
| 10 | `migrations/NNN_<name>.sql` | 新迁移文件 |
| 11 | `crates/server/src/main.rs` | include_str! 新迁移 |

## 关联模块

- [[protocol]] — 定义插件的 MessageType 和 payload
- [[client]] — 插件采集端
- [[server]] — 插件 API 和数据处理
- [[web-frontend]] — 插件管理页面
- [[database]] — 每个插件的数据库表

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/client/src/<plugin>/mod.rs` | 客户端插件实现（每个插件一个目录） |
| `crates/server/src/api/plugins/<plugin>.rs` | 服务端插件 API（每个插件一个文件） |
| `crates/server/src/tcp.rs` | 帧分发 + push_to_targets + push_all_plugin_configs |
| `crates/client/src/main.rs` | 插件 watch channel 创建 + task spawn |
| `crates/client/src/network/mod.rs` | PluginChannels 定义 + 服务器消息分发 |