67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# 教学反馈助手小程序
|
||
|
||
## Monorepo 结构
|
||
|
||
本项目使用单一 Git 仓库管理小程序、Rust API 和中文转录服务。版本提交、分支和远程仓库都只在项目根目录维护，不要在子目录再次初始化 Git 仓库。
|
||
|
||
- `pages/`、`utils/`：微信小程序界面与 API 客户端
|
||
- `server/`：Rust API、数据库迁移与异步转录任务
|
||
- `asr-service/`：基于 FunASR 的本地中文转录服务
|
||
- `compose.asr.yml`：转录服务的容器编排配置
|
||
|
||
## 本地开发
|
||
|
||
1. 确认微信开发者工具登录账号拥有 AppID `wx3fe11e262a4b4885` 对应小程序的开发权限。
|
||
2. 使用微信开发者工具命令行打开项目：
|
||
|
||
```bash
|
||
cli open --project /Users/zhangheng/project/ai/miniprogram/teaching-feedback-assistant --lang zh
|
||
```
|
||
|
||
3. 在微信开发者工具内编译、预览和调试。
|
||
|
||
反馈生成页使用小程序原生录音能力。短录音会直接追加到反馈内容，长录音每 8 分钟自动切片，多节录音可以汇总为一次反馈。真机首次使用时需要允许麦克风权限；中文转录默认使用项目自带的本地 FunASR 服务，不要求腾讯云密钥。
|
||
|
||
小程序默认连接生产服务 `https://feedback.shay7sev.site`。旧版本缓存的默认本地地址会自动迁移；如需调试本地 API，可在“我的”页面保存 `http://127.0.0.1:8080` 并检测服务状态。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
npm run typecheck
|
||
```
|
||
|
||
项目 AppID 已配置在 `project.config.json` 中。
|
||
|
||
## Rust 后端
|
||
|
||
Rust API 位于 [`server/`](./server)。它使用 Axum 和 PostgreSQL 驱动，但不会安装、启动或自动创建本地 PostgreSQL。
|
||
|
||
```bash
|
||
cd server
|
||
cp .env.example .env
|
||
# 在 .env 中填写 DATABASE_URL
|
||
cargo run --bin migrate
|
||
cargo run
|
||
```
|
||
|
||
另开一个终端启动中文转录服务。首次启动会下载 Paraformer、VAD 和标点模型，下载完成后健康检查才会显示语音服务可用：
|
||
|
||
```bash
|
||
docker compose -f compose.asr.yml up --build -d
|
||
curl http://127.0.0.1:10095/health
|
||
```
|
||
|
||
没有 Docker 时可按 [asr-service/README.md](./asr-service/README.md) 使用 Python 3.10 启动。Rust API 默认连接 `http://127.0.0.1:10095`；模型未就绪时已上传录音会保留在队列中，不会阻塞小程序上传。
|
||
|
||
未设置 `DATABASE_URL` 时，仅健康检查可用，数据接口会返回 `503`。数据库配置和迁移说明参见 [server/API.md](./server/API.md)。
|
||
|
||
服务启动后可打开 `http://127.0.0.1:8080/scalar` 查看并直接调用 Scalar 交互文档，原始规范位于 `http://127.0.0.1:8080/openapi.json`。完整测试顺序参见 [server/API_GUIDE.md](./server/API_GUIDE.md)。
|
||
|
||
## 小程序与后端
|
||
|
||
- 学生档案、档案预设和反馈记录均通过 `utils/api.ts` 访问 Rust API。
|
||
- 反馈页只暴露一个语音入口；反馈批次、课节、录音片段和转录状态由后端自动维护。
|
||
- 开发者工具模拟器和真机默认使用 `https://feedback.shay7sev.site`。
|
||
- 微信公众平台需要将该 HTTPS 域名同时配置为 `request` 和 `uploadFile` 合法域名。
|
||
- 小程序通过 `wx.login` 换取后端 Bearer 会话，普通请求和录音上传使用同一身份；部署配置和旧数据归属步骤见 [WECHAT_AUTH_PLAN.md](./WECHAT_AUTH_PLAN.md)。
|