feat: 完成现有小程序接口的全部迁移至新后端

2026-10-19 13:17:51 +08:00
parent 8827110f2f
commit d30cf25890
148 changed files with 13287 additions and 34 deletions
@@ -186,7 +186,7 @@ flowchart LR

 公开接口用 `@Public()` 明确声明，且不返回本人收藏状态；需要个人状态时单独请求 `/me/...`。现有 Public 装饰器会完全跳过守卫，不将它当作“有 token 就自动解析身份”的可选鉴权模式。

-资产接口先验证 purpose、大小、格式、owner 和状态；头像只允许绑定本人拥有、用途为 avatar 且 ready 的私有资产。客户端传来的 assetId、worksheetId、resourceId 都必须做业务校验，不能仅因用户已登录便接受。
+资产接口先验证 purpose、大小、格式、owner 和状态；头像按用户确认使用公开空间，只允许绑定本人拥有、用途为 avatar 且 ready 的资产。客户端传来的 assetId、worksheetId、resourceId 都必须做业务校验，不能仅因用户已登录便接受。

 ### 5.3 管理权限与版本撤销

@@ -259,7 +259,7 @@ flowchart LR
 | `DELETE /me/profile` | 清昵称及头像引用，保留账户、凭证、收藏、历史；前端更新摘要，不清登录态            |
 | `DELETE /me`         | 当前凭证 + 新微信 code + 用户确认，验证同一身份后按数据库规则完整注销             |

-头像流程：`chooseAvatar` 得到临时本地文件 → 带 Bearer 上传 `POST /assets` → 得到本人 avatar assetId → PATCH 绑定。服务端校验归属，不能接受任意头像 URL、文件路径或他人 assetId。替换/清除后按既有文件清理机制处理旧私有对象，失败重试，不在数据库事务里请求对象存储。
+头像流程：`chooseAvatar` 得到临时本地文件 → 带 Bearer 上传 `POST /me/avatar-upload` → 得到本人 avatar assetId → `PUT /me/profile` 绑定。服务端校验归属，不能接受任意头像 URL、文件路径或他人 assetId。替换/清除后按既有文件清理机制处理旧头像对象，失败重试，不在数据库事务里请求对象存储。

 昵称按数据库上限 100 个 Unicode 字符校验，首尾空白规范化，不把它作为唯一账号名。个人中心可分别保存昵称和头像，不强迫二者齐全；微信填写组件提供的临时路径不是永久头像地址。[微信头像昵称填写](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/userProfile.html)。

@@ -390,7 +390,7 @@ Cookie 写请求必须有 CSRF 防护，建议 Origin 校验 + 与会话绑定
 | 清缓存/注销与登录、列表请求并发           | 旧响应不复活状态；注销后后台 resume 不重新建号                                          |
 | 重新登录返回不同 userId                   | 原写请求不重发，原下载队列不代报                                                        |
 | 保存成功后上报超时、重试                  | 原 exportId 重用，不重复计数、不重复扣本地配额                                          |
-| 清资料                                    | 收藏/历史及有效凭证保留，头像私有对象进入清理流程                                       |
+| 清资料                                    | 收藏/历史及有效凭证保留，头像对象进入清理流程                                           |
 | 注销成功或响应丢失                        | 事务完整，旧 token 失效；未知结果可确认，不自动重放或重新注册                           |
 | 任意用户改他人头像、读他人历史            | 拒绝；管理员默认也不能读取全量私有数据                                                  |
 | 小程序本地改角色或显示管理按钮            | 管理 API 仍拒绝，管理写事务重新核对操作者                                               |
@@ -408,3 +408,17 @@ Cookie 写请求必须有 CSRF 防护，建议 Origin 校验 + 与会话绑定
 - [微信网站应用登录](https://developers.weixin.qq.com/doc/oplatform/Website_App/WeChat_Login/Wechat_Login.html)、[OWASP 会话管理](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)：未来网站登录和浏览器会话的参考，不代表本站已接入。

 本次建议默认按“小程序 24 小时 JWT、暂不增加表、Web 优先现有小程序扫码确认”推进。Web 的移动端覆盖、网站应用准入及实际域名拓扑留到 Web 启动时确定；若改选独立手机号/邮箱登录，需要补充验证、凭证、找回和解绑方案，不能直接复用昵称或客户端 UUID。
+
+## 小程序首期接入进度（2026-10-19）
+
+小程序已接入 `wx.login → POST /auth/wechat/login`，启动/回前台非阻塞预热；`utils/auth.ts` 提供 `getUser`、`ensureAuthenticated`、`getCachedUser`、`refreshUser` 和内部清理入口。`refreshUser` 调用受保护的 GET /me。当前阶段没有将资料更新伪装成已迁移：资料编辑、头像上传、收藏、下载记录及账户设置仍由独立的 `utils/legacy-auth.ts` 兼容旧云业务，后续逐项切换。
+
+新凭证通过 AppID 与完整 API baseUrl 隔离，保存版本化的账户历史、凭证、本机预计到期时间及白名单用户摘要。公开分类/题型请求显式不鉴权；其余请求默认获取并携带本站 JWT。首次登录、提前 60 秒续期和 401 恢复共用 Promise；一次业务请求最多恢复与重发一次，迟到的旧 401 复用较新凭证，恢复后账户改变则停止原请求。无效微信 code 最多重新获取一次，网络错误不会复用 code 或自动循环。
+
+账号不存在/禁用会清理凭证并暂停自动恢复，账户历史标记不随会话清理丢失；个人中心提供用户主动重新开始的入口，服务端仍负责拒绝禁用账户。新后端摘要使用 `globalData.user`，旧云端使用 `globalData.legacyUser`，不混用两种用户 ID 或用旧缓存冒充 JWT。
+
+前端专项及分类/预览回归共 23 项通过（真实 8800 联调用例未启用）；真实微信 code 兑换需在开发者工具或真机验证。正式部署前仍需配置线上 API 域名并先迁移旧用户及关联数据，避免在未迁移的生产库创建另一套业务身份。
+
+## 其余接口切换进度（2026-10-19）
+
+已完成微信预拉取之外的云接口替换，旧 `legacy-auth.ts` 兼容层已移除。用户资料、收藏、下载、头像、管理发布/批次与首页动态接口均使用本站用户身份，详见[小程序云接口迁移清单](小程序云接口迁移清单.md)。前文“首期接入进度”是分阶段记录，当前实现以该清单为准；历史云端用户/收藏/下载数据尚未自动搬迁。