Files
SakuraHub/docs/四大问题完整修复方案.md
2026-11-16 20:45:22 +08:00

26 KiB
Raw Permalink Blame History

四大问题完整修复方案(终版)

更新日期: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:无法搜索本地不存在的图库(源不可用)
  3. P0-2:网页端显示 JSON 数据而非图片/小说/漫画
  4. P1-1:APP 发现页向上滚动卡在底部
  5. 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 行

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 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划