# 幼儿园成长报告生成系统

[![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 项目概述

基于Python的自动化幼儿园学期成长报告生成系统。该系统可以从Excel数据文件中读取幼儿信息，结合AI生成个性化评语，并将所有信息批量填充到PPT模板中，最终生成每个学生的个性化成长报告。系统支持双界面操作（命令行界面和图形界面），具备字体安装、图片替换、批量PDF转换、生肖计算、模板导出等完整功能。

## ✨ 主要特性

- 🚀 **一键生成**: 从Excel数据到完整报告的自动化流程
- 🤖 **AI评语**: 智能生成个性化、治愈系风格的幼儿评语
- 🖼️ **图文并茂**: 支持个人照片、活动照片、班级合影的自动替换
- 📄 **格式转换**: 批量PPT转PDF，便于分发和存档
- 🎨 **双界面**: 提供命令行界面和图形界面，满足不同用户需求
- 🐲 **生肖计算**: 根据生日自动计算生肖信息
- 📦 **模板导出**: 生成标准化数据模板，快速上手
- 🔤 **字体安装**: 自动检测和安装所需字体文件

## 🛠️ 技术栈

- **Python 3.13+**: 主要编程语言
- **python-pptx**: PPT文件处理
- **pandas**: Excel数据读取与处理
- **langchain**: AI模型集成
- **comtypes**: PowerPoint转PDF功能
- **rich**: 美化命令行界面
- **loguru**: 日志记录
- **tkinter**: 图形用户界面
- **tomli**: 配置文件解析

## 📋 系统要求

- Windows 10/11 (支持PowerPoint COM接口)
- Python 3.13 或更高版本
- Microsoft PowerPoint (用于PDF转换功能)

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/hanhanshibaobei/growthreport.git
cd growthreport
```

### 2. 安装依赖

#### 使用uv（推荐）
```bash
uv sync
```

#### 使用pip
```bash
pip install -r requirements.txt
```

### 3. 配置系统

编辑 `config.env.toml` 文件，设置以下信息：

- AI API密钥和配置
- 班级信息和教师名单
- 文件路径配置

### 4. 运行程序

#### 图形界面（推荐）
```bash
python UI.py
```

或直接运行：
```bash
start_app.bat
```

#### 命令行界面
```bash
python main.py
```

## 📖 使用指南

### 功能模块

1. **📁 生成图片路径**: 为每个学生创建图片文件夹结构
2. **🤖 生成评语**: 使用AI生成个性化评语
3. **📊 生成报告**: 批量生成PPT成长报告
4. **📑 格式转换**: 将PPT转换为PDF
5. **🐂 生肖转化**: 根据生日计算生肖
6. **📦 导出数据模板**: 生成标准化模板
7. **📤 初始化系统**: 配置系统环境
8. **🔤 字体安装**: 自动安装和检测所需字体

### Excel数据格式

Excel文件应包含以下列（顺序必须与配置文件中一致）：

| 列名 | 说明 | 示例 |
|------|------|------|
| 姓名 | 学生姓名 | 张小明 |
| 英文名 | 英文昵称 | Tom |
| 性别 | 性别 | 男 |
| 生日 | 出生日期 | 2019-03-15 |
| 属相 | 生肖（自动计算） | 猪 |
| 我的好朋友 | 好朋友姓名 | 李小红 |
| 我的爱好 | 个人爱好 | 画画、唱歌 |
| 喜欢的游戏 | 喜欢的游戏 | 积木、捉迷藏 |
| 喜欢吃的食物 | 喜欢的食物 | 苹果、饼干 |
| 评价 | AI生成的评语 | 自动填充 |
| 表现特征 | 表现关键词（可选） | 活泼、聪明 |

### 图片文件结构

```
data/images/
├── K4D.jpg                 # 班级集体照片
└── 张小明/
    ├── me_image.jpg        # 学生个人照片
    ├── 1.jpg              # 活动照片1
    └── 2.jpg              # 活动照片2
```

支持多种图片格式：.jpg, .jpeg, .png

## 📁 项目结构

```
growth_report/
├── main.py                 # 主程序入口（命令行界面）
├── UI.py                   # 图形用户界面入口
├── config.env.toml         # 项目配置文件
├── pyproject.toml          # 项目依赖配置
├── start_app.bat           # 启动脚本
├── README.md               # 项目说明文档
├── IFLOW.md                # 项目详细说明文档
├── config/
│   ├── config.py           # 配置加载工具
│   └── output/             # 配置输出目录
├── utils/
│   ├── agent_utils.py      # AI评语生成工具
│   ├── file_utils.py       # 文件操作工具
│   ├── font_utils.py       # 字体安装和检测工具
│   ├── generate_utils.py   # 核心生成功能
│   ├── growt_utils.py      # PPT模板替换工具
│   ├── image_utils.py      # 图片处理工具
│   ├── pdf_utils.py        # PDF转换工具
│   ├── pptx_utils.py       # PPT文本和图片替换工具
│   └── zodiac_utils.py     # 生肖计算工具
├── data/
│   ├── names.xlsx          # 学生数据Excel文件
│   └── images/             # 学生图片资源文件夹
├── fonts/                  # 字体文件目录
├── templates/              # PPT模板文件
├── output/                 # 生成的报告输出目录
└── old/                    # 旧版本文件备份
```

## 🤖 AI评语生成

系统使用langchain框架与AI模型集成，根据以下信息生成评语：

- 幼儿姓名
- 所在班级（年龄段）
- 性别
- 表现特征

评语风格为"治愈系"，采用三段式结构：
1. **开头**: 亲切问候 + 总体印象
2. **正文**: 具体描述孩子的进步和优点
3. **结尾**: 委婉期望 + 新学期祝福

支持分龄侧重评价：
- **小班 (3-4岁)**: 适应集体生活、情绪稳定性、基本生活自理能力
- **中班 (4-5岁)**: 社交互动、分享与合作、动手能力、好奇心
- **大班 (5-6岁)**: 学习习惯、逻辑思维、领导力、幼小衔接准备

## 🔧 高级配置

### AI配置

在 `config.env.toml` 中配置AI模型：

```toml
[ai]
api_key = "your-api-key"
api_url = "https://api.openai.com/v1"
model = "gpt-3.5-turbo"
prompt = """
你的评语风格是"治愈系"的，能让家长读完后感到欣慰...
"""
```

### 自定义PPT模板

1. 在 `templates/` 目录放置PPT模板
2. 使用占位符格式：`{{变量名}}`
3. 支持的占位符：
   - `{{name}}`: 学生姓名
   - `{{class_name}}`: 班级名称
   - `{{comments}}`: 评语内容
   - 等等...

## 🐛 常见问题

### Q: PDF转换失败怎么办？
A: 请确保已安装Microsoft PowerPoint，并且没有其他程序占用PPT文件。

### Q: AI评语生成失败？
A: 检查API密钥配置是否正确，网络连接是否正常。

### Q: 字体显示异常？
A: 系统会自动安装所需字体，如仍有问题请手动安装 `fonts/` 目录下的字体文件。

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 项目地址: https://gitee.com/hanhanshibaobei/growthreport.git
- 邮箱: 27448307@qq.com

---

⭐ 如果这个项目对你有帮助，请给个星标支持一下！