# 后端接口契约与开发记录 - 日期 / 轮次:2026-09-06 / 第 2 轮 - 输入:00-request.md、10-analysis.md、20-product.md、30-uiux.md@第 2 轮、40-review.md@第 2 轮、50-backend.md@第 1 轮、60-test.md@第 1 轮 Bug #10、prototype/、OpenSpec book-word-spelling-game - 应用的历史教训:无 - 结论:接口就绪,可对接 ## 独立理解 本需求的数据本质是:由大人为一本确定的绘本维护一份内容配置,配置包含可启停的重点单词和可选的重点句子;重点单词可关联一句语境。该配置要跨页面、跨浏览器会话稳定存在,并成为孩子拼字题库的唯一事实来源,因此必须由后端按书持久化,不能写进会被 OCR 工具重建的 `book-structured`,也不能只放 localStorage。 后端需要记录 `stage + book_folder` 对应的完整词句文档,负责规范化单词、拒绝非法或重复词、修复悬空句子关联、生成稳定条目 ID 和时间戳,并用原子替换避免文件写到一半。孩子每轮抽题、字母干扰项、作答过程和 V1 测验结果仍是前端本机状态,不由本接口计算或持久化。 ## 上游核对 ### 原型数据流清单与接口覆盖 - 大人进入当前书「重点词句」并看到已保存内容 → `GET /api/books/{stage}/{book_folder}/key-words`;未配置返回空文档 200。覆盖 20/F01、F10,30/P0-1、40/P0-1。 - 大人新增、编辑、删除、启停单词和维护句子后点击「保存更改」 → 前端提交当前完整文档到 `PUT`;服务端回传最终落盘文档,前端以回传值替换草稿。覆盖 20/F01、F02、F10,30/P0-1、40/P0-1。 - 大人输入 ` Wanted ` → 服务端按 `text.trim().toLowerCase()` 重算为 `text=normalized=wanted`,不信任客户端传入的 `normalized`。覆盖 20/F02,30「合法单词」。 - 大人输入空值、多词、撇号、连字符、数字或重复词 → `PUT` 返回 422 逐条原因,写入前即终止,原文件不变。覆盖 20/F02,30/P0-1。 - 大人删除已关联句子 → 前端提交删除后的完整句子列表;服务端把找不到目标句子的 `sentence_id` 自动置 `null`,单词保留。覆盖 20/F01、F12,30/P0-1、40/P0-1。 - 孩子完成阅读时判断是否展示「玩拼字」 → 前端读取同一个 `GET`,统计 `enabled=true` 的词。覆盖 20/F03、F10,30/P0-2/P0-3、40/P0-2/P0-3。 - 孩子开局冻结当前书题库 → 前端从本次 `GET` 响应读取当前书的启用词,后端按每书独立文件保证不串书。覆盖 20/F04、F10,30/P0-3、40/P0-3。 - 句子语境播放 → 前端根据单词 `sentence_id` 在同文档 `sentences[]` 中取文本。覆盖 20/F12、30/F12。 - 保存失败 → 原子写失败返回 500,前端保留草稿并重试,不可显示「已保存」。覆盖 20「保存失败」、30「保存失败」、40/P0-1。 上游数据流均有接口落点。OpenSpec 决定的整文档 GET/PUT、独立目录、服务端校验、422 结构、原子写和独立路由均已实现;未发现需要改变功能范围或流程的大缺口。自行补齐的小缺口:句子空文本也按 422 拒绝,以免持久化无意义语境,不改变既定范围。 ## 接口契约 ### GET `/api/books/{stage}/{book_folder}/key-words` 用途:读取单本绘本的重点词句。文件不存在时返回空文档,HTTP 200。 请求示例: ```http GET /api/books/stage-03/AtTheSeaside/key-words ``` 空文档响应(200): ```json { "book_id": "stage-03__AtTheSeaside", "version": 1, "words": [], "sentences": [], "updated_at": "2026-09-06T10:55:00+00:00" } ``` 已有配置响应(200): ```json { "book_id": "stage-03__AtTheSeaside", "version": 1, "words": [ { "id": "a1b2c3d4", "text": "wanted", "normalized": "wanted", "enabled": true, "sentence_id": "s1e2n3t4", "created_at": "2026-09-06T10:55:00+00:00", "updated_at": "2026-09-06T10:55:00+00:00" } ], "sentences": [ { "id": "s1e2n3t4", "text": "We wanted an ice cream.", "created_at": "2026-09-06T10:55:00+00:00", "updated_at": "2026-09-06T10:55:00+00:00" } ], "updated_at": "2026-09-06T10:55:00+00:00" } ``` 错误: - 500:已有 JSON 无法读取、解析或不符合文档模型。 ```json {"detail": "重点词句读取失败,请稍后重试"} ``` 底层异常及目标文件绝对路径仅写入服务端日志,不进入 HTTP 响应。 ### PUT `/api/books/{stage}/{book_folder}/key-words` 用途:整体保存一本书的重点词句。路径参数是书籍身份的唯一依据;服务端覆盖客户端传入的 `book_id`、`version`、`normalized` 和文档 `updated_at`。 请求示例: ```json { "book_id": "stage-03__AtTheSeaside", "version": 1, "words": [ { "id": null, "text": " Wanted ", "normalized": "", "enabled": true, "sentence_id": "sentence-1", "created_at": null, "updated_at": null }, { "id": null, "text": "shell", "normalized": "", "enabled": false, "sentence_id": "missing-sentence", "created_at": null, "updated_at": null } ], "sentences": [ { "id": "sentence-1", "text": "We wanted an ice cream.", "created_at": null, "updated_at": null } ], "updated_at": "" } ``` 响应(200):返回实际落盘后的完整 `KeyWordsDocument`。上例中: - `Wanted` 变为 `text=normalized=wanted`; - 缺失的条目 `id`、`created_at`、`updated_at` 由服务端补齐; - `shell.sentence_id` 因关联不存在而变为 `null`; - `book_id` 固定为 `stage-03__AtTheSeaside`,`version` 固定为 `1`。 语义校验错误(422): ```json { "detail": [ { "index": 0, "field": "normalized", "reason": "word must contain only a-z" }, { "index": 1, "field": "normalized", "reason": "word must contain only a-z" }, { "index": 3, "field": "normalized", "reason": "duplicate normalized word" } ] } ``` `index` 是对应 `words[]` 或 `sentences[]` 的零基下标;`field` 指出问题字段;`reason` 是稳定可读原因。语义校验失败不会改写磁盘。请求 JSON 类型不符合 Pydantic 模型时,FastAPI 也返回标准 422。 写入错误(500): ```json {"detail": "重点词句保存失败,请稍后重试"} ``` 写入 500 时旧的正式 JSON 不会被半成品覆盖。底层异常及目标文件绝对路径仅写入服务端日志,不进入 HTTP 响应。 ## 数据结构与存储 - 目录:`config.KEY_WORDS_DIR`,默认 `config.DATA_DIR / "book-key-words"`,可由 `EASYSTUDY_KEY_WORDS_DIR` 覆盖。 - 文件:`{KEY_WORDS_DIR}/{stage}/{book_folder}.json`;实际绝对路径由服务端配置决定,不通过接口暴露。 - 每书一文件,避免保存一本书时重写全库或影响其他书。 - 写入在进程内由单一线程锁串行化;先写同目录 `.json.tmp`,再调用 `os.replace` 原子替换正式文件。 - `book_id` 固定为 `{stage}__{book_folder}`;`version` 当前固定为 1。 - 单词 `text` 与 `normalized` 均按去首尾空格、转小写后的 a–z 值落盘;`normalized` 不采信客户端。 - PUT 保留客户端已有的 `id` 和 `created_at`,缺失时补齐;每次保存重写条目及文档 `updated_at`。 - V1 拼字作答和家长近期错词仍在前端 localStorage,不写入本目录。 ## 代码变更清单 - `bookshelf/backend/app/config.py`:新增目录配置与按书路径函数。 - `bookshelf/backend/app/routers/key_words.py`:新增 Pydantic 文档模型、GET/PUT、校验、关联修复和原子持久化;第 2 轮将 GET/PUT 的底层异常改为服务端日志记录,对外统一返回不含路径的中文原因。 - `bookshelf/backend/app/main.py`:以 `/api/books` 前缀和 `key-words` tag 挂载独立路由。 - `bookshelf/frontend/src/api/client.ts`:新增与后端 snake_case 一致的类型和 `keyWordsApi.get/put`;补齐后端既有 `has_images` 的 `BookIndex` 类型以通过现有构建。 - `openspec/changes/book-word-spelling-game/tasks.md`:勾选 1.1~1.6。 ## 自测记录 ### 第 2 轮 - 服务重启:结束旧 Uvicorn PID 13700,使用 `python -m uvicorn app.main:app --port 8000` 重启,新 PID 15796,未使用 `--reload`;经 `GET http://127.0.0.1/api/health` 返回 200。 - PUT 写入失败复现:让 `stage-03/QaSpell500.json` 成为目录后,经 Nginx 请求 `PUT http://127.0.0.1/api/books/stage-03/QaSpell500/key-words` → 500,响应为 `{"detail":"重点词句保存失败,请稍后重试"}`,不含盘符或绝对路径;服务端错误日志包含目标路径与异常堆栈。 - GET 损坏 JSON 复现:创建损坏的 `stage-03/QaSpellBad.json` 后,经 Nginx请求 `GET http://127.0.0.1/api/books/stage-03/QaSpellBad/key-words` → 500,响应为 `{"detail":"重点词句读取失败,请稍后重试"}`,不含盘符或绝对路径;服务端错误日志包含目标路径与异常堆栈。 - 清理:`QaSpell500.json` 测试目录与 `QaSpellBad.json` 损坏测试文件均已删除。 ### 第 1 轮 - 配置路径:`python -c "from app import config; print(config.key_words_file('stage-03','AtTheSeaside'))"` 输出 `E:\nginx-1.8.0\html\data\book-key-words\stage-03\AtTheSeaside.json`。 - Python 编译:`python -m compileall app` 通过。 - 服务重启:结束旧 Uvicorn 实际工作进程,使用 `python -m uvicorn app.main:app --port 8000` 重启,新 PID 13700,未使用 `--reload`。 - Nginx GET:`GET http://127.0.0.1/api/books/stage-03/AtTheSeaside/key-words` → 200,返回正确空文档。 - 合法 PUT/GET:经 `http://127.0.0.1/api/...` 保存测试书后再次 GET,响应逐字段一致;服务端成功重算 `normalized`、补 ID/时间戳并清空悬空关联。 - 隔离性:保存测试书前后,另一书文件均不存在,未受影响。 - 422:同一请求提交 `ice cream`、`don't`、`want`、`Want` → 422;`detail` 返回 3 条 `{index, field, reason}`;请求前后正式文件字节一致。 - 500:模拟 `os.replace` 权限失败 → 500,错误结构符合契约。 - OpenAPI:`/openapi.json` 中 `/api/books/{stage}/{book_folder}/key-words` 同时存在 `get`、`put`,tag 为 `key-words`。 - 前端类型构建:`npm run build` 通过(TypeScript 与 Vite 均成功)。 - 测试使用的临时书籍 JSON 已清理,未向正式绘本写入示例数据。 ## 本轮改动 对应 `60-test.md` 第 1 轮 Bug #10(P2,后端): - 修复 PUT 写入失败时把 `OSError` 原文拼进 `detail` 的问题;客户端现在只收到通用可读原因“重点词句保存失败,请稍后重试”。 - 同步检查并修复 GET 损坏 JSON、读取错误或模型校验失败时的同类泄露;客户端只收到“重点词句读取失败,请稍后重试”。 - 两条错误路径均使用 `logger.exception` 在服务端记录目标绝对路径和异常堆栈,保留运维排障信息。 - 按 Bug #10 原复现步骤及损坏 JSON 场景,经 Nginx 复验均为 500 且响应不含绝对路径;临时测试数据已清理。