feat: 部署准备

README.md

@@ -1,5 +1,7 @@
 # Doodle Store
 
+当前进度、旧线上服务保留约束、验证结果及下一步任务见 [开发交接文档](docs/v3.5/开发交接文档.md)（2026-10-19）。
+
 独立于 `doodle-mini` 的 pnpm Monorepo，用于维护统一业务后端、后续管理后台和用户 Web 网站。小程序源码与 CloudBase 兼容函数仍在 `doodle-mini`，两个项目通过 HTTPS API 协作。
 
 ## 当前范围

deploy/.env.example

@@ -0,0 +1,5 @@
+# 仅在云服务器保存真实 .env，权限 600；三个密码分别生成，不提交仓库。
+# 建议使用 secrets.token_hex(32) 或 openssl rand -hex 32，便于后续组成连接串。
+POSTGRES_ADMIN_PASSWORD=
+DOODLE_MIGRATOR_PASSWORD=
+DOODLE_APP_PASSWORD=

deploy/README.md

@@ -1,9 +1,127 @@
-# 部署预留目录
+# Doodle 云端部署准备
 
-本次未向云服务器部署服务或启动生产数据库，也未修改云服务器。
+更新时间：2026-10-19。本文件记录部署方案与待确认条件。已在 1Panel 申请根域及泛域名证书；尚未创建 Doodle 云端应用、应用域名 DNS 记录或镜像仓库，也未改动旧线上云开发链路。
 
-本地数据库配置位于 [infra](../infra/README.md)，与云服务器部署分开维护。云端首期只常驻 PostgreSQL 生产库，真实联调按需创建同实例独立测试库；图片等资源直接使用七牛。详见 [v3.5 开发与部署环境方案](../docs/v3.5/开发与部署环境方案.md)。
+## 已确认条件
 
-后续加入 Docker Compose、Nginx、数据库备份与恢复配置，按应用独立部署；数据库不开放公网端口，真实环境变量不提交仓库。
+- 云平台：腾讯云；主机名 `VM-16-14-ubuntu`。
+- 系统：Ubuntu 24.04，内核 `6.8.0-71-generic`，架构 x86_64；应用镜像目标为 `linux/amd64`。
+- 1Panel：2.3.2。
+- 用户提供的地址 `10.0.16.14` 是内网地址；公网域名还需确认实际公网 IP。
+- CPU、内存、磁盘余量、现有网站、OpenResty 网络模式及端口占用尚未核查。历史文档中的“2 核 4 GB”不能视为本轮已确认。
 
