fix:修复项目的README文档

This commit is contained in:
2026-01-24 23:48:44 +08:00
parent de71594812
commit 463c1c8b8f

127
README.md
View File

@@ -13,10 +13,11 @@
- 🤖 **AI评语**: 智能生成个性化、治愈系风格的幼儿评语
- 🖼️ **图文并茂**: 支持个人照片、活动照片、班级合影的自动替换
- 📄 **格式转换**: 批量PPT转PDF便于分发和存档
- 🎨 **多界面**: 提供命令行界面、tkinter图形界面和NiceGUI现代Web界面满足不同用户需求
- 🎨 **多界面**: 提供tkinter图形界面和NiceGUI现代Web界面满足不同用户需求
- 🐲 **生肖计算**: 根据生日自动计算生肖信息
- 📦 **模板导出**: 生成标准化数据模板,快速上手
- 🔤 **字体安装**: 自动检测和安装所需字体文件
- ✍️ **签名生成**: 不依赖占位符,直接在指定位置添加园长签名
## 🛠️ 技术栈
@@ -43,17 +44,19 @@
```bash
git clone https://gitee.com/hanhanshibaobei/growthreport.git
cd growthreport
cd growth_report
```
### 2. 安装依赖
#### 使用uv推荐
```bash
uv sync
```
#### 使用pip
```bash
pip install -r requirements.txt
```
@@ -65,27 +68,26 @@ pip install -r requirements.txt
- AI API密钥和配置
- 班级信息和教师名单
- 文件路径配置
- 签名位置配置(可选)
### 4. 运行程序
#### NiceGUI界面推荐现代Web界面)
```bash
python main_nicegui.py
```
#### 图形界面推荐tkinter界面)
#### 图形界面tkinter界面
```bash
python UI.py
python main.pyw
```
或直接运行:
```bash
start_app.bat
```
#### 命令行界面
#### NiceGUI界面现代Web界面
```bash
python main.py
python main_nicegui.py
```
## 📖 使用指南
@@ -100,24 +102,25 @@ python main.py
6. **📦 导出数据模板**: 生成标准化模板
7. **📤 初始化系统**: 配置系统环境
8. **🔤 字体安装**: 自动安装和检测所需字体
9. **✍️ 生成签名**: 不依赖占位符,直接在指定位置添加园长签名
### Excel数据格式
Excel文件应包含以下列顺序必须与配置文件中一致
| 列名 | 说明 | 示例 |
|------|------|------|
| 姓名 | 学生姓名 | 张小明 |
| 英文名 | 英文昵称 | Tom |
| 性别 | 性别 | 男 |
| 生日 | 出生日期 | 2019-03-15 |
| 属相 | 生肖(自动计算) | 猪 |
| 我的好朋友 | 好朋友姓名 | 李小红 |
| 我的爱好 | 个人爱好 | 画画、唱歌 |
| 喜欢的游戏 | 喜欢的游戏 | 积木、捉迷藏 |
| 喜欢吃的食物 | 喜欢的食物 | 苹果、饼干 |
| 评价 | AI生成的评语 | 自动填充 |
| 表现特征 | 表现关键词(可选) | 活泼、聪明 |
| 列名 | 说明 | 示例 |
| ------------ | ------------------ | ------------ |
| 姓名 | 学生姓名 | 张小明 |
| 英文名 | 英文昵称 | Tom |
| 性别 | 性别 | 男 |
| 生日 | 出生日期 | 2019-03-15 |
| 属相 | 生肖(自动计算) | 猪 |
| 我的好朋友 | 好朋友姓名 | 李小红 |
| 我的爱好 | 个人爱好 | 画画、唱歌 |
| 喜欢的游戏 | 喜欢的游戏 | 积木、捉迷藏 |
| 喜欢吃的食物 | 喜欢的食物 | 苹果、饼干 |
| 评价 | AI生成的评语 | 自动填充 |
| 表现特征 | 表现关键词(可选) | 活泼、聪明 |
### 图片文件结构
@@ -132,14 +135,29 @@ data/images/
支持多种图片格式:.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.py # 主程序入口(命令行界面)
├── UI.py # 图形用户界面入口tkinter
├── main_nicegui.py # NiceGUI界面入口
├── main.pyw # Windows图形界面启动文件
├── main_nicegui.py # NiceGUI界面入口
├── config.toml # 项目配置文件
├── pyproject.toml # 项目依赖配置
├── start_app.bat # 启动脚本
@@ -147,20 +165,19 @@ growth_report/
├── 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__/
│ │ ── task_runner.py # 任务运行器
│ └── views/
── home_page.py # NiceGUI主页面
── config_page.py # 配置页面
│ ├── data_page.py # 数据页面
│ └── home_page.py # 主页面
├── utils/
│ ├── agent_utils.py # AI评语生成工具
│ ├── file_utils.py # 文件操作工具
@@ -171,14 +188,14 @@ growth_report/
│ ├── log_handler.py # 日志处理器
│ ├── pdf_utils.py # PDF转换工具
│ ├── pptx_utils.py # PPT文本和图片替换工具
│ ├── template_utils.py # 模板处理工具
│ └── zodiac_utils.py # 生肖计算工具
├── data/
│ ├── names.xlsx # 学生数据Excel文件
│ └── images/ # 学生图片资源文件夹
│ ├── signature.png # 签名图片
├── fonts/ # 字体文件目录
├── templates/ # PPT模板文件
├── output/ # 生成的报告输出目录
└── old/ # 旧版本文件备份
└── public/ # 公共资源文件
```
## 🤖 AI评语生成
@@ -191,11 +208,13 @@ growth_report/
- 表现特征
评语风格为"治愈系",采用三段式结构:
1. **开头**: 亲切问候 + 总体印象
2. **正文**: 具体描述孩子的进步和优点
3. **结尾**: 委婉期望 + 新学期祝福
支持分龄侧重评价:
- **小班 (3-4岁)**: 适应集体生活、情绪稳定性、基本生活自理能力
- **中班 (4-5岁)**: 社交互动、分享与合作、动手能力、好奇心
- **大班 (5-6岁)**: 学习习惯、逻辑思维、领导力、幼小衔接准备
@@ -209,34 +228,50 @@ growth_report/
```toml
[ai]
api_key = "your-api-key"
api_url = "https://api.openai.com/v1"
model = "gpt-3.5-turbo"
api_url = "https://apis.iflow.cn/v1/chat/completions"
model = "deepseek-v3.2"
prompt = """
你的评语风格是"治愈系"的,能让家长读完后感到欣慰...
# Role
你是一位拥有20年经验的资深幼儿园主班老师。你的文笔温暖、细腻、充满爱意擅长发现每个孩子身上独特的闪光点。你的评语风格是“治愈系”的能让家长读完后感到欣慰并对未来充满希望。
# Goal
请根据用户提供的【幼儿姓名】、【年龄段/班级】以及【日常表现关键词/评分数据】,撰写一份高质量的学期末成长评语。
"""
```
### 自定义PPT模板
### 签名配置
1.`templates/` 目录放置PPT模板
2. 使用占位符格式:`{{变量名}}`
3. 支持的占位符:
- `{{name}}`: 学生姓名
- `{{class_name}}`: 班级名称
- `{{comments}}`: 评语内容
- 等等...
`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) 文件了解详情。
@@ -254,4 +289,4 @@ A: 系统会自动安装所需字体,如仍有问题请手动安装 `fonts/`
---
⭐ 如果这个项目对你有帮助,请给个星标支持一下!
⭐ 如果这个项目对你有帮助,请给个星标支持一下!