# Client（客户端代理）

## 设计思想

`csm-client` 是部署在医院终端设备上的 Windows 代理程序，设计为：
1. **无人值守运行** — 支持控制台模式（开发调试）和 Windows 服务模式（生产部署）
2. **自动重连** — 指数退避策略（1s → 60s），断线后 drain stale frames
3. **插件化采集** — 每个插件独立 task，通过 `watch` channel 接收配置，通过 `mpsc` channel 上报数据
4. **单入口 data channel** — 所有插件共享一个 `mpsc::channel::<Frame>(1024)`，network 模块统一发送

关键设计决策：
- **watch + mpsc 双通道** — `watch` 用于服务器推送配置到插件（多消费者最新值），`mpsc` 用于插件上报数据到网络层（多生产者有序队列）
- **device_uid 持久化** — UUID 首次生成后写入 `device_uid.txt`，与可执行文件同目录
- **device_secret 持久化** — 注册成功后写入 `device_secret.txt`，重启后自动认证

## 代码逻辑

### 启动流程

```
main() → load device_uid → load device_secret → create ClientState
       → create data channel (mpsc 1024)
       → create watch channels for each plugin config
       → spawn core tasks (monitor, asset, usb)
       → spawn plugin tasks (11 plugins)
       → reconnect loop: connect_and_run() with exponential backoff
```

### 网络层 (`network/mod.rs`)

- `connect_and_run()` — TCP 连接、注册/认证、双工读写循环
- `handle_server_message()` — 根据 MessageType 分发服务器下发的帧到对应 watch channel
- `PluginChannels` — 持有所有插件的 `watch::Sender`，用于接收服务器推送的配置
- 注册流程：发送 Register → 收到 RegisterResponse（含 device_secret）→ 持久化 secret
- 认证流程：已有 device_secret 时，心跳帧携带 HMAC-SHA256 签名

### 插件统一模板

每个插件遵循相同模式：
```rust
pub async fn start(
    mut config_rx: watch::Receiver<PluginConfig>,
    data_tx: mpsc::Sender<Frame>,
    device_uid: String,
) {
    loop {
        tokio::select! {
            result = config_rx.changed() => { /* 更新 config */ }
            _ = interval.tick() => {
                if !config.enabled { continue; }
                // 采集数据 → Frame::new_json() → data_tx.send()
            }
        }
    }
}
```

### 双模式运行

- **控制台模式**: 直接 `cargo run -p csm-client`，Ctrl+C 优雅退出
- **服务模式**: `--install` 注册 Windows 服务、`--service` 以服务方式运行、`--uninstall` 卸载

## 关联模块

- [[protocol]] — 使用 Frame 构造上报帧，解析服务器下发帧
- [[server]] — TCP 连接的对端，接收帧并处理
- [[plugins]] — 每个插件的具体实现逻辑

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/client/src/main.rs` | 启动入口、插件 channel 创建、task spawn、重连循环 |
| `crates/client/src/network/mod.rs` | TCP 连接、注册认证、双工读写、服务器消息分发 |
| `crates/client/src/service.rs` | Windows 服务安装/卸载/运行（`#[cfg(target_os = "windows")]`） |
| `crates/client/src/monitor/mod.rs` | 核心设备状态采集（CPU/内存/进程） |
| `crates/client/src/asset/mod.rs` | 硬件/软件资产采集 |
| `crates/client/src/usb/mod.rs` | USB 设备插拔监控 |
| `crates/client/src/web_filter/mod.rs` | 上网拦截插件 |
| `crates/client/src/usage_timer/mod.rs` | 使用时长记录插件 |
| `crates/client/src/software_blocker/mod.rs` | 软件禁止安装插件 |
| `crates/client/src/popup_blocker/mod.rs` | 弹窗拦截插件 |
| `crates/client/src/usb_audit/mod.rs` | U盘文件操作审计插件 |
| `crates/client/src/watermark/mod.rs` | 屏幕水印插件 |
| `crates/client/src/disk_encryption/mod.rs` | 磁盘加密检测插件 |
| `crates/client/src/print_audit/mod.rs` | 打印审计插件 |
| `crates/client/src/clipboard_control/mod.rs` | 剪贴板管控插件 |
| `crates/client/src/patch/mod.rs` | 补丁管理插件 |