root 664181ec6b feat: 集成AVEVA PDMS 12.1 SP4支持

- 添加PDMS软件配置，支持批处理文件启动方式
- 配置executable_path为pdms.bat，startup_args为["Design", "noconsole"]
- 通过进程检测工具确定正确的进程名称：des.exe和PDMSConsole.exe
- 新增check_pdms_processes.py进程检测工具，可自动识别PDMS进程
- 更新Readme.md和frontend-api-docs.md文档
- 支持与Creo、Revit一致的启动、停止、重启功能

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-01 21:14:32 +08:00

8.7 KiB

Raw Blame History

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)

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
实时状态推送
统一错误处理

六、安全考虑

进程隔离
- 限制可执行的软件白名单
- 验证所有路径输入
- 使用受限的进程权限
API安全
- JWT认证
- 请求频率限制
- 日志审计
网络安全
- WSS (WebSocket Secure) 传输
- CORS配置，允许跨域
- 连接状态监控和管理

七、监控与日志

进程监控
- 使用psutil监控软件进程
- 定期检查进程状态
- 异常自动告警
日志记录
- 操作日志：谁在什么时间启动了什么软件
- 错误日志：启动失败原因
- 性能日志：启动耗时统计

八、操作日志系统

1. 日志类型

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

2. 日志存储

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

3. 日志查询

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

九、开发注意事项

软件启动检测
- 不同软件启动时间差异大
- 需要合理的超时机制
权限问题
- 服务运行账户需要有启动目标软件的权限
- 某些软件可能需要桌面交互权限
并发控制
- 限制同时启动的软件数量，一次只能启动1个，默认，也需要在配置文件中添加
WebSocket连接管理
- 处理客户端断线重连
- 消息队列和状态同步
- 连接数量监控
代码质量
- 消除硬编码，使用枚举和配置
- 参数化所有可配置项
- 遵循MVP设计原则
- 纯WebSocket架构，统一接口

十、架构变更说明

从混合架构到纯WebSocket架构

变更原因：

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

变更内容：

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

前端开发影响：

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

迁移优势：

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

8.7 KiB Raw Blame History Unescape Escape

CadHubManage

项目方案设计

一、技术架构概述

二、项目目录结构

三、核心功能设计

1. 软件配置管理 (software_config.yaml)

2. 纯WebSocket架构

四、接口设计

1. WebSocket接口（主要API）

2. HTTP接口（辅助功能）

五、WebSocket通信机制

1. 连接管理

2. 消息处理

六、安全考虑

七、监控与日志

八、操作日志系统

1. 日志类型

2. 日志存储

3. 日志查询

九、开发注意事项

十、架构变更说明

从混合架构到纯WebSocket架构

8.7 KiB

Raw Blame History