update at 2026-02-10 13:47:16

PLAN.md

@@ -1,5 +1,128 @@
 # 项目计划（2026-02-08）
 
+## 0. 手动切换路由方案（2026-02-10）
+
+### 0.1 目标
+
+- 支持在**不发布小程序新版本**的情况下，从服务器 A（`fonts.biboer.cn`）切换到服务器 B（`mac.biboer.cn`），或反向切换。
+- 切换仅通过手动修改远端配置文件触发，不引入自动健康探测。
+- 避免 A/B 来回抖动切换。
+
+### 0.2 已确认约束
+
+- 字体目录统一一份：`/fonts/`（A、B 各自托管同结构字体文件）。
+- 配置文件独立管理：
+  - Web：`/fonts.json`（可选 `/default.json`）
+  - 小程序：`/miniprogram/assets/fonts.json`、`/miniprogram/assets/default.json`
+- 小程序合法域名已包含 A/B 两个域名。
+- 不使用 `version` 字段。
+
+### 0.3 路由配置文件（route-config.json）
+
+- 建议路径：`/miniprogram/assets/route-config.json`（A、B 都提供）
+- 建议结构：
+
+```json
+{
+  "active": "A",
+  "cooldownMinutes": 10,
+  "servers": {
+    "A": { "baseUrl": "https://fonts.biboer.cn" },
+    "B": { "baseUrl": "https://mac.biboer.cn" }
+  }
+}
+```
+
+字段说明：
+- `active`: 当前希望启用的目标服务器（`A` 或 `B`）。
+- `cooldownMinutes`: 最短驻留时间。
+  - `10` 表示 10 分钟内不允许再次切换。
+  - `0` 表示可立即切换。
+
+### 0.4 双确认切换规则（核心）
+
+当客户端当前连接在 A，且读取到 A 配置 `active=B` 时：
+1. 客户端继续请求 B 的 `route-config.json`。
+2. 只有 B 也返回 `active=B`，才允许切换到 B。
+3. 若 A/B 不一致，则保持当前服务器不变。
+4. 若读取 B 失败（超时、非 200、JSON 非法），保持当前服务器不变，并记录失败日志。
+
+反向切换（B -> A）同理执行。
+
+### 0.5 A/B 交互与同步机制
+
+为满足“双确认”，A/B 需要配置一致性机制（交互）：
+- 维护端本地保留单一配置源文件（Git 仓库内）。
+- 通过 `deploy.sh` 一次性下发到 A、B。
+- 采用“临时文件 + 原子替换（mv）”发布，避免客户端读取半文件。
+
+推荐切换步骤（A -> B）：
+1. 同步配置到 B，确保 B 返回 `active=B`。
+2. 再同步配置到 A，改为 `active=B`。
+3. 客户端双确认通过后完成切换。
+
+### 0.6 客户端状态与防抖
+
+本地持久化字段：
+- `activeServerKey`（当前服务器）
+- `lastSwitchAt`（最后切换时间戳）
+- `routeConfigCache`（最近一次配置）
+- `lastRouteCheckAt`（最后一次读取 route-config 时间戳）
+
+切换判定：
+- 若 `cooldownMinutes > 0` 且 `now - lastSwitchAt < cooldownMinutes * 60 * 1000`，拒绝切换。
+- 若 `cooldownMinutes = 0`，通过双确认即可立即切换。
+
+### 0.6.1 route-config.json 读取时机
+
+1. 启动读取（P0）
+- 小程序冷启动时优先读取 `route-config.json`，再加载 `fonts.json/default.json` 与 API 请求。
+
+2. 回前台读取（P0）
+- `App.onShow` 触发时检查是否超过最小间隔（例如 60 秒），超过则读取。
+
+3. 失败兜底读取（P0）
+- 当 API 或配置拉取连续失败时，立即触发一次读取并执行双确认逻辑。
+- 若目标服务器配置读取失败，则仅记录日志并维持当前服务器，不执行切换。
+
+4. 手动刷新读取（P1，可选）
+- 提供调试入口（如“刷新配置”按钮）用于即时验证切换。
+
+节流规则：
+- 若 `now - lastRouteCheckAt < 60s`，跳过非必要读取，避免频繁请求。
+
+### 0.7 实施任务拆分
+
+1. 小程序端
+- 新增 `route-manager`（加载路由配置、执行双确认、应用 cooldown、持久化状态）。
+- `render-api`、`font-loader` 改为读取 `route-manager` 当前 `baseUrl`。
+- 启动时先加载路由，再加载 `fonts.json/default.json`。
+
+2. 服务端与部署
+- A/B 都部署 `route-config.json`。
+- 使用 `deploy.sh` 统一发布：一次性下发到两台服务器并做原子替换。
+- `deploy.sh` 负责同步 `route-config.json`、字体配置文件，并执行可选巡检。
+- 增加巡检命令：检查 A/B 当前 `active` 是否一致。
+
+3. 文档
+- 更新 `miniprogram/README.md`：增加无发版切换流程。
+- 增加运维操作手册：A->B、B->A、回滚流程。
+
+### 0.8 验收标准
+
+- 仅修改远端 `route-config.json`，小程序无需发版即可切换 A/B。
+- `cooldownMinutes=10` 时，10 分钟内不会再次切换。
+- `cooldownMinutes=0` 时，双确认满足后可立即切换。
+- A/B 配置不一致时不发生切换。
+- 目标服务器配置读取失败（超时/非 200/JSON 非法）时不发生切换。
+- 切换后 API、字体清单、默认配置均来自目标服务器。
+
+### 0.9 风险与回滚
+
+- 风险：A/B 配置不同步导致无法切换（预期保护行为）。
+- 风险：CDN 缓存导致短时间读取旧配置（通过短缓存 + 原子发布缓解）。
+- 回滚：将 A/B 两端 `active` 同步改回原服务器，并设置 `cooldownMinutes=0` 可快速恢复。
+
 ## 1. 当前状态
 
 ### 1.1 已完成（保留能力）
@@ -1113,4 +1236,3 @@ wx.downloadFile({ url: fontPath })
 **计划更新日期**：2026-02-08  
 **下次更新**：M1 完成后，根据实际情况调整后续里程碑细节  
 **部署方案**：Cloudflare CDN + 海外服务器（fonts.biboer.cn，免备案）
-