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
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# chore:明确小程序完整功能与托管服务端要求

- 时间:2026-10-16 20:25:03(北京)
- 按用户确认将网页全部用户功能作为首版最低要求,取消自由说、头像和多图反馈延期,补充全功能对照及发布门槛。
- 记录云函数优先、无需自管服务器的服务端目标,覆盖托管数据库、对象存储、后台任务、部署和迁移回退。
- 更新需求索引;本次只修订计划,尚未实现客户端、创建云资源或迁移生产。
67 changes: 49 additions & 18 deletions docs/requirements/20261016-微信小程序版本.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,16 @@

## 目标与非目标

首版目标是完整跑通“进入场景 → 录音 → 转写并允许修改 → 提交评估 → 查看反馈和标准答案 → 重练 → 历史恢复 → 复习”的学习闭环,并能与 Web 使用同一业务账号。
**首版最低要求:小程序具备网页端全部现有用户功能,业务行为和数据一致,不交付功能裁剪版。** 学习闭环和同账号互通只是其中一部分,不能代替全功能验收。

**服务端目标:优先采用云函数及配套托管服务,使用户无需购买、部署或维护常驻服务器。** 选型、流式语音链路和成本通过技术验证确定;这不是已完成的部署承诺。

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

首版不包含实时语音对话、支付、订阅消息、独立小程序后台或 Web 全量组件重写。[实时语音探索](20260920-实时语音对话探索.md)独立推进,不作为首版前置依赖。
不额外新增网页尚未实现的实时语音对话、支付、订阅消息等业务。[实时语音探索](20260920-实时语音对话探索.md)独立推进;若其在小程序验收前成为网页正式功能,也要纳入对照。界面可适配小程序交互习惯,但不得以平台差异为由取消用户能力;确有技术障碍时先研究等价方案并记录缺口,未解决不得宣称功能对齐。

## 当前代码依据

Expand All @@ -40,7 +42,19 @@
| 原生微信小程序 + TypeScript | 可直接控制录音、网络、音频和生命周期,页面需要重写 | 优先方向,技术验证通过后定案 |
| 跨端框架 | 可能复用部分开发经验,但不能直接复用现有 DOM/CSS/浏览器能力,新增框架维护成本 | 仅当技术验证证明收益时采用 |

暂定新增 `miniprogram/` 客户端,复用 FastAPI/MongoDB/OSS 与既有 AI 服务。先复用接口契约和纯数据逻辑,避免为抽共享库提前大改 Web。Node 依赖用 pnpm,共用全局 store;Python 依赖继续用 uv。
暂定新增 `miniprogram/` 客户端,复用现有业务规则、数据及 AI 服务;现有 FastAPI/MongoDB/OSS 是迁移依据,服务端最终部署按下节托管方案验证。先复用接口契约和纯数据逻辑,避免为抽共享库提前大改 Web。Node 依赖用 pnpm,共用全局 store;Python 依赖继续用 uv。

### 服务端:云函数与托管服务

- 优先调查阿里云 FC,北京区域作为默认候选;普通 API 不绑定现有 Docker/Caddy/SSH 部署。是否使用 FastAPI 适配入口由实际验证决定,业务逻辑与运行平台分离。
- 数据库同样必须有无需自管服务器的方案。现有 MongoDB 作为兼容基线,调查托管数据库的兼容性、网络、连接池、索引、备份和费用;不能只迁 API、仍要求用户维护数据库主机。保留历史用户、练习、Attempt、复习、分享及鉴权数据,不直接假定换连接串即可迁移。
- 录音、头像、反馈图片和缓存音频进入托管对象存储;签名、权限、跨端读写、上传下载限制逐项验证,私钥和供应商凭据只在服务端取用。
- 派题生成、定制题、通知、语音/评估等后台工作盘点进程内任务、定时器和长连接,改用合适的托管异步/定时触发及持久任务状态;覆盖重复、超时、进程退出、部分成功与恢复,不依赖常驻工作进程。
- SSE/流式追问、录音上传、ASR/TTS的正文大小、执行时间、代理缓冲、连接中断和冷启动都要真机加真实云入口验证。改传输方式可以,不能因此丢掉网页的流式反馈、追问或失败恢复能力。
- 网页与小程序共用同一业务服务及数据,不维护功能分叉。设计现有网页到新入口的兼容迁移与回退;切换前保留旧部署,实际验收和在途工作交接完成后才能退役。
- 发布通过 Git 与 CI,配置/取密、日志、告警、域名、备份恢复均使用托管方案;发布及运行都不能回到原服务器取配置、转发请求或执行任务。
- 普通请求空闲时不靠保活维持实例;托管数据库、存储、网络与调用可能仍产生费用。先比较实测成本、最低消费及运维负担,再决定具体产品与规格,不把“无需自管服务器”写成“免费”。
- 本次只记录方向,不购买资源、不迁移数据库、不切生产或删除旧服务器。需要新增付费资源或生产迁移时,先形成具体可审阅方案。

