# Windows 监控管理系统接口说明

## 基础信息

- 后端默认地址：`http://127.0.0.1:8000`
- 返回格式：JSON
- 确认状态枚举：`PENDING`、`TRUSTED`、`SUSPICIOUS`、`IGNORED`、`NEED_MORE_INFO`
- AI 风险等级枚举：`LOW`、`MEDIUM`、`HIGH`

## 仪表盘

### 获取仪表盘概览

`GET /api/dashboard`

返回最近扫描记录、服务总数、进程总数、待确认数量、本次未出现数量。

## 标签

系统内置两个默认标签：

| 标签 | 默认是否可以被控制 | 说明 |
| --- | --- | --- |
| windows系统 | 否 | 用于标记 Windows 系统原生服务或进程 |
| 本系统相关 | 否 | 用于标记本项目自身相关服务或进程 |

如果服务或进程存在任一 `is_controllable = false` 的标签，前端不会显示启动、停止、重启等控制操作，后端控制接口也会拒绝执行。

### 查询标签

`GET /api/tags`

### 新增标签

`POST /api/tags`

```json
{
  "name": "业务软件",
  "description": "业务系统相关组件",
  "is_controllable": true
}
```

### 更新标签

`PATCH /api/tags/{tag_id}`

```json
{
  "name": "windows系统",
  "description": "Windows 系统原生服务或进程",
  "is_controllable": false
}
```

### 删除标签

`DELETE /api/tags/{tag_id}`

内置标签不可删除。

## 扫描

### 执行完整扫描

`POST /api/scans/run`

执行 Windows 服务和进程采集，写入扫描记录，并按业务规则更新 `is_present_now`、`last_seen_at`、运行状态等字段。

### 查询扫描历史

`GET /api/scans?page=1&page_size=20`

### 查询扫描详情

`GET /api/scans/{scan_id}`

## 传感器

### 获取实时传感器信息

`GET /api/sensors`

说明：

- 数据不写入数据库。
- CPU、内存负载来自 `psutil`。
- 显卡优先使用 `nvidia-smi`；如果不可用，尝试 Windows GPU 性能计数器。
- 温度优先读取 LibreHardwareMonitor/OpenHardwareMonitor WMI，其次尝试 `psutil` 和 ACPI 热区。
- Windows 原生接口不一定能提供 CPU/GPU 真实温度，实际可见字段取决于硬件、驱动和监控组件。

返回主要字段：

| 字段 | 说明 |
| --- | --- |
| collected_at | 采集时间 |
| cpu | CPU 总负载、每核心负载、核心数、频率 |
| memory | 物理内存和交换区使用情况 |
| gpu | 显卡负载、温度、显存、功耗等 |
| temperatures | psutil/ACPI 温度 |
| hardware_sensors | LibreHardwareMonitor/OpenHardwareMonitor 传感器 |

## 硬盘 SMART

### 扫描 smartctl 设备列表

`GET /api/smart/scan`

等价于执行：

```powershell
smartctl --scan
```

### 获取全部硬盘 SMART 信息

`GET /api/smart/devices?include_jmb39x=true&jmb39x_slots=8`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| include_jmb39x | boolean | 是否对 SAT/ATA 类设备额外探测 JMB39x 阵列槽位 |
| jmb39x_slots | integer | 探测槽位数量，范围 0-16，默认 8 |

普通设备会按 `smartctl --scan` 返回的设备和类型执行：

```powershell
smartctl -a -d sat /dev/sdb
```

JMB39x 阵列会按槽位执行：

```powershell
smartctl -a -d jmb39x,0 /dev/sdb
smartctl -a -d jmb39x,1 /dev/sdb
```

返回每块盘的解析摘要、ATA SMART 属性表、警告信息和原始 `smartctl` 输出。

### 获取单个设备 SMART 信息

`GET /api/smart/device?device=/dev/sda&device_type=nvme`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| device | string | 设备路径，例如 `/dev/sda` |
| device_type | string | 可选，smartctl 的 `-d` 类型，例如 `nvme`、`sat`、`jmb39x,0` |

## Windows 服务

### 查询服务列表

`GET /api/services`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| keyword | string | 按名称、显示名称、路径、描述搜索 |
| confirm_status | string | 确认状态 |
| present | boolean | `true` 本次出现，`false` 本次未出现 |
| page | integer | 页码，默认 1 |
| page_size | integer | 每页数量，默认 20，最大 200 |

### 获取服务详情

`GET /api/services/{service_id}`

### 更新服务说明和状态

`PATCH /api/services/{service_id}`

