YelayMaths/yelaymaths_api/tools/legacy/README.md

旧库数据迁移

把旧系统（api_yeomai_site）的数据迁到新库，供新服务端使用。

前置条件

1. 新库已建好，DATABASE_URL 指向它，且已执行建表（pnpm prisma:migrate）。
2. 旧库 dump 文件位于仓库根目录 数据库/api_yeomai_site_mysql.sql （默认路径；可用环境变量 LEGACY_DUMP 覆盖）。
3. STATIC_BASE_URL 已配置为新静态资源域名，用于改写内容字段里的旧域名。

三条命令

# 1. 体检：确认旧数据能无损映射（不连数据库，纯读 dump）
pnpm legacy:check

# 2. 试运行：完成全部转换，但不写库，用来核对行数
pnpm legacy:migrate -- --dry-run

# 3. 正式迁移
pnpm legacy:migrate

如希望直连旧库读取而不是读 dump：

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：

pnpm test

其中包含行数比对、唯一性约束、域名改写、时间换算、首页长图与课程的关联完整性。 改动迁移逻辑后请先跑测试。