# pyClient

**Repository Path**: jack-code-space/py-client

## Basic Information

- **Project Name**: pyClient
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# py-vue-scaffold

基于 **Python + pywebview + Vue 3** 的桌面应用脚手架：用 Python 承载系统窗口、托盘、文件对话框与自定义 JS API，用 Vue 做界面与路由。默认内置「能力目录」式示例（文件/剪贴板/进程/系统集成等），便于对照扩展。

| 层级 | 技术 |
|------|------|
| 界面 | Vue 3、Vite、Pinia、Vue Router（hash）、Axios |
| 桌面壳 | Python 3.10+、pywebview、可选 pystray（Windows 托盘） |
| Windows 分发 | PyInstaller（单文件 exe）+ Inno Setup（安装向导，可选） |

## 项目结构

```text
py-vue-scaffold/
├─ package.json              # 根目录脚本：dev / start / build:*
├─ build-installer.cmd       # 一键打包安装程序（调用 PowerShell 脚本）
├─ installer/
│  ├─ build-installer.ps1    # 前端构建 → PyInstaller → ISCC
│  └─ py-vue-scaffold.iss    # Inno Setup 安装脚本
├─ frontend/                 # Vue 前端
│  ├─ src/
│  │  ├─ utils/pyBridge.js   # 封装 window.pywebview.api，对齐 invoke 风格调用
│  │  ├─ views/              # 能力目录、实验页、关于/设置等
│  │  └─ features/           # 各能力演示组件
│  ├─ public/                # 静态资源（如 icon.png、favicon）
│  └─ vite.config.js
├─ backend/
│  ├─ main.py                # 入口：窗口、托盘、多窗口、静态服务
│  ├─ api.py                 # PythonApi：供前端调用的 JS API
│  ├─ paths.py               # 前端 dist / 应用数据目录等
│  ├─ static_server.py       # 打包态本地 HTTP 静态服务
│  ├─ pyinstaller.spec       # Windows 单文件打包配置
│  ├─ requirements.txt       # Python 运行时依赖
│  └─ assets/                # app.ico、tray.png 等（见下文「应用图标」）
└─ README.md
```

## 环境要求

- **Node.js** 18+（建议 LTS）
- **pnpm** 10+
- **Python** 3.10+
- **Windows** 完整体验（托盘、部分剪贴板能力）依赖 `requirements.txt` 中的可选组件；其他平台可逐步裁剪

## 快速开始

### 安装依赖

```bash
# 前端
pnpm install:frontend
# 或：cd frontend && pnpm install

# Python（在 backend 目录或指定 -r 路径）
cd backend
pip install -r requirements.txt
```

### 开发运行（两个终端）

**终端 A — 前端（Vite + HMR）**

```bash
pnpm dev
# 或：cd frontend && pnpm dev
```

**终端 B — 桌面壳**

```bash
pnpm start
# 或：cd backend && python main.py
```

说明：

- 开发态下壳层固定连接 `http://127.0.0.1:5173/`（与 Vite 默认一致），请保持两端端口一致。
- 修改端口时：在 `frontend/.env.development` 设置 `VITE_DEV_PORT`，并设置环境变量 `PY_VUE_DEV_PORT` 为相同值。

### 根目录脚本一览

| 命令 | 作用 |
|------|------|
| `pnpm install:frontend` | 安装 `frontend` 依赖 |
| `pnpm dev` / `pnpm dev:frontend` | 启动 Vite 开发服务 |
| `pnpm start` / `pnpm start:desktop` | 运行 `python backend/main.py` |
| `pnpm build:frontend` | 仅构建前端到 `frontend/dist` |
| `pnpm build:installer` / `pnpm pack:win` | 构建前端 + PyInstaller + Inno（需已安装 Inno Setup） |

## 前端构建

```bash
cd frontend
pnpm run build
```

产物目录：`frontend/dist`。打包桌面应用前**必须先**完成此步骤（`pyinstaller.spec` 会把该目录打入 exe）。

## 打包 Windows

### 绿色版单文件 `.exe`（PyInstaller）

```bash
cd frontend
pnpm run build

cd ../backend
pip install -r requirements.txt
pip install pyinstaller
pyinstaller --noconfirm pyinstaller.spec
```

输出：`backend/dist/py-vue-app.exe`（双击运行，**不是**安装向导）。

### 安装向导 `.exe`（Inno Setup）

在「绿色版」基础上，用 Inno 把上述 exe 打成带向导的安装包。

