Files
SakuraHub/docs/在线搜索-书本章节导航-完整解决方案.md
T

1222 lines
44 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 在线搜索错误修复 与 书→目录→章节 导航流程 — 完整解决方案
> 分析日期:2026-06-21
> 参考项目:[legado-with-MD3](https://github.com/HapeLee/legado-with-MD3)
> 涉及范围:Sakura Mobile (Flutter)
> 说明:本文档提供完整的问题分析与解决方案设计,不包含实际代码改动。
---
## 目录
1. [总体结论](#一总体结论)
2. [问题诊断](#二问题诊断)
3. [P0:必须优先修改](#三p0必须优先修改)
4. [P1:第二阶段修改](#四p1第二阶段修改)
5. [P2:后续增强](#五p2后续增强)
6. [优先级总表](#六优先级总表)
7. [页面与数据流设计](#七页面与数据流设计)
8. [数据模型扩展](#八数据模型扩展)
9. [Legado 书源规则字段对照](#九legado-书源规则字段对照)
10. [附录:关键文件清单](#十附录关键文件清单)
---
## 一、总体结论
**不要只修 UI,也不要只做错误提示兜底。**
真正应该改成的完整流程是:
```
搜索页 (ExplorePage)
↓
在线书籍详情页 (OnlineBookDetailPage) ← 合并 BookInfo + TOC 的 UI
├─ 书籍信息(封面、书名、作者、来源、简介)
├─ 章节列表(内嵌加载,不跳独立 TOC 页)
│ ├─ 分页加载
│ └─ 正序/倒序切换
└─ 快捷操作:「从第一章开始阅读」「保存到书架」
↓
阅读器 (OnlineMangaReaderPage / OnlineNovelReaderPage)
├─ 章节驱动(非 URL 驱动)
├─ 上一章 / 下一章 导航
├─ 下一章预加载
└─ 阅读记录
```
核心理念:
```
页面合并,解析分层;
缓存前置,持久化后置;
目录回退要识别章节,不要盲扫链接;
阅读器必须从 URL 驱动改成章节驱动。
```
---
## 二、问题诊断
### 2.1 问题一:搜索结果显示 `unknown:none`
#### 现象
用户在 APP 在线搜索漫画/小说时,搜索结果中某些条目显示为 `unknown:none`。
#### 根因
**位置**:`sakura_mobile/lib/src/core/legado_engine.dart:563-569`
```dart
var message = error
.toString()
.replaceFirst(RegExp(r'^(Exception|StateError):\s*'), '');
if (message.trim() == '[unknown]: null' || message.trim() == 'null') {
message = 'Target site returned an empty or invalid response.';
}
```
当前只匹配了 `[unknown]: null` 和 `null`,但 Dio 在不同平台、不同错误类型下会抛出多种格式的底层异常消息:
| 平台/场景 | 可能的错误消息 | 是否处理 |
|-----------|---------------|----------|
| Android | `[unknown]: null` | ✅ 已匹配 |
| Android | `[unknown]: none` | ❌ **漏掉,原样展示** |
| iOS | `Connection failed: unknown:none` | ❌ 漏掉 |
| Windows 桌面 | `DioException [unknown]: null` | ❌ 部分匹配失败 |
| 超时 | `Connection timed out` | ❌ 漏掉 |
| DNS 失败 | `No address associated with hostname` | ❌ 漏掉 |
| 编码错误 | `FormatException: Bad UTF-8 encoding` | ❌ 走 FormatException 分支,不友好 |
这些未处理的错误消息被原样透传到 `SearchItem.errorMessage`,最终在 UI 的 subtitle 中展示为 `源名称 - unknown:none`。
#### 搜索结果字段提取失败的连锁反应
**位置**:`legado_engine.dart:60-98`
当书源的解析规则与目标网站 HTML 结构不匹配时:
- `title` 为空 → 该结果被 `.where()` 过滤掉 → 整个源的搜索结果为空
- `author` 为空 → subtitle 中显示为 null
- `detailUrl` 为空 → 点击后 URL 为空 → 报错
---
### 2.2 问题二:缺少「书→目录→章节」导航流程
#### 现象
用户搜索到一本书后,点击结果**直接进入阅读器**,而不是进入书籍详情页。结果是:
1. 阅读器把书籍详情页 HTML 当正文展示 → 乱码/空白/无关图片
2. 用户看不到章节列表,无法选择具体章节阅读
#### 根因一:数据模型缺少三个关键规则模块
**位置**:`sakura_mobile/lib/src/core/legado_models.dart:21-86`
当前 `LegadoSource` 只包含搜索相关的规则字段:
```
searchUrl, searchListRule, searchNameRule, searchAuthorRule,
searchCoverRule, searchDetailRule, searchMethod, searchBody
```
完全缺失 Legado 标准书源中的三个关键规则模块:
| 模块 | 作用 | 关键字段 |
|------|------|---------|
| `ruleBookInfo` | 解析书籍详情页 → 得到元数据 + 目录 URL | name, author, cover, intro, **tocUrl** |
| `ruleToc` | 解析目录页 → 得到章节列表 | chapterList, chapterName, chapterUrl |
| `ruleContent` | 解析章节页 → 得到正文/图片 | content, nextChapterUrl, prevChapterUrl |
这三个模块是 Legado 生态的标准配置,被数千个书源规则所遵循。当前项目只实现了其中的搜索模块。
#### 根因二:搜索结果点击逻辑错误
**位置**:`sakura_mobile/lib/src/pages/explore_page.dart:174-228` (`_openItem` 方法)
```dart
// 在线结果 → 直接打开阅读器(❌ 错误!)
if (mode == UnifiedSearchMode.manga) {
Navigator.of(context).push(MaterialPageRoute(
builder: (_) => OnlineMangaReaderPage(
source: source, title: item.title,
detailUrl: item.detailUrl ?? item.coverUrl ?? '', // ← 书籍详情页 URL!
),
));
}
```
`detailUrl` 在 Legado 规则中的语义是**书籍详情页 URL**,不是章节内容 URL。这个 URL 指向的页面包含封面、书名、作者、简介、章节目录链接——唯独没有章节正文。
将此 URL 直接传入阅读器,阅读器会:
- 漫画:调用 `fetchImageUrls()` → 提取详情页所有 `<img>` → 返回封面 + 广告图 + 导航图标
- 小说:调用 `fetchPlainText()` → 提取详情页纯文本 → 返回简介混合着页面导航文字
#### 根因三:阅读器缺少章节概念
两个在线阅读器都接收单一的 `detailUrl` 参数,没有:
- 章节列表
- 上一章/下一章导航
- 阅读进度记录
---
## 三、P0:必须优先修改
> 这些是当前问题的直接根因,需要最先实施。
### 1. 修复 `unknown:none` 错误展示
**修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` → `_shortError()` 方法
**目标**:将所有 Dio 底层异常消息逐一映射为用户可读的中文提示,不再有原始异常消息泄漏到 UI。
**错误消息映射表**:
```
[unknown]: null → 目标站点返回了空响应,请检查书源是否仍然有效
[unknown]: none → 目标站点连接失败,请检查网络或更换书源
unknown:none → 连接异常,书源可能已失效
Connection refused → 目标站点拒绝了连接,可能需要 Cookie 或反爬处理
Connection timed out → 连接超时,请稍后重试
No address associated → 无法解析目标站点域名,请检查网络
Bad UTF-8 encoding → 响应编码异常,请检查书源的 charset 配置
null → 目标站点返回了无效响应
```
**实现思路**:
```dart
String _shortError(Object error) {
// 1. Dio 网络异常 — 按错误类型精准映射
if (error is DioException) {
final host = error.requestOptions.uri.host;
final target = host.isEmpty ? '目标站点' : host;
switch (error.type) {
case DioExceptionType.connectionTimeout:
case DioExceptionType.receiveTimeout:
case DioExceptionType.sendTimeout:
return '连接 $target 超时,请稍后重试。';
case DioExceptionType.connectionError:
return '无法连接 $target,请检查网络或更换书源。';
case DioExceptionType.badResponse:
final code = error.response?.statusCode ?? 0;
if (code == 404) return '书源搜索接口已失效(404)。';
if (code == 403 || code == 444) return '$target 拒绝了访问,可能需要 Cookie 配置。';
return '$target 返回了异常状态(HTTP $code)。';
default:
break;
}
}
// 2. FormatException — 编码/格式问题
if (error is FormatException) {
final msg = error.message.toLowerCase();
if (msg.contains('utf') || msg.contains('encoding'))
return '响应编码异常,请检查书源的 charset 配置。';
return '书源规则期望 JSON 格式,但站点返回了其他内容。';
}
// 3. 原始消息归一化 — 兜底处理所有未分类的异常文本
var message = error
.toString()
.replaceFirst(RegExp(r'^(Exception|StateError|DioException):\s*'), '');
final trimmed = message.trim();
// 按精确度从高到低匹配
if (trimmed == '[unknown]: null' || trimmed == 'null')
return '目标站点返回了空响应,请检查书源是否仍然有效。';
if (trimmed == '[unknown]: none' || trimmed == 'unknown:none')
return '连接异常,书源可能已失效。';
if (trimmed.toLowerCase().contains('connection refused'))
return '目标站点拒绝了连接。';
if (trimmed.toLowerCase().contains('connection timed out'))
return '连接超时,请稍后重试。';
if (trimmed.toLowerCase().contains('no address associated'))
return '无法解析目标站点域名,请检查网络。';
// 4. 兜底截断,避免超长异常堆栈泄漏到 UI
if (message.length > 120) message = '${message.substring(0, 120)}...';
return message.isEmpty ? '未知错误' : message;
}
```
**同时修改 UI 层**(`explore_page.dart::_SearchResultTile`):
- 当 `item.author` 为空时显示"未知作者"而非空白
- 当 `item.isError` 时,subtitle 中的错误消息不应再包含原始异常类名
---
### 2. 扩展 `LegadoSource` 数据模型
**修改位置**:`sakura_mobile/lib/src/core/legado_models.dart`
当前模型只支持搜索规则。需要新增三个规则模块的字段。
**新增字段**:
```dart
class LegadoSource {
// ===== 现有字段(保持不变)=====
final String id;
final String name;
final String url;
final int type; // 0=小说, 2=漫画
final bool enabled;
final String? userAgent;
final Map<String, String> headers;
// ... 现有搜索规则字段 ...
// ===== 🆕 BookInfo 规则(从 ruleBookInfo 解析)=====
final String? bookInfoUrl; // 详情页 URL 模板(可选,默认用搜索结果的 detailUrl)
final String? bookInfoNameRule; // 提取书名(CSS 选择器)
final String? bookInfoAuthorRule; // 提取作者
final String? bookInfoCoverRule; // 提取封面
final String? bookInfoIntroRule; // 提取简介
final String? bookInfoTocRule; // 提取目录页 URL ⭐ 最关键字段
// ===== 🆕 TOC 规则(从 ruleToc 解析)=====
final String? tocUrl; // 目录页 URL 模板(可选,支持 {{page}})
final String? tocListRule; // 提取章节条目列表
final String? tocNameRule; // 提取章节名称
final String? tocUrlRule; // 提取章节链接
final String? tocNextPageRule; // 提取下一页目录的 URL(用于分页)
// ===== 🆕 Content 规则(从 ruleContent 解析)=====
final String? contentRule; // 提取正文/图片内容
final String? contentNextRule; // 提取下一章链接
final String? contentPrevRule; // 提取上一章链接
}
```
**`fromJson()` 中新增的解析逻辑**:
```dart
// 从 ruleBookInfo 提取
final bookInfo = _map(json['ruleBookInfo']);
bookInfoNameRule = _firstString([
bookInfo['name'], bookInfo['bookName'],
]);
bookInfoAuthorRule = _firstString([
bookInfo['author'], bookInfo['bookAuthor'],
]);
bookInfoCoverRule = _firstString([
bookInfo['coverUrl'], bookInfo['cover'],
]);
bookInfoIntroRule = _firstString([
bookInfo['intro'], bookInfo['introduce'], bookInfo['desc'],
]);
bookInfoTocRule = _firstString([
bookInfo['tocUrl'], bookInfo['chapterUrl'],
bookInfo['catalogUrl'], bookInfo['directoryUrl'],
]);
// 从 ruleToc 提取
final toc = _map(json['ruleToc']);
tocListRule = _firstString([
toc['chapterList'], toc['chapters'], toc['list'],
]);
tocNameRule = _firstString([
toc['chapterName'], toc['name'], toc['title'],
]);
tocUrlRule = _firstString([
toc['chapterUrl'], toc['url'], toc['href'],
]);
tocNextPageRule = _firstString([
toc['nextTocUrl'], toc['nextPage'], toc['nextPageUrl'],
]);
// 从 ruleContent 提取
final content = _map(json['ruleContent']);
contentRule = _firstString([
content['content'], content['text'], content['body'],
]);
contentNextRule = _firstString([
content['nextChapterUrl'], content['next'], content['nextPage'],
]);
contentPrevRule = _firstString([
content['prevChapterUrl'], content['prev'], content['prevPage'],
]);
```
**`copyWith` 也需要同步扩展**,确保 `setEnabled()` 等现有方法能正常工作。
---
### 3. 新增在线书籍详情页(合并 BookInfo + TOC UI)
**新增文件**:`sakura_mobile/lib/src/pages/online_book_detail_page.dart`
**关键设计决策**:不要创建独立的 `OnlineTocPage`。将 BookInfo 和章节列表放在**同一个页面**中,但数据加载保持**两次独立请求**(因为很多书源的 `detailUrl ≠ tocUrl`)。
```
┌──────────────────────────────────────┐
│ ← 返回 书籍详情 📤 │ AppBar
├──────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ │ │ 封面图
│ │ 书籍封面 │ │ (CachedNetworkImage)
│ │ │ │
│ └──────────────┘ │
│ │
│ 斗罗大陆 │ 书名(大标题)
│ 唐家三少 · 笔趣阁 · 连载中 │ 作者/来源/状态 一行
│ │
│ ┌──────────────────────────────┐ │
│ │ 简介 │ 简介卡片
│ │ 唐门外门弟子唐三,因偷学内门 │ (可展开/收起)
│ └──────────────────────────────┘ │
│ │
│ ┌──────────────────────────────┐ │
│ │ ▶ 从第一章开始阅读 │ 快捷操作按钮
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ 💾 保存到书架 │ 保存操作
│ └──────────────────────────────┘ │
│ │
│ ──────── 章节目录 (共 336 章) ───── │ 分隔标题
│ [正序 ↑] [倒序 ↓] │ 排序切换
│ │
│ ┌──────────────────────────────────┐│
│ │ 📖 第一章 楔子 ││ 章节条目
│ └──────────────────────────────────┘│
│ ┌──────────────────────────────────┐│
│ │ 📖 第二章 唐三的武魂 ││
│ └──────────────────────────────────┘│
│ ┌──────────────────────────────────┐│
│ │ 📖 第三章 修炼之路 ││
│ └──────────────────────────────────┘│
│ ┌──────────────────────────────────┐│
│ │ ... 更多章节(滚动加载) ││ 支持无限滚动
│ │ 正在加载第2页... ││ TOC 分页指示器
│ └──────────────────────────────────┘│
│ │
└──────────────────────────────────────┘
```
**数据加载方式(分段异步)**:
```
第一步:请求 BookInfo(用 bookInfoRule 解析 detailUrl)
→ 拿到 title, author, cover, intro, tocUrl
→ 立即渲染页面上半部分(封面+书名+作者+简介+快捷按钮)
→ 章节列表区域显示骨架屏 loading
第二步:请求 TOC(用 chapterListRule 解析 tocUrl)
→ 拿到 List<OnlineChapter>
→ 章节列表区域从骨架屏切换为真实数据
→ 如果有 tocNextPageRule,继续加载后续页
两步之间不互相阻塞:BookInfo 失败 → 整个页面显示错误;TOC 失败 → 上半部分正常展示,下半部分显示"目录加载失败,点击重试"
```
**重要**:
```
合并页面 ≠ 合并请求
因为很多书源:
detailUrl (书籍详情页)
≠
tocUrl (章节目录页,可能是独立的分页 URL)
详情和目录必须允许两次独立的 HTTP 请求。
```
---
### 4. 修改搜索结果点击逻辑
**修改位置**:`sakura_mobile/lib/src/pages/explore_page.dart` → `_openItem()` 方法
**当前逻辑(错误)**:
```
点击在线结果 → 直接打开 OnlineMangaReaderPage / OnlineNovelReaderPage
(把 detailUrl 当成章节内容 URL 传给阅读器)
```
**改为**:
```
点击在线结果 → 打开 OnlineBookDetailPage(detailUrl)
→ 用户在详情页看到书籍信息 + 章节列表
→ 点击某个章节 → 打开阅读器(传入章节 URL)
→ 或点击「从第一章开始阅读」→ 自动打开第一个章节
```
```dart
void _openItem(SearchItem item) {
// 云库结果(不变)
if (item.artwork != null) {
Navigator.of(context).push(
MaterialPageRoute(builder: (_) => ArtworkDetailPage(artwork: item.artwork!)),
);
return;
}
if (item.novel != null) {
Navigator.of(context).push(
MaterialPageRoute(builder: (_) => NovelReaderPage(novel: item.novel!)),
);
return;
}
// 在线结果 — 🆕 改为跳转到详情页
final online = item.online;
if (item.isError) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(item.errorMessage ?? '搜索失败,请稍后再试。')),
);
return;
}
if (online == null) return;
final source = ref.read(sourceManagerProvider).sourceById(online.sourceId);
if (source == null) {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(content: Text('书源已不可用。')),
);
return;
}
// 🆕 跳转到在线书籍详情页
Navigator.of(context).push(
MaterialPageRoute(
builder: (_) => OnlineBookDetailPage(
source: source,
initialTitle: item.title,
initialAuthor: item.author,
initialCoverUrl: item.coverUrl,
detailUrl: item.detailUrl ?? '',
mode: mode, // manga 或 novel
),
),
);
}
```
---
### 5. 增加会话级内存缓存
**修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` 或新建独立缓存文件
**第一版用内存缓存即可,不要着急上 Hive/Isar。**
```dart
/// 会话级内存缓存
class OnlineContentCache {
// 存活时间:当次 APP 会话
final _bookInfoCache = <String, OnlineBookInfo>{};
final _tocCache = <String, List<OnlineChapter>>{};
final _chapterCache = <String, OnlineChapterContent>{};
// 缓存 key 规则:source.id + URL
String _key(String sourceId, String url) => '$sourceId|$url';
// BookInfo
OnlineBookInfo? getBookInfo(String sourceId, String url) =>
_bookInfoCache[_key(sourceId, url)];
void putBookInfo(String sourceId, String url, OnlineBookInfo info) =>
_bookInfoCache[_key(sourceId, url)] = info;
// TOC(章节列表)
List<OnlineChapter>? getToc(String sourceId, String tocUrl) =>
_tocCache[_key(sourceId, tocUrl)];
void putToc(String sourceId, String tocUrl, List<OnlineChapter> chapters) =>
_tocCache[_key(sourceId, tocUrl)] = chapters;
// Chapter(单章内容)
OnlineChapterContent? getChapter(String sourceId, String chapterUrl) =>
_chapterCache[_key(sourceId, chapterUrl)];
void putChapter(String sourceId, String chapterUrl, OnlineChapterContent content) =>
_chapterCache[_key(sourceId, chapterUrl)] = content;
// 预加载下一章(阅读器中调用)
void preloadNextChapter(String sourceId, String nextUrl) {
// 由阅读器在后台触发,不阻塞当前阅读
}
void clear() {
_bookInfoCache.clear();
_tocCache.clear();
_chapterCache.clear();
}
}
```
**缓存策略**:
- `BookInfo`:进入详情页时先查缓存,未命中才请求
- `TOC`:目录可能有几百章,每次进页面重新请求既慢也会增加书源站点压力——优先读缓存
- `ChapterContent`:只缓存当前章 + 预加载下一章,不要一口气缓存全部章节正文(容易占内存)
**为什么阶段一不用持久化缓存**:
- 在线书源的内容可能变化(网站改版、章节更新),持久化缓存容易导致过期数据
- 先跑通主流程,确认缓存策略合理后,P2 阶段再引入 Hive/Isar
- 会话级缓存已能覆盖"用户在详情页和阅读器之间来回切换"的核心场景
---
### 6. 章节识别器回退策略(替代盲扫 `<a>` 标签)
**修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` → 新增 `_chapterAwareFallback()` 方法
**问题**:原方案中的 `_fallbackSearchResults` 和自动扫描 `<a>` 都太激进——会把导航链接、广告链接、面包屑链接都当成章节。
**改进**:引入"章节识别器"——即使用正则匹配章节标题特征,而非盲扫所有链接。
```dart
/// 章节标题特征正则
static final _chapterPatterns = [
// 中文数字章节
RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*[章节话卷回]'),
// 中文数字话
RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*话'),
// 纯数字章节
RegExp(r'第\s*\d+\s*[章节话卷回]'),
// 英文章节
RegExp(r'Chapter\s*\d+', caseSensitive: false),
RegExp(r'Episode\s*\d+', caseSensitive: false),
// 卷
RegExp(r'Vol\.?\s*\d+', caseSensitive: false),
RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*卷'),
// 纯数字话
RegExp(r'^\d+\s*[话章]'),
];
/// 判断文本是否像一个章节标题
bool _looksLikeChapterTitle(String text) {
final trimmed = text.trim();
if (trimmed.length < 2 || trimmed.length > 80) return false;
for (final pattern in _chapterPatterns) {
if (pattern.hasMatch(trimmed)) return true;
}
return false;
}
/// 回退目录解析:扫描 HTML 中的 <a> 标签,但只保留符合章节标题特征的
List<OnlineChapter> _fallbackTocParser(String body, String baseUrl) {
final seen = <String>{};
final chapters = <OnlineChapter>[];
final links = RegExp(
r"<a\b[^>]*\bhref=[\"']([^\"']+)[\"'][^>]*>(.*?)</a>",
caseSensitive: false,
dotAll: true,
).allMatches(body);
for (final match in links) {
final href = match.group(1)?.trim() ?? '';
if (href.isEmpty || href.startsWith('#') ||
href.toLowerCase().startsWith('javascript:')) continue;
final title = _htmlToText(match.group(2) ?? '');
if (!_looksLikeChapterTitle(title)) continue; // ← 关键过滤
final url = _resolveUrl(baseUrl, href);
if (url.isEmpty || !seen.add(url)) continue;
chapters.add(OnlineChapter(
title: title,
url: url,
index: chapters.length + 1,
));
}
return chapters;
}
```
**解析优先级**:
```
1. 如果 tocListRule 可用 → 使用规则解析(精确)
2. 如果 tocListRule 不可用 → 使用章节识别器扫描(降级但可控)
3. 返回结果 ≤ 2 条 → 不做二次请求,直接展示(可能书源确实只有少量章节,也可能是网站结构不支持回退解析)
```
---
## 四、P1:第二阶段修改
> 这些依赖于 P0 的数据模型和详情页基础设施就绪。
### 1. 阅读器改造成章节驱动
**修改位置**:`online_manga_reader_page.dart` 和 `online_novel_reader_page.dart`
**当前**:读取器接收 `detailUrl`(其实是书籍详情页 URL),从中提取所有图片/文本。
**改造后**:读取器接收章节级参数。
```dart
class OnlineMangaReaderPage extends ConsumerStatefulWidget {
const OnlineMangaReaderPage({
super.key,
required this.source,
required this.bookTitle, // 🆕 书名(用于 AppBar / 阅读记录)
required this.chapters, // 🆕 完整章节列表
required this.currentChapterIndex,// 🆕 当前章节序号
this.currentChapterUrl, // 当前章节 URL(优先于从 chapters 取)
});
final LegadoSource source;
final String bookTitle;
final List<OnlineChapter> chapters;
final int currentChapterIndex;
final String? currentChapterUrl;
}
```
**进入阅读器时的数据加载**:
```
1. 从 chapters[currentChapterIndex].url 取章节 URL
2. 如果有 contentRule → 用 contentRule 解析
3. 如果没有 contentRule → 回退到现有的 fetchImageUrls / fetchPlainText
4. 用 contentNextRule 提取下一章 URL(优先于 chapters 数组)
5. 用 contentPrevRule 提取上一章 URL
```
**阅读器底部导航**:
```
┌───────────┬───────────┬───────────┐
│ ← 上一章 │ 📋 目录 │ 下一章 → │
└───────────┴───────────┴───────────┘
```
- "上一章":`currentChapterIndex > 0` 时才可用
- "下一章":`currentChapterIndex < chapters.length - 1` 或 `contentNextRule` 解析到了 URL 时才可用
- "目录":`Navigator.pop()` 回到详情页(章节列表已缓存,无需重新加载)
---
### 2. 支持目录分页 `{{page}}`
**修改位置**:`legado_engine.dart` → 新增 `_fetchPaginatedToc()` 方法
**问题**:很多书源的目录是分页的,URL 模板包含 `{{page}}` 占位符,例如:
```
/chapterlist/123?page={{page}}
```
如果不处理分页,只能拿到第一页的章节(通常几十章),后面几百章全部丢失。
**实现**:
```dart
Future<List<OnlineChapter>> _fetchPaginatedToc(
LegadoSource source,
String tocUrlTemplate,
) async {
final allChapters = <OnlineChapter>[];
const maxPages = 20; // 防止死循环
String? nextPageUrl = tocUrlTemplate;
for (int page = 1; page <= maxPages; page++) {
// 1. 替换 {{page}} 占位符
final url = nextPageUrl!
.replaceAll('{{page}}', page.toString())
.replaceAll('{page}', page.toString());
// 2. 请求并解析当前页
final body = await _fetchBody(source, url);
final parser = RuleParser(body, baseUrl: source.url);
// 3. 用规则解析章节条目
final fragments = _safeSelectList(parser, source.tocListRule);
for (final fragment in fragments) {
final name = _safeSelect(parser, fragment, source.tocNameRule);
final chapterUrl = _safeSelect(parser, fragment, source.tocUrlRule);
if (name.isNotEmpty && chapterUrl.isNotEmpty) {
allChapters.add(OnlineChapter(
title: name,
url: _resolveUrl(url, chapterUrl),
index: allChapters.length + 1,
));
}
}
// 4. 检查是否有下一页
if (source.tocNextPageRule != null) {
nextPageUrl = _safeSelect(parser, body, source.tocNextPageRule);
if (nextPageUrl == null || nextPageUrl.isEmpty) break; // 没有下一页了
} else {
// 如果没有 nextPageRule,尝试自动检测:如果当前页有 {{page}},则用 page+1 继续
if (!tocUrlTemplate.contains('{{page}}') &&
!tocUrlTemplate.contains('{page}')) {
break; // URL 模板中没有分页占位符,不继续
}
// 如果当前页返回的章节数与上一页相同,可能到底了,也停止
}
}
return allChapters;
}
```
**自动停止条件**:
- `tocNextPageRule` 返回空 → 停止
- 当前页返回 0 条新章节 → 停止
- 达到 `maxPages`(20 页)→ 停止并打日志
- 当前页与上一页完全重复 → 停止(防止环形分页)
---
### 3. 章节预加载
**修改位置**:阅读器页面
**策略**:阅读当前章节时,后台预加载下一章内容。
```
用户正在读第 3 章
│
├─ 立即请求:第 3 章内容(用 contentRule 解析)
│
└─ 后台请求:第 4 章内容(放入 chapterCache)
│
└─ 用户点"下一章" → 缓存命中 → 秒切
```
```dart
void _preloadNextChapter() {
final nextIdx = currentChapterIndex + 1;
if (nextIdx >= chapters.length) return;
final nextChapter = chapters[nextIdx];
final cacheKey = cache.key(source.id, nextChapter.url);
if (cache.getChapter(source.id, nextChapter.url) != null) return; // 已缓存
// 异步预加载,不阻塞当前渲染
_engine.fetchChapterContent(source, nextChapter.url)
.then((content) {
cache.putChapter(source.id, nextChapter.url, content);
})
.catchError((_) {
// 预加载失败静默忽略,用户点到下一章时再重试
});
}
```
**注意**:
- 只预加载**下一章**,不要一口气预加载全部(几百章的图片会爆内存)
- 预加载失败静默忽略,点击"下一章"时再重新请求
---
### 4. 阅读记录
**新增数据模型**:
```dart
class OnlineReadingRecord {
final String sourceId;
final String sourceName;
final String bookTitle;
final String detailUrl;
final String chapterUrl;
final String chapterTitle;
final int chapterIndex;
final int totalChapters;
final DateTime lastReadTime;
}
```
**存储方式(P1 阶段)**:SharedPreferences 存储 JSON 数组,最多保留 50 条最近记录。
**用途**:
- 「继续阅读」入口(在 ExplorePage 或首页)
- 章节已读标记(在详情页章节列表中显示 ✓ 或灰色)
- 返回详情页时自动定位到上次阅读的章节
**记录时机**:
- 进入某章阅读 → upsert 阅读记录
- 切换章节 → 更新阅读记录
- 返回详情页 → 不记录(只记录"阅读"行为)
---
## 五、P2:后续增强
> 主流程稳定后再做这些。
### 1. 持久化缓存
从内存缓存升级到本地持久化:
| 方案 | 适用场景 |
|------|---------|
| **Hive** | 轻量,适合存储 BookInfo / TOC / 阅读记录 |
| **Isar** | 功能更强,适合存储章节缓存 + 全文搜索 |
| **SQLite / sqflite** | 最灵活,适合复杂查询(按书源查、按时间查等) |
建议:**Hive** 作为第一选择,因为数据模型简单且已广泛用于 Flutter 缓存场景。
持久化内容:
- `BookInfo` → 按 `sourceId + detailUrl` 存储,有效期 24 小时
- `TOC` → 按 `sourceId + tocUrl` 存储,有效期 12 小时
- `阅读记录` → 永久存储,最多 200 条
- 章节内容 → 只缓存最近阅读的 20 章
### 2. ContentType 支持
初期不需要设计 `enum ContentType { text, image, mixed }`。
因为已有 `bookSourceType`:
- `type == 0` → 小说 → `contentRule` 提取文本
- `type == 2` → 漫画 → `contentRule` 提取图片
`mixed` 类型(小说中插图片、漫画中插文字)可以后期再支持。
### 3. 高级 Legado 规则支持
后续逐步补充:
- JSONPath 规则(`$.data.chapters[*]`)
- Regex 规则(`regex:...`)
- `webJs` 规则(需要 WebView 执行 JS 后取结果)
- `replaceRegex`(正文净化,去广告/去水印)
- 图片解密(部分漫画网站对图片做了简单加密,需要 JS 解密后 base64 展示)
这些是 Legado 生态的高级功能,不影响主体流程,可以逐步按需实现。
### 4. 更完整的兼容测试
- 覆盖至少 10 个不同类型的书源(小说/漫画、GBK/UTF-8、分页/单页目录)
- 测试老书源(只有搜索规则,没有 `ruleBookInfo` / `ruleToc`)的回退表现
- 测试网络异常情况(超时、DNS 失败、404、403)
---
## 六、优先级总表
```
P0:必须优先修改
├─ 1. unknown:none 错误归一化
├─ 2. 扩展 LegadoSource 模型(ruleBookInfo / ruleToc / ruleContent)
├─ 3. 新增 OnlineBookDetailPage(合并 BookInfo + TOC UI)
├─ 4. BookInfo + TOC 分段异步加载
├─ 5. 搜索结果点击进入详情页(explore_page.dart 导航逻辑)
├─ 6. 会话级内存缓存(BookInfo / TOC / Chapter)
└─ 7. 章节识别器回退策略(替代盲扫 <a>)
P1:第二阶段修改
├─ 1. 阅读器改造成章节驱动(接收 chapters + currentChapterIndex)
├─ 2. contentRule 正式接入(提取章节正文/图片)
├─ 3. 目录分页 {{page}} 支持
├─ 4. 下一章预加载
└─ 5. 阅读记录(继续阅读 / 已读标记)
P2:后续增强
├─ 1. 持久化缓存(Hive)
├─ 2. ContentType / mixed 内容
├─ 3. 高级 Legado 规则支持(JSONPath / webJs / replaceRegex)
└─ 4. 更完整的兼容测试
```
---
## 七、页面与数据流设计
### 7.1 整体架构
```
┌─────────────────────────────────────────────────────────┐
│ 在线搜索 (ExplorePage) │
│ 输入关键词 → 并发搜索已启用的书源 → 展示结果列表 │
└───────────────────────┬─────────────────────────────────┘
│ 用户点击某本书
▼
┌─────────────────────────────────────────────────────────┐
│ 在线书籍详情页 (OnlineBookDetailPage) 🆕 │
│ │
│ ┌─── 上半部分:BookInfo ───┐ │
│ │ 封面 · 书名 · 作者 · 来源 │ ← 第一步加载 │
│ │ 状态 · 简介 │ │
│ │ [开始阅读] [保存到书架] │ │
│ └──────────────────────────┘ │
│ │
│ ┌─── 下半部分:TOC ────────┐ │
│ │ 章节目录 (共 336 章) │ ← 第二步加载(独立请求) │
│ │ [正序] [倒序] │ │
│ │ 第一章 · 第二章 · ... │ 支持分页加载 │
│ └──────────────────────────┘ │
└───────────────────────┬─────────────────────────────────┘
│ 点击某章节
▼
┌─────────────────────────────────────────────────────────┐
│ 在线阅读器 (MangaReader / NovelReader) 🔧 改造 │
│ │
│ AppBar: 第3话 / 共336话 │
│ 正文内容 / 漫画图片 │
│ [← 上一章] [📋 目录] [下一章 →] │
│ │
│ 接收参数: source, chapters, currentChapterIndex │
│ 预加载: 下一章内容(后台) │
│ 记录: 阅读进度 │
└─────────────────────────────────────────────────────────┘
```
### 7.2 数据流
```
阶段 1 — 搜索:
LegadoSource.searchUrl + keyword
→ HTTP GET/POST
→ searchListRule 提取条目列表
→ 每个条目: {title, author, coverUrl, detailUrl}
阶段 2 — 详情(先):
detailUrl
→ HTTP GET
→ bookInfoRule 提取: {name, author, cover, intro, tocUrl}
→ 存入 bookInfoCache
→ 渲染页面顶部
阶段 3 — 目录(后):
tocUrl
→ HTTP GET(支持 {{page}} 分页)
→ chapterListRule 提取: [{name, url}, ...]
→ 存入 tocCache
→ 渲染章节列表
阶段 4 — 阅读:
chapter.url
→ HTTP GET
→ contentRule 提取: 正文文本 / 漫画图片 URL 列表
→ 存入 chapterCache
→ 展示内容
→ 后台预加载下一章
```
### 7.3 路由变更
| 当前 | 改造后 |
|------|--------|
| ExplorePage → OnlineMangaReaderPage(detailUrl) ❌ | ExplorePage → **OnlineBookDetailPage(detailUrl)** → 点击章节 → OnlineMangaReaderPage(chapterUrl) ✅ |
| ExplorePage → OnlineNovelReaderPage(detailUrl) ❌ | ExplorePage → **OnlineBookDetailPage(detailUrl)** → 点击章节 → OnlineNovelReaderPage(chapterUrl) ✅ |
---
## 八、数据模型扩展
### 8.1 LegadoSource 新增字段
```dart
class LegadoSource {
// ===== 现有字段(保持不变)=====
final String id;
final String name;
final String url;
final int type; // 0=小说, 2=漫画
final bool enabled;
final String? userAgent;
final Map<String, String> headers;
final String? searchUrl;
final String? searchListRule;
final String? searchNameRule;
final String? searchAuthorRule;
final String? searchCoverRule;
final String? searchDetailRule;
final String? searchMethod;
final String? searchBody;
final String? ruleKind;
final String? charset;
final String? urlEncoding;
// ===== 🆕 BookInfo =====
final String? bookInfoUrl;
final String? bookInfoNameRule;
final String? bookInfoAuthorRule;
final String? bookInfoCoverRule;
final String? bookInfoIntroRule;
final String? bookInfoTocRule; // ⭐ 最关键:目录页 URL
// ===== 🆕 TOC =====
final String? tocUrl;
final String? tocListRule;
final String? tocNameRule;
final String? tocUrlRule;
final String? tocNextPageRule; // 目录分页
// ===== 🆕 Content =====
final String? contentRule;
final String? contentNextRule;
final String? contentPrevRule;
}
```
### 8.2 新增运行时数据模型
```dart
/// 在线书籍详情
class OnlineBookInfo {
final String title;
final String? author;
final String? coverUrl;
final String? intro;
final String tocUrl; // ⭐ 目录页 URL
final String? status; // 连载中/已完结
final String? category;
final String? updateTime;
final String sourceName; // 来源书源名称
}
/// 在线章节
class OnlineChapter {
final String title;
final String url;
final int index; // 从 1 开始
bool isRead; // 是否已读(阅读记录反填)
}
/// 在线章节内容
class OnlineChapterContent {
final String title;
final String? textContent; // 小说正文
final List<String>? imageUrls; // 漫画图片
final String? nextChapterUrl; // 下一章 URL(contentNextRule 解析结果)
final String? prevChapterUrl; // 上一章 URL
}
/// 阅读记录
class OnlineReadingRecord {
final String sourceId;
final String sourceName;
final String bookTitle;
final String detailUrl;
final String chapterUrl;
final String chapterTitle;
final int chapterIndex;
final int totalChapters;
final DateTime lastReadTime;
}
```
### 8.3 fromJson / copyWith / toJson 变更
- `fromJson`:新增 12 个字段的解析逻辑(见上文 P0-2)
- `copyWith`:新增 12 个字段的传递(确保 `setEnabled()` 等不丢失数据)
- `toJson`:新增 12 个字段的序列化(确保持久化到 SharedPreferences 时保留)
---
## 九、Legado 书源规则字段对照
### 9.1 完整的 Legado 书源 JSON 示例
```json
{
"bookSourceName": "示例书源",
"bookSourceUrl": "https://www.example.com",
"bookSourceType": 0,
"bookSourceCharset": "gbk",
"ruleSearch": {
"url": "/search?keyword={{key}}&page={{page}}",
"bookList": ".result-list .item",
"name": ".book-title",
"author": ".author",
"coverUrl": "img@src",
"detailUrl": "a@href"
},
"ruleBookInfo": {
"name": "h1.book-title",
"author": ".author span",
"coverUrl": ".book-cover img@src",
"intro": ".book-desc",
"tocUrl": ".catalog-btn@href"
},
"ruleToc": {
"chapterList": ".chapter-list li",
"chapterName": "a",
"chapterUrl": "a@href",
"nextTocUrl": ".next-page@href"
},
"ruleContent": {
"content": "#chapter-content",
"nextChapterUrl": ".next-chapter@href",
"prevChapterUrl": ".prev-chapter@href"
}
}
```
### 9.2 字段映射表
| Legado 字段路径 | Sakura LegadoSource 字段 | P0/P1 |
|----------------|-------------------------|-------|
| `bookSourceName` | `name` | ✅ 已有 |
| `bookSourceUrl` | `url` | ✅ 已有 |
| `bookSourceType` | `type` | ✅ 已有 |
| `bookSourceCharset` | `charset` | ✅ 已有 |
| `ruleSearch.url` | `searchUrl` | ✅ 已有 |
| `ruleSearch.bookList` | `searchListRule` | ✅ 已有 |
| `ruleSearch.name` | `searchNameRule` | ✅ 已有 |
| `ruleSearch.author` | `searchAuthorRule` | ✅ 已有 |
| `ruleSearch.coverUrl` | `searchCoverRule` | ✅ 已有 |
| `ruleSearch.detailUrl` | `searchDetailRule` | ✅ 已有 |
| `ruleBookInfo.name` | `bookInfoNameRule` | 🆕 P0 |
| `ruleBookInfo.author` | `bookInfoAuthorRule` | 🆕 P0 |
| `ruleBookInfo.coverUrl` | `bookInfoCoverRule` | 🆕 P0 |
| `ruleBookInfo.intro` | `bookInfoIntroRule` | 🆕 P0 |
| `ruleBookInfo.tocUrl` | `bookInfoTocRule` | 🆕 P0 ⭐ |
| `ruleToc.chapterList` | `tocListRule` | 🆕 P0 |
| `ruleToc.chapterName` | `tocNameRule` | 🆕 P0 |
| `ruleToc.chapterUrl` | `tocUrlRule` | 🆕 P0 |
| `ruleToc.nextTocUrl` | `tocNextPageRule` | 🆕 P1 |
| `ruleContent.content` | `contentRule` | 🆕 P1 |
| `ruleContent.nextChapterUrl` | `contentNextRule` | 🆕 P1 |
| `ruleContent.prevChapterUrl` | `contentPrevRule` | 🆕 P1 |
---
## 十、附录:关键文件清单
### 修改的文件
| 文件 | 角色 | P0 | P1 | P2 |
|------|------|:--:|:--:|:--:|
| `sakura_mobile/lib/src/core/legado_models.dart` | 数据模型 | 🔧 | | |
| `sakura_mobile/lib/src/core/legado_engine.dart` | 解析引擎 | 🔧 | 🔧 | 🔧 |
| `sakura_mobile/lib/src/core/legado_rule_parser.dart` | 规则解析器 | | | |
| `sakura_mobile/lib/src/pages/explore_page.dart` | 搜索页导航 | 🔧 | | |
| `sakura_mobile/lib/src/pages/online_manga_reader_page.dart` | 漫画阅读器 | | 🔧 | |
| `sakura_mobile/lib/src/pages/online_novel_reader_page.dart` | 小说阅读器 | | 🔧 | |
| `sakura_mobile/lib/src/core/providers.dart` | Riverpod | 视需要 | | |
### 新增的文件
| 文件 | 角色 | P0 | P1 | P2 |
|------|------|:--:|:--:|:--:|
| `sakura_mobile/lib/src/pages/online_book_detail_page.dart` | 在线书籍详情页(合并 UI) | 🆕 | | |
| `sakura_mobile/lib/src/core/online_cache.dart` | 会话级内存缓存 | 🆕 | | |
---
## 总结
以「能落地开发」为最终目标,本方案的核心建议是:
1. **先修 `_shortError()`** — 把 `unknown:none` 等所有 Dio 底层异常映射为中文提示,这是最小的改动但立刻消除最明显的 bug。
2. **再补模型** — `LegadoSource` 补全 `ruleBookInfo`、`ruleToc`、`ruleContent` 字段,`fromJson`/`copyWith`/`toJson` 全部对齐。不补齐模型,后面所有的页面都无从谈起。
3. **再做合并式详情页** — `OnlineBookDetailPage` 把 BookInfo + TOC 放在同一个页面,但数据加载分两次独立请求。不跳独立 TOC 页面,用户体验更流畅。
4. **接章节阅读** — 阅读器接收 `chapters` + `currentChapterIndex`,从 URL 驱动改成章节驱动。这是解决"点开书直接显示乱码"问题的终点。
5. **最后补分页和高级规则** — 目录分页 `{{page}}`、章节预加载、阅读记录、持久化缓存——这些让体验从"能用"到"好用"。
```
页面合并,解析分层;
缓存前置,持久化后置;
目录回退要识别章节,不要盲扫链接;
阅读器必须从 URL 驱动改成章节驱动。
```