feat(reading-goals): 持久化阅读目标并收紧看板布局

docs/V2_API.md

@@ -13,9 +13,9 @@ v1 的 `/api/*` 接口保持不变，两套接口可同时使用。
 | 笔记本与笔记 | 本地 `notebooks` 表 + 实时 `/book/bookmarklist`、`/review/list/mine` | 划线与想法正文实时获取 |
 | 书籍详情 | 实时 `/book/info`、`/book/getprogress`、`/book/chapterinfo`、`/book/bestbookmarks`、`/review/list`、`/book/similar` | 逐项降级，单项失败不影响整页 |
 | 搜索 / 推荐 | 实时 `/store/search`（按 scope 切换类型）、`/book/recommend` | |
-| 阅读目标 | 浏览器 localStorage（key `weread-goals-v2`） | 与设计稿一致，不落库 |
+| 阅读目标 | MySQL `reading_goals` / `reading_goal_books` | 数据库持久化；旧浏览器目标可手动导入 |
 
-MySQL 不可用时接口仍可用（返回 `degraded: true`），依赖本地缓存的字段会退化为实时接口结果。
+MySQL 不可用时，阅读数据接口仍可降级运行（返回 `degraded: true`）。阅读目标必须持久化，其接口返回 503，不退回浏览器保存。
 
 ## 接口清单
 
@@ -38,6 +38,28 @@ MySQL 不可用时接口仍可用（返回 `degraded: true`），依赖本地缓
 
 ## 与微信读书接口的字段口径
 
