From 65e310aaef28f100204c7c0225f962a92027716f Mon Sep 17 00:00:00 2001 From: Mint Grove Date: Fri, 16 Oct 2026 20:10:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E5=BE=AE=E4=BF=A1?= =?UTF-8?q?=E5=B0=8F=E7=A8=8B=E5=BA=8F=E7=89=88=E6=9C=AC=E5=AE=9E=E6=96=BD?= =?UTF-8?q?=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...10\346\234\254\350\256\241\345\210\222.md" | 5 + ...13\345\272\217\347\211\210\346\234\254.md" | 128 ++++++++++++++++++ docs/requirements/README.md | 1 + 3 files changed, 134 insertions(+) create mode 100644 "docs/changelog/20261016-200750-chore-\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254\350\256\241\345\210\222.md" create mode 100644 "docs/requirements/20261016-\345\276\256\344\277\241\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254.md" diff --git "a/docs/changelog/20261016-200750-chore-\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254\350\256\241\345\210\222.md" "b/docs/changelog/20261016-200750-chore-\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254\350\256\241\345\210\222.md" new file mode 100644 index 0000000..fa73e28 --- /dev/null +++ "b/docs/changelog/20261016-200750-chore-\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254\350\256\241\345\210\222.md" @@ -0,0 +1,5 @@ +# chore:记录微信小程序版本计划 + +- 时间:2026-10-16 20:07:50(北京) +- 在需求目录记录小程序首版范围、现有接口依据、技术方案权衡、账号关联、M0–M4实施顺序与验收标准。 +- 更新需求索引。本次只完成计划归档,未实现或发布小程序。 diff --git "a/docs/requirements/20261016-\345\276\256\344\277\241\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254.md" "b/docs/requirements/20261016-\345\276\256\344\277\241\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254.md" new file mode 100644 index 0000000..89d7bc4 --- /dev/null +++ "b/docs/requirements/20261016-\345\276\256\344\277\241\345\260\217\347\250\213\345\272\217\347\211\210\346\234\254.md" @@ -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;尚未新增小程序代码、微信配置或发布行为。 diff --git a/docs/requirements/README.md b/docs/requirements/README.md index 2c4fca7..41ee2c4 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -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) | 引入实时语音对话模型,新增"有教学"的对话练习形态(先记录,未实施) |