# ai-practice 

**Repository Path**: smartoa/ai-practice

## Basic Information

- **Project Name**: ai-practice 
- **Description**: ai陪练
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Practice

AI Practice 是一个基于 `uni-app`、Vue 3、Node.js 和 Dify 的 AI 话术陪练与考试考评平台，面向客户经理培训、销售话术练习、考试发布和学习效果统计等场景。

项目不是纯前端应用。前端负责交互、语音录制和展示，Node.js 后端负责认证校验、Dify/TTS 代理、数据保存、考试判分和管理员统计，MySQL 负责持久化业务数据。

## 核心能力

- 话术陪练：支持 ICT 六步流程、政务云、信创云、可视化监管等业务场景。
- 严格流程练习：按当前步骤推进，未满足要求时允许用户分多轮补充，系统给出当前阶段提示并控制提示带来的评分影响。
- 自由练习：在 ICT 营销话术等场景中进行开放式对话，不强制按步骤推进。
- 语音交互：支持语音输入、语音识别、默认语音播报和停止朗读；HTTP 非安全上下文会按浏览器能力禁用语音能力。
- 复盘评分：保存完整对话、评分、反馈和未评分退出记录；评分结果不会把复盘 JSON 直接作为语音播放内容。
- 考试模式：支持单选、多选、判断、填空和问答题，支持提示、考试时限、重复考试规则、统一反馈和 AI/人工阅卷。
- 题库管理：管理员可下载 Excel 模板、导入草稿、在线编辑、发布版本、撤回发布和删除未使用草稿。
- 考试范围：支持全部人员或在部门/人员树中按部门、姓名、手机号选择参加人员。
- 统计分析：提供练习次数、会话详情、部门/人员树统计、考试成绩、逐题分析、逐人分析、分数分布、完成率、缺考率和知识点掌握度。
- 管理员授权：超级管理员可授权其他管理员，并编辑已授权管理员的名称和备注。

## 技术架构

```mermaid
flowchart LR
  Browser[uni-app H5 / 内置浏览器] --> Frontend[Vue 3 前端]
  Frontend -->|相对路径 /api| Backend[Node.js Express 后端]
  Frontend -->|platform-bridge| Native[Android / 鸿蒙 / iOS 容器]
  Backend -->|OAuth userinfo| Auth[认证网关]
  Backend -->|反向代理| Dify[Dify API / Workflow]
  Backend -->|语音合成| TTS[豆包 TTS 或 Dify TTS]
  Backend --> DB[(MySQL)]
  Backend --> AddressBook[chatbot 通讯录库]
```

### 技术栈

- 前端：`uni-app`、Vue 3、Vite、SCSS。
- 后端：Node.js、Express、`mysql2`、`multer`、`exceljs`、`sharp`。
- AI 服务：Dify Chat API、Dify Workflow、可选豆包语音合成。
- 认证：OAuth 2.0 代理流程，以及 Android、鸿蒙、iOS 的 `platform-bridge`。
- 部署：Nginx、systemd、Linux、Gitee。

## 页面和目录

当前底部导航为四个主要页面：

| 页面 | 文件 | 用途 |
| --- | --- | --- |
| 对话 | `pages/index/index.vue` | 选择话术、开始练习、AI 对话、提示、语音和复盘 |
| 考试 | `pages/exam/exam.vue` | 查看已发布考试、答题、提示和提交试卷 |
| 记录 | `pages/record/record.vue` | 查看话术练习记录和考试成绩 |
| 话术 | `pages/script/script.vue` | 浏览话术方案和业务知识 |

其他页面：

- `pages/record/detail.vue`：练习会话详情和完整事件记录。
- `pages/record/exam-detail.vue`：考生考试成绩及逐题详情。
- `pages/script/detail.vue`：话术详情。
- `admin/index.html`：独立管理员页面，不在普通应用导航中展示。

核心目录：

