commit 0728bd7290740dfeadf59b73e87a682190ce9c46 Author: 陈横 <2938139566@qq.com> Date: Sat Oct 11 09:27:51 2025 +0800 init diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..35410ca --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,8 @@ +# 默认忽略的文件 +/shelf/ +/workspace.xml +# 基于编辑器的 HTTP 客户端请求 +/httpRequests/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml diff --git a/.idea/AugmentWebviewStateStore.xml b/.idea/AugmentWebviewStateStore.xml new file mode 100644 index 0000000..26259a0 --- /dev/null +++ b/.idea/AugmentWebviewStateStore.xml @@ -0,0 +1,10 @@ + + + + + + \ No newline at end of file diff --git a/.idea/MetaCore.iml b/.idea/MetaCore.iml new file mode 100644 index 0000000..d713487 --- /dev/null +++ b/.idea/MetaCore.iml @@ -0,0 +1,14 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000..2bd2921 --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,12 @@ + + + + \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml new file mode 100644 index 0000000..105ce2d --- /dev/null +++ b/.idea/inspectionProfiles/profiles_settings.xml @@ -0,0 +1,6 @@ + + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 0000000..2fca6de --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,7 @@ + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..ed91c99 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/CROSS_PLATFORM_OPTIMIZATION.md b/CROSS_PLATFORM_OPTIMIZATION.md new file mode 100644 index 0000000..6c44fe9 --- /dev/null +++ b/CROSS_PLATFORM_OPTIMIZATION.md @@ -0,0 +1,224 @@ +# 跨平台路径处理优化报告 + +## 优化概述 + +本次优化主要针对 MetaCore 项目中的跨平台兼容性和路径处理问题,使用现代 Python 标准库 `pathlib` 替代传统的 `os.path`,并创建了专门的工具类来处理跨平台差异。 + +## 主要问题 + +### 1. 路径处理问题 +- **混合使用路径分隔符**:代码中存在大量 `replace('\\', '/')` 操作,这是不规范且不可靠的做法 +- **硬编码路径**:存在平台特定的硬编码路径,如Linux下的 `/home/tiger/下载/pycharm-2025.2.0.1/bin/pycharm.sh` +- **不一致的路径API**:混合使用 `os.path.join` 和字符串拼接 + +### 2. 跨平台兼容性问题 +- **平台检测重复**:多处重复的平台类型检测代码 +- **可执行文件查找**:没有统一的可执行文件查找机制 +- **路径规范化不统一**:不同地方使用不同的路径规范化方法 + +## 优化方案 + +### 1. 创建工具类 + +#### PathUtils 类 +```python +class PathUtils: + """跨平台路径处理工具类""" + + @staticmethod + def normalize_path(path_str: str) -> Path: + """规范化路径为Path对象""" + + @staticmethod + def ensure_path_exists(path: Path, is_file: bool = False) -> bool: + """确保路径存在""" + + @staticmethod + def safe_path_join(*parts) -> Path: + """安全地连接路径部分""" + + @staticmethod + def is_valid_path(path_str: str) -> bool: + """检查路径字符串是否有效""" +``` + +#### PlatformUtils 类 +```python +class PlatformUtils: + """跨平台工具类""" + + @staticmethod + def get_system_type() -> str: + """获取系统类型""" + + @staticmethod + def get_executable_extension() -> str: + """获取可执行文件扩展名""" + + @staticmethod + def get_python_executable(venv_path: Path) -> Path: + """获取虚拟环境中的Python可执行文件路径""" + + @staticmethod + def get_pycharm_paths() -> List[Path]: + """获取各平台PyCharm可能的安装路径""" + + @staticmethod + def find_executable(paths: List[Path]) -> Optional[Path]: + """在指定路径列表中查找可执行文件""" +``` + +### 2. 优化的文件 + +#### MetaCore/data/project_manager.py +- **完全重构**:使用 `pathlib.Path` 替代所有 `os.path` 操作 +- **统一路径处理**:所有路径操作都通过 `PathUtils` 进行 +- **移除硬编码路径**:使用动态路径查找替代硬编码路径 +- **改进的PyCharm集成**:使用统一的可执行文件查找机制 + +#### MetaCore/ui/project_card.py +- **优化 show_in_explorer 方法**:使用 `pathlib` 处理路径 +- **改进错误处理**:更好的异常处理和用户提示 +- **跨平台文件管理器支持**:统一的文件管理器打开逻辑 + +### 3. 主要改进 + +#### 路径处理改进 +- ✅ 使用 `pathlib.Path` 替代 `os.path` +- ✅ 统一的路径规范化方法 +- ✅ 自动处理不同操作系统的路径格式 +- ✅ 移除手动的路径分隔符替换 + +#### 跨平台兼容性改进 +- ✅ 统一的平台检测机制 +- ✅ 动态的可执行文件查找 +- ✅ 平台特定的配置统一管理 +- ✅ 改进的错误处理和回退机制 + +#### 代码质量改进 +- ✅ 减少代码重复 +- ✅ 更好的类型提示 +- ✅ 统一的异常处理 +- ✅ 改进的文档和注释 + +## 具体优化案例 + +### 1. 路径连接优化 + +**优化前:** +```python +project_dir = os.path.join(path, title).replace('\\', '/') +full_path = os.path.normpath(os.path.join(project_dir, filename)) +``` + +**优化后:** +```python +path_obj = PathUtils.normalize_path(path) +project_dir = path_obj / title +full_path = project_dir / filename +``` + +### 2. PyCharm路径查找优化 + +**优化前:** +```python +if system == "linux": + return [ + "pycharm", + "pycharm.sh", + "/opt/pycharm*/bin/pycharm.sh", + "/usr/local/bin/pycharm", + "/usr/bin/pycharm", + "/home/tiger/下载/pycharm-2025.2.0.1/bin/pycharm.sh", # 硬编码路径 + os.path.expanduser("~/.local/share/JetBrains/Toolbox/apps/PyCharm-P/ch-*/bin/pycharm.sh") + ] +``` + +**优化后:** +```python +else: # Linux + return [ + Path("pycharm"), + Path("pycharm.sh"), + *Path("/opt").glob("pycharm*/bin/pycharm.sh"), + Path("/usr/local/bin/pycharm"), + Path("/usr/bin/pycharm"), + *home.glob(".local/share/JetBrains/Toolbox/apps/PyCharm-P/ch-*/bin/pycharm.sh") + ] +``` + +### 3. 虚拟环境Python可执行文件查找优化 + +**优化前:** +```python +if os.name == 'nt': # Windows + python_executable = Path(venv_path) / 'Scripts' / 'python.exe' +else: # Unix-like systems + python_executable = Path(venv_path) / 'bin' / 'python' +``` + +**优化后:** +```python +python_executable = PlatformUtils.get_python_executable(venv_path_obj) +``` + +## 测试建议 + +### 1. 跨平台测试 +- Windows 10/11 +- macOS (Intel & Apple Silicon) +- Ubuntu/Debian Linux +- CentOS/RHEL Linux + +### 2. 路径测试 +- 包含中文字符的路径 +- 包含空格的路径 +- 超长路径 +- 网络路径 (Windows UNC) +- 符号链接 + +### 3. 功能测试 +- 项目创建和导入 +- 文件管理器打开 +- PyCharm集成 +- 虚拟环境处理 + +## 后续优化建议 + +### 1. 配置文件优化 +- 使用 `pathlib` 优化配置文件路径处理 +- 统一配置文件格式和位置 + +### 2. 资源文件处理 +- 优化图标和资源文件的路径处理 +- 支持相对路径和绝对路径 + +### 3. 日志系统 +- 添加路径相关的详细日志 +- 改进错误报告机制 + +### 4. 单元测试 +- 为路径处理工具类添加单元测试 +- 添加跨平台兼容性测试 + +## 性能影响 + +### 正面影响 +- ✅ **更少的路径转换操作**:减少字符串替换操作 +- ✅ **更好的缓存利用**:Path对象的内置缓存机制 +- ✅ **减少重复代码**:统一的工具函数 + +### 注意事项 +- ⚠️ **Path对象创建开销**:虽然很小,但比字符串操作略重 +- ⚠️ **兼容性**:确保所有Path对象在需要时正确转换为字符串 + +## 总结 + +本次优化显著改善了 MetaCore 项目的跨平台兼容性和代码质量: + +1. **统一性**:所有路径操作现在使用统一的API +2. **可靠性**:减少了平台特定的bug和问题 +3. **可维护性**:代码更清晰,更容易维护和扩展 +4. **现代化**:使用现代Python最佳实践 + +这些改进为项目的长期维护和跨平台部署奠定了坚实的基础。 \ No newline at end of file diff --git a/Doc/README.md b/Doc/README.md new file mode 100644 index 0000000..fee55f4 --- /dev/null +++ b/Doc/README.md @@ -0,0 +1,80 @@ +# MetaCore 项目文档中心 + +欢迎来到MetaCore项目文档中心!这里包含了项目的所有说明文档,按类别整理便于查阅。 + +## 📚 文档分类 + +### 🚀 快速开始 +- **[快速开始.md](快速开始.md)** - 新用户必读,快速上手指南 +- **[安装PyQt5指南.md](安装PyQt5指南.md)** - PyQt5安装详细步骤 + +### 📖 详细说明 +- **[README_PyQt5.md](README_PyQt5.md)** - PyQt5版本完整功能说明 +- **[项目总览.md](项目总览.md)** - 整个项目的全面概述 +- **[功能对比说明.md](功能对比说明.md)** - Web版本与PyQt5版本对比 + +### 🔧 环境配置 +- **[虚拟环境完整指南.md](虚拟环境完整指南.md)** - 虚拟环境完整指南 + +## 🎯 推荐阅读顺序 + +### 新用户 +1. [快速开始.md](快速开始.md) - 了解如何快速启动 +2. [安装PyQt5指南.md](安装PyQt5指南.md) - 解决安装问题 +3. [README_PyQt5.md](README_PyQt5.md) - 了解完整功能 + +### 开发者 +1. [项目总览.md](项目总览.md) - 了解项目整体架构 +2. [功能对比说明.md](功能对比说明.md) - 理解两个版本的差异 +3. [虚拟环境完整指南.md](虚拟环境完整指南.md) - 配置开发环境 + +### 系统管理员 +1. [虚拟环境完整指南.md](虚拟环境完整指南.md) - 环境部署 +2. [安装PyQt5指南.md](安装PyQt5指南.md) - 依赖安装 +3. [项目总览.md](项目总览.md) - 了解项目状态 + +## 🔍 快速查找 + +### 按问题类型查找 + +#### 安装问题 +- PyQt5安装失败 → [安装PyQt5指南.md](安装PyQt5指南.md) +- 虚拟环境配置 → [虚拟环境完整指南.md](虚拟环境完整指南.md) + +#### 使用问题 +- 如何启动应用 → [快速开始.md](快速开始.md) +- 功能说明 → [README_PyQt5.md](README_PyQt5.md) +- 版本选择 → [功能对比说明.md](功能对比说明.md) + +#### 开发问题 +- 项目架构 → [项目总览.md](项目总览.md) +- 功能对比 → [功能对比说明.md](功能对比说明.md) + +## 📱 文档更新 + +### 最新更新 +- **2024年** - 完成PyQt5版本开发 +- **最近** - 整理文档到Doc目录 + +### 维护说明 +- 所有文档统一存放在Doc目录 +- 按功能和用途分类 +- 定期更新和维护 + +## 🎯 使用建议 + +### 查阅文档 +1. **从README.md开始** - 本文档提供了完整的导航 +2. **按需查阅** - 根据具体问题选择相应文档 +3. **顺序阅读** - 新用户建议按推荐顺序阅读 + +### 贡献文档 +1. **保持结构** - 新文档应放在Doc目录 +2. **更新索引** - 添加新文档时更新本README +3. **统一格式** - 遵循现有文档的格式规范 + +--- + +💡 **提示:** 如果您是第一次使用MetaCore,建议从 [快速开始.md](快速开始.md) 开始阅读! + +🎉 **欢迎使用MetaCore项目管理平台!** diff --git a/Doc/README_PyQt5.md b/Doc/README_PyQt5.md new file mode 100644 index 0000000..24ac29e --- /dev/null +++ b/Doc/README_PyQt5.md @@ -0,0 +1,210 @@ +# MetaCore - PyQt5版本 + +这是基于PyQt5重写的MetaCore项目管理平台,完全复制了原始Web版本的界面和功能。 + +## 功能特性 + +### 🎯 主要功能 +- ✅ **项目管理**:创建、导入、删除、重命名项目 +- ✅ **项目卡片**:三段式布局(标题+菜单、图片+类型标签、时间) +- ✅ **收藏功能**:项目收藏/取消收藏 +- ✅ **搜索过滤**:按名称搜索、按类型过滤 +- ✅ **视图模式**:网格视图和列表视图 +- ✅ **右键菜单**:完整的项目操作菜单 + +### 🎨 界面特性 +- ✅ **深色主题**:现代化的深色界面设计 +- ✅ **响应式布局**:自适应窗口大小 +- ✅ **侧边栏导航**:可展开/收起的导航菜单 +- ✅ **模态对话框**:创建项目和导入项目对话框 +- ✅ **拖拽支持**:文件拖拽导入功能 + +## 安装和运行 + +### 1. 环境要求 +- Python 3.7+ +- PyQt5 5.15.0+ + +### 2. 安装依赖 +```bash +pip install -r requirements.txt +``` + +### 3. 运行应用 +```bash +python main.py +``` + +## 项目结构 + +``` +MetaCore/ +├── main.py # 主程序入口 +├── requirements.txt # 依赖包列表 +├── README_PyQt5.md # 说明文档 +├── data/ # 数据模块 +│ ├── __init__.py +│ ├── project_manager.py # 项目数据管理器 +│ └── projects.json # 项目数据文件(自动生成) +└── ui/ # 界面模块 + ├── __init__.py + ├── main_window.py # 主窗口 + ├── sidebar.py # 侧边栏组件 + ├── project_area.py # 项目显示区域 + ├── project_card.py # 项目卡片组件 + ├── create_project_dialog.py # 创建项目对话框 + ├── import_project_dialog.py # 导入项目对话框 + └── styles.py # 样式表定义 +``` + +## 主要组件说明 + +### 1. 主窗口 (MainWindow) +- 整体布局管理 +- 菜单栏和状态栏 +- 组件间信号连接 +- 窗口事件处理 + +### 2. 侧边栏 (Sidebar) +- Logo区域 +- 快速操作按钮 +- 可展开的导航菜单 +- 用户信息显示 + +### 3. 项目区域 (ProjectArea) +- 工具栏和搜索区域 +- 网格/列表视图切换 +- 项目卡片容器 +- 空状态显示 + +### 4. 项目卡片 (ProjectCard) +- 三段式布局设计 +- 悬停效果 +- 右键菜单 +- 收藏状态显示 + +### 5. 创建项目对话框 (CreateProjectDialog) +- 2:1布局比例 +- 模板选择网格 +- 项目信息表单 +- 文件夹选择功能 + +### 6. 导入项目对话框 (ImportProjectDialog) +- 文件拖拽上传 +- 导入选项配置 +- 文件列表显示 +- 进度反馈 + +## 数据管理 + +### 项目数据结构 +```python +{ + "id": 1, + "title": "项目名称", + "date": "2024-06-08 15:56:35", + "type": "industrial", + "image": "🏭", + "favorite": true, + "path": "/path/to/project" +} +``` + +### 支持的项目类型 +- `industrial` - 工业项目 🏭 +- `smart` - 智能项目 💧 +- `vr` - VR项目 🥽 +- `game` - 游戏项目 🎮 +- `design` - 设计项目 🎨 +- `empty` - 空白项目 📁 + +## 样式系统 + +### 主题色彩 +- **主色调**:深灰色 (#1a1a1a, #2a2a2a) +- **边框色**:中灰色 (#3a3a3a, #4a4a4a) +- **强调色**:紫色 (#8b5cf6, #7c3aed) +- **文字色**:白色/灰色 (#ffffff, #cccccc, #888888) + +### 组件样式 +- 所有组件都有对应的ObjectName用于样式选择器 +- 支持悬停状态和选中状态 +- 统一的圆角和间距设计 +- 平滑的过渡动画效果 + +## 信号和槽机制 + +### 主要信号 +- `projects_changed` - 项目列表变化 +- `project_added` - 项目添加 +- `project_removed` - 项目删除 +- `project_updated` - 项目更新 +- `filter_changed` - 过滤条件变化 +- `search_changed` - 搜索内容变化 + +### 事件处理 +- 鼠标点击事件 +- 键盘快捷键 +- 拖拽事件 +- 窗口事件 + +## 扩展功能 + +### 可以添加的功能 +1. **项目模板系统**:真实的项目模板创建和应用 +2. **文件管理**:项目内文件的管理和预览 +3. **版本控制**:Git集成和版本管理 +4. **协作功能**:多用户协作和权限管理 +5. **插件系统**:支持第三方插件扩展 +6. **云同步**:项目数据云端同步 +7. **导出功能**:项目打包和分享 + +### 性能优化 +1. **虚拟滚动**:大量项目时的性能优化 +2. **缓存机制**:图片和数据缓存 +3. **异步加载**:大文件异步处理 +4. **内存管理**:及时释放不用的资源 + +## 开发说明 + +### 添加新组件 +1. 在`ui/`目录下创建新的组件文件 +2. 继承适当的PyQt5基类 +3. 实现`init_ui()`方法 +4. 添加必要的信号定义 +5. 在样式表中添加对应样式 + +### 修改样式 +1. 在`ui/styles.py`中修改样式定义 +2. 使用ObjectName作为选择器 +3. 支持状态选择器(:hover, :checked等) +4. 遵循现有的颜色和间距规范 + +### 数据持久化 +- 项目数据自动保存到`data/projects.json` +- 应用关闭时自动保存 +- 启动时自动加载历史数据 +- 支持数据备份和恢复 + +## 与Web版本对比 + +### 相同功能 +- ✅ 完全相同的界面布局 +- ✅ 相同的项目管理功能 +- ✅ 相同的视觉设计风格 +- ✅ 相同的用户交互逻辑 + +### PyQt5版本优势 +- ✅ 原生桌面应用体验 +- ✅ 更好的性能表现 +- ✅ 系统集成度更高 +- ✅ 离线使用支持 +- ✅ 文件系统直接访问 + +### 技术差异 +- **Web版本**:HTML + CSS + JavaScript +- **PyQt5版本**:Python + PyQt5 + 自定义样式表 +- **数据存储**:JSON文件 vs 浏览器存储 +- **文件操作**:系统API vs Web API限制 + +这个PyQt5版本完全复制了Web版本的功能和外观,同时提供了更好的桌面应用体验。 diff --git a/Doc/功能对比说明.md b/Doc/功能对比说明.md new file mode 100644 index 0000000..9368ae3 --- /dev/null +++ b/Doc/功能对比说明.md @@ -0,0 +1,208 @@ +# MetaCore Web版本 vs PyQt5版本功能对比 + +## 🎯 完整功能映射 + +### 1. 整体布局结构 + +| Web版本 | PyQt5版本 | 说明 | +|---------|-----------|------| +| `