请求体：

```json
{
  "confirm_status": "TRUSTED",
  "user_note": "人工确认说明"
}
```

### 批量更新服务状态

`PATCH /api/services/batch`

请求体：

```json
{
  "ids": [1, 2, 3],
  "confirm_status": "SUSPICIOUS",
  "user_note": "批量标记说明，可为空"
}
```

### 根据 AI JSON 批量更新服务

`POST /api/services/import-ai`

请求体：

```json
{
  "items": [
    {
      "type": "service",
      "name": "WinDefend",
      "description": "Microsoft Defender 防病毒核心服务。",
      "judgement": "TRUSTED",
      "risk_level": "LOW",
      "reason": "Microsoft 官方安全组件。",
      "suggestion": "保持运行。"
    }
  ]
}
```

### 生成服务 AI 分析提示词

`POST /api/services/ai-prompt`

请求体：

```json
{
  "scope": "selected",
  "ids": [1, 2]
}
```

说明：

- `scope = selected` 时使用 `ids` 指定的服务。
- `scope = pending` 时忽略 `ids`，生成全部待确认服务的提示词。
- 返回 `prompt_text`、`markdown_table` 和 `items`。

### 更新服务标签

`PUT /api/services/{service_id}/tags`

```json
{
  "tag_ids": [1, 2]
}
```

### 启动服务

`POST /api/services/{service_id}/start`

### 停止服务

`POST /api/services/{service_id}/stop`

### 重新启动服务

`POST /api/services/{service_id}/restart`

控制规则：

- `confirm_status` 必须是 `TRUSTED`、`SUSPICIOUS` 或 `IGNORED`。
- `PENDING` 和 `NEED_MORE_INFO` 不允许控制。
- 任一关联标签 `is_controllable = false` 时不允许控制。
- 服务必须在最近一次扫描中仍然存在。

## Windows 进程

### 查询进程列表

`GET /api/processes`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| keyword | string | 按名称、路径、命令行、用户搜索 |
| confirm_status | string | 确认状态 |
| present | boolean | `true` 本次出现，`false` 本次未出现 |
| page | integer | 页码，默认 1 |
| page_size | integer | 每页数量，默认 20，最大 200 |

### 获取进程详情

`GET /api/processes/{process_id}`

### 更新进程说明和状态

`PATCH /api/processes/{process_id}`

请求体：

```json
{
  "confirm_status": "SUSPICIOUS",
  "user_note": "人工确认说明"
}
```

### 批量更新进程状态

`PATCH /api/processes/batch`

请求体：

```json
{
  "ids": [10, 11],
  "confirm_status": "IGNORED",
  "user_note": "批量忽略说明，可为空"
}
```

### 根据 AI JSON 批量更新进程

`POST /api/processes/import-ai`

请求体：

```json
{
  "items": [
    {
      "type": "process",
      "name": "unknown.exe",
      "description": "未知用途执行文件。",
      "judgement": "SUSPICIOUS",
      "risk_level": "HIGH",
      "reason": "路径和命令行异常。",
      "suggestion": "建议隔离并检查哈希和网络连接。"
    }
  ]
}
```

### 生成进程 AI 分析提示词

`POST /api/processes/ai-prompt`

请求体：

```json
{
  "scope": "pending"
}
```

返回 `prompt_text`、`markdown_table` 和 `items`。

### 更新进程标签

`PUT /api/processes/{process_id}/tags`

```json
{
  "tag_ids": [2]
}
```

### 启动进程

`POST /api/processes/{process_id}/start`

使用数据库中记录的 `cmdline` 或 `exe_path` 重新启动进程。

### 停止进程

`POST /api/processes/{process_id}/stop`

使用数据库中记录的 `last_pid` 停止进程，并校验当前 PID 的进程名与记录一致，避免误杀 PID 复用后的其他进程。

控制规则：

- `confirm_status` 必须是 `TRUSTED`、`SUSPICIOUS` 或 `IGNORED`。
- `PENDING` 和 `NEED_MORE_INFO` 不允许控制。
- 任一关联标签 `is_controllable = false` 时不允许控制。
- 停止进程要求该进程在最近一次扫描中仍然存在。

## AI 提示词中的标签信息

服务和进程的 AI 提示词会包含：

- 每个待分析对象的 `tags` 字段。
- 系统中已有标签列表，包括 `name`、`description`、`is_controllable`。
- 标签判断要求：AI 需要结合已有标签进行分析，如果适合已有标签，可以在 `suggestion` 中建议使用对应标签名称，但不能创造不存在的新标签。