diff --git a/docs/LFReader-构想与调研.md b/docs/LFReader-构想与调研.md new file mode 100644 index 0000000..7eb7e94 --- /dev/null +++ b/docs/LFReader-构想与调研.md @@ -0,0 +1,382 @@ +# LFReader · 构想与调研记录 + +> 状态:草案 v0.3 | 更新:2026-10-28 | 范围:个人自用,不对外分发 +> 命名:项目名 **LFReader**。首期唯一上游是番茄小说,但产品、接口与数据模型都不绑定单一来源(见 4.3)。 + +--- + +## 1. 目标 + +### 1.1 硬约束 + +| 约束 | 说明 | +|---|---| +| 墨水屏优先 | 手机、平板、墨水屏三端都要能用;墨水屏不是“顺便支持”,而是主要使用场景 | +| 目标机型 | 主用掌阅 Tango2(6.13" / 1648×842 / 300ppi / SmartOS);手机、平板为辅助端 | +| 段评只读 | 书评、章评、段评都要能看,但不点赞、不发评论、不写任何内容 | +| 自己的账号 | 使用本人番茄账号登录,可开通 VIP;不为“免付费”做任何绕过 | +| 自建服务 | NAS 上跑一个 Docker 个人书库服务,作为唯一上游出口与缓存中心 | +| 官方书架同步 | 只读拉取番茄官方书架/进度,本地书架为准,不回写 | + +### 1.2 产品形态 + +``` +Android 阅读客户端(手机 / 平板 / 墨水屏) + ↕ 内网 / Tailscale(外出时经 Cloudflare Tunnel 或 frp,TLS + 固定 Token) +NAS 上的 LFReader 服务端(Docker:账号会话 + 取数 + 缓存 + 书库 + 导出) + ↕ +番茄官方账号与内容接口 +``` + +### 1.3 使用环境 + +- **客户端**:主用掌阅 Tango2(墨水屏,掌阅 SmartOS,支持安装第三方应用);手机/平板用于碎片阅读与调试。 +- **服务端**:NAS 上的 Docker 容器,日常只走内网;外出阅读经 Cloudflare Tunnel 或 frp 访问,入口用**启动时注入的固定 Token** 鉴权。 +- **预期而非需求**:翻页水波纹等动效。这类效果由设备刷新策略或阅读器自身实现决定,第三方应用未必可控,不作为验收项。 + +### 1.4 明确不做 + +- 不做付费章节破解、设备权益伪造、代理池、批量注册。 +- 不做公开下载站、共享书库、资源分发。 +- 不做评论/点赞/刷时长等任何写操作。 +- 首期不接番茄以外的**实际书源**;但接口与数据模型必须为多源预留(见 4.3)。 + +--- + +## 2. 结论先行 + +1. **客户端用 Flutter**,一套代码覆盖手机/平板/墨水屏;墨水屏刷新优先接厂商插件,掌阅若不开放则退化为“零动画 + 系统快刷档”(见 §7)。Tauri 2 因为依赖系统 WebView,残影与老设备兼容性不可控,不作为主选。若只锁定少数机型,Kotlin + Compose 是更稳的备选。 +2. **服务端用 Rust(axum + SQLite)**,单容器、单二进制、镜像小,签名与协议实现方便做黄金向量测试;Go 是最省心的备选。 +3. **取数依靠“自己的账号 + VIP”解决授权问题,签名与设备身份解决传输问题**,两者独立。段评只有 App 通道有完整数据,是必须保留的一环。 +4. **同步只做单向拉取**:官方书架 → 本地书库;本地进度不回写,避免以账号身份产生写行为。 +5. **真正的可靠性来自“多源回退 + 整本缓存 + 服务端集中限速”**,而不是某一个接口的稳定性。 +6. **找书四件事(搜索 / 推荐 / 榜单 / 分类)都能取到**,但除头条搜索外几乎都落在 App 通道 → 设备身份是**长期维护成本**,不是一次性搭建成本。 +7. **多源是架构要求,不是首期功能**:源适配器与内部 ID 映射现在就留好,将来加第二源不用改客户端。 +8. **部署以“内网为常态、外网为附加”**:Cloudflare Tunnel / frp 只做通道,鉴权靠固定 Token,公网只开放只读面。 + +--- + +## 3. 现状调研(首期源:番茄小说) + +### 3.1 fqapp(什锦铺) + +- 形态:Flutter UI + 进程内 Rust 核心(`libfqapi_core.so`),无自建服务器,GPL-3.0。 +- 取数:番茄 App 端接口(`aid=1967`)+ 虚拟设备池 + Argus551/Ladon 签名 + 设备 `secret_key` 解密;另开 `127.0.0.1:18921` 的 loopback 供 Legado 等外部阅读器调用。 +- 覆盖:搜书、目录、正文、书评、段评、插图、听书、短剧、漫画,最全。 +- 可借鉴:段评接口与解密链路的协议参考;`/api/v1/*` 的归一化设计;Rust 核心的签名/设备分层。 +- 不建议照搬:设备池轮换、给虚拟设备发 30 天权益那一套(滥用风险最高、最易被封),以及它整体偏重的实现。 + +### 3.2 POf-L/Fanqie-novel-Downloader + +- 形态:Tauri 系跨平台打包(发布脚本含 `cargo-tauri`),Windows/macOS/Linux/Android/iOS;**应用源码未公开**,仓库只放 Issue 表单、发布脚本与文档。 +- 功能:搜书、TXT/EPUB 下载、阅读器、**段评浏览**、**番茄官方书架登录后同步**、漫画/短剧、本地书导入、`fanqie serve`(本机/局域网服务)。 +- 产品边界(写在 CONTRIBUTING 里,值得直接照抄): + - 不解锁付费、会员或未上架内容,只读“接口本来就返回给当前账号或游客”的内容; + - 不对抗风控:限速、熔断、冷却;设备轮换默认关闭; + - 不做公开下载服务、共享书库;`serve` 只用于本机或自己的局域网; + - 不自建账号体系、不运营云同步;书架只走番茄官方; + - 不写评论、不点赞、不刷时长;只读段评保留; + - 只做番茄系,不做通用书源。 +- 对本案的价值:**它已经验证了“自有账号 + 只读段评 + 官方书架 + 本地服务”这条产品路线是可行的**;同时说明 Tauri 能跑 Android,但解决不了墨水屏(残影、老 WebView、无 EPD 控制)。 + +### 3.3 其他参考项目 + +| 项目 | 技术 | 取数方式 | 可参考点 | 局限 | +|---|---|---|---|---| +| `h13637404183-hub/fanqie-api` | Python/Flask,Docker | 番茄 PC 网页 API + HTML 解析 | REST 设计、Docker 部署、详情/目录/正文的网页通道 | 无评论;搜索需移动端签名,直接用网页通道做不了 | +| `denniemok/fanqie-novel-reader` | React PWA | 自建代理 + 多个第三方 API 镜像 | 阅读器 UI、PWA 离线、繁简转换、API 健康监控 | 后端代理不公开,依赖镜像,随时失效 | +| `shing-yu/fanqie-novel-download` | Python | 早期网页抓取 | 正文 DOM 与字符映射处理 | 维护停滞,接口已变 | +| `youshen2/Sine-NovelDownloader` | - | 第三方“鲸落 API” | 多源切换思路 | 依赖第三方服务 | +| `legado`(阅读)书源生态 | Kotlin | 规则化书源 | 书源规则与章节缓存模型 | 番茄源质量参差,评论基本没有 | + +### 3.4 三条取数通道对比 + +| 通道 | 覆盖 | 稳定性 | 账号依赖 | 结论 | +|---|---|---|---|---| +| A. 头条小说通道(`aid=13`):`api.fanqiesdk.com` 搜索、`novel.snssdk.com` 目录/正文 | 搜书/目录/正文 | 中 | 弱(device/openudid;正文需 DH 解密) | **正文主力**,实现成本最低 | +| B. 网页端 `fanqienovel.com` | 搜书/目录/正文/书评 | 中 | 中(`a_bogus`、`msToken`、字体映射、风控) | 兜底与详情补充;搜索覆盖有限 | +| C. App 端(`aid=1967`) | 全,含**段评**、插图 | 低-中 | 强(设备 + 签名 + `secret_key`) | **只为段评和缺失章节保留** | + +关键判断:**A 和 B 都拿不到完整的段评**。段评是硬需求,所以 C 无法完全去掉;但可以把 C 的使用范围压到“只读评论 + 兜底正文”,账号用本人 VIP,不做设备池。 + +### 3.5 账号与 VIP 能解决什么 + +| 能解决 | 不能解决 | +|---|---| +| 付费/VIP 章节的访问授权(自己付费) | 反爬签名(`a_bogus` / Argus / Ladon) | +| 官方书架、阅读进度、分组 | 设备绑定与会话风控 | +| 降低“虚拟设备领权益”这类高风险做法 | 段评数据仍只在 App 通道 | +| 让整条链路在道义与版权上更站得住 | 上游接口变更后的维护成本 | + +一句话:**账号是授权层,签名是传输层,两者不能互相替代。** + +### 3.6 找书能力盘点(搜索 / 推荐 / 榜单 / 分类) + +| 能力 | 上游端点 | 通道 | 可得性 | 备注 | +|---|---|---|---|---| +| 搜书(主) | `/reading/bookapi/search/tab/v` | C | 高 | 支持 `tab_type` 与翻页;登录态下结果更全 | +| 搜书(轻签名) | `api.fanqiesdk.com/.../search/v1` | A | 高 | `aid=13`,签名要求最低,适合作主力或回退 | +| 搜索联想 | `search_predict` | A/C | 高 | 输入补全,非必需 | +| 热搜 / 搜索落地页 | `/reading/bookapi/plan/v`(`scene=10`) | C | 高 | 返回 `search_tag_data` 聚合,可当“热门搜索” | +| 推荐流(书城首页) | `/reading/bookapi/bookmall/tab/v` | C | 中 | 按 `tab_index` 返回 `cell_data[]`,`offset` 翻页;是运营位而非个性流 | +| 频道表 | 同端点,带 `tab_type` / `last_tab_type` | C | 中 | `tab_item[]` 的 `title` / `tab_type` 即频道条,服务端配置驱动 | +| 榜单 | `rank_data`(`cell_id = rank_id`) | C | 中 | 参数含 `genre_tab`、`rank_sub_info_id`、`offset`;榜单名集合见 `main_algo_name`(推荐/完本/新书/书友/追更/黑马/巅峰/书荒/礼物/阅读/作者榜) | +| 分类页 | `/reading/bookapi/new_category/front/v` | C | 高 | 男频/女频 + 分类瓦片,一次返回整页 | +| 书籍详情 | 详情/分享类端点 | A/B/C | 高 | 三通道都有,按可用性挑 | +| 书评 | `book_reviews` / `idea_list` | C | 高 | 与段评同族接口 | + +结论: + +1. **四件事全部可得**,形态统一为“服务端聚合 → 客户端只读列表”,不需要客户端自己拼接口。 +2. 除头条搜索外几乎全在 App 通道(`aid=1967` + 设备签名)。所以“去掉设备身份、只留网页通道”会在**找书上**明显退化:网页端搜索覆盖窄,推荐/榜单/分类基本没有。 +3. 榜单的 `rank_id` 不是稳定常量表,通常要从推荐流的 `cell_data` 里取 → 服务端必须缓存一份“榜单目录”,否则客户端无法自己拼(列入 §11 待验证)。 +4. 推荐流是**运营位**,字段随版本变动概率高,客户端要把“区块解析失败”做成静默降级,而不是报错。 + +--- + +## 4. 目标架构 + +```mermaid +flowchart LR + subgraph Clients["LFReader 客户端"] + E[墨水屏设备] + P[手机 / 平板] + end + + subgraph NAS["LFReader 服务端(NAS)"] + API[REST / OPDS] + CORE[源适配层
限速 · 重试 · 熔断] + ACC[账号会话
Cookie / 设备身份] + DB[(SQLite + 书库文件)] + EXP[EPUB / TXT 导出] + end + + F[番茄官方接口
书架 / 目录 / 正文 / 段评] + + E -->|内网 / Tailscale| API + P -->|内网 / Tailscale| API + E -.->|外出| T["Cloudflare Tunnel / frp
TLS + 固定 Token"] + T -.-> API + API --> CORE + CORE --> ACC + CORE --> DB + CORE --> F + F --> CORE + ACC -->|只读拉取| F + DB --> EXP + EXP --> API +``` + +### 4.1 NAS 服务职责 + +1. 保存账号 Cookie 与设备身份(加密存储),维持会话,过期时提示重新登录。 +2. 集中做签名、限速、重试、熔断——客户端永远不直接访问上游。 +3. 搜书、详情、目录、正文、书评/段评的归一化与缓存。 +4. 书库存储:整本正文、评论快照、封面、EPUB/TXT 导出。 +5. 书架同步:只读拉取官方书架与进度,合并到本地书库。 +6. 对外只暴露 REST + OPDS;内网直连,外网经 Cloudflare Tunnel / frp 转发,入口固定 Token 鉴权(见 6.4),不做路由器端口映射。 + +### 4.2 客户端职责 + +1. 只做 UI 与本地阅读:分页、主题、字体、离线包管理。 +2. 从 NAS 下载“整本包”(元数据 + 目录 + 已缓存章节 + 评论快照),断网可读。 +3. 阅读进度本地保存,可选上报给 NAS;不回写官方。 +4. 墨水屏专项:全刷策略、无动画、按键翻页、低内存。 + +### 4.3 多源预留(当前只做番茄,但不做死) + +原则:**能力接口化、源实现可插拔、内部 ID 与外部 ID 解耦。** + +1. 统一领域模型:Book / Chapter / Comment 只存在于内部;源特有字段一律进 `raw_json`,不污染主表。 +2. 源适配器契约(每个源实现同一组方法,缺的能力显式返回 `Unsupported`): + `search(q, page)`、`detail(ext_id)`、`catalog(ext_id)`、`chapter(ext_id)`、`book_comments(ext_id)`、`paragraph_comments(chapter_ext_id)`、`shelf()`、`progress()`。 +3. 能力矩阵:每个源声明 `capabilities {search, recommend, rank, category, comments, paragraph_comments, shelf}`;客户端据此隐藏 UI,而不是“调用后才发现没有”。 +4. ID 解耦:内部 `books.id` 用 ULID;`book_sources(book_id, source, ext_id, is_primary)` 承担映射,一本书可挂多个源。 +5. 结构归一:卷/章统一映射为 `(volume, idx)`;正文用内容 hash 做跨源去重,为将来“换源续读”留位。 +6. 选源策略:未指定源时按 `sources.priority` + `health` 选择;`?source=` 可强制指定,仅用于调试。 +7. 客户端完全不感知源:只调 `/api/v1/*`,换源发生在服务端。 + +### 4.4 客户端信息架构 + +| 入口 | 内容 | 数据来源 | 首期 | +|---|---|---|---| +| 书架 | 本地书架为主,可叠加官方书架只读副本;分组、最近阅读、更新提示 | `shelf` + `/sync/shelf` | 必需 | +| 发现 | 推荐区块、榜单入口、分类入口 | `/discover`、`/rank/{id}`、`/categories` | 必需(可先只做榜单 + 分类) | +| 搜索 | 输入联想 + 热搜 + 结果列表(多通道合并去重) | `/search`、`/search/suggest`、`/search/hot` | 必需 | +| 阅读 | 目录、正文、段评/章评/书评、进度、离线包 | `/catalog`、`/chapters`、`/comments` | 必需 | +| 设置 | 服务地址 + Token、字体与翻页刷新策略、缓存管理、账号状态 | 本地 + `/healthz` | 必需 | + +设计原则: + +- 不照搬官方书城的“无限运营位 + 视频/短剧混排”,只保留书籍形态,非书籍区块整块跳过。 +- 发现页做成**可配置区块列表**:区块类型(榜单 / 分类格 / 横滑书单)由服务端下发,客户端只实现 5-6 种基础类型。 +- 书架是首页,找书是第二入口;不为“像官方 App”牺牲墨水屏的信息密度与翻页速度。 +- 推荐流字段易变,解析失败时静默降级为“榜单 + 分类”,不向用户报错。 + +--- + +## 5. 技术选型 + +### 5.1 客户端(墨水屏权重最高) + +| 方案 | 墨水屏适配 | 三端一致性 | 生态/成本 | 主要风险 | 结论 | +|---|---|---|---|---|---| +| **Flutter** | 好:自绘渲染 + 原生插件调 EPD SDK | 高 | 成熟,招人/查资料容易 | 需按厂商写刷新插件 | **推荐** | +| Kotlin + Compose | 最好:直接调厂商 SDK | 中:一套 UI 自适应 | 成熟 | Compose 动画/内存需专门处理;老设备性能吃紧 | 备选(只锁定少数机型) | +| Kotlin + 自定义 View | 最好 | 低 | 工作量大 | 无现成组件 | 不考虑 | +| Tauri 2 | 差:系统 WebView 残影、老版本 WebView | 高 | Web 前端复用 | 墨水屏体验不可控 | 不推荐 | +| Rust + Slint / egui | 中:软件渲染省电 | 低 | 早期 | 中文排版、分页、输入法成本高 | 观察 | + +选 Flutter 的核心理由:墨水屏需要“完全可控的文字排版 + 可插拔的刷新策略”,Flutter 两端都能满足,且 fqapp 已经证明这条路在 Android 上走得通。 + +### 5.2 服务端 + +| 方案 | 镜像/部署 | 开发效率 | 协议实现 | 结论 | +|---|---|---|---|---| +| **Rust(axum + sqlx + SQLite)** | 单二进制,镜像小 | 中 | 签名/解密移植最合适,可做黄金向量测试 | **推荐** | +| Go | 单二进制,最省心 | 高 | 足够 | 备选 | +| Python(FastAPI) | 镜像较大 | 高(参考实现多) | 快速验证协议 | 适合 M0 验证 | +| Node/TS | 镜像大、常驻内存高 | 高 | 一般 | 不优先 | + +--- + +## 6. 数据与接口草案 + +### 6.1 数据表(SQLite) + +| 表 | 关键字段 | 说明 | +|---|---|---| +| `books` | id, title, author, cover, status, word_count, score, updated_at, raw_json | 详情快照 | +| `chapters` | id, book_id, idx, volume, title, word_count, is_vip, fetched_at | 目录 | +| `contents` | chapter_id, text, format, source, hash, fetched_at | 正文,按章缓存 | +| `comments` | id, book_id, chapter_id, para_index, user, content, like_count, created_at, scope | 书评/章评/段评 | +| `shelf` | book_id, added_at, last_chapter, progress, source | 本地书架 | +| `accounts` | id, cookie_enc, device_id, install_id, secret_key_enc, expires_at | 账号与会话(加密) | +| `sources` | name, enabled, priority, health, last_error | 源健康状态 | +| `book_sources` | book_id, source, ext_id, is_primary | 内部 ID ↔ 源 ID 映射(多源预留) | +| `discover_cache` | source, kind, payload, fetched_at | 推荐/榜单/分类的区块快照 | + +### 6.2 REST 草案 + +``` +GET /api/v1/discover?source= # 发现页聚合:榜单入口 + 分类入口 + 推荐区块(可降级) +GET /api/v1/rank/{rankId}?page= +GET /api/v1/categories?tab= +GET /api/v1/search?q=&type=&source= +GET /api/v1/search/suggest?q= +GET /api/v1/search/hot +GET /api/v1/books/{id} +GET /api/v1/books/{id}/catalog +GET /api/v1/books/{id}/comments?scope=book|chapter|paragraph +GET /api/v1/chapters/{id}?include=comments +GET /api/v1/shelf +POST /api/v1/sync/shelf # 触发只读拉取 +GET /api/v1/offline/{bookId} # 整本离线包 +GET /api/v1/export/{bookId}.epub +GET /opds +GET /healthz +``` + +鉴权:固定 Bearer Token(容器启动时注入),详见 6.4。 + +### 6.3 同步语义 + +- 官方书架 → 本地:只新增/更新元数据,不删除本地书。 +- 官方进度 → 本地:只读取展示,不覆盖本地更靠后的进度。 +- 本地 → 官方:**不回写**。若确实需要“加入官方书架”,做成显式手动动作并二次确认。 + +### 6.4 公网访问与鉴权 + +- **通道**:容器只监听内网;外出统一走 Cloudflare Tunnel 或 frp,不在路由器上做端口映射。 +- **Token**:首次启动生成固定 token(或从环境变量 `LFREADER_TOKEN` 注入),写入 `.env`,不落日志、不回显。 + - 客户端用 `Authorization: Bearer `;不支持自定义头的 OPDS 客户端允许 `?token=`(仅 TLS 下)。 + - 比较用常量时间;失败计数 + 短时封禁,避免被扫描。 +- **传输**:Tunnel / frp 侧必须 TLS,容器内不做明文公网监听。 +- **暴露面分级**: + - 公网可访问:搜索、发现、详情、目录、正文、评论、离线包、OPDS(全部只读)。 + - 仅内网 / VPN:账号登录与会话管理、同步触发、导出、配置与健康详情。 +- **反代细节**:Tunnel 取 `CF-Connecting-IP` 做限速维度;frp 需 `X-Forwarded-For`。`/healthz` 公网只返回状态码,不泄露版本与配置。 +- **客户端配置项**:一个「服务地址」+「Token」两个字段即可完成接入,避免多套配置分散。 + +--- + +## 7. 墨水屏专项清单 + +- [ ] 翻页后全刷,菜单/光标用局部刷新,避免残影累积。 +- [ ] 分页结果按“字体 + 字号 + 屏宽”预计算并持久化,重开秒进。 +- [ ] 内置可读性好的中文字体,避免不同设备系统字体差异。 +- [ ] 关闭所有动画、阴影、半透明、滚动惯性。 +- [ ] 支持音量键/蓝牙翻页器;点击区域大且可配置。 +- [ ] 纯离线包阅读,禁止后台轮询,降低耗电。 +- [ ] 主用机型 **掌阅 Tango2**(6.13" / 1648×842 / 300ppi,掌阅 SmartOS):实机确认第三方 APK 安装路径、后台保活、系统“快刷”档位能否被应用影响。 +- [ ] 确认掌阅是否向第三方应用开放 EPD / 刷新接口;若不开放,退化为“零动画 + 系统快刷档 + 整页刷新”,并把该限制写进 M4 验收说明。 +- [ ] 在 Tango2 上对比 Flutter 自绘与 WebView 的残影/闪烁差异(这是拒绝 Tauri 的实证依据)。 +- [ ] 动效定位:**不做水波纹 / 仿真翻页**,只提供“无动画切换 + 可选整页刷新”;系统或官方阅读器的动效不在控制范围内(见 1.3)。 +- [ ] 分页按 1648×842 / 300ppi 校准,手机与平板沿用同一算法换参数。 +- [ ] 性能门槛:冷启动 < 3s、翻页 < 300ms、内存峰值 < 200MB、连续翻页 50 次无明显残影。 + +--- + +## 8. 可靠性工程 + +1. **源适配层**:每个通道实现同一组能力(搜索/详情/目录/正文/评论),带 health 标记,按优先级回退。 +2. **缓存优先**:正文按章不可变;目录 TTL;评论快照 TTL;失败时返回旧缓存并标注时间。 +3. **限速**:全局令牌桶 + 随机抖动 + 指数退避;服务端统一控制,客户端不直连。 +4. **签名隔离**:签名/设备身份独立成模块,配黄金向量测试;上游变更只改一处。 +5. **契约测试**:录制真实响应做 fixture,字段变更时先失败再修。 +6. **配置化**:端点版本、超时、限速参数放配置文件,容器更新即可调整,无需发 APK。 +7. **备份**:SQLite 定时快照 + EPUB 导出,防止账号或上游异常导致内容不可用。 + +--- + +## 9. 风险与边界 + +| 风险 | 应对 | +|---|---| +| 账号被风控/封禁 | 只用本人账号、低频、只读;保留 EPUB 导出作为兜底 | +| 上游接口变更 | 多源回退 + 服务端集中升级;不把逻辑写死在客户端 | +| 版权与平台条款 | 个人自用、局域网、不传播、不公开服务 | +| 代码许可 | fqapp 为 GPL-3.0,直接移植会继承许可;POf-L 未标注许可证且源码未公开,只能参考产品行为 | +| NAS 单点故障 | 定期备份;客户端保留完整离线包,短时断服可读 | + +--- + +## 10. 里程碑 + +| 阶段 | 内容 | 验收标准 | +|---|---|---| +| M0 协议验证 | 验证 6 个能力:搜索、榜单、分类、目录、正文、段评;确认本人账号下 VIP 章可读、书架可拉 | 每个能力有可复现的请求与响应;确认段评分页方式、榜单 `rank_id` 来源、推荐流字段结构 | +| M1 服务端闭环 | Rust/Go 服务 + SQLite + 限速 + 缓存 + Docker Compose | 核心接口可用(搜索、发现、目录、正文、段评),重启不丢缓存,限速与 Token 鉴权生效 | +| M2 客户端 MVP | Flutter 阅读器:书架、找书(搜索 / 榜单 / 分类,推荐可后置)、详情、目录、正文、离线包 | 手机/平板上完整读一本书,断网可继续;找书入口可用 | +| M3 段评与同步 | 段评气泡/侧栏;官方书架只读同步 | 段评按段落定位准确;同步不产生任何写请求 | +| M4 墨水屏适配 | EPD 刷新插件、字体、按键、机型验证 | 通过第 7 节性能与残影门槛 | +| M5 稳定性 | 多源回退、监控、自动更新、备份 | 单源故障时阅读不中断;容器可一键升级 | + +--- + +## 11. 待验证问题 + +1. 本人账号的 Cookie 能否直接调用 App 端段评接口,还是必须绑定设备身份? +2. VIP 章节在自有账号下取回的正文是否仍为设备密钥加密?密钥与账号还是与设备绑定? +3. 官方书架/进度的拉取频率上限,以及字段是否包含分组与排序? +4. 段评是否支持按章节批量拉取,还是必须逐段/逐章请求? +5. Tango2 实机的中文渲染表现(字形、行距、灰度层次),据此决定是否内置字体。 +6. 是否需要听书/短剧(建议先不做,控制范围)。 +7. 离线包格式:自定义 JSON 包还是直接 EPUB + 旁挂评论数据库? +8. 掌阅 Tango2 是否向第三方应用开放 EPD / 刷新接口;不开放时,系统的快刷档位能否被应用指定。 +9. 榜单 `rank_id` 的稳定来源(推荐流 `cell_data` 还是固定常量表),以及各榜单的分页上限与刷新频率。 +10. 推荐流 / 分类页的 schema 波动幅度,是否需要服务端做字段兼容层。 +11. Cloudflare Tunnel 下主流 OPDS 客户端(静读天下 / KOReader / Thorium)能否带自定义 Header 或 query token。 +12. 同一本书在 App / 头条 / 网页三通道的 ID 是否可直接互转(决定多源 ID 映射与“换源续读”的可行性)。 + +--- + +## 12. 参考链接 + +- [ch6vip/fqapp](https://github.com/ch6vip/fqapp) — Flutter + Rust 的番茄聚合客户端,GPL-3.0 +- [POf-L/Fanqie-novel-Downloader](https://github.com/POf-L/Fanqie-novel-Downloader) — 跨平台下载/阅读器,段评与官方书架同步,`fanqie serve` +- [h13637404183-hub/fanqie-api](https://github.com/h13637404183-hub/fanqie-api) — 网页通道的 Flask 封装,Docker 部署 +- [denniemok/fanqie-novel-reader](https://github.com/denniemok/fanqie-novel-reader) — React PWA 阅读器,多镜像与健康监控 +- [shing-yu/fanqie-novel-download](https://github.com/shing-yu/fanqie-novel-download) — 早期 Python 实现 +- [youshen2/Sine-NovelDownloader](https://github.com/youshen2/Sine-NovelDownloader) — 第三方 API 接入示例 +- [legado(阅读)](https://github.com/gedoor/legado) — 书源规则与本地阅读模型参考