### 登录与老账号

Expand All @@ -58,23 +72,32 @@
- 首选验证分块请求消费现有 SSE,覆盖 UTF-8 跨块、半帧、多帧、`reset`、取消、超时及断连。不能假设开发工具成功等于真机成功。
- 如果分块链路不可靠,先验证已有同步评估作为降级的完成时间和结果一致性;追问另定可恢复方案。断线后优先按会话/Attempt 查回结果,不能自动重复提交产生新轮次和收费调用。

## 页面范围
## 全功能对照范围

| 页面 | 首版内容 |
|---|---|
| 登录与引导 | 微信登录、老账号关联、隐私说明、录音权限及拒绝后的恢复 |
| 练习 | 场景/指定题、偏好、渐进提示、录音/试听、可编辑转写、提交与重练 |
| 结果 | summary、gaps、标准答案、朗读、已有反馈追问和收藏表达 |
| 历史/详情 | 分页、按 practiceId/attemptId 恢复、录音回放、再次进入结果 |
| 复习 | 错题与笔记、记住/未记住、恢复和用表达练题 |
| 我的/分享 | 昵称与偏好、语言、退出、分享开关和分享结果入口 |
以网页当前路由、页面、组件、接口及实际行为共同建立清单;下表是起始范围,不是允许遗漏未列功能的白名单。M0记录基准提交,实施期间跟踪网页新增/变更,发布前重新核对最新基准。每项记录网页入口、小程序入口、行为/数据、异常场景、测试和真机证据。

自由说、头像修改、多图用户反馈在后续补齐;首版导航不展示尚不可用的入口。现有题库和头像按实际返回展示,默认关闭的场景生图不因新客户端而开启。
| 网页功能 | 小程序最低对齐范围 |
|---|---|
| 登录与引导 | 同一业务账号、登录后回原目标、会话失效、退出及旧账号关联;微信登录是平台适配 |
| 场景练习 | 全部现有练习模式、指定题、偏好、渐进提示、换题、无图题、录音/试听/重录、手动输入与转写修正 |
| 自由说 | 话题抽取/切换、去重、录音建会话、评估与重练,和网页相同 |
| 结果与追问 | summary、gaps、进步对比、标准答案/重点表达、例句、朗读、流式追问、复制与选词/收藏笔记等网页现有操作 |
| 历史与详情 | 全部现有列表/分页、各轮Attempt恢复、原声回放和再次进入结果 |
| 错题本与笔记 | 错题/好表达、翻译、复习、记住/未记住、收纳/恢复、删除和用表达练题等现有操作 |
| 个人资料与设置 | 昵称、头像上传/更换/恢复默认、练习偏好、语言和主题(跟随系统/浅色/深色) |
| 用户反馈 | 结果页赞踩/标签/文字、多图原件上传、全局反馈及网页已有提交记录/状态 |
| 分享与管理 | 开启/取消分享、分享管理、公开详情、复制/转发、冷启动直达和登录后回原目标 |
| 共同行为 | 加载/空/错误/重试、权限、弱网、页面重进恢复、双语与跨端数据同步 |

自由说、头像修改、多图反馈均在首版必交付范围。默认关闭的场景生图等配置沿用网页规则,不为小程序单独减少功能。截图逐像素相同不是要求,用户可完成的操作、结果、权限和异常恢复必须等价。

## 分阶段实施 checklist

### M0:平台与技术验证
### M0:全功能盘点、平台与云端技术验证