-在增加数据库、admin、SSR Web 或渲染进程前检查现有 2 核 4 GB 服务器资源，不在生产长期运行整套开发模式。
+## 环境边界
+
+当前采用本地开发 + 单套云端业务环境；未来确有需要时再启用独立 staging，不预先常驻第二套云端系统。
+
+| 小程序包 | 接口选择                                                   |
+| -------- | ---------------------------------------------------------- |
+| develop  | 默认 local，可在 Debug 页切换 local / staging / production |
+| trial    | 固定 production，与正式版使用同一套后端和数据库            |
+| release  | 固定 production                                            |
+
+小程序配置位于 `doodle-mini/miniprogram/config/api.ts`。按用户要求，当前三个环境地址暂时都填写本地接口，客户端会话/缓存隔离不代表服务端数据已隔离；云端验收就绪后再单独替换相应地址。
+
+现有已发布小程序继续使用原云开发。保留全部旧云函数、预拉取模式、地址、生成/发布与定时链路。开发版跳过旧线上预拉取，体验/正式包保留原有预拉取行为；本次不关闭旧服务。
+
+## 建议部署结构
+
+采用“1Panel 管理入口，项目维护应用编排”的组合方式：
+
+```text
+小程序 / Web
+    → HTTPS 域名
+    → 现有 1Panel OpenResty（统一管理 80/443 和证书）
+    → Doodle API 容器（容器内 8800）
+    → 独立 PostgreSQL 容器（持久化数据卷，不发布公网端口）
+
+预览图、字体与头像 → 现有七牛资源域名
+```
+
+API、PostgreSQL 的 Docker Compose、镜像版本、环境变量示例和备份流程保存在项目仓库；1Panel 可用于观察容器状态和管理入口，不要求将应用制作成 1Panel 商店应用，也不额外部署一套 Node.js 运行环境。
+
+1Panel 与项目脚本不能同时维护同一份容器编排。既有服务不为本项目被替换或重装，也不另启 Nginx/Caddy 抢占 80/443。
+
+反向代理的上游地址要依据实际网络模式确定：若 OpenResty 使用 host 网络，可访问宿主机回环地址；若使用 bridge 网络，容器内的 `127.0.0.1` 是 OpenResty 自身，应使用经过核查的共享 Docker 网络连接 API 服务。数据库只与 API 在内部网络通信。应用信任代理的地址范围也据此配置，不直接信任任意来源的转发头。
+
+## 域名选择
+
+以下为建议名称，尚未创建 DNS：
+
+| 用途     | 建议域名                |
+| -------- | ----------------------- |
+| 未来 Web | `doodle.joeyone.cn`     |
+| API      | `doodle-api.joeyone.cn` |
+
+`api.doodle.joeyone.cn` 同样可以使用，名称层级不会使接口功能或 HTTPS 安全性更强。当前推荐 `doodle-api.joeyone.cn`，因为它与 Web 域名处于同一层级，也可被 `*.joeyone.cn` 覆盖（仅在已有这种证书时适用）；`api.doodle.joeyone.cn` 不受该通配符覆盖，需要精确域名证书或 `*.doodle.joeyone.cn`。
+
+用户已选择统一管理根域及一级子域名证书；2026-10-19 已通过 1Panel 签发 `joeyone.cn` + `*.joeyone.cn`，可以覆盖表中的 Web/API 域名。将来换独立品牌域名时，可以在过渡期间让新旧域名同时路由到同一 API，不立即强制重定向旧小程序的 POST/上传请求；待旧客户端退出后再安排旧域名退役。
+
+## 证书与自动续签
+
+用户已选择由 1Panel 统一管理 `joeyone.cn` + `*.joeyone.cn` 的泛域名证书，复用现有 ACME 与腾讯云 DNS 账户；不接入 Atlas 的 acme.sh/systemd/七牛部署任务。
+
+2026-10-19 面板现场核验结果：
+
+| 项目             | 结果                            |
+| ---------------- | ------------------------------- |
+| 证书 ID          | `11`                            |
+| 主域名           | `joeyone.cn`                    |
+| 其他域名         | `*.joeyone.cn`                  |
+| 颁发机构         | Let's Encrypt                   |
+| 验证方式         | DNS 账户自动验证，腾讯云DNS认证 |
+| 密钥算法         | EC 256                          |
+| 状态             | 正常                            |
+| 面板显示过期时间 | `2027-01-17 16:15:52`           |
+| 自动续签         | 已开启，刷新后确认仍开启        |
+| 备注             | joeyone.cn 泛域名共享证书       |
+
+日志确认两个域名均验证成功、DNS-01 临时验证记录已执行清理，并于 2026-10-19 17:14:27（面板日志）返回申请成功。以上确认的是当前签发与续签开关设置，不代表未来的自动续签任务已经执行验收。
+
+后续为 `doodle-api.joeyone.cn` 或 `doodle.joeyone.cn` 建站时，可在 HTTPS 设置中选择同一张证书。证书覆盖域名不替代 A/CNAME 解析、网站绑定和反向代理配置；实际网站证书部署完成后仍需从客户端核验。
+
+泛域名使用 DNS 自动验证，HTTP 验证不能签发泛域名。DNS 账户权限和凭据持续有效才可自动续签，任务失败应有通知。此次未读取、导出或复制 DNS 密钥及证书私钥。
+
+`*.joeyone.cn` 不覆盖 `api.doodle.joeyone.cn` 或 `img.atlas.joeyone.cn`。七牛和 Atlas 现有证书继续独立维护，1Panel 的续签不会自动更新七牛绑定。
+
+参考：[1Panel 申请证书](https://docs.fit2cloud.com/1panel/user_manual/websites/certificate-create/)、[1Panel 续签证书](https://docs.fit2cloud.com/1panel/user_manual/websites/certificate-renew/)、[Let's Encrypt 验证类型](https://letsencrypt.org/docs/challenge-types/)。
+
+## 镜像构建与交付
+
+建议使用多阶段 Dockerfile：构建阶段安装锁定依赖、构建 contracts 和 NestJS，并生成与 Linux 运行环境匹配的 Prisma 客户端；运行阶段包含 Node.js、构建产物和运行依赖，生产启动编译后的服务。
+
+不从 macOS 复制 `node_modules`，不把 `.env`、数据库备份、微信或七牛密钥打进镜像。数据库数据保存在独立卷中，不随应用镜像更新。数据库迁移作为独立发布步骤执行，不在每次应用重启时隐式执行。
+
+镜像要与服务器架构匹配。服务器已确认 x86_64，因此本机构建（包括 Apple Silicon Mac）时明确选择 `linux/amd64`。版本使用发行号或 Git 提交标识，保留上一可运行版本，不只依赖 `latest`。
+
+有两种交付方式，均可使用同一份镜像和 Compose：
+
+### 镜像仓库
+
+```text
+本机或 CI 构建镜像 → push 私有镜像仓库 → 云服务器登录仓库 → pull 指定版本 → Compose 更新 API
+```
+
+优先核查腾讯云容器镜像服务个人版在现有账号/地域的可用性与限制，不为初期部署预先购买企业版。镜像仓库是分发镜像的存储服务，不是运行 API 的服务器；应用仍在现有 Ubuntu 主机上运行。
+
+参考：[腾讯云个人版推送与拉取](https://cloud.tencent.com/document/product/1141/63910)。镜像地址和登录方式以账号实际控制台为准，不能把示例 namespace 当成已经创建的仓库。
+
+### 首次离线交付
+
+如暂不配置镜像仓库，可以本地构建后 `docker image save` 导出，使用 SSH/SCP 上传，再在云端 `docker image load` 导入，由 Compose 启动。无需将整个源码目录上传到服务器，也不要求在云端执行依赖安装与编译。
+
+这适合首次部署或仓库网络暂不可用的情况；后续频繁发布可改为 push/pull，不改变应用内部结构。
+
+参考：[Docker 镜像导出](https://docs.docker.com/reference/cli/docker/image/save/)、[跨平台构建](https://docs.docker.com/build/building/multi-platform/)。
+
+## 后续配置准备顺序
+
+1. 核查公网 IP、CPU/内存/磁盘、Docker/Compose、80/443 占用与 OpenResty 网络模式。
+2. 准备 Dockerfile、`.dockerignore`、云端 Compose、运行时环境变量示例和迁移入口。
+3. 准备数据库持久化、备份和恢复流程；备份副本需要保存到服务器之外。
+4. 核对基础镜像及应用镜像从服务器的拉取能力，再确定仓库分发或首次离线交付。
+5. 确认 API 域名并配置 DNS、1Panel 反向代理，绑定已签发的证书 ID 11，验收 HTTPS 与续签部署链路。
+6. 初始化单套云端数据库、执行迁移、受控导入内容；不整库复制开发用户和临时数据。
+7. 完成微信服务端出口 IP 与合法域名配置，再更新小程序 production 接口地址供体验版验收。
+
+当前仅完成 1Panel 泛域名证书申请，未部署 Doodle 云端应用或数据库。公网入口与云端数据库验收完成前，不将开发机的 `127.0.0.1` 地址当作可用的体验版接口。

deploy/compose.database.yaml

@@ -0,0 +1,56 @@
+name: doodle-prod
+
+services:
+    postgres:
+        image: postgres:18.6-alpine
+        container_name: doodle-postgres
+        restart: unless-stopped
+        environment:
+            POSTGRES_USER: postgres
+            POSTGRES_DB: postgres
+            POSTGRES_PASSWORD: ${POSTGRES_ADMIN_PASSWORD:?请配置独立的数据库管理密码}
+            DOODLE_MIGRATOR_PASSWORD: ${DOODLE_MIGRATOR_PASSWORD:?请配置迁移账号密码}
+            DOODLE_APP_PASSWORD: ${DOODLE_APP_PASSWORD:?请配置应用账号密码}
+            POSTGRES_INITDB_ARGS: '--encoding=UTF8 --locale=C --auth-host=scram-sha-256'
+            TZ: UTC
+            PGTZ: UTC
+        command:
+            - postgres
+            - -c
+            - timezone=UTC
+            - -c
+            - max_connections=50
+            - -c
+            - shared_buffers=128MB
+            - -c
+            - work_mem=4MB
+        # PostgreSQL 18 持久化父目录；不发布宿主机端口。
+        volumes:
+            - postgres-data:/var/lib/postgresql
+            - ./postgres/10-create-roles.sh:/docker-entrypoint-initdb.d/10-create-roles.sh:ro
+        networks:
+            - database
+        mem_limit: 512m
+        cpus: 1.0
+        pids_limit: 128
+        shm_size: 128m
+        healthcheck:
+            test: ['CMD-SHELL', 'pg_isready -U postgres -d doodle_prod']
+            interval: 10s
+            timeout: 5s
+            retries: 12
+            start_period: 15s
+        logging:
+            driver: json-file
+            options:
+                max-size: '10m'
+                max-file: '3'
+
+volumes:
+    postgres-data:
+        name: doodle-prod-postgres-data
+
+networks:
+    database:
+        name: doodle-prod-db
+        internal: true

deploy/postgres/10-create-roles.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+set -eu
+
+# 只在官方镜像首次初始化空数据卷时执行。psql 引用变量，密码不进入 SQL 字面拼接或输出。
+: "${DOODLE_MIGRATOR_PASSWORD:?缺少迁移账号密码}"
+: "${DOODLE_APP_PASSWORD:?缺少应用账号密码}"
+psql --username "$POSTGRES_USER" --dbname postgres --set ON_ERROR_STOP=1 <<'SQL'
+\getenv migration_password DOODLE_MIGRATOR_PASSWORD
+\getenv application_password DOODLE_APP_PASSWORD
+CREATE ROLE doodle_migrator LOGIN PASSWORD :'migration_password' NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;
+CREATE ROLE doodle_app LOGIN PASSWORD :'application_password' NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;
+CREATE DATABASE doodle_prod OWNER doodle_migrator ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;
+REVOKE ALL ON DATABASE doodle_prod FROM PUBLIC;
+GRANT CONNECT ON DATABASE doodle_prod TO doodle_migrator, doodle_app;
+\connect doodle_prod
+REVOKE ALL ON SCHEMA public FROM PUBLIC;
+GRANT USAGE ON SCHEMA public TO doodle_app;
+-- 迁移由 doodle_migrator 执行：后续创建的表自动赋予应用 DML 权限，不授予建表或删表权限。
+ALTER DEFAULT PRIVILEGES FOR ROLE doodle_migrator IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO doodle_app;
+ALTER DEFAULT PRIVILEGES FOR ROLE doodle_migrator IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO doodle_app;
+REVOKE ALL ON DATABASE postgres FROM PUBLIC;
+SQL

deploy/postgres/backup.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+set -eu
+umask 077
+
+# 使用容器本地 socket 备份，无须在命令行或日志中传密码；只生成新文件，不自动清理旧备份。
+deploy_dir=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+backup_dir="$deploy_dir/backups"
+mkdir -p "$backup_dir"
+backup_file="$backup_dir/doodle_prod_$(date -u +%Y%m%dT%H%M%SZ).dump"
+if [ -e "$backup_file" ] || [ -e "$backup_file.partial" ]; then
+    echo '备份文件已存在，请稍后重试' >&2
+    exit 1
+fi
+trap 'rm -f "$backup_file.partial"' EXIT HUP INT TERM
+docker compose --env-file "$deploy_dir/.env" -f "$deploy_dir/compose.database.yaml" \
+    exec -T postgres pg_dump -U postgres -d doodle_prod -Fc > "$backup_file.partial"
+# 从容器内部校验归档目录，确保可被 pg_restore 识别后才发布完整文件名。
+docker compose --env-file "$deploy_dir/.env" -f "$deploy_dir/compose.database.yaml" \
+    exec -T postgres pg_restore --list < "$backup_file.partial" > /dev/null
+mv "$backup_file.partial" "$backup_file"
+trap - EXIT HUP INT TERM
+printf '%s\n' "$backup_file"

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

@@ -0,0 +1,157 @@
+# 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
+```