Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/changelog/20261016-200750-chore-小程序版本计划.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# chore:记录微信小程序版本计划

- 时间:2026-10-16 20:07:50(北京)
- 在需求目录记录小程序首版范围、现有接口依据、技术方案权衡、账号关联、M0–M4实施顺序与验收标准。
- 更新需求索引。本次只完成计划归档,未实现或发布小程序。
128 changes: 128 additions & 0 deletions docs/requirements/20261016-微信小程序版本.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# SpeakUp 微信小程序版本计划

状态:待设计(2026-10-16)。已记录产品范围、实施顺序和验收要求,尚未开始小程序实现。

## 背景与问题

用户希望 SpeakUp 增加小程序版本,方便在微信内随时练口语、查看反馈和回顾练习。本文按微信小程序规划;其他小程序平台后续另行评估。

现有 React Web 依赖浏览器录音、fetch 流式读取、localStorage 与浏览器路由,不能直接搬成小程序。后端现有场景、Attempt、反馈和复习数据应继续共用,避免建立另一套题库和练习记录。

## 目标与非目标

首版目标是完整跑通“进入场景 → 录音 → 转写并允许修改 → 提交评估 → 查看反馈和标准答案 → 重练 → 历史恢复 → 复习”的学习闭环,并能与 Web 使用同一业务账号。

- 题库、偏好、练习会话、Attempt、录音、反馈、复习项共用现有服务端模型与业务接口。
- 支持中文和英文界面、无图场景、权限拒绝、弱网与音频服务失败时的可恢复体验。
- 分享可打开指定练习结果,取消分享后原入口失效;只有公开分享接口允许匿名读取。
- 保留现有 Web,两个客户端分别构建和发布。

首版不包含实时语音对话、支付、订阅消息、独立小程序后台或 Web 全量组件重写。[实时语音探索](20260920-实时语音对话探索.md)独立推进,不作为首版前置依赖。

## 当前代码依据

| 位置 | 已有能力与迁移影响 |
|---|---|
| `web/src/api/client.js` | JSON、multipart、Bearer 鉴权,以及评估/追问两套 SSE 消费;需要小程序网络适配 |
| `web/src/context/UserContext.jsx` | 登录和偏好缓存;小程序需改用自己的存储及生命周期 |
| `server/routes/auth.py`、`server/services/auth_tokens.py` | 手机号入口创建业务会话,令牌摘要保存在 `authSessions`,业务接口验证 Bearer;目前手机号入口缺少号码归属验证 |
| `server/routes/transcribe.py` | multipart `audio/userId/practiceId`,检查登录用户一致性和 30MB 上限;实际录音格式仍需逐端验证 |
| `server/routes/correct.py` | 已有同步评估和 SSE;流式包含 `started/chunk/reset/done/error`,必须保留 Attempt 关联及服务切换重置语义 |
| `docs/design/schema.md`、`docs/业务/` | 业务数据与已实现行为的依据;新增微信身份映射后同步设计,不在本文假定已经落地 |

以上来自当前代码。入口文档仍有“无 token”的历史描述,实施时以代码和接口测试核对后同步修正。

## 方案权衡与暂定方向

| 方案 | 权衡 | 暂定决定 |
|---|---|---|
| Web 页面放入 web-view | 页面改造少,但录音、登录、分享与平台配置仍需验证 | 不作为首版主方案 |
| 原生微信小程序 + TypeScript | 可直接控制录音、网络、音频和生命周期,页面需要重写 | 优先方向,技术验证通过后定案 |
| 跨端框架 | 可能复用部分开发经验,但不能直接复用现有 DOM/CSS/浏览器能力,新增框架维护成本 | 仅当技术验证证明收益时采用 |

暂定新增 `miniprogram/` 客户端,复用 FastAPI/MongoDB/OSS 与既有 AI 服务。先复用接口契约和纯数据逻辑,避免为抽共享库提前大改 Web。Node 依赖用 pnpm,共用全局 store;Python 依赖继续用 uv。

### 登录与老账号