```text
.
├─ pages/                         # uni-app 页面
├─ components/chencc-difyChat/    # 对话、考试、语音和消息组件
│  ├─ composables/                # 会话、文件、语音等组合逻辑
│  └─ services/                   # Dify、TTS、记录和业务服务
├─ utils/                         # OAuth 与 Android/鸿蒙/iOS bridge
├─ server/                        # Express 后端、考试服务和数据库初始化
│  ├─ index.js                    # API、认证、代理和统计入口
│  ├─ exam-service.js             # 题库、考试会话和成绩逻辑
│  └─ db/init.sql                 # MySQL 初始化脚本
├─ admin/                         # 管理员页面
├─ file/                          # Dify DSL、Excel 和业务资料
├─ assets/scripts/                # 可复用话术资料
├─ scripts/                       # Dify 配置、诊断和部署脚本
├─ nginx/                         # Nginx 配置模板
├─ docs/                          # 开发、认证、考试和部署文档
└─ skills/dify-workflow-dsl/      # 项目专用 Dify DSL 校验规则
```

`人人过关考评助手` 等原型文件不属于当前主应用运行链路，不作为生产功能入口。

## 认证机制

认证入口由后端 `GET /api/auth-config` 返回配置，前端通过以下顺序处理：

1. 在 Android、鸿蒙或 iOS 容器中优先调用 `utils/platform-bridge.js` 获取用户身份。
2. 生产环境仍需 OAuth 获取 API 访问令牌；桥接身份没有令牌时会继续跳转 OAuth。
3. OAuth 回调后由后端兑换 token，并通过 userinfo 获取用户信息。
4. 后端以认证结果中的手机号作为用户 ID，不信任前端提交的 `userId`、分数或管理员标志。
5. 本地开发默认关闭鉴权，使用 `TEST_USER_ID`；生产环境应显式配置 OAuth，不要把 `AUTH_DISABLED=1` 带入生产。

认证相关文件：

- `utils/auth.js`：前端认证状态、OAuth 回调和用户信息处理。
- `utils/platform-bridge.js`：Android、鸿蒙、iOS 容器桥接。
- `docs/authentication.md`：认证接口和生产配置说明。
- `server/index.js`：后端 Bearer Token 校验、用户隔离和管理员授权。

生产环境 OAuth 回调地址必须与实际入口一致，例如：

```text
https://your-domain/practice/zs/
```

如果从 HTTP 入口进入，认证中心也必须登记对应的 HTTP 回调地址。实际入口由 Nginx 配置决定。

## Dify 和语音

前端只访问相对路径 `/api/dify/v1`，Dify API Key 保存在后端 `server/.env`，不会写入前端构建产物。后端主要代理：

- `/api/dify/v1/chat-messages`
- `/api/dify/v1/files/upload`
- `/api/dify/v1/audio-to-text`
- `/api/dify/v1/text-to-audio`
- `/api/dify/v1/messages`
- `/api/dify/v1/conversations`
- `/api/dify/v1/ict-strict/evaluate`
- `/api/doubao-tts`

主要 Dify DSL：

- `file/AI陪练助手对话流程-修复版.yml`：通用陪练流程。
- `file/AI陪练助手对话流程-ICT营销话术增强版.yml`：ICT 业务场景流程。
- `file/AI陪练助手-问答题评分工作流.yml`：考试问答题语义评分和提示流程。

Dify DSL 导入平台后才会生效。仅修改仓库中的 YAML 不会自动修改 Dify 服务端流程。

## 考试模式

考试功能由程序控制题目推进、考试时间、答题保存、客观题判分和最终成绩，Dify 只作为问答题语义评分与提示服务，不负责考试状态机。

支持的题目类型：

- 单选题、多选题、判断题、填空题。
- 问答题：允许任意非空回答提交，可使用语音输入；Dify 根据语义判断得分、缺失要点和反馈。

答题后反馈方式：

- 每题提交后立即显示。
- 交卷后统一显示。
- 答题后不反馈，但仍保存答题和最终得分。

管理员入口：

```text
https://your-domain/practice/zs/admin/
```

管理员页面分为：题库与配置、人工阅卷、成绩记录、成绩分析、练习统计和系统配置。管理员手机号、通讯录数据库和授权规则见 `docs/exam-mode.md`。