1. 安装 [Inno Setup 6](https://jrsoftware.org/isdl.php)（或使用 `winget install -e --id JRSoftware.InnoSetup`）。
2. 在**仓库根目录**执行：

```bash
pnpm build:installer
```

等价方式：

- `powershell -NoProfile -ExecutionPolicy Bypass -File installer/build-installer.ps1`
- 双击 `build-installer.cmd`

输出目录：`installer/output/`（例如 `py-vue-scaffold-1.0.0-setup.exe`）。该目录已在 `.gitignore` 中忽略。

若系统未找到 `ISCC.exe`，可将 Inno 安装目录设为环境变量 **`INNO_SETUP`**（目录内需包含 `ISCC.exe`）。脚本会依次尝试：环境变量、`PATH`、常见安装路径、注册表卸载信息。

安装向导默认 **按当前用户安装**（`PrivilegesRequired=lowest`），含开始菜单项、可选桌面快捷方式、安装结束可启动；可在「应用和功能」中卸载。

### PyInstaller 与 macOS

需在 **macOS** 上执行打包流程（Windows 无法直接生成可用的 macOS 应用）。步骤类似：先 `pnpm run build`，再于 macOS 上配置并运行 `pyinstaller`（路径与 GUI 后端可能与 Windows 不同，需自行按需调整 spec）。

## 应用图标

将资源放在 **`backend/assets/`**：

- **`app.ico`**：嵌入 `py-vue-app.exe`、安装向导图标、任务栏/窗口图标（建议多尺寸）。
- **`tray.png`**（或 `tray.ico` / `app.png` 等）：系统托盘；详见 `main.py` 中的加载顺序。

页签图标：在 `frontend/public/` 放置图片，并在 `frontend/index.html` 的 `<link rel="icon" ...>` 中引用（当前示例使用 `icon.png`）。

## 前端与 Python 通信

- 桌面壳会把 `PythonApi` 实例挂到 **`window.pywebview.api`**。
- 前端推荐通过 **`frontend/src/utils/pyBridge.js`** 调用（含 `invoke`、文件对话框封装等），与页面中 `isDesktopShell()` 判断配合使用。
- 扩展能力：在 `backend/api.py` 的 `PythonApi` 中新增方法，并在 `pyBridge.js` 中按需暴露。

## 常用环境变量

| 变量 | 说明 |
|------|------|
| `VITE_DEV_PORT` | 写在 `frontend/.env.development`，Vite 端口，默认 `5173` |
| `PY_VUE_DEV_PORT` | 后端连接前端的端口，须与 `VITE_DEV_PORT` 一致 |
| `PY_VUE_FORCE_DEV=1` | 打包（frozen）后仍强制使用开发服务器 URL（调试） |
| `PYWEBVIEW_DEBUG=1` | 开启 pywebview 调试 |
| `PY_VUE_FRAMELESS=1` | 使用无边框窗口（可能影响拖动缩放等行为） |
| `INNO_SETUP` | Inno 安装目录，供 `build-installer.ps1` 查找 `ISCC.exe` |
| `VITE_API_BASE_URL` | 覆盖 Axios `baseURL`（默认 `/api`） |
| `VITE_DEV_PROXY_TARGET` | 开发时 Vite 将 `/api` 代理到的后端（默认 `http://127.0.0.1:8000`） |

## 路由与多窗口

- 路由为 **hash 模式**（如 `#/`、`#/setting`、`#/case-aux`），适合 file/http 加载与多窗口 `load_url`。
- 辅助窗口路由示例：`#/case-aux`，由 `main.py` 中 `open_window` 与常量 `CASE_AUX_ROUTE` 配合。

## 常见问题

1. **白屏或连不上前端**  
   确认已先启动 `pnpm dev`，且端口与 `PY_VUE_DEV_PORT` / Vite 一致；防火墙勿拦截本机 `127.0.0.1`。

2. **`pnpm build:installer` 报找不到 ISCC**  
   安装 Inno Setup 6，或使用 `winget`；设置 `INNO_SETUP` 指向安装目录。

3. **PowerShell 脚本中文乱码或解析错误**  
   `build-installer.ps1` 已按 UTF-8 BOM 保存；若仍异常，可尝试用 **PowerShell 7**（`pwsh`）执行同一脚本。

4. **托盘不出现**  
   Windows 下依赖 `pystray` 与 `pillow`；若导入失败，`main.py` 会静默跳过托盘逻辑。

## 备注

- 后端不负责绘制自定义标题栏视觉样式；顶栏由前端 `TitleBar.vue` 等与 `PythonApi` 窗口控制配合。
- 更多忽略规则见仓库根目录 **`.gitignore`**（含 `node_modules`、`dist`、`installer/output` 等）。