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」。