745 lines
26 KiB
Markdown
745 lines
26 KiB
Markdown
# 四大问题完整修复方案(终版)
|
||||
|
|
|
|||
|
|
> 更新日期:2026-06-16
|
|||
|
|
> 范围:Sakura Mobile (Flutter) + Sakura Cloud (FastAPI) + Sakura Admin Web (Vue.js) + Desktop GUI (Python)
|
|||
|
|
> 版本:v2.0 — 调整优先级为 P0/P1 两级、修正问题二的风险边界和工期、问题一拆为两层修复、问题四拆为开发/生产两套方案、问题三补搜索防抖
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
1. [优先级总览](#零优先级总览)
|
|||
|
|
2. [P0-1:无法搜索本地不存在的图库(源不可用)](#一p0-1无法搜索本地不存在的图库源不可用)
|
|||
|
|
3. [P0-2:网页端显示 JSON 数据而非图片/小说/漫画](#二p0-2网页端显示-json-数据而非图片小说漫画)
|
|||
|
|
4. [P1-1:APP 发现页向上滚动卡在底部](#三p1-1app-发现页向上滚动卡在底部)
|
|||
|
|
5. [P1-2:导入源的位置排版有问题](#四p1-2导入源的位置排版有问题)
|
|||
|
|
6. [实施计划](#五实施计划)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 零、优先级总览
|
|||
|
|
|
|||
|
|
| 等级 | 问题 | 严重程度 | 工期 | 风险 |
|
|||
|
|
|:----:|------|:--------:|:----:|:----:|
|
|||
|
|
| **P0-1** | 书源搜索不可用 | 核心功能阻断 | 3–5 天 | **高** |
|
|||
|
|
| **P0-2** | Web 端显示 JSON / 无法展示内容 | 入口不可用 | 1–2 天 | 低 |
|
|||
|
|
| **P1-1** | 发现页 Feed 滚动卡死 | 高频场景阻断 | 1–2 天 | 低 |
|
|||
|
|
| **P1-2** | 书源管理页排版和性能 | 管理体验差 | 0.5–1 天 | 低 |
|
|||
|
|
|
|||
|
|
**优先级判断依据:**
|
|||
|
|
- 问题二是"在线探索"的整个功能链路不通,影响范围最大。
|
|||
|
|
- 问题四是 Web 端入口整体不可用,新用户访问会直接流失。
|
|||
|
|
- 问题一如果高频复现(每次打开发现页都卡),也接近阻断级,但只影响单页面。
|
|||
|
|
- 问题三是管理后台的体验优化,不影响核心浏览链路。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、P0-1:无法搜索本地不存在的图库(源不可用)
|
|||
|
|
|
|||
|
|
### 1.1 问题现象
|
|||
|
|
|
|||
|
|
"在线探索"(ExplorePage)搜索漫画/小说时,所有已启用的书源永远不返回结果。无论是否从仓库导入源,`legado_engine.search()` 都静默返回 `[]`,UI 显示"暂无搜索结果"。
|
|||
|
|
|
|||
|
|
### 1.2 根因分析
|
|||
|
|
|
|||
|
|
**审查文件(6 个):** `source_manager.dart`、`legado_engine.dart`、`legado_models.dart`、`legado_rule_parser.dart`、`unified_search.dart`、`explore_page.dart`
|
|||
|
|
|
|||
|
|
#### 根因 1(阻断级):默认种子源 URL = `example.invalid`,且 searchUrl/searchListRule 全空
|
|||
|
|
|
|||
|
|
**文件:** `source_manager.dart` 第 274–317 行
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
LegadoSource(
|
|||
|
|
name: '笔趣阁',
|
|||
|
|
url: 'https://example.invalid/novel/biquge', // IANA 保留测试域名
|
|||
|
|
type: 0, enabled: true,
|
|||
|
|
// searchUrl、searchListRule —— 全部 null
|
|||
|
|
),
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`LegadoEngine.search()` 入口(第 36–39 行):
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
if (searchUrl == null || listRule == null) {
|
|||
|
|
return const <UnifiedSearchResult>[]; // 静默短路
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
六个默认种子源全都没有搜索规则。不论用户是否"启用",搜索入口直接返回空。这些种子源是从设计之初就存在的占位符,但从未被替换为可用源。
|
|||
|
|
|
|||
|
|
#### 根因 2(阻断级):CSS 选择器仅支持 `<tag>...</tag>` 简单正则,不支持 class/ID/属性/后代
|
|||
|
|
|
|||
|
|
**文件:** `legado_rule_parser.dart` 第 86–96 行
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
List<String> _cssFragments(String selector) {
|
|||
|
|
final tag = _selectorTag(selector); // 只取开头 a-zA-Z 部分作 tag
|
|||
|
|
if (tag == null) return const <String>[];
|
|||
|
|
final pattern = RegExp('<$tag\\b[^>]*>.*?</$tag>', ...);
|
|||
|
|
return pattern.allMatches(body)...;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Legado 源仓库中 95%+ 的规则使用 class 选择器(`.book-list > .item`),当前引擎完全无法解析。
|
|||
|
|
|
|||
|
|
#### 根因 3(阻断级):GBK 编码 HTML 抛 `FormatException`
|
|||
|
|
|
|||
|
|
**文件:** `legado_engine.dart` 第 216–220 行
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
if (charset == 'gbk' || charset == 'gb2312' || ...) {
|
|||
|
|
return gbk.decode(bytes); // ← 无容错参数,遇非 GBK 字节直接抛异常
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`utf8.decode` 使用了 `allowMalformed: true`,但 `gbk.decode` **没有容错**。大量声称 charset=gbk 的页面实际混入了非 GBK 字节(emoji、广告注入的特殊符号等),导致整个 `_fetchBody` 失败。
|
|||
|
|
|
|||
|
|
#### 根因 4:`_ruleType` 忽略传入的 `kind` 参数
|
|||
|
|
|
|||
|
|
**文件:** `legado_rule_parser.dart` 第 130–134 行
|
|||
|
|
|
|||
|
|
`selectList` 和 `select` 虽然接受 `kind` 参数,但传给 `_ruleType` 的逻辑有断裂——`_ruleType` 方法签名不接受 `kind`,只根据规则文本前缀判断类型。如果 `source.ruleKind == 'xpath'` 但规则文本不以 `xpath:` 开头,会错误地按 CSS 解析。
|
|||
|
|
|
|||
|
|
#### 根因 5:仓库 URL 在国内网络不可达 + 首次启动静默失败
|
|||
|
|
|
|||
|
|
`legado.aoaostar.com`、`gcore.jsdelivr.net`、`git.nyne.dev` 均可能被 DNS 污染或不可达。`initializeIfFirstRun()` 首次启动自动拉仓库,12 秒超时后静默失败,用户无法感知问题所在。
|
|||
|
|
|
|||
|
|
#### 根因 6:搜索结果 DOM 解析在 UI 线程
|
|||
|
|
|
|||
|
|
每条结果调一次 `html_parser.parse(fragment)`,搜索结果 20 条 × 6 源 = 120 次 DOM 解析。低端机上会造成 frame drop。
|
|||
|
|
|
|||
|
|
### 1.3 解决方案
|
|||
|
|
|
|||
|
|
**⚠️ 法律与风险声明:** 问题二的本质是半个解析引擎重构 + 第三方内容源集成。涉及版权法律风险、源站反爬策略、编码兼容性和解析性能。以下方案在技术层面给出修复路径,**实际实施前需要产品侧确认法律边界和使用条款**。
|
|||
|
|
|
|||
|
|
#### 方案 A:删除占位种子源,首次启动不做任何自动导入
|
|||
|
|
|
|||
|
|
**修改文件:** `source_manager.dart`
|
|||
|
|
|
|||
|
|
**策略——客户端不内置任何第三方书源仓库、书源 URL 或规则:**
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
Future<void> initializeIfFirstRun() async {
|
|||
|
|
await load();
|
|||
|
|
final prefs = await SharedPreferences.getInstance();
|
|||
|
|
if (prefs.getBool(_initializedKey) == true) return;
|
|||
|
|
|
|||
|
|
// 不做任何自动导入。首次启动源列表为空。
|
|||
|
|
await prefs.setBool(_initializedKey, true);
|
|||
|
|
notifyListeners();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
删除 `_seedDefaultSources()` 中的 6 个 `example.invalid` 占位源。首次启动后源列表为空,UI 显示引导入口:
|
|||
|
|
|
|||
|
|
> **当前没有可用书源。**
|
|||
|
|
> 书源规则是第三方网站的内容解析配置,请从你信任的仓库导入,或手动添加你有使用权限的书源。
|
|||
|
|
> [从内置仓库导入] [从 URL 导入]
|
|||
|
|
|
|||
|
|
**不内置任何仓库索引 JSON。** 仓库列表仅作为 UI 入口的快捷链接提供,不硬编码到客户端。
|
|||
|
|
|
|||
|
|
#### 方案 B:重写 CSS 选择器——引入 `html` 包 + Isolate 解析
|
|||
|
|
|
|||
|
|
**修改文件:** `legado_rule_parser.dart`、`pubspec.yaml`
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
dependencies:
|
|||
|
|
html: ^0.15.5
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
import 'package:html/parser.dart' as html_parser;
|
|||
|
|
|
|||
|
|
List<String> _cssFragments(String selector) {
|
|||
|
|
try {
|
|||
|
|
final doc = html_parser.parse(body);
|
|||
|
|
final elements = doc.querySelectorAll(selector);
|
|||
|
|
return elements.map((el) => el.outerHtml).where(_notEmpty).toList();
|
|||
|
|
} on Object {
|
|||
|
|
return _legacyCssFragments(selector); // 正则降级
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
String _cssText(String fragment, String selector) {
|
|||
|
|
final attrMatch = RegExp(r'@([a-zA-Z0-9_-]+)$').firstMatch(selector);
|
|||
|
|
final clean = selector.replaceFirst(RegExp(r'@([a-zA-Z0-9_-]+)$'), '').trim();
|
|||
|
|
try {
|
|||
|
|
final el = html_parser.parse(fragment).querySelector(clean);
|
|||
|
|
if (el == null) return '';
|
|||
|
|
if (attrMatch != null) return el.attributes[attrMatch.group(1)] ?? '';
|
|||
|
|
return el.text.trim();
|
|||
|
|
} on Object {
|
|||
|
|
return _legacyCssText(fragment, selector);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
对超过 20 条的搜索结果,在 `Isolate` 中批量解析:
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
import 'dart:isolate';
|
|||
|
|
|
|||
|
|
Future<List<UnifiedSearchResult>> _parseBatch(
|
|||
|
|
List<_SearchRawResult> raw,
|
|||
|
|
) async {
|
|||
|
|
if (raw.length < 20) return _parseInline(raw);
|
|||
|
|
return Isolate.run(() => _parseInIsolate(raw));
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 方案 C:修复 GBK/GB18030 解码容错
|
|||
|
|
|
|||
|
|
**修改文件:** `legado_engine.dart` 第 202–223 行
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
String _decodeBody(List<int> bytes, {String? declaredCharset, ...}) {
|
|||
|
|
if (bytes.isEmpty) return '';
|
|||
|
|
final charset = (declaredCharset ?? _charsetFromContentType(contentType))
|
|||
|
|
?.trim().toLowerCase();
|
|||
|
|
|
|||
|
|
if (charset == 'gbk' || charset == 'gb2312' || charset == 'gb18030' || charset == 'gbk-0') {
|
|||
|
|
try {
|
|||
|
|
return gbk.decode(bytes);
|
|||
|
|
} on FormatException {
|
|||
|
|
return latin1.decode(bytes, allowInvalid: true); // 降级,保留可读部分
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (charset == 'latin1' || charset == 'iso-8859-1' || charset == 'windows-1252') {
|
|||
|
|
return latin1.decode(bytes, allowInvalid: true);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
return utf8.decode(bytes, allowMalformed: true);
|
|||
|
|
} on FormatException {
|
|||
|
|
return latin1.decode(bytes, allowInvalid: true);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 方案 D:修复 `_ruleType`——优先使用传入的 `kind`
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
String _resolveKind(String rule, String? explicitKind) {
|
|||
|
|
if (explicitKind != null && explicitKind.isNotEmpty) return explicitKind;
|
|||
|
|
final lower = rule.toLowerCase();
|
|||
|
|
if (lower.startsWith('json:') || lower.startsWith(r'$.')) return 'json';
|
|||
|
|
if (lower.startsWith('regex:')) return 'regex';
|
|||
|
|
return 'css';
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
调用方改为 `_resolveKind(normalized, kind)` 替代原来的 `kind ?? _ruleType(normalized)`。
|
|||
|
|
|
|||
|
|
#### 方案 E:多源异常隔离——单源失败不拖垮全局
|
|||
|
|
|
|||
|
|
**修改文件:** `legado_engine.dart` `searchAll()` 方法
|
|||
|
|
|
|||
|
|
当前实现已经是 `.catchError` 静默跳过,但错误信息被丢弃。改为:
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
Future.wait(batch.map((source) =>
|
|||
|
|
search(source, keyword, page: page)
|
|||
|
|
.timeout(perSourceTimeout)
|
|||
|
|
.then((items) => items)
|
|||
|
|
.catchError((error) => <UnifiedSearchResult>[
|
|||
|
|
UnifiedSearchResult.error(
|
|||
|
|
sourceId: source.id,
|
|||
|
|
sourceName: source.name,
|
|||
|
|
errorMessage: _shortError(error),
|
|||
|
|
),
|
|||
|
|
]),
|
|||
|
|
));
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
错误结果显示在 UI 中(如 `"笔趣阁 - 请求超时"`),用户可以看到哪些源失败了。
|
|||
|
|
|
|||
|
|
#### 方案 F:仓库镜像轮询 + 网络探测
|
|||
|
|
|
|||
|
|
为 5 个仓库 URL 各提供 2–3 个镜像域名。`importFromRepo()` 依次尝试,全部失败则提示用户手动输入 URL。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、P0-2:网页端显示 JSON 数据而非图片/小说/漫画
|
|||
|
|
|
|||
|
|
### 2.1 问题现象
|
|||
|
|
|
|||
|
|
浏览器访问 Sakura Cloud 后端或 Admin Web 时,页面显示原始 JSON(`{"items": [...]}`),而非渲染好的图片网格、小说内容、漫画翻页器。
|
|||
|
|
|
|||
|
|
### 2.2 根因分析
|
|||
|
|
|
|||
|
|
**审查文件:** `sakura_cloud/main.py`、`sakura_cloud/api/middleware.py`、`sakura_admin_web/`、`pixiv_app/services/gallery_api.py`
|
|||
|
|
|
|||
|
|
#### 根因 1(阻断级):FastAPI 未注册 CORS 中间件
|
|||
|
|
|
|||
|
|
**文件:** `sakura_cloud/main.py`
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
app = FastAPI(...)
|
|||
|
|
# ← 缺少 app.add_middleware(CORSMiddleware, ...)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Admin Web 开发时运行在 `localhost:5174`,后端在 `localhost:8000`。浏览器跨域请求被拦截,前端连 API 都调不通。CSP 中间件(`middleware.py`)处理的是内容安全策略,**不替代 CORS**。
|
|||
|
|
|
|||
|
|
#### 根因 2(阻断级):Cloud 后端未挂载 SPA 静态文件
|
|||
|
|
|
|||
|
|
**文件:** `sakura_cloud/main.py` 第 61–78 行
|
|||
|
|
|
|||
|
|
`/admin` 路由返回的是硬编码占位 HTML,不是 `sakura_admin_web/dist/index.html` 构建产物。任何 `/app`、`/login` 路径返回 404 或触发认证检查。
|
|||
|
|
|
|||
|
|
#### 根因 3:Admin Web 缺少内容浏览 Vue 组件
|
|||
|
|
|
|||
|
|
- `UserDashboard.vue`:仅导航卡片,无实际内容页
|
|||
|
|
- `UserDetailPage.vue`:占位组件——"详情数据由现有 API 按需加载"
|
|||
|
|
- 路由没有注册 `/gallery`、`/novels` 等内容浏览路由
|
|||
|
|
|
|||
|
|
#### 根因 4:CSP `img-src 'self'` 阻止外部图片
|
|||
|
|
|
|||
|
|
API 返回的 `thumbnail_url` 指向外部域名时,浏览器 CSP 引擎直接拦截。
|
|||
|
|
|
|||
|
|
### 2.3 解决方案
|
|||
|
|
|
|||
|
|
#### ⸻ 开发环境 ⸻
|
|||
|
|
|
|||
|
|
#### 方案 A:注册 CORS 中间件
|
|||
|
|
|
|||
|
|
**修改文件:** `sakura_cloud/main.py`
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from fastapi.middleware.cors import CORSMiddleware
|
|||
|
|
|
|||
|
|
app.add_middleware(
|
|||
|
|
CORSMiddleware,
|
|||
|
|
allow_origins=[
|
|||
|
|
"http://localhost:5174",
|
|||
|
|
"http://127.0.0.1:5174",
|
|||
|
|
"app://.",
|
|||
|
|
],
|
|||
|
|
allow_credentials=True,
|
|||
|
|
allow_methods=["*"],
|
|||
|
|
allow_headers=["*"],
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 方案 B:修复 CSP 中间件
|
|||
|
|
|
|||
|
|
**修改文件:** `sakura_cloud/api/middleware.py`
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
"img-src 'self' data: blob: https: http:;"
|
|||
|
|
"connect-src 'self' http://localhost:* ws://localhost:*;"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 方案 C:开发环境可选挂载 Vue dist
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# sakura_cloud/main.py — 开发环境可选
|
|||
|
|
import os
|
|||
|
|
from fastapi.staticfiles import StaticFiles
|
|||
|
|
|
|||
|
|
frontend_dist = os.path.join(os.path.dirname(__file__), "..", "sakura_admin_web", "dist")
|
|||
|
|
if os.path.isdir(frontend_dist) and settings.debug:
|
|||
|
|
assets = os.path.join(frontend_dist, "assets")
|
|||
|
|
if os.path.isdir(assets):
|
|||
|
|
app.mount("/assets", StaticFiles(directory=assets), name="assets")
|
|||
|
|
|
|||
|
|
@app.get("/app/{full_path:path}")
|
|||
|
|
async def spa_fallback(full_path: str = ""):
|
|||
|
|
index = os.path.join(frontend_dist, "index.html")
|
|||
|
|
return FileResponse(index) if os.path.isfile(index) else HTMLResponse("Not built")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意:不添加 API 路径自动重定向的中间件。** 这会导致 APP 的 Dio/浏览器 Extension 发起的 API 请求被误重定向。API 路径就让它返回 JSON——它是 REST API 的正确行为。前端 SPA 从 `/app` 入口加载后用 JS fetch 数据。
|
|||
|
|
|
|||
|
|
#### ⸻ 生产环境 ⸻
|
|||
|
|
|
|||
|
|
#### 方案 D:Nginx 托管 SPA + 反向代理 API
|
|||
|
|
|
|||
|
|
**推荐的生产结构:**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Nginx
|
|||
|
|
├── / → /var/www/sakura_admin_web/dist/index.html
|
|||
|
|
├── /app → SPA fallback (try_files $uri /index.html)
|
|||
|
|
├── /login → SPA fallback
|
|||
|
|
├── /assets/ → 静态资源,expires 1y(Vite 产物带 hash)
|
|||
|
|
└── /api/ → proxy_pass http://127.0.0.1:8000
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Nginx 配置示例:**
|
|||
|
|
|
|||
|
|
```nginx
|
|||
|
|
server {
|
|||
|
|
listen 80;
|
|||
|
|
server_name admin.your-domain.com;
|
|||
|
|
root /var/www/sakura_admin_web/dist;
|
|||
|
|
index index.html;
|
|||
|
|
|
|||
|
|
location /api/ {
|
|||
|
|
proxy_pass http://127.0.0.1:8000;
|
|||
|
|
proxy_set_header Host $host;
|
|||
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|||
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|||
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
location /assets/ {
|
|||
|
|
expires 1y;
|
|||
|
|
add_header Cache-Control "public, immutable";
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
location / {
|
|||
|
|
try_files $uri $uri/ /index.html;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
FastAPI **不长期托管前端静态资源**,只负责 API。
|
|||
|
|
|
|||
|
|
#### 方案 E:新增内容浏览 Vue 组件
|
|||
|
|
|
|||
|
|
**新增文件:**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
sakura_admin_web/src/views/app/
|
|||
|
|
├── GalleryBrowsePage.vue # 画廊浏览:grid + 分页 + 搜索筛选
|
|||
|
|
├── NovelReadPage.vue # 小说阅读:章节列表 + 正文渲染
|
|||
|
|
└── MangaViewerPage.vue # 漫画翻页:PageView 横向翻页
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
路由注册:
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// router/index.ts
|
|||
|
|
{ path: '/app/gallery', component: () => import('@/views/app/GalleryBrowsePage.vue') },
|
|||
|
|
{ path: '/app/novels', component: () => import('@/views/app/NovelReadPage.vue') },
|
|||
|
|
{ path: '/app/manga/:id', component: () => import('@/views/app/MangaViewerPage.vue') },
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、P1-1:APP 发现页向上滚动卡在底部
|
|||
|
|
|
|||
|
|
### 3.1 问题现象
|
|||
|
|
|
|||
|
|
发现页从底部向上回滚时卡住,须等待数据加载完或强制下拉刷新才能恢复。
|
|||
|
|
|
|||
|
|
### 3.2 根因分析
|
|||
|
|
|
|||
|
|
**审查文件:** `feed_tab.dart`(829 行)
|
|||
|
|
|
|||
|
|
| 根因 | 位置 | 严重程度 |
|
|||
|
|
|------|------|:--------:|
|
|||
|
|
| `_ensureFutures()` 在 `build()` 中反复调用 | 第 64–66 行 | 高 |
|
|||
|
|
| `_refresh()` 用 `setState` 归零所有 future → 布局高度剧烈跳动 | 第 53–62 行 | **阻断** |
|
|||
|
|
| `_StatCard` 在列表末尾加载完成后高度变化 | 第 182–186 行 | 中 |
|
|||
|
|
| 内嵌横向 `ListView` 与纵向 `ListView` 手势竞争 | 第 443–507 行 | 中(部分设备) |
|
|||
|
|
| `ScrollController` 未显式管理生命周期 | 缺 | 低 |
|
|||
|
|
|
|||
|
|
### 3.3 解决方案——拆为两层
|
|||
|
|
|
|||
|
|
#### 第一层:必须做(P1 范围)
|
|||
|
|
|
|||
|
|
**1. `AsyncNotifier` 替代 `FutureBuilder` + 状态统一管理**
|
|||
|
|
|
|||
|
|
当前 `_FeedTabState` 用 5 个散落的 `Future` + `FutureBuilder` 管理异步状态,刷新时 `setState(null)` 归零所有 future 再在下一帧重建——这个模式是滚动问题的根源。
|
|||
|
|
|
|||
|
|
改为用一个统一的 `FeedState` 对象:
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class FeedState {
|
|||
|
|
final bool loading;
|
|||
|
|
final List<Artwork> todayArtworks;
|
|||
|
|
final List<Artwork> recentArtworks;
|
|||
|
|
final List<Novel> recentNovels;
|
|||
|
|
final List<Map<String, dynamic>> alerts;
|
|||
|
|
final Map<String, dynamic> stat;
|
|||
|
|
final String? error;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
用 Riverpod `AsyncNotifier` 管理整个页面的数据加载。`build()` 只读取 `ref.watch(feedProvider)`,不调用 `_ensureFutures()`,不在 build 中创建 future。
|
|||
|
|
|
|||
|
|
**2. 显式 `ScrollController`**
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class _FeedTabState extends ConsumerState<FeedTab> {
|
|||
|
|
final ScrollController _scrollController = ScrollController();
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
void dispose() {
|
|||
|
|
_scrollController.dispose();
|
|||
|
|
super.dispose();
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
外层 `ListView` 绑定此 controller。切换 tab 时通过 `_scrollController.hasClients` 检查位置有效性。
|
|||
|
|
|
|||
|
|
**3. `_StatCard` 固定高度**
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
SizedBox(
|
|||
|
|
height: 106,
|
|||
|
|
child: _StatCard(stat: stat),
|
|||
|
|
),
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
通过 `AnimatedSwitcher` 平滑过渡内容而非跳变布局。
|
|||
|
|
|
|||
|
|
**4. Refresh 状态统一管理**
|
|||
|
|
|
|||
|
|
`RefreshIndicator.onRefresh` 调用 provider 的 `ref.invalidate(feedProvider)`,由一个入口触发重载,不再散射到 5 个独立的 `setState(null)` 调用。
|
|||
|
|
|
|||
|
|
#### 第二层:如果仍有横向列表抢手势(专项修复)
|
|||
|
|
|
|||
|
|
仅当第一层修复后,在部分设备上仍出现"在对角线滑动时外层垂直滚动丢失"的问题时,才实施此层:
|
|||
|
|
|
|||
|
|
对横向 `_ArtworkStrip` 的 `ListView` 外套方向判定:
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
SizedBox(
|
|||
|
|
height: 210,
|
|||
|
|
child: RawGestureDetector(
|
|||
|
|
gestures: {
|
|||
|
|
HorizontalDragGestureRecognizer:
|
|||
|
|
GestureRecognizerFactoryWithHandlers<HorizontalDragGestureRecognizer>(
|
|||
|
|
() => HorizontalDragGestureRecognizer(),
|
|||
|
|
(instance) {},
|
|||
|
|
),
|
|||
|
|
},
|
|||
|
|
child: ListView.separated(
|
|||
|
|
scrollDirection: Axis.horizontal,
|
|||
|
|
physics: const ClampingScrollPhysics(),
|
|||
|
|
...
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`HorizontalDragGestureRecognizer` 在竞技场中只响应水平方向的拖拽,对角滑动时垂直分量不会被它吃掉,外层垂直 ListView 正常响应。
|
|||
|
|
|
|||
|
|
**不推荐 `PageStorageKey` 解决手势竞争。** `PageStorageKey` 的职责是页面切换后恢复滚动位置(`PageStorage` 机制),它不参与手势竞技场裁决。两项是不同层面的问题,不应混用。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、P1-2:导入源的位置排版有问题
|
|||
|
|
|
|||
|
|
### 4.1 问题现象
|
|||
|
|
|
|||
|
|
书源管理页布局混乱:搜索栏在导入区底部(须滑过所有卡片才能搜索)、已导入 2200+ 条后 `for` 循环展开所有 Card 导致卡顿、5 个仓库全部展开占用过多空间。
|
|||
|
|
|
|||
|
|
### 4.2 根因分析
|
|||
|
|
|
|||
|
|
**审查文件:** `source_manager_page.dart`(465 行)
|
|||
|
|
|
|||
|
|
| 根因 | 位置 |
|
|||
|
|
|------|------|
|
|||
|
|
| 搜索栏放在仓库 + 导入卡片**之后** | 第 81–85 行 |
|
|||
|
|
| `for` 循环展开全部源,无懒加载 | 第 102–129 行 |
|
|||
|
|
| 5 个仓库全部展开,每个 ~120px | 第 376–413 行 |
|
|||
|
|
| 缺少分段标题和视觉层次 | 全页 |
|
|||
|
|
|
|||
|
|
### 4.3 解决方案
|
|||
|
|
|
|||
|
|
#### 方案 A:CustomScrollView + SliverAppBar 吸顶搜索栏
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context) {
|
|||
|
|
final manager = ref.watch(sourceManagerProvider);
|
|||
|
|
final filteredSources = _filterSources(manager);
|
|||
|
|
|
|||
|
|
return Scaffold(
|
|||
|
|
body: CustomScrollView(
|
|||
|
|
slivers: [
|
|||
|
|
// 搜索栏吸顶
|
|||
|
|
SliverAppBar(
|
|||
|
|
pinned: true,
|
|||
|
|
title: const Text('书源管理'),
|
|||
|
|
bottom: PreferredSize(
|
|||
|
|
preferredSize: const Size.fromHeight(56),
|
|||
|
|
child: Padding(
|
|||
|
|
padding: const EdgeInsets.fromLTRB(16, 0, 16, 8),
|
|||
|
|
child: SearchBar(
|
|||
|
|
hintText: '搜索已导入的书源',
|
|||
|
|
leading: const Icon(Icons.search),
|
|||
|
|
onChanged: onSearchChanged, // 带防抖
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
|
|||
|
|
// 统计 + 维护 + 仓库 + 导入 —— 各 SliverToBoxAdapter
|
|||
|
|
SliverToBoxAdapter(child: _StatsCard(manager: manager)),
|
|||
|
|
SliverToBoxAdapter(child: _MaintenanceCard(...)),
|
|||
|
|
SliverToBoxAdapter(child: _CollapsibleRepoSection(...)),
|
|||
|
|
SliverToBoxAdapter(child: _CustomImportCard(...)),
|
|||
|
|
|
|||
|
|
// 分段标题
|
|||
|
|
SliverToBoxAdapter(
|
|||
|
|
child: Padding(
|
|||
|
|
padding: const EdgeInsets.fromLTRB(16, 8, 16, 4),
|
|||
|
|
child: Text('已导入 (${filteredSources.length})', ...),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
|
|||
|
|
// 源列表 —— 懒加载
|
|||
|
|
SliverList.builder(
|
|||
|
|
itemCount: filteredSources.length,
|
|||
|
|
itemBuilder: (context, index) {
|
|||
|
|
final source = filteredSources[index];
|
|||
|
|
return Card(
|
|||
|
|
child: SwitchListTile(
|
|||
|
|
value: source.enabled,
|
|||
|
|
onChanged: (value) =>
|
|||
|
|
ref.read(sourceManagerProvider).setEnabled(source.id, value),
|
|||
|
|
title: Text(source.name),
|
|||
|
|
subtitle: Text('${source.isManga ? '漫画' : '小说'} - ${source.url}'),
|
|||
|
|
secondary: Icon(source.isManga
|
|||
|
|
? Icons.menu_book_rounded
|
|||
|
|
: Icons.auto_stories_rounded),
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
},
|
|||
|
|
),
|
|||
|
|
|
|||
|
|
if (filteredSources.isEmpty)
|
|||
|
|
SliverToBoxAdapter(
|
|||
|
|
child: const Padding(
|
|||
|
|
padding: EdgeInsets.all(28),
|
|||
|
|
child: Center(child: Text('还没有导入书源,请先导入一个书源仓库。')),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
|
|||
|
|
const SliverToBoxAdapter(child: SizedBox(height: 28)),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**不使用 `shrinkWrap: true` ——** `SliverList.builder` 本身就是懒加载,不需要这个参数。
|
|||
|
|
|
|||
|
|
#### 方案 B:搜索防抖
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
Timer? _debounce;
|
|||
|
|
|
|||
|
|
void onSearchChanged(String value) {
|
|||
|
|
_debounce?.cancel();
|
|||
|
|
_debounce = Timer(const Duration(milliseconds: 180), () {
|
|||
|
|
setState(() {
|
|||
|
|
filter = value;
|
|||
|
|
});
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@override
|
|||
|
|
void dispose() {
|
|||
|
|
_debounce?.cancel();
|
|||
|
|
customUrl.dispose();
|
|||
|
|
super.dispose();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
180ms 防抖确保用户快速输入时不会每按一个键就触发一次全文过滤。
|
|||
|
|
|
|||
|
|
#### 方案 C:仓库列表改用 ExpansionTile
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
class _CollapsibleRepoSection extends StatelessWidget {
|
|||
|
|
@override
|
|||
|
|
Widget build(BuildContext context) {
|
|||
|
|
return Card(
|
|||
|
|
child: ExpansionTile(
|
|||
|
|
title: const Text('内置书源仓库'),
|
|||
|
|
subtitle: Text('${SourceManager.builtinRepos.length} 个仓库可用'),
|
|||
|
|
initiallyExpanded: false,
|
|||
|
|
children: [
|
|||
|
|
for (final repo in SourceManager.builtinRepos)
|
|||
|
|
ListTile(
|
|||
|
|
leading: const Icon(Icons.cloud_download_outlined),
|
|||
|
|
title: Text(repo.name),
|
|||
|
|
subtitle: Text(repo.description),
|
|||
|
|
trailing: FilledButton.tonal(
|
|||
|
|
onPressed: ...,
|
|||
|
|
child: Text(repo.isSubscription ? '订阅' : '导入'),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
],
|
|||
|
|
),
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、实施计划
|
|||
|
|
|
|||
|
|
### 阶段 1:P0 可用性修复(3–6 天)
|
|||
|
|
|
|||
|
|
| 天数 | 任务 | 涉及文件 |
|
|||
|
|
|:----:|------|----------|
|
|||
|
|
| 1–3 | **问题二:书源搜索链路修复** | |
|
|||
|
|
| | └ 方案 A:删除占位种子源,空列表首次启动 | `source_manager.dart` |
|
|||
|
|
| | └ 方案 B:`html` 包重写 CSS 选择器 + Isolate | `legado_rule_parser.dart`、`pubspec.yaml` |
|
|||
|
|
| | └ 方案 C:GBK/GB18030 编码异常处理 | `legado_engine.dart` |
|
|||
|
|
| | └ 方案 D:`_ruleType` 优先使用 `kind` 参数 | `legado_rule_parser.dart` |
|
|||
|
|
| | └ 方案 E:多源异常隔离(错误透传 UI) | `legado_engine.dart` |
|
|||
|
|
| | └ 方案 F:仓库镜像轮询 + 网络探测 | `source_manager.dart` |
|
|||
|
|
| | └ **测试:** 真实书源搜索回归(≥10 个不同源站点) | |
|
|||
|
|
| 4–6 | **问题四:Web 端 JSON → 可视化内容** | |
|
|||
|
|
| | └ 方案 A:CORS 中间件(10min) | `sakura_cloud/main.py` |
|
|||
|
|
| | └ 方案 B:CSP 修复(10min) | `sakura_cloud/api/middleware.py` |
|
|||
|
|
| | └ 方案 C:开发环境可选挂载 Vue dist | `sakura_cloud/main.py` |
|
|||
|
|
| | └ 方案 D:Nginx 生产部署配置 | 新建 `sakura_admin_web/nginx.conf` |
|
|||
|
|
| | └ 方案 E:GalleryBrowsePage + NovelReadPage + MangaViewerPage | `sakura_admin_web/src/views/app/` |
|
|||
|
|
| | └ **测试:** 浏览器 `/app` → 图片网格 → 点击作品 → 大图 → 分页 |
|
|||
|
|
|
|||
|
|
### 阶段 2:P1 体验稳定性修复(2–4 天)
|
|||
|
|
|
|||
|
|
| 天数 | 任务 | 涉及文件 |
|
|||
|
|
|:----:|------|----------|
|
|||
|
|
| 1–2 | **问题一:Feed 滚动稳定性(第一层必做)** | |
|
|||
|
|
| | └ AsyncNotifier 替代 FutureBuilder + 状态统一管理 | `feed_tab.dart` |
|
|||
|
|
| | └ 显式 ScrollController + dispose | `feed_tab.dart` |
|
|||
|
|
| | └ StatCard 固定高度 106px | `feed_tab.dart` |
|
|||
|
|
| | └ Refresh 状态统一入口(Riverpod provider) | `feed_tab.dart` + `providers.dart` |
|
|||
|
|
| | └ 第二层(按需):RawGestureDetector 手势方向判定 | `feed_tab.dart` |
|
|||
|
|
| | └ **测试:** Android 真机快速上下滚动 × 50 次 | |
|
|||
|
|
| 3–4 | **问题三:书源管理页 Sliver 重构** | |
|
|||
|
|
| | └ CustomScrollView + SliverAppBar 吸顶搜索栏 | `source_manager_page.dart` |
|
|||
|
|
| | └ SliverList.builder 懒加载 | `source_manager_page.dart` |
|
|||
|
|
| | └ ExpansionTile 折叠仓库列表 | `source_manager_page.dart` |
|
|||
|
|
| | └ 搜索防抖 180ms + dispose 清理 | `source_manager_page.dart` |
|
|||
|
|
| | └ **测试:** 导入 2200+ 源后滚动 + 搜索 | |
|
|||
|
|
|
|||
|
|
### 阶段 3:回归测试(1–2 天)
|
|||
|
|
|
|||
|
|
| 测试项 | 方法 |
|
|||
|
|
|--------|------|
|
|||
|
|
| Android 真机滚动 | feed_tab 快速上下滑 × 50 次,观察有无卡顿 |
|
|||
|
|
| 2200+ 书源压力测试 | 从"精选书源仓库"导入全量 → 搜索 → 启用/禁用单个源 → 滚动 |
|
|||
|
|
| Web 端 `/app` | Chrome + Firefox 访问 → 图片网格加载 → 分页翻页 |
|
|||
|
|
| Web 端 `/api` | 直接访问 API 路径 → 确认返回 JSON(正常行为) |
|
|||
|
|
| Web 端图片加载 | 检查 CSP 日志 → 确认无 `img-src` 拦截 |
|
|||
|
|
| 无书源首次启动 | 清除 SharedPreferences → 冷启动 APP → 确认显示引导 UI 而非假源 |
|
|||
|
|
|
|||
|
|
### 风险矩阵
|
|||
|
|
|
|||
|
|
| 风险 | 等级 | 缓解措施 |
|
|||
|
|
|------|:----:|----------|
|
|||
|
|
| 问题二中 CSS 选择器 `html` 包性能不足 | 中 | 保留正则降级路径,低端机自动切降级 |
|
|||
|
|
| 问题二中真实书源测试覆盖不足 | 高 | 选择 ≥10 个已知稳定的 Legado 源作为回归集 |
|
|||
|
|
| 问题一中 AsyncNotifier 迁移引入新问题 | 低 | 先写测试用例覆盖原有 5 种数据加载路径 |
|
|||
|
|
| 问题四中 Nginx 配置与现有部署冲突 | 中 | 提供独立配置文件和部署检查清单 |
|
|||
|
|
| 书源法律边界 | 高 | 客户端不内置任何仓库 URL 或规则,由用户自行导入 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
> **版本记录:**
|
|||
|
|
> - v1.0 (2026-06-16):初始版本
|
|||
|
|
> - v1.1 (2026-06-16):技术评审修订——修正延迟数字、shrinkWrap 陷阱、重定向误伤、补充 CORS/ScrollController/GBK 异常/Isolate
|
|||
|
|
> - v2.0 (2026-06-16):终版——优先级改为 P0/P1、问题二风险升级为 3–5 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划
|