# 四大问题完整修复方案(终版) > 更新日期: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 []; // 静默短路 } ``` 六个默认种子源全都没有搜索规则。不论用户是否"启用",搜索入口直接返回空。这些种子源是从设计之初就存在的占位符,但从未被替换为可用源。 #### 根因 2(阻断级):CSS 选择器仅支持 `...` 简单正则,不支持 class/ID/属性/后代 **文件:** `legado_rule_parser.dart` 第 86–96 行 ```dart List _cssFragments(String selector) { final tag = _selectorTag(selector); // 只取开头 a-zA-Z 部分作 tag if (tag == null) return const []; final pattern = RegExp('<$tag\\b[^>]*>.*?', ...); 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 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 _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> _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 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.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 todayArtworks; final List recentArtworks; final List recentNovels; final List> alerts; final Map stat; final String? error; } ``` 用 Riverpod `AsyncNotifier` 管理整个页面的数据加载。`build()` 只读取 `ref.watch(feedProvider)`,不调用 `_ensureFutures()`,不在 build 中创建 future。 **2. 显式 `ScrollController`** ```dart class _FeedTabState extends ConsumerState { 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(), (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 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划