csm/AUDIT_REPORT.md

# CSM 系统功能审计报告

> **审计日期**: 2026-04-06
> **审计范围**: 全系统 (Protocol + Server + Client + Frontend)
> **审计方法**: 五步审计流程 + 十项通用检查 + 五种差距模式识别

---

## 1. 功能清单与设计意图

### 1.1 核心功能 (10项)

| # | 功能 | 设计目标 | 业务价值 | 完成度 |
|---|------|---------|---------|--------|
| F1 | 设备注册与管理 | 设备身份认证、在线状态追踪 | 资产可见性 | **95%** |
| F2 | 实时状态监控 | CPU/内存/进程/磁盘/网络采集 | 运维告警基础 | **70%** |
| F3 | 硬件/软件资产采集 | 硬件信息+已安装软件清单 | 资产管理 | **90%** |
| F4 | USB设备管控 | 策略化USB设备接入控制 | 数据防泄露 | **85%** |
| F5 | 心跳与HMAC验证 | 连接存活检测+防伪造 | 通信安全 | **95%** |
| F6 | JWT认证与权限 | 登录/刷新/角色鉴权 | 访问控制 | **90%** |
| F7 | WebSocket实时推送 | 设备上下线/告警实时通知 | 运维效率 | **85%** |
| F8 | 告警规则与通知 | 自定义告警+邮件/Webhook | 主动监控 | **80%** |
| F9 | 分组管理 | 设备分组+配置三级作用域 | 批量管理 | **85%** |
| F10 | 管理审计日志 | 管理员操作追溯 | 合规审计 | **80%** |

**综合核心功能完成度: 85.5%**

### 1.2 客户端插件 (9项)

| # | 插件 | 设计目标 | 业务价值 | 完成度 | 关键问题 |
|---|------|---------|---------|--------|---------|
| P1 | 水印 (watermark) | 屏幕叠加用户信息水印 | 拍照溯源 | **90%** | 不上报执行状态 |
| P2 | 上网行为管理 (web_filter) | 通过hosts文件拦截URL | 网络安全 | **70%** | 不上报访问日志 |
| P3 | 使用时长统计 (usage_timer) | 活跃/空闲时间+应用使用量 | 行为分析 | **85%** | - |
| P4 | 软件黑名单 (software_blocker) | 检测并终止违规软件 | 软件合规 | **85%** | - |
| P5 | 弹窗拦截 (popup_blocker) | 按规则关闭弹窗窗口 | 用户体验 | **80%** | 不上报拦截统计 |
| P6 | USB文件审计 (usb_audit) | 监控USB驱动器文件操作 | 数据泄露取证 | **85%** | - |
| P7 | USB设备监控 (usb) | USB设备插拔检测+策略执行 | 设备管控 | **80%** | vendor_id/serial匹配是placeholder |
| P8 | 系统监控 (monitor) | 周期性采集设备状态 | 基础监控 | **70%** | 磁盘/网络指标始终为0 |
| P9 | 磁盘加密 (disk_encryption) | BitLocker状态上报 | 数据保护 | **5%** | 全链路断裂(死代码) |

**综合插件完成度: 72.2%**

### 1.3 未实现功能 (3项)

| # | 功能 | 状态 | 有Migration | 有代码 |
|---|------|------|------------|--------|
| N1 | 打印审计 (print_audit) | 完全缺失 | 有(013) | 无 |
| N2 | 剪贴板控制 (clipboard_control) | 完全缺失 | 有(014) | 无 |
| N3 | 插件远程启禁 (PluginControl) | 半实现 | - | 仅客户端侧 |

---

## 2. 五步审计流程详情

### 2.1 文档对齐 — 代码 vs CLAUDE.md

| 检查项 | 结果 | 详情 |
|--------|------|------|
| 协议MessageType编号范围 | ⚠️ 部分一致 | CLAUDE.md记载 0x9x=加密/打印/剪贴板，实际仅磁盘加密有部分代码(未接入) |
| API路由 kebab-case | ✅ 一致 | 所有路由遵循 kebab-case 命名 |
| 配置推送三级作用域 | ✅ 一致 | `push_to_targets()` 支持 global/group/device |
| 插件模板统一性 | ⚠️ 不完全 | `disk_encryption` 未在 main.rs 声明 `mod` |
| 二进制协议格式 | ✅ 一致 | MAGIC+VERSION+TYPE+LENGTH+PAYLOAD |
| 插件开发必改清单 | ⚠️ 不完全 | disk_encryption 未按清单完整执行 |

