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

746 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 四大问题完整修复方案(终版)
> 更新日期: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 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划