# attendance-photo-helper

**Repository Path**: yabar/attendance-photo-helper

## Basic Information

- **Project Name**: attendance-photo-helper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 照片考勤/分类工具

一款轻量级的桌面客户端照片考勤/分类工具，根据照片拍摄时间自动分类到对应日期文件夹，并支持导出为Word文档。

## 功能特点

- **现代化图形界面**：基于PyQt5开发，操作简单直观，支持暗色主题
- **智能分类**：根据照片拍摄时间自动分类到对应日期文件夹
- **工作日/周末区分**：工作日照片直接分类到日期文件夹，周末照片分类到「周末」子文件夹
- **灵活操作**：支持复制/移动两种模式
- **时间提取**：优先提取EXIF拍摄时间，从多个字段获取日期，可选择使用文件时间作为替代
- **Word导出**：支持将照片按日期导出为Word文档，自动添加周末标识
- **异常处理**：友好处理各种异常情况，保证程序稳定运行
- **跨平台兼容**：支持Windows/macOS/Linux系统
- **HEIC格式支持**：支持处理iPhone拍摄的HEIC格式照片

## 安装步骤

### 1. 安装Python

确保您的系统已安装Python 3.8或更高版本。您可以从[Python官方网站](https://www.python.org/downloads/)下载并安装。

### 2. 安装依赖

打开命令行工具，进入项目目录，执行以下命令安装依赖：

```bash
pip install -r requirements.txt
```

### 3. 运行程序

在项目目录中执行以下命令运行程序：

```bash
python main.py
```

## 打包步骤

如果您需要将程序打包为可执行文件，方便在没有Python环境的系统上运行，可以按照以下步骤操作：

### 1. 确保已安装打包依赖

打包脚本使用PyInstaller来生成可执行文件，该依赖已包含在requirements.txt中，执行安装依赖步骤后即可使用。

### 2. 运行打包脚本

在项目目录中执行以下命令运行打包脚本：

```bash
python build.py
```

### 3. 打包结果

打包脚本会根据当前操作系统自动生成对应的可执行文件：

- **Windows系统**：生成 `dist/PhotoOrganizer.exe` 文件
- **macOS系统**：生成 `dist/PhotoOrganizer` 可执行文件
- **Linux系统**：生成 `dist/PhotoOrganizer` 可执行文件

### 4. 使用打包后的程序

打包后的可执行文件是独立的，不需要Python环境即可运行：

1. 进入 `dist` 目录
2. 双击可执行文件即可运行程序
3. 程序图标已正确嵌入，会在可执行文件、窗口标题栏和任务栏中显示

### 5. 打包配置说明

打包脚本 `build.py` 包含以下配置：

- **单文件模式**：生成单个可执行文件，包含所有依赖
- **窗口模式**：无命令行窗口，直接显示图形界面
- **图标嵌入**：将 `logo.ico` 作为应用图标嵌入
- **资源文件**：将必要的资源文件（如图标）一并打包
- **输出路径**：可执行文件输出到 `dist` 目录
- **工作路径**：打包过程中的临时文件存放在 `build` 目录

## 使用流程

1. **选择文件夹**：点击「浏览」按钮，选择包含照片的文件夹
2. **设置选项**：
   - 选择「复制」或「移动」模式
   - 可选是否「递归处理子文件夹」
   - 可选是否「使用文件时间替代EXIF时间」
   - 可选是否「按时间重命名文件」
3. **开始分类**：点击「开始分类」按钮，程序将自动处理照片
4. **导出Word**：点击「导出Word」按钮，可将照片按日期导出为Word文档
5. **查看日志**：在日志区查看处理过程和结果
6. **清空日志**：点击「清空日志」按钮，可清空当前日志

## 核心功能说明

### 照片时间提取
- 优先提取照片EXIF元数据中的拍摄时间，尝试从多个字段获取：
  - DateTimeOriginal（原始拍摄时间）
  - DateTime（文件修改时间，备用）
  - CreateDate（某些相机的创建时间）
- 可选择使用文件修改时间作为替代（当EXIF时间不可用时）
- 支持常见图片格式：jpg、jpeg、png、webp、bmp、tiff、jfif、heic

### 文件夹创建规则
- **工作日照片**：在所选文件夹内创建「年-月-日」命名的文件夹
- **周末照片**：先创建一级文件夹「周末」，再在其内部创建「年-月-日」二级文件夹
- 若对应日期文件夹已存在，直接使用，不重复创建

### 图片处理
- **复制**模式（默认）：保留原文件，复制到对应文件夹
- **移动**模式：将原文件移动到对应文件夹
- **按时间重命名**：可选择将文件重命名为「YYYYMMDD_HHMMSS.ext」格式

### Word导出功能
- 按日期分组导出照片
- 自动为周末日期添加「(周末)」标识
- 照片宽度统一设置为5英寸
- 文件名格式：「照片考勤_年月日_时分秒.docx」

## 异常处理

- 过滤非图片文件，不进行任何处理
- 对无EXIF拍摄时间且未启用「文件时间替代」的图片，日志提示并跳过
- 处理文件读写权限问题、磁盘空间不足等异常，给出友好提示
- 兼容Windows/macOS/Linux系统，路径处理使用Python标准库

## 代码结构

项目采用模块化设计，代码结构清晰：

- **core/**：核心功能模块
  - `photo_organizer.py`：实现PhotoOrganizer类，包含照片分类和Word导出的核心逻辑

- **gui/**：图形界面模块
  - `main_window.py`：实现MainWindow类，基于PyQt5的图形界面

- **utils/**：工具函数模块
  - （预留）可用于存放通用工具函数

- **main.py**：应用程序入口
- **requirements.txt**：依赖文件
- **README.md**：项目说明

## 系统要求

- Python 3.8+

## 依赖项

项目使用以下Python库：

- **Pillow**：用于图像处理
- **PyQt5**：用于图形界面
- **python-docx**：用于Word文档导出
- **exifread**：用于更稳健地读取EXIF信息
- **pyheif**：用于处理HEIC格式文件

## 注意事项

1. 处理大量照片时，可能会消耗较多系统资源，请耐心等待
2. 移动模式会修改原文件位置，请谨慎使用
3. 建议在处理前备份重要照片，以防意外情况
4. 导出Word文档时，照片数量较多可能会导致生成的文档较大

## 许可证

本项目采用MIT许可证。