# pyqt_software_store

**Repository Path**: chairou/pyqt_software_store

## Basic Information

- **Project Name**: pyqt_software_store
- **Description**: pyqt_software_store，软件商店
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyQt 软件商店

基于 **PyQt6** 的桌面软件商店前端，通过本机 **AppStream 元数据** 与 **Flatpak CLI** 浏览、搜索、安装和更新应用（路线与 GNOME Software 的 Flatpak 插件类似，不依赖 libgnomesoftware）。

**可以在 Ubuntu 上运行**（已在 Ubuntu 22.04 / 24.04 及衍生版上验证思路；需图形会话与下文依赖）。

---

## 系统要求

| 项目 | 说明 |
|------|------|
| 操作系统 | Ubuntu 22.04+（或其它带桌面环境的 Debian 系发行版） |
| Python | 3.10 或更高 |
| 显示 | 图形界面（Wayland / X11）；无显示器可用 offscreen 跑测试 |
| Flatpak | **推荐必装**——安装、更新、软件源均依赖 `flatpak` 命令 |
| PackageKit | 可选（`pkcon`），用于部分搜索/刷新兜底 |
| 磁盘 | 首次扫描 AppStream 与缓存约需数百 MB 空闲空间 |

---

## Ubuntu 快速开始

### 1. 安装系统依赖

```bash
sudo apt update
sudo apt install -y \
  python3 python3-venv python3-pip \
  flatpak \
  libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0
```

首次使用 Flatpak 建议添加 Flathub（否则探索页可能为空）：

```bash
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak update --appstream -y
```

可选（PackageKit 命令行，非必须）：

```bash
sudo apt install -y packagekit-tools
```

### 2. 进入项目目录

本仓库中项目位于 `gnome-software` 下的 `pyqt-software-store`：

```bash
cd /path/to/gnome-software/pyqt-software-store
```

### 3. 创建虚拟环境并安装 Python 依赖

```bash
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -r requirements.txt
```

### 4. 启动应用

```bash
export PYTHONPATH=.
python -m pyqt_software_store
```

窗口标题为 **「软件」**，左侧为探索 / 已安装 / 更新等导航。

---

## 开发：运行测试

```bash
cd pyqt-software-store
source venv/bin/activate
pip install -r requirements-dev.txt
export PYTHONPATH=.
export QT_QPA_PLATFORM=offscreen
python -m pytest tests/ -q
```

测试使用独立缓存目录，不会污染 `~/.cache/pyqt-software-store`。

---

## 常用说明

### 缓存目录

应用缓存位于：

```text
~/.cache/pyqt-software-store/
```

包含探索页分区、分类列表、下载任务等。若界面异常（例如只剩测试用「Example」），可删除后重启：

```bash
rm -rf ~/.cache/pyqt-software-store
```

然后重新打开应用或点击窗口右上角 **⟳ 刷新**。

### 功能范围（当前版本）

- **安装 / 卸载 / 更新**：以 Flatpak 为主
- **探索 / 分类 / 搜索**：读取本机 AppStream XML + Flatpak 目录
- **下载任务**：支持暂停、继续；关闭窗口后可在首选项中配置是否自动续装
- 完整对标进度见仓库内 [PARITY.md](PARITY.md)

### 无图形界面（SSH）

无法启动 GUI，仅可跑单元测试（见上文 `QT_QPA_PLATFORM=offscreen`）。

---

## 故障排除

| 现象 | 处理 |
|------|------|
| `ModuleNotFoundError: PyQt6` | 确认已 `source venv/bin/activate` 且 `pip install -r requirements.txt` |
| 启动报错缺少 `libxcb` 等 | `sudo apt install libxcb-cursor0 libxkbcommon-x11-0` |
| 探索页空白 | 安装 `flatpak`、添加 `flathub`，执行 `flatpak update --appstream`，再点应用内刷新 |
| 只能装 Flatpak，不能 apt 装 deb | 当前设计如此；系统 deb 包请用「软件中心」或 `apt` |
| 安装时要密码 | 由 Polkit / `flatpak` 提权，属正常系统行为 |

---

## 项目结构（简要）

```text
pyqt-software-store/
├── pyqt_software_store/    # 应用代码
│   ├── main_window.py      # 主窗口
│   ├── pages/              # 探索、详情、下载等页面
│   ├── services/           # StoreFacade、缓存
│   └── backend/            # AppStream、Flatpak CLI
├── styles/                 # 浅色 / 深色 QSS
├── tests/                  # pytest
├── requirements.txt
└── PARITY.md               # 与 GNOME Software 对标说明
```

---

## 许可证

与上层 `gnome-software` 仓库保持一致；使用前请阅读仓库根目录的许可证文件。