CadHubManage/Readme.md

# CadHubManage

基于WebSocket的实时软件控制管理系统，用于通过Web接口控制Windows服务器上的软件。

## 项目方案设计

### 一、技术架构概述

**核心技术栈：**
- 后端：Python + FastAPI
- 实时通信：WebSocket（纯WebSocket架构）
- 进程管理：subprocess + psutil
- 数据格式：JSON
- 日志系统：异步文件存储

### 二、项目目录结构

```
project-root/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 主入口
│   ├── config.py               # 配置文件
│   │
│   ├── api/                    # API 路由
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── websocket.py   # WebSocket API（所有功能）
│   │
│   ├── core/                   # 核心功能
│   │   ├── __init__.py
│   │   ├── security.py         # JWT 认证逻辑
│   │   ├── software_manager.py # 软件管理核心类
│   │   ├── process_monitor.py  # 进程监控
│   │   ├── websocket_manager.py # WebSocket 连接管理
│   │   └── log_manager.py      # 操作日志管理
│   │
│   ├── models/                 # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py            # 用户模型
│   │   ├── software.py        # 软件定义模型
│   │   ├── task.py            # 任务模型
│   │   └── operation_log.py   # 操作日志模型
│   │
│   ├── schemas/                # Pydantic 模型
│   │   ├── __init__.py
│   │   ├── auth.py            # 认证请求/响应模型
│   │   ├── software.py        # 软件操作请求/响应模型
│   │   └── task.py            # 任务状态模型
│   │
│   ├── services/               # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── software_service.py # 软件操作服务
│   │   └── notification.py     # 通知服务
│   │
│   └── utils/                  # 工具函数
│       ├── __init__.py
│       ├── logger.py           # 日志配置
│       └── exceptions.py       # 自定义异常
│
├── configs/                    # 配置文件目录
│   ├── software_config.yaml    # 软件配置（路径、参数等）
│   └── users.json             # 用户配置（简单认证）
│
├── logs/                       # 日志目录
│   ├── operation_logs/          # 操作日志文件目录
│   └── app.log                 # 系统日志文件
│
├── tests/                      # 测试目录
│   ├── __init__.py
│   └── test_software.py
│
├── requirements.txt            # Python 依赖
├── .env                       # 环境变量
├── .env.example               # 环境变量示例
└── README.md                  # 项目文档
```

### 三、核心功能设计

#### 1. **软件配置管理** (software_config.yaml)
```yaml
software:
  creo:
    name: "PTC Creo"
    executable_path: "C:\\Program Files\\PTC\\Creo 5.0.0.0\\Parametric\\bin\\parametric.exe"
    startup_args: []
    startup_timeout: 60
    check_process_name: ["xtop.exe", "pro_comm_msg.exe"]  # 支持多进程检测
    stop_timeout: 15  # 停止超时时间
    
  revit:
    name: "Autodesk Revit 2017"
    executable_path: "C:\\Program Files\\Autodesk\\Revit 2017\\Revit.exe"
    startup_args: ["/language", "CHS"]
    startup_timeout: 90
    check_process_name: "Revit.exe"
    
  autocad:
    name: "AutoCAD"
    executable_path: "C:\\Program Files\\Autodesk\\AutoCAD 2024\\acad.exe"
    startup_args: []
    startup_timeout: 45
    check_process_name: "acad.exe"
    
  pdms:
    name: "AVEVA PDMS 12.1 SP4"
    executable_path: "C:\\AVEVA\\Plant\\PDMS12.1.SP4\\pdms.bat"
    startup_args: ["Design", "noconsole"]
    startup_timeout: 120
    check_process_name: ["des.exe", "PDMSConsole.exe"]
    stop_timeout: 20
    
  # ... 其他软件配置
```

#### 2. **纯WebSocket架构**

**架构设计理念：**
- 所有功能通过WebSocket实现统一接口
- 实时双向通信，支持服务器主动推送
- 连接建立后通信开销小，性能优异
- 统一的JSON消息格式，易于开发和调试

**WebSocket功能覆盖：**
- 软件控制：启动、停止、重启、状态查询
- 日志管理：记录、查询、统计、清理
- 系统监控：服务状态、连接管理
- 实时通知：状态变化、错误推送

