# AI 语音面试系统 - 项目进度总结

> 更新日期: 2026-01-21

## 一、项目概述

**项目名称**: AI 语音面试系统 (轻医美行业)  
**项目周期**: 2026-01 至今  
**当前状态**: 🟡 开发中 (核心功能已完成，语音模式待优化)

## 二、已完成功能

### 2.1 用户端 (前端)

| 功能 | 状态 | 说明 |
|------|------|------|
| 欢迎页面 | ✅ | 品牌展示、开始面试入口 |
| 信息采集 | ✅ | 姓名输入、简历 PDF 上传 |
| 面试初始化 | ✅ | 调用 Workflow A 生成 session_id |
| 文字面试模式 | ✅ | 基于 /v3/chat API 的文字对话 |
| 语音面试模式 | 🟡 | RTC 连接正常，session_id 传递待优化 |
| 调试面板 | ✅ | 显示 session_id、API 响应、错误信息 |

### 2.2 管理后台

| 功能 | 状态 | 说明 |
|------|------|------|
| 登录页面 | ✅ | 账号密码认证 |
| 数据概览 | ✅ | 统计卡片、匹配度分布、状态饼图、排行榜 |
| 面试列表 | ✅ | 搜索、筛选、分页、阶段标签 |
| 面试详情 | ✅ | 匹配度圆环、维度评分、风险分析、对话记录 |
| 骨架屏加载 | ✅ | 优化加载体验，替代 v-loading 遮罩 |

### 2.3 后端服务

| 功能 | 状态 | 说明 |
|------|------|------|
| 文件上传 | ✅ | 支持 PDF，上传到自建文件服务器 |
| 面试初始化 API | ✅ | 调用 Workflow A，返回 session_id |
| 文字聊天 API | ✅ | 调用 /v3/chat，支持多轮对话 |
| 语音房间 API | ✅ | 调用 /v1/audio/rooms 创建 RTC 房间 |
| 管理后台 API | ✅ | 通过 Workflow C 查询 Coze 数据库 |

### 2.4 Coze 工作流

| 工作流 | ID | 功能 |
|--------|-----|------|
| Workflow A | 7597357422713798710 | 面试初始化：接收 name + file_url，解析简历，生成 session_id |
| Workflow B | 7595077233002840079 | 面试主流程：4 维度提问、评分、生成报告 |
| Workflow C | 7597376294612107318 | 数据查询：接收 table + sql，执行增删改查 |

### 2.5 基础设施

| 组件 | 状态 | 说明 |
|------|------|------|
| 自建文件服务器 | ✅ | Nginx + PHP，域名 files.test.ai.ireborn.com.cn |
| Coze 数据库 | ✅ | ci_interview_assessments, ci_interview_logs, ci_business_config |

## 三、技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                        用户端                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  欢迎页面   │→│  信息采集   │→│  面试页面   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                          ↓                ↓                 │
│                    文件上传          语音/文字模式           │
└─────────────────────────────────────────────────────────────┘
                           ↓                ↓
┌─────────────────────────────────────────────────────────────┐
│                      FastAPI 后端                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ /init-interview │ /api/chat  │ /api/room    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                       Coze 平台                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Workflow A  │  │ Workflow B  │  │ Workflow C  │         │
│  │ (初始化)    │  │ (面试主流程) │  │ (数据查询)  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                          ↓                                  │
│                    Coze Database                            │
└─────────────────────────────────────────────────────────────┘
```

## 四、待解决问题

### 4.1 语音模式 session_id 传递

**问题**: 语音模式下，session_id 无法通过 /v1/audio/rooms API 传递到 Workflow B

**已尝试方案**:
1. ❌ `config.session_id` - 不支持
2. ❌ `parameters` 字段 - 不支持
3. ❌ `user_id` 字段 - 可设置但 Workflow 无法读取
4. ❌ Volcengine RTC SDK `sendRoomMessage` - 不是 Coze 信令通道
5. 🟡 `@coze/realtime-api` SDK `session.update` 事件 - 待验证

**建议方案**:
- 在 Workflow B 开始时通过数据库查询最近的 session_id
- 或使用 `@coze/realtime-api` 的 `session.update` 事件

### 4.2 面试阶段字段

**已实现**: current_stage 数值映射
- >= 50: 面试完成 (求职动机阶段)
- >= 40: 素质项评估
- >= 30: 销售观评估
- >= 20: 销售技能
- >= 10: 简历上传

## 五、数据库表结构

### ci_interview_assessments
| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 (自动生成) |
| session_id | String | 会话 ID |
| candidate_name | String | 候选人姓名 |
| current_stage | String | 当前阶段 (10-50) |
| sales_skill_score | String | 销售技能分数 |
| sales_skill_report | String | 销售技能报告 |
| sales_concept_score | String | 销售观分数 |
| sales_concept_report | String | 销售观报告 |
| competency_score | String | 综合素质分数 |
| competency_report | String | 综合素质报告 |
| final_score_report | String | 最终评估报告 |
| resume_text | String | 简历文本 |
| risk_warning | String | 风险提示 |

### ci_interview_logs
| 字段 | 类型 | 说明 |
|------|------|------|
| log_id | String | 主键 (必填) |
| session_id | String | 会话 ID |
| stage | String | 面试阶段 |
| round | String | 轮次 |
| ai_question | String | AI 问题 |
| user_answer | String | 用户回答 |
| log_type | String | 日志类型 |

## 六、关键文件清单

### 前端
- `frontend/src/pages/interview/index.vue` - 欢迎页 + 信息采集
- `frontend/src/pages/interview/call.vue` - 面试页面 (语音/文字)
- `frontend/src/pages/admin/*.vue` - 管理后台页面
- `frontend/src/composables/useCozeRealtime.ts` - Coze Realtime SDK 封装
- `frontend/src/api/candidate.ts` - API 调用封装

### 后端
- `backend/main.py` - FastAPI 入口
- `backend/app/services/coze_service.py` - Coze API 服务
- `backend/app/routers/init.py` - 面试初始化 API
- `backend/app/routers/chat.py` - 文字聊天 API
- `backend/app/routers/room.py` - 语音房间 API
- `backend/app/routers/admin.py` - 管理后台 API

### 配置
- `backend/.env` - 环境变量 (PAT_TOKEN, BOT_ID, FILE_SERVER_TOKEN 等)
- `docs/upload.php` - 文件上传 PHP 脚本
- `docs/nginx-files-server.conf` - Nginx 配置

## 七、访问地址

| 服务 | 地址 |
|------|------|
| 用户端 | http://localhost:5173 |
| 管理后台 | http://localhost:5173/admin |
| 后端 API | http://localhost:8000 |
| 文件服务器 | https://files.test.ai.ireborn.com.cn |