- 新增微信 code 的服务端交换入口,由服务端确认微信身份后签发现有业务 Bearer 会话;客户端提交的 openid 不作为身份凭据。
- 微信身份映射到现有 `userId`,不把 openid 直接当业务用户 ID;AppSecret、供应商密钥与微信会话密钥均留在服务端配置。
- 老账号关联必须验证号码或既有可信会话的控制权,不能只输入手机号就合并历史数据。具体绑定方式在第一阶段设计并测试;不因开发方便自动合并两个用户。
- 授权取消、会话失效、重复绑定、账号冲突和退出登录均有明确行为;小程序凭据与 Web 存储隔离。
- 当前手机号直接登录的既有风险是公开上线前待解决项,新增微信登录本身不能消除它;限制或升级旧入口须单独设计兼容方式。

### 录音、播放与流式反馈

- 通过小程序录音 API 实现开始、停止、试听和重录;先实测 iOS/Android 的编码、MIME、文件大小和后端转写兼容,再固定格式与时长限制。
- 录音上传复用现有 multipart 接口,并与服务端返回的 `attemptId` 关联;离开页面、来电或切后台后停止采集,保留可恢复提示,释放音频资源。
- TTS 复用后端返回音频地址及缓存;签名过期重新取得地址。小程序不依赖浏览器 `speechSynthesis`,朗读失败时保留文字并允许重试。
- 首选验证分块请求消费现有 SSE,覆盖 UTF-8 跨块、半帧、多帧、`reset`、取消、超时及断连。不能假设开发工具成功等于真机成功。
- 如果分块链路不可靠,先验证已有同步评估作为降级的完成时间和结果一致性;追问另定可恢复方案。断线后优先按会话/Attempt 查回结果,不能自动重复提交产生新轮次和收费调用。

## 页面范围

| 页面 | 首版内容 |
|---|---|
| 登录与引导 | 微信登录、老账号关联、隐私说明、录音权限及拒绝后的恢复 |
| 练习 | 场景/指定题、偏好、渐进提示、录音/试听、可编辑转写、提交与重练 |
| 结果 | summary、gaps、标准答案、朗读、已有反馈追问和收藏表达 |
| 历史/详情 | 分页、按 practiceId/attemptId 恢复、录音回放、再次进入结果 |
| 复习 | 错题与笔记、记住/未记住、恢复和用表达练题 |
| 我的/分享 | 昵称与偏好、语言、退出、分享开关和分享结果入口 |

自由说、头像修改、多图用户反馈在后续补齐;首版导航不展示尚不可用的入口。现有题库和头像按实际返回展示,默认关闭的场景生图不因新客户端而开启。

## 分阶段实施 checklist

### M0:平台与技术验证

- [ ] 确认小程序主体、AppID、可用类目、隐私申报与当前审核要求;域名/上传下载域名等在平台后台配置,不把实际地址和凭据写进仓库。
- [ ] 真机验证录音 → 上传 → ASR、TTS 播放、SSE 分块和分享入站;记录微信/系统/基础库版本、配置、失败样本与实际耗时。
- [ ] 核对服务端超时、代理缓冲、签名地址和跳转后的对象存储访问;开发工具关闭域名校验不算通过。
- [ ] 依据验证结果确定原生或跨端方案、最低基础库、同步降级边界及账号绑定协议。

### M1:项目骨架与账号

- [ ] 建立客户端工程、配置模板、双语字典、网络/上传/音频/存储适配和独立 CI。
- [ ] 完成微信登录、业务令牌复用、身份映射与老账号绑定;覆盖越权、伪造身份、冲突和重复请求。
- [ ] 区分开发/体验/正式环境;补服务端测试、模型说明及配置文档,不直接迁移现有数据。

### M2:练习和反馈闭环

- [ ] 接通场景、偏好、提示、会话创建、录音转写、文本修正和评估。
- [ ] 接通标准答案、差距反馈、TTS、追问、重练及 Attempt 录音关联。
- [ ] 页面参数保存必要业务 ID,冷启动/重进可从服务端恢复;提交中断、重复点击和流式重置无重复结果。

