doodle-store/docs/v3.5/开发交接文档.md

Doodle v3.5 开发交接文档

2026-10-22 更新：用户确认云端 doodle_prod 已准备完成。已提供 服务端首次部署操作手册 和配套 Docker/Compose/环境模板；本轮仅准备配置和说明，未实际部署云端 API、执行生产迁移或切换小程序地址。当前流程为 Mac 构建 linux/amd64 镜像后通过 1Panel 上传导入，复用面板已有 PostgreSQL 与 OpenResty。后文“尚未准备部署配置”“数据库未部署”等属于历史记录，不覆盖本条更新。

更新时间：2026-10-19。本次整理当前进度和后续任务，未执行云端部署。验证结果来自此前开发记录，本次文档更新未重新运行全套测试。

2026-10-20 最新决策：云端 PostgreSQL 由 1Panel 安装管理。本地 doodle_dev 提供已整理的内容及七牛映射，CloudBase 提供最新用户、收藏、下载记录及题型真实计数；建议在本机独立迁移库整合后导入 doodle_prod。此前“仅导内容”和“直接全量复制本地库”的约定均已被替代；逐表来源和补导边界见 生产数据整合与导入方案。其余尚未更新的历史部署建议不覆盖本条决策。

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 去重，小程序保存图片成功后上报。
• 已实现管理员题型发布、批量修改/预演、状态调整、首页配置读取/重建及每日快照刷新开关。
• 管理员权限根据数据库当前角色校验，不自动授权开发者或第一个用户。
• 新后端首页刷新任务与旧云端任务分开，现有管理开关不会关闭旧云任务。

完整路由及权限对照见 小程序云接口迁移清单。

七牛与资源

• 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 执行迁移，不使用开发期重置命令初始化云端业务库。
• 按 2026-10-20 最新方案整合本地内容/七牛映射与 CloudBase 最新用户业务/统计；先在独立迁移库转换和对账，再迁入云端，账号和运行密钥单独配置。
• 配置数据库持久化、异机备份、恢复与迁移失败处理，并完成一次恢复验证。
• 保留上一可运行后端版本，明确应用回滚与数据库迁移的兼容边界。

C. 微信与体验版验收

• 配置相应 request / uploadFile 等合法域名，以及微信服务端接口 IP 白名单中的实际服务器出口 IP。
• 真机验证静默登录和到期恢复、查询、资料/头像、收藏、下载、管理员权限及内容下架。
• 验证预拉取仍用原模式/地址，L3 和后台刷新使用新后端，新管理操作不修改旧云数据或任务。
• 验证重复请求、异常恢复、资源上传/清理、服务重启和数据库恢复。

体验版验收通过后，再单独制定正式发布、历史用户迁移及新旧版本并行兼容方案。正式切换不是本轮部署默认动作，旧线上云服务继续保留。

6. 继续工作入口

• 小程序云接口迁移清单：最新接口与权限。
• 数据库设计文档：结合 Prisma schema 和迁移核对结构。
• 用户鉴权与登录设计、服务端登录接入说明。
• 题型查询接口说明、内容发布与可见性。
• 资源同步工具。
• 部署目录、开发与部署环境方案：部分历史内容待下一阶段更新。

后端常用验证，在 doodle-store 根目录执行：

pnpm typecheck
pnpm test
pnpm test:db
pnpm build

小程序针对本次迁移的回归，在 doodle-mini 根目录执行：

node --import tsx --test tests/auth-api.test.mjs tests/category-api.test.mjs tests/preview-assets.test.mjs