# 学业辅导智能体

**Repository Path**: ysq233/learning-assistant-agent

## Basic Information

- **Project Name**: 学业辅导智能体
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学业分析智能体

高校学生成绩分析与学业预警系统，支持学生、辅导员、教师三个角色。

## 技术栈

- **前端**: React 18 + Vite 5 + TailwindCSS 3 + ECharts 5 + react-router-dom 6
- **后端**: Python FastAPI + ReportLab（PDF 导出）
- **数据**: SQLite `backend/app/app.db`
- **AI 对话**: OpenAI 兼容接口 SSE 流式输出（可选）

## 项目结构

```
sai/
├── backend/
│   └── app/
│       ├── main.py          # FastAPI 路由入口
│       ├── db.py            # 统一 SQLite 连接与 schema
│       ├── data_store.py    # SQLite 数据访问层
│       ├── agent.py         # AI 智能体客户端
│       └── pdf_export.py    # PDF 导出
├── frontend/
│   └── src/
│       ├── components/      # 通用组件（Layout/AgentChat/Charts/StudentDetailModal）
│       ├── pages/           # 页面（Login/Student/Counselor/Teacher）
│       ├── context/         # AuthContext
│       └── services/        # API 客户端
├── backend/app/app.db       # SQLite 样例数据库
└── plan_v1.md
```

## 快速启动

### 前置要求

- Node.js >= 18
- Python >= 3.10

### 1. 启动后端

```bash
# 安装依赖
cd backend
pip install -r requirements.txt

# 启动服务（热重载）
cd ..
uvicorn backend.app.main:app --reload --port 8000
```

后端运行在 `http://localhost:8000`。

### 2. 启动前端

```bash
# 安装依赖
cd frontend
npm install

# 启动开发服务器
npm run dev
```

前端运行在 `http://localhost:3000`（自动代理 API 请求到后端 8000 端口）。

### 3. 登录

页面会自动打开 `http://localhost:3000`，使用以下测试账号：

| 角色 | 账号 | 密码 |
|------|------|------|
| 学生 | 2020001 | 123456 |
| 辅导员 | C2000 | 123456 |
| 教师 | T1000 | 123456 |

密码支持固定值 `123456` 或使用与账号相同的字符串。

### 4. AI 智能体（可选）

在 `backend/.env` 中配置 API Key 即可启用 AI 对话：

```env
DEEPSEEK_API_KEY=your_deepseek_key
# 或使用其他 OpenAI 兼容接口：
# OPENAI_API_KEY=your_key
# OPENAI_BASE_URL=https://your-endpoint/v1
```

未配置时智能体仍可打开，但会提示未配置 API Key。

## 主要功能

- **学生**: 成绩总览、预警状态、学分获取饼图、成绩分布柱状图、课程成绩明细
- **辅导员**: 年级学业报表、预警分布统计、课程均分排名、预警学生名单（可点击查看详情与评语）
- **教师**: 任教课程选择、课程成绩统计、成绩分布图、挂科学生名单（可点击查看生涯档案与评语）
- **学期评语**（教师/辅导员可见）: 查看和添加学生每学期的评语记录
- **AI 智能体**: 可收起的右侧对话栏，回答学业相关问题
- **PDF 导出**: 学生成绩单、辅导员报表、教师课程统计

## SQLite 样例数据

`backend/app/app.db` 中包含：

| 表 | 记录数 | 说明 |
|------|--------|------|
| students | 520 | 学生信息 |
| teachers | 30 | 教师信息 |
| counselors | 20 | 辅导员信息 |
| courses | 49 | 课程信息 |
| enrollments | 552 | 教师授课关系 |
| scores | 31800 | 成绩记录 |
| student_comments | 19 | 学期评语样本 |

如需从旧 CSV/旧 SQLite 文件重建统一数据库，可参考 `backend/scripts/migrate_to_app_db.py`。运行时以 `app.db` 为唯一数据源。