### 2.2 数据流追踪

#### 端到端完整的功能链路 (12项)

```
[Client 插件] --MessageType Frame--> [Server process_frame] --DB写入--> [API查询] --HTTP--> [前端页面]
```

| 功能 | 链路完整性 | 断裂点 |
|------|-----------|--------|
| 设备注册 | ✅ 完整 | — |
| 状态上报 | ✅ 完整 | — |
| 硬件资产 | ✅ 完整 | — |
| 软件资产 | ✅ 完整 | — |
| USB事件上报 | ✅ 完整 | — |
| USB策略推送 | ✅ 完整 | — |
| 水印配置 | ✅ 完整 | 无上报反馈 |
| 上网过滤配置 | ⚠️ 配置推送正常 | 客户端不上报拦截日志 |
| 使用时长 | ✅ 完整 | — |
| 软件黑名单 | ✅ 完整 | — |
| 弹窗拦截配置 | ⚠️ 配置推送正常 | 客户端不上报拦截统计 |
| USB文件审计 | ✅ 完整 | — |
| 磁盘加密 | ❌ 全链路断裂 | 见下方详情 |
| 插件远程启禁 | ❌ 无服务端触发 | 见下方详情 |

#### 断裂链路详情

**1. 磁盘加密 — 全链路断裂**

```
Protocol: 无 DiskEncryptionStatusPayload 等类型
Client: disk_encryption/mod.rs 存在但 main.rs 未声明 mod
Server: disk_encryption.rs handler 存在但 plugins/mod.rs 未注册路由
TCP: process_frame 无 DiskEncryptionStatus 处理分支
DB: Migration 012 存在但 main.rs 未 include
前端: 无对应页面/路由
```

**2. PluginEnable/PluginDisable — 无触发源**

```
Protocol: PluginControlPayload 已定义 ✅
Client: handle_plugin_control() 已实现 ✅
Server: 无API端点发送此消息 ❌
Server: push_all_plugin_configs() 未推送插件启禁状态 ❌
```

**3. TaskExecute — 客户端未实现**

```
Protocol: TaskExecutePayload 已定义 ✅
Server: 可发送 (仅在设备删除时发 SelfDestruct) ⚠️
Client: 接收后只 log "not yet implemented" ❌
```

**4. ConfigUpdate — 客户端未实现**

```
Protocol: ConfigUpdateType (UpdateIntervals/TlsCertRotate/SelfDestruct) 已定义 ✅
Client: 接收后只 log，不做任何处理 ❌
```

**5. WebAccessLog — 客户端不上报**

```
Protocol: WebAccessLogEntry 已定义 ✅
Server: process_frame 有 WebAccessLog 插入分支 ✅
Server DB: web_access_log 表存在 ✅
Client: web_filter 插件修改 hosts 但不拦截日志 ❌
前端: WebFilter.vue 有访问日志tab，但数据永远为空 ❌
```

### 2.3 Dead Code 识别

#### 服务端

| 位置 | 类型 | 说明 |
|------|------|------|
| `api/plugins/disk_encryption.rs` | 未注册路由 | 3个handler函数从未被调用 |
| `device.rs: UsbPolicy/UsbPolicyType/UsbDevicePattern` | 未使用类型 | 被 message.rs 中的 UsbPolicyPayload 替代 |
| `Cargo.toml: include_dir` | 未使用依赖 | 未被任何代码引用 |
| `Migrations 012/013/014` | 未include | main.rs 只include 001-011 |

#### 客户端

| 位置 | 类型 | 说明 |
|------|------|------|
| `disk_encryption/mod.rs` | 未编译模块 | main.rs 无 `mod disk_encryption;` |
| `network/mod.rs.tmp.575580.1775308681874` | 临时文件 | 残留的旧版本文件 |
| `monitor/mod.rs: disk_usage/disk_total_mb/network_*` | TODO占位 | 始终上报0值 |

#### 协议层