+### 阅读目标接口
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/v2/goals` | 返回 `{"goals":[...]}`，成员按书籍 ID 排序 |
+| POST | `/api/v2/goals` | 新建，成功返回 201 和 `{"goal":{...}}` |
+| PUT | `/api/v2/goals/<id>` | 整体替换目标和书目，返回 `{"goal":{...}}` |
+| DELETE | `/api/v2/goals/<id>` | 删除目标及其成员，返回 `{"ok":true}` |
+| POST | `/api/v2/goals/import` | 请求 `{"goals":[...]}`，返回 `{"imported":新增数量}` |
+
+新建、编辑和导入中的目标字段一致：
+
+```json
+{"id":"goal-example","name":"秋季阅读","start":"2026-09-01","end":"2026-09-30","ids":["123","456"],"sources":["文学书单"]}
+```
+
+ID 和书籍 ID 为 1 至 64 字符的字符串；名称去除首尾空格后为 1 至 60 字符。日期必须为有效的 `YYYY-MM-DD`，年份为 1000 至 9999，结束日期不早于开始日期。`ids` 为非空字符串数组；`sources` 为字符串数组，省略时默认为空。PUT 请求体 ID 必须与路径一致。
+
+书籍和来源去重，未知书籍 ID 仍保留。错误返回 `{"error":"中文说明"}`：400 参数非法、404 目标不存在、409 新建 ID 冲突、503 数据库不可用。导入不覆盖已有 ID，失败时回滚整个批次。迁移与验证方式见 [技术指南](technical-guide.md)。
+
+### 阅读数据字段
+
 - 评分：接口 `newRating` 为 0~1000，接口层换算成 `score = newRating / 100`（前端按设计稿公式展示为 `评分 XX/100`），详情页展示 `rating = newRating / 10`。
 - 封面：设计稿使用 4 种示意底色（`c1`~`c4`），由 `book_id` 哈希稳定映射；真实封面 URL 保留在 `cover_url`。
 - 进度：统一到 0~100 整数；`status` 口径为「读完=done、有最近阅读=reading、从未读过=wish」。

docs/code-design.md

@@ -48,3 +48,29 @@
 书架的有声内容完结不等于用户读完，所以未用其完结状态计算阅读目标。文章收藏是入口，不假装能直接列出内部文章。缺失资料显示暂无，不补造 ISBN 等字段。
 
 正式接口接入单独推进，必须核对实时可用接口、鉴权、分页、错误、升级提示及字段口径；本轮 Demo 的完成状态不得用于宣称这些能力已真实接入。
+
+## 正式看板的紧凑布局
+
+正式看板在 `static/css/styles.css` 中统一调整页面密度。顶栏高度为桌面 58 px、手机 56 px；标题区采用更短的上下间距，隐藏页面标题前的英文装饰文字。标题、说明、筛选、内容依次展示，操作按钮在桌面与标题并排，手机上自然换行。
+
+书架按可用宽度自动排列书籍，每列约 116 px 起步；手机固定两列。真实封面维持原比例，并受所在列宽度约束。例如，书架网格可用宽度为 900 px 时显示多列紧凑排布，手机宽度为 390 px 时显示 2 列，长书名仍使用已有省略规则。
+
+目标介绍区在宽屏上把说明与统计并排，窄屏上改为上下排列；目标卡按可用宽度自动排列，每张卡约 280 px 起步，并缩小封面预览和上下间距。例如，一个包含 6 本书、已读完 2 本的月度目标仍展示原有完成数和进度，只减少卡片占位。页面渲染、筛选、目标计算和数据流保持由现有 JavaScript 实现，CSS 不改变业务口径。
+
+## 正式看板的阅读目标持久化
+
+正式看板使用 `static/js/app.js`、`static/js/weapi.js` 和 `api_v2.py`。本节覆盖正式页面；前文的 Demo 存储方式不适用于正式目标。
+
+`reading_goals` 保存 `id`、`name`、`start_date`、`end_date`、来源书单名称 `sources` 和创建、修改时间。`reading_goal_books` 保存 `goal_id`、`book_id`，联合主键防止同一目标重复计书。目标 ID 沿用前端生成值，便于导入旧目标。来源名称保存为 JSON 数组，不表示持续关联书单。
+
+目标成员只通过外键关联目标。删除目标时级联删除成员，书架不受影响；书籍移出书架时也不删除目标成员。迁移位于 `migrations/001_reading_goals.sql`，只需部署时执行，不在请求中自动建表。
+
+页面加载时 GET 目标列表，新建时 POST，编辑及追加书籍时 PUT，删除时 DELETE。表单先校验名称、日期和书目，服务端再次校验。目标与成员在同一事务中提交，编辑时锁定目标父记录并整体替换成员，避免并发请求混入两份书目。多个浏览器同时编辑同一目标时，以最后成功保存的完整内容为准。
+
+前端收到提交成功响应后更新内存并关闭表单。保存中阻止重复提交；目标列表未从数据库读取完成前，不打开新建或编辑窗口，避免初始读取失败状态覆盖刚保存的目标。新建重试保持原 ID。数据库错误转换为 503，回滚事务并让前端保留草稿。目标列表不使用进程缓存，刷新即读取数据库。
+
+例：创建“秋季阅读”，日期为 `2026-09-01` 至 `2026-09-30`，输入书籍 `["A", "A", "B"]` 和来源 `["文学书单"]`。数据库生成 1 条目标、2 条成员。若 A 已读完而 B 未读完，页面显示 `1 / 2，50%`；B 暂时不在书架中时仍显示 `1 / 2，50%`，B 的资料占位显示“状态待同步”，可在编辑器移除。若用户明确移除 B，则显示 `1 / 1，100%`。
+
+完成率和状态不写入目标表。当前已知已读状态用于计算，不要求在目标日期内读完；全部已读完优先显示“已完成”，否则按浏览器本地日期显示未开始、进行中或已到期，起止当天均属于进行中。未知状态不计为已完成，但仍计入分母。
+
+旧数据仅在用户点击导入时发送给 `/api/v2/goals/import`。先校验整批，再在事务中逐项插入；相同 ID 已存在时保留数据库内容，批次内重复 ID 只处理第一条。例如库中已有 G1，导入 `[G1, G2, G2]` 返回 `{"imported":1}`，再次导入返回 `{"imported":0}`。任何写入失败均回滚整批；成功后保留原浏览器备份并记录导入标记。

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

@@ -0,0 +1,18 @@
+# 阅读目标数据库持久化实施计划
+
+**目标：** 将正式看板的阅读目标迁移到现有 MySQL，保留当前业务规则与浏览器旧数据导入入口。
+
+**方案：** Flask v2 接口读写 `reading_goals`、`reading_goal_books`，前端仅在服务端确认后更新目标。沿用当前个人看板范围，不增加账户体系。书籍成员独立于书架缓存，完成率根据当前已知阅读状态计算。
+
+**技术栈：** 现有 Flask、PyMySQL、原生 JavaScript，无新增依赖。
+
+## 步骤与验收
+
+- [x] 后端：在 `api_v2.py` 增加 GET/POST `/api/v2/goals`、PUT/DELETE `/api/v2/goals/<id>`、POST `/api/v2/goals/import`。JSON 字段沿用 `id/name/start/end/ids/sources`；列表返回 `{goals: [...]}`，写入返回 `{goal: ...}`，导入返回 `{imported: N}`。先补接口失败用例，再实现校验、原子事务、重复导入跳过已有 ID。
+- [x] 表结构：新增 `migrations/001_reading_goals.sql`，只创建目标与成员两表；成员联合主键去重，仅对目标做级联删除。通过显式迁移应用，不在每次请求时建表。
+- [x] 前端：在 `static/js/weapi.js` 复用请求封装支持 JSON 写入，在 `static/js/app.js` 接入加载、保存、追加、删除、导入和错误提示。保存中阻止重复提交，失败保留表单；旧 localStorage 不再作为运行时目标来源，也不删除旧备份。
+- [x] 边界：缺失书籍仍保留 ID 和目标分母，显示“状态待同步”，允许在编辑器移除；书单来源仅保存名称和加入时书目；日期含起止当天，全部读完优先显示已完成。
+- [x] 文档：同步 `docs/technical-guide.md`、`docs/code-design.md`、`docs/V2_API.md` 及正式页面提示，保留静态 Demo 的独立说明。
+- [x] 验证：使用标准库测试验证非法输入、重复 ID、事务回滚与数据库异常；真实 MySQL 验证新建、重读、编辑、导入和删除，仅操作唯一测试 ID。检查 JavaScript 语法并通过浏览器完成新建、刷新、编辑和清理闭环。
+
+不创建分支、提交或合并。本次工作在已检查的非主分支工作区进行，保留既有未提交改动。

docs/technical-guide.md

@@ -55,3 +55,54 @@ node --check web-demo/demo-data.js
 ## 与 1.0 的关系
 
 1.0 继续由根目录的 `app.py`、`fetch_data.py`、`templates/` 和 `static/` 提供，运行在 8080 端口。2.0 探索 Demo 位于 `web-demo/`，两者可以独立预览。
+
+## 正式看板的紧凑样式
+
+正式看板由 `templates/index.html` 和 `static/css/styles.css` 提供，使用现有启动方式，不新增依赖、配置或环境变量。上文的 `web-demo/` 是独立的历史设计 Demo，本次样式调整仅应用于正式看板。
+
+刷新正式看板即可加载样式；若浏览器仍显示旧间距，强制刷新页面。检查阅读概览、我的书架、阅读目标在桌面和手机宽度下的展示，并切换暗色主题。目标数据的保存方式由当前应用逻辑决定，样式不参与存储。
+
+## 正式看板的阅读目标数据库
+
+正式页面的目标通过 `/api/v2/goals` 保存到 MySQL。浏览器只保留编辑草稿和页面状态，刷新或换浏览器后从同一服务读取目标。上文 `web-demo/` 的本地存储说明仅适用于静态 Demo。
+
+沿用 `api_v2.py` 的 `WEREAD_DB_HOST`、`WEREAD_DB_PORT`、`WEREAD_DB_USER`、`WEREAD_DB_PASSWORD` 和 `WEREAD_DB_NAME` 配置，不新增依赖。服务仍使用当前个人账号的数据；多个浏览器连接同一服务时共享目标，没有新增多用户隔离。
+
+部署新代码前，在项目根目录执行一次迁移。下面的命令复用服务配置，只创建两张目标表，不修改已有业务表：
+
+```sh
+python3 - <<'PY'
+from pathlib import Path
+import pymysql
+from api_v2 import MYSQL_CONFIG
+
+with pymysql.connect(**MYSQL_CONFIG) as conn:
+    with conn.cursor() as cur:
+        for sql in Path('migrations/001_reading_goals.sql').read_text().split(';'):
+            if sql.strip():
+                cur.execute(sql)
+print('阅读目标表已就绪')
+PY
+PORT=8080 python3 app.py
+```
+
+使用已安装 `requirements.txt` 的 Python 环境。若 8080 已有本项目实例，先停止旧实例再启动，使 Flask 加载新接口。迁移可重复执行；运行账户需要目标表的读写权限。目标表不参与 `fetch_data.py` 的采集覆盖。
+
+浏览器旧目标不会自动覆盖数据库。在原访问地址打开“阅读目标”，点击“导入已有目标”；数据库已有同一 ID 时跳过，整批成功才标记导入完成。`weread-goals-v2` 原数据保留，`weread-goals-v2-imported` 只记录已导入。不同浏览器、域名和端口的旧存储需要分别在原地址导入。
+
+保存失败会保留表单并提示重试；读取失败显示错误和重试按钮，不冒充空列表。若新建提示 ID 已存在，刷新目标列表确认上次请求是否已经保存。数据库不可用或尚未执行迁移时，目标接口返回 503，不退回浏览器保存。
+
+验证命令：
+
+```sh
+python3 -m unittest discover -s tests -p 'test_reading_goals*.py' -v
+node --test tests/goals_frontend.test.cjs
+node --check static/js/app.js
+node --check static/js/weapi.js
+```
+
+真实数据库验证需先执行迁移，再显式运行 `WEREAD_TEST_MYSQL=1 python3 -m unittest discover -s tests -p 'test_reading_goals_mysql.py' -v`。测试创建唯一测试目标并清理，只操作本次生成的 ID。
+
+本次样式收紧覆盖正式看板的概览、书架和阅读目标页。顶栏、标题区、筛选区、统计卡、书架网格、右侧目标摘要、目标介绍区和目标卡片均使用覆盖规则压缩占位；书架在窄屏固定两列，避免横向溢出。本地真实数据验收覆盖 1280 px 桌面和 390 px 手机宽度：桌面顶栏 58 px，统计卡从约 200 px 开始，书架一行 7 本，目标页介绍区约 67 px 高，目标卡约 317 px 宽；手机顶栏 56 px，书架两列，目标卡约 298 px 宽，概览、书架和目标页均未出现横向溢出。
+
+本次数据库验收已在 8080 正式看板完成：页面新建目标后刷新仍可读取，编辑后再次刷新仍可读取，并已清理临时验收目标。读取目标列表未完成时，新建和编辑入口只显示目标页的加载或错误状态，不会打开保存表单。