# PyTauri

**Repository Path**: python_90/py-tauri

## Basic Information

- **Project Name**: PyTauri
- **Description**: PyTauri 的桌面相册管理应用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📷 本地相册管理系统

> 基于 **PyTauri** 的桌面相册管理应用，使用 Python + Vue 3 技术栈，纯 Python 方案无需 Rust 编译器即可运行开发环境。

## ✨ 项目介绍

本地相册管理系统是一个跨平台桌面应用，专注于本地照片与视频的扫描、导入、浏览和管理。它把 Python 后端的强大处理能力与 Vue 3 前端的现代 UI 体验结合在一起，通过 PyTauri 的 IPC 机制高效通信。

**核心能力一览：**

- 🔍 **智能扫描导入**：自动识别系统图片/视频目录，支持递归扫描与实时进度反馈
- 🏷️ **EXIF 元数据解析**：拍摄时间、相机品牌型号、GPS 经纬度等一键提取
- 🖼️ **缩略图生成**：本地缓存缩略图，列表加载丝滑流畅
- ⭐ **收藏与软删除**：无损管理你的相册，支持评分
- 📊 **统计信息**：照片数量、收藏数、存储占用一目了然
- 🖥️ **无边框自定义窗口**：现代化 UI，支持最小化/最大化/关闭到托盘

## 🖼️ 界面展示

> 当前版本未附带界面截图，以下为功能界面文字说明，便于快速了解应用形态。

- **主窗口**：1280×760 无边框窗口，顶部自定义标题栏（最小化 / 最大化 / 关闭），左侧导航栏，右侧内容区
- **画廊页（Gallery）**：照片瀑布流网格，支持分页、排序、筛选；悬停显示收藏与删除按钮
- **收藏页（Favorites）**：仅展示已收藏照片，布局与画廊页一致
- **相册页（Albums）**：相册分组管理（开发中）
- **图片详情（PhotoDetail）**：大图预览 + EXIF 信息面板（拍摄时间、相机、GPS）
- **图片查看器（ImageViewer）**：全屏沉浸式浏览
- **视频播放器（VideoPlayer）**：基于 video.js 的本地视频播放

> 📌 **图片排版规则**（后续添加截图时遵循）：
> - 1 张图：使用 `<div align="center"><img .../></div>` 居中展示
> - 多张图：使用 2 列表格等宽排版，每行 2 张
> - 界面展示截图统一放在本节，置于项目介绍之后

## 🛠️ 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Python 3.10+ + PyTauri | IPC 通信，纯 Python 方案 |
| 前端 | Vue 3 + Element Plus + Pinia | Composition API，Vite 构建 |
| 数据库 | SQLite + Peewee ORM | 轻量级本地存储 |
| 图像处理 | Pillow | 缩略图生成 |
| EXIF 解析 | exifread | 元数据提取 |
| 包管理 | uv / pnpm | Python 与前端依赖管理 |
| 打包 | Tauri + tauri-cli | 生成 msi / nsis 安装包 |

## 📦 项目结构

```
py-tauri/
├── src/
│   ├── backend/              # Python 后端
│   │   ├── commands/         # IPC 命令模块（scan/photos/window）
│   │   ├── utils/            # 工具模块（media_finder/exif_parser/thumbnail）
│   │   ├── models.py         # Peewee 数据模型
│   │   └── main.py           # 应用入口
│   ├── frontend/             # Vue 3 前端
│   │   ├── src/
│   │   │   ├── components/   # Vue 组件
│   │   │   ├── views/        # 页面（Gallery/Favorites/Albums/...）
│   │   │   ├── stores/       # Pinia Store
│   │   │   ├── utils/        # pytauri.js / api.js
│   │   │   ├── App.vue
│   │   │   └── main.js
│   │   ├── package.json
│   │   └── vite.config.js
│   ├── data/                 # 数据目录（SQLite）
│   └── assets/               # 静态资源 / 缩略图缓存
├── src-tauri/                # Tauri 配置与 Rust 侧代码
├── doc/                      # 设计文档
├── pyproject.toml            # 项目配置 + uv 镜像
├── requirements.txt          # Python 依赖（兼容 pip）
├── build.py                  # 打包脚本
├── run.py                    # 启动脚本
└── run.bat                   # Windows 一键运行
```

## 🚀 小白部署教程（Windows）

> 本教程面向零基础用户，按步骤操作即可跑起来。所有命令在 **PowerShell** 或 **CMD** 中执行。

### 第 0 步：克隆项目

```powershell
git clone https://gitee.com/python_90/py-tauri.git
cd py-tauri
```

### 第 1 步：安装 Python（≥ 3.10）

