# AI面试官

**Repository Path**: gyd-cn/ai-interviewer

## Basic Information

- **Project Name**: AI面试官
- **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-09-16
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 面试官系统（AI Interviewer）

一套可运行、可测试、可演示的「AI 面试官系统」全栈项目：

> 简历解析 → AI 动态出题 → 多轮追问 → 自动评分 → 综合报告 → 数据分析

## 技术栈

| 端 | 技术 |
|---|---|
| 后端 | FastAPI · LangChain 0.3（LCEL）· pandas · SQLAlchemy 2.0 · JWT · bcrypt |
| 前端 | React 18 · TypeScript · Vite · Ant Design 5 · ECharts · zustand · axios |
| 数据 | MySQL（默认） / SQLite / PostgreSQL 任意切换 |
| AI | OpenAI 兼容（`OPENAI_API_KEY` 留空则自动规则降级） |

## 目录结构

```
20260916085613/
├── backend/                   # FastAPI 后端
│   ├── app/
│   │   ├── core/              # 配置 / 安全 / 日志
│   │   ├── db/                # SQLAlchemy 引擎 / 会话 / 初始化
│   │   ├── models/            # ORM 模型 + JSONType
│   │   ├── schemas/           # Pydantic 入出参
│   │   ├── api/               # FastAPI 依赖 + v1 路由
│   │   ├── services/          # 业务层
│   │   ├── ai/                # LLM 抽象 / 提示词 / 5 条 LCEL 链 / RAG / 记忆
│   │   ├── analytics/         # pandas 统计 + Excel 多 Sheet 报表
│   │   └── utils/             # 简历文件解析
│   ├── tests/                 # pytest 测试
│   ├── requirements.txt
│   ├── .env.example
│   └── README.md
├── frontend/                  # React 前端
│   ├── src/
│   │   ├── api/               # axios 请求层（含拦截器）
│   │   ├── store/             # zustand 登录态
│   │   ├── router/            # 路由 + 登录守卫
│   │   ├── layouts/           # 基础布局
│   │   ├── components/        # 通用组件
│   │   ├── pages/             # 页面
│   │   ├── styles/            # 主题与全局样式
│   │   └── types/             # 类型定义
│   ├── package.json
│   └── README.md
└── README.md                  # 你正在看的文件
```

## 快速开始

### 1. 启动后端

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate              # Windows
pip install -r requirements.txt
copy .env.example .env             # Windows；macOS/Linux 用 cp
uvicorn app.main:app --reload --port 8000
```

> **前置条件**：默认连接本机 MySQL（`root:root@127.0.0.1:3306`），库不存在会自动创建，
> 但需先启动 MySQL 服务，且账号密码与 `.env` 一致。
> 若暂时没有 MySQL，把 `.env` 里的 `DATABASE_URL` 改成 `sqlite:///./ai_interviewer.db`，即可零配置启动。

打开 `http://127.0.0.1:8000/docs` 查看 Swagger。

### 2. 启动前端

```bash
cd frontend
npm install
npm run dev                         # http://127.0.0.1:5173
```

`vite.config.ts` 已将 `/api` 反代到 `http://127.0.0.1:8000`。

### 3. 登录

| 账号 | 密码 | 角色 |
|---|---|---|
| `admin` | `admin123` | 管理员（可访问数据分析） |
| `interviewer` | `interview123` | 面试官 |

> 启动时若数据库为空，将自动建表 + 插入演示账号。

## 演示流程

1. **上传简历** → `/resumes` 上传 PDF/DOCX/TXT，自动解析画像
2. **创建面试** → `/interviews/new` 选择简历 + 难度 + 轮次
3. **智能出题** → `/interviews/:id` 点击「智能出题」，支持自动追问
4. **作答评分** → 输入候选人回答，自动评分 0-100，<70 分自动生成追问
5. **生成报告** → 点击「结束并生成报告」生成综合评估
6. **数据分析** → `/analytics`（管理员）查看 5 维度统计 + 趋势 + 薄弱点，支持一键导出 Excel

## 无 LLM API Key 也能跑

`OPENAI_API_KEY` 留空时：

- **简历画像**：基于关键词扫描 + 首段摘要
- **出题**：内置 7 套题库（technical / behavioral / project / system_design / coding × easy / medium / hard）
- **追问**：基于模板的「请结合具体例子」类追问
- **评分**：关键词命中率 × 60% + 表达密度 × 25%
- **报告**：按分数阈值生成优劣势清单与改进建议

切换到真实 LLM 只需在 `.env` 设置 `OPENAI_API_KEY`（兼容任何 OpenAI 协议服务，含 Azure / 国产代理）。

## 主要接口

```
POST /api/v1/auth/login
POST /api/v1/resumes/upload           (multipart/form-data)
GET  /api/v1/resumes
POST /api/v1/questions                (手动建题)
POST /api/v1/questions/generate       (智能出题)
POST /api/v1/interviews
POST /api/v1/interviews/{id}/answer   (提交作答 → 评分 + 追问)
POST /api/v1/interviews/{id}/report   (生成综合报告)
GET  /api/v1/dashboard/workbench      (工作台聚合：卡片 / 待办 / 趋势 / 漏斗)
GET  /api/v1/practice/scenarios       (8 大专项练习场景库)
GET  /api/v1/practice/scenarios/{code}
POST /api/v1/practice/sessions        (开始练习：free / timed / adversarial)
POST /api/v1/practice/sessions/{id}/answer
GET  /api/v1/practice/history
GET  /api/v1/practice/stats           (练习统计与进步曲线)
GET  /api/v1/analytics/overview
GET  /api/v1/analytics/export         (下载 xlsx 多 Sheet)
```

## 测试

```bash
cd backend
.venv\Scripts\python.exe -m pytest -q
```

当前结果：**59 passed**（覆盖健康检查、认证、简历解析、面试引擎、专项练习、工作台与数据分析层）。

## 设计要点

- **API 层零业务逻辑**：仅做参数装配与权限校验
- **统计口径单一来源**：所有聚合函数集中在 `app/analytics/pandas_engine.py`
- **跨库 JSON**：统一的 `JSONType`（PG → JSONB / MySQL → LONGTEXT / SQLite → TEXT），由类型装饰器自动完成序列化
- **资源隔离**：`scope_owner_id` 保证多租户/角色数据范围隔离
- **强降级**：LLM 任意一步失败都自动 fallback 到规则路径
- **Pydantic-ORM 解耦**：ORM 模型与 API Schema 分层，互相不耦合

## 许可证

仅用于演示与学习。