feat: 增加环境切换

README.md

@@ -20,7 +20,7 @@ keyPrefix: 'doodle-assets/',
 
 ### 新后端静默登录与鉴权
 
-启动及回到前台时通过 `utils/auth.ts` 非阻塞预热：`wx.login` 取一次性 code，调用 `POST /api/v1/auth/wechat/login`。首次使用 `start`，已有会话续期和 401 恢复使用 `resume`；明确无效 code 最多重新取一次。JWT 与用户摘要按 AppID、接口地址分开保存，凭证到期前 60 秒按需续登。不缓存角色或微信 OpenID，不记录凭证、code 或完整登录响应。
+启动及回到前台时通过 `utils/auth.ts` 非阻塞预热：`wx.login` 取一次性 code，调用 `POST /api/v1/auth/wechat/login`。首次使用 `start`，已有会话续期和 401 恢复使用 `resume`；明确无效 code 最多重新取一次。JWT 与用户摘要按 AppID、包类型、环境名称和接口地址分开保存，凭证到期前 60 秒按需续登。不缓存角色或微信 OpenID，不记录凭证、code 或完整登录响应。
 
 统一请求层 `services/api-request.ts` 默认要求登录并携带 Bearer；公开分类与题型接口显式指定 `auth: 'none'`，不携带凭证、不触发登录。受保护请求遇到可恢复 401 时最多重登并重发一次，并发请求合并登录，迟到的旧 401 不会清掉新凭证。恢复后身份变化时不补发原业务写入。403、限流、服务错误或网络失败不触发自动重登链。
 
@@ -44,10 +44,28 @@ await apiRequest('/me');
 
 ### 业务接口切换
 
-本地开发中的小程序运行代码已不再调用 `wx.cloud`；首页继续使用 `wx.getBackgroundFetchData` 获取预拉取首屏，在后台使用新 `/page-config` 刷新，管理改动也会刷新首页。旧云端的预拉取地址、生成与发布链路、定时任务保持原样，新管理开关仅控制新后端的快照刷新任务。
+本地开发中的小程序运行代码已不再调用 `wx.cloud`；体验版与正式版首页继续使用 `wx.getBackgroundFetchData` 获取预拉取首屏，在后台使用新 `/page-config` 刷新。开发版跳过旧线上预拉取，使用所选接口环境自己的内容缓存及新后端；管理改动也会刷新首页。旧云端的预拉取地址、生成与发布链路、定时任务保持原样，新管理开关仅控制新后端的快照刷新任务。
 
 当前已发布的线上版仍使用旧云开发接口。`cloudfunctions/` 中全部旧云函数源码、云开发配置及线上服务均须保留；本地开发版切换接口不代表线上旧版本已停止调用。未经另行明确安排，不删除、停用旧云函数，不改变其接口契约，不清理旧云数据库或云存储，也不迁移现有预拉取模式。
 
 用户接口由 `services/member-api.ts` 与 `utils/auth.ts` 管理，管理页由 `services/admin-api.ts` 适配具名 REST 路由。图片通过本站 multipart 上传接口进入七牛，不暴露 AK/SK；同一次上传恢复沿用 UUID uploadId。管理页只能由数据库中当前角色为 admin 的账户操作，开发版不会绕过权限。
 
 服务端路由、权限与数据迁移说明见 doodle-store 的 `docs/v3.5/小程序云接口迁移清单.md`。旧云端用户、收藏与下载历史本次未自动导入，正式切换前需要另行核对迁移。
+
+### 开发版接口环境切换
+
+入口：个人中心 → Debug 工具 → 接口环境。`develop` 可切换 `local / staging / production`，选择保存在本机，切换后自动重建页面返回首页，无需重新编译。开发版导航栏显示当前环境。`trial / release` 固定使用 `production`，忽略本机调试选择，配置层与切换入口均有校验。
+
+地址在 `miniprogram/config/api.ts` 集中配置：
+
+- `localBaseUrl`：本地开发接口。
+- `stagingBaseUrl`：未来测试接口。
+- `productionBaseUrl`：未来正式接口。
+
+目前按要求，三个地址都暂填 `http://127.0.0.1:8800/api/v1`，客户端缓存和会话按环境隔离，但实际请求仍访问同一个本地后端和数据库。真机的 `127.0.0.1` 指向手机；调试时 local 需改为电脑局域网地址。部署时把 staging/production 占位地址改为对应 HTTPS 地址，不会因地址缺失自动回退 local。
+
+切换会清空共享用户和内容状态，读取目标环境凭证，并强制从目标接口加载首页；原环境的缓存与会话保留。所有 API 响应按环境版本检查，即使快速 A→B→A，旧请求也不能覆盖当前数据。写请求（含登录等待及上传重试）未完成时禁止切换。目标接口不可用时提示连接失败并保留所选环境，不展示上一环境的内容。打印偏好继续共用。
+
+本轮仅调整开发版数据来源；体验/正式包原预拉取模式、地址及全部旧云端服务保持原样。
+
+环境切换回归：`node --import tsx --test tests/environment-switch.test.mjs`。