# Student-Data-Visualization

**Repository Path**: hnyu-1009-dev/student-data-visualization

## Basic Information

- **Project Name**: Student-Data-Visualization
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2025-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Student Data Visualization

一个轻量级的前后端分离练习项目：后端使用 FastAPI + Pandas/Numpy/Matplotlib 处理 Excel 学生成绩并生成可视化图；前端使用 Vue 3 + TypeScript 负责文件上传与结果展示。

## 项目结构

```
Student-data-visualization/
├─ backend/                      # 后端（FastAPI）
│  ├─ main.py                    # 应用入口，挂载路由与静态目录
│  ├─ routers/
│  │  └─ upload_router.py        # 上传接口（/upload）
│  ├─ services/
│  │  ├─ excel_service.py        # Excel 读取、筛选与统计
│  │  └─ plot_service.py         # Matplotlib 绘图，输出综合图
│  ├─ utils/
│  │  └─ file_utils.py           # 文件保存等工具方法
│  ├─ uploads/                   # 前端上传的原始文件
│  ├─ outputs/
│  │  ├─ results/                # 过滤后的 Excel 结果
│  │  └─ charts/                 # 生成的可视化图片
│  └─ requirements.txt           # 后端依赖
└─ frontend/
   └─ data-visual/               # 前端（Vue 3 + TS + Vite）
      ├─ src/
      │  ├─ api/dataService.ts   # Axios 封装（指向 http://localhost:8000）
      │  ├─ components/UploadExcel.vue
      │  └─ pages/
      │     ├─ Home.vue          # 上传与筛选
      │     └─ Visualization.vue # 结果展示（图片 + 摘要）
      └─ package.json
```

## 运行环境

- Python 3.10+
- Node.js 20+（或更高，见前端 `package.json` 中 engines）

## 后端启动

1) 安装依赖

```
cd backend
pip install -r requirements.txt
```

2) 运行开发服务（默认 8000 端口）

```
uvicorn main:app --reload --port 8000
```

后端将：
- 暴露 `POST /upload` 接口用于上传 Excel 并返回统计结果与图片路径
- 挂载静态目录 `/outputs`，前端可通过 `http://localhost:8000/outputs/...` 访问图片

## 前端启动

```
cd frontend/data-visual
npm install
npm run dev
```

默认在 `http://localhost:5173` 打开前端，已将请求指向 `http://localhost:8000`（见 `src/api/dataService.ts`）。

## 使用流程

1) 在前端首页选择/拖拽上传 Excel 文件，并选择年级、班级
2) 前端调用后端 `POST /upload`（`multipart/form-data`）提交字段：
   - `file`: Excel 文件
   - `grade`: 例如：`高一`/`高二`/`高三` 或 `全部`
   - `className`: 例如：`一班`、`二班`、… 或 `全部`
3) 后端读取 Excel，按筛选条件过滤数据，计算摘要，并在 `outputs/charts/` 生成综合图
4) 前端接收 `image_path` 和 `summary`，在可视化页面展示

## Excel 字段要求（示例）

- 基础维度：`年级`、`班级`
- 学科列：`语文`、`数学`、`英语`、`物理`、`化学`、`生物`
- 可选：`总分`（若缺失会按学科列求和生成）

兼容常见的中英文/大小写命名（如 `Grade/grade`、`Class/class`），并将年级、班级做了简单映射匹配。

## 主要接口

- `POST /upload`
  - Body: `multipart/form-data`
  - Fields: `file`, `grade`, `className`
  - Response:
    ```json
    {
      "status": "success",
      "summary": { "总人数": 60, "语文平均": 96.5, ... },
      "image_path": "outputs/charts/高三_一班_overview.png"
    }
    ```

## 常见问题

- Matplotlib 中文乱码：
  - 代码中已配置 `SimHei`/`Microsoft YaHei`，若仍乱码，请在系统安装中文字体或调整 `plot_service.py` 的字体设置。
- 跨域（CORS）：
  - 后端已全量开启 CORS，若部署环境域名/端口变化，请同步更新前端 `baseURL`。
- 图片无法显示：
  - 确认后端已通过 `app.mount("/outputs", ...)` 暴露静态目录；前端拼接的图片 URL 是否为 `http://localhost:8000/${image_path}`。

## 许可

仅供学习与练习使用。
![1761582421857](./data/image1.png)
![1761582421857](./data/image2.png)
![1761582421857](./data/image3.png)