| 位置 | 类型 | 说明 |
|------|------|------|
| `AlertAck (0x07)` | 无发送/接收方 | 完全死代码 |
| `WebAccessLogEntry` | 结构体未使用 | 定义但客户端从未发送 |
| `TaskExecutePayload` | 结构体未使用 | 定义但从未有效使用 |
| `ConfigUpdateType` | 枚举未使用 | 定义但客户端不处理 |
| `AssetChange/AssetChangeType` | 类型未使用 | 定义但无发送方 |

#### 前端

| 位置 | 类型 | 说明 |
|------|------|------|
| `package.json: dayjs` | 未使用依赖 | 零引用 |
| `package.json: @vueuse/core` | 未使用依赖 | 零引用 |
| `stores/devices.ts: fetchDeviceHistory` | 未调用方法 | store action无调用方 |
| `stores/devices.ts: DeviceStatusDetail` | 未使用导出 | 仅内部使用 |

### 2.4 接口实现检查

| 接口 | 状态 | 说明 |
|------|------|------|
| Frame 编解码 | ✅ 完整 | new/new_json/encode/decode/decode_payload |
| DeviceRepo DB操作 | ✅ 一致 | 静态方法+pool参数模式 |
| API handler | ✅ 一致 | axum State提取模式 |
| 客户端插件 start() | ⚠️ 不统一 | monitor/asset 无 watch channel；watermark/popup/web_filter 无 data_tx |

### 2.5 端到端验证总结

| 通过 | 警告 | 失败 |
|------|------|------|
| 10 | 2 | 2 |

---

## 3. 十项通用审计检查

| # | 检查项 | 评分 | 详情 |
|---|--------|------|------|
| 1 | 代码存在性 | ⚠️ 7/10 | 磁盘加密代码存在未接入；打印/剪贴板仅有migration |
| 2 | 调用链连通性 | ⚠️ 6/10 | 5条断裂链路：磁盘加密、插件控制、WebAccessLog、AssetChange、TaskExecute |
| 3 | 配置参数传递 | ✅ 9/10 | 插件watch channel链路完整；API到TCP推送完整 |
| 4 | 降级策略 | ⚠️ 7/10 | 重连有退避；TLS可选；无本地缓存/离线模式 |
| 5 | 错误处理 | ⚠️ 6/10 | 后端完备；前端多处catch {}静默吞错误 |
| 6 | 日志完整性 | ✅ 9/10 | tracing覆盖完整；审计日志自动记录 |
| 7 | 性能指标监控 | ⚠️ 5/10 | 磁盘/网络指标为0；无APM |
| 8 | 安全控制 | ✅ 9/10 | JWT+HMAC+TLS+限流+审计日志 |
| 9 | 兼容性 | ⚠️ 6/10 | 3套HTTP客户端；DDL与API不一致 |
| 10 | 文档代码同步 | ⚠️ 7/10 | CLAUDE.md部分超前(打印/剪贴板) |

**综合评分: 7.1/10**

---

## 4. 五种差距模式

### 模式1: "写了没接" (5项)

| 组件 | 位置 | 断裂点 |
|------|------|--------|
| disk_encryption 客户端 | `client/src/disk_encryption/` | main.rs 无 mod 声明 + protocol 无类型 |
| disk_encryption 服务端 | `server/src/api/plugins/disk_encryption.rs` | plugins/mod.rs 无注册 |
| Migration 012/013/014 | `migrations/` | main.rs 未 include |
| PluginEnable/Disable | protocol message.rs | 服务端无发送API |
| ConfigUpdate | 客户端 network/mod.rs | 客户端只log不处理 |

### 模式2: "接了没传" (4项)

| 组件 | 缺失数据 |
|------|---------|
| Monitor 状态上报 | disk_usage/disk_total_mb/network_rx_rate/network_tx_rate 始终为0 |
| Web Filter 插件 | 不上报 WebAccessLog 拦截记录 |
| Popup Blocker 插件 | 不上报拦截统计 |
| Watermark 插件 | 不上报执行状态 |

### 模式3: "传了没存" (1项)

| 组件 | 问题 |
|------|------|
| WebAccessLog | Server有DB handler，但Client从未发送，web_access_log表始终为空 |

### 模式4: "存了没用" (4项)

