# 看一眼

**Repository Path**: a320gitlen/take-a-look

## Basic Information

- **Project Name**: 看一眼
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学生管理系统 (StuMagSys)

一个基于 FastAPI 和 SQLAlchemy 构建的现代化学生管理系统后端 API。

## ✨ 特性

- 🚀 基于 FastAPI 构建，性能优异
- 📚 完整的学生、成绩、就业、班级、教师管理功能
- 📊 丰富的统计分析功能
- 🤖 四大名著智能问答系统（基于 RAG）
- 📁 文件上传与向量检索功能
- 🧠 AI 智能助手
- 🔐 完整的权限管理系统
- 🔧 配置化管理，易于部署
- 📝 完整的 API 文档（Swagger UI）
- 🎯 符合行业规范的代码结构
- 🧪 类型安全（使用 Pydantic v2）

## 📋 系统要求

- Python 3.8+
- MySQL 5.7+

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd StuMagSys
```

### 2. 安装依赖

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

### 3. 配置数据库

创建 MySQL 数据库 `wolin`，用户名为 `root`，密码为 `123456`。

如需修改配置，请复制 `.env.example` 为 `.env` 并修改相应配置：

```bash
cp .env.example .env
# 编辑 .env 文件
```

### 4. 启动服务

**方式一：使用启动脚本（推荐）**
```bash
# 启动后端
start_server.bat

# 启动前端
start_frontend.bat
```

**方式二：直接使用 Python:**
```bash
python main.py
```

### 5. 访问系统

启动成功后，可以访问：

- **前端界面**: http://localhost:8000/simple-index.html
- **API 文档**: http://localhost:8001/docs
- **ReDoc**: http://localhost:8001/redoc
- **健康检查**: http://localhost:8001/health

## 📁 项目结构

```
StuMagSys/
├── Api/                      # API 路由层
│   ├── api_students.py      # 学生管理
│   ├── api_scores.py        # 成绩管理
│   ├── api_employment.py    # 就业管理
│   ├── api_classes.py       # 班级管理
│   ├── api_teachers.py      # 教师管理
│   └── api_statistics.py    # 统计分析
│
├── dao/                      # 数据访问层
│   ├── dao_students.py
│   ├── dao_scores.py
│   ├── dao_employment.py
│   ├── dao_classes.py
│   ├── dao_teachers.py
│   └── dao_statistics.py
│
├── db_model/                 # 数据库模型
│   ├── db_student_info.py
│   ├── db_employment.py
│   ├── db_score.py
│   ├── db_class.py
│   └── db_teacher.py
│
├── pdc_model/               # Pydantic 数据模型
│   └── schemas.py
│
├── config.py                # 配置文件
├── database_info.py         # 数据库连接
├── main.py                  # 应用入口
└── requirements.txt         # 依赖列表
```

## 🔌 API 端点

### 学生管理 (`/api/v1/students`)
- `POST /` - 添加学生
- `GET /` - 查询所有学生（分页）
- `GET /{student_id}` - 根据ID查询
- `GET /name/{student_name}` - 根据姓名查询
- `GET /class/{class_id}` - 根据班级查询
- `PUT /{student_id}` - 更新信息
- `DELETE /{student_id}` - 删除学生

### 成绩管理 (`/api/v1/scores`)
- `POST /` - 添加成绩
- `GET /` - 查询所有成绩
- `GET /{student_id}/{exam_order}` - 查询指定成绩
- `PUT /{student_id}/{exam_order}` - 更新成绩
- `DELETE /{student_id}/{exam_order}` - 删除成绩

### 就业管理 (`/api/v1/employment`)
- `GET /` - 查询所有就业信息
- `GET /{student_id}` - 根据ID查询
- `GET /class/{class_id}` - 根据班级查询
- `GET /company/{company_name}` - 根据公司查询
- `GET /salary/range` - 根据薪资范围查询
- `POST /` - 添加就业信息
- `PUT /{student_id}` - 更新信息
- `DELETE /{student_id}` - 删除信息

### 班级管理 (`/api/v1/classes`)
- `POST /` - 添加班级
- `DELETE /{class_id}` - 删除班级
- `PUT /{class_id}` - 更新班级
- `GET /{class_id}` - 根据ID查询
- `GET /` - 查询所有班级

### 教师管理 (`/api/v1/teachers`)
- `POST /` - 添加教师
- `GET /{teacher_id}` - 根据ID查询
- `PUT /{teacher_id}` - 更新教师
- `DELETE /{teacher_id}` - 删除教师

### 统计分析 (`/api/v1/statistics`)
- `GET /students/age/over-30` - 查询超过30岁的学生
- `GET /classes/count` - 统计班级人数
- `GET /students/gender/count` - 统计性别分布
- `GET /scores/excellent` - 查询优秀学生
- `GET /scores/below-60` - 查询不及格学生
- `GET /classes/average-score` - 统计班级平均分
- `GET /employment/top-salary` - 查询高薪学生
- `GET /employment/job-duration` - 统计就业时长
- `GET /classes/avg-job-duration` - 统计班级平均就业时长

### 四大名著学习 (`/api/v1/classics`)
- `GET /health` - 健康检查
- `POST /ask` - 智能问答接口
- `POST /files/upload` - 文件上传接口
- `POST /files/search` - 文件内容检索接口
- `GET /files/list` - 获取已上传文件列表

### AI 助手 (`/api/v1/ai`)
- `POST /chat` - AI 对话接口

### 权限管理 (`/api/v1/auth`)
- `POST /login` - 用户登录
- `GET /current-user` - 获取当前用户信息
- `POST /logout` - 用户登出

### 角色管理 (`/api/v1/roles`)
- `POST /` - 创建角色
- `GET /` - 获取角色列表
- `GET /{role_id}` - 获取角色详情
- `PUT /{role_id}` - 更新角色
- `DELETE /{role_id}` - 删除角色

### 权限管理 (`/api/v1/permissions`)
- `POST /` - 创建权限
- `GET /` - 获取权限列表
- `GET /{permission_id}` - 获取权限详情
- `PUT /{permission_id}` - 更新权限
- `DELETE /{permission_id}` - 删除权限

## 📝 使用示例

### 添加学生

```python
import requests

