first commit

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kunkunxiaomaoandClaude committed 2026-11-16 20:45:22 +08:00
commit 9c5fef1a4d
412 files changed
+94582

No files matched your search

+280
View File
@@ -0,0 +1,280 @@
# APK 下拉刷新 / 删除后页面不刷新 修复
**日期**: 2026-06-22
**问题**: 删除作品后页面不刷新;下拉刷新不生效,无法重新请求当前页数据
---
## 根因分析
### 根因 1:`RefreshIndicator` 放错位置,嵌套在 `FutureBuilder` 内部
`RefreshIndicator` 被放在 `FutureBuilder` 的 `builder` 闭包内。每次 `setState` 更新 `future` → `FutureBuilder` 重建 → `RefreshIndicator` 被销毁再创建 → 下拉手势/动画状态丢失。
**正常工作**的 `feed_tab.dart` 结构:
```
RefreshIndicator → ListView → FutureBuilder(内部)
```
**异常结构**(修复前):
```
FutureBuilder → RefreshIndicator → CustomScrollView
```
### 根因 2:缺少 `AlwaysScrollableScrollPhysics`
`CustomScrollView` 未设置 `physics: AlwaysScrollableScrollPhysics()`。数据少于一屏时不可滚动 → `RefreshIndicator` 无法探测下拉手势。
### 根因 3(核心):API 客户端缓存导致的"假刷新"
`api_client.dart` 的 `gallery()` 方法有 **30 分钟 SharedPreferences 缓存**:
```dart
// 修复前 - 每次都先查缓存
final cacheKey = _cacheKey('gallery', params);
final cached = await _readCache<List<dynamic>>(cacheKey);
if (cached != null) return cached; // ← 始终返回旧数据
```
刷新链路全追踪:
```
_refresh()
→ ref.invalidate(apiClientProvider) ✅ 创建新 SakuraApiClient
→ _load()
→ gallery()
→ _cacheKey('gallery', params) ❌ token 没变 → cache key 一样
→ _readCache(cacheKey) ❌ 命中 30 分钟前的缓存
→ 返回删除/修改前的旧数据 ❌ 表现:刷新无效
```
Token 不变 → `_cacheKey` 内 `token.hashCode` 不变 → **缓存 key 不变** → 永远返回缓存。即使 `ref.invalidate` 创建了新客户端实例也无效,因为缓存存在 SharedPreferences 中,跨实例共享。
---
## 修改文件清单(3 个文件)
| 文件 | 改动 |
|------|------|
| `sakura_mobile/lib/src/core/api_client.dart` | `gallery()` 加 `bypassCache` 参数 |
| `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | 结构调整 + 缓存穿透 + 删除刷新按钮 |
| `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` | 结构调整 + 删除刷新按钮 |
---
## 改动详情
### 一、`sakura_mobile/lib/src/core/api_client.dart`
#### `gallery()` 加 `bypassCache` 参数
**改动前**:
```dart
Future<List<dynamic>> gallery({
String? search,
String searchScope = 'all',
bool? isFavorite,
String? contentType,
String? sort,
int page = 1,
int limit = 60,
bool includeTotal = true,
}) async {
...
final cacheKey = _cacheKey('gallery', params);
final cached = await _readCache<List<dynamic>>(cacheKey);
if (cached != null) return cached;
final response = await dio.get('/api/v1/gallery', queryParameters: params);
final data = response.data['data']['items'] as List<dynamic>;
await _writeCache(cacheKey, data);
return data;
}
```
**改动后**:
```dart
Future<List<dynamic>> gallery({
String? search,
String searchScope = 'all',
bool? isFavorite,
String? contentType,
String? sort,
int page = 1,
int limit = 60,
bool includeTotal = true,
bool bypassCache = false, // ← 新增
}) async {
...
final cacheKey = _cacheKey('gallery', params);
if (!bypassCache) { // ← 新增:仅在非刷新时读缓存
final cached = await _readCache<List<dynamic>>(cacheKey);
if (cached != null) return cached;
}
final response = await dio.get('/api/v1/gallery', queryParameters: params);
final data = response.data['data']['items'] as List<dynamic>;
await _writeCache(cacheKey, data);
return data;
}
```
---
### 二、`sakura_mobile/lib/src/pages/tabs/gallery_tab.dart`
#### 改动 1:`_load()` 加 `forceRefresh` 参数,传递到 `gallery()`
**改动前**:
```dart
Future<List<Artwork>> _load({bool reset = true}) async {
if (reset) {
_page = 1;
_hasMore = true;
_items.clear();
selectedIds.clear();
selectionMode = false;
}
final rows = await ref.read(apiClientProvider).gallery(
search: search.text.trim().isEmpty ? null : search.text.trim(),
searchScope: searchScope,
isFavorite: favoritesOnly ? true : null,
contentType: _effectiveContentType,
sort: recentUpdatesOnly ? 'updated' : null,
page: _page,
limit: _pageSize,
includeTotal: false,
);
```
**改动后**:
```dart
Future<List<Artwork>> _load({bool reset = true, bool forceRefresh = false}) async {
if (reset) {
_page = 1;
_hasMore = true;
_items.clear();
selectedIds.clear();
selectionMode = false;
}
final rows = await ref.read(apiClientProvider).gallery(
search: search.text.trim().isEmpty ? null : search.text.trim(),
searchScope: searchScope,
isFavorite: favoritesOnly ? true : null,
contentType: _effectiveContentType,
sort: recentUpdatesOnly ? 'updated' : null,
page: _page,
limit: _pageSize,
includeTotal: false,
bypassCache: forceRefresh, // ← 新增:刷新时绕过缓存
);
```
#### 改动 2:`_refresh()` 改为 async,传递 `forceRefresh: true`
**改动前**:
```dart
void _refresh() {
setState(() {
future = _load();
});
}
```
**改动后**:
```dart
Future<void> _refresh() async {
ref.invalidate(apiClientProvider);
final f = _load(forceRefresh: true); // ← 绕过缓存
setState(() {
future = f;
});
await f; // ← RefreshIndicator 等 future 完成才停止动画
}
```
#### 改动 3:`RefreshIndicator` 移到 `FutureBuilder` 外层
**改动前**:
```dart
return FutureBuilder<List<Artwork>>(
future: future,
builder: (context, snapshot) {
...
return RefreshIndicator(
onRefresh: _refresh,
child: CustomScrollView(
controller: _scrollController,
slivers: [...],
),
);
},
);
```
**改动后**:
```dart
return RefreshIndicator(
color: const Color(0xFFD95A83),
onRefresh: _refresh,
child: FutureBuilder<List<Artwork>>(
future: future,
builder: (context, snapshot) {
...
return CustomScrollView(
controller: _scrollController,
physics: const AlwaysScrollableScrollPhysics(), // ← 新增
slivers: [...],
);
},
),
);
```
#### 改动 4:删除刷新 IconButton
**改动前**:
```dart
trailing: [
...
IconButton(
tooltip: '刷新',
onPressed: _refresh,
icon: const Icon(Icons.refresh),
),
],
```
**改动后**:
```dart
trailing: [
... // 刷新按钮已移除,统一使用下拉刷新
],
```
---
### 三、`sakura_mobile/lib/src/pages/tabs/novels_tab.dart`
同 gallery_tab 的改动 3、4(结构调整 + 删除按钮)。novels API 本身无缓存,无需 `bypassCache`。
---
## 修复后的刷新链路
```
用户下拉 → RefreshIndicator.onRefresh → _refresh()
→ ref.invalidate(apiClientProvider) ✅ 创建新客户端
→ _load(forceRefresh: true)
→ gallery(bypassCache: true) ✅ 跳过缓存
→ dio.get('/api/v1/gallery') ✅ 真实 HTTP 请求
→ _writeCache(cacheKey, newData) ✅ 写入新缓存
→ 返回服务器最新数据 ✅
→ setState({future: f}) ✅ FutureBuilder 拿到新 future
→ await f ✅ 等待完成,停止下拉动画
→ UI 展示最新数据 ✅ 删除/修改后的数据正确
```
## 构建产物
| 产物 | 路径 | 大小 |
|------|------|------|
| APK | `release/sakura.apk` | 66.8 MB |
| EXE | `dist/sakuradownloader.exe` | 63 MB |
+310
View File
@@ -0,0 +1,310 @@
# 云同步 401 自动刷新 Token 修复
**日期**: 2026-06-22
**问题**: 桌面端 `POST /api/v1/sync/check` 持续返回 401,无重试/续期机制
**根因**: `CloudSyncConfig` 只存 `access_token`,无 `refresh_token` 和自动续期逻辑
---
## 修改文件清单
| 文件 | 改动类型 |
|------|----------|
| `pixiv_app/core/cloud_sync.py` | 核心:加 refresh_token、401 自动刷新、token 更新回调 |
| `pixiv_app/gui/app.py` | 存储/加载/传递 refresh_token,回调持久化 |
| `pixiv_app/core/gallery_service.py` | 传递 refresh_token |
| `pixiv_app/core/origin_follow_sync.py` | 传递 refresh_token |
| `pixiv_app/core/x_media_service.py` | 传递 refresh_token |
---
## 改动详情
### 1. `pixiv_app/core/cloud_sync.py`
#### 1.1 `CloudSyncConfig` — 加 `refresh_token` 字段
**改动前**:
```python
@dataclass
class CloudSyncConfig:
base_url: str
access_token: str
chunk_size: int = 5 * 1024 * 1024
timeout: float = 60.0
```
**改动后**:
```python
@dataclass
class CloudSyncConfig:
base_url: str
access_token: str
refresh_token: str = ""
chunk_size: int = 5 * 1024 * 1024
timeout: float = 60.0
```
#### 1.2 `SakuraCloudClient.__init__` — 加 `on_token_refreshed` 回调
**改动前**:
```python
class SakuraCloudClient:
def __init__(self, config: CloudSyncConfig) -> None:
self.config = config
self.base_url = config.base_url.rstrip("/")
self.session = requests.Session()
self.session.headers.update({"Authorization": f"Bearer {config.access_token}"})
```
**改动后**:
```python
class SakuraCloudClient:
def __init__(self, config: CloudSyncConfig, *, on_token_refreshed: callable | None = None) -> None:
self.config = config
self.base_url = config.base_url.rstrip("/")
self.session = requests.Session()
self.session.headers.update({"Authorization": f"Bearer {config.access_token}"})
self._on_token_refreshed = on_token_refreshed
self._refresh_lock = False # 防止并发刷新
```
#### 1.3 `_post` — 加 401 自动刷新 + 重试
**改动前**:
```python
def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
response = self.session.post(f"{self.base_url}{path}", json=payload, timeout=self.config.timeout)
return self._unwrap(response)
```
**改动后**:
```python
def _post(self, path: str, payload: dict[str, Any], *, _retry_on_401: bool = True) -> dict[str, Any]:
response = self.session.post(f"{self.base_url}{path}", json=payload, timeout=self.config.timeout)
if response.status_code == 401 and _retry_on_401:
refreshed = self._try_refresh_token()
if refreshed:
return self._post(path, payload, _retry_on_401=False)
return self._unwrap(response)
```
#### 1.4 新增 `_try_refresh_token` 方法
**新增代码**:
```python
def _try_refresh_token(self) -> bool:
"""用 refresh_token 换取新的 access_token。成功返回 True 并通知上层持久化。"""
refresh = self.config.refresh_token.strip()
if not refresh or self._refresh_lock:
return False
self._refresh_lock = True
try:
resp = self.session.post(
f"{self.base_url}/api/v1/auth/refresh",
json={"refresh_token": refresh},
timeout=self.config.timeout,
)
if resp.status_code != 200:
return False
body = resp.json()
data = body.get("data", body) if isinstance(body, dict) else {}
new_access = (data.get("access_token") or "").strip()
new_refresh = (data.get("refresh_token") or "").strip()
if not new_access:
return False
self.config.access_token = new_access
self.session.headers.update({"Authorization": f"Bearer {new_access}"})
if new_refresh:
self.config.refresh_token = new_refresh
if self._on_token_refreshed:
try:
self._on_token_refreshed(self.config.access_token, self.config.refresh_token)
except Exception:
pass # 持久化失败不阻塞业务
return True
except Exception:
return False
finally:
self._refresh_lock = False
```
---
### 2. `pixiv_app/gui/app.py`
#### 2.1 新增 `cloud_refresh_token` 实例变量
**改动前**:
```python
self.cloud_access_token = ""
```
**改动后**:
```python
self.cloud_access_token = ""
self.cloud_refresh_token = ""
```
#### 2.2 `get_cloud_sync_config` — 加 `refresh_token`
**改动前**:
```python
def get_cloud_sync_config(self) -> dict:
return {
"enabled": bool(self.cloud_sync_enabled_var.get()),
"base_url": (self.cloud_base_url or DEFAULT_CLOUD_API).strip(),
"access_token": self.cloud_access_token.strip(),
}
```
**改动后**:
```python
def get_cloud_sync_config(self) -> dict:
return {
"enabled": bool(self.cloud_sync_enabled_var.get()),
"base_url": (self.cloud_base_url or DEFAULT_CLOUD_API).strip(),
"access_token": self.cloud_access_token.strip(),
"refresh_token": self.cloud_refresh_token.strip(),
}
```
#### 2.3 登录成功时捕获 `refresh_token`
**改动前**:
```python
token = data.get("data", {}).get("access_token")
if token:
self.cloud_access_token = str(token).strip()
self.enqueue_ui(self.cloud_status_var.set, "登录成功,云同步凭证已自动保存")
```
**改动后**:
```python
token = data.get("data", {}).get("access_token")
if token:
self.cloud_access_token = str(token).strip()
refresh = (data.get("data", {}).get("refresh_token") or "")
if refresh:
self.cloud_refresh_token = str(refresh).strip()
self.enqueue_ui(self.cloud_status_var.set, "登录成功,云同步凭证已自动保存")
```
#### 2.4 `restore_session` 加载 refresh_token
**改动前**:
```python
self.cloud_access_token = str(cloud.get("access_token") or "")
if self.cloud_access_token:
```
**改动后**:
```python
self.cloud_access_token = str(cloud.get("access_token") or "")
self.cloud_refresh_token = str(cloud.get("refresh_token") or "")
if self.cloud_access_token:
```
#### 2.5 新增 `_on_cloud_token_refreshed` 回调 + 更新 `create_sync_manager`
**改动前**:
```python
def create_sync_manager(self) -> SyncManager | None:
config = self.get_cloud_sync_config()
if not (config.get("enabled") and config.get("base_url") and config.get("access_token")):
return None
return SyncManager(
SakuraCloudClient(
CloudSyncConfig(
base_url=str(config["base_url"]),
access_token=str(config["access_token"]),
)
)
)
```
**改动后**:
```python
def _on_cloud_token_refreshed(self, new_access: str, new_refresh: str) -> None:
"""Token 自动刷新后更新内存并持久化到本地会话文件。"""
self.cloud_access_token = new_access
if new_refresh:
self.cloud_refresh_token = new_refresh
self.enqueue_ui(self.cloud_status_var.set, "云同步 Token 已自动续期")
self.enqueue_ui(self.save_session)
def create_sync_manager(self) -> SyncManager | None:
config = self.get_cloud_sync_config()
if not (config.get("enabled") and config.get("base_url") and config.get("access_token")):
return None
return SyncManager(
SakuraCloudClient(
CloudSyncConfig(
base_url=str(config["base_url"]),
access_token=str(config["access_token"]),
refresh_token=str(config.get("refresh_token") or ""),
),
on_token_refreshed=self._on_cloud_token_refreshed,
)
)
```
---
### 3. `pixiv_app/core/gallery_service.py`
**改动前**:
```python
return SyncManager(
SakuraCloudClient(
CloudSyncConfig(
base_url=base_url,
access_token=access_token,
)
)
)
```
**改动后**:
```python
return SyncManager(
SakuraCloudClient(
CloudSyncConfig(
base_url=base_url,
access_token=access_token,
refresh_token=str(cloud.get("refresh_token") or ""),
)
)
)
```
---
### 4. `pixiv_app/core/origin_follow_sync.py`
同 gallery_service.py,仅加 `refresh_token` 行。
### 5. `pixiv_app/core/x_media_service.py`
同 gallery_service.py,仅加 `refresh_token` 行。
---
## 工作流程
```
POST /api/v1/sync/check
├── 200 → 正常返回
└── 401
├── refresh_token 为空? → 抛异常(旧 token 永久失效)
├── 正在刷新中? → 抛异常(防并发)
└── POST /api/v1/auth/refresh
├── 200 → 更新内存 token → 回调持久化 → 重试原请求
└── 非200 → 抛异常(refresh 也过期了,需重新登录)
```
## 兼容性
- `refresh_token` 默认值 `""` — 不传也能正常工作(旧行为)
- `on_token_refreshed` 可选 — 不传也不影响其他调用方
- 现有的 `ConfigCloudSync` 构造方式全兼容
File diff suppressed because it is too large. Load diff
+492
View File
@@ -0,0 +1,492 @@
# APP 端问题分析与解决方案
> 更新日期:2026-06-14
> 范围:Sakura Mobile (Flutter) + Sakura Cloud (FastAPI 后端) + Sakura Downloader (Python 桌面端)
> 说明:本文档仅提供问题分析和修改方案,不包含实际代码改动。
---
## 问题一:APP 莫名其妙跳转到 "dakura" 用户
### 问题现象
APP 在使用过程中会突然切换到 "dakura" 用户身份,导致看到的是其他用户的数据而并非自己的内容。
### 根因分析
经过对全部代码的排查,问题出在 **Session 持久化缺少用户隔离机制**。涉及以下关键位置:
#### 1. 移动端 Session 存储无用户绑定 (`sakura_mobile/lib/src/core/session.dart`)
**文件位置:** `sakura_mobile/lib/src/core/session.dart` 第 44-52 行
```dart
static const _baseUrlKey = 'sakura.baseUrl';
static const _accessTokenKey = 'sakura.accessToken';
Future<void> _load() async {
final prefs = await SharedPreferences.getInstance();
state = SessionState(
baseUrl: prefs.getString(_baseUrlKey) ?? defaultCloudApi,
accessToken: prefs.getString(_accessTokenKey) ?? '',
);
```
**问题:** `SharedPreferences` 使用固定 key `sakura.accessToken` 存储 token,不绑定任何用户标识。当存在以下情况时会发生串号:
- 同一设备上先后登录过不同账号(如 "dakura" 和当前用户)
- SharedPreferences 中的旧 token 未完全清除
- App 从后台恢复时读取了旧的/缓存的 token
- 多进程/多任务环境下 SharedPreferences 跨进程同步延迟
#### 2. 登录流程缺少旧 Session 清理 (`sakura_mobile/lib/src/core/session.dart` 第 70-86 行)
```dart
Future<void> login(String usernameOrEmail, String password) async {
state = state.copyWith(loading: true, error: null);
try {
final api = SakuraApiClient(baseUrl: state.baseUrl);
final tokens = await api.login(usernameOrEmail, password);
final accessToken = tokens['access_token']?.toString() ?? '';
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_accessTokenKey, accessToken);
```
**问题:** 登录时直接覆盖 `_accessTokenKey`,但如果 SharedPreferences 写入失败或未完全刷盘,旧 token 仍然存在。没有先清除旧 token 再写入新 token 的原子操作。
#### 3. Web 端使用 sessionStorage 同样缺少隔离 (`sakura_admin_web/src/stores/session.ts` 第 15-30 行)
```typescript
const ACCESS_KEY = "sakura_access_token";
const REFRESH_KEY = "sakura_refresh_token";
export const authState = reactive({
accessToken: sessionStorage.getItem(ACCESS_KEY) || "",
refreshToken: sessionStorage.getItem(REFRESH_KEY) || "",
user: null as CurrentUser | null,
loading: false
});
```
**问题:** sessionStorage 的 key 是固定的,同一浏览器不同标签页可能共享或冲突。
#### 4. 桌面端 Session 文件共享 (`pixiv_app/core/paths.py` 和 `pixiv_app/core/auth.py`)
Session 文件 `pixiv_app_session.json` 保存的是单一的 cookie 和 cloud_sync 配置,没有对应用户上下文。如果云端切换了用户但本地 session 文件未同步更新,可能导致不一致。
### 解决方案
#### 方案 A:Token 绑定用户名校验(推荐)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/session.dart` | 第 44-52 行 | 在 `_load()` 后调用 `/api/v1/users/me` 校验 token 归属用户 |
| `sakura_mobile/lib/src/core/session.dart` | 第 70-86 行 | `login()` 时先清除旧 token,写入后立即验证 |
| `sakura_mobile/lib/src/core/session.dart` | 新增方法 | 添加 `_validateAndFixSession()` 方法,对比登录用户名与 token 归属 |
**具体做法:**
1. 在 `SessionController._load()` 中,加载 token 后立即调用 `api.me()` 获取当前 token 对应的用户名
2. 将用户名也存入 SharedPreferences,key 使用 `sakura.username`
3. 每次 `_load()` 后比对 `sakura.username` 与 `me()` 返回的 username,不一致则清除旧 token 强制重新登录
4. `login()` 成功后立即存储用户名,防止与旧数据混淆
#### 方案 B:增加 Token 失效主动检测
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/api_client.dart` | 第 12-47 行 | 在 `SakuraApiClient` 中增加 401 拦截器 |
| `sakura_mobile/lib/src/core/session.dart` | 第 100-108 行 | `logout()` 时增加确认清理 SharedPreferences 全部 key |
**具体做法:**
1. 通过 Dio 拦截器全局捕获 401/403 响应,自动清除 token 并跳转登录页
2. 在 `logout()` 中不单删除 `_accessTokenKey`,同时清理所有 sakura 相关 key
3. 增加 `clearAllSakuraData()` 方法用于完全重置
#### 方案 C:服务端 Token 版本号机制
**修改位置:** 后端 `sakura_cloud/` (FastAPI) 相关认证模块
**具体做法:**
1. 在用户表增加 `token_version` 字段
2. 每次重新登录时 token_version +1
3. JWT payload 中嵌入 token_version
4. 验证 token 时比对版本号,旧版本 token 直接拒绝
5. 确保用户登出后旧 token 彻底失效
---
## 问题二:发现页查询过慢,需要加载缓冲或优化
### 问题现象
APP 打开"发现"页(FeedTab)时,整个页面长时间白屏/转圈,用户体验差。
### 根因分析
#### 1. 五个 API 串行阻塞全部内容 (`sakura_mobile/lib/src/pages/tabs/feed_tab.dart`)
**文件位置:** `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 20-26 行
```dart
return FutureBuilder<List<Object?>>(
future: Future.wait([
api.galleryStat(), // 统计总数
api.galleryFeed(mode: 'created', limit: 36), // 今日新增
api.galleryFeed(mode: 'recent', limit: 24), // 最近更新
api.recentNovels(limit: 12), // 最近小说
api.unreadAlerts(limit: 12), // 未读提醒
]),
```
**问题:**
- `Future.wait` 等待所有 5 个请求完成才渲染页面
- 任一接口慢(尤其是 `galleryStat()` 和 `galleryFeed()`),整个发现页都会卡住
- `galleryStat()` 可能后端做了全表 COUNT,数据量大时耗时数秒
#### 2. 后端 gallery/feed 查询可能缺少优化
**文件位置:** 后端 API(`sakura_cloud/` 目录下的 gallery/feed 路由)
`galleryFeed` 接口通常对应:
- `mode: 'created'` → 按创建时间排序的最近作品
- `mode: 'recent'` → 按更新时间排序
如果后端 SQL 查询缺少合适的复合索引,或者做了全表扫描 + JOIN 多表,在数据量上千条后就会明显变慢。典型慢查询模式:
```sql
-- 可能的慢查询(缺少索引或 JOIN 过多)
SELECT a.*, ar.name, tc.thumbnail_path, ...
FROM artworks a
LEFT JOIN artists ar ON ...
LEFT JOIN thumbnail_cache tc ON ...
LEFT JOIN artwork_files af ON ...
LEFT JOIN favorites fav ON ...
ORDER BY a.created_at DESC
LIMIT 36
```
**对比本地库查询** (`pixiv_app/core/gallery_service.py` 第 96-134 行) 同样有类似的多表 LEFT JOIN + GROUP BY + 复合搜索条件,这在 SQLite 上尤其慢:
```python
total = library.connection.execute(
f"SELECT COUNT(DISTINCT a.artwork_id) AS total FROM artworks a {joins} {where_sql}",
params,
).fetchone()["total"]
```
先 COUNT 再 SELECT,等于两次大查询。
#### 3. 图片缩略图同步加载阻塞渲染
**文件位置:** `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 385-389 行
```dart
CachedNetworkImage(
imageUrl: thumbUrl,
httpHeaders: api.authHeaders(),
fit: BoxFit.cover,
),
```
**问题:** 虽然使用了 `CachedNetworkImage` 做缓存,但如果后端 `thumbnail_url` 指向的是需要实时生成或大文件的原图,加载会很慢;且横向滚动的 `ListView` 会一次性构建多个图片 widget,造成网络拥塞。
### 解决方案
#### 方案 A:渐进式加载 + 骨架屏(推荐,前端改动最小)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 20-26 行 | 将 `Future.wait` 拆分为独立请求,每个区块独立加载 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 62-137 行 | 为每个 `_ArtworkStrip`、`_NovelStrip`、`_AlertStrip` 增加独立的 loading/skeleton 状态 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 新增组件 | 增加 `_SkeletonStrip` 骨架屏组件 |
**具体做法:**
1. 不再使用单个 `FutureBuilder` + `Future.wait`,改为每个 section 独立使用 `FutureBuilder`
2. 统计卡片(`_TodayUpdateCard` 和 `_StatCard`)优先加载
3. 各内容条(插画、漫画、小说、提醒)各自独立加载,失败的只影响自己
4. 加载中的条显示 shimmer 骨架屏而非空白
5. `galleryStat()` 如果慢,可设置 3 秒超时,超时则降级显示 "--"
#### 方案 B:后端增加 feed 缓存表(推荐,解决根本问题)
**修改位置:** 后端 `sakura_cloud/`
**具体做法:**
1. 新增 `feed_cache` 表:
```sql
CREATE TABLE feed_cache (
user_id UUID NOT NULL,
feed_type VARCHAR(32) NOT NULL, -- 'created', 'recent', 'stat'
payload_json JSONB NOT NULL,
generated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (user_id, feed_type)
);
```
2. 在每次上传新作品、同步关注的定时任务完成后,异步刷新 feed_cache
3. `/api/v1/gallery/feed` 和 `/api/v1/gallery/stat` 优先从 `feed_cache` 读取
4. 缓存有效期设为 5-10 分钟,过期后后台异步刷新,当前请求仍返回旧缓存
5. 如果缓存不存在,降级为直接查询(首次慢但后续快)
#### 方案 C:本地 SQLite 缓存 + 增量同步(移动端离线方案)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/api_client.dart` | 新增方法 | 增加本地缓存读写方法 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 20 行 | 优先读本地缓存,后台静默刷新 |
**具体做法:**
1. 移动端使用 `sqflite` 或 `drift` 建立轻量本地库
2. 发现页数据缓存到本地,设置 30 分钟有效期
3. 打开发现页时先展示缓存数据(秒开),同时后台请求新数据
4. 新数据到达后平滑替换(`AnimatedSwitcher` 已就位)
5. 支持下拉强制刷新(`RefreshIndicator` 已就位)
#### 方案 D:优化后端 gallery/feed 查询语句
**修改位置:** 后端 `sakura_cloud/api/v1/` 中 gallery/feed 相关路由
**具体做法:**
1. 分析慢查询日志,定位具体慢的 SQL
2. 为 `artworks` 表增加复合索引:
```sql
CREATE INDEX idx_artworks_user_created ON artworks(user_id, created_at DESC);
CREATE INDEX idx_artworks_user_updated ON artworks(user_id, updated_at DESC);
```
3. 将 COUNT + SELECT 两次查询合并为一次(用窗口函数或子查询)
4. 限制 `galleryStat()` 的统计精度,超过 10000 条时显示 "10000+"
5. 对缩略图 URL 确保使用 CDN 或 Nginx 静态文件服务,而非 Django/FastAPI 流式响应
---
## 问题三:提醒中心用户更新检测问题
### 问题现象
1. **最近提醒显示的并非实际关注的作者名字**,而是作者 ID 数字
2. **已关注的作者有更新但未检测到**,提醒中心未生成新提醒
### 根因分析
#### 1. 提醒标题使用 author_id 而非 author_name
**文件位置:** `pixiv_app/core/gallery_service.py` 第 588-613 行
```python
def _create_cloud_pixiv_update_alerts(self, artist_id: int, work_ids: list[int]) -> int:
...
for work_id in work_ids:
try:
manager.client.create_alert(
{
"platform": "pixiv",
"creator_id": str(int(artist_id)),
"title": f"Pixiv 作者 {int(artist_id)} 更新了作品 {int(work_id)}",
# ↑↑↑ 问题在这里:用的是 author_id 数字,而非 author name
"body": "你关注的 Pixiv 作者有新作品了",
...
}
)
```
**问题详解:**
- `_create_cloud_pixiv_update_alerts` 没有接收 `artist_name` 参数
- 调用它的 `sync_followed_artists`(第 505-586 行)虽然能从 `library` 查到作者信息,但没传给 alert 创建函数
- 导致提醒标题变成 "Pixiv 作者 123456 更新了作品 789012",用户看到的是一串数字
- 移动端 `reminder_center_page.dart` 直接展示 `alert['title']`,所以显示的是数字 ID
#### 2. 关注作者有更新但未检测到
**文件位置:** `pixiv_app/core/gallery_service.py` 第 505-586 行
```python
def sync_followed_artists(self, *, cookie, max_new_per_artist=20, download=True, save_root="Sakura_Downloads"):
...
for row in followed:
artist_id = int(row["artist_id"])
# 获取已存在的作品 ID
existing = {
int(item["artwork_id"])
for item in library.connection.execute(
"SELECT artwork_id FROM artworks WHERE artist_id = ? AND type IN ('illust', 'manga')",
(artist_id,),
).fetchall()
}
# 获取远程作品 ID
_, work_ids = fetch_user_work_ids(user_id=artist_id, cookie=cookie)
# 只取本地没有的
new_ids = [work_id for work_id in work_ids if work_id not in existing][:max_new_per_artist]
```
**问题详解:**
- `fetch_user_work_ids` 需要有效的 Pixiv Cookie,如果 Cookie 已过期,API 调用静默失败
- 对比逻辑只看 `existing` 中的 artwork_id,但如果作品之前下载失败、入库未完成,可能漏掉
- `mark_artist_synced(artist_id, error=str(exc))` 在异常时记录了错误但未区分错误类型(Cookie 过期 vs 网络错误 vs 限流)
- 没有"最近检查时间"的限流机制 —— 如果短时间内多次同步同一个作者,每次都做全量对比
#### 3. 检查完成后未更新 `last_checked_at`
**文件位置:** `pixiv_app/core/library.py` 第 592-603 行
```python
def mark_artist_synced(self, artist_id: int, *, error: str = "") -> None:
with self.connection:
self.connection.execute(
"""
INSERT INTO followed_artists (artist_id, enabled, last_synced_at, last_error)
VALUES (?, 1, CURRENT_TIMESTAMP, ?)
ON CONFLICT(artist_id) DO UPDATE SET
last_synced_at = CURRENT_TIMESTAMP,
last_error = excluded.last_error
""",
(artist_id, error),
)
```
**问题:** `last_synced_at` 只在本地 SQLite 更新,**没有同步到云端** follows 表的 `last_checked_at`。移动端提醒中心展示的是云端 follows 数据:
**文件位置:** `sakura_mobile/lib/src/pages/reminder_center_page.dart` 第 22-27 行
```dart
Future<_ReminderCenterData> _load() async {
final api = ref.read(apiClientProvider);
final results = await Future.wait<Object?>([
api.me(),
api.follows(enabled: true), // ← 从云端读取 follows
api.alerts(limit: 50), // ← 从云端读取 alerts
]);
```
**问题详解:**
- 移动端显示的 `last_checked_at` 来自云端 follows 表
- 桌面端 `_upsert_cloud_follow` 只更新了 creator 基本信息,**没有更新 `last_checked_at`**
- 所以云端看到的"最近检查"时间永远是旧的甚至为空
- 用户无法判断哪个作者实际上被检查过
#### 4. Alert 创建没有去重
**文件位置:** `pixiv_app/core/gallery_service.py` 第 588-613 行
```python
for work_id in work_ids:
try:
manager.client.create_alert({...})
created += 1
except Exception:
continue
```
**问题:**
- 每次同步都会为同一个 work_id 创建新的 alert
- 如果多次同步同一批作品,会产生大量重复提醒
- 没有检查 "这个 work_id 是否已经发过 alert"
### 解决方案
#### 方案 A:修复 Alert 标题——传入作者名(推荐,最小改动)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 588 行 | `_create_cloud_pixiv_update_alerts` 增加 `artist_name` 参数 |
| `pixiv_app/core/gallery_service.py` | 第 562-565 行 | `sync_followed_artists` 传入作者名 |
| `pixiv_app/core/gallery_service.py` | 第 599 行 | 修改 title 使用作者名 |
**具体做法:**
在 `sync_followed_artists` 方法中,从 followed_artists 或 artists 表获取作者名:
```python
# 第 527-538 行之间,获取 followed 列表时同时获取 name
followed = library.connection.execute(
"SELECT fa.artist_id, COALESCE(NULLIF(fa.name,''), NULLIF(ar.name,''), '') AS name "
"FROM followed_artists fa "
"LEFT JOIN artists ar ON ar.artist_id = fa.artist_id "
"WHERE fa.enabled = 1 ORDER BY fa.artist_id"
).fetchall()
```
然后修改 `_create_cloud_pixiv_update_alerts` 签名:
```python
def _create_cloud_pixiv_update_alerts(
self, artist_id: int, work_ids: list[int], artist_name: str = ""
) -> int:
```
title 改为:
```python
"title": f"Pixiv 作者 {artist_name or str(artist_id)} 更新了 {len(work_ids)} 个新作品"
```
#### 方案 B:同步云端 follows 的检查状态
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 556-559 行 | `mark_artist_synced` 之后同步更新云端 follows 的 `last_checked_at` |
| `pixiv_app/core/cloud_sync.py` | 第 167-168 行 | `upsert_follow` 增加 `last_checked_at` 和 `latest_published_at` 字段 |
| `pixiv_app/core/gallery_service.py` | 第 415-447 行 | `_upsert_cloud_follow` 增加更新时间戳参数 |
**具体做法:**
1. 在 `_upsert_cloud_follow` 方法中增加 `last_checked_at` 和 `latest_published_at` 参数
2. 每次同步完一个作者后,调用 `_upsert_cloud_follow` 更新云端状态
3. 在云端 follows API 的 upsert 逻辑中接受并存储这些时间字段
4. 移动端 `reminder_center_page.dart` 中 `_FollowTile` 就能显示正确的"最近检查"时间
#### 方案 C:Alert 去重 & 按作者聚合
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 588-613 行 | 重构 `_create_cloud_pixiv_update_alerts` 逻辑 |
| 后端 `sakura_cloud/api/v1/follows.py` | alert 创建路由 | 增加去重逻辑 |
**具体做法:**
1. 将每个作者的多个新作品合并为**一条聚合 alert**,而非每个作品一条
2. Alert 的 `source_id` 使用 `f"{artist_id}:{min(work_ids)}:{max(work_ids)}"` 生成唯一标识
3. 创建 alert 前先检查是否存在相似 alert(同一作者 + 同一天内)
4. 如果存在则更新而非新建
5. title 格式改为:`"你关注的 {作者名} 更新了 {N} 个新作品"`
#### 方案 D:增加关注作者更新状态页面
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/pages/reminder_center_page.dart` | 第 350-371 行 | 已关注作者列表增加"手动检查更新"按钮 |
| 后端新增接口 | - | `POST /api/v1/follows/{follow_id}/check` 触发单作者更新检测 |
**具体做法:**
1. 在已关注作者列表中为每个作者增加状态标识:
- 🟢 最近 24h 内检查过
- 🟡 24h-7d 内检查过
- 🔴 超过 7 天未检查
2. 增加"手动检查"按钮,调用后端触发单个作者的更新检测
3. 检查完成后自动刷新提醒列表
---
## 总结优先级
| 优先级 | 问题 | 推荐方案 | 改动范围 | 预期效果 |
|--------|------|----------|----------|----------|
| P0 紧急 | 跳转到 dakura 用户 | 方案 A:Token 绑定用户名 | 移动端 session.dart | 根除串号问题 |
| P0 紧急 | Alert 显示数字而非作者名 | 方案 A:传入作者名 | gallery_service.py | 提醒可读 |
| P1 高 | 发现页加载慢 | 方案 A + B:渐进加载 + feed_cache | feed_tab.dart + 后端 | 首屏从 3-5s 降到 <1s |
| P1 高 | 关注作者未检测更新 | 方案 B:同步检查状态到云端 | gallery_service.py + cloud_sync.py | 状态准确可追溯 |
| P2 中 | Alert 重复创建 | 方案 C:去重 + 聚合 | gallery_service.py + 后端 | 减少重复提醒 |
| P2 中 | 查询性能优化 | 方案 D:SQL 索引 | 后端数据库 | 查询耗时降低 50%+ |
@@ -0,0 +1,738 @@
# Legado 规则引擎重构 — 分阶段实施方案
> 日期:2026-06-21
> 基于:源码架构总结 + 截图问题诊断 + 方案文档反馈
> 涉及:`legado_rule_parser.dart`、`legado_engine.dart`、`legado_models.dart`
> 原则:不改 UI 层,只在 core 层动刀;前 4 步零新依赖。
---
## 一、问题根因定性与实施顺序纠偏
### 1.1 截图 Bug ↔ 真实根因对照
| 截图 | 现象 | 代码层面的真实原因 |
|------|------|-------------------|
| 截图3 | "这一章还没有找到漫画页面" | `fetchChapterContent()` → `contentRule` → `RuleParser` 只认 CSS/JSON/Regex 三种前缀,**包子漫画5 的 `contentRule` 使用了 `@tag.img@src` / `##` / `&&` 等链式语法**,`_safeSelect()` 返回空串,`rawHtml` 兜底也没触发。 |
| 截图4 | "未知作者" / 封面空白 | `bookInfoAuthorRule` / `bookInfoCoverRule` 同上,规则语法不被 `RuleParser` 支持。 |
| 截图1 | "书籍详情加载失败" | `fetchBookInfo()` 整体 try/catch 后只设 `infoError`,不区分"网络不通"还是"规则不支持"。 |
| 搜索 `unknown:none` | 错误消息原样展示 | `_shortError()` 已修好(源码已含完整中文映射),这个 bug 已不存在于当前源码。 |
### 1.2 原方案步骤的纠偏
原方案第 1 步是「支持 URL,{method,body,headers}」,但实际上:
- `_buildSearchRequest()` 已有 GET/POST 分支
- `_applySearchTemplate()` 已支持 12 种占位符变体
- `fromJson` 解析 `header` 已支持 Map / JSON 字符串 / 冒号分隔行三种格式
**请求层不是最优先的问题。最优先的是 RuleParser 不支持 Legado 链式规则语法。**
### 1.3 修正后的实施顺序
```
第1步:rawHtml 兜底扫描 + script 变量扫描 ← 零成本,立刻修复截图3
第2步:RuleParser 支持 @tag/@text/@html/@src 链式语法 ← 解锁包子漫画5等核心书源
第3步:支持 ## 替换、|| 备选、&& 拼接 ← 兼容更多规则变体
第4步:fetchBookInfo / fetchToc 失败时区分错误类型 ← 解决截图1
第5步:JS 特判(newImgs / imageList 等高频变量) ← 覆盖 60%+ JS 规则,零依赖
第6步:@put / @get 上下文变量 ← 跨规则传值
第7步:书源兼容度检测 UI ← 用户体验闭环
第8步:完整 JS 引擎(flutter_js / quickjs) ← 最后做,覆盖剩余 40%
```
**前 4 步不需要引入任何新依赖,只在 `legado_rule_parser.dart` 和 `legado_engine.dart` 里改。**
---
## 二、总体架构重构方案
### 2.1 不要继续往 RuleParser 里塞逻辑
当前 `RuleParser`(262 行)已经承担了 CSS / JSONPath / Regex 三种解析路径,再往里面加链式语法会导致它变成无法维护的千行怪物。
**建议拆成三层**:
```
请求层 ── LegadoRequestBuilder ── 构建 URL、headers、body、编码
规则层 ── LegadoRuleExecutor ── 链式规则执行引擎
检测层 ── SourceCompatChecker ── 导入时打兼容度标签
```
```
┌──────────────────────────────────────────────────┐
│ LegadoEngine │
│ (对外 API:search / fetchBookInfo / fetchToc / │
│ fetchChapterContent 不变) │
├──────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────┐ │
│ │LegadoRequestBuilder│ │ LegadoRuleExecutor │ │
│ │· buildSearchUrl │ │· select() │ │
│ │· buildRequest │ │· selectList() │ │
│ │· encodeKeyword │ │· execChain() 🆕 │ │
│ │· applyTemplate │ │· applyReplace() 🆕 │ │
│ └──────────────────┘ │· extractImages() 🆕 │ │
│ │· scanScriptVars() 🆕 │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ RuleParser (保留) │ │
│ │ CSS / JSON / Regex │ │
│ │ 不改内部,只当底层 │ │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────┘
```
### 2.2 核心原则
1. **LegadoEngine 对外 API 不动**。`search()` / `fetchBookInfo()` / `fetchToc()` / `fetchChapterContent()` 签名不变,UI 层零改动。
2. **RuleParser 降级为底层原子工具**。它继续支持 CSS / JSONPath / Regex 三种基础解析,但不理解链式语法。所有链式逻辑放在 `LegadoRuleExecutor` 里。
3. **新规则执行器按优先级链执行**。每条规则被解析为一条 **执行链 (execChain)**,按序执行,任意一步返回空就终止并返回空。
---
## 三、第 1 步:rawHtml 兜底扫描 + script 变量扫描
> 目标:不改 RuleParser,在 `fetchChapterContent()` 和 `fetchImageUrls()` 里补兜底逻辑。
### 3.1 问题
当 `contentRule` 为空或解析失败时,当前代码回到 `_htmlToText(body)` 或 `_extractImageUrls(body)` 暴力扫描 HTML。但如果漫画图片 URL 藏在 `<script>` 的 JS 变量里(如 `var newImgs = ["url1","url2"]`),暴力扫描 `<img>` 标签找不到任何东西。
### 3.2 修改位置
`legado_engine.dart` 中的 `fetchChapterContent()` 和 `_extractImageUrls()`。
### 3.3 逻辑
```
extractImagesWithFallback(String rawHtml, String baseUrl):
1. 先用 RuleParser 走 contentRule → 语法错误或结果为空 → 进入兜底
2. 兜底 1:扫描 HTML img 标签
RegExp: <img[^>]+(?:src|data-src|data-original|data-srcset)=["']([^"']+)["']
同时提取 srcset 中的备选 URL
3. 兜底 2:扫描常见 JS 变量
按优先级依次尝试:
newImgs = [...]
imageList = [...]
chapterImages = [...]
page_url = ...
pics = [...]
imgData = [...]
chapterData.images = [...]
km5_img_url = ...
result.imageList = ...
提取方式:
RegExp: var\s+变量名\s*=\s*(\[[^\]]*\])
RegExp: var\s+变量名\s*=\s*['"]([^'"]+)['"]
如果是 JSON 数组 → jsonDecode
如果是逗号分隔 → split(',').map(trim)
4. 兜底 3:扫描 data:image 内嵌图片
5. 全部 URL resolve 为绝对路径
```
### 3.4 改动量
- `_extractImageUrls()` 新增 ~40 行
- 不影响现有 `RuleParser` 任何逻辑
- 无需新依赖
### 3.5 预期效果
截图 3 「这一章还没有找到漫画页面」在包子漫画 5 上直接消除(即使 `contentRule` 语法不被支持,script 变量扫描也能抓到 `newImgs`)。
---
## 四、第 2 步:RuleParser 支持 @tag/@text/@html/@src 链式语法
> 这是最核心的一步。包子漫画 5、6漫画、WebToon 等主流漫画源全部依赖这种语法。
### 4.1 Legado 链式规则语法规范
Legado 规则的本质是**管道链式操作**,每一步的输出是下一步的输入。语法格式:
```
基础选择器@操作.子选择器@属性
```
**链式管道符**:
| 符号 | 含义 | 示例 |
|------|------|------|
| `@tag.xxx` | 在当前结果内找第一个 `<xxx>` 子元素 | `@tag.img` → 找 img 标签 |
| `@text` | 提取当前元素的 innerText | `.title@text` |
| `@html` | 提取当前元素的 innerHtml | `.content@html` |
| `@src` | 提取 src 属性值 | `img@src` |
| `@href` | 提取 href 属性值 | `a@href` |
| `@class` | 提取 class 属性值 | `div@class` |
| `@alt` / `@title` | 提取 alt / title 属性 | `img@alt` |
| `@data-xxx` | 提取 data-xxx 属性值 | `img@data-original` |
| `@css:.xxx` | 用 CSS 选择器在当前结果内再次选择 | `div.content@css:.chapter@text` |
**管道执行顺序**:
```
原始 HTML
→ CSS 选择器(第一段)→ 得到匹配元素集合
→ @tag.img → 在每个元素内找第一个 img
→ @src → 提取 src 属性值
→ 返回字符串列表
```
### 4.2 实现方式:在 RuleParser 内部新增链式分支
`select()` 和 `selectList()` 方法检测规则中是否包含 `@tag` / `@text` / `@html` / `@src` 等链式操作符。如果有,走新分支 `_selectChain()`。
```dart
List<String> _selectChain(String fragment, String rule) {
// 1. 解析 rule 为执行步列表
final steps = _parseChainSteps(rule);
// 2. 从 fragment 开始,逐步执行
var current = <String>[fragment];
for (final step in steps) {
current = _executeChainStep(current, step);
if (current.isEmpty) return const [];
}
return current;
}
List<_ChainStep> _parseChainSteps(String rule) {
// 规则示例: ".book-list li@tag.a@href"
// 拆分为: [('.book-list li', css), ('a', tag), ('href', attr)]
//
// 关键:@ 是管道分隔符,不是属性选择器的一部分
// "@tag.xxx" 是一个整体 token
// "@src" "@href" "@text" "@html" 是属性提取 token
// "@css:.xxx" 是嵌套 CSS token
}
List<String> _executeChainStep(List<String> fragments, _ChainStep step) {
switch (step.type) {
case _StepType.css:
return _cssSelect(fragments, step.value); // 降级到现有 CSS 路径
case _StepType.tag:
return _tagSelect(fragments, step.value); // fragments 中每个元素内找第一个 <tag>
case _StepType.attr:
return _attrExtract(fragments, step.value); // 提取属性值
case _StepType.text:
return _textExtract(fragments); // 提取 innerText
case _StepType.html:
return _htmlExtract(fragments); // 提取 innerHtml
case _StepType.nestedCss:
return _nestedCssSelect(fragments, step.value); // @css: 语法
}
}
```
### 4.3 链式步骤解析规则
```
规则字符串:
"div.image-area@tag.img@src"
解析产物:
[
{ type: css, value: "div.image-area" }, // @ 之前的部分 → CSS 选择器
{ type: tag, value: "img" }, // @tag.img → 找 img 子标签
{ type: attr, value: "src" }, // @src → 提取 src 属性
]
规则字符串:
"h1.title@text||h1.book-name@text"
解析产物(备选规则):
[
[ {css:"h1.title"}, {text} ], // 方案 A
[ {css:"h1.book-name"}, {text} ], // 方案 B → 先执行 A,A 为空则执行 B
]
规则字符串:
".chapter-content@html##去除广告正则##"
解析产物(带替换):
[
{ type: css, value: ".chapter-content" },
{ type: html, value: null },
{ type: regexReplace, value: "去除广告正则" },
]
```
### 4.4 改动量
- `legado_rule_parser.dart` 新增 `_selectChain()` 方法 ~120 行
- `_parseChainSteps()` ~40 行
- 辅助方法 `_tagSelect()` / `_attrExtract()` / `_textExtract()` / `_htmlExtract()` ~80 行
- `select()` 和 `selectList()` 入口处新增链式检测分支 ~10 行
- 总计 ~250 行
- **零新依赖**(tagSelect / attrExtract 用现有 html parser 或 RegExp 实现)
### 4.5 预期效果
包子漫画 5 的 `contentRule: "div.comic-content@tag.img@src"` 能正确执行:
1. CSS `div.comic-content` → 拿到内容区 DOM
2. `@tag.img` → 在内容区找所有 img 标签
3. `@src` → 提取每个 img 的 src
4. 返回图片 URL 列表
---
## 五、第 3 步:支持 ## 替换、|| 备选、&& 拼接
### 5.1 语法定义
| 符号 | 含义 | 示例 |
|------|------|------|
| `\|\|` | 备选规则:第一个成功就返回,否则尝试下一个 | `.title@text\|\|h1@text` |
| `&&` | 串联拼接:两个结果用空格或换行拼接 | `.title@text&&.author@text` |
| `##` | 正则替换/净化:对当前结果执行正则替换 | `@text##\s+\|\|##g` |
| `###` | 正则删除:删除匹配的部分 | `@html###<script[^>]*>.*?</script>###` |
### 5.2 实现位置
`LegadoRuleExecutor` 的 `execChain()` 方法。
### 5.3 执行顺序
```
解析 rawRule:
1. 按 || 拆分为备选组
2. 每个备选组按 && 拆分为串联组
3. 每个串联组解析为链式步骤(复用第2步的 _parseChainSteps)
4. 每个链式步骤末尾检测 ## 替换指令
执行:
for 备选组 in 备选组列表:
结果 = 执行 备选组
if 结果非空 → 返回结果
return 空
执行备选组:
parts = []
for 串联组 in 备选组:
part = 执行串联组
parts.add(part)
return parts.join('\n') // && 的结果用换行拼接
执行串联组:
result = 执行链式步骤(复用 _selectChain)
if 有 ## 替换指令:
for 替换 in 替换指令:
result = result.replaceAll(替换.regex, 替换.replacement)
return result
```
### 5.4 改动量
- `legado_rule_parser.dart` 新增 `_selectWithAlternatives()` ~50 行
- `##` 替换逻辑 ~30 行
- 总计 ~80 行
- **零新依赖**
---
## 六、第 4 步:fetchBookInfo / fetchToc 失败时区分错误类型
### 6.1 问题
当前 `fetchBookInfo()` 的 try/catch 结构:
```dart
try {
final value = await engine.fetchBookInfo(...);
setState(() { info = value; loadingInfo = false; });
} catch (error) {
setState(() { infoError = error; loadingInfo = false; }); // 所有错误一视同仁
}
```
用户看不到是"网络不通"还是"规则不支持",只能看到统一的"书籍详情加载失败"。
### 6.2 方案:定义错误类型,不新增异常类
```dart
enum LoadFailureReason {
network, // 网络不通 / DNS 失败 / 超时
httpError, // HTTP 4xx / 5xx
ruleNotSupported, // 规则语法不被当前引擎支持
ruleParseEmpty, // 规则执行成功但结果为空(可能是网站改版)
encoding, // 编码问题
unknown,
}
```
在 `fetchBookInfo()` 和 `fetchToc()` 内部区分异常类型,通过 `_shortError()` 返回带 reason 的错误消息(或通过一个简单的包装类)。
### 6.3 UI 差异化展示
```
网络不通:
"无法连接到目标网站,请检查网络或稍后重试。"
[重试]
HTTP 404:
"书源详情页已失效(404),该书源可能需要更新。"
[更换书源]
规则不支持:
"该书源的详情解析规则包含不被当前版本支持的语法(如 @js),更新 APP 后可能可用。"
[查看原始页面]
规则解析为空:
"目标网站页面结构已变化,书源规则可能已过时。"
[重试] [更换书源]
```
### 6.4 改动量
- `legado_engine.dart` 新增 `_classifyError()` 方法 ~30 行
- `_shortError()` 新增 reason 字段 ~10 行
- `online_book_detail_page.dart` 根据 reason 展示不同的 UI ~30 行
- 总计 ~70 行
- **零新依赖**
---
## 七、第 5 步:JS 特判(零依赖)
### 7.1 问题
很多漫画源的 `contentRule` 直接写 JS:
```json
"content": "<js>\nvar result = [];\nvar imgs = JSON.parse...\nnewImgs.map(...)\nresult.join('\\n')</js>"
```
或者写在 `ruleContent.content` 里用 `@js:` 前缀。
当前引擎对 `@js:` 和 `<js>` 完全无处理能力,规则执行到这一步直接抛异常。
### 7.2 第一阶段的 JS 特判策略
不引入完整 JS 引擎。只做模式匹配,覆盖最常见的漫画图片提取模式:
| 模式 | 真实 JS 代码 | 特判正则 |
|------|-------------|---------|
| `newImgs.map` | `newImgs.map(i => i.url)` | 先扫描 rawHtml 中的 `var newImgs = [...]` |
| `imageList` | `imageList[0].src` | 扫描 `var imageList = [...]` |
| `page_url` | `page_url + img` | 扫描 `var page_url = "..."` |
| `chapterImages` | `chapterImages.join` | 扫描 `var chapterImages = [...]` |
| `km5_img_url` | `km5_img_url` | 扫描 `var km5_img_url = "..."` |
| `base64Images` | 从 base64 解码 | 检测 `data:image` 前缀 |
| `eval(decrypt(...))` | 简单解密 | 正则提取被 eval 的字符串 |
### 7.3 实现方式
```dart
List<String> _jsFallbackImages(String rawHtml, String baseUrl) {
final patterns = [
// 1. 数组变量
_JsVarPattern('newImgs', arrayPattern: true),
_JsVarPattern('imageList', arrayPattern: true),
_JsVarPattern('chapterImages', arrayPattern: true),
_JsVarPattern('pics', arrayPattern: true),
_JsVarPattern('imgList', arrayPattern: true),
_JsVarPattern('pageImgs', arrayPattern: true),
// 2. 字符串拼接变量
_JsVarPattern('page_url', arrayPattern: false),
_JsVarPattern('imgDomain', arrayPattern: false),
// 3. data:image 内嵌
_JsVarPattern('data:image', base64Pattern: true),
];
for (final pattern in patterns) {
final urls = _tryExtractJsVar(rawHtml, pattern);
if (urls.isNotEmpty) return urls.map((u) => resolveUrl(baseUrl, u)).toList();
}
return const [];
}
```
### 7.4 改动量
- `legado_engine.dart` 新增 `_jsFallbackImages()` ~60 行
- `_tryExtractJsVar()` ~40 行
- 总计 ~100 行
- **零新依赖**
---
## 八、第 6 步:@put / @get 上下文变量
### 8.1 用途
Legado 高级规则中可以在同一次执行中跨步骤传值:
```
@put:{bookId:$.id}
// ... 在后续规则中使用 ...
/api/book/{{bookId}}/chapters
```
### 8.2 实现方式
在 `LegadoRuleExecutor` 中维护一个 `Map<String, String> _context`。
```dart
class LegadoRuleExecutor {
final Map<String, String> _context = {};
// 执行 @put:{key:value} 时写入 _context
// 解析 URL 模板时用 _context 替换 {{key}}
// @get:key → 从 _context 读取
}
```
### 8.3 改动量
- `legado_rule_parser.dart` 新增 `_context` Map ~5 行
- `@put` / `@get` 语法解析 ~30 行
- `_applySearchTemplate()` 新增 `{{$.key}}` 占位符支持 ~10 行
- 总计 ~45 行
- **零新依赖**
---
## 九、第 7 步:书源兼容度检测
### 9.1 目标
导入书源后,自动分析每个书源用到的规则语法,打上兼容度标签,在书源管理 UI 中展示。
### 9.2 兼容度标签定义
```dart
enum SourceCompatLevel {
full, // 完全兼容:所有规则语法已被引擎支持
partial, // 部分兼容:搜索可用,但正文/详情可能因缺少 JS 执行而不完整
needsJs, // 需要 JS:contentRule 或 bookInfoRule 依赖 @js 或 <js>
needsPost, // 需要 POST 搜索:searchMethod == POST 或 URL 包含 ,{
needsHeaders, // 需要自定义请求头
broken, // 已失效:基础 URL 不可达
unknown, // 尚未验证
}
class SourceCompatInfo {
final SourceCompatLevel level;
final bool searchOk; // 搜索规则可执行
final bool bookInfoOk; // 详情规则可执行
final bool tocOk; // 目录规则可执行
final bool contentOk; // 正文规则可执行
final bool hasJsRule; // 规则中包含 @js / <js>
final bool hasPutGet; // 规则中包含 @put / @get
final List<String> warnings; // 警告信息列表
}
```
### 9.3 检测逻辑(导入时运行)
```dart
SourceCompatInfo analyzeSource(LegadoSource source) {
final warnings = <String>[];
bool hasJs = false;
bool hasPutGet = false;
bool hasChainSyntax = false;
// 1. 检查所有规则字段是否包含 JS 语法
for (final rule in _allRuleFields(source)) {
if (rule == null) continue;
if (rule.contains('@js') || rule.contains('<js>')) hasJs = true;
if (rule.contains('@put') || rule.contains('@get')) hasPutGet = true;
if (rule.contains('@tag.') || rule.contains('@src') ||
rule.contains('@text') || rule.contains('@html')) {
hasChainSyntax = true;
}
}
// 2. 评估各模块可行性
final searchOk = source.searchUrl != null && source.searchListRule != null;
final bookInfoOk = source.bookInfoTocRule != null || source.bookInfoNameRule != null;
final tocOk = source.tocListRule != null || source.tocNameRule != null;
final contentOk = source.contentRule != null;
// 3. 确定级别
SourceCompatLevel level;
if (!searchOk && !contentOk) {
level = SourceCompatLevel.broken;
} else if (hasJs) {
level = SourceCompatLevel.needsJs;
} else if (hasPutGet) {
level = SourceCompatLevel.partial;
} else if (!bookInfoOk && !contentOk) {
level = SourceCompatLevel.partial; // 只能搜
} else {
level = SourceCompatLevel.full;
}
return SourceCompatInfo(level: level, ...);
}
```
### 9.4 UI 展示
在 `source_manager_page.dart` 的书源列表中,每行右侧显示兼容度标签:
```
包子漫画5 [🔴 需要 JS]
6漫画 [🔴 需要 JS]
全本玄幻小说 [🟢 完全兼容]
WebToon [🟡 需要 POST]
某已失效源 [⚫ 已失效]
```
### 9.5 改动量
- `legado_models.dart` 新增 `SourceCompatInfo` 类 ~30 行
- `source_manager.dart` 新增 `analyzeSource()` ~50 行
- `source_manager_page.dart` UI 展示 ~40 行
- 总计 ~120 行
- **零新依赖**
---
## 十、第 8 步:完整 JS 引擎
### 10.1 时机
前 7 步完成后,已有书源中约 60-70% 的漫画源可正常阅读(通过 JS 特判覆盖)。剩下的 30-40% 需要完整 JS 执行环境。
### 10.2 推荐方案
| 方案 | 优点 | 缺点 |
|------|------|------|
| **flutter_js** | 纯 Dart,不依赖 WebView | 性能一般,JS 互操作受限 |
| **quickjs_dart_bridge** | 轻量、快、支持 ES2020 | 需要 Native 桥接 |
| **flutter_js_engine** | 基于 JavaScriptCore/QuickJS | 体积较大 |
| **WebView 隐藏执行** | 兼容性最好 | 太重,不适合批量 |
**建议**:先用 **quickjs_dart_bridge**(已有成功集成到阅读器的先例)。
### 10.3 注入的 JS 运行环境
```js
// 注入变量
result; // 当前 HTML 或 RuleParser 结果
baseUrl; // 当前请求的 base URL
// 注入函数(兼容 Legado 的 java.xxx 调用风格)
java.get(key); // → 从 _context 读
java.put(key, value); // → 写入 _context
java.getElements(html, selector); // → querySelectorAll → 返回元素列表
java.base64Decode(str); // → base64 解码
java.ajax(url); // → HTTP GET → 返回响应文本
// 注入输出收集器
__result; // 脚本执行完毕后读取此变量作为输出
```
### 10.4 安全措施
- JS 沙箱:禁止 `XMLHttpRequest`、`fetch`、`localStorage`
- 超时限制:每条 JS 规则最多执行 3 秒
- 错误隔离:单条 JS 规则失败不影响其他规则
- Isolate 执行:防卡 UI(可选,复杂度较高)
### 10.5 改动量
- `pubspec.yaml` 新增 `quickjs_dart_bridge` 依赖
- 新建 `legado_js_runner.dart` ~150 行
- `LegadoRuleExecutor` 集成 JS 执行 ~30 行
- 总计 ~180 行
---
## 十一、完整实施路线图
```
Week 1 ████████░░░░░░░░░░░░
第1步: rawHtml 兜底 + script 变量扫描
第2步: @tag/@text/@html/@src 链式语法
Week 2 ████████░░░░░░░░░░░░
第3步: ##/||/&& 语法
第4步: 错误类型区分
Week 3 ████████████████░░░░
第5步: JS 特判
第6步: @put/@get
第7步: 书源兼容度检测
Week 4+ ████████████████████
第8步: 完整 JS 引擎
测试: 30+ 书源的回归测试
零新依赖 新依赖
├───────────────────┼──────────┤
第1步 第8步
第2步
第3步
第4步
第5步
第6步
第7步
```
---
## 十二、改动文件清单
| 文件 | 第1步 | 第2步 | 第3步 | 第4步 | 第5步 | 第6步 | 第7步 | 第8步 |
|------|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|
| `legado_rule_parser.dart` | | 🔧250 | 🔧80 | | | 🔧45 | | |
| `legado_engine.dart` | 🔧40 | | | 🔧70 | 🔧100 | 🔧10 | | 🔧30 |
| `legado_models.dart` | | | | | | | 🔧30 | |
| `source_manager.dart` | | | | | | | 🔧50 | |
| `source_manager_page.dart` | | | | | | | 🔧40 | |
| `online_book_detail_page.dart` | | | | 🔧30 | | | | |
| `legado_js_runner.dart` 🆕 | | | | | | | | 🆕150 |
| `pubspec.yaml` | | | | | | | | +1dep |
---
## 十三、总结
整个方案的核心理念是:
```
RuleParser 是对现有 CSS/JSON/Regex 的兼容 → 保留为底层原子工具
LegadoRuleExecutor 是新增的链式规则执行层 → 理解 @tag、##、||、&&
JS 分两级做 → 特判覆盖 60% + 引擎覆盖 40%
书源兼容度检测 → 导入时打标签,用户体验闭环
请求层不动 —— 它没问题
Bug 优先级由截图驱动 —— 第1步修截图3,第2步解锁主流漫画源,第4步修截图1
前4步零新依赖,直接在现有文件里改
```
**一句话**:不推翻现有代码,在 `RuleParser` 之上加一层**链式规则执行器**,让 `@tag.img@src` 和 `##替换` 能被正确理解,这是解锁包子漫画 5 等主流漫画源的关键。
---
## 附录:All.json 常见规则语法统计
基于对 30+ 个典型漫画/小说书源规则的手工分析:
| 语法 | 出现频率 | 典型场景 | 本方案覆盖 |
|------|:--------:|---------|:----------:|
| `@tag.xxx` | ★★★★★ | 漫画正文图片提取 | 第2步 |
| `@src` | ★★★★★ | 图片 URL 提取 | 第2步 |
| `@text` | ★★★★ | 书名/作者/章节名 | 第2步 |
| `@html` | ★★★ | 正文 HTML 提取 | 第2步 |
| `##` | ★★★★ | 广告/水印净化 | 第3步 |
| `\|\|` | ★★★★ | 备选规则 | 第3步 |
| `&&` | ★★★ | 多字段拼接 | 第3步 |
| `<js>` / `@js:` | ★★★ | 漫画图片解密 | 第5/8步 |
| `@put` / `@get` | ★★ | 跨步骤传递 ID | 第6步 |
| `@css:` | ★★★ | 嵌套 CSS 选择 | 第2步 |
| `@data-xxx` | ★★ | data-original 等 | 第2步 |
| `,{method,body}` | ★★ | POST 搜索 | 请求层(现有) |
File diff suppressed because it is too large. Load diff
Binary file not shown.
@@ -0,0 +1,393 @@
# 小说与漫画三级层级展示 —— 前端改造方案
## Context
当前 `sakura_admin_web` 的小说和漫画展示是 **2 级扁平结构**:列表页将同一部作品的章节折叠为一张"作品卡片",点击直接跳转到单章阅读器。用户无法浏览"一本书下面有哪些章节"这个中间层。
本方案将漫画和小说改为 **3 级层级导航**:
```
Level 1 (系列列表) → Level 2 (章节列表) → Level 3 (内容阅读)
```
## 后端 API 现状与数据模型
### Novel(小说)
- **有专用 series API**:`GET /novels/series`(列表)、`GET /novels/series/{series_id}`(单系列含全部章节)
- `NovelSeriesGroup` 包含:`series_id, series_title, author, chapter_count, cover_path, chapters[]`
- 每个 chapter(`NovelOut`)有:`id, title, chapter_title, chapter_order, updated_at`
- 当前前端调的是 `GET /me/novels`(扁平 rows),客户端自己 `groupNovels()`
### Manga/Comic(漫画)
- **无专用 series API**,漫画存储为 `Artwork` 行(`content_type="manga"`)
- 系列分组依赖 JSON 字段 `artwork_metadata.series_id` / `artwork_metadata.series_title`
- 当前前端调用 `GET /me/gallery?content_type=manga`,客户端 `groupManga()` 分组
- 需要在客户端缓存分组数据,供 Level 2 页面使用
---
## 关键设计决策(必读)
### 1. 漫画 seriesKey 稳定性规则
`seriesKey` 是 Level 1 跳 Level 2 的路由参数,也是缓存的索引,必须稳定且防冲突。
**构造规则(优先级从高到低):**
```
seriesKey = series_id
? `manga-${series_id}`
: `manga-title-${series_title || title}`
```
说明:
- 优先用 `artwork_metadata.series_id`,它最稳定
- `series_id` 缺失时用 `series_title || title` 回退,加 `manga-title-` 前缀避免与 `manga-` 冲突
- **所有来源的值都要 `trim()`**
- URL 传递时使用 `encodeURIComponent(seriesKey)`,接收端用 Vue Router 自动解码后的值
### 2. 小说 series_id 类型统一
后端可能返回数字或字符串类型的 `series_id`。**所有地方必须统一转成字符串:**
```
seriesId: String(item.series_id)
```
原因:Vue Router 的 `:seriesId` 参数总是字符串,如果缓存 key 或比较逻辑里混了数字类型,会导致匹配失败。
### 3. 漫画缓存缺失回退流程(明确)
当用户直接访问 `/app/manga/series/:seriesKey` 而缓存为空时,按以下步骤回退:
1. 调用 `GET /me/gallery?content_type=manga&limit=200`
2. 对返回的 rows 执行与 `UserListPage.groupManga()` **完全一致的分组逻辑**
3. 在所有分组结果中查找 `seriesKey` 匹配的组(匹配规则同构造规则)
4. 找到后填充页面
5. 未找到则显示错误:"未找到该系列的章节"
这样保证了不管是从 Level 1 正常导航进来,还是直接访问 URL,显示结果一致。
### 4. Level 3 返回逻辑的 fallback
阅读器中通过 `fromSeries` query 参数构建"返回章节列表"链接:
```
if (fromSeries) → /app/${kind}/series/${fromSeries}
else → /app/${kind} (返回系列列表)
```
面包屑中间的"章节列表"链接同理——没有 `fromSeries` 时不渲染该级面包屑,直接从 Level 1 跳到 Level 3。
### 5. 路由顺序严格要求
`/app` 下的漫画和小说子路由必须按以下顺序注册(**顺序错会导致路由匹配错误**):
```
1. manga ← Level 1
2. manga/series/:seriesKey ← Level 2(固定路径段优先)
3. manga/read/:id ← Level 3(固定路径段优先)
4. manga/:id → redirect ← 旧路由兼容,放最后
5. novels ← Level 1
6. novels/series/:seriesId ← Level 2(固定路径段优先)
7. novels/read/:id ← Level 3(固定路径段优先)
8. novels/:id → redirect ← 旧路由兼容,放最后
```
原理:`manga/series/:seriesKey` 有固定前缀 `series/`,如果放在 `manga/:id` 之后,Vue Router 会把 `series` 当成 `:id` 的值匹配进去。**固定路径段必须排在动态 `:id` 前面。**
### 6. 章节数据 normalize
不同来源的章节字段命名不一致(漫画在 `artwork_metadata` 里嵌套、小说是顶层字段),建议统一写一个 normalize 函数,不要在各处散着取字段。
**小说章节 normalize(输入:`NovelOut`):**
| 要取的字段 | 取值路径 |
|-----------|---------|
| `id` | `String(item.id)` |
| `title` | `item.chapter_title \|\| item.title \|\| "未命名章节"` |
| `order` | `Number(item.chapter_order \|\| 0)` |
| `updated_at` | `item.updated_at \|\| ""` |
**漫画章节 normalize(输入:`ArtworkOut` 单行):**
| 要取的字段 | 取值路径 |
|-----------|---------|
| `id` | `String(item.id)` |
| `title` | `item.title \|\| item.artwork_metadata?.chapter_title \|\| "未命名章节"` |
| `order` | `Number(item.artwork_metadata?.chapter_order \|\| 0)` |
| `page_count` | `Number(item.page_count \|\| 1)` |
| `thumbnail_url` | `item.thumbnail_url \|\| ""` |
| `updated_at` | `item.updated_at \|\| ""` |
在 `UserListPage.groupManga()` 和 `UserChapterListPage.loadMangaSeries()` 中都应使用同一套 normalize。
### 7. Level 2 的状态覆盖
`UserChapterListPage` 必须覆盖以下四种状态,否则直接访问 URL 时体验差:
| 状态 | 条件 | UI |
|------|------|----|
| **加载中** | `loading === true` | `"正在加载章节..."` |
| **加载失败** | `error !== ""` | 显示错误信息,带"重试"按钮 |
| **空章节** | `!loading && !error && chapters.length === 0` | `"暂无章节"` |
| **缓存失效重载** | manga 缓存命空 → 自动触发 API 回退 | `"正在重新加载..."`(过渡态) |
---
## 路由改造
### 新路由结构
**文件:** `src/router/index.ts` —— 修改
```
修改前(2 级) 修改后(3 级)
───────────────── ─────────────────
/app/novels /app/novels ← Level 1 系列列表
/app/novels/:id /app/novels/series/:seriesId ← Level 2 章节列表(新)
/app/novels/read/:id ← Level 3 阅读器(原 /novels/:id)
/app/manga /app/manga ← Level 1 系列列表
/app/manga/:id /app/manga/series/:seriesKey ← Level 2 章节列表(新)
/app/manga/read/:id ← Level 3 详情(原 /manga/:id)
```
**路由注册顺序(严格):**
```ts
// 漫画
{ path: "manga", component: UserListPage, props: { kind: "manga" } },
{ path: "manga/series/:seriesKey", component: UserChapterListPage, props: (route) => ({ kind: "manga", seriesKey: route.params.seriesKey }) },
{ path: "manga/read/:id", component: UserDetailPage, props: (route) => ({ kind: "manga", id: route.params.id }) },
// 小说
{ path: "novels", component: UserListPage, props: { kind: "novels" } },
{ path: "novels/series/:seriesId", component: UserChapterListPage, props: (route) => ({ kind: "novels", seriesId: route.params.seriesId }) },
{ path: "novels/read/:id", component: UserDetailPage, props: (route) => ({ kind: "novels", id: route.params.id }) },
// 旧路由重定向(必须放最后)
{ path: "manga/:id", redirect: (to) => `/app/manga/read/${to.params.id}` },
{ path: "novels/:id", redirect: (to) => `/app/novels/read/${to.params.id}` },
```
---
## 改造清单
### 一、新建文件
#### 1. `src/stores/seriesCache.ts` —— 漫画系列缓存
**为何需要:** 后端没有 manga series 端点。Level 1 页面做完客户端分组后,需要把分组数据传给 Level 2 页面。使用 Vue `reactive()` 对象做跨组件共享缓存。
```ts
// 核心结构
interface MangaChapterCacheEntry {
id: string // gallery item id
title: string // 章节标题(normalize 后)
page_count: number // 页数
thumbnail_url: string // 缩略图
updated_at: string // 更新时间
}
interface MangaSeriesCacheEntry {
seriesKey: string // 唯一标识(按"关键设计决策 1"构造)
seriesTitle: string // 系列标题
coverUrl: string // 封面图
author: string // 作者
chapters: MangaChapterCacheEntry[] // 该系列下所有章节(已 normalize 且按 order 排序)
}
// 导出 mangaSeriesCache: reactive<Record<string, MangaSeriesCacheEntry>>
// 导出 clearMangaCache(): void
```
#### 2. `src/views/app/UserChapterListPage.vue` —— 章节列表页(Level 2)
**复用项目 pattern:** 通过 `kind` prop 同时支持 novels 和 manga。
**Props:**
```ts
{
kind: "novels" | "manga"
seriesId?: string // novels: 后端 series_id(统一 String 类型)
seriesKey?: string // manga: 客户端分组 key
}
```
**模板结构:**
- 面包屑导航:`小说/漫画 > 系列标题`
- "← 返回" 按钮(`router.back()`)
- **四种状态覆盖:**
- 加载中 → `"正在加载章节..."`
- 加载失败 → `error` 文本 + 重试按钮
- 空章节 → `"暂无章节"`(加载成功但 chapters 为空)
- 缓存失效重载 → manga 缓存命中但 chapters 为空时,自动切到 API 回退
- 系列信息头:封面 + 标题 + 作者 + 章节数
- 章节列表:每行显示序号 | 章节标题 | 页数/更新时间 | →
**数据加载:**
- `kind="novels"`:调用 `GET /novels/series/{seriesId}`,对返回的 chapters 执行 normalize
- `kind="manga"`:
1. 优先读 `mangaSeriesCache[seriesKey]`
2. 缓存命中且 chapters 不为空 → 直接展示
3. 缓存未命中或 chapters 为空 → 按"关键设计决策 3"执行 API 回退
**跳转到 Level 3:** `/app/{kind}/read/{id}?fromSeries={encodedSeriesRef}`
---
### 二、修改现有文件
#### 3. `src/views/app/UserListPage.vue` —— 系列列表页(Level 1)
##### 3.1 novels 加载改为 `/novels/series`
当前 `load()` → `GET /me/novels` → `groupNovels()`。改为:
- `endpoint()` 对 novels 返回 `/novels/series`
- `params()` 对 novels 传 `{ include_chapters: false }`(后端返回轻量 series 摘要)
- `groupNovels()` 直接从 series 数据映射 WorkGroup,不再做客户端分组
- WorkGroup 新增 `seriesId: String(series.series_id)` 字段
##### 3.2 manga 加载保持 `/me/gallery`,增强分组逻辑
- 按照"关键设计决策 1"构造稳定的 `seriesKey`
- 构建 WorkGroup 时同步写入 `mangaSeriesCache[seriesKey]`
- 缓存中的 chapters 按"关键设计决策 6"的 normalize 规则统一格式,并已按 order 排序
- WorkGroup 新增 `seriesKey` 字段
##### 3.3 detailUrl 修改
```ts
// 修改前:直接跳阅读器
function detailUrl(id: string) { return `/app/${props.kind}/${id}` }
// 修改后:跳章节列表页
function detailUrl(group: WorkGroup): string {
if (kind === "novels") return `/app/novels/series/${group.seriesId}`
if (kind === "manga") return `/app/manga/series/${encodeURIComponent(group.seriesKey!)}`
...
}
// 为 gallery / alerts 保留原始逻辑
function detailUrlById(id: string): string {
return `/app/${props.kind}/${id}`
}
```
##### 3.4 WorkGroup 类型扩展
```ts
type WorkGroup = {
// ... 原有字段
seriesKey?: string // manga 用(稳定构造)
seriesId?: string // novels 用(统一 String)
}
```
##### 3.5 分页调整
novels 改用 `/novels/series` 后不再需要前端分页(后端一次返回所有系列),因此:
- `supportsPagination` computed 对 novels 返回 false
- 隐藏分页控件
#### 4. `src/views/app/UserDetailPage.vue` —— 阅读器页(Level 3)
- **新增面包屑导航**(仅 novels/manga):
- 始终显示:`小说/漫画 > 当前章节标题`
- `fromSeries` 存在时插入中间级:`小说/漫画 > [章节列表] > 当前章节标题`
- **新增返回按钮**:`"← 返回"`(`$router.back()`)
- **`fromSeries` 参数处理**(按"关键设计决策 4"):
```ts
const fromSeries = computed(() => String(route.query.fromSeries || ""))
const backToListRoute = computed(() => {
if (fromSeries.value) return `/app/${props.kind}/series/${fromSeries.value}`
return `/app/${props.kind}` // fallback 到系列列表
})
```
- 原有阅读器/详情逻辑不变
#### 5. `src/router/index.ts` —— 路由配置
- 新增 `UserChapterListPage` 导入
- 新增 4 条路由(novels/manga 的 series 和 read),严格按照"关键设计决策 5"的顺序排列
- 末尾添加 2 条旧路由重定向
---
### 三、CSS 新增样式
**文件:** `src/styles.css` —— 追加
| 样式类 | 用途 |
|---------|------|
| `.breadcrumb` | 面包屑导航容器(flex, 小字号 muted) |
| `.breadcrumb a` | 面包屑链接(pink-strong, hover opacity) |
| `.breadcrumb .current` | 当前页名(ink, bold) |
| `.series-header` | 章节列表页的系列信息头(flex, 封面+标题+作者+统计) |
| `.series-cover` | 系列封面图(110px 宽, 3:4 比例) |
| `.series-cover.placeholder` | 封面色块占位(粉色背景, 居中文字) |
| `.series-info` | 系列元信息容器 |
| `.series-info h2` | 系列标题(ellipsis 溢出省略) |
| `.chapter-list` | 章节列表网格(gap 8px) |
| `.chapter-row` | 单行章节(flex, hover 阴影+边框变色) |
| `.chapter-row .chapter-index` | 圆形粉色序号标识(36px 圆, number) |
| `.chapter-row .chapter-info` | 章节标题与元信息(flex 收缩, ellipsis) |
| `.chapter-row .chapter-info strong` | 章节标题 |
| `.chapter-row .chapter-info .muted` | 页数 / 更新时间的灰色副文本 |
---
## 数据流示意
### 小说
```
UserListPage ──GET /novels/series?include_chapters=false──→ [{ series_id, chapter_count, cover_path }]
│ seriesId = String(series_id)
│ 点击卡片 → /app/novels/series/:seriesId
▼
UserChapterListPage ──GET /novels/series/:id──→ { chapters: [{id, chapter_title, ...}] }
│ 对 chapters 执行 normalize
│ 点击章节 → /app/novels/read/:id?fromSeries=:seriesId
▼
UserDetailPage ──GET /novels/:id/content──→ 正文阅读
│ 面包屑:小说 > [章节列表] > 当前章名
│ fromSeries 缺失时省略中间级
```
### 漫画
```
UserListPage ──GET /me/gallery?content_type=manga──→ client groupManga()
│ seriesKey 按稳定规则构造(series_id 优先)
│ 章节按 normalize 统一格式、排序
│ └→ 写入 mangaSeriesCache[seriesKey]
│ 点击卡片 → /app/manga/series/:seriesKey(encoded)
▼
UserChapterListPage ──读 mangaSeriesCache[seriesKey]──→ 展示
│ 缓存未命中或 chapters 为空:
│ ① GET /me/gallery?content_type=manga&limit=200
│ ② 执行同一套 groupManga() 分组逻辑
│ ③ 查找匹配 seriesKey 的组
│ ④ 找到 → 填充;未找到 → 显示错误
│ 点击章节 → /app/manga/read/:id?fromSeries=:seriesKey(encoded)
▼
UserDetailPage ──GET /gallery/:id──→ 详情展示
│ 面包屑:漫画 > [章节列表] > 当前章名
│ fromSeries 缺失时省略中间级
```
---
## 验证方案
1. **Level 1 → Level 2 导航**:访问 `/app/novels`,点击任意作品卡片,确认跳转到 `/app/novels/series/:seriesId`,且显示正确的章节列表
2. **Level 2 → Level 3 导航**:在章节列表页点击某一章,确认跳转到 `/app/novels/read/:id?fromSeries=:seriesId`,正文正常显示
3. **面包屑返回**:在阅读器中点击面包屑"章节列表",确认返回 Level 2;点击"← 返回",确认能正常回退
4. **面包屑 fallback**:直接访问 `/app/novels/read/:id`(无 fromSeries),确认面包屑不显示中间级,返回按钮回到 `/app/novels`
5. **漫画缓存链路**:从 Level 1 → Level 2 → Level 3 完整走通漫画导航
6. **漫画缓存缺失回退**:清除缓存后直接访问 `/app/manga/series/:seriesKey`,确认自动回退到 API 拉取并正确展示
7. **漫画 series_id 缺失**:对没有 `artwork_metadata.series_id` 的漫画数据,确认 seriesKey 回退到 `manga-title-{series_title}` 且导航正常
8. **Level 2 空状态**:对章节数为 0 的系列(理论上不应出现,但做防御),确认显示"暂无章节"
9. **Level 2 错误状态**:模拟 API 失败,确认显示错误信息 + 重试按钮
10. **不受影响的功能**:图片(gallery)、提醒(alerts)、个人资料(profile)页面仍正常运作
11. **旧路由兼容**:访问 `/app/novels/旧id` 确认重定向到 `/app/novels/read/旧id`
12. **管理后台不受影响**:`/admin/novels`、`/admin/gallery` 表格正常
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,656 @@
# 两项核心改进 — TOC 分页规则 · 搜索健康分
> 日期:2026-06-22
> 范围:仅移动端 Dart 侧(`sakura_mobile/lib/src/core/`)
> 涉及文件:
>
> - `legado_models.dart` — 数据模型
> - `legado_rule_parser.dart` — 规则解析器
> - `legado_engine.dart` — 搜索引擎入口
> 原则:不改 Python 插件,不改 UI 层,只动 core 层。
---
## 一、改进 1:TOC 章节目录分页规则完整支持
### 1.1 问题
`fetchToc()` 只拉第一页目录。很多书源第一页只给 50~100 章,剩下的靠 **分页目录规则** 指向下一页。不支持分页规则 → 用户看到的目录永远不全。
### 1.2 兼容的字段名
书源 JSON 中,下一页 URL 的字段名可能是以下任意一种,按优先级遍历取第一个非空值:
```dart
// legado_models.dart — BookSource / TocRule 中新增字段解析
static const List<String> _tocNextPageCandidates = [
'tocNextPageRule', // Legado 标准名
'nextTocUrl', // 常见别名
'nextUrl', // 通用别名
'nextPage', // 页码式
'tocNextPage', // 变体
];
String? get tocNextPageRule {
for (final name in _tocNextPageCandidates) {
final v = rawJson[name];
if (v is String && v.trim().isNotEmpty) return v.trim();
}
return null;
}
```
### 1.3 分页规则语法全集
| 规则类型 | 语法示例 | 说明 |
| --------- | ----------------------------------- | ------------------ |
| JS 表达式 | `<js>nextUrl</js>` | 执行 JS 获取下一页 URL |
| JS 缩写 | `@js:nextUrl` | 同上,简写形式 |
| 模板拼接 | `https://host/list?page={{page}}` | `{{page}}` 从 1 自增 |
| 偏移模板 | `{{page+1}}` / `{{page-1}}` | 页号偏移 |
| CSS 选择器 | `text.下一页@href` | 从当前页 HTML 提取下一页链接 |
| class 选择器 | `class.next@href` | 同上 |
| id 选择器 | `id.pagenext@href` | 同上 |
| 属性选择器 | `@href` | 取当前元素 href |
| XPath | `//a[contains(text(),'下一页')]/@href` | XPath 提取 |
| 字符串切片 | `!0:-1` | 对当前 URL 切片(去掉末尾字符) |
| offset 翻页 | `offset=50` | 按 offset 递增翻页 |
| 纯文本 URL | `https://...` | 直接跳到指定 URL |
| 相对路径 | `/list/2.html` | 基于当前 URL 拼接 |
### 1.4 实现 — `TocPaginationResolver`
```dart
// 放在 legado_engine.dart 或新建 legado_toc_pagination.dart
class TocPaginationResolver {
final LegadoRuleExecutor _ruleExecutor;
final HttpClient _client;
TocPaginationResolver(this._ruleExecutor, this._client);
/// 拉取全部分页章节,合并去重。
Future<List<ChapterInfo>> fetchAllChapters({
required String firstPageUrl,
required String? tocNextPageRule,
required String tocRule,
required Map<String, String>? headers,
int maxPages = 20,
}) async {
final all = <ChapterInfo>[];
final seenPageUrls = <String>{};
final seenChapterUrls = <String>{};
String? url = firstPageUrl;
int page = 0;
while (url != null && page < maxPages) {
if (!seenPageUrls.add(url)) break; // 死循环保护
final html = await _client.get(url, headers: headers);
final batch = _ruleExecutor.selectList(html, url, rule: tocRule);
int added = 0;
for (final ch in batch) {
if (seenChapterUrls.add(ch.url)) {
all.add(ch);
added++;
}
}
if (added == 0) break; // 本页无新章节,终止翻页
url = _resolveNextPage(
currentUrl: url,
currentHtml: html,
rule: tocNextPageRule,
pageIndex: page,
);
page++;
}
return all;
}
// ---------- 下一页 URL 解析 ----------
String? _resolveNextPage({
required String currentUrl,
required String currentHtml,
required String? rule,
required int pageIndex,
}) {
if (rule == null || rule.trim().isEmpty) return null;
final r = rule.trim();
// 1) JS: <js>...</js> 或 @js:...
if (r.startsWith('<js>') || r.startsWith('@js:')) {
final code = r
.replaceFirst(RegExp(r'^<js>'), '')
.replaceFirst(RegExp(r'</js>$'), '')
.replaceFirst(RegExp(r'^@js:'), '');
return _ruleExecutor.evalJs(code, context: {
'result': currentHtml,
'baseUrl': currentUrl,
'page': pageIndex,
});
}
// 2) 切片: !start:end
if (r.startsWith('!')) {
return _applySlice(currentUrl, r.substring(1));
}
// 3) CSS 选择器 / XPath
if (_isSelector(r)) {
return _ruleExecutor.select(currentHtml, currentUrl, rule: r);
}
// 4) 模板替换 {{page}} / {{page+1}} / {{page-1}}
if (r.contains('{{page')) {
return _renderPageTemplate(r, pageIndex);
}
// 5) offset / start 参数
if (RegExp(r'[?&](offset|start)=').hasMatch(r)) {
return _renderOffsetTemplate(r, pageIndex);
}
// 6) 绝对 URL
if (r.startsWith('http://') || r.startsWith('https://')) {
return _renderPageTemplate(r, pageIndex);
}
// 7) 相对路径
return Uri.parse(currentUrl).resolve(r).toString();
}
// ---------- 规则判定 ----------
bool _isSelector(String s) {
return s.startsWith('text.') ||
s.startsWith('class.') ||
s.startsWith('id.') ||
s.startsWith('@') ||
s.startsWith('//'); // XPath
}
// ---------- 模板渲染 ----------
String _renderPageTemplate(String tpl, int page) {
return tpl
.replaceAll('{{page+1}}', '${page + 1}')
.replaceAll('{{page-1}}', '${page - 1}')
.replaceAll('{{page}}', '$page');
}
String _renderOffsetTemplate(String tpl, int page) {
return tpl
.replaceAllMapped(
RegExp(r'offset=(\d+)'),
(m) => 'offset=${int.parse(m.group(1)!) * page}',
)
.replaceAllMapped(
RegExp(r'start=(\d+)'),
(m) => 'start=${int.parse(m.group(1)!) * page}',
);
}
String? _applySlice(String url, String expr) {
final parts = expr.split(':');
if (parts.length != 2) return null;
final a = int.tryParse(parts[0]) ?? 0;
final b = int.tryParse(parts[1]);
final start = a < 0 ? url.length + a : a;
if (b != null) {
final end = b < 0 ? url.length + b : b;
return url.substring(start, end);
}
return url.substring(start);
}
}
```
### 1.5 集成到 `LegadoEngine.fetchToc`
```dart
// legado_engine.dart — 修改 fetchToc
Future<List<ChapterInfo>> fetchToc(BookSource source, String tocUrl) async {
final rule = source.tocRule;
if (rule == null || rule.isEmpty) return [];
final resolver = TocPaginationResolver(_ruleExecutor, _client);
return resolver.fetchAllChapters(
firstPageUrl: tocUrl,
tocNextPageRule: source.tocNextPageRule, // ← 新增
tocRule: rule,
headers: _buildHeaders(source),
maxPages: 20,
);
}
```
### 1.6 死循环防护(三层)
1. **`maxPages = 20`** — 单书最多翻 20 页目录
2. **`seenPageUrls`** — 同一 URL 不重复请求
3. **`added == 0` 终止** — 当前页没有新增章节则停止
---
## 二、改进 2:搜索源健康分 + 短超时 + 分阶段返回
### 2.1 问题
当前 `search()` 对所有启用源并发请求,每个源 timeout 20~30 秒。10 个源一批,坏源多时整批拖到 20+ 秒才出结果。
### 2.2 源健康分模型
```dart
// legado_models.dart — 新增 SourceHealth
class SourceHealth {
final String sourceId;
int successCount = 0;
int failCount = 0;
int timeoutCount = 0;
int totalLatencyMs = 0;
DateTime? lastSuccessAt;
DateTime? lastFailAt;
int _consecutiveFails = 0;
SourceHealth({required this.sourceId});
// ---- 判定 ----
/// 连续失败 ≥ 5 次 → 临时禁用
bool get isUsable {
if (_consecutiveFails >= 5) return false;
if (failCount >= 5 && successCount == 0) return false;
return true;
}
int get consecutiveFails => _consecutiveFails;
/// 健康分 0~100
double get score {
final total = successCount + failCount + timeoutCount;
if (total == 0) return 50.0; // 新源默认 50
double s = 0.0;
// 成功率 60%
s += 60.0 * (successCount / total);
// 平均延迟 25%
if (successCount > 0 && totalLatencyMs > 0) {
final avg = totalLatencyMs / successCount;
if (avg < 500) {
s += 25.0;
} else if (avg < 2000) {
s += 25.0 * (1.0 - (avg - 500) / 1500);
}
}
// 新鲜度 15%(24h 内有成功记录)
if (lastSuccessAt != null) {
final h = DateTime.now().difference(lastSuccessAt!).inHours;
if (h < 1) {
s += 15.0;
} else if (h < 24) {
s += 15.0 * (1.0 - h / 24);
}
}
return s.clamp(0.0, 100.0);
}
// ---- 记录 ----
void recordSuccess(int latencyMs) {
successCount++;
totalLatencyMs += latencyMs;
lastSuccessAt = DateTime.now();
_consecutiveFails = 0;
}
void recordFailure() {
failCount++;
lastFailAt = DateTime.now();
_consecutiveFails++;
}
void recordTimeout() {
timeoutCount++;
lastFailAt = DateTime.now();
_consecutiveFails++;
}
void resetConsecutiveFails() => _consecutiveFails = 0;
// ---- 序列化(持久化到 SharedPreferences)----
Map<String, dynamic> toJson() => {
'sourceId': sourceId,
'successCount': successCount,
'failCount': failCount,
'timeoutCount': timeoutCount,
'totalLatencyMs': totalLatencyMs,
'lastSuccessAt': lastSuccessAt?.toIso8601String(),
'lastFailAt': lastFailAt?.toIso8601String(),
'consecutiveFails': _consecutiveFails,
};
factory SourceHealth.fromJson(Map<String, dynamic> json) {
final h = SourceHealth(sourceId: json['sourceId']);
h.successCount = json['successCount'] ?? 0;
h.failCount = json['failCount'] ?? 0;
h.timeoutCount = json['timeoutCount'] ?? 0;
h.totalLatencyMs = json['totalLatencyMs'] ?? 0;
h.lastSuccessAt = json['lastSuccessAt'] != null
? DateTime.tryParse(json['lastSuccessAt'])
: null;
h.lastFailAt = json['lastFailAt'] != null
? DateTime.tryParse(json['lastFailAt'])
: null;
h._consecutiveFails = json['consecutiveFails'] ?? 0;
return h;
}
}
```
### 2.3 健康分持久化
```dart
// legado_engine.dart — SourceHealthStore
class SourceHealthStore {
static const _key = 'source_health_v1';
final Map<String, SourceHealth> _data = {};
Future<void> load() async {
final prefs = await SharedPreferences.getInstance();
final raw = prefs.getStringList(_key);
if (raw == null) return;
for (final s in raw) {
try {
final h = SourceHealth.fromJson(jsonDecode(s));
_data[h.sourceId] = h;
} catch (_) {}
}
}
Future<void> save() async {
final prefs = await SharedPreferences.getInstance();
final raw = _data.values.map((h) => jsonEncode(h.toJson())).toList();
await prefs.setStringList(_key, raw);
}
bool isUsable(String id) => _data[id]?.isUsable ?? true;
double score(String id) => _data[id]?.score ?? 50.0;
void _ensure(String id) {
_data.putIfAbsent(id, () => SourceHealth(sourceId: id));
}
void recordSuccess(String id, int latencyMs) {
_ensure(id);
_data[id]!.recordSuccess(latencyMs);
}
void recordFailure(String id) {
_ensure(id);
_data[id]!.recordFailure();
}
void recordTimeout(String id) {
_ensure(id);
_data[id]!.recordTimeout();
}
/// 用户手动重置所有源健康状态
void resetAll() {
for (final h in _data.values) {
h.resetConsecutiveFails();
}
}
}
```
### 2.4 分阶段搜索调度器
```dart
// legado_engine.dart — SearchScheduler
class SearchScheduler {
static const fastTimeout = Duration(seconds: 5);
static const slowTimeout = Duration(seconds: 8);
static const maxConcurrent = 6;
final SourceHealthStore _health;
final LegadoEngine _engine;
SearchScheduler(this._health, this._engine);
/// 返回 Stream,UI 层逐阶段渲染结果
Stream<SearchPhase> search(String keyword, List<BookSource> allSources) async* {
// 过滤 + 按健康分排序
final usable = allSources
.where((s) => _health.isUsable(s.id))
.toList()
..sort((a, b) => _health.score(b.id).compareTo(_health.score(a.id)));
if (usable.isEmpty) {
yield SearchPhase(name: 'error', message: '没有可用的搜索源');
return;
}
// 分三档
final fast = usable.where((s) => _health.score(s.id) >= 70).toList();
final normal = usable.where((s) {
final sc = _health.score(s.id);
return sc >= 40 && sc < 70;
}).toList();
final slow = usable.where((s) => _health.score(s.id) < 40).toList();
final results = <SearchItem>[];
final doneIds = <String>{};
final seen = <String>{};
// ---- 阶段 1:快速源,超时 5s ----
yield SearchPhase(name: 'searching', message: '正在搜索 ${usable.length} 个源...');
final r1 = await _batch(fast, keyword, timeout: fastTimeout, onDone: doneIds.add);
_merge(results, r1, seen);
yield SearchPhase(
name: 'partial',
items: List.of(results),
doneCount: doneIds.length,
totalCount: usable.length,
);
// ---- 阶段 2:普通源,超时 8s ----
final r2 = await _batch(normal, keyword, timeout: slowTimeout, onDone: doneIds.add);
_merge(results, r2, seen);
yield SearchPhase(
name: 'partial',
items: List.of(results),
doneCount: doneIds.length,
totalCount: usable.length,
);
// ---- 阶段 3:慢源后台继续,不阻塞 ----
if (slow.isNotEmpty) {
// 放入后台队列,不 await
_batch(slow, keyword, timeout: slowTimeout, onDone: doneIds.add)
.then((r3) {
_merge(results, r3, seen);
// TODO: EventBus 通知 UI 追加
});
yield SearchPhase(
name: 'complete_with_pending',
items: List.of(results),
doneCount: doneIds.length,
totalCount: usable.length,
message: '${slow.length} 个慢源将在后台继续搜索',
);
} else {
yield SearchPhase(
name: 'complete',
items: List.of(results),
doneCount: doneIds.length,
totalCount: usable.length,
);
}
}
// ---- 内部分批并发 ----
Future<List<SearchItem>> _batch(
List<BookSource> sources,
String keyword, {
required Duration timeout,
required void Function(String) onDone,
}) async {
final out = <SearchItem>[];
for (var i = 0; i < sources.length; i += maxConcurrent) {
final chunk = sources.skip(i).take(maxConcurrent).toList();
final futures = chunk.map((s) => _searchOne(s, keyword, timeout));
final results = await Future.wait(futures);
for (var j = 0; j < results.length; j++) {
if (results[j] != null) out.addAll(results[j]!);
onDone(chunk[j].id);
}
}
return out;
}
Future<List<SearchItem>?> _searchOne(
BookSource source, String keyword, Duration timeout,
) async {
final sw = Stopwatch()..start();
try {
final items = await _engine.search(source, keyword).timeout(timeout);
sw.stop();
_health.recordSuccess(source.id, sw.elapsedMilliseconds);
return items;
} on TimeoutException {
_health.recordTimeout(source.id);
return null;
} catch (_) {
_health.recordFailure(source.id);
return null;
}
}
void _merge(List<SearchItem> all, List<SearchItem> incoming, Set<String> seen) {
for (final item in incoming) {
if (seen.add(item.id)) all.add(item);
}
}
}
// ---- 阶段结果 ----
class SearchPhase {
final String name; // searching | partial | complete | complete_with_pending | error
final List<SearchItem> items;
final int doneCount;
final int totalCount;
final String? message;
SearchPhase({
required this.name,
this.items = const [],
this.doneCount = 0,
this.totalCount = 0,
this.message,
});
}
```
### 2.5 UI 增量渲染时序
```
t=0s → 显示 "正在搜索 N 个源..."
t=0~5s → 第 1 批结果到达 → 首屏渲染(最快的 5~10 条)
t=5~8s → 第 2 批结果到达 → 列表追加
t=8s → 停止等待 → 提示"慢源已跳过,后台补充中"
t=8~15s → 第 3 批结果到达 → 静默追加到列表末尾
```
### 2.6 健康分自动衰减
每次 `save()` 时做一次衰减:
```dart
// SourceHealthStore.save() 追加衰减逻辑
Future<void> save() async {
// 超过 7 天无任何记录 → 衰减 successCount 和 failCount 各减半
for (final h in _data.values) {
final latest = h.lastSuccessAt ?? h.lastFailAt;
if (latest != null &&
DateTime.now().difference(latest).inDays >= 7) {
h.successCount = (h.successCount * 0.5).round();
h.failCount = (h.failCount * 0.5).round();
h.timeoutCount = (h.timeoutCount * 0.5).round();
}
}
// ... 写入 SharedPreferences
}
```
---
## 三、两改进的协作关系
```
用户搜索一本书
│
├─ SearchScheduler.search(keyword)
│ ├─ 按健康分排序源
│ ├─ 快速源先搜(5s 超时)
│ ├─ 普通源补搜(8s 超时)
│ └─ 返回结果列表
│
├─ 用户点击某条结果 → fetchBookInfo → fetchToc
│ └─ TocPaginationResolver 拉全章节(支持分页规则)
│
└─ 用户阅读某章 → fetchChapterContent(按需加载)
```
改进 1 保证"搜到书后章节不断尾",改进 2 保证"搜索本身不卡"。
---
## 四、实施顺序
```
第 1 步:改进 2 的 SourceHealth + SourceHealthStore
→ 只加数据模型 + 持久化,不影响现有搜索流程
→ 可以先跑几天积累健康数据
第 2 步:改进 2 的 SearchScheduler + 短超时
→ 替换现有 search() 的并发逻辑
→ UI 层适配 Stream<SearchPhase>
第 3 步:改进 1 的 TocPaginationResolver
→ 依赖 RuleParser 链式语法的基础支持
→ 见《Legado 规则引擎重构方案》第 1~3 步
第 4 步:联调 + 回归
```
---
## 五、风险控制
| 风险 | 应对 |
| -------------------- | --------------------------------------------- |
| TOC 分页死循环 | `maxPages=20` + `seenUrls` 去重 + `added==0` 终止 |
| 健康分误杀快源 | 只降权不禁用;连续失败 ≥5 才标记不可用 + 手动可重置 |
| 短超时漏结果 | 慢源后台继续,event bus 异步追加,不丢数据 |
| 新源全部 50 分 | 第一轮搜索后就有真实分,冷启动无影响 |
| SharedPreferences 过大 | 只存 String list,每个源约 200 字节,100 个源 ≈ 20KB |
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+410
View File
@@ -0,0 +1,410 @@
# 代码审计报告
> 审计日期:2026-06-16
> 审计范围:全项目(Flutter 移动端 30 个文件 + Python 桌面端 16 个文件 + Cloud 后端 10 个文件 + 5 个插件)
> 发现总数:111 项(Critical 9 / High 20 / Medium 46 / Low 36)
---
## 目录
1. [Critical(紧急修复)](#一critical紧急修复)
2. [High(高危)](#二high高危)
3. [Medium(中危)](#三medium中危)
4. [Low(低危)](#四low低危)
5. [跨模块问题汇总](#五跨模块问题汇总)
6. [修复优先级建议](#六修复优先级建议)
---
## 一、Critical(紧急修复)
### C1. Cloud 后端:JWT 密钥使用已知默认值
- **文件:** `sakura_cloud/core/config.py:29`
- **代码:** `jwt_secret_key: str = Field(default="change-this-secret-in-production", min_length=16)`
- **问题:** 默认 JWT 密钥是公开的占位字符串。如果运维人员忘记设置 `JWT_SECRET_KEY` 环境变量,任何知道此默认值的人都可以伪造任意用户的 JWT token,获得完全未授权访问。
- **修复:** 生产环境启动时检测是否为默认值,若是则拒绝启动并输出明确错误信息。不使用带默认值的 `Field`,改用 `Field(default=None)` 并在启动时校验。
### C2. 笔趣阁插件:硬编码 AES 密钥和 IV
- **文件:** `plugins/biquge/plugin.py:60-67`
- **代码:**
```python
TOKEN_SECRET = "book@token.html"
TOKEN_MD5 = hashlib.md5(TOKEN_SECRET.encode("utf-8")).hexdigest()
TOKEN_IV = TOKEN_MD5[:16].encode("utf-8")
TOKEN_KEY = TOKEN_MD5[16:].encode("utf-8")
```
- **问题:** AES 密钥和 IV 从硬编码字符串经 MD5 派生,任何人看到源代码即可解密和伪造 API token。固定 IV 下的 CBC 模式使相同明文产生相同密文,可被已知明文攻击。这不是加密,是混淆。
- **修复:** 每次加密使用随机 IV(`os.urandom(16)`),密钥从用户配置或安全随机源派生。
### C3. 小红书插件:`--no-sandbox` 禁用 Chromium 安全沙箱
- **文件:** `plugins/xiaohongshu/plugin.py:361`
- **代码:** `"args": ["--disable-blink-features=AutomationControlled", "--no-sandbox"]`
- **问题:** `--no-sandbox` 完全禁用 Chromium 沙箱,浏览器进程以完整 OS 权限运行。小红书的页面是不受信任的外部内容——如果渲染引擎存在漏洞被利用,攻击者获得主机系统的无限制访问权。
- **修复:** 移除 `--no-sandbox`。如果必须在 Docker/root 环境运行,使用 `--cap-add=SYS_ADMIN` 或配置 seccomp profile,而非全局禁用沙箱。
### C4. Cloud 后端:数据库默认凭据 `sakura:sakura`
- **文件:** `sakura_cloud/core/config.py:17`
- **代码:** `database_url: str = "postgresql+psycopg://sakura:sakura@localhost:5432/sakura_cloud"`
- **问题:** 默认数据库用户名和密码都是 `sakura`。如果部署时未覆盖 `DATABASE_URL`,数据库对任何能访问 `localhost:5432` 的人开放。
- **修复:** 同 C1——生产环境启动时检测默认值并拒绝启动。
### C5. Cloud 后端:MinIO 默认凭据 `minioadmin:minioadmin`
- **文件:** `sakura_cloud/core/config.py:24-25`
- **代码:** `minio_access_key: str = "minioadmin"` / `minio_secret_key: str = "minioadmin"`
- **问题:** 这是 MinIO 官方默认凭据。如果 MinIO 端点暴露在网络上,任何人可以访问所有用户存储的文件。
- **修复:** 同上——启动时检测是否为默认值,若是则拒绝启动。
### C6. 桌面端:云同步 API 使用明文 HTTP
- **文件:** `pixiv_app/gui/app.py:54`
- **代码:** `DEFAULT_CLOUD_API = "http://api.kunkunxiaomao.top:8000"`
- **问题:** 使用 HTTP 而非 HTTPS。用户凭据(邮箱、密码、access token)和上传文件内容以明文在网络上传输。同一网络上的攻击者可通过被动嗅探截获所有认证凭据和文件数据。
- **修复:** 改为 `http://api.kunkunxiaomao.top`(如果服务器支持 HTTPS)。最差情况下至少做出显式警告。
### C7. Flutter:`_initialized` 标志在 Firebase 初始化成功前设置
- **文件:** `sakura_mobile/lib/src/core/push_notifications.dart:27-29`
- **代码:** `_initialized = true` 在 `await Firebase.initializeApp()` **之前**设置
- **问题:** 如果 `Firebase.initializeApp()` 抛出异常,`_initialized` 已经是 `true`,导致后续 `initialize()` 调用全部命中 `if (_initialized) return` 的 early return,Firebase 永远无法重试初始化。推送功能永久失效,无任何提示。
- **修复:** 将 `_initialized = true` 移到 `await Firebase.initializeApp()` 成功之后。
### C8. Flutter:`recentUpdatesOnly` 是死开关(dead UI switch)
- **文件:** `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart:32,120`
- **问题:** `recentUpdatesOnly` 状态变量控制哪个 Chip 显示"已选中",但 `_load()` 方法从未将其作为查询参数传给 API。用户看到的"最近更新"筛选切换实际上没有任何效果。
- **修复:** 在 `_load()` 中将 `recentUpdatesOnly` 转换为对应的 API 参数,或者移除该 Chip。
### C9. 桌面端:ProxyPool 的多线程数据竞争
- **文件:** `pixiv_app/core/proxy_pool.py:193,272-273,278-279`
- **问题:**
1. `ProxyPool.current_index` 的读取(line 272)和递增(line 273)之间无锁保护,`ThreadPoolExecutor` 的多个 worker 同时调用 `get_proxy()` 时产生重复或跳跃的索引
2. `ProxyPool.working_proxies` 被 `mark_failed()` 的 `.remove()` 修改,而其他线程可能正在迭代它——可抛出 `ValueError` 或不一致迭代
3. `ProxyInfo.fail_count` 和 `success_count` 的非原子递增在 `ThreadPoolExecutor` 16 个 worker 并行调用 `verify_proxy()` 时静默丢失计数
- **修复:** 使用 `threading.Lock` 保护所有对 `working_proxies`、`current_index` 的写操作,`fail_count`/`success_count` 改用 `threading` 安全计数或原子操作。
---
## 二、High(高危)
### H1. Cloud 后端:用户登录无限流 → 可暴力破解
- **文件:** `sakura_cloud/api/v1/endpoints/auth.py:56-76`
- **问题:** `/login` 端点无限流(`admin_login_rate_limit_per_minute` 只用于 admin 端点)。攻击者可无限制尝试密码组合进行暴力破解。
- **修复:** 对 `/login`、`/register`、`/token/refresh` 增加速率限制(如每 IP 每分钟 5 次)。
### H2. Cloud 后端:用户注册无限流 + 信息泄露
- **文件:** `sakura_cloud/api/v1/endpoints/auth.py:24-53`
- **问题:** `/register` 端点无限流。409 响应明确区分"用户名已存在"和"邮箱已存在",可用于枚举已注册用户。
- **修复:** 加速率限制。错误消息统一为"注册失败,请检查输入"。
### H3. Cloud 后端:存储配额未强制执行
- **文件:** `sakura_cloud/api/v1/endpoints/gallery.py:223`、`sync.py:86-141`
- **问题:** `default_storage_limit_bytes` 在 config 中定义了(line 108-109),但在创建 artwork 和同步 metadata 时**从未检查** `current_user.storage_used` 是否超过配额。用户可以上传无限制的数据。
- **修复:** 在 `gallery.py` 和 `sync.py` 的写入路径中增加 `if current_user.storage_used + new_size > limit: raise HTTPException(413)`。
### H4. Cloud 后端:Logout 不撤销 token
- **文件:** `sakura_cloud/api/v1/endpoints/auth.py:79-81`
- **问题:** `/logout` 只返回 `{"ok": True}`,不做任何 token 撤销操作。access token 在其自然过期(最长 24 小时)前持续有效。用户登出后无法阻止 token 被盗用。
- **修复:** Logout 时递增 `user.token_version`,使当前所有 token 立即失效。
### H5. Cloud 后端:Refresh token 轮转不撤销旧 token
- **文件:** `sakura_cloud/api/v1/endpoints/auth.py:84-104`
- **问题:** 交换 refresh token 时签发新的 access + refresh token,但旧的 refresh token 未失效。如果 refresh token 被盗,攻击者和合法用户都可以持续刷新——直到某人重新登录(才会 bump `token_version`)。
- **修复:** 实现 refresh token 轮转——每次使用时废弃旧 token 并签发新的。
### H6. 桌面端 & Flutter:敏感凭据多处明文存储
|| 位置 | 凭据类型 | 存储方式 |
||------|---------|---------|
|| `pixiv_app/core/auth.py:36-41` | Pixiv cookie | JSON 文件明文 |
|| `plugins/pixiv/plugin.py:42-43` | Pixiv cookie | 内存明文 |
|| `plugins/x/plugin.py:76` | X/Twitter cookies | `x_cookies.json` 明文 |
|| `plugins/ao3/plugin.py:687-688` | AO3 cookie | 内存明文 |
|| `plugins/xiaohongshu/plugin.py:386-404` | 小红书 cookies | `xiaohongshu_cookies.json` 明文 |
|| `pixiv_app/core/proxy_pool.py:67-68` | Quake API key | `app_session_file()` JSON 明文 |
|| `sakura_mobile/lib/src/core/session.dart:44-47` | Access token | SharedPreferences 明文 |
- **修复:** 生产环境使用操作系统密钥链(Windows DPAPI / macOS Keychain / Android Keystore)。最低限度应对配置文件设置受限的文件权限。
### H7. Flutter:小说阅读页面翻页不节流 → API 洪泛
- **文件:** `sakura_mobile/lib/src/pages/novel_reader_page.dart:787-790`
- **问题:** `onPageChanged` 对**每次翻页**同步调用 `updateNovelProgress(currentNovel.id, page)`。快速翻页时数十上百个 API 请求瞬间发出,压垮服务器并浪费电量/带宽。
- **修复:** 增加 500ms 防抖,只发送最终位置。
### H8. Flutter:探索页从"插画"tab 点搜索 → 打开"小说"模式
- **文件:** `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart:398-399`
- **问题:** 用户在"图片"(illust)tab 点击在线搜索时,代码 `widget.fixedContentType != 'manga'` 为真,传入 `UnifiedSearchMode.novel`。从图片页搜索却打开了小说搜索模式。
- **修复:** 将 explore mode 与 gallery content type 解耦。默认为 manga 模式(漫画源更多)。或增加一个独立的选择器。
### H9. Flutter:Session 构造器中异步工作不可 await
- **文件:** `sakura_mobile/lib/src/core/session.dart:44-47`
- **问题:** `SessionController()` 构造器中调用异步 `_load()`,但构造器不能 `async`。Provider 观察者先看到默认 loading 态再被 `_load()` 完成后的 `notifyListeners()` 更新。Provider 初始化异常无法被外部捕获。
- **修复:** 使用 Riverpod 的 `FutureProvider` 或 `AsyncNotifier`,或将初始化方法显式暴露给 widget tree 调用。
### H10. Flutter:`_validateStoredSession` 静默吞所有异常
- **文件:** `sakura_mobile/lib/src/core/session.dart:159`
- **问题:** `catch (_)` 捕获所有异常返回 `null`,不记录日志。网络故障或服务器宕机时用户被静默登出,无任何提示。
- **修复:** 最低限度 `debugPrint(e)`。更好:区分网络错误(可恢复)和认证错误(需重新登录),并显示对应 UI。
### H11. Cloud 后端:JWT 缺少 `aud`/`iss` 声明验证
- **文件:** `sakura_cloud/core/security.py:23-32,53-62`
- **问题:** Token 创建时不设置 `aud`(受众)和 `iss`(签发者),`decode_token` 也不验证。如果同一 JWT 密钥被意外共享,一个服务的 token 可在另一个服务中复用。
- **修复:** 创建 token 时设置 `aud="sakura-cloud"`,解码时验证。
### H12. 小红书插件:代理凭据暴露在 URL 字符串中
- **文件:** `plugins/xiaohongshu/plugin.py:107-110`
- **问题:** `ProxyConfig.url` 属性将明文用户名密码嵌入 URL:`"https://user:pass@host:port"`。如果这个 URL 字符串被记录到 Playwright 调试日志、异常堆栈或错误消息中,凭据泄露。
- **修复:** 通过 Playwright 的 `proxy` context 选项分别传入 `username`/`password`(lines 368-371 已部分正确),`.url` 属性不包含凭据。
### H13. Flutter:默认 API URL 用 HTTP 明文
- **文件:** `sakura_mobile/lib/src/core/api_client.dart:9`
- **代码:** `const defaultCloudApi = 'http://api.kunkunxiaomao.top:8000'`
- **问题:** 与桌面端 C6 相同——明文 HTTP 传输所有凭据和内容。
- **修复:** 改为 HTTPS。
### H14. Flutter:Push notification token refresh 监听器持有过期凭据
- **文件:** `sakura_mobile/lib/src/core/push_notifications.dart:66-83`
- **问题:** `onTokenRefresh.listen` 捕获注册时的 `baseUrl` 和 `accessToken`。如果用户后续登录其他服务器或换号,监听器仍用旧凭据,导致 push 注册静默失败(line 79 catch 吞错)。
- **修复:** 每次 token 刷新时从当前 provider 读取最新凭据。
### H15. 桌面端:SQLite 跨线程共享缺少显式锁
- **文件:** `pixiv_app/core/library.py:29`
- **代码:** `check_same_thread=False` 允许跨线程共享连接,"当有锁保护时"——但锁的保护由调用者负责且不一致。
- **问题:** `TaskQueue`(`enqueue.py:232`)将连接传给多个 `ThreadPoolExecutor` worker,没有外部锁。WAL 模式下 SQLite 通常能处理,但高并发写入时仍可能 `SQLITE_BUSY`。
- **修复:** 改用连接池(如 `sqlite3` 的 URI 模式 `file:path?mode=rw`),或每个 worker 使用独立连接。
### H16. 桌面端:画廊同步对每个文件行新开 DB 连接(O(N) 连接泛滥)
- **文件:** `pixiv_app/gui/app.py:2175-2184`
- **问题:** `_sync_pixiv_rows` 中**每个文件行**都调用 `sqlite3.connect(DEFAULT_LIBRARY_DB)` → 查询 → `close()`。100 个文件同步 = 100 次 DB 打开/关闭循环。性能低下且在高负载下可能触及 OS 文件描述符上限。
- **修复:** 复用单个连接或将查询批量化。
### H17. Cloud 后端:用户登录无限流(跨所有端点)
- **问题范围:** `/login`(auth.py:56)、`/register`(auth.py:24)、`/token/refresh`(auth.py:84)、所有 gallery 端点、所有 novel 端点、所有 sync 端点——除 admin 外**无一有限流**。
- **修复:** 全局应用 rate limiting 中间件(如 `slowapi` 或自定义中间件)。
### H18. Cloud 后端:`--no-sandbox` 同样存在于 X 插件
- **文件:** `plugins/x/plugin.py`(Playwright 启动参数)
- **问题:** 与 C3 相同风险。X/Twitter 页面同样是不受信任的外部内容。
- **修复:** 移除或至少评估必要性。
### H19. 桌面端:N+1 查询模式在关注作者同步中
- **文件:** `pixiv_app/core/gallery_service.py:547-561`
- **问题:** `sync_followed_artists` 对每个关注的作者创建 → 查询 → 关闭独立的 `PixivLibrary` 实例。50 个作者 = 100+ 次 DB 打开/关闭。
- **修复:** 使用池化或缓存的连接。
### H20. Flutter:多个页面存在静默吞错 → 空列表
|| 文件 | 位置 | 模式 |
||------|------|------|
|| `novels_tab.dart` | 63-67 | `.catchError((_) => <dynamic>[])` |
|| `api_client.dart` | 532 | `_readCache` catch 返回 null |
|| `providers.dart` | 17-21 | `initializeIfFirstRun()` 的 future 被丢弃 |
- **影响:** API 失败时用户看到空书架/空画廊/空收藏,无法区分"真的没数据"和"加载失败了"。
- **修复:** 区分 error 状态并在 UI 中显示错误提示和重试按钮。
---
## 三、Medium(中危)
### 后端
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| M1 | `sakura_cloud/main.py` | 130-131 | asyncio background task 无引用监控,异常静默死亡 |
| M2 | `sakura_cloud/api/middleware.py` | 77 | `img-src https: http:` 完全取消 CSP 图片保护 |
| M3 | `sakura_cloud/api/middleware.py` | 79 | `style-src 'unsafe-inline'` 可被 XSS 利用 |
| M4 | `sakura_cloud/core/config.py` | 31 | access token 有效期 24h 过长,token 被盗后窗口大 |
| M5 | `sakura_cloud/core/config.py` | 56-58 | FCM 默认启用但无有效凭据,运行时报错 |
| M6 | `sakura_cloud/core/config.py` | 18 | Redis 默认 URL 无密码认证 |
| M7 | `sakura_cloud/api/v1/endpoints/gallery.py` | 324-332 | 删除 artwork 时文件不清理 → 磁盘孤儿文件累积 |
| M8 | `sakura_cloud/api/v1/endpoints/novels.py` | 53-73 | GET 请求触发 DB 写操作(`_resolve_novel_storage_path`),违反 REST 幂等性 |
| M9 | `sakura_cloud/api/v1/endpoints/files.py` | 39 | 缩略图生成同步阻塞 FastAPI 事件循环 |
| M10 | `sakura_cloud/api/v1/endpoints/sync.py` | 38,100,138 | metadata dict 无大小限制 → 数据库 bloat 攻击 |
| M11 | `sakura_cloud/api/v1/endpoints/sync.py` | 37,99,138 | tags 列表无长度/元素限制 → 数据库 bloat 攻击 |
| M12 | `sakura_cloud/api/v1/endpoints/auth.py` | 9 | 密码复杂度仅 `min_length=8`,弱密码可过 |
| M13 | `pixiv_app/core/downloader.py` | 46-48 | 文件名未做长度限制,Windows MAX_PATH 260 字符溢出导致 OSError |
| M14 | `pixiv_app/core/downloader.py` | 476,502,537 | 大量 `except Exception: continue` 静默丢错,生产调试不可能 |
| M15 | `pixiv_app/core/downloader.py` | 690,901-945 | 每个作品创建新 `requests.Session()`(无 keep-alive),100 作品 = 100 次 TLS 握手 |
| M16 | `pixiv_app/core/gallery_service.py` | 399-414 | `_create_sync_manager` 在 3 个文件中重复实现 |
| M17 | `pixiv_app/core/origin_follow_sync.py` | 103 | `asyncio.run()` 在可能已有 event loop 的同步上下文中调用 |
| M18 | `pixiv_app/core/proxy_pool.py` | 213 | 代理测试时 `verify=False`,代理自身可 MITM 注入虚假成功结果 |
| M19 | `pixiv_app/core/auth.py` | 36-41 | `SessionStore.load()` 用裸 `except Exception` 吞所有异常(JSON 损坏、权限错误等) |
| M20 | `pixiv_app/core/gallery_service.py` | 79-81 | tag 筛选用 `JOIN`(非 `LEFT JOIN`),孤儿 `artwork_tags` 行导致作品静默遗漏 |
| M21 | `pixiv_app/core/downloader.py` | 698 | `int(detail.get("pageCount") or 0)` 遇非数字字符串抛 `ValueError` |
### 插件
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| M22 | `plugins/pixiv/plugin.py` | 243-244 | 文件名从 URL 提取,URL 编码的 `%2F` 可绕过 `rsplit` 做路径穿越 |
| M23 | `plugins/x/plugin.py` | 217-218,386 | 每次操作启动新 Playwright browser context,无复用 → 资源耗尽 |
| M24 | `plugins/biquge/plugin.py` | 845-867 | Playwright page 实例缓存跨操作复用,一次失败污染后续 |
| M25 | `plugins/ao3/plugin.py` | 503-506 | EPUB 解压无 zip bomb 防护,压缩炸弹可 OOM |
| M26 | `plugins/ao3/plugin.py` | 92-96 | `Retry-After` 头无上限,`Retry-After: 999999999` 可使插件休眠 ~31 年 |
| M27 | `plugins/xiaohongshu/plugin.py` | 377 | `headless=False` 在服务器/无 GUI 环境运行失败 |
| M28 | `plugins/xiaohongshu/plugin.py` | 480-588 | `page.evaluate()` 执行不受信任页面的 JS,结果未经域名验证 |
| M29 | `plugins/xiaohongshu/plugin.py` | 630-648 | 下载图片时转发页面所有 cookies 给图片 CDN(含第三方追踪 cookie) |
### Flutter
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| M30 | `api_client.dart` | 440-502 | `translateText()` 每次调用创建并销毁新的 Dio 实例 |
| M31 | `api_client.dart` | 518-535 | `_readCache<T>` 泛型类型不安全——声称返回任何 T 但 SharedPreferences 只存 JSON 基本类型 |
| M32 | `providers.dart` | 17-21 | `sourceManager.initializeIfFirstRun()` 是 async 但返回值被丢弃 |
| M33 | `app.dart` | 24 | 硬编码 Windows 字体 `Microsoft YaHei UI`,iOS/macOS/Linux 回退不一致 |
| M34 | `gallery_tab.dart` | 269-278 | 收藏/取消收藏触发全量列表重载(`_refresh()`),非单项更新 |
| M35 | `gallery_tab.dart` | 336-367 | 批量下载用 `for` + 顺序 `await`,无并发无进度 |
| M36 | `login_page.dart` | 141 | TabBarView 高度硬编码 430px,不同屏幕尺寸下可能裁剪或留白 |
| M37 | `novel_reader_page.dart` | 17-32 | 14 个可变实例字段——翻页设置(字号/行高/主题)在每次页面跳转时丢失 |
| M38 | `novel_detail_page.dart` | 67 | 硬编码 `430`px 滚动偏移到目录区,不随内容高度自适应 |
| M39 | `reminder_center_page.dart` | 22-35 | `results[0]! as Map` 等不安全类型强转,API 返回异常形状时抛 `TypeError` |
| M40 | `profile_tab.dart` | 403 | `logout()` 是 async 但 button onPressed 丢弃返回的 Future |
| M41 | `profile_tab.dart` + `reminder_center_page.dart` | 44-97 | 提醒时间设置逻辑完全重复两份 |
| M42 | `favorites_page.dart` | 51-54 | 每次点击 artwork 都重新执行 O(n) 的 `buildMangaCollections` |
| M43 | `novels_tab.dart` | 461 | epoch 0 作为时间戳兜底 → 显示"53 年前",无意义 |
| M44 | `manga_collections.dart` | 59 | 不同 null-author 作者的同名作品被错误合并为同一合集 |
### Cloud 后端(补充)
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| M45 | `sakura_cloud/main.py` | 123-126 | 启动时 digest 发送失败仅打日志,无告警 |
| M46 | `sakura_cloud/core/security.py` | 54-59 | `decode_token` 冗余手动检查 `exp`,且未设 clock skew 容差 |
---
## 四、Low(低危)
### 后端
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| L1 | `sakura_cloud/main.py` | 113-131 | startup 事件阻塞事件循环,无就绪探针/超时 |
| L2 | `sakura_cloud/api/middleware.py` | 32-42 | debug 模式 CSP `connect-src` 开放 `localhost:*`(所有本地端口) |
| L3 | `sakura_cloud/api/deps.py` | 29 | `str(user_id)` 对 None 产生字面字符串 `"None"` |
| L4 | `sakura_cloud/api/deps.py` | 34 | `token_version` 比较中,双方都为 0/None 时通过,旧 token 缺少 `tv` 声明不被拒绝 |
| L5 | `sakura_cloud/core/config.py` | 89-103 | `json.loads()` 在 field validator 中内联 import,不标准 |
| L6 | `sakura_cloud/api/v1/endpoints/auth.py` | 79-81 | logout 不递增 `token_version` |
| L7 | `sakura_cloud/api/v1/endpoints/gallery.py` | 51-97 | `ILIKE` + `plainto_tsquery` 用户输入无长度限制 → 可能触发慢查询 |
| L8 | `sakura_cloud/api/v1/endpoints/files.py` | 32 | `original_name` 用户可控 → 下载附件名可用于社工 |
| L9 | `sakura_cloud/api/v1/endpoints/sync.py` | 25 | SHA256 字段只验证长度不验证 hex 字符 |
| L10 | `sakura_cloud/api/v1/endpoints/sync.py` | 144-157 | 设备注册无每用户数量上限 |
| L11 | `pixiv_app/core/downloader.py` | 40 | `PixivRequestError` 继承 `RuntimeError` 而非 `Exception`(语义不当) |
| L12 | `pixiv_app/core/downloader.py` | 233 | `str(user_id).isdigit()` 中 `user_id` 可能为 None → `str(None)` = `"None"` |
| L13 | `pixiv_app/core/downloader.py` | 700,709,771 | 同一 artwork 三次调用 `ensure_artwork_stub`(`INSERT OR IGNORE`,无害但浪费) |
| L14 | `pixiv_app/core/gallery_service.py` | 588-613 | 同一 artwork 多次同步中重复创建 alert |
| L15 | `pixiv_app/core/x_media_service.py` | 522-523 | `datetime.now()` 无时区 → 跨时区对比可能偏差一天 |
| L16 | `pixiv_app/gui/app.py` | 1153-1157 | 小红书页缩进不一致(7 空格,PEP 8 违规) |
| L17 | `sakura_cloud/core/security.py` | 54-59 | `decode_token` 的 `exp` 手动检查与 `jwt.decode` 内建检查重复 |
### 插件
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| L18 | `plugins/x/plugin.py` | 414 | 下载缓存 JSON 暴露本地绝对路径结构 |
| L19 | `plugins/x/plugin.py` | 463-475 | 文件类型仅凭 URL 子串匹配判断,无 MIME 验证 |
| L20 | `plugins/biquge/plugin.py` | 135,360-361 | `requests.Session()` 无连接池限制 |
| L21 | `plugins/xiaohongshu/plugin.py` | 375-376 | 浏览器 profile 跨会话共享,可能积累旧 cookies 泄漏 |
### Flutter
| # | 文件 | 行号 | 问题 |
|---|------|------|------|
| L22 | `app.dart` | 11-16 | `ColorScheme.fromSeed()` 在 build 中创建(实际仅一次,低影响) |
| L23 | `artwork_detail_page.dart` | 264-265 | `showDialog` 异常抛出时 TextEditingController 泄漏 |
| L24 | `online_manga_reader_page.dart` | 101-103 | 源 headers 直接传给 `Image.network`,第三方源可能捕获凭据 |
| L25 | `novel_reader_page.dart` | 78,330 | `Future.microtask` 在 widget 可能已 dispose 的上下文中执行 |
| L26 | `novels_tab.dart` | 446,461 | 时间戳兜底使用 epoch 0 → 显示"53 年前" |
| L27 | `explore_page.dart` | 186-222 | `_openItem` 从 provider 同步读取 source,可能搜完源已被删除 |
| L28 | `source_manager.dart` | 86-96 | `initializeIfFirstRun()` 的 initialized flag 在可能失败的 `load()` 之后无条件设为 true |
| L29 | `source_manager.dart` | 242-260 | 从 JSON 导入时,源的 id 由 name+URL 的 codeUnit 求和生成——不同源可能碰撞 |
| L30 | `legado_engine.dart` | 167-200 | `_encodeKeyword` 对非 UTF-8/GBK 编码的平台通道调用无超时 |
---
## 五、跨模块问题汇总
| 问题类别 | 涉及模块 | 严重程度 |
|---------|---------|:--------:|
| **凭据明文存储** | 桌面端 + 5 个插件 + Flutter | Critical/High(7 处) |
| **HTTP 明文传输** | 桌面端 API + Flutter API | Critical/High(2 处) |
| **默认密码/密钥** | Cloud config(JWT、DB、MinIO、Redis) | Critical/High(4 处) |
| **无限流** | Cloud 全部用户端点 | High(17+ 端点) |
| **存储配额未执行** | Cloud gallery + sync | High(2 处) |
| **静默吞错 → 空列表** | Flutter + 桌面 downloader + session | High/Medium(10+ 处) |
| **线程安全** | 桌面 ProxyPool + SQLite + counter | Critical/Medium(3 处) |
| **资源泄漏** | 桌面 DB 连接 + Flutter Dio × translate + X 插件 browser | High/Medium(3 处) |
| **Token 生命周期** | Cloud auth(logout、refresh、expiry、version) | High/Medium(5 处) |
| **插件安全** | `--no-sandbox` + 硬编码密钥 + zip bomb + URL 路径穿越 | Critical/Medium(5 处) |
| **Flutter 状态管理** | FutureBuilder 模式 + async 构造器 + provider 初始化 | High/Medium(5 处) |
---
## 六、修复优先级建议
### 第一轮(立即修复,1–3 天)
| 顺序 | ID | 问题 | 工时 |
|:----:|:---|------|:----:|
| 1 | C1,C4,C5 | Cloud 默认凭据:JWT 密钥 + DB 密码 + MinIO 凭据 | 1h |
| 2 | C3,H18 | 移除 `--no-sandbox`(小红书 + X 插件) | 1h |
| 3 | C6,H13 | HTTP → HTTPS(桌面端 + Flutter) | 2h |
| 4 | C9 | ProxyPool 多线程数据竞争(加锁) | 2h |
| 5 | C7 | Firebase 初始化 flag 移到成功之后 | 10m |
| 6 | C2 | 笔趣阁 AES 密钥改为随机 IV + 安全随机密钥 | 2h |
| 7 | H1,H2,H17 | Cloud 端全局速率限制 | 4h |
| 8 | H3 | 存储配额强制执行 | 2h |
### 第二轮(本周内,3–5 天)
| 顺序 | ID | 问题 | 工时 |
|:----:|:---|------|:----:|
| 9 | H4,H5 | Token 撤销(logout + refresh rotation) | 4h |
| 10 | H16 | 云同步 O(N) DB 连接改为复用连接 | 2h |
| 11 | H15 | SQLite 跨线程连接池化 | 3h |
| 12 | H7 | 小说翻页 API 增加 500ms 防抖 | 1h |
| 13 | H8 | 探索页"插画→小说"模式修复 | 1h |
| 14 | C8 | gallery_tab `recentUpdatesOnly` 死开关修复 | 1h |
| 15 | H19 | 关注作者同步 N+1 查询优化 | 3h |
| 16 | H20 | 多处静默吞错 → 显式错误状态 UI | 4h |
| 17 | M8 | GET novel 路径解析触发的 DB 写操作改为 lazily 计算 | 2h |
### 第三轮(下一迭代)
| 顺序 | 类别 | 内容 | 工时 |
|:----:|------|------|:----:|
| 18 | 凭据加密 | 7 处明文凭据改为 OS 密钥链存储 | 8h |
| 19 | CSP | CSP 策略加固(nonce/hash 替代 unsafe-inline) | 4h |
| 20 | 测试 | 为 Critical/High 项编写回归测试 | 8h |
| 21 | Flutter 重构 | AsyncNotifier 替代 FutureBuilder(feed_tab, gallery_tab, novels_tab) | 8h |
| 22 | 插件审计 | 对全部 5 个插件的网络/文件访问权做沙箱化评估 | 4h |
---
> **审核范围确认:** Flutter 移动端 30 个 Dart 文件 × Python 桌面端 16 个文件 × Cloud 后端 10 个端点文件 × 5 个插件 × 中间件/配置/安全模块。合计约 65 个源文件,发现 111 个问题。
+507
View File
@@ -0,0 +1,507 @@
# 樱云下载器 — 优化方案与功能规划
> 版本:2.1.0-draft | 日期:2026-06-24
> 基于代码审计报告、产品文档、CHANGELOG 及全仓库源码分析制定
---
## 目录
1. [优先级定义](#0-优先级定义)
2. [P0 — 安全与基础设施(必须修)](#1-p0--安全与基础设施)
3. [P1 — 核心体验缺陷(尽快修)](#2-p1--核心体验缺陷)
4. [P2 — 功能完善与增强](#3-p2--功能完善与增强)
5. [P3 — 体验优化与锦上添花](#4-p3--体验优化与锦上添花)
6. [P4 — 长期架构演进](#5-p4--长期架构演进)
7. [实施路线图](#6-实施路线图)
---
## 0. 优先级定义
| 等级 | 含义 | 建议时间 |
|------|------|---------|
| **P0** | 安全漏洞 / 数据风险 / 系统崩溃 | 1 周内 |
| **P1** | 核心功能阻断或严重缺陷 | 2–4 周 |
| **P2** | 功能缺口 / 重要增强 | 1–2 月 |
| **P3** | 体验优化 / 锦上添花 | 按需排期 |
| **P4** | 架构演进 / 平台扩展 | 中长期规划 |
---
## 1. P0 — 安全与基础设施
> 来源:代码审计报告 Critical 项 + 其他发现
### 1.1 JWT 密钥强制生产配置
- **现状**:`sakura_cloud/core/config.py` 中 `jwt_secret_key` 默认值为 `"change-this-secret-in-production"`,任何人都可伪造 JWT
- **方案**:启动时检测是否为已知默认值,若是则拒绝启动并输出明确的错误信息,引导运维设置 `JWT_SECRET_KEY` 环境变量
- **影响范围**:`sakura_cloud/core/config.py`、`sakura_cloud/core/security.py`
### 1.2 数据库凭据与 MinIO 凭据硬编码
- **现状**:
- PostgreSQL 默认凭据 `sakura:sakura`
- MinIO 默认凭据 `minioadmin:minioadmin`
- **方案**:同 JWT 策略——启动时检测默认值,若未被覆盖则拒绝启动;为 MinIO 增加随机密码生成脚本
- **影响范围**:`sakura_cloud/core/config.py`、部署文档
### 1.3 桌面端 → 云端启用 HTTPS
- **现状**:`DEFAULT_CLOUD_API = "http://api.kunkunxiaomao.top:8000"` 使用明文 HTTP,用户凭据和文件明文传输
- **方案**:
- 短期:支持 HTTP 但增加显式警告弹窗("当前使用非加密连接,凭据可能被窃取")
- 长期:服务器配置 SSL 证书(Let's Encrypt / 自签名),客户端默认改为 HTTPS,初次连接时做证书校验引导
- **影响范围**:`pixiv_app/gui/app.py`、`pixiv_app/core/cloud_sync.py`、云端 nginx/Caddy 配置
### 1.4 登录接口限流
- **现状**:`/api/v1/auth/login` 无限流,可暴力破解
- **方案**:对 `/login`、`/register`、`/token/refresh` 增加 IP 级别速率限制(如每分钟 5 次),使用 Redis 或内存计数器实现
- **影响范围**:`sakura_cloud/api/v1/endpoints/auth.py`、新增限流中间件
### 1.5 笔趣阁插件 AES 密钥随机化
- **现状**:`plugins/biquge/plugin.py` 中 AES 密钥和 IV 从硬编码字符串经 MD5 派生,固定 IV 下的 CBC 模式可被已知明文攻击
- **方案**:
- 每次加密使用随机 IV(`os.urandom(16)`),与密文一起传输
- 密钥从用户配置或安全随机源派生,而非硬编码
- **影响范围**:`plugins/biquge/plugin.py`
### 1.6 Chrome `--no-sandbox` 移除
- **现状**:小红书插件使用 `--no-sandbox` 禁用 Chromium 沙箱,浏览器以完整 OS 权限运行不受信任的外部内容
- **方案**:移除 `--no-sandbox`。若在 Docker/root 环境下必须使用,改为配置 `--cap-add=SYS_ADMIN` 或 seccomp profile
- **影响范围**:`plugins/xiaohongshu/plugin.py`
### 1.7 Firebase 初始化竞态修复
- **现状**:`push_notifications.dart` 中 `_initialized = true` 在 `await Firebase.initializeApp()` **之前**设置,若初始化失败则永久不再重试
- **方案**:将 `_initialized = true` 移到 `await Firebase.initializeApp()` 成功之后
- **影响范围**:`sakura_mobile/lib/src/core/push_notifications.dart`
### 1.8 ProxyPool 多线程数据竞争
- **现状**:`current_index` 无锁读写、`working_proxies` 并发修改、`fail_count`/`success_count` 非原子递增
- **方案**:引入 `threading.Lock` 保护所有对共享数据的写操作;或将 `current_index` 改为 `itertools.cycle` + 原子计数器
- **影响范围**:`pixiv_app/core/proxy_pool.py`
### 1.9 敏感文件 `.gitignore` 完善
- **现状**:`.env.cloud.example` 已提供模板,但不清楚 `.env` 是否在 `.gitignore` 中;会话文件 `app_session.json` 可能被误提交
- **方案**:在 `.gitignore` 中显式添加 `*.env`(除 `.example`)、`app_session.json`、`runtime/`、`*.db`、`*.key`
- **影响范围**:`.gitignore`
---
## 2. P1 — 核心体验缺陷
> 来源:代码审计报告 High/Medium 项 + 已知 bug + 功能缺口
### 2.1 手机端 `recentUpdatesOnly` 死开关修复
- **现状**:`gallery_tab.dart` 中 `recentUpdatesOnly` 状态变量只控制 Chip 高亮,从未作为 API 参数传入 `_load()`,切换无实际效果
- **方案**:在 `_load()` 中将 `recentUpdatesOnly` 转换为 `order=updated_at` 或后端新增 `recent_only` 查询参数;或如果后端暂时不支持,先移除该 Chip
- **影响范围**:`sakura_mobile/lib/src/pages/tabs/gallery_tab.dart`
### 2.2 Legado 书源搜索引擎完善
- **现状**:6 个默认种子源 `searchUrl` / `searchListRule` 全为 null,CSS 选择器解析不支持 class/ID/属性选择器,GBK 编码无容错
- **方案**(分两步):
- **2.2a 引擎层**:扩展 CSS 选择器支持 class(`.classname`)、ID(`#id`)、属性(`[attr=val]`)、后代(`A B`)选择器;GBK 解码增加容错参数
- **2.2b 源数据层**:用真实可用的书源 JSON 替换默认种子源,或提供从 Legado 仓库一键导入的引导流程
- **影响范围**:`legado_rule_parser.dart`、`legado_engine.dart`、`source_manager.dart`
### 2.3 手机端发现页滚动卡死修复
- **现状**:发现页 Feed 向上滚动时可能卡在底部
- **方案**:排查 `feed_tab.dart` 中的 `ScrollController` 和分页加载逻辑,确保加载更多后正确更新 `hasMore` 状态,以及 `ListView` 的 `addPostFrameCallback` 不产生死循环
- **影响范围**:`sakura_mobile/lib/src/pages/tabs/feed_tab.dart`
### 2.4 Web 管理后台页面完善
- **现状**:普通用户 Web 端详情页已从占位改为真实加载,但管理后台可能仍有死角
- **方案**:
- 完成管理员端用户管理、内容审核、统计面板页面
- 普通用户端确保图片/漫画/小说三种内容类型均有完整的列表+详情页
- **影响范围**:`sakura_admin_web/`
### 2.5 云同步上传失败队列与断点续传
- **现状**:`SAKURA_CLOUD_V1_STATUS.md` 明确标注"上传失败队列与断点恢复细节"尚未完成
- **方案**:
- 桌面端新增 `sync_failures` 表记录上传失败的文件,支持自动/手动重试
- 上传分片支持断点续传(保存已上传分片索引)
- 云端 `upload/complete` 接口增加分片校验
- **影响范围**:`pixiv_app/core/cloud_sync.py`、`sakura_cloud/api/v1/endpoints/upload.py`
### 2.6 Alembic 数据库迁移完善
- **现状**:SAKURA_CLOUD_V1_STATUS 标注 Alembic 迁移尚未完成
- **方案**:补全所有模型的 Alembic migration 脚本,确保 `alembic upgrade head` 一键建库;新增 CI 中检查迁移一致性
- **影响范围**:`sakura_cloud/migrations/`
### 2.7 手机端 App 正式签名
- **现状**:APK 使用调试签名,不适合正式分发;README 和用户手册均强调此限制
- **方案**:
- 生成正式 keystore
- 更新 `sakura_mobile/android/app/build.gradle.kts` 签名配置
- 文档更新,区分 debug/release 构建流程
- **影响范围**:`sakura_mobile/android/`、构建脚本
### 2.8 桌面端 Cookie 过期自动检测与提醒
- **现状**:Pixiv Cookie 过期后抓取静默失败,用户需手动排查
- **方案**:
- 在每次抓取前自动检测会话有效性(已有「检测会话」按钮逻辑,改为自动调用)
- Cookie 将过期或已过期时弹窗提醒并引导重新导入
- **影响范围**:`pixiv_app/core/auth.py`、`pixiv_app/gui/app.py`
### 2.9 下载失败自动重试与错误分类
- **现状**:`runtime/executor.py` 已有基本重试与错误分类,但未区分限流(429)、临时故障(5xx)、权限错误(403/404)
- **方案**:
- 429 → 自动退避重试(指数退避 + 抖动)
- 5xx → 有限重试(最多 2 次)
- 403/404 → 不重试,直接标记失败
- 失败原因写入 `download_tasks` 表便于排查
- **影响范围**:`pixiv_app/runtime/executor.py`、`pixiv_app/tasks/models.py`
### 2.10 图库搜索性能优化
- **现状**:图库 SQLite 查询在大数据量下(数万条作品)可能变慢,标签模糊搜索使用 `LIKE '%keyword%'` 无法走索引
- **方案**:
- 对 `artworks.title`、`artists.name`、`tags.name` 建立索引
- 标签搜索改为 FTS5 全文索引
- 云端的 `gallery` 查询为 `include_total` 参数已有优化,进一步对 `artworks.created_at`、`artworks.artist_id` 建立联合索引
- **影响范围**:`pixiv_app/core/library.py`、`sakura_cloud/models/artwork.py`
---
## 3. P2 — 功能完善与增强
### 3.1 手机端推送通知(FCM)
- **现状**:Firebase 已集成但推送链路不完整;当前"每日提醒"仅是应用内摘要,非系统级推送
- **方案**:
- 完成 FCM token 注册与服务端对接
- 云端提醒生成后通过 FCM 发送系统通知
- 点击通知直接跳转到对应内容
- 用户可配置"仅 Wi-Fi 下推送"、"免打扰时段"
- **影响范围**:`sakura_mobile/lib/src/core/push_notifications.dart`、`sakura_cloud/services/push.py`
### 3.2 插件市场在线对接
- **现状**:`PluginMarketClient` 为占位类,仅支持本地文件系统发现插件
- **方案**:
- 云端提供 `/api/v1/plugins/` 端点(列表、下载、版本检查)
- 桌面端「插件管理」面板增加"在线市场"标签页
- 支持一键安装/更新/卸载
- 插件版本兼容性检查
- **影响范围**:`pixiv_app/core/plugin/market.py`、`pixiv_app/gui/plugin_panel.py`、`sakura_cloud/` 新增端点
### 3.3 视频下载与播放支持
- **现状**:X/Twitter 插件可抓取视频文件,但本地图库和缩略图墙未针对视频做优化;手机端无视频播放页
- **方案**:
- 缩略图墙增加视频缩略图(自动截取首帧或使用平台提供的 thumbnail)
- 手机端新增视频播放页(基于 `video_player` 插件)
- 图库列表支持视频类型筛选
- **影响范围**:`pixiv_app/core/gallery_service.py`、`sakura_mobile/` 新增页面
### 3.4 阅读进度跨设备同步
- **现状**:手机端小说阅读器记录阅读进度,但仅本地存储(`online_reading_history.dart`)
- **方案**:
- 云端新增 `/api/v1/reading-progress/` 端点(GET/PUT)
- 手机端在进度变更时自动上报云端
- 桌面端缩略图墙也可展示阅读进度
- 多设备间同账号自动同步阅读位置
- **影响范围**:`sakura_mobile/lib/src/core/online_reading_history.dart`、`sakura_cloud/` 新增端点
### 3.5 内容合集 / 专辑功能
- **现状**:作品可以按作者、标签归类,但没有用户自定义合集的能力
- **方案**:
- 桌面端和手机端均支持创建"合集",将任意作品(图片/漫画/小说)归入合集
- 合集支持排序、封面设置、备注
- 云端同步合集数据
- **影响范围**:`pixiv_app/core/library.py`(新增表)、`sakura_cloud/models/`(新增模型)、`sakura_mobile/` 新增页面
### 3.6 漫画连续阅读模式增强
- **现状**:手机端已有漫画分组与连续阅读,但体验可以更流畅
- **方案**:
- 左右滑动翻页(当前可能仅支持上下滚动)
- 预加载下一页/上一页(当前页 ± 2 页)
- 阅读进度条(当前页/总页数)
- 双击缩放、长按保存
- **影响范围**:`sakura_mobile/lib/src/pages/online_manga_reader_page.dart`
### 3.7 批量导出功能
- **现状**:用户可通过缩略图墙浏览,但无法批量导出原图
- **方案**:
- 缩略图墙增加"批量选择 → 导出原图"功能
- 支持按作者/标签/收藏筛选后全选导出
- 导出格式:原图 ZIP 包或保持目录结构
- **影响范围**:`pixiv_app/core/gallery_service.py`、缩略图墙前端模板
### 3.8 X (Twitter) 作者时间线监控
- **现状**:X 插件支持抓取作者媒体和单个推文,但缺少"监控作者新推文"的主动检测
- **方案**:
- 桌面端新增"X 监控"面板,可添加监控的 X 用户名
- 定时轮询作者时间线,检测新推文 → 自动下载 → 写入云端关注提醒
- 与现有每日提醒系统打通
- **影响范围**:`plugins/x/`、`pixiv_app/core/x_media_service.py`
### 3.9 下载内容去重增强
- **现状**:`download_tasks` 表有 `fingerprint` 唯一约束,`artwork_files.content_hash` 字段已预留但默认空字符串
- **方案**:
- 下载完成后计算文件 SHA256 并写入 `content_hash`
- 新下载前先检查 `content_hash` 是否已存在,跳过重复文件
- 缩略图墙可展示"重复文件"列表,支持清理
- **影响范围**:`pixiv_app/core/downloader.py`、`pixiv_app/core/library.py`
### 3.10 代理池健康度评分
- **现状**:代理有 `fail_count` / `success_count` 但仅用于简单标记失败
- **方案**:
- 引入代理健康度评分(成功率、响应延迟、可用性百分比)
- 代理按健康度排序,优先使用高分代理
- 健康度过低的代理自动移出池
- 代理池 UI 展示健康度统计
- **影响范围**:`pixiv_app/core/proxy_pool.py`
---
## 4. P3 — 体验优化与锦上添花
### 4.1 桌面端深色模式
- **现状**:GUI 锁定 `ctk.set_appearance_mode("light")`
- **方案**:增加"外观"设置项——浅色 / 深色 / 跟随系统;`customtkinter` 原生支持 `dark` 模式,改动极小
- **影响范围**:`pixiv_app/gui/app.py`
### 4.2 缩略图墙 UI 现代化
- **现状**:缩略图墙是本地 WebUI(Jinja2 模板),功能齐全但 UI 风格较为基础
- **方案**:
- 引入轻量 CSS 框架(如 Pico.css 或 Water.css)美化
- 支持网格/列表视图切换
- 图片懒加载(当前可能一次性加载所有缩略图)
- 虚拟滚动(大量作品时性能优化)
- **影响范围**:`pixiv_app/core/gallery_service.py`、模板文件
### 4.3 手机端首页个性化配置
- **现状**:发现页展示"最近浏览的图片/漫画/小说"和"更新提醒"
- **方案**:
- 用户可选择发现页展示哪些模块(图片/漫画/小说/提醒)
- 支持拖拽排序模块
- "继续阅读"模块(直接从上次阅读位置进入)
- **影响范围**:`sakura_mobile/lib/src/pages/tabs/feed_tab.dart`
### 4.4 下载速度与流量统计
- **现状**:桌面端有进度条但无历史统计
- **方案**:
- 记录每次下载的文件大小、耗时
- 主界面增加"本次会话下载量"和"总计下载量"统计
- 可查看每日/每周下载量趋势图(可选,使用 matplotlib)
- **影响范围**:`pixiv_app/gui/app.py`、`pixiv_app/core/library.py`
### 4.5 国际化(i18n)支持
- **现状**:GUI 和手机端 UI 均为中文硬编码
- **方案**:
- 桌面端:提取所有 UI 字符串到 JSON 语言文件,支持中文/英文/日文
- 手机端:使用 Flutter `intl` / `easy_localization` 实现多语言
- 优先完成英文翻译以扩大用户群
- **影响范围**:全局 UI
### 4.6 错误日志收集与诊断
- **现状**:日志分散在 `日志/` 目录和终端输出,排查问题需手动翻找
- **方案**:
- 桌面端增加"一键导出诊断包"按钮(日志 + 配置 + 数据库状态摘要,压缩为 ZIP)
- 手机端增加"上传诊断日志"功能
- 云端增加错误聚合面板(按错误类型/时间统计)
- **影响范围**:`pixiv_app/`、`sakura_mobile/`、`sakura_cloud/`
### 4.7 桌面端系统托盘与后台运行
- **现状**:关闭 GUI 窗口即退出程序
- **方案**:
- 最小化到系统托盘(使用 `pystray` 或 `customtkinter` 配合系统托盘库)
- 托盘菜单:显示/隐藏窗口、开始/停止抓取、退出
- 下载完成后托盘气泡提示
- **影响范围**:`pixiv_app/gui/app.py`
### 4.8 自动更新检查
- **现状**:用户需手动关注 releases 目录获取新版本
- **方案**:
- 桌面端启动时检查云端最新版本号
- 有新版本时提示下载,可选"自动下载 → 下次启动替换"
- 手机端同理(检查 APK 版本号)
- **影响范围**:`pixiv_app/gui/app.py`、`sakura_mobile/lib/src/app.dart`、`sakura_cloud/` 新增版本检查端点
---
## 5. P4 — 长期架构演进
### 5.1 桌面端从 CustomTkinter 迁移到更现代化的 GUI 框架
- **理由**:CustomTkinter 功能有限,深色模式、动画、富文本等支持较弱;Windows 11 下风格略显过时
- **候选方案**:
- **Tauri (Rust + Web 前端)**:体积小、性能好、现代 UI,但需重写全部 Python 逻辑为 Rust 或通过 sidecar 通信
- **Electron + Python 后端**:重用现有 Python 下载引擎,Electron 负责 UI,但体积大(~150MB+)
- **PySide6 / PyQt6**:纯 Python 方案,迁移成本最低,支持 QSS 样式和丰富控件
- **Flet (Flutter for Python)**:用 Python 写 Flutter UI,可与现有 Flutter 移动端共享设计语言
- **建议**:优先评估 **Flet**(与 Flutter 移动端风格统一、纯 Python)或 **PySide6**(迁移成本最低)。不宜急于重写,等 P0/P1 完成后评估
### 5.2 iOS 客户端
- **理由**:当前仅支持 Android,iOS 用户无法使用
- **方案**:
- Flutter 跨平台特性使得 iOS 适配成本较低(大部分 Dart 代码可复用)
- 需额外处理:iOS 文件系统权限、后台任务限制、APNs 推送替代 FCM
- 需要 Apple Developer Program 账号($99/年)用于签名分发
- **影响范围**:`sakura_mobile/ios/`(生成)、`sakura_mobile/lib/`(少量平台适配)
### 5.3 Web 端 PWA(渐进式 Web 应用)
- **理由**:桌面端 EXE 体积大(~68MB),部分用户只希望轻量浏览
- **方案**:
- 将缩略图墙升级为 PWA(Service Worker + 离线缓存 + 可安装到桌面)
- 或单独开发 `sakura_web` 前端项目替代当前 `sakura_admin_web`
- **影响范围**:`sakura_admin_web/` 或新建 `sakura_web/`
### 5.4 分布式爬虫完善
- **现状**:`distributed_crawler/` 目录有 Master-Worker 架构但尚不完整
- **方案**:
- 补全 Worker 节点注册、心跳、任务分配
- Master 面板(Web UI)展示各 Worker 状态和任务进度
- Docker Compose 一键部署 Master + N Workers
- **影响范围**:`distributed_crawler/`
### 5.5 AI 辅助功能
- **理由**:PaddleOCR 已集成,可在其基础上扩展更多 AI 能力
- **方案**:
- **AI 标签自动生成**:对下载的图片使用轻量视觉模型(如 MobileNet/EfficientNet)自动打标签
- **翻译增强**:手机端小说翻译当前仅支持"当前页翻译",可升级为整本翻译 + 双语对照
- **图片去重**:基于感知哈希(pHash/dHash)的相似图片检测
- **内容安全扫描**:对上传至云端的内容进行自动安全审核(NSFW 检测)
- **影响范围**:`pixiv_app/core/ocr.py`、`sakura_cloud/services/ocr.py`
### 5.6 多用户/家庭共享
- **现状**:云同步为单用户设计,无分享功能
- **方案**:
- 云端新增"家庭组"/"共享空间"概念
- 用户可邀请其他账号加入共享空间
- 共享空间内的内容(图库/小说/漫画)成员均可访问
- 权限控制:管理员/编辑/只读
- **影响范围**:`sakura_cloud/` 新增模型与端点、手机端新增分享页面
---
## 6. 实施路线图
### 第一阶段:安全加固(第 1–2 周)
```
P0-1 JWT 密钥强制生产配置 ████████░░░░░░░░ 1d
P0-2 数据库/MinIO 凭据强制覆盖 ████████░░░░░░░░ 1d
P0-3 HTTPS 支持 + 警告 ████████████░░░░ 1.5d
P0-4 登录接口限流 ████████░░░░░░░░ 1d
P0-5 笔趣阁 AES 随机化 ████░░░░░░░░░░░░ 0.5d
P0-6 Chrome --no-sandbox 移除 ████░░░░░░░░░░░░ 0.5d
P0-7 Firebase 初始化竞态修复 ████░░░░░░░░░░░░ 0.5d
P0-8 ProxyPool 线程安全 ████████░░░░░░░░ 1d
P0-9 .gitignore 完善 ████░░░░░░░░░░░░ 0.5d
────────────────────────────────────────────────────────
小计约 7.5 人天
```
### 第二阶段:体验修复(第 3–6 周)
```
P1-1 手机端死开关修复 ████░░░░░░░░░░░░ 0.5d
P1-2 Legado 搜索引擎完善 ████████████████ 4d
P1-3 发现页滚动卡死 ████████░░░░░░░░ 2d
P1-4 Web 管理后台完善 ████████████░░░░ 3d
P1-5 上传失败队列 + 断点续传 ████████████████ 4d
P1-6 Alembic 迁移 ████████░░░░░░░░ 2d
P1-7 正式签名 ████░░░░░░░░░░░░ 1d
P1-8 Cookie 过期自动检测 ████████░░░░░░░░ 2d
P1-9 下载失败重试优化 ████████░░░░░░░░ 2d
P1-10 图库搜索性能 ████████████░░░░ 3d
────────────────────────────────────────────────────────
小计约 23.5 人天
```
### 第三阶段:功能增强(第 7–14 周)
```
P2-1 FCM 推送通知 ████████████████ 5d
P2-2 插件市场在线对接 ████████████████ 5d
P2-3 视频下载与播放 ████████████░░░░ 4d
P2-4 阅读进度跨设备同步 ████████████░░░░ 4d
P2-5 内容合集/专辑 ████████████████ 5d
P2-6 漫画连续阅读增强 ████████░░░░░░░░ 3d
P2-7 批量导出 ████████████░░░░ 4d
P2-8 X 作者时间线监控 ████████████░░░░ 4d
P2-9 下载去重增强 ████████░░░░░░░░ 3d
P2-10 代理池健康度评分 ████████░░░░░░░░ 3d
────────────────────────────────────────────────────────
小计约 40 人天
```
### 第四阶段及以后(按需排期)
```
P3-1 深色模式 ████░░ 1d
P3-2 缩略图墙 UI 现代化 ██████ 2d
P3-3 首页个性化 ██████ 2d
P3-4 下载统计 ████░░ 1.5d
P3-5 国际化 ██████ 3d
P3-6 错误诊断包 ██████ 2d
P3-7 系统托盘 ██████ 2d
P3-8 自动更新 ██████ 2d
P4-X 长期架构演进 TBD
────────────────────────────────────────────────────────
小计约 15.5 人天
```
### 关键里程碑
| 里程碑 | 时间 | 交付物 |
|--------|------|--------|
| **M1: 安全基线** | 第 2 周末 | 所有 P0 项修复完成,安全审计复测通过 |
| **M2: 体验基线** | 第 6 周末 | 所有 P1 项修复完成,核心链路无阻断 |
| **M3: 功能补全** | 第 14 周末 | P2 主要项完成,推送/插件市场/跨设备进度同步可用 |
| **M4: 体验升级** | 第 20 周末 | P3 项完成,深色模式/国际化/自动更新上线 |
---
## 附录:已完成功能清单(便于对照)
| 模块 | 已具备能力 |
|------|-----------|
| **桌面端** | 多平台抓取、Cookie/密码登录、插件系统、本地图库 SQLite、缩略图墙 WebUI、云同步、代理池、任务队列 + 增量同步、OCR |
| **云端** | FastAPI REST API、JWT 认证、图库/小说/文件 CRUD、关注管理、每日提醒摘要、分片上传、健康检查 |
| **手机端** | 登录注册、发现/图片/漫画/书架/我的 五个标签页、小说阅读器(分页/收藏/翻译/进度)、漫画分组阅读、书源管理+Legado 引擎、在线搜索、FCM(部分) |
| **插件** | Pixiv、X/Twitter、小红书、笔趣阁、长佩文学、AO3 |
| **DevOps** | 一键构建 EXE/APK、Docker Compose 部署、Alembic 迁移 |
---
*本文档由代码审计报告、产品文档、CHANGELOG、SAKURA_CLOUD_V1_STATUS 及全仓库源码分析综合生成,供开发排期与需求评审参考。*
+745
View File
@@ -0,0 +1,745 @@
# 四大问题完整修复方案(终版)
> 更新日期: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 天且不内置任何仓库、问题一拆为两层修复(第一层必做 + 第二层按需)、问题四拆为开发/生产两套方案、问题三补搜索防抖、三阶段实施计划
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+778
View File
@@ -0,0 +1,778 @@
下面是整合后的**最终完整方案**,包括:漫画解析、章节完整性、图片加载、调试能力、搜索性能,以及你刚刚提到的顶部搜索框 UI 问题。
Sakura 漫画模块完整改进方案
=================
一、改进目标
------
本轮改造解决 5 类问题:
1. 漫画章节目录不全
2. 漫画图片解析失败
3. 图片 URL 有数量但无法显示
4. 在线搜索速度慢
5. 漫画 / 图片页顶部搜索框布局异常,在线搜索入口位置不合理
* * *
二、整体优先级
=======
P0:顶部搜索框 UI 修复与在线搜索入口重构
P1:图片 URL 合法性验证
P2:PageImage + headers 拆分
P3:图片 HTTP 探测与调试能力
P4:TOC 分页抓全章节
P5:章节排序支持番外
P6:Script 图片变量提取
P7:漫画调试页
P8:搜索健康分与增量搜索
说明:
P0 先做,因为它是明显 UI 问题,改动小、收益快。
P1~P7 解决漫画“能不能看”。
P8 最后做,解决“搜得慢”。
* * *
P0:顶部搜索框 UI 修复与在线搜索入口重构
=======================
问题
--
截图中红框区域出现:
顶部搜索栏被状态栏 / 右上角按钮挤压
漫画页和图片页都出现同类问题
在线搜索入口放在右上角,不符合用户预期
目标
--
漫画页 / 图片页顶部布局稳定
搜索框不被状态栏遮挡
在线搜索入口集成到搜索框流程中
不再在右上角放在线搜索按钮
推荐交互
----
页面顶部只保留一个统一搜索框:
[ 搜索图标 ] 搜索标题、作者或标签 [筛选] [刷新]
点击搜索框进入统一搜索页:
SearchPage
├─ 搜索输入框
├─ 搜索范围切换:本地 / 在线 / 全部
└─ 结果分区:
├─ 本地漫画
├─ 在线漫画源
└─ 图片 / 插画
代码结构
----
新增统一组件:
class SakuraSearchBar extends StatelessWidget {
final String hintText;
final VoidCallback onTap;
final VoidCallback? onFilterTap;
final VoidCallback? onRefreshTap;
const SakuraSearchBar({
super.key,
required this.hintText,
required this.onTap,
this.onFilterTap,
this.onRefreshTap,
});
@override
Widget build(BuildContext context) {
return Material(
elevation: 6,
borderRadius: BorderRadius.circular(32),
color: Theme.of(context).colorScheme.surface,
child: InkWell(
borderRadius: BorderRadius.circular(32),
onTap: onTap,
child: SizedBox(
height: 56,
child: Row(
children: [
const SizedBox(width: 18),
const Icon(Icons.search),
const SizedBox(width: 12),
Expanded(
child: Text(
hintText,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: Theme.of(context).textTheme.titleMedium,
),
),
if (onFilterTap != null)
IconButton(
icon: const Icon(Icons.tune),
onPressed: onFilterTap,
),
if (onRefreshTap != null)
IconButton(
icon: const Icon(Icons.refresh),
onPressed: onRefreshTap,
),
const SizedBox(width: 8),
],
),
),
),
);
}
}
页面顶部必须用:
SafeArea(
bottom: false,
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 8, 16, 8),
child: SakuraSearchBar(
hintText: '搜索标题、作者或标签',
onTap: () {
Navigator.push(
context,
MaterialPageRoute(
builder: (_) => UnifiedSearchPage(
initialMode: SearchMode.manga,
),
),
);
},
onFilterTap: _openFilter,
onRefreshTap: _refresh,
),
),
)
禁止再用:
Stack + Positioned 顶部硬定位
AppBar 右上角塞在线搜索入口
状态栏高度手动写死
* * *
P1:图片 URL 合法性验证
===============
目标
--
不要相信 `1/17` 这种页数。它可能是:
17 个真实图片
17 个空字符串
17 个 loading 图
17 个 placeholder
17 个错误 URL
新增模型:
class ImageCandidate {
final String raw;
final String? url;
final bool isValid;
final String? reason;
const ImageCandidate({
required this.raw,
required this.url,
required this.isValid,
this.reason,
});
}
验证逻辑:
ImageCandidate validateImageCandidate(String raw, String baseUrl) {
final value = raw.trim();
if (value.isEmpty) {
return ImageCandidate(
raw: raw,
url: null,
isValid: false,
reason: 'empty',
);
}
if (value.startsWith('data:')) {
return ImageCandidate(
raw: raw,
url: null,
isValid: false,
reason: 'data-uri',
);
}
final lower = value.toLowerCase();
if (lower.contains('loading') ||
lower.contains('placeholder') ||
lower.contains('logo') ||
lower.contains('icon')) {
return ImageCandidate(
raw: raw,
url: value,
isValid: false,
reason: 'placeholder',
);
}
final normalized = normalizeImageUrl(value, baseUrl);
final uri = Uri.tryParse(normalized);
if (uri == null || !uri.hasScheme || uri.host.isEmpty) {
return ImageCandidate(
raw: raw,
url: normalized,
isValid: false,
reason: 'invalid-url',
);
}
return ImageCandidate(
raw: raw,
url: normalized,
isValid: true,
);
}
URL 归一化:
String normalizeImageUrl(String raw, String baseUrl) {
var u = raw.trim()
.replaceAll(r'\/', '/')
.replaceAll(r'\u002F', '/');
if (u.startsWith('//')) {
u = 'https:$u';
}
return Uri.parse(baseUrl).resolve(u).toString();
}
* * *
P2:PageImage + headers 拆分
=========================
问题
--
Legado 漫画源经常返回:
https://xxx.jpg,{"headers":{"Referer":"https://site.com"}}
如果直接丢给:
Image.network(raw)
图片必炸。
新模型
---
class PageImage {
final int index;
final String raw;
final String url;
final Map<String, String> headers;
const PageImage({
required this.index,
required this.raw,
required this.url,
required this.headers,
});
}
拆分逻辑
----
class ParsedImageSpec {
final String url;
final Map<String, String> headers;
ParsedImageSpec({
required this.url,
required this.headers,
});
}
ParsedImageSpec splitLegadoImageSpec(String raw) {
final idx = raw.indexOf(',{');
if (idx < 0) {
return ParsedImageSpec(url: raw.trim(), headers: {});
}
final url = raw.substring(0, idx).trim();
final jsonText = raw.substring(idx + 1).trim();
final headers = <String, String>{};
try {
final decoded = jsonDecode(jsonText);
final h = decoded['headers'];
if (h is Map) {
h.forEach((k, v) {
headers[k.toString()] = v.toString();
});
} else if (h is String) {
final inner = jsonDecode(h);
if (inner is Map) {
inner.forEach((k, v) {
headers[k.toString()] = v.toString();
});
}
}
} catch (_) {}
return ParsedImageSpec(url: url, headers: headers);
}
生成 PageImage:
PageImage buildPageImage({
required String raw,
required String chapterUrl,
required LegadoSource source,
required int index,
}) {
final parsed = splitLegadoImageSpec(raw);
final headers = <String, String>{
...source.headers,
'User-Agent': source.userAgent ?? defaultUserAgent,
'Referer': chapterUrl,
...parsed.headers,
};
return PageImage(
index: index,
raw: raw,
url: normalizeImageUrl(parsed.url, chapterUrl),
headers: headers,
);
}
阅读器改成:
Image.network(
page.url,
headers: page.headers,
fit: BoxFit.contain,
errorBuilder: (_, error, stack) {
return const Icon(Icons.broken_image);
},
)
* * *
P3:图片 HTTP 探测
=============
目标
--
判断到底是:
URL 错
headers 错
反爬
图片损坏
Flutter 缓存问题
新增:
class ImageProbeResult {
final String url;
final int? statusCode;
final String? contentType;
final int contentLength;
final String first16BytesHex;
final bool looksLikeImage;
final String? error;
const ImageProbeResult({
required this.url,
this.statusCode,
this.contentType,
required this.contentLength,
required this.first16BytesHex,
required this.looksLikeImage,
this.error,
});
}
探测:
Future<ImageProbeResult> probeImage(Dio dio, PageImage image) async {
try {
final resp = await dio.get<List<int>>(
image.url,
options: Options(
responseType: ResponseType.bytes,
headers: image.headers,
validateStatus: (_) => true,
),
);
final bytes = resp.data ?? const <int>[];
final first16 = bytes
.take(16)
.map((b) => b.toRadixString(16).padLeft(2, '0'))
.join();
return ImageProbeResult(
url: image.url,
statusCode: resp.statusCode,
contentType: resp.headers.value('content-type'),
contentLength: bytes.length,
first16BytesHex: first16,
looksLikeImage: isImageMagic(bytes),
);
} catch (e) {
return ImageProbeResult(
url: image.url,
contentLength: 0,
first16BytesHex: '',
looksLikeImage: false,
error: e.toString(),
);
}
}
魔数判断:
bool isImageMagic(List<int> b) {
if (b.length < 4) return false;
// JPG
if (b[0] == 0xFF && b[1] == 0xD8 && b[2] == 0xFF) return true;
// PNG
if (b[0] == 0x89 && b[1] == 0x50 && b[2] == 0x4E && b[3] == 0x47) {
return true;
}
// WEBP
if (b.length >= 12 &&
b[0] == 0x52 &&
b[1] == 0x49 &&
b[2] == 0x46 &&
b[3] == 0x46 &&
b[8] == 0x57 &&
b[9] == 0x45 &&
b[10] == 0x42 &&
b[11] == 0x50) {
return true;
}
// GIF
if (b[0] == 0x47 && b[1] == 0x49 && b[2] == 0x46 && b[3] == 0x38) {
return true;
}
// BMP
if (b[0] == 0x42 && b[1] == 0x4D) return true;
return false;
}
诊断表:
403 / 444
→ Referer / User-Agent / Cookie 问题
404
→ 图片 URL 拼错或章节页已失效
200 + text/html
→ 反爬页 / 登录页 / 错误页
200 + image/* + contentLength < 1024
→ 可能是伪装错误图或破损图
200 + image/* + 魔数失败
→ 响应不是有效图片
200 + image/* + 魔数成功但 Image.network 不显示
→ headers 没传进 Image.network / 图片缓存污染 / Flutter 图片组件问题
* * *
P4:TOC 分页抓全章节
=============
问题
--
一人之下 600+ 话,但现在只显示几十章,说明目录分页没有抓全。
支持字段
----
tocNextPageRule
nextTocUrl
nextUrl
nextPage
tocNextPage
抓取流程
----
firstTocUrl
→ 请求当前页
→ 解析 chapterList
→ 解析 nextTocUrl
→ resolve 成绝对 URL
→ 合并章节并去重
→ 继续下一页
终止条件
----
nextUrl == null
seenPageUrls 已访问
连续 2 页新增章节为 0
pageCount >= 100
chapterCount >= 3000
建议参数:
const maxTocPages = 100;
const maxTocChapters = 3000;
const emptyPageDelay = Duration(milliseconds: 500);
* * *
P5:章节排序支持番外
===========
支持:
第660话
第660.5回
Ch.660
ch 660.5
660话
660.5 番外
章节号提取:
double? extractChapterNo(String title) {
var m = RegExp(r'第\s*(\d+(?:\.\d+)?)\s*[回话章节节]').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
m = RegExp(r'[Cc]h\.?\s*(\d+(?:\.\d+)?)').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
m = RegExp(r'^\s*(\d+(?:\.\d+)?)\s*(?:话|回|章|节)?').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
return null;
}
排序:
chapters.sort((a, b) {
final na = extractChapterNo(a.title);
final nb = extractChapterNo(b.title);
if (na != null && nb != null && na != nb) {
return na.compareTo(nb);
}
return a.index.compareTo(b.index);
});
* * *
P6:Script 图片变量提取
================
当 `ruleContent.content` 失败或候选图片全无效时,从 rawHtml 的 script 中提取图片。
支持变量:
newImgs
imageList
page_url
chapterImages
photosr
img_data
picTree
示例:
List<String> extractImagesFromScripts(String html) {
final out = <String>[];
final patterns = [
RegExp(r'newImgs\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'imageList\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'"page_url"\s*:\s*(\[[\s\S]*?\])'),
RegExp(r'chapterImages\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'photosr\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'img_data\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'picTree\s*=\s*(\[[\s\S]*?\])'),
];
for (final p in patterns) {
final m = p.firstMatch(html);
if (m == null) continue;
final raw = m.group(1)!;
final list = tryDecodeStringList(raw);
out.addAll(list.map(sanitizeScriptUrl));
}
return out;
}
清洗:
String sanitizeScriptUrl(String url) {
return url
.replaceAll(r'\/', '/')
.replaceAll(r'\u002F', '/');
}
* * *
P7:漫画调试页
========
入口
--
书籍详情页 → 长按章节 → 调试本章
阅读器右上角菜单 → 调试当前章
展示内容
----
{
"sourceName": "包子漫画5",
"bookTitle": "一人之下",
"chapterTitle": "第652回",
"chapterUrl": "...",
"ruleContent": "...",
"rawHtmlLength": 123456,
"contentOutputLength": 2048,
"rawCandidateCount": 17,
"validCandidateCount": 0,
"pageImageCount": 0,
"firstCandidates": [
{
"raw": "...",
"normalized": "...",
"reason": "placeholder"
}
],
"probe": [
{
"url": "...",
"status": 200,
"contentType": "image/jpeg",
"contentLength": 312,
"first16Bytes": "ffd8ff...",
"looksLikeImage": false
}
]
}
操作按钮
----
复制调试信息
重新检测前 5 张图
切换 Referer:章节页 / 详情页 / 源首页
清除图片缓存后重试
打开原始章节 URL
* * *
P8:搜索健康分与增量搜索
=============
问题
--
搜索慢主要来自:
坏源太多
每个源 timeout 太长
所有源一起等结果
模型
--
class SourceHealth {
final String sourceId;
int successCount = 0;
int failCount = 0;
int timeoutCount = 0;
int totalLatencyMs = 0;
int consecutiveFails = 0;
DateTime? lastSuccessAt;
DateTime? lastFailAt;
}
策略
--
健康源优先
坏源降权
连续失败 >= 5 临时跳过
搜索超时 5~8 秒
快速源先返回
慢源后台补充
搜索阶段
----
0~5s:快速源结果
5~8s:普通源结果
8s 后:慢源后台补
* * *
三、最终落地顺序
========
第 1 阶段:UI 先止血
-------------
P0:顶部搜索框 UI 修复
P0:在线搜索入口放进统一搜索页
结果:
漫画页 / 图片页顶部不再错位
在线搜索不再占右上角
搜索体验统一
第 2 阶段:图片链路可观测
--------------
P1:图片 URL 合法性验证
P2:PageImage + headers 拆分
P3:图片 HTTP 探测
P7:漫画调试页
结果:
可以准确判断图片失败原因
不再靠猜
第 3 阶段:章节抓全
-----------
P4:TOC 分页
P5:章节排序
结果:
一人之下这类 600+ 话漫画可以抓全
章节顺序稳定
第 4 阶段:提升漫画源覆盖率
---------------
P6:Script 图片变量提取
结果:
更多漫画源能解析图片
第 5 阶段:优化搜索速度
-------------
P8:搜索健康分与增量搜索
结果:
坏源不拖慢搜索
结果更快出现
* * *
=======
@@ -0,0 +1,70 @@
# 视频云同步与内容合集设计方案
## 目标
让 X、小红书、抖音采集到的视频和图片一样进入 Sakura Cloud,并能在手机端与 Web 端查看。云端对每个用户的视频总占用做 30GB 上限,Web 端从“后台列表”调整为适合阅读、看视频、浏览插画的内容合集。
## 云端设计
- 复用现有 `upload / sync / gallery / files` 链路,不新增数据库表,不改变 API 返回结构。
- 视频仍作为 `Artwork` 保存,`content_type=video`,`mime_type=video/*`,文件实体复用 `FileBlob` 与 `UserFile`。
- 上传接口允许 `resource_type=video`,视频文件进入 `uploads/videos/{user_id}/{year}/{month}`。
- 新增配置:
- `MAX_VIDEO_UPLOAD_SIZE_MB=2048`:单个视频默认最大 2GB。
- `VIDEO_STORAGE_LIMIT_GB=30`:单用户视频总空间上限 30GB。
- 配额计算以当前登录用户为准,从 `UserFile -> FileBlob` 统计该用户所有 `mime_type LIKE 'video/%'` 的文件大小。命中上限时返回 `413`,不会创建上传会话。
- 已存在文件秒传时同样检查该用户的视频总配额,防止跨用户复用文件绕过限制。
## 桌面端采集同步设计
- `SyncManager` 根据 MIME 与 `content_type` 判断上传资源类型:
- 小说:`novel`
- 视频:`video`
- 其他:`image`
- X 手动预览下载和关注作者同步共用云端同步逻辑,视频文件下载成功后自动同步 metadata。
- WebUI 通用插件下载路径也接入云同步,因此小红书、抖音插件只要返回 `files=[{type: "video"}]`,就能自动上传云端。
- 小红书插件补充 DOM 视频解析,支持从 `video/source` 标签提取直接视频地址;搜索结果进入详情下载时也同时处理 `images + videos`。
- 抖音插件已有视频文件抽取与下载逻辑,本方案复用其 `Resource.files` 输出,不重写下载器。
## 手机端设计
- `Artwork` 模型补充 `mimeType`、`fileSize`、`isVideo` 与 `primaryMediaPath`。
- 图库页新增视频筛选,视频卡片显示播放叠层,不再伪装成普通插画。
- 视频详情页展示视频封面、标题、作者、MIME、大小,并提供:
- 播放视频
- 下载到本地
- 收藏
- 为避免新增播放器依赖导致构建不稳定,当前采用“受保护下载到本地后调用系统播放器”的方式。
- Android 通过 FileProvider 暴露 Sakura 下载目录中的临时读取 URI,不暴露任意路径。
## Web 端内容合集设计
- 普通用户首页改为内容合集:
- 顶部概览:用户、空间、视频额度、最近内容。
- 视频区:16:9 视频卡片,播放标记,显示作者与大小。
- 插画区:缩略图网格。
- 漫画区:阅读列表入口。
- 小说区:阅读列表入口。
- 在线搜索与提醒中心作为主操作入口。
- 页面复用现有 API:
- `/me/gallery?content_type=video`
- `/me/gallery?content_type=illust`
- `/me/gallery?content_type=manga`
- `/novels/series`
- CSS 使用现有粉白主题、8px 圆角和响应式网格,手机浏览时自动改为单列。
## 安全与边界
- 不上传第三方平台 Cookie、Token 或浏览器登录态。
- 云端只保存视频文件与作品 metadata。
- 视频配额按当前登录用户统计,避免水平越权。
- 文件读取继续走现有 `/files` 和 gallery ownership 校验。
- Android FileProvider 只给外部播放器一次性读取 URI,不暴露数据库或任意文件系统路径。
## 验收点
- X、小红书、抖音插件下载视频后,云同步开启时视频可进入 cloud gallery。
- 超过 30GB 视频总配额时,上传初始化返回 413。
- 手机端图库可以筛选视频,视频详情可以下载并调用系统播放器查看。
- Web 普通用户首页能看到视频、插画、漫画、小说四类内容入口。
- 现有图片、漫画、小说同步与阅读入口保持可用。
+322
View File
@@ -0,0 +1,322 @@
# Sakura Downloader(樱云下载器)项目方案书
> 版本:v1.0 | 日期:2026-06-18 | 状态:已交付
---
## 一、项目概述
### 1.1 项目名称
**Sakura Downloader(樱云下载器)** — 个人媒体采集、本地图库管理与跨设备云同步系统。
### 1.2 项目定位
一个面向个人用户的**多媒体内容采集-整理-阅读一体化平台**,解决"从多个内容平台采集插画/漫画/小说 → 本地归档整理 → 在手机/桌面等多设备上随时浏览阅读"的完整链路。
### 1.3 核心价值
| 痛点 | 解决方案 |
|------|----------|
| 多平台内容分散(Pixiv、X、小红书、AO3、笔趣阁等) | 统一插件架构,一个入口采集所有平台 |
| 下载后文件散乱、难以检索 | 本地图库 + SQLite 索引 + 缩略图墙 + 标签/作者搜索 |
| 桌面下载了,手机上没法看 | Sakura Cloud 云端同步,手机端实时访问 |
| 关注的作者更新了不知道 | 云端每日摘要提醒,手机端查看 |
| 跨平台小说阅读体验差 | Flutter 移动端专为阅读优化:自动分页、进度记忆、翻译、字体调节 |
---
## 二、系统架构
### 2.1 整体拓扑
```text
┌─────────────────────────────────────────────────────────┐
│ Sakura Cloud (FastAPI) │
│ PostgreSQL + JWT Auth │
│ api.kunkunxiaomao.top:8000 │
└──────┬──────────────────────┬───────────────────────────┘
│ REST API │ REST API
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Windows 桌面端 │ │ Android 移动端 │
│ Python + │ │ Flutter + │
│ CustomTkinter │ │ Riverpod + Dio │
│ (采集/整理中枢) │ │ (阅读/提醒终端) │
└──────┬─────────┘ └──────────────────┘
│ 本地 SQLite │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ 本地图库文件 │ │ 本地缓存/下载 │
│ (图片/漫画/小说)│ │ (离线阅读) │
└──────────────┘ └──────────────┘
```
### 2.2 技术栈总览
| 层级 | 技术选型 |
|------|----------|
| **Windows 桌面端** | Python 3.8+ · CustomTkinter · SQLite · Playwright · Pillow |
| **云端 API** | FastAPI · PostgreSQL · SQLAlchemy · Alembic · JWT · Docker |
| **Android 移动端** | Flutter 3.x · Dart · Riverpod · Dio · shared_preferences |
| **管理后台 Web** | Vite · TypeScript · Vue/React · Nginx |
| **插件系统** | Python 动态加载 · manifest.json · 统一 PluginBase 接口 |
| **打包分发** | PyInstaller (EXE) · Flutter build (APK) |
---
## 三、客户端种类与职责
### 3.1 Windows 桌面端(`pixiv_app/` + `main.py`)
**角色:采集与整理中枢**
| 功能模块 | 说明 |
|----------|------|
| **多平台采集** | 通过插件系统支持 Pixiv、X (Twitter)、小红书、AO3、笔趣阁等 |
| **Cookie/密码登录** | 支持 Cookie 导入(推荐)和账号密码登录 |
| **灵活抓取模式** | 作者全部作品、单作品/漫画、小说/系列、关键词搜索 |
| **本地图库** | SQLite 索引 + 文件系统存储,支持缩略图生成 |
| **缩略图墙** | 本地 Web 服务(127.0.0.1:8765),浏览器中浏览、搜索、筛选、收藏 |
| **关注同步** | Pixiv 关注作者管理 + X 关注同步 |
| **云同步** | 一键上传到 Sakura Cloud,自动同步新下载内容 |
| **代理池** | 浏览器代理池 + HTTP 代理,规避反爬 |
| **Playwright 集成** | 无头浏览器渲染 JS 页面(X 插件依赖) |
| **指纹伪装** | 浏览器指纹随机化,降低封禁风险 |
**打包产物**:`sakuradownloader.exe` (~68 MB, PyInstaller 单文件)
### 3.2 Sakura Cloud 云端(`sakura_cloud/`)
**角色:数据与账号中心**
| 功能模块 | 说明 |
|----------|------|
| **用户系统** | 注册/登录/邮箱验证/JWT Token 鉴权 |
| **媒体存储** | 图片/漫画/小说上传、存储、缩略图生成 |
| **收藏系统** | 跨设备收藏同步 |
| **关注与提醒** | 关注作者管理 + 每日更新摘要提醒 |
| **阅读进度** | 小说阅读进度云端存储,跨设备同步 |
| **管理后台** | SPA 管理控制台(可选) |
| **自动运维** | 启动自动 migrate、定时清理过期上传、每 5 分钟检查提醒摘要 |
**部署方式**:Docker Compose(FastAPI + PostgreSQL)
### 3.3 Android 移动端(`sakura_mobile/`)
**角色:跨设备阅读与提醒终端**
| 功能模块 | 说明 |
|----------|------|
| **发现页** | 最近浏览 + 更新提醒摘要 |
| **图片页** | 缩略图列表 · 详情 · 收藏 · 下载 · 编辑 · 删除 |
| **漫画页** | 按漫画分组浏览,整组连续阅读,整组下载 |
| **书架页** | 三列彩色方块风格,系列小说按书名归档,章节选择 |
| **小说阅读器** | 自动分页 · 阅读进度记忆 · 收藏 · 当前页翻译 · 原文/译文切换 · 字体/行高/背景色调节 · 章节切换 |
| **我的页** | 用户资料 · 云端空间 · 收藏管理 · 每日提醒开关/时间 · 提醒中心 |
| **搜索** | 图片/漫画/小说全局搜索 |
**打包产物**:`app-release.apk` (~54 MB, 调试签名)
### 3.4 管理后台 Web(`sakura_admin_web/`)
**角色:云端管理控制台**
- 基于 Vite + TypeScript 的 SPA 单页应用
- 通过 Sakura Cloud 的 `/admin` 路由挂载
- 提供可视化的数据和用户管理界面
- 可选部署(`admin_frontend_enabled` 配置项)
---
## 四、插件体系
### 4.1 插件架构
```text
plugins/
├── pixiv/ # Pixiv 插画/漫画/小说
│ ├── manifest.json
│ └── plugin.py
├── x/ # X (Twitter) 媒体
│ ├── manifest.json
│ ├── plugin.py
│ ├── playwright_client.py
│ └── x_login.py
├── xiaohongshu/ # 小红书
├── ao3/ # Archive of Our Own
└── biquge/ # 笔趣阁(小说)
```
### 4.2 插件接口规范
每个插件只需实现 `PluginBase` 抽象类,包含:
- `platform_name` — 平台标识
- `supports_modes` — 支持的抓取模式列表
- `search()` — 搜索
- `fetch_work()` — 获取作品详情
- `fetch_author_works()` — 获取作者全部作品
- `download()` — 下载媒体文件
通过 `manifest.json` 声明元数据,桌面端启动时自动发现并加载。
---
## 五、核心数据流
### 5.1 采集下载流程
```text
用户输入(ID/链接/关键词)
│
▼
任务解析器 (parser.py)
│
▼
任务队列 (queue.py)
│
▼
插件调度 → 对应平台 plugin.py
│
▼
HTTP/Playwright 抓取 → 解析作品列表
│
▼
下载器 (downloader.py) → 保存到本地图库
│
▼
SQLite 索引写入 + 缩略图生成
│
▼
(可选) 云同步上传到 Sakura Cloud
```
### 5.2 云同步流程
```text
桌面端下载完成
│
▼
检查"启用云同步"开关
│
▼
cloud_sync.py → POST /api/v1/media/upload
│
▼
Sakura Cloud 存储 + 生成缩略图
│
▼
移动端刷新 → GET /api/v1/media → 展示
```
### 5.3 每日提醒流程
```text
桌面端同步关注作者的新作品到云端
│
▼
云端写入 follow + update_alert 记录
│
▼
reminder_digest_loop (每5分钟检查)
│
▼
到达用户设定的提醒时间 → 生成每日摘要
│
▼
移动端"发现"页展示更新提醒
```
---
## 六、用法概览
### 6.1 桌面端典型工作流
1. **登录** → 导入 Pixiv Cookie(推荐)或账号密码登录
2. **抓取** → 选择平台 → 选择模式 → 输入目标 → 开始抓取
3. **浏览** → 打开缩略图墙 → 搜索/筛选/收藏
4. **关注** → 在缩略图墙中关注作者 → 后续同步关注作者更新
5. **云同步** → 登录 Sakura Cloud → 开启云同步 → 自动上传
### 6.2 移动端典型工作流
1. **安装** → 安装 APK → 允许未知来源
2. **登录** → 使用与桌面端相同的 Sakura Cloud 账号
3. **浏览** → 底部 5 个页签切换(发现/图片/漫画/书架/我的)
4. **阅读小说** → 自动分页 · 调节字体 · 翻译 · 章节切换
5. **提醒** → 我的 → 每日更新提醒 → 开启并设置时间
### 6.3 云端部署
```bash
cd sakura_cloud
docker-compose up -d
# FastAPI :8000 + PostgreSQL :5432
```
### 6.4 构建打包
```bash
# 桌面 EXE
scripts\build_desktop_exe.bat
# Android APK
scripts\build_mobile_android.bat
# 复制到 releases/
scripts\copy_release_artifacts.bat
```
---
## 七、项目交付物
| 交付物 | 路径 | 说明 |
|--------|------|------|
| Windows EXE | `releases/sakuradownloader.exe` | 双击即用,~68 MB |
| Android APK | `releases/app-release.apk` | 调试签名,~54 MB |
| 用户使用说明 | `使用说明-桌面版与安卓版.md` | 终端用户操作手册 |
| 项目方案书 | `docs/项目方案书.md` | 本文档 |
| 开发文档 | `项目文件/BUILD.md` | 构建与排错 |
| 构建脚本 | `scripts/` | 一键打包脚本 |
| 云端 API | `sakura_cloud/` | Docker 部署 |
| 源码 | 全部 Python/Dart/TypeScript | 可二次开发 |
---
## 八、技术亮点
1. **插件化架构** — 新平台接入只需新增一个插件目录,不改动核心代码
2. **多反爬策略** — Cookie 管理 · Playwright 无头浏览器 · 代理池 · 指纹伪装 · 限速退避
3. **跨设备云同步** — 桌面采集 → 云端存储 → 手机阅读,全链路打通
4. **沉浸式阅读体验** — 自动分页 · 进度记忆 · 即时翻译 · 个性化排版
5. **智能提醒** — 关注作者更新云端汇总,非本地闹钟,静默不打扰
6. **本地优先** — 所有数据本地 SQLite 存储,云端为可选项,离线也能用
---
## 九、后续演进方向
| 方向 | 说明 |
|------|------|
| iOS 客户端 | Flutter 已预留 iOS 平台支持,补充苹果开发者账号与签名 |
| 正式应用签名 | APK 替换调试签名为正式 keystore,支持上架分发 |
| 更多平台插件 | 持续扩充插件库(如 Fantia、Fanbox、DeviantArt 等) |
| AI 能力增强 | OCR 文字识别(代码已预留)· AI 翻译优化 · 智能标签 |
| 分布式爬取 | `distributed_crawler/` 目录已有 Master-Worker 架构原型 |
| PWA 移动端 | 缩略图墙升级为 PWA,支持手机浏览器直接访问 |
---
## 十、许可与免责
- 本项目仅供个人学习、研究及合法使用。
- 使用 X 插件需自行承担对应平台的使用条款风险。
- APK 当前为调试签名,仅供个人测试,不宜正式分发。
- 请遵守各内容平台的用户协议,合理使用爬取功能。
---
*文档生成于 2026-06-18 · Sakura Downloader Project*