229 lines
7.3 KiB
Markdown
229 lines
7.3 KiB
Markdown
# 幼儿园成长报告生成系统
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于Python的自动化幼儿园成长报告生成系统。该系统可以从Excel数据文件中读取幼儿信息，结合AI生成个性化评语，并将所有信息批量填充到PPT模板中，最终生成每个学生的个性化成长报告。系统支持双界面运行（命令行界面、图形界面和NiceGUI界面），具备字体安装、图片替换、批量PDF转换、生肖计算等功能。
|
||
|
||
## 技术栈
|
||
|
||
- **Python 3.13+**: 主要编程语言
|
||
- **python-pptx**: PPT文件处理
|
||
- **pandas**: Excel数据读取与处理
|
||
- **langchain**: AI模型集成
|
||
- **comtypes**: PowerPoint转PDF功能
|
||
- **rich**: 美化命令行界面
|
||
- **loguru**: 日志记录
|
||
- **tomli**: 配置文件解析
|
||
- **tkinter**: 图形用户界面
|
||
- **nicegui**: 现代Web界面
|
||
|
||
## 核心功能
|
||
|
||
### 1. 生成模板 (📁 生成图片路径)
|
||
- 从Excel文件中读取学生姓名
|
||
- 为每个学生创建图片文件夹结构
|
||
- 支持批量创建学生专属图片目录
|
||
|
||
### 2. 生成评语 (🤖 生成评语)
|
||
- 使用AI模型根据学生姓名、年龄组、性别和表现特征生成个性化评语
|
||
- 评语会自动写入Excel文件的对应列
|
||
- 支持跳过已有评语的记录以节省API调用
|
||
- 采用"治愈系"三段式评语结构
|
||
|
||
### 3. 生成报告 (📊 生成报告)
|
||
- 读取Excel数据和图片资源
|
||
- 将信息批量填充到PPT模板中
|
||
- 保持原有的文字格式和样式
|
||
- 替换文本占位符和图片占位符
|
||
- 支持5页PPT模板的完整替换
|
||
|
||
### 4. 格式转换 (📑 格式转换)
|
||
- 批量将生成的PPT文件转换为PDF格式
|
||
- 使用COM接口与PowerPoint进行交互
|
||
- 支持跳过已存在的PDF文件
|
||
|
||
### 5. 生肖转化 (🐂 生肖转化)
|
||
- 根据学生生日自动计算生肖
|
||
- 批量更新Excel中的生肖信息
|
||
- 支持日期格式自动识别
|
||
|
||
### 6. 导出数据模板 (📦 导出数据模板)
|
||
- 生成标准化的数据模板ZIP包
|
||
- 包含示例Excel文件和图片文件夹结构
|
||
- 方便新用户快速上手
|
||
|
||
### 7. 初始化系统 (📤 初始化系统)
|
||
- 自动创建必要的目录结构
|
||
- 安装所需字体文件
|
||
- 配置系统环境
|
||
|
||
### 8. 字体安装 (🔤 字体安装)
|
||
- 自动检测系统是否安装了指定字体
|
||
- 自动安装项目所需的字体文件
|
||
- 支持方正兰亭黑简体和方正少儿简体字体
|
||
|
||
## 主要文件结构
|
||
|
||
```
|
||
growth_report/
|
||
├── main.py # 主程序入口（命令行界面）
|
||
├── UI.py # 图形用户界面入口（tkinter）
|
||
├── main_nicegui.py # NiceGUI界面入口
|
||
├── main.pyw # Windows图形界面启动文件
|
||
├── config.env.toml # 项目配置文件
|
||
├── pyproject.toml # 项目依赖配置
|
||
├── start_app.bat # Windows启动批处理文件
|
||
├── README.md # 项目说明文档
|
||
├── IFLOW.md # 项目详细说明文档
|
||
├── config/
|
||
│ ├── config.py # 配置加载工具
|
||
│ └── output/ # 配置输出目录
|
||
├── ui/
|
||
│ ├── app_window.py # tkinter图形界面
|
||
│ ├── main_nicegui.py # NiceGUI界面主文件
|
||
│ ├── assets/
|
||
│ │ ├── icon.ico # 应用图标
|
||
│ │ └── style.css # 样式文件
|
||
│ ├── core/
|
||
│ │ ├── logger.py # 日志处理
|
||
│ │ ├── state.py # 应用状态管理
|
||
│ │ ├── task_runner.py # 任务运行器
|
||
│ │ └── __pycache__/
|
||
│ └── views/
|
||
│ └── home_page.py # NiceGUI主页面
|
||
├── utils/
|
||
│ ├── agent_utils.py # AI评语生成工具
|
||
│ ├── file_utils.py # 文件操作工具
|
||
│ ├── font_utils.py # 字体安装和检测工具
|
||
│ ├── generate_utils.py # 核心生成功能
|
||
│ ├── growt_utils.py # PPT模板替换工具
|
||
│ ├── image_utils.py # 图片处理工具
|
||
│ ├── log_handler.py # 日志处理器
|
||
│ ├── pdf_utils.py # PDF转换工具
|
||
│ ├── pptx_utils.py # PPT文本和图片替换工具
|
||
│ └── zodiac_utils.py # 生肖计算工具
|
||
├── data/
|
||
│ ├── names.xlsx # 学生数据Excel文件
|
||
│ └── images/ # 学生图片资源文件夹
|
||
├── fonts/ # 字体文件目录
|
||
├── templates/ # PPT模板文件
|
||
├── output/ # 生成的报告输出目录
|
||
└── old/ # 旧版本文件备份
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### config.env.toml
|
||
|
||
- `paths`: 定义文件路径（模板、输出、Excel、图片、字体）
|
||
- `class_info`: 班级信息（名称、教师名单）
|
||
- `defaults`: 默认设置（默认评语、年龄组）
|
||
- `excel`: Excel表配置（工作表名、列名顺序）
|
||
- `ai`: AI配置（API密钥、URL、模型、提示词）
|
||
|
||
### Excel数据格式
|
||
|
||
Excel文件应包含以下列（顺序必须与配置文件中一致）：
|
||
|
||
- 姓名
|
||
- 英文名
|
||
- 性别
|
||
- 生日
|
||
- 属相
|
||
- 我的好朋友
|
||
- 我的爱好
|
||
- 喜欢的游戏
|
||
- 喜欢吃的食物
|
||
- 评价
|
||
- 表现特征（可选，用于AI评语生成）
|
||
|
||
### 图片文件结构
|
||
|
||
```
|
||
data/images/
|
||
├── 班级名称.jpg # 班级集体照片
|
||
└── 学生姓名/
|
||
├── me.jpg # 学生个人照片
|
||
├── 1.jpg # 活动照片1
|
||
├── 2.jpg # 活动照片2
|
||
```
|
||
|
||
支持多种图片格式：.jpg, .jpeg, .png
|
||
|
||
## AI评语生成
|
||
|
||
系统使用langchain框架与AI模型集成，根据以下信息生成评语：
|
||
|
||
- 幼儿姓名
|
||
- 所在班级（年龄段）
|
||
- 性别
|
||
- 表现特征
|
||
|
||
评语风格为"治愈系"，采用三段式结构：亲切问候、具体描述优点、委婉期望与祝福。支持分龄侧重评价，针对不同年龄段有不同的评价重点。
|
||
|
||
## 使用方法
|
||
|
||
### 运行程序
|
||
|
||
#### 命令行界面
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
#### 图形界面 (tkinter)
|
||
```bash
|
||
python UI.py
|
||
```
|
||
|
||
#### NiceGUI界面 (现代Web界面)
|
||
```bash
|
||
python main_nicegui.py
|
||
```
|
||
|
||
或直接运行批处理文件：
|
||
```bash
|
||
start_app.bat
|
||
```
|
||
|
||
### 依赖安装
|
||
|
||
#### 使用uv（推荐）
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
#### 使用pip
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 初始化设置
|
||
|
||
1. 编辑`config.env.toml`配置文件，设置API密钥和其他参数
|
||
2. 准备Excel数据文件（按指定格式）
|
||
3. 准备图片资源文件夹（按指定结构）
|
||
4. 准备PPT模板文件
|
||
|
||
## 系统特点
|
||
|
||
- **三界面支持**: 提供命令行界面、tkinter图形界面和NiceGUI现代Web界面三种操作方式
|
||
- **自动化流程**: 从数据到成品报告的全流程自动化
|
||
- **AI集成**: 智能生成个性化评语
|
||
- **格式保持**: 替换文本时保持原有格式
|
||
- **用户友好**: 丰富的命令行界面和多种图形界面，实时日志显示
|
||
- **批量处理**: 支持批量生成和转换
|
||
- **错误处理**: 完善的异常处理和日志记录
|
||
- **生肖计算**: 自动根据生日计算生肖
|
||
- **模板导出**: 支持导出标准数据模板
|
||
- **字体管理**: 自动安装和检测所需字体
|
||
- **跨平台兼容**: 支持Windows环境运行
|
||
|
||
## 开发约定
|
||
|
||
- 使用`loguru`进行日志记录
|
||
- 使用`rich`美化命令行输出
|
||
- 使用`tkinter`和`nicegui`构建图形界面
|
||
- 配置文件使用TOML格式
|
||
- 图片和文本替换使用占位符机制
|
||
- 遵循Python代码规范
|
||
- 使用uv进行依赖管理 |