docs: 基本完成初版数据库设计

docs/v3.5/迁移任务清单.md

@@ -0,0 +1,160 @@
+# Doodle Mini 云服务端迁移任务清单
+
+更新日期：2026-10-13。依据当前代码、数据库设计及《Doodle Mini 现有功能迁移到云服务端方案》整理。
+
+目标：把现有业务后端、数据、文件和定时任务迁出 CloudBase，由 doodle-store 提供统一 API、PostgreSQL 主数据库和七牛资源存储；doodle-mini 保留现有生成、绘制、保存、分享及广告能力。
+
+标记说明：已勾选表示已有实现及记录的验证；未勾选表示待完成。Server 能启动、数据库已建表，不代表业务迁移已经完成。清单不承诺具体工期，外部权限、备案和微信审核单独记录。
+
+## 一、当前已完成
+
+- [x] 建立独立 doodle-store pnpm 工作区、NestJS 11 Server、公共 contracts 包及构建检查脚本；小程序保持独立项目。
+- [x] 确认 PostgreSQL + Prisma 方向；完成 v3.5 数据库、环境及 Server 基础设置文档。
+- [x] 启动本地 PostgreSQL 18.6 Docker 开发环境，地址 127.0.0.1:5434，数据库 doodle_dev。
+- [x] 生成并执行 10 张表的建表 SQL、索引、约束及两条初始配置；临时库 19 项约束检查通过。
+- [x] 接入 Server JSON 日志、脱敏、requestId、bodyParser、/api/v1 前缀、CORS、Helmet、DTO 校验、统一错误处理及 Swagger。
+- [x] 接入 JWT 签发/验签、默认鉴权守卫、公开接口和角色声明；保留账户读取接入点。账户读取当前为拒绝放行的占位实现，真实登录未完成。
+- [x] Server 完整检查及 12 项基础/集成测试通过，构建入口真实启动检查通过；代码统一 4 空格并补充关键中文注释。
+
+## 二、实施原则与范围
+
+- 公开内容无需登录；用户资料、收藏、下载历史仅访问本人数据；管理接口只允许当前有效管理员。
+- 云服务器首期只常驻生产库；本地负责日常开发和测试，真实微信联调时按需创建同实例独立 staging 库及测试 API，不测试写生产库。
+- 图片、头像、字体及预览直接使用七牛，开发和生产资源隔离；不引入本地 MinIO、Redis、队列或微服务。
+- 本次迁移必须保留管理 API 和现有小程序管理能力。完整 Web 网站和完整独立管理后台页面不是切换前置条件。
+- 管理后台“仅管理员能登录”作为鉴权验收要求；后台登录方式尚待确认，若选账号密码需补凭证设计。
+- 暂不纳入会员、支付、孩子档案、学习包、批量 PDF、全量 Canvas 服务端重写或完整 SEO 平台。
+
+## 三、S0：线上盘点与条件核实
+
+- [ ] S0-01：确认服务器现有服务、CPU/内存/磁盘可用量，记录生产部署边界。
+- [ ] S0-02：确认 API/资源域名、备案、DNS、HTTPS、小程序 request/upload/download 域名及后台配置权限。
+- [ ] S0-03：取得微信 AppID/AppSecret、CloudBase 导出/文件权限和七牛空间/区域/域名配置；密钥仅写受控环境。
+- [ ] S0-04：全量分页导出并备份 users、categories、worksheets、favorites、download_logs、page_configs、settings；盘点是否有设计之外的线上集合和字段。
+- [ ] S0-05：整理所有旧文件引用，覆盖头像、预览、字体、配置嵌套对象、内置兜底和云存储目录；核实已有 HTTPS 文件归属。
+- [ ] S0-06：建立固定样本，记录老用户关联、原始/seed 计数、推荐顺序、页面配置、旧定时任务实际时区与执行记录。
+
+阶段验收：有完整原始备份、集合及文件清单、异常报告模板和明确的外部实施条件。
+
+## 四、S1：Prisma 与首条业务链路
+
+- [ ] S1-01：安装并锁定 Prisma 兼容版本，建立覆盖 10 张表的 schema，保持原字符串主键、C 排序规则及现有约束。
+- [ ] S1-02：将已执行的 SQL 登记为迁移基线，补齐数据库迁移流程；不得在已有表的开发库重复执行初始 DDL。
+- [ ] S1-03：实现 PrismaService、数据库连接/关闭和独立就绪检查；配置真实开发连接串及受控连接池。
+- [ ] S1-04：实现真实 AccountReader，查询用户状态、authVersion 和 role；替换当前有效 token 仍返回 503 的占位实现。
+- [ ] S1-05：落实公开/本人/管理接口分类，服务层强制校验数据归属；管理员角色不自动开放全体用户私有数据。
+- [ ] S1-06：实现 POST /auth/wechat/login：微信 code2Session、按可信 OpenID 查找并沿用老 userId、并发首次登录唯一性、JWT 签发及活跃时间维护。
+- [ ] S1-07：实现最小题型公开读取，以及收藏、成功下载记录的事务纵向样板；验证重复请求只产生一次关系或一次计数。
+- [ ] S1-08：完善公开 DTO、分页/总量、错误码与 requestId 契约；新接口 id 与旧端 _id/path/previewImg 兼容转换明确记录。
+
+阶段验收：数据库接入真实可用，老用户 ID 延续，公开内容可读，用户写入不能越权，收藏/下载并发重试不重复计数。
+
+## 五、S2：补齐服务端现有功能
+
+### 5.1 用户、收藏与下载
+
+- [ ] S2-U01：实现 GET /me、PATCH /me/profile、DELETE /me/profile；清资料保留收藏和历史。
+- [ ] S2-U02：实现 DELETE /me 注销：事务清理收藏及相关 likes、下载历史、用户资料和身份；旧凭证失效，私有文件可重试清理。
+- [ ] S2-U03：补齐收藏添加/取消/分页列表/数量/单张检查/批量检查；关系与 likes 同事务，仅真实增删影响计数。
+- [ ] S2-U04：补齐下载记录添加/分页列表/数量；要求新版 exportId，日志与 downloads 同事务；历史 NULL 事件保留。
+- [ ] S2-U05：处理失联历史：缺用户记录隔离，缺题型历史保留原 worksheetId 且详情可为空；不向用户暴露 draft/hidden 内容。
+
+### 5.2 公开内容
+
+- [ ] S2-P01：实现题型列表/详情及分类列表；公开接口强制只返回 active，不允许客户端参数绕过状态限制。
+- [ ] S2-P02：实现分龄推荐，保留 5 个年龄段、现有年龄匹配、Top3 下载+Top3 收藏、去重和不足补齐规则。
+- [ ] S2-P03：区分真实计数与 seed 展示值；推荐保留种子参与规则，排序并列明确稳定规则并与固定样本核对。
+- [ ] S2-P04：提供公共首页配置接口，保留 home/category/age/version/updatedAt 及 previewImg 字段形状。
+
+### 5.3 管理权限与操作
+
+- [ ] S2-A01：确定管理后台登录方式及凭证方案；配置首个管理员，默认用户不能注册或自升管理员。
+- [ ] S2-A02：落实后台独立登录入口或明确的管理员授权流程：身份验证后校验 active+admin，非管理员不能获得后台登录态；现有小程序管理入口同样受保护。
+- [ ] S2-A03：全部管理 API 服务端检查管理员身份；用户降权/禁用后立即失去权限，不能只靠前端隐藏按钮。
+- [ ] S2-A04：实现题型发布/重新发布/上下架/管理列表和分类状态数量；普通重发不清零真实计数，保留 createdAt/contentUpdatedAt/updatedAt 语义。
+- [ ] S2-A05：实现分类创建/更新，保留主键和父子关系，校验父分类及循环引用。
+- [ ] S2-A06：实现批量年龄/年级/tags/seed/统计修订，保留 dryRun、逐项结果和错误；真实/seed 修订记录操作者、原因及前后值。
+- [ ] S2-A07：管理修改与审计同事务；核实 worksheetsStatsUpdate 的旧调用需要，不向普通用户开放通用加数接口。
+
+### 5.4 七牛、首页与任务
+
+- [ ] S2-F01：接入七牛环境配置，落实公共预览/字体与私有头像访问策略，开发/生产上传和清理范围隔离。
+- [ ] S2-F02：实现资源上传 API，校验身份、用途、类型、大小和归属；普通用户仅上传本人头像，预览上传仅管理员。
+- [ ] S2-F03：实现 assets 元数据、对象 key、文件校验及稳定引用；响应生成访问地址，不把临时签名 URL 写入数据库。
+- [ ] S2-F04：实现头像/预览/分类图标/字体及配置嵌套资源的 DTO 解析；私有 URL 有效期与客户端刷新可用。
+- [ ] S2-C01：实现首页手动构建与配置读取，保留 featuredIds/hotIds/sections、page 分支及旧参数兜底语义。
+- [ ] S2-C02：实现首页自动 Top5 下载/收藏榜，只覆盖对应推荐数组，保留手动栏目。
+- [ ] S2-C03：实现定时启停、明确 Asia/Shanghai 时区及计划时刻、job_runs 执行结果/失败记录、当日遗漏补跑。
+- [ ] S2-C04：手动和自动刷新使用一致锁序及配置版本检查，避免并发覆盖；资产上传不放入长数据库事务。
+- [ ] S2-C05：如果兼容期仍需静态配置文件，实现按版本发布、失败重试及上一有效文件保留，DB 为唯一权威源。
+
+阶段验收：17 个现有云函数均有迁移落点或明确停用说明；用户、公开内容、管理、文件、首页和任务行为与原版对照通过。
+
+## 六、S3：小程序适配、数据试迁与旧版兼容
+
+### 6.1 小程序 HTTP 接入
+
+- [ ] S3-M01：在 doodle-mini 建立环境 API 地址及业务服务层，保留小程序独立项目和原路由/分享路径。
+- [ ] S3-M02：改造 wx.login+HTTP 登录、token 管理和 401 并发登录合并，登录成功最多重试一次；写请求复用业务幂等键。
+- [ ] S3-M03：替换分类、分龄、首页、收藏、下载、资料与设置中的正式云调用；不能只改 cloud-adapter。
+- [ ] S3-M04：替换现有管理页面的云函数调用和 settings 数据库直读，保持发布、上下架、批量同步及首页运营入口。
+- [ ] S3-M05：替换头像/预览上传、云字体解析、内置 cloud:// 兜底和首页预拉取地址；修正 HTTP 下载临时文件路径契约。
+- [ ] S3-M06：升级资料/页面配置缓存名称或版本，清理旧 cloud:// 缓存；断网继续使用可用生成/保存与内容兜底。
+- [ ] S3-M07：实现保存成功后的同 exportId 补报队列，绑定原 userId；网络失败不误报相册保存失败、不重复扣本地配额或埋点。
+- [ ] S3-M08：核对收藏成功埋点、export_success、广告、分享和相册权限；微信平台功能继续按现有方式使用。
+
+### 6.2 数据与文件迁移
+
+- [ ] S3-D01：实现全量分页导出、日期/空值/字段规范化、可重复主键导入、dryRun 和目标环境保护，正式切换后禁止旧快照覆盖新写入。
+- [ ] S3-D02：处理重复用户身份、重复收藏、重复非空 exportId、失联关联、非法字段及未知字段，逐项记录归并或隔离依据。
+- [ ] S3-D03：建立旧 fileID → assetId/objectKey → 大小/类型/checksum/状态清单；下载、上传后校验内容，不只替换 URL。
+- [ ] S3-D04：按依赖顺序导入并保留原 userId、worksheetId、日期、原始/seed 计数、页面结构和设置；不按日志数重算旧累计计数。
+- [ ] S3-D05：执行试导和对账，满足原始数=正常导入数+合并重复数+隔离数；抽查老用户、无资料用户、缺题型记录及各年龄段。
+- [ ] S3-D06：实现并演练反向转换，覆盖切换后新增、修改、取消收藏和注销删除，避免恢复时复活旧关系。
+
+### 6.3 旧版兼容桥
+
+- [ ] S3-L01：为旧云函数建立 cloud/readonly/server 模式；兼容登录、资料、收藏、下载和公共内容的两种旧响应格式。
+- [ ] S3-L02：实现桥接签名、可信 AppID/OpenID、时间窗、重放防护与服务端权限检查；旧客户端自报身份不可采信。
+- [ ] S3-L03：内部转发重试复用业务幂等键；旧下载缺 exportId 时每次接收生成 legacy ID，不按秒级时间窗口错误去重。
+- [ ] S3-L04：处理旧版 CloudBase 上传：校验旧文件环境、路径和所有者，复制至七牛后提交新库；不把永久 cloud:// 写进新库。
+- [ ] S3-L05：记录旧桥与旧文件调用量，明确管理员使用新版；不承诺旧调试管理页的数据库直读完全兼容。
+
+### 6.4 部署与联调验收
+
+- [ ] S3-O01：准备生产 Compose、固定镜像、PostgreSQL 持久卷及数据库账号权限；数据库不开放公网端口。
+- [ ] S3-O02：配置 Nginx/HTTPS/证书续期、生产密钥和日志轮转；开发/生产配置隔离，生产 Swagger 默认关闭。
+- [ ] S3-O03：按需部署独立测试 API 和 staging 库，完成新 HTTP 与旧桥共同访问隔离测试库的联调。
+- [ ] S3-O04：实现数据库每日异机备份、恢复步骤及恢复演练；若需更低 RPO，再评估 PostgreSQL WAL/PITR，不直接照搬 MySQL binlog。
+- [ ] S3-O05：配置服务/数据库就绪、错误、磁盘、备份失败与定时任务失败监测及通知。
+- [ ] S3-T01：运行权限、数据归属、登录错误、分页、并发收藏/下载、事务失败、账户注销及管理员操作的业务自动测试。
+- [ ] S3-T02：固定样本核对分类/分龄/首页分支、榜单 seed、字段、排序、去重、补齐和兜底；移除旧 100 条隐形上限。
+- [ ] S3-T03：微信体验版 iOS/Android 真机验收登录、头像/字体、生成、保存、收藏/历史、注销、管理、广告及分享；关闭域名校验绕过。
+- [ ] S3-T04：验证 token 过期、离线、保存后补报、API/任务重启、重复事件及恢复后的新增/删除数据。
+
+阶段验收：数据/文件审计通过，新旧协议只调用同一业务实现；测试版本功能及恢复演练通过，生产切换前置条件齐备。
+
+## 七、S4：正式切换
+
+- [ ] S4-01：准备低峰维护窗口、正式小程序审核/发布版本、切换模式与版本记录，明确写入冻结和回滚责任。
+- [ ] S4-02：冻结 CloudBase 全部业务及管理写入，停止旧任务；导出最终快照和新增文件，避免测试数据混入生产。
+- [ ] S4-03：最终生产导入及关联/计数/文件核对通过后，将兼容桥切到 server，新 PostgreSQL 成为唯一写入源。
+- [ ] S4-04：更新预拉取及资源配置，开启新任务，发布新版小程序，核对老用户、收藏、保存记录、字体/头像和管理功能。
+- [ ] S4-05：记录生产切换时间、Server/数据库/小程序版本、审计报告及故障处置；新库已有写入时优先回滚 API，继续使用新主库。
+
+阶段验收：新旧客户端都只写新库；生产数据、文件和功能可核对，旧库保持只读，可按演练步骤恢复。
+
+## 八、S5：观察与 CloudBase 退场
+
+- [ ] S5-01：建议先观察至少 14 天，持续核对错误、任务、真实计数、旧桥和旧文件访问；天数本身不是删除旧资源的证明。
+- [ ] S5-02：确认旧调用归零或明确剩余旧版的升级要求，完成旧数据/文件受控可恢复归档。
+- [ ] S5-03：移除正式小程序 CloudBase 初始化、旧调用和云配置；确认新端不再有 cloud://、旧上传或云字体运行依赖。
+- [ ] S5-04：满足退场条件后停用兼容函数、旧存储和套餐，保存最终审计与退出记录。
+
+阶段验收：业务稳定运行于新后端；必要旧数据有恢复副本，CloudBase 无剩余运行依赖。
+
+## 九、下一步建议
+
+优先推进 S0 线上盘点和 S1 Prisma/真实登录/题型读取/收藏下载事务的纵向样板。基础设施已齐备，当前首要技术阻塞是未接入真实数据库账户查询和业务模块。七牛资源准备可同步推进。
+
+管理员登录方式、跨端账户绑定、完整后台页面和完整 Web 分别管理：管理员授权能力及现有管理 API 属于本次；完整后台/Web 页面和 Web 用户登录不作为现有小程序迁移的切换前置条件。