# ipa-study

**Repository Path**: 363359328/ipa-study

## Basic Information

- **Project Name**: ipa-study
- **Description**: 介于小学生一开始不学音标,   小学生学习音标和单词的工具.
软件读音均来自于权威站点，不是自己臆造
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IPA Study（音标达人）

面向小学生的英语音标与单词学习系统，包含微信小程序、抖音小程序、H5、管理后台和后端 API。

项目核心目标是：让孩子通过"听音辨音标 / 听音选单词 / 拖拽拼单词"的方式，在游戏中掌握国际音标和小学 3-6 年级核心词汇，并记录学习与错题情况。

## 功能概览

### 小程序端（uni-app）

- 音标表：全部 / 元音 / 辅音 分类浏览，支持试听与跟读
- 音标闯关：听音选择音标、音标发音评测
- 单词闯关：听音选词、拼词拖拽
- 发音评测：录音上传，音标使用本地信号算法，单词可接腾讯云 SOE
- 个人中心：积分、星星、学习记录、错题集（音标 + 单词）
- 未登录学习次数限制，达到阈值弹窗引导登录
- 微信 / 抖音授权登录（可选）

### 管理后台（Vue 3 + Element Plus）

- 仪表盘、用户管理、角色权限、操作日志
- 音标管理（增删改查、上传音频、批量排序）
- 单词关卡管理（按年级、音标、拼写拆分）
- 学习记录（音标学习 / 单词学习，错题红色提示）
- 系统设置（评测积分、星星基数、错题阈值、验证码开关、未登录学习上限）
- 第三方设置（微信、抖音登录配置）

### 后端 API（FastAPI）

- 统一 REST 接口，小程序与管理后台共用
- 数据库自动建表 + 初始化数据，无需手工导入 SQL
- JWT / 会话双模式登录
- 音标评测：librosa 提取 MFCC + fastDTW 对齐，抗语速变化
- 单词评测：mock 或腾讯云智聆口语评测（SOE），Provider 可切换
- 线程池执行 CPU / IO 密集任务，避免阻塞 Web 主线程

## 技术栈

| 模块 | 技术 |
| --- | --- |
| 后端 | Python 3.9+、FastAPI、SQLAlchemy、MySQL、Redis |
| 管理后台 | Vue 3、Vite、Element Plus、Pinia、Axios |
| 小程序 | uni-app（Vue 3 语法）、微信小程序 / 抖音小程序 / H5 |
| 语音评测 | librosa、fastDTW、scipy；腾讯云 SOE（可选） |
| 部署 | Nginx 反代 + uvicorn，默认 API 端口 8001 |

## 目录结构

```
ipa-study/
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── data/             # 内置音标表与 3-6 年级词库（JSON）
│   │   ├── routers/api/      # 接口路由
│   │   ├── services/         # 业务服务（评测、拼写拆分、第三方登录等）
│   │   ├── static/           # 静态资源目录（音频需自行准备）
│   │   ├── config.py         # 环境配置入口
│   │   ├── models.py         # 数据模型
│   │   ├── seed.py           # 初始化数据
│   │   └── main.py           # FastAPI 应用
│   ├── requirements.txt
│   └── run.py
├── frontend/                 # Vue 3 管理后台
├── uniapp/                   # uni-app 多端小程序
├── data/                     # 部署相关数据目录（默认空）
└── README.md / INSTALL.md
```

## 快速开始

两种部署方式：

- 传统部署（Python + Node + MySQL）：见 [INSTALL.md](INSTALL.md)
- Docker Compose 一键部署：见 [DOCKER.md](DOCKER.md)

本地开发最短路径：

1. 安装 MySQL 与 Redis，创建数据库 `ipa-study`（字符集 `utf8mb4`）
2. 后端：复制 `backend/app/.env.example` 为 `.env.local`，填写数据库、Redis、密钥
3. 启动后端：`cd backend && python run.py`，首次启动自动建表并写入音标 / 词库
4. 管理后台：`cd frontend && npm install && npm run dev`
5. 小程序：用 HBuilderX 打开 `uniapp/`，或执行 `npm run dev:mp-weixin`

默认管理员账号：

```
用户名：admin
密码：admin123
```

> 首次登录后请立即修改默认密码。

## 在线演示

管理后台演示地址：

```
http://douya-ipa.siruisoft.cn/
```

演示账号（只读）：

```
用户名：admin-demo
密码：admin123
```

演示账号可以查看全部菜单与数据，但无法新增、修改或删除任何内容，所有写操作都会被后端拒绝。

## 数据说明

仓库内置：

- `backend/app/data/ipa_phonemes.json`：48 个国际音标基础数据
- `backend/app/data/grade3_6_words.json`：小学 3-6 年级核心词汇（含音标、中文、拼写拆分）

