growth_report/README.md

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

[![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模板中，最终生成每个学生的个性化成长报告。系统支持UI界面操作，具备字体安装、图片替换、批量PDF转换、生肖计算、模板导出等完整功能。

## ✨ 主要特性

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

## 🛠️ 技术栈

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

## 📋 系统要求

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

## 🚀 快速开始

### 1. 克隆项目

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

### 2. 安装依赖

#### 使用uv（推荐）

```bash
uv sync
```

#### 使用pip

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

### 3. 配置系统

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

- AI API密钥和配置
- 班级信息和教师名单
- 文件路径配置
- 签名位置配置（可选）

### 4. 运行程序

#### 图形界面（推荐，tkinter界面）

```bash
python main.pyw
```

或直接运行：

```bash
start_app.bat
```

#### NiceGUI界面（现代Web界面）

```bash
python main_nicegui.py
```

## 📖 使用指南

### 功能模块

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

### Excel数据格式

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

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

### 图片文件结构

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

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

### 签名配置

在 `config.toml` 文件中，你可以配置签名图片的位置和大小：

```toml
[paths]
signature_image = "data/signature.png"  # 签名图片路径

# 签名位置配置（可选）
signature_left = 2987040    # 左位置
signature_top = 8273415     # 上位置
signature_width = 1800000   # 宽度
signature_height = 720000   # 高度
```

如果不配置签名位置，系统会使用默认值。

## 📁 项目结构

```
growth_report/
├── main.pyw                # Windows图形界面启动文件
├── main_nicegui.py         # NiceGUI界面入口
├── config.toml             # 项目配置文件
├── pyproject.toml          # 项目依赖配置
├── start_app.bat           # 启动脚本
├── README.md               # 项目说明文档
├── IFLOW.md                # 项目详细说明文档
├── config/
│   ├── config.py           # 配置加载工具
├── ui/
│   ├── app_window.py       # tkinter图形界面
│   ├── assets/
│   │   ├── icon.ico        # 应用图标
│   │   └── style.css       # 样式文件
│   ├── core/
│   │   ├── logger.py       # 日志处理
│   │   ├── state.py        # 应用状态管理
│   │   └── task_runner.py  # 任务运行器
│   └── views/
│       ├── config_page.py  # 配置页面
│       ├── data_page.py    # 数据页面
│       └── home_page.py    # 主页面
├── 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文本和图片替换工具
│   ├── template_utils.py   # 模板处理工具
│   └── zodiac_utils.py     # 生肖计算工具
├── data/
│   ├── signature.png       # 签名图片
├── fonts/                  # 字体文件目录
├── templates/              # PPT模板文件
├── output/                 # 生成的报告输出目录
└── public/                 # 公共资源文件
```

## 🤖 AI评语生成

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

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

评语风格为"治愈系"，采用三段式结构：

1. **开头**: 亲切问候 + 总体印象
2. **正文**: 具体描述孩子的进步和优点
3. **结尾**: 委婉期望 + 新学期祝福

支持分龄侧重评价：

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

## 🔧 高级配置

### AI配置

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

```toml
[ai]
api_key = "your-api-key"
api_url = "https://apis.iflow.cn/v1/chat/completions"
model = "deepseek-v3.2"
prompt = """
# Role
你是一位拥有20年经验的资深幼儿园主班老师。你的文笔温暖、细腻、充满爱意，擅长发现每个孩子身上独特的闪光点。你的评语风格是“治愈系”的，能让家长读完后感到欣慰并对未来充满希望。

# Goal
请根据用户提供的【幼儿姓名】、【年龄段/班级】以及【日常表现关键词/评分数据】，撰写一份高质量的学期末成长评语。
"""
```

### 签名配置

在 `config.toml` 中配置签名位置：

```toml
[paths]
signature_image = "data/signature.png"

# 签名位置配置
signature_left = 2987040    # 左位置
signature_top = 8273415     # 上位置
signature_width = 1800000   # 宽度
signature_height = 720000   # 高度
```

## 🐛 常见问题

### Q: PDF转换失败怎么办？

A: 请确保已安装Microsoft PowerPoint，并且没有其他程序占用PPT文件。

### Q: AI评语生成失败？

A: 检查API密钥配置是否正确，网络连接是否正常。

### Q: 字体显示异常？

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

### Q: 签名生成失败？

A: 检查签名图片路径是否正确，以及签名位置配置是否合适。

## 📄 许可证

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

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

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

---

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