### M3:历史、复习和分享

- [ ] 接通历史、详情、复习项和收藏表达;与 Web 的同账号数据双向核对。
- [ ] 实现分享路径、匿名只读、取消分享失效、登录后返回原目标;分享参数不携带私人令牌。
- [ ] 完成“我的”、语言和偏好,核对首版功能矩阵及未支持项的呈现。

### M4:真机验收与发布准备

- [ ] 通过下表验收;记录真机证据、已知问题和后端/Web 回归结果。
- [ ] 完成平台当前要求的隐私说明、录音用途与权限文案,体验版验收后再提审;主体资格和审核材料以平台实际要求为准。
- [ ] 固定客户端版本、后端最低兼容版本、发布顺序与回退步骤;小程序审核周期内旧客户端仍可访问兼容 API。
- [ ] 实施完成后同步设计/业务/变更档案,再更新本需求状态。只有计划提交不能勾选这些实施项。

## 验收标准

| 范围 | 通过条件 |
|---|---|
| 学习闭环 | 两类真机均完成一题、查看反馈、重练和复习;无图题可正常练习 |
| 账号 | Web 老用户成功关联且历史不丢;不同用户不能读取私人记录或绑定他人账号;公开分享仅暴露原允许字段 |
| 录音 | 首次允许/拒绝、再次授权、静音、切后台、来电、重录和上传失败均可恢复;原声归属正确 Attempt |
| 反馈 | chunk/reset/done 顺序、跨块中文与错误正确处理;断线重进可恢复已保存结果,无隐式重复评估 |
| 音频 | 标准答案和录音可播,播放互斥;签名过期可重新取址;TTS 失败保留文本 |
| 数据互通 | Web 创建的历史/复习在小程序可见,反向也成立;偏好使用同一服务端事实源 |
| 分享 | 冷启动直达目标;匿名与已登录行为正确;取消分享后失效,非法参数有可返回页面 |
| 质量 | 客户端关键状态测试、后端鉴权/绑定/接口回归、Web 既有测试通过;开发工具和真机分别记录,skipped 不记为通过 |
| 成本与发布 | 测试使用专用测试账号、默认 mock 外部服务;真实语音小样本记账,无因重试重复调用;审核与兼容回退均有实际记录 |

性能指标先由 M0 测量录音上传、转写、首段反馈、完整评估和播放启动,再确定可接受阈值;本计划不编造耗时或工期承诺。

## 参考与进度交接

实施前核对微信官方[登录](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html)、[网络](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)、[请求](https://developers.weixin.qq.com/miniprogram/dev/api/network/request/wx.request.html)、[录音](https://developers.weixin.qq.com/miniprogram/dev/api/media/recorder/RecorderManager.html)文档及平台后台的最新要求。本次官方页面正文未能在线读取,平台能力、基础库限制和审核资格仍列为 M0 待验证项,不视为已确认结论。

2026-10-16:用户提出新增小程序版本,本次仅完成计划归档。下一步从 M0 小样本技术验证与账号关联设计开始,验证通过后再推进 M1–M4;尚未新增小程序代码、微信配置或发布行为。
1 change: 1 addition & 0 deletions docs/requirements/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@

| 状态 | 文件 | 范围 |
|---|---|---|
| 待设计 | [20261016-微信小程序版本.md](20261016-微信小程序版本.md) | 微信小程序首版学习闭环、账号关联、录音/流式验证及分阶段实施验收 |
| 已完成 | [20260918-运营通知飞书.md](20260918-运营通知飞书.md) | 注册与练习提交事件合并推送飞书,10 分钟一条,走 Open API 应用凭据(Infisical) |
| 已设计 | [20260826-渐进式场景提示.md](20260826-渐进式场景提示.md) | 新题按需逐条显示中文提示,含指定题目 URL、评分隔离、试点投放与可测量验收 |
| 待设计 | [20260920-实时语音对话探索.md](20260920-实时语音对话探索.md) | 引入实时语音对话模型,新增"有教学"的对话练习形态(先记录,未实施) |
Expand Down
Loading