# 成绩数据转换工具

**Repository Path**: magic-along/chengji3.0

## Basic Information

- **Project Name**: 成绩数据转换工具
- **Description**: Along成绩分析工具是一款专为学校设计的**自动化成绩处理与分析系统**，能够帮助教育工作者快速、准确地处理考试成绩数据。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📊 Along成绩分析工具使用操作文档

---

## 🎯 1. 程序概述

Along成绩分析工具是一款专为古蔺学校设计的**自动化成绩处理与分析系统**，能够快速结构化古蔺返回来的成绩分析统计数据，方便学校二次存储和查看，内置皇华中学成绩质量考核数据生成。

### ✨ 1.1 主要功能

✅ **自动数据处理**：智能识别并处理Excel格式的原始成绩数据  
✅ **多维度排名**：计算班级、校点、法人单位的成绩排名  
✅ **关键指标统计**：自动生成平均分、优生率、及格率等核心教育指标  
✅ **教学质量分析**：深入分析教师教学质量和获奖情况  
✅ **专业报表生成**：输出格式化、美观的Excel分析报表  
✅ **历史数据追踪**：合并历史数据支持长期教学质量趋势分析  

### 📁 1.2 程序结构

```
├── 🚀 chengji3.0.py          # 程序主入口
├── 🔧 jiegou_data.py         # 数据结构化模块
├── 📊 jisuan_data.py         # 成绩计算模块
├── 📦 chengjiFunction.py     # 通用功能函数库
└── 🗂️ data/                  # 数据目录
    ├── 📄 原始数据/          # 存放原始成绩文件
    ├── 📊 处理结果/          # 存放处理后的报表
    ├── 📚 历史数据/          # 存放合并的历史数据
    ├── 📥 返回数据/          # 古蔺返回的原始成绩文件
    └── ⚙️ config.json        # 程序配置文件
```

## 🛠️ 2. 安装与配置

### 💻 2.1 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 7/8/10/11 |
| Python版本 | 3.6或更高版本（推荐3.8+） |
| 依赖库 | pandas, openpyxl, styleframe |

### 📥 2.2 安装步骤

1. **安装Python环境**：确保已安装Python 3.6或更高版本  
2. **安装依赖库**：打开命令提示符，执行以下命令：  
   ```bash
   pip install pandas openpyxl styleframe
   ```
3. **获取程序文件**：将程序文件下载并解压到本地目录  
4. **自动配置**：首次运行程序时，系统会自动创建必要的数据文件夹结构  

### ⚙️ 2.3 配置文件说明

**⚠️ 重要提醒：首次使用前，请务必完善配置文件！**

程序配置文件 `data/config.json` 包含以下核心配置项，需根据学校实际情况修改：

| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| **学校信息** | 学校的法人名称、校点名称和班级编码前缀 | `"法人": ["古蔺县皇华初级中学校"]` |
| **城区学校** | 城区学校列表，用于区分城乡学校分类 | `["古蔺县东区实验学校", "古蔺县实验学校"]` |
| **考核分值** | 各项教学指标（平均分、优生率、及格率）的权重设置 | `"平均分": 20, "平均分权重": 0.7` |
| **计算年级** | 系统需要处理的年级列表 | `["7", "8", "9"]` |
| **考核分** | 根据排名计算的综合考核分数映射表 | `{"名次": 1, "分值": 20}` |
| **新接基础分** | 新接班级的基础分值补偿设置 | `{"名次": 12, "分值": 1}` |

**配置文件修改方法**：
1. 使用文本编辑器（如记事本、VS Code）打开 `data/config.json`
2. 根据学校实际情况修改对应配置项
3. 保存文件并关闭

## 📖 3. 使用指南

### 📋 3.1 准备工作

1. **准备原始数据**：
   - ⚠️ **仅支持古蔺返回的分析数据文件**！
   - 将古蔺返回的成绩分析统计Excel文件放入 `data/原始数据` 文件夹
   - 文件名示例：`2025年春期古蔺县期末成绩统计结果.xlsx`
   
2. **检查文件格式**：
   - 确保文件扩展名为 `.xlsx`（不支持 `.xls` 格式）
   - 确保文件包含完整的成绩数据区域
   
