# 02 离线同步与用户维度 > 所属:`tasks/data-platform/`(三路并行设计 · 本路) > 版本:v1.0(2026-09-19) > 范围:**数据所有权、部署拓扑、同步协议、冲突、身份、API 分期、隐私** > 非范围:不写表结构 DDL(`01-*`)、不写资源物理路径/打包格式(`03-*`)、不改前端页面、不 git commit > 上游实现(只读):`bookshelf/backend/app/routers/{plan,events,srs,reports,days,records,books,words,curriculum,key_words}.py`、`services/{events_service,srs_engine,plan_engine,store,days_support,reports}.py`、`frontend/src/pages/child/learningEvents.ts`、`docs/data/learning/`、`docs/data/reading-records/`、`openspec/changes/daily-plan-engine/` > 下游:`01` 按本文「逻辑实体」落表;`03` 按本文「课程包/资源包边界」做物理迁移;实现阶段不得改 `/estudy/api/*` 对外 JSON 形状 --- ## 0. 一句话结论 服务端 MySQL 是**多用户学习进度的唯一真源**(事件追加、计划聚合、SRS 判定、星星);设备本地 SQLite 是**单孩子的资源镜像 + 离线进度缓冲**。上行只推事件/阅读记录/计划完成证据,幂等键仍是 `(child_id, event_id)`;下行只拉课程包清单、资源清单、画像摘要。冲突以**事件并集 + 服务端重放**为准,禁止用整份 `srs.json` / `days.json` 做 LWW。孩子已得星不得因后到的空计划或较旧快照被抹掉。现有 `POST /api/events`、`POST /api/srs/sync`、`POST /api/records` 形状保持兼容,分阶段只换存储引擎。 --- ## 1. 现状(从代码读到的事实) ### 1.1 存储与用户维度 | 数据 | 路径 | 用户维度 | 写入 | | --- | --- | --- | --- | | 绘本索引 / 结构化页 | `docs/data/book-index.json`、`book-structured/` | 无(全局目录) | 工具链 / 编辑接口 | | 拼读 / 释义 / 音素 | `251228-words/phonics-data.json`、`data.json`、`phoneme.json` | 无 | 工具链 | | 课程 | `docs/data/curriculum/*.json` | 无;`GET /api/curriculum/week` 用孩子游标切片 | 工具链 | | 重点词句 | `docs/data/book-key-words/{stage}/{book}.json` | 无(书维度配置) | `PUT /api/books/.../key-words` | | 学习运行时 | `docs/data/learning/{child_id}/`:`profile.json`、`srs.json`、`plans/`、`events/YYYY-MM.jsonl`、`days.json`、`reports/` | **已按 child_id 分目录**;V1 实际只用 `default`,测试夹杂 `apitest` 等 | 事件驱动 + 定时任务 | | 阅读记录 | `docs/data/reading-records/{child_id}.json` 数组 | child_id 文件名 | `POST /api/records` 始终 **append**(记录 id 服务端生成) | | 媒体 | Nginx alias:`/estudy/images`、`/estudy/audio`、`/estudy/data` | 无;静态直出 | 不经 API | `config.learning_path(child_id, ...)` 已是「按孩子分桶」。`main.py` lifespan 只 `ensure_profile("default")`;`scheduler.py` 的 04:00 / 23:30 / 周六周报 **写死 `child_id="default"`**。多用户后调度必须按孩子枚举,不能再写死。 ### 1.2 事件与 SRS 契约(必须保持) `POST /api/events`(单条或 ≤200 数组): - 客户端生成 `id`(`evt_` 前缀);字段 `childId、type、at(+08:00)、planItemId?、itemId?、payload、client?` - 客户端可写 type:`phonics | quiz | quiz_summary | spelling | reading | listening | writing_checkin` - 服务端独占 type(客户端提交 → **4xx**):`card_complete | day_complete | card_skip | sync | day_off`(`speaking | test` 同样拒绝,留给后续流水线) - 幂等:`(childId, id)`;重复返回 `{ok:true, ids, srsUpdates:[], card:当前}`,不追加、不重算 SRS、不加星 - 批量:**先整体校验,任一条非法 → 整批 4xx 且一条不写** - 成功响应:`{ok, ids[], srsUpdates:[{itemId, from, to, dueAt}], card:{id, status, stars}|null}` - `planItemId` = `"{date}:{cardId}"`;`itemId` = `{kind}:{normalized}`(如 `word:cat`、`phoneme:eɪ`) `POST /api/records` 仍是阅读**唯一入口**:写 JSON 数组后进程内转发**一条** `reading` 事件;`event_id` 缺省为 `evt_rec_{record.id}`。页面不得再单独 `POST /api/events` 报 reading。 `POST /api/srs/sync` 是 **localStorage `BookStudyState` 一次性迁移**,不是日常 SRS 对账。确定性 id:`evt_mig_` + sha1,item 按 `itemId` 合并且**不倒退**服务端已推进的状态。前端标记 `easy-study:synced=1`。 SRS 真源是事件流 + `srs_engine.apply`,不是客户端掌握度。本地 `status` 只镜像 `srsUpdates`。 ### 1.3 已有离线队列(且已知会 4xx 中毒) `learningEvents.ts`: - 键:`easy-study:event-queue`、`easy-study:plan-cache`、`easy-study:synced`;`CHILD_ID` 写死 `'default'` - `emit`:在线 `POST /api/events`,**任意失败**(含 4xx)入队,并乐观返回 `{ok:true, ids:[id], srsUpdates:[]}` - `flushQueue`:≤200 一批;成功则按返回 `ids` 删除;**catch 全部错误**(含 400 校验)后指数退避(1s→30s)再刷 - 触发:`online`、`visibilitychange`、进入今天页 后果:一条非法事件卡在队头时,因服务端「整批失败不写入」,队头之后的合法事件也永远刷不出去。**4xx 不得永久留在重试队列**(见 §6)。 另外:`POST /api/records` 对重复 `event_id` **仍会再 append 一条记录**,只是 reading 事件幂等。同步设计里记录也必须按 `(child_id, event_id)` upsert,避免列表膨胀。 ### 1.4 身份现状 - 查询参数 `child_id` 默认 `"default"`,孩子端前端写死 - 前端写接口:**无用户令牌**(局域网信任) - Hermes:`X-Easy-Token` 对 `EASYSTUDY_TOKEN`;仅当 body 声明 `hermes|wechat` 时校验,否则 401。Token 为空则全信 body(本地开发) - `profile.json` 把「账号资料 / 限额 / 游标 / level」揉在一份文件里 - `reading-records/default.json` 仍被 git 跟踪;`docs/data/learning/` 已 gitignore ### 1.5 隐私缺口(现状) Nginx `location /estudy/data/` alias 到 `$workhome/data/`。若运行时 `learning/`、`reading-records/` 落在该树下,学习记录可被静态 URL 拉取。资源包与静态 alias **不得**再暴露用户数据。 --- ## 2. 数据所有权与部署拓扑 ### 2.1 两个存储角色(不要混成「一个 SQLite」) | 角色 | 引擎目标 | 租户 | 职责 | 不是什么 | | --- | --- | --- | --- | --- | | **服务端库** | 现 JSON → 单机 SQLite(过渡)→ **MySQL(默认多用户)** | 多家长 / 多孩子 | 目录权威、用户权威、事件权威、计划/SRS/报告计算 | 不是给 iPad 直接挂载的文件 | | **设备本地库** | **SQLite**(每台设备一份) | **单孩子绑定** | 课程/绘本/音频**镜像**、近日计划与 SRS **缓存**、上行 outbox、下载状态 | 不是多用户账号库;不是星星真源 | 浏览器阶段可用 IndexedDB / 现有 localStorage 队列作为 SQLite 的语义等价物;原生壳或本地 sidecar 再落到真正的 SQLite 文件。协议不变。 ### 2.2 拓扑 ``` ┌─ 家长微信 / Hermes ─┐ │ 服务凭证 X-Easy-Token │ │ 只转发文案,不持有进度 │ └──────────┬────────────┘ ▼ ┌─ 公网/NAS 入口 ─ Nginx /estudy/ ─────────────────────────┐ │ 静态:前端包、已发布资源(无 learning/records) │ │ 反代:/estudy/api/* → FastAPI │ └────────────────────────────┬─────────────────────────────┘ ▼ FastAPI 业务(判定、计划、聚合) │ ┌────────────────┼────────────────┐ ▼ ▼ 服务端 MySQL(多用户) 对象/文件层(03 负责物理) 用户 + 事件 + 计划快照 绘本页图、整本音频、TTS、音素 目录元数据 + 包清单版本 ▲ │ HTTPS 同步(设备令牌) │ ┌────────┴────────┐ │ 孩子设备 iPad │ │ 本地 SQLite │ │ · 资源镜像 │ │ · 计划/SRS 缓存 │ │ · outbox │ │ 离线可学、可听、可翻页 └─────────────────┘ ``` 所有权规则: 1. **目录(书/词/课)**:服务端发布;设备只下载已签名的包。设备不得回写目录权威(重点词句编辑走家长/教研接口,不进孩子同步)。 2. **用户基本信息**:只在服务端创建;设备缓存 nick、作息、限额。 3. **用户使用数据**:设备可离线写入 outbox;**提交成功前不算服务端完成**。星星、streak、卡 `done` 以服务端聚合为准。 4. **用户画像**:只在服务端由事件 + SRS + 评测派生;设备只缓存**摘要**。 5. Hermes / 微信**不存**学习数据,继续只拉文案、代打卡(`writing_checkin` / `day_off` / `skip`)。 ### 2.3 在线 vs 离线时谁回答 `/estudy/api/*` | 阶段 | 设备在线 | 设备离线 | | --- | --- | --- | | A JSON | FastAPI 读 `docs/data` | 仅 `plan-cache` + 事件队列;无资源镜像则听读失败 | | B 服务端 SQLite | FastAPI 读本机 SQLite(从 JSON 导入) | 同上;可选开始下课程包 | | C MySQL + 设备 SQLite | FastAPI 读 MySQL;设备同步后以本地缓存加速 | **本地 SQLite 回答读接口**(书页、词卡、今日计划缓存、SRS due 缓存);写进 outbox,恢复后上行 | 孩子端 URL 与 JSON 形状不因离线切换而改变。离线时写接口由本地适配层返回与现网相同的 `{ok, ids, ...}` 乐观形,但 `srsUpdates` 仍为空或仅本地预览,**不得把卡永久标 done**(沿用 daily-plan-engine 规格)。 --- ## 3. 四层数据与落点 逻辑实体名供 `01` 建表;本文不给 DDL。`03` 只处理「目录层媒体文件」的物理迁移。 ### 3.1 分层 | 层 | 含义 | 现有文件对应 | 服务端 | 设备 SQLite | | --- | --- | --- | --- | --- | | **L1 书本/词汇基础数据** | 与谁在学无关 | book-index、book-structured、key-words、phonics-data、words data、phoneme map、curriculum/*、评测题库 | **必须有**(元数据 + 包版本) | **可全量或按包缓存** | | **L2 用户基本信息** | 家长账号、孩子、设备、作息限额 | `profile.json` 中 nick/schedule/limits/thresholds/windows/streak/features | **必须有** | 缓存当前孩子一份 | | **L3 用户使用数据** | 学了什么、计划、记录 | events、records、plans、srs、days、reports | **必须有**(报告可重建) | 近日缓存 + outbox;**不是权威** | | **L4 用户画像** | 从 L3 派生的能力摘要 | `profile.level`、cursors、报告亮点、基线评测结果 | **必须有**(派生表或物化视图) | **只缓存摘要**;禁止进资源包 | `profile.json` 拆开,避免整文件 LWW: - L2:`nick、dailyMinutes、schedule、limits、thresholds、windows、streak 规则、features、publicBaseUrl` - L3 游标:`cursors.phonicsWeek / ortIndex / ortDay / letterIndex / writtenWords[] / rereadQueue[] / ortRetried`(计划引擎读写) - L4:`level` 及后续薄弱音素、功能词正确率等摘要 ### 3.2 服务端必须有 / 可缓存到本地 / 纯本地 | 逻辑实体 | 服务端 | 设备缓存 | 纯本地 | 下载粒度 | | --- | --- | --- | --- | --- | | 绘本索引、结构化文本、页图、整本音频 | 必须 | 按书包 | 下载中的临时文件 | **按绘本** `stage__folder` | | 课程(phonics-units、hf、ort、letters、qa-bank、starters) | 必须 | 按课程包(周/单元)或全量 | 否 | **按课程包**(如 W1)或全量 | | 词库/拼读/音素图/TTS | 必须 | 全量或「本包用到的词」 | TTS 生成缓存可本地 | 全量小;音频按词 | | 重点词句配置 | 必须(书维度) | 随书包 | 否 | 随绘本 | | 家长账号、孩子、设备绑定、令牌哈希 | 必须 | 当前会话孩子 id + 设备令牌 | 令牌明文只存系统密钥链 | 不同步到第二台,直到重新绑定 | | 学习事件 | 必须(追加) | 近日窗口可选 | **outbox / dead-letter** | 不上行媒体包 | | 阅读记录 | 必须 | 近日列表 | outbox | 同上 | | 每日计划 | 必须(生成结果) | 今/昨/明 | `plan-cache` 语义 | 下行 JSON,不进资源包 | | SRS 项 | 必须(可由事件重建,但生产要物化) | due 列表 + 在学项 | 禁止当权威回推 | 下行快照 | | days.off / studyDays / starsTotal | 必须;starsTotal **建议由 card_complete 重算** | streak 摘要 | 否 | 下行 | | 日报周报 | 可重建;生产物化 | 可选 | 否 | 下行;不进资源包 | | 画像摘要 | 必须 | 一份 | 否 | 下行 `portrait` | | 孩子录音 speech | 默认可不进服务端(05:本机) | 否 | **纯本地**,90 天滚动 | 不进资源包 | | UI:成人解锁、主题、队列 | 否 | 否 | **纯本地** | — | | 服务端密钥、MySQL、ARK、Hermes token | 必须在服务端 | **禁止** | **禁止** | — | ### 3.3 课程包 vs 资源包(给 03 的边界,不写物理路径) - **课程包(catalog pack)**:某周/单元学什么——规则、词 id 列表、书 id 列表、评测抽样指针。体积小,可先下。 - **资源包(asset pack)**:某书或某词表的页图、音频、结构化 JSON。按绘本或按「本周涉及的书」下载。 - 两种包的 manifest **只含 L1**。打包工具若扫到 `learning/`、`reading-records/`、`profile`、`srs`、报告、画像,必须失败。 - 允许两种策略并存:家庭 NAS 一次全量;蜂窝网络按绘本/课程包增量。设备记录 `pack_id + version + checksum`(checksum 算法由 03 定)。 --- ## 4. 同步协议 对外仍走 `/estudy/api/*`。新增同步专用端点是**加**,不是替换 events。日常学习继续 `POST /api/events`,以便 Hermes、今天页、闯关与现网一致。 ### 4.1 概念时钟 | 时钟 | 用途 | | --- | --- | | `event_id` | 上行幂等;客户端在离线生成时就定死 | | `at` | Asia/Shanghai ISO 8601;判定与日切用 `at` 的日期,不用到达时间 | | `server_seq` | 服务端写入后单调序号;下行增量用 | | `catalog_version` | 目录/包版本;与学习进度无关 | | `portrait_updated_at` | 画像摘要失效 | 禁止用设备墙钟覆盖服务端 `generatedAt` / `dueAt`。 ### 4.2 上行(设备 → 服务端) 优先复用现契约,全部带 `childId`(或 query `child_id`,二者必须一致,不一致 4xx)。 | 数据 | 现接口 | 同步语义 | | --- | --- | --- | | 学习事件 | `POST /api/events` | 事实源。幂等 `(child_id, event_id)`。批量 ≤200。 | | 阅读完成 | `POST /api/records` | 转一条 reading;**必须以客户端 `event_id` 为稳定键**;记录行 upsert | | 计划完成/跳过 | `POST /api/plan/{date}/cards/{id}/complete\|skip` | 服务端写 `card_complete` / `card_skip`;离线时**不要**客户端伪造这两个 type,只积攒导致完成的业务事件,由服务端聚合 | | 请假 | `POST /api/days/{date}/off` | 服务端写 `day_off`;需家长/Hermes 身份 | | 旧 localStorage | `POST /api/srs/sync` | **一次性**;多设备不得当日常推 SRS | 可选整包(原生客户端):`POST /api/sync/push` ```json { "childId": "chd_…", "deviceId": "dev_…", "events": [ "/* 与 POST /api/events 单条相同 */" ], "records": [ "/* ReadingRecordInput + event_id 必填 */" ], "lastAckSeq": 12345 } ``` 实现上 `sync/push` 内部调用与 `events.ingest` / `records.create` **同一套**校验与幂等,禁止第二套判定。响应在现有 `{ok, ids, srsUpdates, card}` 上增加 `ackSeq、droppedPoison[]`(见 §6)。 **不上行**:整份 `srs.json`、整份 `days.json`、整份 plan、画像、资源文件、Hermes token。 ### 4.3 下行(服务端 → 设备) | 数据 | 现接口(继续可用) | 同步清单接口(可新增) | | --- | --- | --- | | 今日计划 | `GET /api/plan/today?child_id&date=` | 纳入 pull 的 `plans[]` | | SRS due / 列表 | `GET /api/srs/due`、`/api/srs/items` | `srsSnapshot`(压缩:在学+到期,不必全量 history) | | 连续天数/总星 | `GET /api/days/streak` | `streak` | | 课程切片 | `GET /api/curriculum/week` | `curriculumWeek` | | 书/词 | `/api/books/*`、`/api/words/*` | **不塞 pull**;走资源清单 | | 报告 | `/api/reports/daily\|weekly` | 可选;体积大则按需 GET | | 课程包/资源包清单 | 无 | `GET /api/catalog/manifest` | | 画像摘要 | 无(现混在 profile.level) | `portraitSummary` | `GET /api/sync/pull?child_id&since_seq=` 建议载荷: ```json { "childId": "chd_…", "ackSeq": 12390, "catalog": { "curriculumPacks": [{ "id": "phonics-W1", "version": "…", "checksum": "…" }], "assetPacks": [{ "id": "book:stage-03__AtTheSeaside", "version": "…", "checksum": "…" }] }, "plan": { "/* 与 GET /api/plan/today 相同形状 */": true }, "srsDue": { "items": [] }, "streak": { "streak": 0, "graceLeft": 1, "starsTotal": 6 }, "portraitSummary": { "level": "standard", "updatedAt": "2026-09-19T22:00:00+08:00", "weakPhonemes": ["eɪ"], "cursors": { "phonicsWeek": 1, "ortIndex": 0 } } } ``` `portraitSummary` 只含可驱动计划与家长一屏的字段,不含逐题事件。资源二进制仍按 03 的 URL 下载,不经 pull JSON。 ### 4.4 同步节奏 1. 打开 App / `online` / 今天页聚焦:先 `flush outbox`,再 `pull`,再核对缺失资源包。 2. 学习过程:单条 `POST /api/events`(与现在一致);失败入 outbox。 3. 资源:pull 发现新 version → 后台下载;未下完的书可进阅读器但页图缺失要有明确失败,不得用其它书的图顶上。 4. 服务端定时任务(04:00 生成计划等)按**所有活跃孩子**跑,结果等设备 pull,不要求设备在线。 --- ## 5. 冲突策略(不丢已完成星) 原则:**事件是并集;派生状态由服务端按 `at` 重放/增量 apply;禁止对派生快照做整文档 LWW。** | 对象 | 策略 | 理由 | | --- | --- | --- | | 事件 | **先写获胜**(同一 `(child_id, event_id)` 忽略后到 payload) | 已有幂等;重放安全 | | 不同 id 的真实两次作答 | **都保留**,按 `at` 顺序 apply | 两台设备各做一题都该计 | | SRS 项 | **禁止 LWW `srs.json`**。只通过事件 apply。`POST /api/srs/sync` 的「不倒退 status、sources 并集、wrongCount 相加」仅用于一次性迁移 | 避免旧快照把 `weekly` 打回 `new` | | 计划卡状态 / `earnedStars` | **服务端按事件重聚合**。`done` ∪ `done` = `done`。禁止用「更新的 pending 计划」覆盖已有 done | 离线收星后另一台先拉到空计划会丢星 | | `starsTotal` | **max(重算值, 已存值)** 或直接由 `card_complete` 事件去重求和(推荐后者) | `days_support.add_stars` 是累加器,LWW 会丢;重放必须幂等 | | `card_complete` id | 保持 `evt_srv_{date}_{cardId}` 天然幂等 | 两台同时学完同一卡只加一星 | | `profile` L2 字段 | **LWW by `updatedAt`**(家长改作息) | 无星星语义 | | `cursors` | **单调合并**:数字 `max`,数组 **并集**,布尔 `ortRetried` 一旦 true 不回 false | 防止周进度被旧设备打回 W1 | | `days.off` | 日期键 **并集** | 请假不可丢 | | `level` / 画像 | 服务端重算,下行覆盖本地摘要 | 本地不算掌握度 | | 资源包 | 版本号高者胜;校验失败则保留旧包可用 | 学习不堵在坏包 | | 阅读记录 | `(child_id, event_id)` upsert;无 event_id 的历史行保持原 `id` | 修现状的双写 | **明确否决**:以设备 `updatedAt` 较新的整份 `days.json`(`starsTotal: 0`)覆盖服务端 6 星——这是会丢星的 LWW。 多设备同时离线学同一张卡:事件 id 不同 → 可能重复练习计数(SRS `correctDays` 同日仍只计 1,见现规格),但星星仍只 1(`card_complete` 幂等)。可接受。 家长 `POST /api/srs/items/{id}/reset` 是服务端命令,下行后本地必须跟从(这是故意回退,不是冲突)。 --- ## 6. 离线队列与 4xx 中毒 ### 6.1 队列分层(设备纯本地) | 队列 | 内容 | 成功 | 失败 | | --- | --- | --- | --- | | **outbox(重试)** | 尚未被服务端确认的合法候选 | 返回 ids 则删除 | 仅网络 / 5xx / 429 | | **dead-letter(隔离)** | 确认不可自动恢复的 4xx | 不自动重试 | 家长可见「有 X 条没记下」,不进孩子主路径 | | **in-flight** | 正在刷的一批 | — | 崩溃则回到 outbox,靠幂等 | 现有单数组 `easy-study:event-queue` 升级为上述三态;键名可保留兼容,条目加 `status、lastError、httpStatus、attempts`。 ### 6.2 HTTP 分类(已知:4xx 不得永久塞重试队列) | 状态 | 动作 | | --- | --- | | 2xx | 按 `ids` 出队;幂等重复视为成功 | | 401 / 403 | **暂停** outbox,进入需重新绑定/登录;**不出死信、不丢事件**(令牌过期不是内容坏) | | 408 / 429 / 5xx / 网络失败 | 留在 outbox,指数退避 + 抖动,上限建议 5 min;**整批可重试** | | 400 / 422(校验:type、payload、id 前缀、batch>200) | **不得**用同一整批死循环。拆成单条(或二分)定位毒丸 → 毒丸进 dead-letter,其余回 outbox 立即再刷 | | 404 卡不存在等业务 4xx | 进 dead-letter(计划已换日等);不阻塞后续事件 | | 413 | 缩小批次,不进死信 | 服务端继续「非法整批拒绝」以保持现契约;**解毒在客户端隔离**,不强迫第一天改成部分成功。后续可加每条 `{id, status, error}` 以减少往返,但对现网客户端仍要能消化整批 4xx。 `emit()` 今日把 4xx 与断网一视同仁地入队——这是中毒根因。分期改造:4xx 校验失败走 dead-letter;仅传输失败走 outbox。本文只定协议,不改页面。 ### 6.3 与星星乐观显示 沿用规格:离线可显示「待同步」,**禁止**本地把卡写成永久 `done`、禁止本地推进 SRS。毒丸进死信后,该题可以「没记下」而不发星;其它已确认事件仍由服务端聚合发星。 ### 6.4 records 队列 阅读完成若走 `POST /api/records`,离线必须带客户端 `event_id`。重试不得因服务端每次新生成 `record.id` 而插入第二行(§1.3)。队列分类与 events 相同。 --- ## 7. 身份:孩子、家长、设备、default 迁移 ### 7.1 三个身份,不要再用一个共享 token 冒充用户 | 身份 | 是谁 | 凭证 | 能做什么 | | --- | --- | --- | --- | | **家长账号** `parent_id` | 微信/密码登录的成人 | 会话令牌(服务端签发) | 看报告、改作息、skip、请假、reset SRS、绑设备 | | **孩子** `child_id` | 学习主体(稳定 id,不再长期用 `default` 字符串当主键) | 不直接持有密码 | 所有 L3/L4 挂在此 id | | **设备** `device_id` | 一台 iPad / 一台浏览器配置文件 | **设备令牌**(绑定 `child_id`,可吊销) | 同步、拉包、写 events/records | | **Hermes 服务** | 家里的网关 | 现有 `EASYSTUDY_TOKEN` / `X-Easy-Token` | 代发微信、代写 checkin/off/skip;**不下发到 iPad 前端** | 孩子端请求:`Authorization: Bearer ` + 现有 `child_id`。令牌与 child 不一致 → 403。过渡期(局域网、token 未配):行为与现在相同(信任 query `child_id`),但日志打 `auth=lan-trust`。 Hermes 继续用服务 token,并带 `EASYSTUDY_CHILD_ID`;多孩子后脚本必须显式传 child,禁止默认写到已迁移走的 `default` 别名而不察觉。 ### 7.2 `child_id` 稳定化 - 对外 API **继续接受** `child_id=default`,作为**别名**解析到该部署的「主孩子」`child_id`(UUID/`chd_…`)。 - 事件 JSON 里历史 `childId: "default"` 迁移后可保留原样或回填新 id;幂等键用**解析后的内部 id** + `event.id`,以免别名切换导致重放双计。推荐:库内一律内部 id;读接口按需仍可展示。 - 前端 `learningEvents.ts` 的 `CHILD_ID = 'default'` 在绑定期改为读已解析 id;本路不改页面,只要求实现时把硬编码收口到一处配置。 ### 7.3 把 `default` 迁成真用户 一次性、幂等、可重复执行: 1. 创建 `parent_id`(家庭第一位家长)。 2. 创建真实 `child_id`,`nick` 取 `learning/default/profile.json` 的 nick(现「小丫」)。 3. 登记别名 `default` → 该 `child_id`。 4. 导入 `docs/data/learning/default/**`:events 行保持原 `id`;srs/plans/days/reports/profile 按层拆入。 5. 导入 `docs/data/reading-records/default.json`:为无 `event_id` 的旧行生成稳定 `event_id = evt_rec_{原id}` 再走 ingest(已存在则跳过)。 6. 写一条服务端 `sync` 事件,payload 记录 `migratedFrom: "default"`、条数。 7. 测试目录(`apitest`、`cardtest`…)**不要**当成真用户导入生产。 8. `POST /api/srs/sync` 对已导入孩子再次调用:保持现语义(migratedItems=0)。 回滚:保留 JSON 文件只读备份;别名可指回文件后端(阶段 A)。 ### 7.4 多设备绑定 家长在家长端确认「这台 iPad 是小丫的」。新设备令牌签发后,旧设备可并存(家里两台)——冲突按 §5。丢失设备:吊销 device_token,outbox 作废(未上行的进度无法找回,需产品文案说明)。 --- ## 8. API 演进与分阶段切换 ### 8.1 不变的形状 前缀仍是 Nginx `/estudy/api/` → 进程 `/api/`。下列路径与 JSON 字段名、大小写(事件 camelCase、records snake_case)**保持**: | 方法 | 路径 | 现数据源 | C 阶段数据源 | | --- | --- | --- | --- | | GET | `/api/health` | 内存 | 可加 `storage=mysql` | | GET | `/api/books/`、`/{stage}/{folder}`、`/page/`、`/words` | book-index + structured + 页图 | MySQL 目录 + 本地包优先 | | GET/PUT | `/api/books/.../key-words` | book-key-words JSON | 目录表 | | PUT/DELETE | 页词编辑、audio-time | structured JSON | 目录表(教研,非孩子同步) | | GET | `/api/words/phonemes`、`phoneme-audio-map`、`lookup`、`search`、`references` | phonics-data / data.json / phoneme.json | 目录表;音频 URL 仍相对 `/estudy/audio/...` | | POST | `/api/words/tts/{word}` | 生成文件 | 服务端生成或 404 让设备用已下载 TTS | | POST/GET | `/api/records` | `reading-records/{child}.json` | MySQL L3;离线 SQLite outbox | | GET | `/api/plan/today`、wechat-text | `plans/*.json` | MySQL;离线缓存 | | POST | `/api/plan/generate`、skip、complete | 同上 + events | 同上 | | POST/GET | `/api/events` | `events/*.jsonl` | MySQL;幂等键不变 | | GET/POST | `/api/srs/due|items|reset|sync` | `srs.json` | MySQL 物化;sync 仍一次性 | | GET | `/api/reports/daily|weekly` | 物化 JSON 或即时聚合 | MySQL;规则不变 | | POST/GET | `/api/days/{date}/off`、`/streak` | `days.json` | MySQL | | GET | `/api/curriculum/week` | curriculum JSON + profile cursors | 目录 + L3 游标 | 错误体仍 `{detail}`。`child_id` 缺省在别名存在时等于主孩子,否则 400(取消「静默写到错误的 default 目录」)。 ### 8.2 阶段闸门(存储切换,不是改前端路由) ``` 阶段 A 仍读 JSON 现网。补:records 按 event_id 幂等、队列 4xx 分类(实现任务,非本文件改代码) 阶段 B 服务端 SQLite FastAPI 背后换引擎;从 JSON 导入;接口测试(test_daily_plan_http)应几乎不改断言 阶段 C 服务端 MySQL 多用户默认;设备令牌可选打开 阶段 D 设备 SQLite 镜像 资源包 + outbox + pull;离线主路径。可与 C 并行试点 ``` 阶段 B 的 SQLite 是**服务端**过渡(单机、便于从 JSON 搬家),**不是** iPad 里那份。两份 schema 应对齐逻辑实体,但设备库可以没有家长账号表、可以没有全量历史事件。 切换开关建议:`EASYSTUDY_STORE=json|sqlite|mysql`(环境变量)。同一进程不混写两种权威库。双写仅允许短暂迁移窗,且以新库为准做读。 ### 8.3 前端/Hermes 兼容 - 孩子端继续 `withBase('/api')`。 - Hermes 脚本继续 `EASYSTUDY_API` + `X-Easy-Token`;增加显式 `EASYSTUDY_CHILD_ID`(已有)。 - 新设备令牌用独立头,**不要**把 `EASYSTUDY_TOKEN` 编译进前端。 - `POST /api/srs/sync` 在 C 以后仍保留,供尚未清掉的 `easy-study:phonics:book:*`。 --- ## 9. 隐私与密钥 1. **画像与学习记录不进资源包**(课程包/绘本包/词音频包均同)。CI / 打包脚本拒绝 `learning/**`、`reading-records/**`、`reports/**`、`srs`、`profile`。 2. **Nginx**:`/estudy/data/` 不得再 alias 整个 `DATA_DIR`。公开静态只保留目录资源;或改为仅 `curriculum/`、`book-structured/` 白名单。`learning/` 只经 API + 鉴权。 3. **服务端密钥不进客户端**:`EASYSTUDY_TOKEN`、MySQL、ARK、对象存储密钥、备份凭据。设备只有设备令牌。TTS/ASR 的云密钥只在服务端。 4. **下行最小化**:pull 给画像摘要,不给完整事件史(家长报告页在线另拉)。设备 outbox 属本机,卸权时清除。 5. **录音**:默认纯本地;若将来上传,按 event_id 对象键且不进公开 alias。 6. **测试孩子数据**(`apitest` 等)不进生产包、不进真用户迁移。 --- ## 10. 与现有 events / srs 契约的兼容清单 实现阶段验收必须全部为真: 1. `POST /api/events` 单条 `phonics` 仍返回 `ok / ids / srsUpdates / card`;JSONL 或 MySQL 行可按原 `id` 查到。 2. 同一 `(childId, id)` 重放:第二次 `srsUpdates=[]`,星星与 `wrongCount` 不变。 3. 客户端提交 `card_complete` 仍 4xx。 4. 201 条批量仍 4xx 且零写入。 5. `POST /api/records` 无新字段仍成功,并转一条 reading;带 `event_id` 的两次提交只产生一条 reading、c3 只一星。 6. `POST /api/srs/sync` 重复调用 `migratedItems=0, migratedEvents=0`。 7. `GET /api/srs/due`、`/items`、`reset` 行为不变。 8. 计划 `force=true` 在当日已有 planItemId 事件时仍 4xx。 9. 离线队列:合法事件在 4xx 毒丸存在时仍能被刷上去(毒丸进死信)。 10. 别名 `child_id=default` 在迁移后读写的是真孩子,不丢 `learning/default` 里已有星。 --- ## 11. 给并行两路的接口(无 DDL、无物理路径) **给 01 表结构**(逻辑实体,按层): - L1:`catalog_pack`、`asset_pack`、书/页/词/音素/课程单元的权威行(细节由 01 定) - L2:`parent`、`child`、`child_alias(default)`、`device`、`device_token_hash`、孩子设置(原 profile L2) - L3:`learning_event` 唯一键 `(child_id, event_id)`;`reading_record` 唯一键 `(child_id, event_id)`;`daily_plan`;`srs_item`;`day_state`;报告物化可选 - L4:`portrait_summary`(由 L3 派生,可重建) - 不要为「整份 srs.json 同步」建冲突时间戳覆盖列作为权威 **给 03 资源物理迁移**: - 包类型只有 L1;manifest 字段至少 `id, version, checksum, items[]` - 下载 URL 继续可映射到现 `/estudy/images`、`/estudy/audio` - 明确排除用户目录;修复 `/estudy/data/` 过宽 alias - 设备 SQLite 只存「包元数据 + 本地文件指针」,文件落盘布局由 03 决定 --- ## 12. 风险 - 事件与 SRS/plan 今日跨文件非事务;迁库后 **ingest 必须单事务**:插事件(或忽略重复)+ apply SRS + 聚合卡 + 加星。JSON 阶段可用「事件为真源、夜间重建」兜底。 - 幂等索引现只预热两个月;SQL 唯一键后该问题消失。 - 局域网信任关掉过早会让现 iPad 全 401;阶段 C 默认仍可 lan-trust,设备令牌用开关。 - 全量词音频很大:必须支持按书/按周包,不能只提供「一次性下完整个 workhome」。