commit
9c5fef1a4d
412 files changed
+94582
No files matched your search
@@ -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 |
|
||||
@@ -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
@@ -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
+1187
File diff suppressed because it is too large.
Load diff
+410
@@ -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 个问题。
|
||||
@@ -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 及全仓库源码分析综合生成,供开发排期与需求评审参考。*
|
||||
@@ -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
@@ -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
@@ -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*
|
||||
Reference in new issue
Block a user