fix:修复项目的README文档

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

101
README.md
View File

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