## 后端 API 概览

### 公共与认证

- `GET /api/health`：后端、数据库和外部服务配置健康信息。
- `GET /api/auth-config`：前端认证配置。
- `POST /api/auth-token`：OAuth code 换 token。
- `GET /api/auth-userinfo`：获取当前 OAuth 用户信息。
- `POST /api/client-log`：接收前端诊断日志，内容应脱敏。

### 练习和考试

- `GET/POST /api/practice-records`：查询、保存本人练习记录。
- `GET /api/practice-records/:recordNo`：查询本人练习详情。
- `POST /api/usage/events`：记录访问、会话、消息、语音和退出等使用事件。
- `GET /api/exams`：查询可参加的已发布考试。
- `POST /api/exams/:bankId/start`：创建考试会话。
- `POST /api/exam-sessions/:sessionNo/hint`：获取问答题提示。
- `POST /api/exam-sessions/:sessionNo/answer`：提交答案并推进题目。
- `GET /api/exam-sessions/:sessionNo/report`：查询考试报告。

### 管理员

管理员接口统一经过后端鉴权和角色校验，主要包括：

- 使用概览、部门/人员树和练习统计。
- 练习记录、会话详情和完整对话查看。
- 题库 Excel 模板、导入、编辑、发布、撤回和删除草稿。
- 考试成绩、逐题/逐人分析、专项统计和 Excel 导出。
- 管理员授权、名称备注编辑和状态管理。

## 数据模型

后端会在 MySQL 中使用或创建以下主要表：

- `practice_records`：已评分或已结束的练习记录。
- `practice_sessions`：每轮练习会话的开始、结束、场景和评分状态。
- `practice_session_messages`：练习中的用户消息、AI 回复和系统事件。
- `usage_events`：页面、消息、语音、评分和退出等事件流水。
- `admin_users`：管理员授权信息和状态。
- `exam_banks`：考试题库和版本。
- `exam_audiences`：考试参加范围。
- `exam_questions`：题目、选项、答案、提示和评分配置。
- `exam_sessions`：考生考试会话和成绩。
- `exam_answers`：逐题答案、得分、阅卷状态和反馈。

初始化或升级表结构：

```bash
mysql -uroot -p < server/db/init.sql
```

考试相关表由 `server/exam-service.js` 在服务启动时按需初始化并补充必要字段。生产数据库变更前必须备份并确认回滚方案。

## 环境变量

先复制模板：

```powershell
Copy-Item server/.env.example server/.env
```

常用配置分类：

| 分类 | 变量示例 | 说明 |
| --- | --- | --- |
| 服务 | `PORT` | Node 后端监听端口，默认 `3001` |
| Dify | `DIFY_BASE_URL`、`DIFY_API_KEY` | Dify 地址和应用密钥 |
| MySQL | `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE` | 业务数据库连接 |
| 本地调测 | `TEST_USER_ID` | 鉴权关闭时使用的测试用户 |
| OAuth | `AUTH_SERVER_DOMAIN`、`AUTH_CLIENT_ID`、`AUTH_CLIENT_SECRET`、`AUTH_REDIRECT_URI`、`AUTH_SCOPE` | 生产认证配置 |
| 管理员 | `ADMIN_PHONES`、`SUPER_ADMIN_PHONES` | 管理员白名单和超级管理员 |
| 通讯录 | `ADDRESS_BOOK_DATABASE` | chatbot 通讯录数据库名 |
| 考试评分 | `EXAM_GRADING_DIFY_BASE_URL`、`EXAM_GRADING_DIFY_API_KEY` | 可选的问答题评分 Workflow |
| TTS | `TTS_PROVIDER`、`DOUBAO_API_KEY`、`DOUBAO_RESOURCE_ID` | 豆包或 Dify 语音配置 |

安全要求：

- `server/.env` 只保存在本地或服务器，不提交 Git。
- 不要在前端配置 Dify Key、OAuth Client Secret、豆包 Key 或数据库密码。
- 生产环境必须配置 OAuth 和管理员白名单。
- `AUTH_DISABLED=1` 仅用于临时本地调测，不得用于生产。