3. **完善配置文件**：
   - 务必检查并修改 `data/config.json` 中的学校信息
   - 确认考核分值和计算年级设置正确

### 🚀 3.2 运行程序

1. **启动方式**：
   - **EXE文件运行**（推荐）：直接双击 `chengji3.0.exe` 可执行文件  
   - **Python脚本运行**：直接双击 `chengji3.0.py` 文件  
   - **命令行运行**：在命令行中执行：
     ```bash
     python chengji3.0.py
     ```

   **EXE文件运行注意事项**：
   - `chengji3.0.exe` 文件需与 `data` 文件夹位于同一目录下  
   - 首次运行时，系统会自动创建必要的数据文件夹结构  
   - 无需安装Python环境即可运行  
   - 运行速度比Python脚本更快  

2. **欢迎界面**：程序启动后显示欢迎信息和主菜单
   ```
   ************欢迎使用Along成绩分析工具************
   
   请选择操作：
   1、计算考核数据
   2、结构化数据
   3、退出系统
   请输入操作序号：
   ```

### 📊 3.3 计算考核数据

1. **选择功能**：在主菜单输入 `1`，然后按回车键  

2. **选择文件**：程序会自动列出 `data/原始数据` 文件夹中所有的Excel文件
   ```
   1、2025年春期古蔺县期末成绩统计结果.xlsx
   2、2024年秋期古蔺县期末成绩统计结果（公布）.xlsx
   
   请输入需要处理的文件序号：
   ```

3. **开始处理**：输入对应文件的序号，然后按回车键  

4. **处理进度**：程序会实时显示处理进度
   ```
   年级:7
   年级:8
   年级:9
   ```

5. **完成提示**：处理完成后，程序会自动退出  

### 📂 3.4 查看结果

处理完成后，生成的考核数据文件将保存在 `data/处理结果/` 文件夹中：
- 文件名格式：`2025年春成绩考核数据.xlsx`
- 包含4个工作表：
  1. **法人排名数据**：各法人单位的成绩排名和综合考核数据
  2. **班级成绩考核数据**：各班的详细成绩和教学质量指标
  3. **教师教学质量获奖情况**：教师的获奖等级和相关评价数据
  4. **校点成绩统计**：各校点的成绩汇总和统计分析

### 📁 3.5 结构化数据

**功能说明**：仅对原始数据进行结构化处理，不生成完整的考核数据报表和合并历史数据。

1. **选择功能**：在主菜单输入 `2`，然后按回车键  
2. **选择文件**：程序会自动列出 `data/原始数据` 文件夹中所有的Excel文件  
3. **开始处理**：输入对应文件的序号，然后按回车键  
4. **处理进度**：程序会实时显示处理的年级信息  
5. **完成提示**：处理完成后，程序会自动退出  

### 🚪 3.6 退出系统

1. **选择功能**：在主菜单输入 `3`，然后按回车键  
2. **确认退出**：程序会自动退出

## 🔍 4. 功能详解

### 📊 4.1 数据结构化处理

程序采用智能识别算法，自动解析古蔺返回的成绩分析文件，将其转换为标准化的结构化数据。

**处理流程**：
1. **信息提取**：自动识别文件中的学期和年级信息  
2. **学科识别**：动态识别文件中包含的所有学科  
3. **区域划分**：智能划分不同数据区域（全县、城区、乡镇等）  
4. **指标结构化**：将各项成绩指标转换为统一格式  
5. **排名计算**：计算同类学校的相对排名  
6. **数据筛选**：精准筛选出本校相关数据  

### 📈 4.2 成绩考核计算

根据配置文件中的考核规则，多维度计算教学质量考核指标：

| 指标名称 | 说明 |
|---------|------|
| **平均分** | 班级、校点、法人单位的整体平均分 |
| **优生率** | 成绩达到优生线的学生比例 |
| **及格率** | 成绩及格的学生比例 |
| **学困率** | 学习困难学生的比例 |
| **均分差** | 与全县平均分的差值对比 |
| **考核分** | 根据排名计算的综合考核分数 |

### 🏆 4.3 获奖情况分析

基于教学成绩数据，智能分析教师的教学质量和获奖情况：

1. **计算平均名次**：统计教师所教学科的县平均名次  
2. **进步情况分析**：重点关注新接班级的成绩进步情况  
3. **获奖等级确定**：根据考核规则确定教师的获奖等级  

