TermControlAgent/docs/system_api.md

# 系统API文档

## 概述

系统API提供了获取机器码和系统信息的功能，支持Windows和Linux系统，遵循项目的分层架构设计。

## API端点

### 1. 获取机器码

**端点：** `GET /api/v1/system/machine-code`

**描述：** 获取当前系统的机器码

**响应示例：**
```json
{
  "success": true,
  "message": "机器码获取成功",
  "data": {
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "system_type": "windows",
    "method": "wmic csproduct get uuid"
  }
}
```

### 2. 获取系统信息

**端点：** `GET /api/v1/system/info`

**描述：** 获取当前系统的详细信息

**响应示例：**
```json
{
  "success": true,
  "message": "系统信息获取成功",
  "data": {
    "system_type": "windows",
    "platform": "Windows-10-10.0.17763-SP0",
    "architecture": "64bit",
    "processor": "AMD64 Family 23 Model 24 Stepping 1, AuthenticAMD",
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "python_version": "3.10.5"
  }
}
```

### 3. 获取详细机器码信息

**端点：** `GET /api/v1/system/machine-code/detailed`

**描述：** 获取包含系统信息的详细机器码信息

**响应示例：**
```json
{
  "success": true,
  "message": "详细机器码信息获取成功",
  "data": {
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "system_type": "windows",
    "method": "wmic csproduct get uuid",
    "system_info": {
      "system_type": "windows",
      "platform": "Windows-10-10.0.17763-SP0",
      "architecture": "64bit",
      "processor": "AMD64 Family 23 Model 24 Stepping 1, AuthenticAMD",
      "machine_code": "03000200-0400-0500-0006-000700080009",
      "python_version": "3.10.5"
    },
    "timestamp": "2025-08-15T15:21:54.205977"
  }
}
```

### 4. 系统健康检查

**端点：** `GET /api/v1/system/health`

**描述：** 检查系统基本功能是否正常

**响应示例：**
```json
{
  "success": true,
  "message": "系统健康检查通过",
  "data": {
    "system_type": "windows",
    "machine_code_available": true,
    "status": "healthy"
  }
}
```

## 技术实现

### Windows系统
- 主要方法：`wmic csproduct get uuid`
- 备用方法：PowerShell `Get-WmiObject -Class Win32_ComputerSystemProduct`

### Linux系统
- 主要方法：`dmidecode -s system-serial-number`
- 备用方法1：读取 `/sys/class/dmi/id/product_serial`
- 备用方法2：`hostid` 命令

### 错误处理
- 命令执行超时处理
- 多种备用方案确保兼容性
- 详细的错误日志记录

## 架构设计

```
API端点层 (app/api/v1/endpoints/system.py)
    ↓
服务层 (app/services/system_service.py)
    ↓
工具层 (app/utils/system_utils.py)
    ↓
系统命令执行
```

## 使用示例

### Python客户端
```python
import requests

# 获取机器码
response = requests.get("http://localhost:8000/api/v1/system/machine-code")
machine_code = response.json()["data"]["machine_code"]

# 获取系统信息
response = requests.get("http://localhost:8000/api/v1/system/info")
system_info = response.json()["data"]
```

### curl命令
```bash
# 获取机器码
curl -X GET "http://localhost:8000/api/v1/system/machine-code"

# 获取系统信息
curl -X GET "http://localhost:8000/api/v1/system/info"

# 系统健康检查
curl -X GET "http://localhost:8000/api/v1/system/health"
```

## 注意事项

1. **权限要求**：某些系统命令可能需要管理员权限
2. **兼容性**：不同系统版本可能有差异，已提供多种备用方案
3. **性能**：命令执行有超时限制，避免长时间阻塞
4. **安全性**：仅获取系统标识信息，不涉及敏感数据