| 组件 | 问题 |
|------|------|
| device_groups 表 | DDL支持层级(parent_id)，API只支持扁平分组 |
| plugin_state 表 | migration 010创建，无API读写 |
| popup_block_stats 表 | 有查询但无写入，始终为空 |
| AssetChange 事件 | protocol定义但无生成逻辑 |

### 模式5: "双系统不同步" (4项)

| 组件 | 不一致 |
|------|--------|
| Protocol USB类型 | UsbPolicy vs UsbPolicyPayload 两套定义 |
| 前端 HTTP 客户端 | api.ts vs devices.ts vs Devices.vue 三套实现 |
| 插件前端调用 | 2个用api.ts，4个用raw fetch手动header |
| Migration vs Binary | 14个SQL文件，binary只含11个 |

---

## 5. 问题清单 (按严重级别)

### CRITICAL — 阻塞功能完整性 (3项)

#### C-1: disk_encryption 全链路断裂

**影响**: 磁盘加密功能完全不可用

**涉及文件**:
- `crates/protocol/src/message.rs` — 缺少 `DiskEncryptionStatus` 等MessageType和Payload
- `crates/protocol/src/lib.rs` — 缺少 re-export
- `crates/client/src/main.rs` — 缺少 `mod disk_encryption;`
- `crates/client/src/disk_encryption/mod.rs` — 引用不存在的protocol类型
- `crates/server/src/api/plugins/mod.rs` — 缺少 `pub mod disk_encryption;` 和路由注册
- `crates/server/src/tcp.rs` — 缺少 process_frame 分支
- `crates/server/src/main.rs` — 缺少 `include_str!("../../migrations/012_disk_encryption.sql")`

**修复方案**: 按照 CLAUDE.md 的"新增插件必改文件清单"，逐项补全10个文件的修改。

---

#### C-2: PluginEnable/PluginDisable 无服务端触发源

**影响**: 管理员无法通过前端远程启用/禁用客户端插件

**涉及文件**:
- `crates/server/src/api/plugins/mod.rs` — 需新增插件启禁API
- `crates/server/src/tcp.rs` — 需在push_all_plugin_configs中推送plugin_state
- `web/src/views/` — 需新增插件管理页面

**修复方案**:
1. 在 `plugin_state` 表基础上新增 API: `POST /api/plugins/:name/enable`, `POST /api/plugins/:name/disable`
2. API handler 写入 plugin_state 表 + 通过 TCP 发送 PluginEnable/PluginDisable
3. push_all_plugin_configs 中查询 plugin_state 并推送

---

#### C-3: print_audit / clipboard_control 完全缺失

**影响**: 打印审计和剪贴板控制功能完全不可用

**涉及文件**:
- `crates/server/src/main.rs` — 需 include migrations 013/014
- 其余所有文件均需从零创建

**修复方案**: 按 CLAUDE.md 清单逐步实现。优先级低于 C-1（可先修复 disk_encryption 作为模板）。

---

### HIGH — 影响数据完整性/用户体验 (8项)

#### H-1: Monitor 磁盘/网络指标始终为0

**文件**: `crates/client/src/monitor/mod.rs:79`
**修复**: 使用 Windows API 或 PowerShell 采集磁盘使用率和网络速率

---

#### H-2: Web Filter 不上报访问日志

**文件**: `crates/client/src/web_filter/mod.rs`
**修复**: 在 hosts 拦截生效后，无法直接通过 hosts 方案检测拦截事件。需改为 DNS 代理或浏览器扩展方案才能真正上报访问日志。

**当前状态**: hosts文件方案的技术限制决定了无法准确检测拦截事件。建议将此标记为"已知限制"而非BUG。

---

#### H-3: Popup Blocker 不上报拦截统计

**文件**: `crates/client/src/popup_blocker/mod.rs`
**修复**: 在关闭弹窗时，通过 data_tx 发送拦截统计消息（需新增 MessageType 或复用现有类型）

---

#### H-4: 前端3套HTTP客户端不统一

**文件**:
- `web/src/lib/api.ts` — 标准客户端(fetch)
- `web/src/stores/devices.ts` — 独立axios实例
- `web/src/views/Devices.vue` — 又一个axios实例