### 📚 4.4 历史数据合并

程序会自动将新处理的数据无缝合并到历史数据库中，支持长期教学质量趋势分析：

- 自动整合所有处理过的学期数据  
- 生成历史数据汇总分析表  
- 支持跨学期、跨年级的成绩对比分析  
- 为教育决策提供长期数据支持  

## ❓ 5. 常见问题与解决方案

### 🚫 5.1 程序无法启动

**症状**：双击程序后无反应或显示错误信息  

**解决方案**：
- ✅ 检查Python是否正确安装（推荐3.8+版本）  
- ✅ 确保已安装所有依赖库：`pip install pandas openpyxl styleframe`  
- ✅ 尝试在命令行中运行以查看详细错误信息  
- ✅ 检查系统是否有足够的内存和硬盘空间  

### 🔍 5.2 原始数据无法识别

**症状**：程序提示"没有需要处理的数据文件"  

**解决方案**：
- ✅ 确认文件已正确放入 `data/原始数据` 文件夹  
- ✅ 检查文件名是否包含中文，格式是否正确  
- ✅ 确保文件扩展名为 `.xlsx`（不支持 `.xls` 格式）  
- ✅ 确认文件是古蔺返回的分析数据文件  

### 📊 5.3 处理结果异常

**症状**：生成的报表数据有误或不完整  

**解决方案**：
- ✅ 仔细检查原始数据是否为古蔺返回的完整分析数据文件  
- ✅ 验证 `config.json` 中学校信息和编码是否正确  
- ✅ 确保原始数据包含所有必要的指标列  
- ✅ 尝试重新处理数据或更换原始数据文件  

### 📝 5.4 报表格式问题

**症状**：生成的Excel报表格式异常或乱码  

**解决方案**：
- ✅ 确保使用最新版本的Microsoft Excel打开  
- ✅ 检查系统区域设置是否为中文  
- ✅ 尝试重新生成报表  
- ✅ 确保计算机已安装必要的字体文件  

## 📚 6. 附录

### 📋 6.1 原始数据格式规范

**⚠️ 重要提醒：仅支持古蔺返回的分析数据文件！**

古蔺返回的成绩分析文件需满足以下基本要求：

#### 🔹 基本要求
- 文件格式：`.xlsx`（Excel 2007及以上版本）  
- 文件内容：包含完整的成绩统计数据，包括全县、城区、乡镇等各类别数据  
- 工作表：按年级划分工作表（如：7年级数据在"7"工作表中）  

#### 🔹 数据区域结构
原始文件需包含以下数据区域：
- ✅ 全县法人数据区域  
- ✅ 全县校点数据区域  
- ✅ 全县班级数据区域  
- ✅ 各类别数据区域（城区、乡镇等）  

### 📊 6.2 输出报表说明

生成的Excel报表包含以下核心数据：

| 数据类别 | 包含内容 |
|---------|---------|
| **基本信息** | 学期、年级、班级、学科、教师等 |
| **成绩指标** | 平均分、优生率、及格率、学困率等 |
| **排名数据** | 全县排名、同类学校排名 |
| **考核数据** | 均分差、综合考核分等 |
| **获奖信息** | 获奖等级、进步名次等 |

### 📝 6.3 更新日志

| 版本 | 更新内容 |
|------|---------|
| **v3.0** | - 重构程序架构，提高代码可维护性<br>- 优化数据处理算法，提升运行效率<br>- 新增历史数据合并功能<br>- 改进用户界面，增强操作友好性<br>- 强化错误处理和日志记录机制 |
| **v3.1** | - 简化菜单结构，优化用户操作流程<br>- 增加配置文件完善提醒<br>- 明确仅支持古蔺返回的分析数据文件<br>- 优化处理结果输出路径说明 |

## 🤝 7. 技术支持

如在使用过程中遇到问题或有改进建议，请联系技术支持：

- 🧑‍💻 作者：Along  
- 📌 版本：3.1  
- 📅 更新日期：2025年12月  

---

### 📄 版权声明

© 2025 Along成绩分析工具 | **仅供内部使用**

本工具仅供教育机构内部使用，未经授权请勿传播或用于商业用途。

---

**✨ 感谢使用Along成绩分析工具！✨**

---