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

2026-10-19 13:17:51 +08:00
parent 8827110f2f
commit d30cf25890
148 changed files with 13287 additions and 34 deletions
@@ -74,3 +74,40 @@ docs/             工程初始化与接入边界说明
 ## 云存储备份同步七牛

 独立脚本项目位于 [packages/asset-sync](packages/asset-sync/README.md)，配置入口为该目录的 `.env`，已填写本地 cloud_backup 源目录。`pnpm assets:sync` 默认只预演；填写七牛 AK/SK 与 bucket 后，使用 `pnpm assets:sync --apply --only assets/previews` 同步题型预览。支持保留相对路径、同内容跳过、冲突保护、有限重试和报告；头像与其他资源共用 QINIU_BUCKET 公开空间。该工具不修改业务数据库或自动替换旧 cloud 引用。
+
+### 服务端资源地址配置
+
+`apps/server/.env` 与 asset-sync 使用同一组公开配置；服务端无需配置七牛 AK/SK：
+
+```dotenv
+QINIU_PUBLIC_DOMAIN=https://cdn.joeyone.cn
+QINIU_KEY_PREFIX=doodle-assets/
+QINIU_BUCKET=doodle-cn
+```
+
+地址规则为「域名 / 对象 key」。字体等固定资源由 `publicResourceUrl(config, 'assets/fonts/ToneOZ-Pinyin-Regular.ttf')` 补上前缀，得到 `https://cdn.joeyone.cn/doodle-assets/assets/fonts/ToneOZ-Pinyin-Regular.ttf`。支持空前缀；域名仅接受 HTTPS origin，不包含目录。修改配置后重启 server。
+
+数据库 `assets.object_key` 存完整 key，例如 `doodle-assets/assets/previews/math/example.jpg`，返回预览时直接拼域名，不再次添加前缀。`QINIU_BUCKET` 是对象所属空间，不拼进 URL，也不会自动修改资产记录。图片上传成功后仍需根据同步报告回填资产的 key、bucket、摘要等字段并标记 ready；pending 资产继续返回空预览，配置域名不会自动宣布迁移完成。
+
+资源上传后，可将成功同步报告映射回本地 `assets`，保留原资源 ID 与业务表外键：
+
+```bash
+# 预演：重新核对本地文件与七牛对象，仅允许本机 doodle_dev
+pnpm assets:map --report /绝对路径/成功同步报告.json
+# 核对通过后，整批事务写入并记录迁移审计
+pnpm assets:map --report /绝对路径/成功同步报告.json --apply
+```
+
+当前工具处理已有 cloud 来源的题型预览：根据原文件相对路径匹配，回填 bucket、完整 objectKey、MIME、大小和 SHA-256，设置 ready。重复执行同一映射会跳过，已就绪但映射不同的资产会拒绝覆盖；有缺失或核对失败则整批不写入。不创建用户头像记录、不猜测头像归属。
+
+业务表（例如 worksheets.preview_asset_id、users.avatar_asset_id）仅保存资源 ID；assets 保存文件定位和元数据，不保存七牛完整访问 URL。固定字体未作为业务记录入库，小程序通过 `miniprogram/config/assets.ts` 统一配置域名和前缀；接口提供的图片地址直接使用，不在小程序重复拼接。
+
+### 微信登录上游失败排查
+
+`503 / AUTH_UPSTREAM_UNAVAILABLE` 表示服务端兑换微信 code 未成功。查看同一 requestId 的 `wechat_exchange_failed` 日志：只记录失败阶段、HTTP 状态和微信数值错误码，不输出 AppSecret、code、完整请求 URL 或微信 errmsg。
+
+若 `wechat_errcode=40164`，且有 `egress_ip`，表示微信拒绝当前服务器公网出口 IP。登录对应 AppID 的微信公众平台，在服务端接口调用的 IP 白名单中添加该出口 IP（与代码上传白名单分别核对），保存后在小程序重新触发登录。换网络或代理出口后需重新核对 IP；上线时使用实际服务器的固定出口 IP。仅修改本站后端 `.env` 无法解除微信侧白名单限制。
+
+### 小程序业务接口迁移
+
+除微信预拉取外，用户资料、头像、收藏、下载记录、年龄推荐、动态首页兜底和各管理页已迁至本站 API；详见 [小程序云接口迁移清单](docs/v3.5/小程序云接口迁移清单.md)。上传凭据仅由服务端持有，本地已沿用 asset-sync 的七牛配置。`20261019000000_member_assets` 已在本地应用；云端历史用户及关联记录仍需单独导入。管理功能要求数据库当前角色为 admin，不自动授权开发者账户。