R524809
85 lines
11 KiB
Markdown
85 lines
11 KiB
Markdown
# 生产数据整合与导入方案
|
||
|
||
更新时间：2026-10-20。本文整理本轮最新的数据来源与推荐导入流程，尚未执行导出、合并或云端导入。
|
||
|
||
## 1. 最新范围与数据来源
|
||
|
||
目标是建立同时包含本地已整理内容与 CloudBase 最新用户业务数据的 `doodle_prod`。本条替代此前“只导内容”和“直接整库复制本地 doodle_dev”两种约定。
|
||
|
||
- 内容来源：本地 `doodle_dev` 中已修改的分类、题型、内容关联和七牛资源映射。
|
||
- 用户业务来源：小程序实际使用的 CloudBase 环境中最新的用户、收藏和下载记录。
|
||
- 统计、头像、设置等跨来源数据按下表逐字段处理，不用任何一个来源整库覆盖另一个来源。
|
||
- 原始源文件和本地开发库保留；先在独立迁移库整合和验证，再导入云端。旧云函数、旧数据、预拉取文件及定时任务继续保留，本次不自动修改或停用。
|
||
|
||
## 2. 表与字段来源
|
||
|
||
当前 Prisma 定义 13 张业务表，另有 `_prisma_migrations` 技术表。以下为推荐执行规则，实际导入前预演并列出冲突。
|
||
|
||
| 目标表 | 数据来源与处理 |
|
||
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `categories` | 本地。保留分类 ID、名称、层级、排序、发布状态及图标引用。 |
|
||
| `worksheets` | 内容字段取本地：标题、分类、路径、年龄/年级、难度、标签、排序、运营标记、发布状态、生成配置与预览资产引用。按相同 worksheet ID 合并 CloudBase 最新 `downloads` / `likes`；`downloads_seed` / `likes_seed` 保留本地值，不与真实计数混加。 |
|
||
| `worksheet_grades` | 本地。保留经本地维护的适用年级关系，不从旧兼容 grade 自动推断。 |
|
||
| `worksheet_resources` | 本地。保留内容资源及预览关系。 |
|
||
| `worksheet_resource_assets` | 本地。保留内容资源与文件关联。 |
|
||
| `assets` | 内容资源映射取本地；用户头像按 CloudBase 最新 `avatarUrl` 匹配已核验的七牛对象，缺失时补迁文件并建立资产。不能整表沿用本地旧头像绑定。 |
|
||
| `users` | CloudBase。保留有效的源 `_id → id`、OpenID、UnionID、昵称与原始时间；头像转换为新 `avatar_asset_id`。本地同一微信用户按 OpenID 对照，不带入本地测试身份、管理员授权或凭证状态。 |
|
||
| `favorites` | CloudBase 最新完整快照。按迁移后的 user ID 和稳定 worksheet ID 建立关联；校验唯一性，反映已取消的收藏，不将本地测试收藏合入。 |
|
||
| `download_logs` | CloudBase。保留原 ID、用户/题型引用、时间和已有 exportId；重复源记录、exportId 冲突及缺失关联进入报告，不对无 exportId 的不同历史记录擅自合并。 |
|
||
| `settings` | 逐项转换。导出 CloudBase 设置作为对照，迁移需要继续使用的业务配置；新后端专有配置单独初始化。旧 `homeAutoRefresh` 控制旧云任务，新开关控制新后端任务，不能把二者视为同一个执行器。 |
|
||
| `page_configs` | 在数据整合后由新后端重建。保留两边旧快照作核对，不直接恢复含旧资源地址或旧统计的页面缓存，不修改旧线上预拉取文件。 |
|
||
| `job_runs` | 初始化新后端任务状态。本地旧任务记录保留在源库/归档中供核对，不让开发环境的运行锁、租约或任务结果成为生产任务状态。 |
|
||
| `admin_audit_logs` | 为本次导入生成带来源、批次和摘要的迁移审计。本地历史审计保留归档，不直接当作已在线上发生的管理员操作。 |
|
||
| `_prisma_migrations` | 迁移库由仓库锁定的正式迁移初始化，保留其真实执行历史；若最终导出包含结构和该表，恢复后检查迁移状态，不重新手工建表。 |
|
||
|
||
所有源 ID 和业务计数的最终值均需报告；用户字段或设置缺少对应目标字段时采用明确映射，不透传未知字段。
|
||
|
||
## 3. 合并时需要单独处理的问题
|
||
|
||
### 题型计数
|
||
|
||
旧云函数会实时更新 CloudBase `worksheets.downloads` 和 `likes`，因此这两个字段不能取本地旧值，也不能在导入日志/收藏时再累加一次。旧计数写入与记录写入并非同一事务；先保留线上源计数，同时统计日志/收藏与计数的差异，不未经核实就用记录条数覆盖历史运营计数。
|
||
|
||
CloudBase 中不存在的本地新题型保留内容及展示 seed，真实计数建议初始化为 0，排除开发操作产生的计数。CloudBase 中存在、但本地不存在的题型进入差异清单；先补齐内容和七牛映射，再处理相关收藏/下载，不丢弃线上记录或用旧预览地址覆盖本地内容。
|
||
|
||
### 用户身份、头像和权限
|
||
|
||
CloudBase `_id` 保留为生产 user ID，同一小程序 AppID 下的 OpenID 用于核对本地与线上的相同身份，昵称和头像不能用作身份匹配。若本地资产归属使用了另一个 user ID，需要按已核对的身份映射转换；无法匹配的归属进入冲突清单。
|
||
|
||
旧用户结构没有新后端的完整权限与凭证字段。缺失时按新后端规则初始化 `role=user`、`status=active`、`auth_version`；生产管理员另按明确授权设置，不继承本地开发授权。线上存在的状态/权限字段须先核对其真实含义，不能盲目套用本地值。
|
||
|
||
`users.total_downloads` 需与 CloudBase 原始 `totalDownloads` 和有效下载记录对账。当前旧下载云函数未维护用户的 totalDownloads，不能只复制可能一直为 0 的字段；建议按去重和关联校验后的有效下载记录数建立该用户统计，并在报告中保留原值及调整理由。
|
||
|
||
头像必须以本次线上用户记录为准。已清除的头像保持为空；现有七牛对象只有在源引用和文件校验匹配时才复用。此前备份的头像可能过期，不能按文件名推断归属或默认认为用户仍在使用该图片。
|
||
|
||
CloudBase 旧注销逻辑仅删除 users，可能留下收藏或下载记录。找不到用户的记录进入隔离报告并保留原始导出，不为了满足关联而重新创建已注销账户。
|
||
|
||
### 快照时效与后续补导
|
||
|
||
一次导入得到的是某次快照，不会自动保持实时同步。CloudBase 继续接收用户操作时，导入后仍会新增下载、修改资料、取消收藏或删除账户；仅按时间追加新行无法完整处理这些变化。
|
||
|
||
正式切换前需另行安排最终快照/补导与对账；旧版本仍写 CloudBase 时还需要明确兼容或持续同步策略。本方案不以“已导入”为由自动停写旧服务，也不宣称新旧系统已实时一致。后续补导以 CloudBase 用户业务为来源，不再用本地旧整库备份覆盖已运行的生产库。
|
||
|
||
## 4. 推荐流程：先在本机独立迁移库整合
|
||
|
||
第一阶段分类、题型及必要资产的逐步命令、试导、云端连接和回退流程见 [分类与题型首次导入操作手册](./分类与题型首次导入操作手册.md)。该阶段真实题型计数暂置 0，后续仍按本方案从 CloudBase 最新快照赋值。
|
||
|
||
建议创建本地 `doodle_migration_YYYYMMDD` 作为本轮一次性整合库；它与日常 `doodle_dev` 分开，也不是需要长期维护的 staging 环境。
|
||
|
||
```text
|
||
本地 doodle_dev：内容与七牛映射 ─┐
|
||
├→ 本机独立迁移库 → 对账与恢复验证 → doodle_prod
|
||
CloudBase：最新用户业务与统计 ──┘
|
||
```
|
||
|
||
1. 保存两个来源的不可变导出、批次时间、条数与文件 SHA-256；CloudBase 导出覆盖 users、favorites、download_logs，以及用于计数/差异对照的 worksheets、categories、settings、page_configs。
|
||
2. 用项目正式 Prisma 迁移初始化独立迁移库，不修改 `doodle_dev`。
|
||
3. 导入本地内容及对应资产；若内容资产含用户归属，先按线上身份建立依赖所需的用户骨架。按分类父子及资源依赖顺序写入。
|
||
4. 导入 CloudBase 用户主体（头像先留空），核验/补迁头像资产后再绑定；处理 OpenID 重复、源 ID 冲突和用户归属映射。
|
||
5. 导入收藏、下载记录，合并线上题型计数，核对用户统计，完成设置转换和页面配置重建。
|
||
6. 对账内容完整性、源 ID、关联、记录数量、计数、头像归属、资源可访问性及管理员权限；冲突与隔离记录必须有处理结果或明确保留状态，不将它们默认为成功导入。
|
||
7. 对首次空目标制作完整 PostgreSQL 导入包，排除数据库集群角色/密码和本机运行密钥，试恢复验证后上传并导入 `doodle_prod`。若目标已使用，先核查并备份，改用可重复的受控合并流程，不直接覆盖。
|
||
8. 云端验证并备份；保留批次清单与映射，作为正式切换前补导、对账和回滚依据。
|
||
|
||
数据库密码、JWT 密钥、微信 AppSecret、七牛 AK/SK 不写入导出报告或源码。导入包包含用户数据，使用受控目录并通过 SSH/1Panel 传输；不要求开放 PostgreSQL 公网端口。
|