为规避第三方版权风险，仓库不包含任何音标 / 单词音频文件。音频需自行准备：

- 音标音频：在管理后台"音标管理"中逐条上传，或批量放入 `backend/app/static/voices/` 后更新数据表字段
- 单词音频：在管理后台"单词关卡"中逐条上传
- 用户上传录音：运行时写入 `backend/app/static/uploads/`，该目录已加入 `.gitignore`

## 语音评测说明

### 音标评测（本地算法）

1. 小程序录音并上传到 `POST /api/eval/phoneme`
2. 后端根据提交的音标 symbol，从数据库查出对应标准音频路径
3. 使用 `librosa` 提取 MFCC，`fastDTW` 计算用户录音与标准音频的距离
4. 距离归一化后映射为 0-100 分

标准音频按数据库记录的地址读取，因此音频文件缺失时该音标无法评分。

### 单词评测（可切换 Provider）

通过 `.env` 中 `VOICE_PROVIDER` 切换：

- `mock`：返回模拟分数，便于本地开发与联调
- `tencent`：调用腾讯云智聆口语评测 SOE，需填写 `TENCENT_APP_ID`、`TENCENT_SECRET_ID`、`TENCENT_SECRET_KEY`

## 环境变量

后端支持两套环境文件，通过 `backend/app/config.py` 顶部开关切换：

```python
ENV_MODE = "local"   # local -> app/.env.local；server -> app/.env.server
```

也可以用环境变量临时覆盖：

```bash
APP_ENV=server python run.py
```

关键配置项：

| 变量 | 说明 |
| --- | --- |
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | MySQL 连接 |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_DB` / `REDIS_PASSWORD` | Redis 连接 |
| `JWT_SECRET_KEY` / `SECRET_KEY` | 生产环境务必替换为随机长字符串 |
| `SESSION_COOKIE_SAME_SITE` / `SESSION_COOKIE_SECURE` / `SESSION_COOKIE_DOMAIN` | 会话 Cookie 策略 |
| `CORS_ALLOW_ORIGIN_REGEX` / `CORS_ALLOW_ORIGINS` | 跨域白名单 |
| `VOICE_PROVIDER` | `mock` 或 `tencent` |
| `WECHAT_MINI_APPID` / `WECHAT_MINI_SECRET` | 微信小程序登录 |
| `DOUYIN_MINI_APPID` / `DOUYIN_MINI_SECRET` | 抖音小程序登录 |
| `IPA_GRADES` | 年级列表，默认 `3,4,5,6` |

## 常见问题

**登录成功但不跳转，接口返回 401**

多为 Cookie 策略不匹配。本地 http 使用 `SameSite=lax` + `Secure=false`；线上跨站 https 使用 `SameSite=none` + `Secure=true`。检查 `.env.local` / `.env.server` 是否用错。

**小程序请求接口失败**

检查 `uniapp/config/index.js` 中的 `domain` 是否指向后端地址，并在微信 / 抖音后台配置合法域名。

**音标评测总是不准**

确认数据库 `ipa` 表中对应音标的音频地址有效，且标准音频与目标音标一致。音频缺失时会直接返回错误或低保真分数。

**npm install 之后小程序仍报错**

小程序推荐使用 HBuilderX 内置编译器；命令行方式请确认 Node 版本与 `uniapp/package.json` 中依赖版本匹配。

## 开源协议与商业授权

本项目采用 **AGPL-3.0 + 商业授权** 双许可模式。

### 个人与非商用

个人学习、研究、教学演示等非商业用途，可免费使用本项目，并须遵守 [AGPL-3.0](LICENSE) 协议：

- 修改、分发本项目或其衍生作品时，必须以 AGPL-3.0 开源全部源码
- 通过网络向用户提供服务时，也必须向用户提供完整源码

### 商业使用

以下场景需要事先取得商业授权：

- 将本项目或其衍生作品用于任何形式的对外收费服务
- 在商业产品、商业网站、App、小程序中集成并对外运营
- 需要闭源使用、二次开发后闭源分发
- 需要去除 AGPL-3.0 的源码公开义务

商业授权不受 AGPL-3.0 约束，可提供闭源许可、定制开发与技术支持。

商业授权与咨询请联系：

```
邮箱：363359328@qq.com
```

> 商业授权与合作咨询请通过上述邮箱联系。

## 贡献

欢迎提交 Issue 与 Pull Request。提交前请确保不包含任何真实密钥、用户数据或受版权保护的音频资源。

## 辅助

本项目在开发过程中使用了 Codex + DeepSeek 辅助开发。
![输入图片说明](data/3in1.png)
![输入图片说明](data/c271d5a1-0976-4fb8-a476-fb3eaeefd372.png)