**修复**: 统一使用 api.ts，devices store 和 Devices.vue 改用 api 对象

---

#### H-5: 4个插件视图用raw fetch绕过api.ts

**文件**:
- `web/src/views/plugins/UsageTimer.vue`
- `web/src/views/plugins/SoftwareBlocker.vue`
- `web/src/views/plugins/PopupBlocker.vue`
- `web/src/views/plugins/UsbFileAudit.vue`

**修复**: 将 raw fetch 调用改为 `api.get()`/`api.post()` 等方法

---

#### H-6: 前端多处静默吞错误

**文件与行号**:
- `Layout.vue` — fetchUnreadAlerts catch {}
- `Dashboard.vue` — 数据加载 catch {}
- `DeviceDetail.vue` — 多处 catch {}
- `Settings.vue` — health check catch {}
- `UsbPolicy.vue` — 多处 catch {}

**修复**: 将 catch {} 改为 `ElMessage.error()` 展示错误信息

---

#### H-7: UsbPolicy 两套并行定义

**文件**:
- `crates/protocol/src/device.rs` — `UsbPolicy`/`UsbPolicyType`/`UsbDevicePattern`
- `crates/protocol/src/message.rs` — `UsbPolicyPayload`/`UsbDeviceRule`

**修复**: 删除 device.rs 中未使用的 `UsbPolicy` 等类型，统一使用 message.rs 中的定义

---

#### H-8: device_groups 表层级设计与API不一致

**文件**: `migrations/001_init.sql` — parent_id 列
**API**: `crates/server/src/api/groups.rs` — 仅扁平分组

**修复**: 要么移除 parent_id 列，要么实现层级分组功能。建议当前先移除 parent_id（非必要功能）。

---

### MEDIUM — 代码质量/维护性 (9项)

| ID | 问题 | 修复 |
|----|------|------|
| M-1 | `network/mod.rs.tmp.*` 临时文件 | 删除文件 |
| M-2 | `include_dir` Cargo依赖未使用 | 从 Cargo.toml 移除 |
| M-3 | `dayjs`/`@vueuse/core` npm依赖未使用 | 从 package.json 移除 |
| M-4 | 多个未使用的协议类型 | 清理或标记为reserved |
| M-5 | `fetchDeviceHistory` store action 无调用方 | 移除或实现前端历史图表 |
| M-6 | PopupBlocker.vue 表单缺 enabled 字段 | 添加 enabled 开关 |
| M-7 | 前端大量 `any` 类型 | 定义 TypeScript 接口 |
| M-8 | 无前端测试 | 添加 vitest + @vue/test-utils |
| M-9 | 3个插件不反馈执行状态 | 添加状态上报消息 |

---

## 6. 修复优先级路线图

### Phase 1: 关键链路修复 (C-1, C-2)
1. 修复 disk_encryption 全链路 (protocol -> client -> server -> migration)
2. 添加 PluginControl API (plugin_state CRUD + TCP推送)

### Phase 2: 数据完整性 (H-1, H-3, H-7)
3. 实现 Monitor 磁盘/网络指标采集
4. 添加 Popup Blocker 拦截统计上报
5. 清理 Protocol 重复类型

### Phase 3: 前端统一化 (H-4, H-5, H-6)
6. 统一 HTTP 客户端为 api.ts
7. 修复前端静默错误处理
8. 添加 PopupBlocker enabled 字段

### Phase 4: 代码清洁 (M-*)
9. 清理临时文件和未使用依赖
10. 清理未使用协议类型

### Phase 5: 新功能 (C-3)
11. 实现 print_audit 插件
12. 实现 clipboard_control 插件

---

## 7. 统计摘要

| 指标 | 数值 |
|------|------|
| 核心功能完成度 | 85.5% |
| 插件完成度 | 72.2% |
| 综合完成度 | **80.4%** |
| CRITICAL 问题 | 3 |
| HIGH 问题 | 8 |
| MEDIUM 问题 | 9 |
| 端到端通过链路 | 10/14 (71.4%) |
| Dead Code 项 | 15+ |
| "写了没接" 差距 | 5 |
| "接了没传" 差距 | 4 |
| "传了没存" 差距 | 1 |
| "存了没用" 差距 | 4 |
| "双系统不同步" 差距 | 4 |