R524809
5.4 KiB
题型数据导入说明
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 根目录执行，文件和报告路径使用绝对路径：
# 本地元数据预演，不写数据库
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 数据若不同则报冲突，不用旧快照覆盖新写入，不删除附件外的数据。报告文件在写库前独占创建，避免路径/权限或重名问题发生在提交之后。
报告与验证
已通过 pnpm check 及 pnpm test:db。独立临时数据库验证默认拒绝 pending、dry-run 不写库、缺分类拒绝、原 ID/计数/日期/兼容年级保留、重复导入、共享预览复用、旧快照覆盖保护与半批失败回滚；测试库已清理。正式写库后，独立于解析器逐字段核对全部 51 条题型及资产来源，并实际重复执行确认时间及审计不变。
导入本身不提供 HTTP API。2026-10-16 已另行完成题型公开查询，返回文字/元数据并对未就绪预览返回 null，详见 题型查询接口说明。七牛文件迁移与题型管理写接口仍待实施。