**WebSocket支持的消息类型：**
- `ping` - 心跳检测
- `get_status` - 获取服务状态
- `get_software_list` - 获取软件列表
- `start_software` - 启动软件
- `stop_software` - 停止软件
- `restart_software` - 重启软件
- `log_operation` - 记录用户操作日志
- `query_logs` - 查询操作日志
- `get_log_by_id` - 根据ID获取日志
- `get_log_stats` - 获取日志统计信息
- `cleanup_logs` - 清理过期日志
- `get_operation_types` - 获取操作类型列表

### 四、接口设计

#### 1. **WebSocket接口（主要API）**
```
WS     /api/v1/ws/connect          # WebSocket连接端点
```

**支持的消息类型：**
- 软件控制：`start_software`, `restart_software`, `get_software_list`
- 日志管理：`log_operation`, `query_logs`, `get_log_by_id`, `get_log_stats`, `cleanup_logs`, `get_operation_types`
- 系统监控：`ping`, `get_status`

#### 2. **HTTP接口（辅助功能）**
```
GET    /                           # 服务信息
GET    /health                     # 健康检查
```

### 五、WebSocket通信机制

#### 1. **连接管理**
- 支持多客户端同时连接
- 自动生成客户端ID
- 支持用户身份标识
- 连接状态实时监控

#### 2. **消息处理**
- 异步消息处理机制
- 任务立即返回ID
- 实时状态推送
- 统一错误处理

### 六、安全考虑

1. **进程隔离**
   - 限制可执行的软件白名单
   - 验证所有路径输入
   - 使用受限的进程权限

2. **API安全**
   - JWT认证
   - 请求频率限制
   - 日志审计

3. **网络安全**
   - WSS (WebSocket Secure) 传输
   - CORS配置，允许跨域
   - 连接状态监控和管理

### 七、监控与日志

1. **进程监控**
   - 使用psutil监控软件进程
   - 定期检查进程状态
   - 异常自动告警

2. **日志记录**
   - 操作日志：谁在什么时间启动了什么软件
   - 错误日志：启动失败原因
   - 性能日志：启动耗时统计

### 八、操作日志系统

#### 1. **日志类型**
- **系统操作日志** - 软件启动、重启等系统自动记录
- **用户操作日志** - 前端发送的用户自定义操作记录

#### 2. **日志存储**
- **格式** - JSON Lines (.jsonl) 格式
- **轮转** - 按日期自动分割文件
- **清理** - 自动清理过期日志文件
- **位置** - `logs/operation_logs/` 目录

#### 3. **日志查询**
- 支持按时间、类型、用户等多维度过滤
- 提供统计信息和操作类型汇总
- WebSocket实时查询接口
- 支持分页和复杂查询条件

### 九、开发注意事项

1. **软件启动检测**
   - 不同软件启动时间差异大
   - 需要合理的超时机制

2. **权限问题**
   - 服务运行账户需要有启动目标软件的权限
   - 某些软件可能需要桌面交互权限

3. **并发控制**
   - 限制同时启动的软件数量，一次只能启动1个，默认，也需要在配置文件中添加

4. **WebSocket连接管理**
   - 处理客户端断线重连
   - 消息队列和状态同步
   - 连接数量监控

5. **代码质量**
   - 消除硬编码，使用枚举和配置
   - 参数化所有可配置项
   - 遵循MVP设计原则
   - 纯WebSocket架构，统一接口

### 十、架构变更说明

#### **从混合架构到纯WebSocket架构**

**变更原因：**
- 统一API接口，简化前端开发
- 提升实时性，支持服务器主动推送
- 减少HTTP连接开销，提高性能
- 便于功能扩展和维护

**变更内容：**
- 移除HTTP REST API（认证、软件控制、日志查询）
- 保留基础HTTP接口（健康检查、服务信息）
- 所有业务功能通过WebSocket实现
- 统一JSON消息格式

**前端开发影响：**
- 只需维护一个WebSocket连接
- 统一的消息处理机制
- 实时状态更新和错误推送
- 完整的日志查询和管理功能

**迁移优势：**
- ✅ 架构简化，代码更清晰
- ✅ 实时性能提升
- ✅ 资源使用优化
- ✅ 功能完整性保持
- ✅ 开发效率提升