94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# 旧库数据迁移
|
||
|
||
把旧系统（`api_yeomai_site`）的数据迁到新库，供新服务端使用。
|
||
|
||
## 前置条件
|
||
|
||
1. 新库已建好，`DATABASE_URL` 指向它，且**已执行建表**（`pnpm prisma:migrate`）。
|
||
2. 旧库 dump 文件位于仓库根目录 `数据库/api_yeomai_site_mysql.sql`
|
||
（默认路径；可用环境变量 `LEGACY_DUMP` 覆盖）。
|
||
3. `STATIC_BASE_URL` 已配置为新静态资源域名，用于改写内容字段里的旧域名。
|
||
|
||
## 三条命令
|
||
|
||
```bash
|
||
# 1. 体检：确认旧数据能无损映射（不连数据库，纯读 dump）
|
||
pnpm legacy:check
|
||
|
||
# 2. 试运行：完成全部转换，但不写库，用来核对行数
|
||
pnpm legacy:migrate -- --dry-run
|
||
|
||
# 3. 正式迁移
|
||
pnpm legacy:migrate
|
||
```
|
||
|
||
如希望直连旧库读取而不是读 dump：
|
||
|
||
```bash
|
||
pnpm legacy:migrate -- --from-db # 需配置 LEGACY_DATABASE_URL
|
||
```
|
||
|
||
## 迁移做了什么
|
||
|
||
| 旧表 | 新表 | 说明 |
|
||
|---|---|---|
|
||
| 用户信息 | `users` | 284 行 |
|
||
| 用户已购课程 | `entitlements` | 48 行，`source=2`（老数据），**不走支付直接标记为已拥有** |
|
||
| 课程口令码读取信息 | `courses` | 10 行，`code` 原值保留 |
|
||
| 视频课程数据 | `lessons` | 841 行，`章节id`/`播放id` 原值保留 |
|
||
| 免费视频课程数据 | `free_lessons` | 12 行 |
|
||
| 首页课程列表 | `home_courses` | 5 行，并自动关联到对应付费课程 |
|
||
| 首页免费课程列表 | `home_free_courses` | 3 行 |
|
||
| 首页横幅图片 | `banners` | 3 行 |
|
||
| 网页列表 | `articles` | 2 行 |
|
||
| 课程页面Tips | `course_tips` | 2 行 |
|
||
| cloudconfig | `settings` | 13 行 → 12 行（ID 0 占位丢弃），数字 ID 改字符串 key |
|
||
| 课程口令码 | — | **作废，不迁移** |
|
||
| 各类 `xxx2` 备份表、`网页数据`、`验证码发送` | — | 废弃 |
|
||
|
||
## 必须知道的四件事
|
||
|
||
### 1. 内容字段里的旧域名会被改写
|
||
|
||
旧库的 `首页课程列表.内容`（44 处）和 `网页列表.网页内容`（4 处）里存的是**绝对 URL**，
|
||
形如 `https://api.yeomai.site/Images/...`。旧域名退役后这些图片/视频会全部 404。
|
||
|
||
迁移时按 `STATIC_BASE_URL` 自动改写。**执行前务必确认这个变量填的是新静态域名。**
|
||
|
||
### 2. 时间按 +08:00 换算
|
||
|
||
旧库时间由服务器本地 `NOW()` 写入，是北京时间墙钟值。新库统一存 UTC，
|
||
迁移时按 `+08:00` 换算（可用 `LEGACY_UTC_OFFSET` 覆盖）。
|
||
|
||
注意旧库中确实存在 `2024-02-01` 这种**只有日期没有时间**的值，已单独处理。
|
||
|
||
### 3. `courses.code` 绝对不能被改写
|
||
|
||
它同时是视频目录名（`Course/{code}/…/playlist.m3u8`）与封面名（`Course/{code}.png`）。
|
||
迁移脚本对它逐字透传，测试中有断言保护。
|
||
|
||
### 4. 迁移会清空新库业务表
|
||
|
||
脚本采用「先清空再写入」实现幂等，失败可原样重跑。
|
||
|
||
**安全阀**：若新库已存在订单数据（说明已上线），脚本会拒绝执行，必须显式加 `--force`。
|
||
|
||
## 迁移后核对
|
||
|
||
脚本会自动逐表比对行数。此外建议人工抽查：
|
||
|
||
- 随机选几个老用户，确认其 `entitlements` 里的课程与升级前一致。
|
||
- 打开首页，确认轮播、新课长图、试听入口图片都能加载（验证域名改写生效）。
|
||
|
||
## 测试
|
||
|
||
迁移的转换逻辑由 `transform.test.ts` 覆盖（18 项），跑的是**真实的旧库 dump**：
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
其中包含行数比对、唯一性约束、域名改写、时间换算、首页长图与课程的关联完整性。
|
||
改动迁移逻辑后请先跑测试。
|
||
|