1. 访问 [python.org](https://www.python.org/downloads/) 下载 Python 3.10 及以上版本
2. 安装时勾选 **Add Python to PATH**
3. 验证：`python --version` 应输出 `Python 3.10.x` 或更高

### 第 2 步：安装 Node.js 与 pnpm

1. 访问 [nodejs.org](https://nodejs.org/) 下载 LTS 版本并安装
2. 验证：`node --version` 与 `npm --version`
3. 安装 pnpm：
   ```powershell
   npm install -g pnpm
   pnpm --version
   ```

### 第 3 步：安装 uv（Python 包管理器）

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

验证：`uv --version`（如未生效，重开终端）

> 💡 已配置清华镜像（见 `pyproject.toml` 中 `[tool.uv]`），国内安装依赖更快。

### 第 4 步：安装前端依赖

```powershell
cd src\frontend
pnpm install
cd ..\..
```

### 第 5 步：安装 Python 依赖

```powershell
uv sync
```

> 若 `uv sync` 不可用，可使用：`uv pip install -e .`

### 第 6 步：启动开发环境

**方式 A：一键运行（推荐）**

```powershell
.\run.bat
```

**方式 B：手动分终端运行**

- 终端 1（前端开发服务器）：
  ```powershell
  cd src\frontend
  pnpm dev
  ```
- 终端 2（后端，需先设置开发服务器地址）：
  ```powershell
  $env:DEV_SERVER="http://localhost:5173"
  uv run python run.py
  ```

启动后会弹出 1280×760 的应用窗口，即表示部署成功 🎉

### 第 7 步（可选）：打包为独立可执行文件

打包需要 Rust 工具链：

```powershell
irm https://win.rustup.rs | iex
uv run python build.py
```

产物位于 `src-tauri/target/release/bundle/`。

## 📚 PyTauri IPC 通信机制

### 后端命令定义

```python
from pytauri import Commands, WebviewWindow
from pytauri.ipc import Channel, JavaScriptChannelId

commands = Commands()

@commands.command()
async def scan_photos(
    folder_path: str,
    recursive: bool,
    channel_id: JavaScriptChannelId[Msg],
    webview_window: WebviewWindow
) -> dict:
    channel = channel_id.channel_on(webview_window.as_ref_webview())
    channel.send_model(Msg(type='progress', message='处理中...'))
    return {'success': True, 'imported': count}
```

### 前端调用

```javascript
import { pyInvoke } from "tauri-plugin-pytauri-api";
import { Channel } from "@tauri-apps/api/core";

const result = await pyInvoke('get_photos', { page: 1, per_page: 50 });

const channel = new Channel((message) => {
    console.log(message.type, message.message);
});
await pyInvoke('scan_photos', {
    folder_path: '/path/to/photos',
    recursive: true,
    channel_id: channel
});
```

## 🧰 常用命令

### Python（uv）

```bash
uv sync                      # 同步依赖（推荐）
uv pip install <package>     # 添加依赖
uv pip install --upgrade <package>
uv pip freeze > requirements.txt
uv run python run.py         # 运行应用
uv run python build.py       # 打包
```

### 前端（pnpm）

```bash
cd src/frontend
pnpm install
pnpm dev                     # 开发服务器
pnpm build                   # 生产构建
pnpm add <package>
pnpm update
```

## 🗃️ 数据库模型

### Photo（照片表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| path | TEXT | 文件路径（唯一） |
| filename | TEXT | 文件名 |
| file_type | TEXT | 类型（image/video） |
| file_size | INTEGER | 文件大小 |
| width | INTEGER | 宽度 |
| height | INTEGER | 高度 |
| taken_at | DATETIME | 拍摄时间 |
| camera_make | TEXT | 相机品牌 |
| camera_model | TEXT | 相机型号 |
| gps_latitude | REAL | GPS 纬度 |
| gps_longitude | REAL | GPS 经度 |
| is_favorite | BOOLEAN | 是否收藏 |
| is_deleted | BOOLEAN | 是否软删除 |
| thumbnail_path | TEXT | 缩略图路径 |

## 🔌 API 列表

### 扫描导入

- `select_folder()` — 选择文件夹
- `scan_photos(folder_path, recursive, channel_id)` — 扫描照片
- `scan_system_photos(channel_id)` — 扫描系统目录
- `get_scan_preview(folder_path)` — 获取扫描预览

### 照片管理

- `get_photos(page, per_page, sort_by, ...)` — 获取照片列表
- `get_photo_detail(photo_id)` — 获取照片详情
- `get_photo_image(photo_id, thumbnail)` — 获取图片数据
- `toggle_favorite(photo_id)` — 切换收藏
- `delete_photo(photo_id, permanent)` — 删除照片
- `update_photo_rating(photo_id, rating)` — 更新评分
- `get_photos_stats()` — 获取统计信息

### 窗口管理

- `minimize_window()` — 最小化窗口
- `maximize_window()` — 最大化/还原窗口
- `close_window()` — 关闭到托盘
- `open_settings_window()` — 打开设置窗口

## 🌈 功能特性

### 已实现

- [x] 照片扫描导入（支持图片和视频）
- [x] EXIF 元数据解析（拍摄时间、相机信息、GPS 等）
- [x] 缩略图生成
- [x] 照片列表展示（支持分页、排序、筛选）
- [x] 收藏功能
- [x] 删除功能（软删除）
- [x] 扫描进度实时反馈（Channel 流式传输）

### 待实现

- [ ] 大图预览
- [ ] 地图展示 GPS 位置
- [ ] 相册管理
- [ ] 重复文件检测
- [ ] 视频播放
- [ ] 批量操作
- [ ] 系统托盘
- [ ] 设置面板

## 📄 许可证

MIT License