## 本地开发

### 命令行运行

建议 Node.js 20 或更高版本：

```powershell
npm ci
Copy-Item server/.env.example server/.env
# 编辑 server/.env，至少配置 MySQL 和 Dify

npm run dev:server
npm run dev:h5 -- --port 8082
```

浏览器访问：

```text
http://localhost:8082/practice/zs/#/
```

如果本地配置或开发服务器未使用 `/practice/zs/` 基础路径，请以终端输出的实际地址为准。语音输入在普通 HTTP 下可能被浏览器禁用，建议使用 HTTPS 或受信任的内置浏览器环境。

### HBuilderX

这是一个 uni-app 工程，可以使用 HBuilderX 打开并运行到浏览器、App 或小程序。HBuilderX 适合多端调试；H5 本地开发也可以直接使用上面的 `npm run dev:h5`，不要求必须安装 HBuilderX。

## 构建、检查和部署

### 常用检查

```powershell
node --check server/index.js
node --check server/exam-service.js
npm run build:h5
git diff --check
npm audit --omit=dev
```

当前仓库没有正式的 lint、type-check、unit test 或 CI 命令；修改后应至少执行可用的语法检查和 H5 构建，并在提交说明中注明未执行的检查。

修改 Dify DSL 后：

```powershell
$files = Get-ChildItem -LiteralPath file -Filter '*.yml' | Select-Object -ExpandProperty FullName
python skills/dify-workflow-dsl/scripts/validate_project_dsl.py --strict $files
python -m unittest skills/dify-workflow-dsl/tests/test_project_validator.py -v
```

### 本地或服务器直接部署

```bash
sudo bash scripts/deploy-linux.sh
```

默认目录：

- 前端：`/opt/aizs-ui/zs`
- 后端：`/opt/aizs-ui/aipractice-server`
- systemd：`aipractice-server`
- Nginx：由服务器当前配置管理，脚本默认不覆盖现有 Nginx 配置。

### 从 Gitee 同步并部署

服务器已有源码目录时：

```bash
sudo bash scripts/sync-deploy-gitee.sh
```

服务器源码存在本地改动时脚本会停止，确认要以远端代码覆盖后才使用：

```bash
sudo FORCE_SYNC=1 bash scripts/sync-deploy-gitee.sh
```

脚本会拉取 `master`、构建 H5、发布前端和后端、重启 `aipractice-server`、执行 `nginx -t` 并 reload Nginx。服务器上的 `server/.env` 会被保留。

部署后检查：

```bash
systemctl status aipractice-server --no-pager -l
systemctl status nginx --no-pager -l
curl http://127.0.0.1:3001/api/health
```

更完整的更新、认证和 Nginx 说明：

- `docs/ai-update-deploy-guide.md`
- `docs/deploy-linux-nginx.md`
- `docs/sync-deploy-gitee.md`
- `docs/authentication.md`
- `docs/android-webview-tls-diagnostics.md`

## 安全和维护约定

- 后端认证和授权是唯一权限边界，前端隐藏按钮不等于权限控制。
- 练习记录、考试成绩和管理员数据必须按认证手机号进行服务端隔离。
- 不信任前端提交的用户 ID、分数、管理员标志、文件名、URL、Header 或 AI 返回内容。
- 不使用未消毒的 `v-html`、`eval` 或动态执行用户输入。
- 文件上传必须经过大小、类型和路径校验；上传目录不能被当作脚本执行目录。
- 修改数据库结构前先备份，并通过版本化迁移或可重复初始化逻辑处理。
- 生产日志应便于排查问题，但不得记录 Token、密码、Cookie、API Key 或完整个人敏感信息。
- 修改代码前先阅读调用链并检查 `git status`；提交时只暂存本次任务文件，不使用 `git add .`。

详细的 AI Agent 修改规范见 `AGENTS.md` 和 `docs/project-audit/AI_AGENT_PROJECT_GUIDE.md`。