# 数据平台总览(交叉对齐) 三路设计已完成。本文是**唯一入口**:对照 ID/URI/包边界,列出冲突与裁定、阶段顺序、明确不做什么。不替代 01/02/03 长文;长文论证未改。 | 路 | 文档 | 产物 | |----|------|------| | 表结构 | [01-json-inventory-and-schema.md](01-json-inventory-and-schema.md) | [schema/sqlite.sql](schema/sqlite.sql) · [schema/mysql.sql](schema/mysql.sql) · [schema/json-to-table-map.md](schema/json-to-table-map.md)(99 表 + 2 视图) | | 同步 | [02-offline-sync-and-user-dimension.md](02-offline-sync-and-user-dimension.md) | MySQL 真源、设备 SQLite 镜像、事件并集、禁止 SRS LWW | | 资源 | [03-static-resource-migration.md](03-static-resource-migration.md) | [migration/](migration/README.md) 盘点/映射/dry-run(禁止全量拷贝) | --- ## 一页总决策 1. **`book_id = {stage}__{img_folder}`**(与 `ort-sequence` / events / key-words 一致,可含撇号与 `!`)。**`fs_slug` 只用于物理目录与 ASCII 文件名**,不得冒充 book_id。试点书 `stage-03__AtTheSeaside` 二者相同。 2. **`course_id` 只有 `opw-*`**(闪卡/选修课件)。**`package_id` / 下载包 id**:`core-runtime` · `book:{book_id}` · `course:{course_id}` · `dict-words` · 逻辑周包 `phonics-W1`(文件在 core,不单独 zip)。 3. **`assets.rel_uri` 是无 `/estudy` 前缀的规范公开路径**(切流后用 fs_slug):`/images/{stage}/{fs_slug}/002.png`、`/audio/books/{stage}/{fs_slug}/book.mp3`。磁盘上的 `images/books/` 由 Nginx alias 消化,**不入库**。 4. **二进制不入库**;库只存 URI / sha256 / 字节 / `package_id`。设备 SQLite 再加 `pack_id + version + checksum` 与本地文件指针。 5. **用户数据(learning / records / srs / profile / reports)绝不进资源包、绝不进公开 `/estudy/data/`**。打包扫到即失败。 6. **冲突以事件并集 + 服务端按 `at` 重放为准**,禁止整份 `srs.json` / `days.json` LWW。 7. **API 换引擎(JSON → 服务端 SQLite → MySQL)与静态树迁移(junction → html/estudy ASCII)是两条正交轨**,不要绑成一次切换。 8. **现网 API JSON 形状不变**;本目录只设计落地顺序,**现在不执行全量拷贝、不改前端、不改现网 Nginx**。 --- ## ID / URI / 包 对照 | 名称 | 公式 | 例 | 谁用 | |------|------|----|------| | `book_id` | `{stage}__{img_folder}` | `stage-03__AtTheSeaside`;`stage-03__Kipper'sIdea` | 表、events、ort、key-words、pull 的 asset pack | | `fs_slug` | ASCII:去撇号,`!?,`→`-` | `KippersIdea`;`ChipsRobot` | `html/estudy/images/books/{stage}/{fs_slug}/` | | `course_id` | `opw-*` | `opw-flashcards` | 选修课件树 `courses/{course_id}/` | | `package_id` / pack `id` | 见上表决策 2 | `book:stage-03__Kipper'sIdea` | `catalog_packages`、`assets.package_id`、manifest JSON | | 磁盘 manifest/zip 名 | `{stage}__{fs_slug}` | `manifests/book/stage-03__KippersIdea.json` | 避免文件名含 `'` / `!`;**JSON 内 id 仍用逻辑 book_id** | | `rel_uri` | 无 context 的规范 URL | `/images/stage-03/AtTheSeaside/002.png` | `assets`;运行时再加 `/estudy` | | 公开 URL | `/estudy` + rel_uri | `/estudy/images/stage-03/AtTheSeaside/002.png` | Nginx;旧空格/撇号 URL 走 rewrite | | 物理文件 | `$static_root/estudy/...` | `estudy/images/books/stage-03/AtTheSeaside/002.png` | 03 树;**不要**把 `books/` 写进 rel_uri | `example-courses.csv` 第一列叫 `course_id`,实际是 **mapping 行 id**(含 `core-tts`、`EXCLUDE-learning`)。那些不是 `course_id` 命名空间。 --- ## 冲突与裁定 | # | 冲突 | 裁定 | 已改 | |---|------|------|------| | 1 | 01/运行时:`book_id={stage}__{img_folder}`;03 mapping 曾用 `{stage}__{fs_slug}`(40 本撇号/标点书对不上 ort,如 `Kipper'sIdea` vs `KippersIdea`) | **逻辑 id 跟 01 与现网 JSON**。slug 只走路 | **已改** `01-build-mapping.py`、`books.csv` / `url-rewrites.csv`(40 本)、样例 CSV、打包脚本按 `fs_slug` 找盘 | | 2 | 01 示例 `assets.package_id=books-stage-03`(按阶段);02/03 按绘本 `book:{book_id}` | **按绘本**,与 pull/zip 同粒度 | **已改** sqlite/mysql 示例与 map | | 3 | 01 `rel_uri=/audio/books/{stage}/{title}.mp3`;03 目标 `.../{fs_slug}/book.mp3` | **切流后规范 URI 用 slug + `book.mp3`**;旧 title URL 只进 rewrite 表 | **已改** map §6 + 音频示例行 | | 4 | 01 `assets.sha1`;03 文件/包 checksum = SHA-256 | **文件与下载包用 sha256**;`catalog_packages.source_sha1` 仅课程生成器源 JSON | **已改** `assets.sha256`、`catalog_packages.checksum/checksum_alg` | | 5 | 02 课程包「按周 W1」;03 把全部 `data/curriculum` 放进 `core-runtime`(~0.9MB) | **JSON 全量进 core**(体积允许)。pull 仍可标 `phonics-W1` 作逻辑周,**不单独打含页图的周 zip** | 示例插入 `phonics-W1`(`kind=curriculum_pack`);无新 zip 格式 | | 6 | 02 书包含结构化 JSON;03 core 已含全量 L1 `data/` | **L1 JSON 以 core 为权威**;单书包强制页图+`book.mp3`,structured **可重复**带上便于只下该书 | 文档裁定;hash 脚本仍可附带该书 structured | | 7 | 03 正文 core = SPA+闪卡+L1+core 音频;`03-hash-manifest.py` 曾漏闪卡 | 以 03 正文为准 | **已改** hash 的 core 目录含 `courses/opw-flashcards` | | 8 | 01:测试 `child_id` 同等导入;02:测试孩子不进生产 | **开发库可导入回放;生产 MySQL 过滤 `apitest` 等** | 不改长文 | | 9 | 02 要 `child_alias(default→真 uuid)`;01 现 99 表无别名表 | **阶段 B 库内仍可用 `default`。阶段 C 再加别名表**,不把 99 表扩成 100 | 不改 DDL | | 10 | 01 阅读记录与 reading 事件分表;02 records 必须按 `(child_id,event_id)` upsert | **两表保留**;同步层 upsert,禁止重复 append | 不改 DDL | | 11 | Nginx `/estudy/data/` 过宽 vs 学习记录 | **deny `learning/` 与 `reading-records/`**,与是否拷贝资源无关 | 草稿已在 snippet;**尚未改现网 conf**(见下一步) | 03 正文仍写 `book_id={stage}__{fs_slug}`——以**本裁定 + 已改正文/脚本**为准,不回改 03 长文。 --- ## 库 vs 文件包(说清) ``` 服务端 MySQL / 过渡 SQLite 设备 SQLite 磁盘 / zip ───────────────────────── ──────────────────────── ──────────── catalog 元数据(书/词/课) 子集镜像 无(JSON 也可在 core 的 data/) assets 索引(URI/hash/包) pack_id+version+checksum png/mp3 真文件 usage / SRS / events 近日缓存 + outbox **禁止** ident / 画像 当前孩子摘要 **禁止** ``` - **服务端库不是给 iPad 挂载的文件**;**设备库不是多用户真源**。 - zip / `html/estudy` 只含 L1。`learning/` 继续走 API(阶段 A 仍是 JSON 文件,只是不要静态直出)。 --- ## 两轨阶段(不要互踩) | | **存储轨(02)** | **资源轨(03)** | |--|------------------|------------------| | 现在 | **A** 仍读 `docs/data` JSON | **P0 方案完成**;未全量拷贝 | | 下一步 | A 上补 records 幂等、队列 4xx 分类(实现任务) | **P1 一本试点 + 挡 learning** | | 之后 | **B** 服务端 SQLite 导库(接口测试几乎不改断言) | P2 运行时全量硬链接(~16.7GB 子集) | | | **C** MySQL 多用户 | P3 Nginx 切 ASCII 树 + rewrite | | | **D** 设备 SQLite + pull/outbox | P4 `estudy-core.zip` + 按书 zip | **互踩禁令:** - 不要在 P3 切 `book.mp3` 目录的同时改 `EASYSTUDY_STORE`(B/C)。先靠 rewrite / 过渡硬链接保旧 URL。 - 不要在 FastAPI 仍往 `DATA_DIR/learning` 写文件时,把 `DATA_DIR` 换成「不含用户目录的 catalog 副本」而不改代码。 - 不要等 MySQL 才挡 `/estudy/data/learning/`——与引擎无关。 - 不要把设备 SQLite(D)和服务端 SQLite(B)当成同一份文件。 - P1 未过不要 P2;不要现在 robocopy 全量。 开关建议:`EASYSTUDY_STORE=json|sqlite|mysql` 与 Nginx alias 切流**分开发布**。 --- ## 不做什么(本目录 / 当前执行) - 不 git commit、不改前端、不改现网 Nginx、不拷贝 16.7GB、不打生产 zip。 - 不把 `learning/`、`reading-records/`、`srs.json`、`profile`、报告打进包。 - 不把整份 JSON 塞进 TEXT;不用 SRS/days 文档 LWW。 - 不把 `EASYSTUDY_TOKEN` / MySQL / ARK 密钥下发到 iPad。 - 不把网盘「牛津树整棵树 / 白板 ISO / 67GB 视频」打进 core。 - 不回写 01/02/03 长文论证。 --- ## 建议下一步(仍是设计落地顺序) **P1 试点绘本:`stage-03__AtTheSeaside`**(readable、folder=slug、已有 key-words、mapping 音频齐全)。 建议顺序(实现任务,不是本文已执行): 1. **先挡** Nginx `location /estudy/data/learning/` 与 `/estudy/data/reading-records/` → `deny all`(或 403)。不依赖拷贝,立刻补上 02 标出的隐私缺口。catalog 的 `book-index` / `curriculum` 仍可静态。 2. `02-migrate.ps1 -FilterBookId stage-03__AtTheSeaside` 先 DryRun 再 Execute(同卷硬链接)。 3. 浏览器:封面 `002.png`、翻页、整本音频旧 URL rewrite;确认 learning URL 不再出 JSONL。 4. 复制 tts/phonemes 等到 `html/estudy`(跨卷 copy,体积小)。 5. P1 通过后再谈 P2 全量与存储轨 B。 `/estudy/data/` 整段白名单化可与 P1 挡目录一起做;**不要**把 `DATA_DIR` 从仓库 junction 一把抽走。