1223 lines
44 KiB
Markdown
1223 lines
44 KiB
Markdown
# 在线搜索错误修复 与 书→目录→章节 导航流程 — 完整解决方案
|
||
|
||
> 分析日期: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 驱动改成章节驱动。
|
||
```
|