R524809
59 lines
5.4 KiB
Markdown
59 lines
5.4 KiB
Markdown
# 题型数据导入说明
|
||
|
||
## 2026-10-16 本地导入
|
||
|
||
已将用户提供的 `worksheets.json` 导入本地 `doodle_dev`。源文件为 CloudBase JSON Lines，共 51 条，无重复 ID、未知字段或日期错误，5 个引用分类均已存在。原附件未改动，SHA-256 为 `184e357f25c3c32de76d5f417315fa831e9022d24c8723d92e7bad2e77707150`。
|
||
|
||
| 项目 | 结果 |
|
||
| ---------------------------- | -------------------------------------------------- |
|
||
| 题型 | 新增 51，更新 0，隔离 0 |
|
||
| 原始发布状态 | 51 条 active，原样保留 |
|
||
| 分类分布 | math 22、puzzle 11、english 7、chinese 6、pinyin 5 |
|
||
| 预览资产 | 新增 51 条，全部 pending |
|
||
| 迁移审计 | 新增 51 条，与题型及资产同事务提交 |
|
||
| 重复导入 | 新增 0、更新 0、未变化 51，资产/时间/审计均未改变 |
|
||
| 新适用年级关系及完整内容资源 | 均未生成，不从旧值或预览图推断 |
|
||
|
||
导入批次时间为 `2026-10-16T05:59:22.266Z`，北京时间 13:59:22.266；题型自身的 createdAt/updatedAt 使用附件原值，不使用批次时间覆盖。2 条 contentUpdatedAt 原样保留，其余为 NULL。
|
||
|
||
计数对账：downloads **4203**，likes **217**，downloads_seed **629**，likes_seed **666**。11 条题型未提供两种 seed，按数据库约定默认 0，并在报告逐项列出，不重算或修正原下载、收藏计数。
|
||
|
||
`break-ten`（破十法练习）的旧 grade 为 **23**，超出新年级体系 -4～6。该值原样保留在兼容列 `worksheets.grade`；不拆成 2、3，不裁剪或归零，也不写入 `worksheet_grades`。其余旧 grade 同样未自动成为审核后的适用年级关系，后续应提供经审核的 worksheetId → grades 映射。
|
||
|
||
## 文件迁移边界
|
||
|
||
本次是**本地元数据暂存**，不是文件迁移或生产发布。51 张预览图均为旧 `cloud://` 引用，未提供本地图片，项目也尚未接入七牛配置。因此先登记稳定资产 ID 与 source_ref/source_ref_hash，status 为 pending；bucket、object_key、external_url、mime_type、size_bytes、checksum 均为 NULL，没有虚构七牛地址或文件校验结果。
|
||
|
||
为保留原始状态，题型仍记录源 active；这不表示预览图已经可访问，报告明确 `readyForPublicUse=false`。后续公共题型接口/首页构建必须校验预览资产 ready 和访问策略，不能仅检查 active 就把这批待迁移数据当作完整可用内容。正式迁移/发布仍遵循数据库设计中先完成并核验资产的顺序。
|
||
|
||
老功能保留原 ID、完整 path、标题、标签及运营标记。generation_mode 使用旧功能兼容默认 procedural，renderer_key 为 NULL，render_config 为 {}；不从 ID 猜 renderer，不把封面图当作线框，不伪造 first_published_at、内容资源或文件关联。
|
||
|
||
## 工具
|
||
|
||
在 doodle-store 根目录执行，文件和报告路径使用绝对路径：
|
||
|
||
```bash
|
||
# 本地元数据预演，不写数据库
|
||
pnpm worksheets:import --file "/绝对路径/worksheets.json" --metadata-only
|
||
|
||
# 确认预演后写入；可选报告文件必须尚不存在
|
||
pnpm worksheets:import --file "/绝对路径/worksheets.json" --metadata-only --apply --report "/绝对路径/import-report.json"
|
||
```
|
||
|
||
根命令先构建依赖和服务端；已构建时可执行 `pnpm --filter @doodle/server worksheets:import ...`。工具只允许本机 `doodle_dev`，仅读取服务端 `.env`，不连接生产。默认是 dry-run；未显式使用 `--metadata-only` 时，任何未就绪预览都会阻止导入。
|
||
|
||
输入支持 JSON Lines/数组、ISO 字符串和 CloudBase `{ "$date": "..." }` 时间，最多 10000 条、10 MiB。未知字段、重复 ID、缺分类、非法时间、年龄/难度/类型错误、负计数或数字精度风险均阻止整批写入。
|
||
|
||
题型、资产映射和迁移审计原子提交；任何后续行冲突也回滚前面已写数据。共享预览按源引用 SHA-256 复用资产；相同数据重复执行不改变原时间或增加审计。已有同 ID 数据若不同则报冲突，不用旧快照覆盖新写入，不删除附件外的数据。报告文件在写库前独占创建，避免路径/权限或重名问题发生在提交之后。
|
||
|
||
## 报告与验证
|
||
|
||
- [预演报告](worksheets-dry-run-2026-10-16.json)
|
||
- [正式导入报告](worksheets-import-2026-10-16.json)
|
||
- [重复导入报告](worksheets-reimport-2026-10-16.json)
|
||
- [独立逐字段对账报告](worksheets-verification-2026-10-16.json)
|
||
|
||
已通过 `pnpm check` 及 `pnpm test:db`。独立临时数据库验证默认拒绝 pending、dry-run 不写库、缺分类拒绝、原 ID/计数/日期/兼容年级保留、重复导入、共享预览复用、旧快照覆盖保护与半批失败回滚；测试库已清理。正式写库后，独立于解析器逐字段核对全部 51 条题型及资产来源，并实际重复执行确认时间及审计不变。
|
||
|
||
导入本身不提供 HTTP API。2026-10-16 已另行完成题型公开查询，返回文字/元数据并对未就绪预览返回 null，详见 [题型查询接口说明](./题型查询接口说明.md)。七牛文件迁移与题型管理写接口仍待实施。
|