Files
SakuraHub/docs/在线搜索-书本章节导航-完整解决方案.md
T
2026-11-16 20:45:22 +08:00

1223 lines
44 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 在线搜索错误修复 与 书→目录→章节 导航流程 — 完整解决方案
> 分析日期: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 驱动改成章节驱动。
```