R524809
158 lines
12 KiB
Markdown
158 lines
12 KiB
Markdown
# Doodle v3.5 开发交接文档
|
||
|
||
更新时间：2026-10-19。本次整理当前进度和后续任务，未执行云端部署。验证结果来自此前开发记录，本次文档更新未重新运行全套测试。
|
||
|
||
## 1. 当前阶段与保留约束
|
||
|
||
本地数据库、主要业务后端、小程序开发代码的接口迁移及七牛接入已完成。下一阶段先准备部署工程，再部署云端测试 API 和独立测试数据库，供小程序体验版联调。
|
||
|
||
必须区分：本地开发中的小程序已改用新后端；当前已发布的线上版仍使用旧云开发。用户明确要求：
|
||
|
||
- 保留 `wx.getBackgroundFetchData`、现有预拉取模式和地址。
|
||
- 保留旧云端预拉取数据生成、发布和定时刷新链路。
|
||
- 保留全部旧云函数源码、云开发配置和线上服务，继续服务当前线上版。
|
||
- 未另行明确安排前，不停用旧任务、不改变旧接口契约、不删除旧云数据，也不迁移预拉取模式。
|
||
- 头像与其他资源使用同一个七牛公开空间。
|
||
- 七牛 AK/SK、微信 AppSecret、JWT 密钥及数据库密码只保存在服务端配置，不提交、不写入文档、不下发小程序。
|
||
|
||
历史文档中的“停止旧任务”“私有头像”“七牛尚未接入”等过时表述，不应直接作为当前操作依据。旧线上链路持续保留的要求优先。
|
||
|
||
## 2. 工作区与本地环境
|
||
|
||
| 项目 | 路径或配置 |
|
||
| ------------------- | -------------------------------------------------------- |
|
||
| 后端仓库 | `/Users/joey-xd/sites/doodle/doodle-store` |
|
||
| 小程序仓库 | `/Users/joey-xd/sites/doodle/doodle-mini` |
|
||
| 云存储备份 | `/Users/joey-xd/sites/doodle/doodle-assets/cloud_backup` |
|
||
| 后端应用 | `apps/server`，NestJS + Prisma + PostgreSQL |
|
||
| 公共契约 / 资源工具 | `packages/contracts` / `packages/asset-sync` |
|
||
| 后续管理后台 / Web | `apps/admin` / `apps/web`，当前仅占位 |
|
||
| 运行时 | Node.js 24.20.0、pnpm 11.24.0 |
|
||
| 本地数据库 | Docker PostgreSQL 18.6，`127.0.0.1:5434`，`doodle_dev` |
|
||
| 本地 API | `http://127.0.0.1:8800/api/v1` |
|
||
| Swagger | `http://127.0.0.1:8800/api-docs` |
|
||
|
||
配置入口分别为根 `.env`、`apps/server/.env`、`packages/asset-sync/.env`，真实文件均须保持 Git 忽略。启动前先检查进程状态，避免重复启动。
|
||
|
||
两个仓库有大量尚未提交的开发改动。继续前检查 Git 状态，不覆盖或回滚已有修改；服务端还有用户安装的技能文件，不为通过检查而擅自修改或删除。
|
||
|
||
## 3. 已完成内容
|
||
|
||
### 数据库与内容
|
||
|
||
- 数据库设计、SQL、Prisma 已落地；本地已应用基线、分类发布状态、`20261019000000_member_assets` 三个迁移。
|
||
- 本地已导入 6 条分类和 51 条题型，保留源 ID、原始计数和展示种子。
|
||
- 已实现分类公开查询、管理员新增/修改/删除，以及 worksheets 列表、详情、分类、年级、年龄、Tag、最新/热门查询。
|
||
- 热门按下载量加展示种子计算；年龄段使用完整覆盖匹配，例如 3～8 岁题型可以命中 5～6 岁。参数及兼容行为以当前 DTO 和 Swagger 为准。
|
||
- 分类与题型发布状态、分类祖先可见性约束已实现；未就绪的预览图返回空值。
|
||
|
||
### 登录、个人业务与管理
|
||
|
||
- `wx.login` 获取 code，新后端向微信兑换并签发本站 JWT；AppSecret 仅服务端持有。
|
||
- 已实现启动/回前台静默登录、到期前续登、并发合并、业务 401 一次恢复重试，以及账户切换、删除和禁用时的处理。
|
||
- 已实现资料修改、头像上传及绑定、清除资料、注销账户、本人统计、收藏操作和分页、下载记录新增和分页。
|
||
- 收藏和下载计数包含事务及并发幂等；下载通过 `exportId` 去重，小程序保存图片成功后上报。
|
||
- 已实现管理员题型发布、批量修改/预演、状态调整、首页配置读取/重建及每日快照刷新开关。
|
||
- 管理员权限根据数据库当前角色校验，不自动授权开发者或第一个用户。
|
||
- 新后端首页刷新任务与旧云端任务分开，现有管理开关不会关闭旧云任务。
|
||
|
||
完整路由及权限对照见 [小程序云接口迁移清单](./小程序云接口迁移清单.md)。
|
||
|
||
### 七牛与资源
|
||
|
||
- `packages/asset-sync` 支持配置备份目录、AK/SK、预演、上传、同内容跳过、冲突保护、重试及报告。
|
||
- 用户已上传资源；此前核验的成功同步报告包含 62 个文件。51 个题型预览资产已回填本地库为 ready，原资产 ID 与业务外键保持不变。
|
||
- 首页、分类等预览和字体已改用七牛；已知旧预拉取/缓存预览地址会转换为七牛地址。
|
||
- 业务表保存资源 ID；`assets` 保存完整对象 key、bucket、摘要和状态等；响应 URL 根据配置生成。
|
||
- 服务端头像及管理员预览上传已实现，限制 PNG/JPEG、2 MiB，校验图片尺寸、幂等标识和远端文件。
|
||
- 头像替换、清除和账户注销会排队清理资源，包含失败重试与慢上传交错处理。
|
||
|
||
公开配置为 `QINIU_PUBLIC_DOMAIN=https://cdn.joeyone.cn`、`QINIU_KEY_PREFIX=doodle-assets/`、`QINIU_BUCKET=doodle-cn`。示例字体为 `https://cdn.joeyone.cn/doodle-assets/assets/fonts/ToneOZ-Pinyin-Regular.ttf`。
|
||
|
||
现有资产映射工具仅允许本机 `doodle_dev`，云端内容初始化需另行准备流程，不能直接更改目标库运行本地工具。
|
||
|
||
### 小程序与旧线上链路
|
||
|
||
- 最近静态扫描覆盖 707 个代码及配置文件，未发现运行代码中的直接 `wx.cloud` 调用。用户业务、内容查询和管理页均已切换新后端。
|
||
- 首页顺序为 L1 微信预拉取 → L2 本地缓存 → L3 新 `/page-config`；L1/L2 命中后后台请求新后端刷新。
|
||
- 旧预拉取与新后端数据源尚未统一，首屏可能短暂展示旧内容，随后刷新。保留现状，后续调整需单独安排。
|
||
- `wx.uploadFile` 用于新后端 multipart 上传，是普通网络 API。
|
||
- 配置入口为 `doodle-mini/miniprogram/config/api.ts`。develop 可切 local/online；trial/release 当前共用未填写的 `onlineBaseUrl`，不会回退本地。
|
||
- 17 个旧云函数全部保留，仍服务当前线上版；实际云端部署和触发器状态未通过控制台核验，本次不调整。
|
||
|
||
## 4. 验证记录与未解决事项
|
||
|
||
此前验证结果：
|
||
|
||
- 后端类型检查、相关业务文件 ESLint/格式检查及两个仓库的 `git diff --check` 通过。
|
||
- 后端常规测试通过；隔离数据库回归覆盖 6 组文件、49 项测试，结束后清理测试库。
|
||
- 小程序本次迁移相关测试 28 项通过，1 项本地服务集成测试跳过。
|
||
- 本地 HTTP 已验证 health、page-config、年龄推荐和 Swagger 参数/路由。health 成功仅证明 HTTP 进程可响应。
|
||
- 上传测试使用替身，未由测试向真实七牛上传或删除文件；真实微信 code 和真机上传仍需验收。
|
||
|
||
待处理事项及限制：
|
||
|
||
- 小程序完整 TypeScript 检查仍有 115 个既有错误，既有 ESLint 配置也有兼容问题，不能声称全项目检查通过。
|
||
- 根 `pnpm check` 曾被用户新安装的第三方技能 Markdown 格式问题阻塞；业务代码已单独检查，不擅自更改这些技能文件。
|
||
- 登录曾返回 `503 / AUTH_UPSTREAM_UNAVAILABLE`，诊断得到微信错误 `40164`，为服务端出口 IP 白名单拒绝。云部署需配置实际服务器出口 IP；尚无后续真实 code 成功验收记录。
|
||
- 旧云端用户、收藏及下载历史未迁移，新旧账户关联和正式切换流程待制定。
|
||
- 云端 API 域名未确定；后端和数据库尚未部署到云服务器。
|
||
- 上传限流当前为单实例每人每小时 30 个新标识，未实现多实例共享配额。
|
||
- 小程序 4 个 `worksheet:patch:*` 命令引用不存在的旧脚本；部分文案、类型和文档仍有 Cloud 命名。可单独清理，不涉及删除旧云函数。
|
||
|
||
## 5. 下一步任务：云端体验版联调
|
||
|
||
下列任务尚未执行。先准备可审查的部署配置与说明，再结合实际服务器条件部署；本阶段不切换当前线上版。
|
||
|
||
### A. 部署工程与环境配置
|
||
|
||
- [ ] 确认服务器地址、系统、已有服务、端口、资源和部署方式；历史记录为 2 核 4 GB，执行前重新核实。
|
||
- [ ] 确定测试 API HTTPS 域名、DNS 和证书。
|
||
- [ ] 编写构建/发布、反向代理、进程管理、日志及健康检查配置；内部 API 使用 8800，对外使用 HTTPS，云端运行构建产物，不长期运行 `pnpm dev`。
|
||
- [ ] 数据库仅内部访问；配置明确的代理信任范围、服务自启动及重启策略。
|
||
- [ ] 小程序环境拆为 local / staging / production，体验版用 staging，未来正式版用 production，避免共用地址误连库。
|
||
- [ ] 使用独立 `doodle_staging` 库和角色，不连接本地开发库或未来生产库；可复用 PostgreSQL 实例，无须常驻两套完整系统。
|
||
- [ ] 测试与正式环境分开配置 JWT 密钥、数据库凭据、Swagger 访问策略；微信配置与实际小程序一致。
|
||
- [ ] 明确测试上传和清理范围，避免删除现有资源；对象前缀不能替代 AK/SK 权限隔离。
|
||
- [ ] 更新过时的部署环境方案，明确旧云函数和预拉取链路持续保留。
|
||
|
||
### B. 云端数据与运维
|
||
|
||
- [ ] 使用 `prisma migrate deploy` 执行迁移，不使用开发期重置命令初始化云端业务库。
|
||
- [ ] 准备受控内容初始化流程，迁入分类、题型、关联资产及必要配置；核对 ID、发布状态、计数、分类关联和预览，不整库复制测试用户及临时记录。
|
||
- [ ] 配置数据库持久化、异机备份、恢复与迁移失败处理，并完成一次恢复验证。
|
||
- [ ] 保留上一可运行后端版本，明确应用回滚与数据库迁移的兼容边界。
|
||
|
||
### C. 微信与体验版验收
|
||
|
||
- [ ] 配置相应 request / uploadFile 等合法域名，以及微信服务端接口 IP 白名单中的实际服务器出口 IP。
|
||
- [ ] 真机验证静默登录和到期恢复、查询、资料/头像、收藏、下载、管理员权限及内容下架。
|
||
- [ ] 验证预拉取仍用原模式/地址，L3 和后台刷新使用新后端，新管理操作不修改旧云数据或任务。
|
||
- [ ] 验证重复请求、异常恢复、资源上传/清理、服务重启和数据库恢复。
|
||
|
||
体验版验收通过后，再单独制定正式发布、历史用户迁移及新旧版本并行兼容方案。正式切换不是本轮部署默认动作，旧线上云服务继续保留。
|
||
|
||
## 6. 继续工作入口
|
||
|
||
- [小程序云接口迁移清单](./小程序云接口迁移清单.md)：最新接口与权限。
|
||
- [数据库设计文档](./数据库设计文档.md)：结合 Prisma schema 和迁移核对结构。
|
||
- [用户鉴权与登录设计](./用户鉴权与登录设计.md)、[服务端登录接入说明](./服务端登录接入说明.md)。
|
||
- [题型查询接口说明](./题型查询接口说明.md)、[内容发布与可见性](./内容发布与可见性.md)。
|
||
- [资源同步工具](../../packages/asset-sync/README.md)。
|
||
- [部署目录](../../deploy/README.md)、[开发与部署环境方案](./开发与部署环境方案.md)：部分历史内容待下一阶段更新。
|
||
|
||
后端常用验证，在 `doodle-store` 根目录执行：
|
||
|
||
```bash
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm test:db
|
||
pnpm build
|
||
```
|
||
|
||
小程序针对本次迁移的回归，在 `doodle-mini` 根目录执行：
|
||
|
||
```bash
|
||
node --import tsx --test tests/auth-api.test.mjs tests/category-api.test.mjs tests/preview-assets.test.mjs
|
||
```
|