url = "http://localhost:8000/api/v1/students/"
data = {
    "class_id": "CS2024001",
    "student_name": "张三",
    "native_place": "北京",
    "graduated_school": "北京大学",
    "major": "计算机科学",
    "enrollment_time": "2020-09-01",
    "graduation_time": "2024-06-30",
    "education": "本科",
    "consultant_id": 1,
    "age": 22,
    "gender": "男"
}

response = requests.post(url, json=data)
print(response.json())
```

### 查询学生

```python
import requests

url = "http://localhost:8000/api/v1/students/"
response = requests.get(url)
print(response.json())
```

### 添加成绩

```python
import requests

url = "http://localhost:8000/api/v1/scores/"
data = {
    "student_id": 1,
    "exam_order": 1,
    "score": 85
}

response = requests.post(url, json=data)
print(response.json())
```

### 四大名著智能问答

```python
import requests

url = "http://localhost:8001/api/v1/classics/ask"
data = {
    "question": "诸葛亮在赤壁之战中起了什么作用？"
}

response = requests.post(url, json=data)
print(response.json())
```

### 文件上传

```python
import requests

url = "http://localhost:8001/api/v1/classics/files/upload"
files = {'file': open('example.txt', 'rb')}

response = requests.post(url, files=files)
print(response.json())
```

## ⚙️ 配置说明

### 主要配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| API_HOST | API 服务地址 | 0.0.0.0 |
| API_PORT | API 服务端口 | 8001 |
| DB_HOST | 数据库地址 | localhost |
| DB_PORT | 数据库端口 | 3306 |
| DB_USER | 数据库用户名 | root |
| DB_PASSWORD | 数据库密码 | 123456 |
| DB_NAME | 数据库名称 | wolin |
| DEFAULT_PAGE_SIZE | 默认分页大小 | 20 |
| MAX_PAGE_SIZE | 最大分页大小 | 100 |
| ALIYUN_API_KEY | 阿里云API密钥（四大名著功能） | - |

### 环境变量

创建 `.env` 文件来覆盖默认配置：

```env
APP_NAME=学生管理系统
DEBUG=True
API_HOST=0.0.0.0
API_PORT=8000
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=wolin
```

## 🧪 测试

使用 Swagger UI (http://localhost:8000/docs) 进行交互式测试。

## 📖 文档

详细的 API 文档请查看：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 🔄 代码优化说明

本项目已进行全面重构，主要优化内容包括：

1. ✅ 统一命名规范（英文命名，符合 PEP 8）
2. ✅ 模块化设计，职责清晰
3. ✅ 完整的文档字符串
4. ✅ 改进的错误处理
5. ✅ 统一的响应格式
6. ✅ 配置化管理
7. ✅ 类型注解完善

详细的重构说明请查看 [REFACTORING_SUMMARY.md](REFACTORING_SUMMARY.md)

## 🛠️ 开发

### 代码规范

- 遵循 PEP 8 规范
- 使用 Google 风格的文档字符串
- 所有函数都包含类型注解

### 运行开发服务器

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 👥 作者

StuMagSys 开发团队

## 📧 联系方式

如有问题，请联系开发团队。

---

**注意**: 本项目为教学演示项目，生产环境使用请进行必要的优化和安全加固。