26 KiB
四大问题完整修复方案(终版)
更新日期:2026-06-16 范围:Sakura Mobile (Flutter) + Sakura Cloud (FastAPI) + Sakura Admin Web (Vue.js) + Desktop GUI (Python) 版本:v2.0 — 调整优先级为 P0/P1 两级、修正问题二的风险边界和工期、问题一拆为两层修复、问题四拆为开发/生产两套方案、问题三补搜索防抖
目录
- 优先级总览
- P0-1:无法搜索本地不存在的图库(源不可用)
- P0-2:网页端显示 JSON 数据而非图片/小说/漫画
- P1-1:APP 发现页向上滚动卡在底部
- P1-2:导入源的位置排版有问题
- 实施计划
零、优先级总览
| 等级 | 问题 | 严重程度 | 工期 | 风险 |
|---|---|---|---|---|
| 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 行
LegadoSource(
name: '笔趣阁',
url: 'https://example.invalid/novel/biquge', // IANA 保留测试域名
type: 0, enabled: true,
// searchUrl、searchListRule —— 全部 null
),
LegadoEngine.search() 入口(第 36–39 行):
if (searchUrl == null || listRule == null) {
return const <UnifiedSearchResult>[]; // 静默短路
}
六个默认种子源全都没有搜索规则。不论用户是否"启用",搜索入口直接返回空。这些种子源是从设计之初就存在的占位符,但从未被替换为可用源。
根因 2(阻断级):CSS 选择器仅支持 <tag>...</tag> 简单正则,不支持 class/ID/属性/后代
文件: legado_rule_parser.dart 第 86–96 行
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 行
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 或规则:
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
dependencies:
html: ^0.15.5
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 中批量解析:
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 行
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
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 静默跳过,但错误信息被丢弃。改为:
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
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
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
"img-src 'self' data: blob: https: http:;"
"connect-src 'self' http://localhost:* ws://localhost:*;"
方案 C:开发环境可选挂载 Vue dist
# 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 配置示例:
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 横向翻页
路由注册:
// 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 对象:
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
class _FeedTabState extends ConsumerState<FeedTab> {
final ScrollController _scrollController = ScrollController();
@override
void dispose() {
_scrollController.dispose();
super.dispose();
}
}
外层 ListView 绑定此 controller。切换 tab 时通过 _scrollController.hasClients 检查位置有效性。
3. _StatCard 固定高度
SizedBox(
height: 106,
child: _StatCard(stat: stat),
),
通过 AnimatedSwitcher 平滑过渡内容而非跳变布局。
4. Refresh 状态统一管理
RefreshIndicator.onRefresh 调用 provider 的 ref.invalidate(feedProvider),由一个入口触发重载,不再散射到 5 个独立的 setState(null) 调用。
第二层:如果仍有横向列表抢手势(专项修复)
仅当第一层修复后,在部分设备上仍出现"在对角线滑动时外层垂直滚动丢失"的问题时,才实施此层:
对横向 _ArtworkStrip 的 ListView 外套方向判定:
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 吸顶搜索栏
@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:搜索防抖
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
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 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划