WeReadBoard/docs/superpowers/plans/2026-09-12-reading-goals.md

阅读目标数据库持久化实施计划

目标： 将正式看板的阅读目标迁移到现有 MySQL，保留当前业务规则与浏览器旧数据导入入口。

方案： Flask 当前接口读写 reading_goals、reading_goal_books，前端仅在服务端确认后更新目标。沿用当前个人看板范围，不增加账户体系。书籍成员独立于书架缓存，完成率根据当前已知阅读状态计算。

技术栈： 现有 Flask、PyMySQL、原生 JavaScript，无新增依赖。

步骤与验收

• 后端：在 reading_api.py 增加 GET/POST /api/reading/goals、PUT/DELETE /api/reading/goals/<id>、POST /api/reading/goals/import。JSON 字段沿用 id/name/start/end/ids/sources；列表返回 {goals: [...]}，写入返回 {goal: ...}，导入返回 {imported: N}。先补接口失败用例，再实现校验、原子事务、重复导入跳过已有 ID。
• 表结构：新增 migrations/001_reading_goals.sql，只创建目标与成员两表；成员联合主键去重，仅对目标做级联删除。通过显式迁移应用，不在每次请求时建表。
• 前端：在 static/js/weapi.js 复用请求封装支持 JSON 写入，在 static/js/app.js 接入加载、保存、追加、删除、导入和错误提示。保存中阻止重复提交，失败保留表单；旧 localStorage 不再作为运行时目标来源，也不删除旧备份。
• 边界：缺失书籍仍保留 ID 和目标分母，显示“状态待同步”，允许在编辑器移除；书单来源仅保存名称和加入时书目；日期含起止当天，全部读完优先显示已完成。
• 文档：同步 docs/technical-guide.md、docs/code-design.md、docs/API.md 及正式页面提示，保留静态 Demo 的独立说明。
• 验证：使用标准库测试验证非法输入、重复 ID、事务回滚与数据库异常；真实 MySQL 验证新建、重读、编辑、导入和删除，仅操作唯一测试 ID。检查 JavaScript 语法并通过浏览器完成新建、刷新、编辑和清理闭环。

不创建分支、提交或合并。本次工作在已检查的非主分支工作区进行，保留既有未提交改动。