# AI_English_Tutor

**Repository Path**: ZBeeeeeeeeee/AI_English_Tutor

## Basic Information

- **Project Name**: AI_English_Tutor
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 考研英语作文 AI Agent

[English](README.md) | **中文**

考研英语大小作文日常练习与 AI 智能批改平台。

## 功能

- **每日题目**：每天自动生成一篇大作文 + 一篇小作文题目
- **AI 批改**：提交作文后获得评分、逐句建议、参考范文
- **实时反馈**：SSE 推送批改进度，无需刷新
- **历史记录**：查看所有练习记录与批改详情
- **管理后台**：用户管理、作文记录、Token 消耗统计图表

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router |
| 后端 | FastAPI (ASGI) + SQLAlchemy (async) + Alembic |
| 异步任务 | Celery + Redis |
| AI | DeepSeek / OpenAI (可切换) + LLM Adapter 抽象层 |
| 数据库 | SQLite (dev) -> PostgreSQL (prod) |

## 快速开始

### 环境要求

- Python 3.9+
- Node.js 18+
- Docker (仅用于 Redis)

### 一键启动

```bash
./start-dev.sh start
```

脚本会自动：
1. 启动 Redis 容器
2. 运行数据库迁移 + 插入种子题目
3. 启动 FastAPI 后端 (端口 8000)
4. 启动 Celery Worker + Beat
5. 启动 Vite 前端 (端口 5173)

### 访问

| 地址 | 说明 |
|---|---|
| http://localhost:5173 | 前端应用 |
| http://localhost:8000/docs | 后端 API 文档 |

**首个注册用户自动成为管理员。**

### 配置 LLM

编辑 `backend/.env`：

```env
# 使用真实 DeepSeek API
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-key-here

# 或使用 OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o
```

未配置 API Key 时自动回退到 Mock 模式，返回模拟批改数据，保证 dev 模式可跑通。

### 其他命令

```bash
./start-dev.sh stop     # 停止所有服务
./start-dev.sh status   # 查看服务状态
```

### 运行 E2E 测试

```bash
cd backend
.venv/bin/python e2e_test.py
```

## 目录结构

```
AI_english_tutor/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 入口
│   │   ├── config.py            # 配置
│   │   ├── database.py          # SQLAlchemy async
│   │   ├── models/              # 5 个数据模型
│   │   ├── schemas/             # Pydantic 模型
│   │   ├── api/                 # 路由 (auth/topics/essays/tasks/admin)
│   │   ├── adapters/            # LLM 适配层 (base/deepseek/openai/mock)
│   │   ├── agents/              # AI Agent (题目生成/批改)
│   │   ├── tasks/               # Celery (worker/beat)
│   │   ├── services/            # 业务逻辑
│   │   └── utils/               # security/sse/redis
│   ├── alembic/                 # 数据库迁移
│   ├── seed.py                  # 种子数据
│   ├── e2e_test.py              # E2E 回归测试
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/                 # Axios 封装
│   │   ├── stores/              # Pinia (auth/topics)
│   │   ├── router/              # Vue Router + 守卫
│   │   ├── views/               # 页面组件
│   │   ├── components/          # 布局/业务组件
│   │   └── utils/               # SSE 客户端
│   └── vite.config.ts           # Vite + proxy 配置
└── start-dev.sh                 # 一键启动脚本
```

## Dev 模式前后端拉通

前端 Vite dev server (5173) 通过 proxy 将 `/api` 请求转发到后端 FastAPI (8000)：

```ts
// vite.config.ts
server: {
  proxy: { '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true } }
}
```

后端 CORS 允许 `localhost:5173`，SSE 长连接也通过代理正常工作。

## Docker 部署 (PostgreSQL + Nginx)

### 一键部署 (交互式)

```bash
./deploy.sh
```

首次运行会进入交互式配置向导：
1. 输入对外端口（默认 8080）
2. 选择 LLM 提供商（DeepSeek / OpenAI）
3. 输入 API Key（必填，校验格式）
4. 自动生成 JWT 密钥和数据库密码

配置写入 `.env.docker`（不提交 Git），然后自动构建启动。

### 端口配置

编辑 `.env.docker` 中的 `WEB_PORT`：

```env
WEB_PORT=8080
```

### 其他命令

```bash
./deploy.sh stop      # 停止
./deploy.sh restart   # 重启
./deploy.sh logs      # 查看日志
./deploy.sh down      # 停止并删除所有容器+数据
./deploy.sh reconfig  # 重新配置 (删除 .env.docker 重新引导)
./deploy.sh ps        # 查看状态
```

### 手动切换 PostgreSQL (dev 模式)

1. 修改 `backend/.env`：
   ```env
   DATABASE_URL=postgresql+asyncpg://user:pass@localhost/essay_app
   ```
2. 安装 asyncpg：`pip install asyncpg`
3. 运行迁移：`alembic upgrade head`
4. JSON 字段自动映射为 JSONB