- [ ] 从网页最新基准建立逐功能/子操作清单,覆盖所有路由、组件交互及异常路径;首版范围不留“后续补齐”。
- [ ] 盘点服务器依赖,形成云函数、托管数据库、对象存储、异步任务、定时触发、日志告警和CI发布方案,比较兼容性、成本及迁移回退。
- [ ] 真正云入口验证冷/热请求、流式反馈、语音上传/转写/播放、数据库连接和失败恢复;本地启动不代替云端验证。
- [ ] 确认小程序主体、AppID、可用类目、隐私申报与当前审核要求;域名/上传下载域名等在平台后台配置,不把实际地址和凭据写进仓库。
- [ ] 真机验证录音 → 上传 → ASR、TTS 播放、SSE 分块和分享入站;记录微信/系统/基础库版本、配置、失败样本与实际耗时。
- [ ] 核对服务端超时、代理缓冲、签名地址和跳转后的对象存储访问;开发工具关闭域名校验不算通过。
Expand All @@ -85,22 +108,26 @@
- [ ] 建立客户端工程、配置模板、双语字典、网络/上传/音频/存储适配和独立 CI。
- [ ] 完成微信登录、业务令牌复用、身份映射与老账号绑定;覆盖越权、伪造身份、冲突和重复请求。
- [ ] 区分开发/体验/正式环境;补服务端测试、模型说明及配置文档,不直接迁移现有数据。
- [ ] 建立云函数部署与取密、托管数据访问及可追溯发布/回退,不新增自管常驻服务。

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

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

### M3:历史、复习和分享
### M3:补齐全部网页功能

- [ ] 接通历史、详情、复习项和收藏表达;与 Web 的同账号数据双向核对。
- [ ] 实现分享路径、匿名只读、取消分享失效、登录后返回原目标;分享参数不携带私人令牌。
- [ ] 完成“我的”、语言和偏好,核对首版功能矩阵及未支持项的呈现。
- [ ] 完成昵称、头像上传/恢复默认、语言、主题和偏好。
- [ ] 完成结果反馈与全局反馈、多图上传、记录/状态,以及结果页表达讲解、复制/收藏等网页全部子操作。
- [ ] 按M0清单逐项消除差异;阶段只划分实施顺序,不代表允许裁剪发布。

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

- [ ] 通过下表验收;记录真机证据、已知问题和后端/Web 回归结果。
- [ ] 对网页最新基准逐项全量验收,覆盖所有用户功能和子操作;缺项不得作为首版发布。记录真机证据、已知问题和后端/Web回归结果。
- [ ] 验证完整运行链路无需自管服务器,完成托管数据备份恢复、异步故障恢复、费用评估及旧服务切换/回退演练;未验收前不退役原服务。
- [ ] 完成平台当前要求的隐私说明、录音用途与权限文案,体验版验收后再提审;主体资格和审核材料以平台实际要求为准。
- [ ] 固定客户端版本、后端最低兼容版本、发布顺序与回退步骤;小程序审核周期内旧客户端仍可访问兼容 API。
- [ ] 实施完成后同步设计/业务/变更档案,再更新本需求状态。只有计划提交不能勾选这些实施项。
Expand All @@ -109,6 +136,8 @@

| 范围 | 通过条件 |
|---|---|
| 全功能一致 | 网页功能/子操作清单全部逐项通过;自由说、头像、多图反馈、主题等均不可延期;技术缺口未解决不得标完成 |
| 无需自管服务器 | API、数据库、文件、后台任务、调度、配置及运行依赖全部有已验证托管方案;生产入口不依赖原常驻主机,保留数据并通过迁移/回退验收 |
| 学习闭环 | 两类真机均完成一题、查看反馈、重练和复习;无图题可正常练习 |
| 账号 | Web 老用户成功关联且历史不丢;不同用户不能读取私人记录或绑定他人账号;公开分享仅暴露原允许字段 |
| 录音 | 首次允许/拒绝、再次授权、静音、切后台、来电、重录和上传失败均可恢复;原声归属正确 Attempt |
Expand All @@ -126,3 +155,5 @@
实施前核对微信官方[登录](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;尚未新增小程序代码、微信配置或发布行为。

2026-10-16补充确认:用户明确“功能跟网页完全一样是最低要求”,取消原计划自由说、头像、多图反馈延期的安排;并要求服务端优先云函数,目标无需自管服务器。上述均为正式验收要求,当前仍仅为计划、未实施。
2 changes: 1 addition & 1 deletion docs/requirements/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@

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