Files
SakuraHub/docs/APK端漫画小说源与WEB端认证修复方案.md
T
2026-11-16 20:45:22 +08:00

1977 lines
80 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# APK 端漫画/小说第三方源集成 + WEB 端认证修复方案
> 更新日期:2026-06-15
> 范围:Sakura Mobile (Flutter APK) + Sakura Cloud (FastAPI) + Sakura Admin Web (Vue.js)
> 说明:本文档提供完整的问题分析与实现方案,按模块划分,方便逐步实施。
---
## 目录
1. [APK 端:漫画与小说第三方来源网站集成](#一apk-端漫画与小说第三方来源网站集成)
2. [APK 端:未保存内容的在线搜索与实时浏览](#二apk-端未保存内容的在线搜索与实时浏览)
3. [WEB 端:认证失败与登录页缺失修复](#三web-端认证失败与登录页缺失修复)
4. [APK 端 UI 美化:配色、标题与选项卡](#四apk-端-ui-美化配色统一标题优化与选项卡样式修复)
5. [实施优先级与排期建议](#五实施优先级与排期建议)
---
## 一、APK 端:漫画与小说第三方来源网站集成
### 1.1 现状分析
当前 Sakura Mobile Flutter 应用的画廊(Gallery)和小说(Novels)板块,数据来源仅限于:
- **自建 Sakura Cloud 后端**(`api.kunkunxiaomao.top:8000`)—— 即用户手动同步/上传到私有云的内容
- 移动端 `api_client.dart` 中的 `gallery()` 和 `novels()` 方法直接调用云端 API
- **没有接入任何第三方漫画/小说源**
### 1.2 目标与核心约束
为漫画板块和小说板块分别接入多个第三方内容源,用户在 APP 内可选择不同来源站点浏览内容。
#### 📌 核心设计原则
> **原则 1:三层漏斗模型 —— 6000+ 是仓库规模,不是搜索规模**
>
> ```
> 源仓库 Repo(5 个预置入口)
> │ 用户按需导入
> ▼
> 源规则 Source(6000+ 条规则,按需存本地)
> │ 用户手动启用
> ▼
> 已启用源 Enabled Source(默认 6 个精选,用户自行扩展)
> ```
>
> - **第一层**:APP 内置 5 个源仓库 **入口 URL**(不内置规则本身)
> - **第二层**:用户从仓库导入规则后,规则存于本地(不自动启用)
> - **第三层**:用户手动勾选启用哪些源,**只有已启用的源参与搜索**
> - 默认策略:首次安装仅启用 **精选小说源 3 个 + 精选漫画源 3 个**
> **原则 2:纯实时流式读取,不下载到云端或本地**
>
> 所有第三方源的内容**仅做实时流式浏览**,不经过 Sakura Cloud 后端存储,也不写入手机本地持久化目录。
> - 图片/文本在 APP 内存中临时加载,离开页面即释放
> - 不使用 `CachedNetworkImage` 的持久缓存(可用内存缓存,退出 APP 清空)
> - **不触发任何下载行为**:不保存到系统图库、不写入本地文件、不同步到私有云
> **原则 3:跨源聚合搜索 + 安全限流**
>
> 用户输入一个关键词 → 并行查询**已启用的源**,结果按来源分组展示。
> - 搜索一次 = 并行请求**已启用的源**(默认 6 个,非 6000 个)
> - 最大并发 10 个源、单源超时 5 秒、失败静默跳过
> - 用户在"源管理"中可自行扩展启用的源数量
> - 结果按来源分组,同作品在不同源中按源分别列出
> **原则 4:APK 不支持 Pixiv 实时查看(⚠️ 重要)**
>
> Pixiv 的反爬虫机制导致其图片/小说内容**无法在移动端直接实时访问**:
> - Pixiv 图片服务器(`i.pximg.net`)有严格的 Referer 检查,APP 内直接加载会 403
> - 因此 **Pixiv 不接入第三方实时源**,Pixiv 内容仍走现有的"桌面端下载 → 同步到私有云 → APP 浏览"流程
> - 其他源(Legado 生态中的公开源)不受此限制
### 1.3 源站方案:基于 Legado(阅读)规则引擎 + 预置源仓库
与其为每个站点手写解析器(工作量大、维护成本高),更合理的方案是:**在 Flutter 中内置一个轻量级 Legado 规则引擎**,直接复用"阅读"生态已有的 6000+ 条书源规则。
#### 推荐的预置源仓库
| 源名称 | 地址 | 规模 | 用途 |
|--------|------|:--:|------|
| **全量综合源** | `https://legado.aoaostar.com/` | 6000+ | 小说 + 漫画 + 有声,首页一键导入 |
| **精简高速源** | `https://www.yckceo.com/yuedu/shuyuans/json/id/640.json` | ~2200 | 已校验去重,稳定可靠 |
| **漫画专享源** | `https://gcore.jsdelivr.net/gh/yuedu521/yiciyuan/1012.json` | 208 | 纯漫画源,聚焦漫画场景 |
| **订阅源(推荐)** | `https://www.yckceo.com/yuedu/rss/json/id/193.json` | 持续更新 | 自动推送最新源,一次配置永久省心 |
| **Venera 漫画源** | `https://git.nyne.dev/nyne/venera-configs/raw/branch/main/index.json` | 精选 | 漫画专用配置,持续维护 |
#### Legado 源格式简介
每个源是一个 JSON 对象,核心字段:
```json
{
"bookSourceName": "源名称",
"bookSourceUrl": "https://example.com",
"bookSourceType": 0,
"ruleSearch": {
"bookList": "...",
"name": "...",
"author": "...",
"coverUrl": "...",
"detailUrl": "..."
},
"ruleBookInfo": {
"name": "...",
"author": "...",
"coverUrl": "...",
"intro": "...",
"chapterList": "..."
},
"ruleContent": {
"content": "..."
},
"ruleToc": {
"chapterList": "...",
"chapterName": "...",
"chapterUrl": "..."
},
"httpUserAgent": "Mozilla/5.0 ...",
"header": "{\"Referer\": \"...\"}"
}
```
**规则类型说明:**
- `ruleSearch` — 搜索规则(URL 模板 + 结果列表 CSS/JSONPath 选择器)
- `ruleBookInfo` — 书籍详情规则(封面、简介、作者等字段提取)
- `ruleToc` — 章节目录规则(章节列表 + 名称 + URL 提取)
- `ruleContent` — 正文内容规则(正文提取 + 广告/乱码清洗)
- 支持 CSS 选择器、XPath、正则、JSONPath 四种规则语法
- 支持 JavaScript 预处理(高级源),但首版可先跳过
#### ❌ 明确排除的源
| 来源 | 排除原因 |
|------|----------|
| **Pixiv** (漫画+小说) | 图片服务器 `i.pximg.net` 有严格 Referer + Cookie 检查,APP 端直连 403;反爬机制频繁更新,绕过成本高。Pixiv 内容维持现有流程:桌面端下载 → 同步私有云 → APP 浏览 |
| **需要付费账号的源** | 首版先覆盖免费公开源 |
### 1.4 架构设计
```
┌──────────────────────────────────────────────────────────────────┐
│ Sakura Mobile (Flutter) │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 三层漏斗模型 ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ ① 源仓库 Repo ② 源规则 Source ③ 已启用源 │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │
│ │ │ 5 个预置入口 │ ──▶ │ 6000+ 条规则 │ ──▶ │ 6 个精选 │ │ │
│ │ │ (本地仅存URL) │ │ (用户按需导入)│ │ (默认启用) │ │ │
│ │ └──────────────┘ └──────────────┘ └────────────┘ │ │
│ │ 规模:5 规模:按需 规模:6~N(可控) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 搜索时:仅 ③ 已启用源 参与,最大并发 10,单源超时 5s │
│ │
├──────────────────────────────────────────────────────────────────┤
│ │
│ GalleryTab / NovelsTab / ExplorePage(统一搜索页) │
│ │ │
│ ├── 云库 Tab:现有流程(Pixiv 同步内容) │
│ │ │
│ └── 在线 Tab:纯实时流 │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ SourceManager │ ← 管理三层:仓库/规则/启用 │
│ │ - 预置仓库 URL │ │
│ │ - 导入/启用/禁用 │ │
│ │ - 默认精选源 6 个 │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ LegadoRuleEngine │ ← 规则引擎(纯 Dart) │
│ │ CSS / XPath / JSON │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ 搜索限流器:maxConcurrency=10, timeout=5s │ │
│ └────────────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 纯内存流式渲染 │ ← 不写磁盘、不入云库 │
│ │ (Memory Only) │ │
│ └──────────────────┘ │
│ │
│ ⚠️ Pixiv → 桌面端下载 → 同步云库 → APP 云库Tab 查看 │
└──────────────────────────────────────────────────────────────────┘
```
**搜索并发控制:**
| 参数 | 默认值 | 说明 |
|------|:------:|------|
| 最大并发源数 | 10 | 一次搜索最多同时请求 10 个源 |
| 单源超时 | 5s | 超时自动放弃,不阻塞其他源 |
| 失败策略 | 静默跳过 | 单个源失败不影响搜索整体结果 |
| 默认启用源 | 6 | 小说 3 个 + 漫画 3 个精选源 |
| 用户可扩展至 | N | 高级设置中手动启用更多,无硬上限但受并发限制 |
### 1.5 实现方案(Flutter 侧)
#### Step 1:Legado 规则引擎(核心)
在 `sakura_mobile/lib/src/legado/` 新建规则引擎:
```
sakura_mobile/lib/src/legado/
├── legado_engine.dart # 引擎入口:加载源 → 执行搜索/详情/目录/正文
├── rule_parser.dart # 规则解析器:解析 CSS/XPath/JSONPath/Regex 规则
├── source_loader.dart # 源加载器:从 URL/文件/内置 assets 加载源 JSON
├── http_client.dart # HTTP 封装:自动添加 UA/Referer/Cookie
├── source_manager.dart # 源管理器:增删改查 + 启用禁用 + 订阅更新
└── models/
├── legado_source.dart # Legado 源数据模型
└── search_result.dart # 统一搜索结果模型
```
**Legado 源数据模型:**
```dart
// sakura_mobile/lib/src/legado/models/legado_source.dart
class LegadoSource {
final String bookSourceName; // 源名称
final String bookSourceUrl; // 源站点 URL
final int bookSourceType; // 0=文本 1=音频 2=图片(漫画)
final String? bookSourceGroup; // 分组标签
final String? bookSourceComment;// 备注
// 搜索规则
final SearchRule? ruleSearch;
// 书籍详情规则
final BookInfoRule? ruleBookInfo;
// 章节目录规则
final TocRule? ruleToc;
// 正文内容规则
final ContentRule? ruleContent;
// HTTP 配置
final String? httpUserAgent;
final Map<String, String>? headers;
// 元数据
final String? sourceUrl; // 来源 URL(远程导入时记录)
final DateTime? lastUpdated;
final bool enabled; // 用户可禁用某个源
// ... fromJson / toJson
}
class SearchRule {
final String? url; // 搜索 URL 模板,{{key}} 替换为关键词
final String? method; // GET/POST
final String? body; // POST body
final String? bookList; // 结果列表选择器
final String? name; // 书名选择器
final String? author; // 作者选择器
final String? coverUrl; // 封面选择器
final String? detailUrl; // 详情页 URL 选择器
final String? kind; // 规则类型:css/xpath/json/regex
}
class BookInfoRule {
final String? name;
final String? author;
final String? coverUrl;
final String? intro; // 简介
final String? kind;
final String? chapterList; // 目录列表选择器(部分源目录在详情页)
final String? chapterName;
final String? chapterUrl;
}
class TocRule {
final String? chapterList;
final String? chapterName;
final String? chapterUrl;
final String? kind;
final String? nextTocUrl; // 分页目录的下一页
}
class ContentRule {
final String? content; // 正文提取规则
final String? kind;
final String? replaceRegex; // 正则清洗(去除广告等)
final String? webJs; // JavaScript 预处理(高级,可延后支持)
}
```
**规则引擎核心逻辑:**
```dart
// sakura_mobile/lib/src/legado/legado_engine.dart
class LegadoEngine {
final LegadoHttpClient _http;
LegadoEngine({LegadoHttpClient? http}) : _http = http ?? LegadoHttpClient();
/// 根据搜索规则,发起搜索请求并解析结果
Future<List<UnifiedSearchResult>> search(
LegadoSource source,
String keyword, {
int page = 1,
}) async {
final rule = source.ruleSearch;
if (rule == null) return [];
// 1. 构建搜索 URL(替换 {{key}} 占位符)
final url = rule.url!
.replaceAll('{{key}}', Uri.encodeComponent(keyword))
.replaceAll('{{page}}', page.toString());
// 2. 发起 HTTP 请求
final body = await _http.request(
url: url,
method: rule.method ?? 'GET',
headers: source.headers,
userAgent: source.httpUserAgent,
);
// 3. 根据规则类型解析 HTML/JSON
final parser = RuleParser(body, baseUrl: source.bookSourceUrl);
final bookList = parser.selectList(rule.bookList!, kind: rule.kind);
// 4. 对每条结果提取字段
return bookList.map((item) {
return UnifiedSearchResult(
sourceName: source.bookSourceName,
title: parser.select(item, rule.name!, kind: rule.kind),
author: parser.select(item, rule.author, kind: rule.kind),
coverUrl: parser.select(item, rule.coverUrl, kind: rule.kind),
detailUrl: parser.select(item, rule.detailUrl!, kind: rule.kind),
);
}).toList();
}
/// 获取书籍详情(元信息 + 章节目录)
Future<BookDetail> getDetail(LegadoSource source, String detailUrl) async { ... }
/// 获取章节正文(提取 + 清洗)
Future<String> getContent(LegadoSource source, String chapterUrl) async { ... }
}
```
**规则解析器(RuleParser)—— 支持四种语法:**
```dart
// sakura_mobile/lib/src/legado/rule_parser.dart
// 利用现有 pub.dev 包实现(无需从零造轮子)
import 'package:html/dom.dart' as html_dom;
import 'package:html/parser.dart' as html_parser;
import 'package:xpath_parser/xpath_parser.dart';
import 'package:json_path/json_path.dart';
class RuleParser {
final String _body;
final String _baseUrl;
html_dom.Document? _doc;
dynamic _json; // lazy parse
RuleParser(this._body, {required String baseUrl}) : _baseUrl = baseUrl;
/// 选择单个文本
String select(String node, String? rule, {String? kind}) {
if (rule == null || rule.isEmpty) return '';
final parsed = _parseRule(rule);
switch (kind ?? parsed.type) {
case 'css':
return _cssSelectOne(node, parsed.expression);
case 'xpath':
return _xpathSelectOne(node, parsed.expression);
case 'json':
return _jsonPathSelectOne(node, parsed.expression);
case 'regex':
return _regexExtract(node, parsed.expression);
default:
return _cssSelectOne(node, rule);
}
}
/// 选择列表
List<String> selectList(String node, String? rule, {String? kind}) { ... }
// 内部实现,利用成熟的 pub 包…
String _cssSelectOne(String html, String selector) { ... }
String _xpathSelectOne(String html, String xpath) { ... }
String _jsonPathSelectOne(String json, String path) { ... }
}
```
> **依赖包:** `html`(HTML DOM 解析)、`json_path`(JSONPath)、已有 pub 上有成熟的 CSS 选择器和 XPath 包可用。这些包都是纯 Dart 实现,不依赖原生平台代码,可直接在 Flutter 中使用。
#### Step 2:源管理器 —— 三层漏斗 + 默认精选
```dart
// sakura_mobile/lib/src/legado/source_manager.dart
/// ┌─────────────────────────────────────────────────────┐
/// │ 三层漏斗模型 │
/// │ │
/// │ ① 源仓库 Repo ② 源规则 Source ③ 已启用源 │
/// │ 规模: 5 个预置 规模: 按需导入 规模: 6~N │
/// │ 仅存 URL 用户手动启用 参与搜索 │
/// └─────────────────────────────────────────────────────┘
class SourceManager {
// ============================================
// ① 源仓库层:5 个预置入口(仅存 URL,不含规则)
// ============================================
static const builtinSourceRepos = [
SourceRepo(
name: '全量综合源',
url: 'https://legado.aoaostar.com/',
description: '6000+ 站点,含小说、漫画、有声',
category: '综合',
),
SourceRepo(
name: '精简高速源',
url: 'https://www.yckceo.com/yuedu/shuyuans/json/id/640.json',
description: '约 2200 条,已校验去重,稳定可靠',
category: '综合',
),
SourceRepo(
name: '漫画专享源',
url: 'https://gcore.jsdelivr.net/gh/yuedu521/yiciyuan/1012.json',
description: '208 条漫画专用源',
category: '漫画',
),
SourceRepo(
name: '订阅源(推荐)',
url: 'https://www.yckceo.com/yuedu/rss/json/id/193.json',
description: '自动推送最新源,一次配置永久省心',
category: '订阅',
isSubscription: true,
),
SourceRepo(
name: 'Venera 漫画源',
url: 'https://git.nyne.dev/nyne/venera-configs/raw/branch/main/index.json',
description: '精选漫画配置,持续维护',
category: '漫画',
),
];
// ============================================
// ② 源规则层:所有已导入的规则(导入 ≠ 启用)
// ============================================
final List<LegadoSource> _importedSources = [];
// ============================================
// ③ 已启用源:默认仅 6 个精选源
// ============================================
/// 首次安装默认启用的精选源名称列表
static const defaultEnabledNovelSources = [
'全本玄幻小说', // 小说
'笔趣阁', // 小说
'妙笔阁', // 小说
];
static const defaultEnabledMangaSources = [
'包子漫画', // 漫画
'古风漫画网', // 漫画
'COCO漫画', // 漫画
];
/// 首次启动时自动执行:导入精选源 + 启用
Future<void> initializeIfFirstRun() async {
final prefs = await SharedPreferences.getInstance();
if (prefs.getBool('source_manager_initialized') == true) return;
// 从精简高速源仓库导入规则(2200 条)
await importFromRepo(builtinSourceRepos[1]); // 精简高速源
// 仅启用 6 个精选源
final allNovelNames = defaultEnabledNovelSources.toSet();
final allMangaNames = defaultEnabledMangaSources.toSet();
for (final source in _importedSources) {
if (allNovelNames.contains(source.bookSourceName) ||
allMangaNames.contains(source.bookSourceName)) {
_enabledSourceNames.add(source.bookSourceName);
}
}
await prefs.setBool('source_manager_initialized', true);
}
/// 获取参与搜索的源(仅 ③ 已启用源)
List<LegadoSource> get enabledSources =>
_importedSources.where((s) => _enabledSourceNames.contains(s.bookSourceName)).toList();
/// 从仓库导入规则(导入 ≠ 启用,用户需手动勾选)
Future<int> importFromRepo(SourceRepo repo) async { ... }
/// 从 URL 导入用户自定义源
Future<int> importFromUrl(String url) async { ... }
/// 从本地 JSON 文件导入
Future<int> importFromFile(String filePath) async { ... }
/// 手动启用/禁用某个源
Future<void> setEnabled(String sourceName, bool enabled) async { ... }
}
```
**首次安装体验流程:**
```
用户首次打开 APP
│
├─→ 自动从"精简高速源"仓库导入约 2200 条规则到本地
│
├─→ 自动启用 6 个精选源(小说 3 + 漫画 3)
│
├─→ 用户在探索页搜索 → 仅这 6 个源参与
│
└─→ 用户进入"源管理" → 可看到 5 个仓库入口
├─→ 点击"全量综合源" → 导入 6000+ 条到本地
├─→ 逐一手动勾选启用 → 启用源扩展到 N 个
└─→ 搜索时最多并发 10 个
```
**搜索限流器:**
```dart
// sakura_mobile/lib/src/legado/legado_engine.dart
class LegadoEngine {
static const maxConcurrency = 10; // 最多同时请求 10 个源
static const perSourceTimeout = Duration(seconds: 5); // 单源超时
/// 搜索入口:自动限制并发 + 超时
Future<List<UnifiedSearchResult>> searchAll(
List<LegadoSource> enabledSources,
String keyword,
) async {
// 只取前 N 个(如果用户启用了 >10 个源)
final batch = enabledSources.take(maxConcurrency).toList();
final results = <UnifiedSearchResult>[];
// 并行搜索,单源失败不影响其余
final responses = await Future.wait(
batch.map((source) =>
search(source, keyword)
.timeout(perSourceTimeout)
.catchError((_) => <UnifiedSearchResult>[]) // 静默跳过失败源
),
);
for (final list in responses) {
results.addAll(list);
}
return results;
}
}
```
```
#### Step 3:UI 层 —— 源管理页面(展示三层漏斗)
新建 `sakura_mobile/lib/src/pages/source_manager_page.dart`:
```
┌──────────────────────────────────────────────┐
│ ← 源管理 [+ 自定义导入] │
├──────────────────────────────────────────────┤
│ │
│ 📊 统计:已导入 2200 条 | 已启用 6 个 │
│ │
│ ── ① 源仓库(5 个预置入口) ────────────── │
│ ┌──────────────────────────────────────────┐│
│ │ 📚 全量综合源 [导入 6000+ 条] ││
│ │ legado.aoaostar.com 未导入 ││
│ ├──────────────────────────────────────────┤│
│ │ 🚀 精简高速源 [已导入 2200 条] ││
│ │ yckceo.com ✓ 已导入 ││
│ ├──────────────────────────────────────────┤│
│ │ 🎨 漫画专享源 [导入 208 条] ││
│ │ 208 条漫画专用 未导入 ││
│ ├──────────────────────────────────────────┤│
│ │ 📡 订阅源(推荐) [订阅] ││
│ │ 自动推送最新源 未订阅 ││
│ ├──────────────────────────────────────────┤│
│ │ 🎌 Venera 漫画源 [导入] ││
│ │ 精选漫画配置 未导入 ││
│ └──────────────────────────────────────────┘│
│ │
│ ── ② 源规则(已导入 2200 条)──────────── │
│ ┌──────────────────────────────────────────┐│
│ │ 🔍 搜索已导入的源... ││
│ │ [✓ 已启用] [ ] 小说源 [ ] 漫画源 ││
│ ├──────────────────────────────────────────┤│
│ │ [✓] 全本玄幻小说 📖 小说 [禁用] ││
│ │ [✓] 笔趣阁 📖 小说 [禁用] ││
│ │ [✓] 妙笔阁 📖 小说 [禁用] ││
│ │ [✓] 包子漫画 🎨 漫画 [禁用] ││
│ │ [✓] 古风漫画网 🎨 漫画 [禁用] ││
│ │ [✓] COCO漫画 🎨 漫画 [禁用] ││
│ │ ── 以下未启用 ───────────────────────── ││
│ │ [ ] 笔趣阁2 📖 小说 [启用] ││
│ │ [ ] 顶点小说 📖 小说 [启用] ││
│ │ [ ] ... 共 2194 条未启用 ││
│ └──────────────────────────────────────────┘│
│ │
│ ── ③ 搜索配置 ────────────────────────── │
│ ┌──────────────────────────────────────────┐│
│ │ 最大并发源数: [■■■■■■■■■□] 10 ││
│ │ 单源超时时间: [■■■■■□□□□□] 5 秒 ││
│ │ 已启用源总数: 6 个(参与搜索) ││
│ │ ││
│ │ ⚠️ 启用源越多,搜索越慢。建议保持 ≤20 个 ││
│ └──────────────────────────────────────────┘│
│ │
│ 🔗 高级:自定义导入 │
│ ┌──────────────────────────────────────────┐│
│ │ [https://... ] [从URL导入] ││
│ │ [选择本地JSON文件] [从文件导入] ││
│ └──────────────────────────────────────────┘│
└──────────────────────────────────────────────┘
```
#### Step 4:跨源搜索入口
在 GalleryTab / NovelsTab / ExplorePage 中调用:
```dart
// 用户点击搜索后
final manager = ref.read(sourceManagerProvider);
final engine = ref.read(legadoEngineProvider);
final enabledSources = manager.enabledSources;
// 并行搜索所有已启用的源 + 云库
final results = await Future.wait([
// 云库搜索
api.gallery(search: query, ...),
// 所有第三方源并行搜索
...enabledSources.map((source) =>
engine.search(source, query).catchError((_) => <UnifiedSearchResult>[])
),
]);
```
---
## 二、APK 端:未保存内容的在线搜索与实时浏览
### 2.1 现状分析
当前移动端的搜索功能仅限于**已同步到云端的内容**:
- `GalleryTab._load()` 调用 `api.gallery(search: ...)` → 仅查询 Sakura Cloud 数据库中已有的 Artwork
- `NovelsTab._load()` 调用 `api.novels(search: ...)` → 仅查询 Sakura Cloud 数据库中已有的 Novel
- **用户无法搜索尚未保存/同步到私有云的外部作品**
### 2.2 目标
- 用户输入一个关键词 → **自动并行搜索所有第三方源 + 云库**,结果聚合展示
- 搜索结果即时展示封面、标题、作者、来源等元信息
- 点击后**纯内存流式浏览**,不下载到本地,不同步到云库
- **Pixiv 不参与实时搜索/浏览**,Pixiv 内容仍走桌面端同步流程
### 2.3 跨源聚合搜索设计
```
用户输入 "鬼灭之刃"
│
▼
┌──────────────────────────────────────────────────────┐
│ CrossSourceSearch.aggregate() │
│ │
│ 仅搜索 ③ 已启用源(默认 6 个,非 6000 个) │
│ 并发限制 max=10, 单源超时 5s, 失败静默跳过 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 我的云库 │ │ 包子漫画 │ │ 古风漫画 │ ... │
│ │ (已有) │ │ (启用) │ │ (启用) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AggregatedResults (按源分组) │ │
│ │ │ │
│ │ 📦 我的云库 (3条) ← Pixiv 同步内容 │ │
│ │ 📦 包子漫画 (5条) ← Legado 规则引擎 │ │
│ │ 📦 古风漫画网 (2条) │ │
│ │ 📦 全本玄幻小说 (8条) │ │
│ │ ...(共 6 个已启用源的结果) │ │
│ │ │ │
│ │ 💡 未找到?去 源管理 导入更多仓库并启用新源 │ │
│ │ ❌ Pixiv — 不参与实时搜索 │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```
### 2.4 实现方案
#### Step 1:搜索 —— 跨源聚合搜索引擎
```dart
// sakura_mobile/lib/src/core/unified_search.dart (新增)
class UnifiedSearch {
final SakuraApiClient _cloudApi;
final SourceManager _sourceManager;
UnifiedSearch(this._cloudApi, this._sourceManager);
/// 统一漫画搜索:同步搜索云库 + 所有第三方源
Future<UnifiedSearchResults> searchManga(
String query, {
int page = 1,
Set<String>? enabledSources, // 用户选择启用的源
}) async {
final results = UnifiedSearchResults(
query: query,
sections: [],
);
// 1. 搜索私有云库(最快)
final cloudItems = await _cloudApi.gallery(
search: query,
page: page,
limit: 20,
contentType: 'manga',
);
if (cloudItems.isNotEmpty) {
results.sections.add(SearchSection(
sourceId: 'cloud',
sourceName: '我的云库',
items: _toCloudArtworks(cloudItems),
));
}
// 2. 搜索第三方源
final targetSources = _sourceManager.mangaSources
.where((s) => enabledSources == null || enabledSources.contains(s.sourceId));
final sourceResults = await Future.wait(
targetSources.map((source) =>
source.search(query, page: page, limit: 20)
.then((items) => SearchSection(
sourceId: source.sourceId,
sourceName: source.sourceName,
items: items,
))
.catchError((_) => null) // 单个源失败不影响其他
),
);
results.sections.addAll(sourceResults.whereType<SearchSection>());
return results;
}
}
/// 搜索结果容器
class UnifiedSearchResults {
final String query;
final List<SearchSection> sections;
// 所有 items 可展平为列表
const UnifiedSearchResults({required this.query, required this.sections});
}
/// 按来源分组的搜索结果
class SearchSection {
final String sourceId;
final String sourceName;
final List<dynamic> items; // MangaSearchResult | Artwork
const SearchSection({
required this.sourceId,
required this.sourceName,
required this.items,
});
}
```
#### Step 2:实时浏览 —— 在线漫画阅读器(纯内存、零下载)
新建 `sakura_mobile/lib/src/pages/online_manga_reader_page.dart`:
> ⚠️ **关键约束:** 图片仅通过 `Image.network()` 或 `Image.memory()` 在内存中渲染,**不使用 `CachedNetworkImage` 的持久缓存**,不调用 `downloadProtectedFile()`,不写入任何本地文件。
```dart
// sakura_mobile/lib/src/pages/online_manga_reader_page.dart (新增)
import 'package:flutter/material.dart';
import '../core/source_interface.dart';
/// 在线漫画阅读器 —— 纯实时流式浏览
/// - 图片在内存中临时加载,离开页面即释放
/// - 不保存到系统图库、不写入本地文件、不同步到私有云
class OnlineMangaReaderPage extends StatefulWidget {
final MangaSource source;
final String mangaId;
final String chapterId;
final String title;
const OnlineMangaReaderPage({
super.key,
required this.source,
required this.mangaId,
required this.chapterId,
required this.title,
});
@override
State<OnlineMangaReaderPage> createState() => _OnlineMangaReaderPageState();
}
class _OnlineMangaReaderPageState extends State<OnlineMangaReaderPage> {
late Future<List<MangaPage>> _pagesFuture;
final _pageController = PageController();
int _currentPage = 0;
int _totalPages = 0;
@override
void initState() {
super.initState();
_pagesFuture = widget.source.getChapterPages(
widget.mangaId,
widget.chapterId,
);
}
@override
void dispose() {
_pageController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
actions: [
if (_totalPages > 0)
Center(
child: Padding(
padding: const EdgeInsets.only(right: 8),
child: Text(
'${_currentPage + 1} / $_totalPages',
style: const TextStyle(fontSize: 14),
),
),
),
],
),
body: FutureBuilder<List<MangaPage>>(
future: _pagesFuture,
builder: (context, snapshot) {
if (snapshot.hasError) {
return Center(child: Text('加载失败: ${snapshot.error}'));
}
if (!snapshot.hasData) {
return const Center(child: CircularProgressIndicator());
}
final pages = snapshot.data!;
_totalPages = pages.length;
return PageView.builder(
controller: _pageController,
scrollDirection: Axis.horizontal,
itemCount: pages.length,
onPageChanged: (page) => setState(() => _currentPage = page),
itemBuilder: (context, index) {
final page = pages[index];
return InteractiveViewer(
child: Center(
// ✅ 使用 Image.network(内存缓存),不用 CachedNetworkImage(磁盘缓存)
child: Image.network(
page.imageUrl,
headers: page.headers,
fit: BoxFit.contain,
loadingBuilder: (_, child, progress) {
if (progress == null) return child;
return const Center(child: CircularProgressIndicator());
},
errorBuilder: (_, __, ___) =>
const Center(child: Icon(Icons.broken_image, size: 48)),
),
),
);
},
);
},
),
);
}
}
```
#### Step 3:在线小说阅读器
新建 `sakura_mobile/lib/src/pages/online_novel_reader_page.dart`:
```dart
// 类似 OnlineMangaReaderPage,但渲染纯文本
// 从第三方源获取章节正文后,滚动显示文本内容
// 支持翻页、字体调整、夜间模式等
```
#### Step 4:搜索页 UI 整合
新建 `sakura_mobile/lib/src/pages/explore_page.dart` —— 探索/发现页:
```
┌──────────────────────────────────────┐
│ [🔍 搜索漫画或小说...] │ ← 搜索栏
├──────────────────────────────────────┤
│ 来源:[我的云库] [MangaDex] [漫画柜] │ ← 横向滚动来源选择
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 封面 │ │ 封面 │ │ 封面 │ │
│ │ │ │ │ │ │ │ ← 瀑布流搜索结果
│ │ 标题 │ │ 标题 │ │ 标题 │ │
│ │ 来源 │ │ 来源 │ │ 来源 │ │
│ └────────┘ └────────┘ └────────┘ │
├──────────────────────────────────────┤
│ 点击 → 直接进入在线阅读(不保存) │
│ 长按 → 保存到我的云库 │
└──────────────────────────────────────┘
```
### 2.5 数据流总结
```
用户搜索 "关键词"
│
├─→ Sakura Cloud /gallery?search=xxx (已有云库内容)
│
├─→ MangaDexSource.search("xxx") (第三方漫画源)
├─→ CopymangaSource.search("xxx") (第三方漫画源)
├─→ NarouSource.search("xxx") (第三方小说源)
│
│ ❌ Pixiv — 不参与实时搜索
│ → UI 上显示提示:"Pixiv 内容请通过桌面端同步后查看"
│
▼
CrossSourceSearch.aggregate()
→ 并行请求,按源分组,合并返回
│
▼
统一 AggregatedResults
│
▼
用户点击某条结果
│
├─→ 云库内容 → 现有 ArtworkDetailPage / NovelReaderPage
│ (可收藏、可下载、可同步进度)
│
└─→ 第三方源内容 → OnlineMangaReaderPage / OnlineNovelReaderPage
│
├─→ Image.network() 逐页渲染(内存缓存,离开释放)
├─→ 文本流式加载到 Text widget(内存,离开释放)
│
├─→ ❌ 不调用 downloadProtectedFile()
├─→ ❌ 不写 SharedPreferences/本地文件
├─→ ❌ 不触发系统图库保存
└─→ ❌ 不同步到 Sakura Cloud
```
---
## 三、WEB 端:认证失败与登录页缺失修复
### 3.1 问题现象
部署新版 Sakura Admin Web 后,访问页面始终返回:
```json
{"detail": "Not authenticated"}
```
**没有出现登录页面**,直接报错,无法正常使用。
### 3.2 根因分析
经过对全部相关代码的排查,问题涉及以下多个层面:
#### 根因 1:CSP(内容安全策略)过于严格 —— **核心问题**
**文件位置:** `sakura_cloud/api/middleware.py` 第 37-41 行
```python
response.headers.setdefault(
"Content-Security-Policy",
"default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'",
)
```
**问题:**
- `connect-src 'self'` 限制了所有 API 请求只能发送到同源
- 当开发环境前端运行在 `localhost:5174`,后端运行在 `localhost:8000` 时,前端通过 Vite proxy 代理 API 请求到后端,但浏览器会因为 CSP 限制而阻止跨域 API 调用
- `img-src 'self' data:` 限制了图片资源只能从同源加载,外部图片无法显示
- 生产部署时,如果前端构建为静态文件通过 Nginx 部署,API 请求不同端口也会被 CSP 拦截
#### 根因 2:SPA 路由未正确回退
**文件位置:** `sakura_cloud/main.py` 第 61-78 行
```python
@app.get("/admin", response_class=HTMLResponse)
def admin_console() -> str:
if not settings.admin_frontend_enabled:
return "<h1>Admin console disabled</h1>"
return """<!doctype html>...""" # 硬编码的占位 HTML,不是真正的 SPA
```
**问题:**
- 后端只注册了 `/admin` 这一个路由返回 HTML
- Vue Router 使用了 `createWebHistory()`(`sakura_admin_web/src/router/index.ts` 第 60 行),意味着 URL 如 `/login`、`/app`、`/admin/users` 等都是真实路径
- 当用户直接访问 `/login` 或刷新 `/app/dashboard` 时,后端没有对应路由,返回 404 或触发认证检查
- SPA 需要所有非 API 路径回退到 `index.html`
#### 根因 3:前端 API 路径与后端不一致
**文件位置:** `sakura_admin_web/src/stores/auth.ts` 第 7-8 行
```typescript
const path = admin ? "/admin/login" : "/auth/login";
const response = await http.post(path, { ... });
```
**文件位置:** `sakura_admin_web/src/api/http.ts` 第 4 行
```typescript
const API_BASE = import.meta.env.VITE_API_BASE_URL || "/api/v1";
```
实际 API 路径:
- 用户登录:`POST /api/v1/auth/login`
- 管理员登录:`POST /api/v1/admin/login`
- 获取当前用户:`GET /api/v1/me`
**问题:** 前端 `http.ts` 的 `API_BASE` 默认是 `/api/v1`,而 Vite 的 proxy 配置是将 `/api` 代理到后端。这意味着前端的 `/api/v1/auth/login` 实际被代理为 `http://127.0.0.1:8000/api/v1/auth/login` —— 虽然这个路径是正确的,但当**不通过 Vite dev server 访问**(即生产部署)时,如果静态文件服务器没有正确配置代理,API 调用会失败。
#### 根因 4:前端路由守卫在 token 不存在时无限循环
**文件位置:** `sakura_admin_web/src/router/index.ts` 第 64-70 行
```typescript
router.beforeEach(async (to) => {
if (!to.meta.requiresAuth) return true;
const user = await loadMe().catch(() => null);
if (!user) return { path: "/login", query: { redirect: to.fullPath } };
if (to.meta.requiresAdmin && !isAdmin(authState.user?.role)) return "/403";
return true;
});
```
**问题:**
- `loadMe()` 调用 `GET /api/v1/me`,需要 Bearer token
- 如果 token 不存在或已过期,API 返回 401,前端捕获错误后 `user` 为 null,重定向到 `/login`
- 但如果后端中间件在所有路由(包括 `/login` 对应的 API 调用)都要求认证,用户永远看不到登录页
- `auth.ts` 中的 `login()` 在管理员登录时调用 `/admin/login`,但后端 `admin_login` 端点有 IP 速率限制(`admin_login_rate_limit_per_minute: 5`),开发时频繁刷新容易触发
#### 根因 5:缺少生产部署的静态文件服务配置
**文件位置:** `sakura_cloud/main.py` —— 没有挂载静态文件
后端没有配置 `app.mount()` 来服务前端构建产物。生产环境需要:
- 后端直接 serving SPA 静态文件(FastAPI `StaticFiles`)
- 或者 Nginx 反向代理 + 静态文件服务
### 3.3 解决方案
#### 方案 A:修复 CSP 中间件(立即执行)
修改 `sakura_cloud/api/middleware.py`:
```python
# sakura_cloud/api/middleware.py 修改后的 security_headers_middleware
async def security_headers_middleware(request: Request, call_next: Callable) -> Response:
response = await call_next(request)
response.headers.setdefault("X-Content-Type-Options", "nosniff")
response.headers.setdefault("X-Frame-Options", "DENY")
response.headers.setdefault("Referrer-Policy", "no-referrer")
response.headers.setdefault("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=()")
# ===== 修复后的 CSP =====
# 开发环境 localhost:5174 / 生产环境根据 CORS 配置
api_origin = request.headers.get("origin", "")
allowed_connect = "'self'"
# 如果 CORS origins 中包含此 origin,允许 connect
cors_origins_str = ", ".join(settings.cors_origins) if settings.cors_origins else ""
csp = (
"default-src 'self'; "
"img-src 'self' data: https: http:; " # 允许外部图片
"style-src 'self' 'unsafe-inline'; "
"script-src 'self' 'unsafe-inline'; "
"connect-src 'self' http://localhost:* ws://localhost:*; " # 允许开发环境 API + WebSocket
"font-src 'self' data:; "
)
if settings.debug:
# 开发模式放宽 CSP
csp = csp.replace("connect-src 'self'", "connect-src *")
response.headers.setdefault("Content-Security-Policy", csp)
return response
```
#### 方案 B:后端添加 SPA 回退路由
修改 `sakura_cloud/main.py`,将硬编码的占位 HTML 替换为真正的 SPA 静态文件服务:
```python
# sakura_cloud/main.py 修改
import os
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, FileResponse
from fastapi.staticfiles import StaticFiles
def create_app() -> FastAPI:
# ... 现有配置 ...
# === 新增:服务前端 SPA 静态文件 ===
frontend_dist = os.path.join(os.path.dirname(__file__), "..", "sakura_admin_web", "dist")
frontend_dist = os.path.abspath(frontend_dist)
if os.path.isdir(frontend_dist):
# 挂载静态资源(JS, CSS, 图片等)
assets_dir = os.path.join(frontend_dist, "assets")
if os.path.isdir(assets_dir):
app.mount("/assets", StaticFiles(directory=assets_dir), name="admin_assets")
# SPA 回退路由:所有非 API 路径返回 index.html
@app.get("/admin/{full_path:path}")
async def spa_fallback(full_path: str = ""):
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built. Run: cd sakura_admin_web && npm run build</h1>")
@app.get("/admin")
async def admin_root():
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
# 为 Vue Router 的 history mode 添加额外回退路由
@app.get("/login")
@app.get("/register")
@app.get("/forgot-password")
async def public_spa_fallback(request: Request):
"""公开页面回退(不需要认证)"""
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
@app.get("/app/{full_path:path}")
@app.get("/app")
async def app_spa_fallback():
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
# ... 其余配置 ...
return app
```
#### 方案 C:Nginx 生产部署配置(推荐方案)
创建 `sakura_admin_web/nginx.conf`:
```nginx
server {
listen 80;
server_name admin.your-domain.com;
# 前端静态文件
root /path/to/sakura_admin_web/dist;
index index.html;
# API 反向代理到后端
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;
}
# SPA History Mode 回退
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
```
#### 方案 D:修复前端路由守卫的正向逻辑
修改 `sakura_admin_web/src/router/index.ts`,确保 `/login` 页面不需要认证检查:
```typescript
// sakura_admin_web/src/router/index.ts 路由守卫修改
const PUBLIC_PATHS = ['/login', '/register', '/forgot-password', '/403', '/404'];
router.beforeEach(async (to) => {
// 公开路径直接放行,不做任何 API 调用
if (PUBLIC_PATHS.includes(to.path) || to.path === '/') {
return true;
}
if (!to.meta.requiresAuth) return true;
// 只有受保护路径才检查 token
const user = await loadMe().catch(() => null);
if (!user) {
// 带上 redirect 参数,登录后可跳回
return { path: "/login", query: { redirect: to.fullPath } };
}
if (to.meta.requiresAdmin && !isAdmin(authState.user?.role)) {
return "/403";
}
return true;
});
```
#### 方案 E:前端环境变量与构建配置
修改 `sakura_admin_web/.env.production`(新建):
```bash
# sakura_admin_web/.env.production
VITE_API_BASE_URL=/api/v1
```
修改 `sakura_admin_web/vite.config.ts`,添加生产构建选项:
```typescript
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
export default defineConfig(({ mode }) => ({
plugins: [vue()],
server: {
port: 5174,
proxy: {
"/api": {
target: "http://127.0.0.1:8000",
changeOrigin: true
}
}
},
build: {
outDir: "dist",
assetsDir: "assets",
// 确保 Vite 构建的 base 路径正确
base: "/",
}
}));
```
### 3.4 修复后的访问流程
```
用户访问 http://admin.your-domain.com/login
│
▼
Nginx / FastAPI 返回 index.html(SPA 入口)
│
▼
Vue.js 加载,Vue Router 匹配到 /login → 渲染 LoginPage.vue
│
▼
用户输入账号密码,点击登录
│
▼
前端调用 POST /api/v1/auth/login
│
▼
Nginx 代理 → http://127.0.0.1:8000/api/v1/auth/login
│
▼
后端验证通过,返回 access_token + refresh_token
│
▼
前端保存 token 到 sessionStorage,调用 GET /api/v1/me
│
▼
路由守卫校验通过 → 跳转到 /app 或 /admin
```
### 3.5 快速验证清单
| 检查项 | 命令/方法 | 期望结果 |
|--------|-----------|----------|
| CSP 是否正确 | 浏览器 DevTools → Console | 无 CSP 错误 |
| API 代理是否正常 | `curl -X POST http://localhost:8000/api/v1/auth/login -H "Content-Type: application/json" -d '{"username_or_email":"test","password":"test"}'` | 返回 JSON(即使 401) |
| SPA 回退是否正常 | 浏览器访问 `http://localhost:8000/login` | 显示登录页 HTML,非 404 |
| 静态资源是否加载 | 浏览器 DevTools → Network | `.js`/`.css` 文件返回 200 |
| 登录流程是否打通 | 在登录页输入正确凭据 | 成功跳转到 Dashboard |
---
## 四、APK 端 UI 美化:配色统一、标题优化与选项卡样式修复
### 4.1 问题概述
根据用户反馈,当前 APK 端存在三个 UI 问题:
| # | 问题 | 现状 | 期望 |
|---|------|------|------|
| 1 | 登录页配色不和谐 | 使用蓝色系(`#3A7BFF`) | 改为粉色系,与 App 主题统一 |
| 2 | 选项卡选中样式错误 | 选中态填充整个方块区域 | 选中态只指示文字(下划线或紧凑 pill) |
| 3 | 各页面标题位置太低 | `SliverAppBar.large` 占用过多空间 | 压缩标题区域,内容更早上屏 |
### 4.2 问题一:登录页蓝色 → 粉色(统一品牌色)
#### 4.2.1 现状分析
**文件位置:** `sakura_mobile/lib/src/pages/login_page.dart`
App 全局主题色定义在 `app.dart` 第 12-16 行:
```dart
final colorScheme = ColorScheme.fromSeed(
seedColor: const Color(0xFFE98AA6),
primary: const Color(0xFFD95A83), // 主色:玫瑰粉
secondary: const Color(0xFFF3A6B8), // 辅色:浅粉
surface: const Color(0xFFFFFBFD), // 表面色:暖白
);
```
但登录页完全硬编码了蓝色系,完全绕过了主题系统:
| 元素 | 当前值(蓝色) | 所在行 |
|------|---------------|--------|
| 页面背景渐变 | `#F4F8FF → #E6EEFF` | 第 62-66 行 |
| 图标容器背景 | `#3A7BFF` 12% 透明度 | 第 95 行 |
| 图标颜色 | `#3A7BFF` | 第 98 行 |
| TabBar 背景 | `#F1F5FD` | 第 117 行 |
| TabBar 选中指示器 | `#3A7BFF` | 第 122 行 |
| 未选中文字色 | `#5A6D80` | 第 126 行 |
#### 4.2.2 修改方案
将登录页所有硬编码蓝色替换为主题粉色系:
```dart
// sakura_mobile/lib/src/pages/login_page.dart 修改后的 build 方法
@override
Widget build(BuildContext context) {
final session = ref.watch(sessionProvider);
final bannerText = session.error ?? _message;
final bannerIsError = session.error != null || _messageIsError;
final theme = Theme.of(context);
final primaryColor = theme.colorScheme.primary; // Color(0xFFD95A83)
return Scaffold(
body: DecoratedBox(
// ✅ 修改 1:背景渐变从蓝色改为粉色系
decoration: const BoxDecoration(
gradient: LinearGradient(
begin: Alignment.topCenter,
end: Alignment.bottomCenter,
colors: [Color(0xFFFFF5F8), Color(0xFFFFE8EE)], // 粉色渐变
),
),
child: SafeArea(
child: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 520),
child: ListView(
padding: const EdgeInsets.fromLTRB(20, 24, 20, 28),
children: [
Container(
padding: const EdgeInsets.fromLTRB(22, 24, 22, 24),
decoration: BoxDecoration(
color: Colors.white.withValues(alpha: 0.96),
borderRadius: BorderRadius.circular(30),
boxShadow: const [
BoxShadow(
color: Color(0x18D95A83), // ✅ 阴影改为粉色基调
blurRadius: 28,
offset: Offset(0, 12),
),
],
),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// ✅ 修改 2:图标容器颜色从蓝色改为粉色
Container(
width: 58,
height: 58,
decoration: BoxDecoration(
color: primaryColor.withValues(alpha: 0.12),
borderRadius: BorderRadius.circular(18),
),
child: Icon(Icons.cloud_done_outlined,
color: primaryColor, size: 30), // 使用主题色
),
const SizedBox(height: 18),
Text(
'樱云同步',
style: theme.textTheme.headlineMedium
?.copyWith(fontWeight: FontWeight.w800),
),
const SizedBox(height: 10),
Text(
'一个账号管理你的收藏、阅读进度和移动端浏览体验。',
style: theme.textTheme.bodyLarge?.copyWith(
color: const Color(0xFF8A6A74), // ✅ 辅助文字改为暖灰
height: 1.55,
),
),
const SizedBox(height: 20),
// ✅ 修改 3:TabBar — 背景和指示器改为粉色
// (详见问题二的完整重构)
_buildTabBar(theme),
// ... 其余内容不变
],
),
),
],
),
),
),
),
),
);
}
```
**完整颜色映射表:**
| 元素 | 旧值(蓝色) | 新值(粉色) |
|------|------------|------------|
| 页面渐变起点 | `#F4F8FF` | `#FFF5F8`(与 `scaffoldBackgroundColor` 一致) |
| 页面渐变终点 | `#E6EEFF` | `#FFE8EE`(浅樱色) |
| 卡片阴影 | `#160F2740` | `#18D95A83`(粉色阴影) |
| 图标背景 | `#3A7BFF` @12% | `ColorScheme.primary` @12% |
| 图标颜色 | `#3A7BFF` | `ColorScheme.primary` |
| 描述文字 | `#607287`(冷灰) | `#8A6A74`(暖灰,与底部导航栏一致) |
| TabBar 背景 | `#F1F5FD` | `#FFEFF5`(浅粉底) |
| TabBar 指示器 | `#3A7BFF` | `ColorScheme.primary` |
| 未选中文字 | `#5A6D80` | `#8A6A74` |
### 4.3 问题二:选项卡选中样式 —— 从「板块选择」改为「文字下划线」
#### 4.3.1 现状分析
**文件位置:** `sakura_mobile/lib/src/pages/login_page.dart` 第 114-133 行
```dart
Container(
decoration: BoxDecoration(
color: const Color(0xFFF1F5FD), // 整个容器有背景色
borderRadius: BorderRadius.circular(18),
),
child: TabBar(
controller: _tabController,
indicator: BoxDecoration( // ← 问题核心:BoxDecoration 填充整个 tab
color: const Color(0xFF3A7BFF), // 看起来像两个按钮,而不是选项卡
borderRadius: BorderRadius.circular(14),
),
labelColor: Colors.white,
unselectedLabelColor: const Color(0xFF5A6D80),
dividerColor: Colors.transparent,
tabs: const [
Tab(text: '登录'),
Tab(text: '注册'),
],
),
),
```
**问题:** `BoxDecoration` 指示器把整个 tab 区域填满了颜色,视觉上看起来是"两个切换的按钮",而不是"登录/注册的文字选项卡"。用户期望选中态只是一个文字下方的指示条或紧凑的 pill 包裹文字。
#### 4.3.2 修改方案:Underline 风格选项卡
```dart
// sakura_mobile/lib/src/pages/login_page.dart
// 将 TabBar 的 indicator 从 BoxDecoration 改为 UnderlineTabIndicator
Container(
// ✅ 去掉容器的背景色和圆角,让它更轻量
decoration: BoxDecoration(
border: Border(
bottom: BorderSide(
color: const Color(0xFFF1CAD7).withValues(alpha: 0.4),
width: 1,
),
),
),
child: TabBar(
controller: _tabController,
// ✅ 将方块指示器改为下划线 + 文字颜色变化
indicator: UnderlineTabIndicator(
borderSide: const BorderSide(
color: Color(0xFFD95A83), // 粉色下划线
width: 2.5,
),
insets: const EdgeInsets.symmetric(horizontal: 16), // 下划线比文字略宽
),
// ✅ 选中文字用主题色,不再白字(因为没有蓝色方块了)
labelColor: const Color(0xFFD95A83),
labelStyle: const TextStyle(
fontWeight: FontWeight.w700,
fontSize: 15,
),
unselectedLabelColor: const Color(0xFF8A6A74),
unselectedLabelStyle: const TextStyle(
fontWeight: FontWeight.w500,
fontSize: 15,
),
dividerColor: Colors.transparent,
indicatorSize: TabBarIndicatorSize.label, // ✅ 指示器宽度 = 文字宽度
tabs: const [
Tab(text: '登录'),
Tab(text: '注册'),
],
),
),
```
**效果对比:**
```
修改前(BoxDecoration 方块): 修改后(Underline 文字下划线):
┌──────────────────────────┐ ┌──────────────────────────┐
│ ┌─────────┬─────────┐ │ │ │
│ │ ■■■■■■ │ 登录 │ │ │ 登录 注册 │
│ │ ■登录■ │ │ │ │ ════ │
│ │ ■■■■■■ │ │ │ │ │
│ └─────────┴─────────┘ │ │ │
│ 蓝色方块填充整个tab │ │ 粉色下划线 + 文字变色 │
└──────────────────────────┘ └──────────────────────────┘
```
**备选方案:Pill 风格(推荐用于需要更强视觉区分的场景)**
如果希望保留一定视觉强度但不至于太"重",可以使用更紧凑的 pill 包裹文字:
```dart
indicator: BoxDecoration(
color: const Color(0xFFFFE8EE), // 浅粉底,不是深色方块
borderRadius: BorderRadius.circular(20),
),
labelColor: const Color(0xFFD95A83), // 文字用深粉,不用白色
```
### 4.4 问题三:标题位置太低(SliverAppBar.large 优化)
#### 4.4.1 现状分析
当前 `gallery_tab.dart` 和 `novels_tab.dart` 均使用 `SliverAppBar.large`,这会渲染一个 Material 3 风格的大标题:
```dart
// gallery_tab.dart 第 312 行
SliverAppBar.large(
title: Text(selectionMode ? '已选 ${selectedIds.length} 项' : widget.pageTitle),
bottom: PreferredSize(
preferredSize: Size.fromHeight(selectionMode ? 266 : 178),
// 搜索栏 + 筛选 Chip 行...
),
),
```
**具体问题:**
1. `SliverAppBar.large` 的 title 区域高度约 **120-140px**,仅用于显示"图片"或"漫画"两个字
2. `bottom` 的 `PreferredSize` 又占用 **178-266px**(搜索栏 56px + 搜索范围 chips 行 50px + 筛选 chips 行 50px + 可能的选区面板 88px)
3. 在 720px 高的手机上,标题+筛选区域合计占用约 **300-400px**,超过屏幕一半,核心内容(图片网格/列表)被严重挤压
4. `home_page.dart` 中还嵌套了 `SafeArea`(第 49 行),顶部再增加约 24-40px
#### 4.4.2 修改方案:紧凑化 AppBar + 搜索栏外提
**方案:将 SliverAppBar.large 改为标准 SliverAppBar + 将搜索栏提升到 AppBar 内部**
```dart
// gallery_tab.dart build 方法修改
@override
Widget build(BuildContext context) {
final api = ref.watch(apiClientProvider);
return FutureBuilder<List<Artwork>>(
future: future,
builder: (context, snapshot) {
final items = snapshot.data ?? const <Artwork>[];
final mangaEntries = _isMangaShelfMode
? buildMangaCollections(items)
: const <MangaCollection>[];
return CustomScrollView(
slivers: [
// ✅ 修改 1:SliverAppBar.large → 标准 SliverAppBar(更紧凑)
SliverAppBar(
pinned: true, // 吸顶
floating: false,
snap: false,
// 使用标准高度(约 56px)而不是 large 的 120px+
title: Text(
selectionMode ? '已选 ${selectedIds.length} 项' : widget.pageTitle,
style: const TextStyle(
fontWeight: FontWeight.w700,
fontSize: 20, // 比 large title 的 28-32px 更紧凑
),
),
// ✅ 修改 2:bottom 压缩高度(-30px 从搜索范围行移除)
bottom: PreferredSize(
preferredSize: Size.fromHeight(
selectionMode ? 210 : 140, // 原 266/178 → 压缩约 20%
),
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 12),
child: Column(
children: [
// 搜索栏
SearchBar(
controller: search,
hintText: '搜索标题、作者或标签',
leading: const Icon(Icons.search),
trailing: [
if (!selectionMode)
IconButton(
tooltip: '管理',
onPressed: () {
setState(() { selectionMode = true; });
},
icon: const Icon(Icons.checklist_rounded),
),
IconButton(
tooltip: '刷新',
onPressed: _refresh,
icon: const Icon(Icons.refresh),
),
],
onSubmitted: (_) => _refresh(),
),
const SizedBox(height: 8), // 原 10 → 8
// ✅ 修改 3:将搜索范围 Chips 和筛选 Chips 合并为一行
SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: Row(
children: [
// 搜索范围(更紧凑的图标按钮)
_CompactToggle(
icon: Icons.search,
label: '全部',
selected: searchScope == 'all',
onTap: () => setState(() {
searchScope = 'all';
future = _load();
}),
),
_CompactToggle(
icon: Icons.title,
label: '标题',
selected: searchScope == 'title',
onTap: () => setState(() {
searchScope = 'title';
future = _load();
}),
),
_CompactToggle(
icon: Icons.label_outline,
label: '标签',
selected: searchScope == 'tags',
onTap: () => setState(() {
searchScope = 'tags';
future = _load();
}),
),
_CompactToggle(
icon: Icons.text_fields,
label: 'OCR',
selected: searchScope == 'ocr',
onTap: () => setState(() {
searchScope = 'ocr';
future = _load();
}),
),
const SizedBox(width: 12),
// 分隔符
Container(
width: 1,
height: 20,
color: const Color(0xFFF1CAD7),
),
const SizedBox(width: 12),
// 筛选条件
_CompactToggle(
icon: Icons.update,
label: '最近',
selected: recentUpdatesOnly && !favoritesOnly,
onTap: () => setState(() {
recentUpdatesOnly = true;
favoritesOnly = false;
future = _load();
}),
),
_CompactToggle(
icon: Icons.auto_awesome,
label: _allChipLabel,
selected: !recentUpdatesOnly &&
!favoritesOnly &&
(_effectiveContentType == null ||
_effectiveContentType == widget.fixedContentType),
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType = '';
future = _load();
}),
),
if (widget.showTypeFilters &&
widget.fixedContentType == null) ...[
_CompactToggle(
icon: Icons.menu_book_rounded,
label: '漫画',
selected: contentType == 'manga',
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType =
contentType == 'manga' ? '' : 'manga';
future = _load();
}),
),
_CompactToggle(
icon: Icons.brush,
label: '插画',
selected: contentType == 'illust',
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType =
contentType == 'illust' ? '' : 'illust';
future = _load();
}),
),
],
_CompactToggle(
icon: Icons.favorite,
label: '收藏',
selected: favoritesOnly,
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = !favoritesOnly;
future = _load();
}),
),
],
),
),
// 选区面板(仅在 selection mode 时显示)
if (selectionMode) ...[
const SizedBox(height: 8),
_SelectionPanel(
message: _selectionHint,
onCancel: _exitSelectionMode,
onDownload: selectedIds.isEmpty
? null
: () => _downloadSelected(items),
onDelete:
selectedIds.isEmpty ? null : _deleteSelected,
),
],
],
),
),
),
),
// ... 内容区域不变
],
);
},
);
}
// ✅ 新增紧凑型 Toggle 组件(替代原有的 ChoiceChip)
class _CompactToggle extends StatelessWidget {
const _CompactToggle({
required this.icon,
required this.label,
required this.selected,
required this.onTap,
});
final IconData icon;
final String label;
final bool selected;
final VoidCallback onTap;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.only(right: 6),
child: Material(
color: selected ? const Color(0xFFFFE8EE) : Colors.transparent,
borderRadius: BorderRadius.circular(20),
child: InkWell(
onTap: onTap,
borderRadius: BorderRadius.circular(20),
child: Padding(
padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 7),
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
icon,
size: 16,
color: selected
? const Color(0xFFD95A83)
: const Color(0xFF8A6A74),
),
const SizedBox(width: 5),
Text(
label,
style: TextStyle(
fontSize: 13,
fontWeight: selected ? FontWeight.w700 : FontWeight.w500,
color: selected
? const Color(0xFFD95A83)
: const Color(0xFF8A6A74),
),
),
],
),
),
),
),
);
}
}
```
#### 4.4.3 空间节省对比
```
修改前:
┌─────────────────────────────────┐
│ SafeArea padding (~24px) │
│ SliverAppBar.large title │
│ "图片" 大标题 (~120px) │ ← 浪费!只显示2个字
│ 搜索栏 (~56px) │
│ 搜索范围 Chips 行 (~50px) │
│ 筛选 Chips 行 (~50px) │
├─────────────────────────────────┤
│ 内容区域仅剩 ~420px │ ← 被挤压
└─────────────────────────────────┘
修改后:
┌─────────────────────────────────┐
│ SliverAppBar (pinned, 56px) │
│ 搜索栏 + 合并 Chips 行 (~130px) │ ← 紧凑,图标+文字 Chip
├─────────────────────────────────┤
│ 内容区域恢复 ~534px │ ← 多出约 27% 空间
└─────────────────────────────────┘
```
#### 4.4.4 novels_tab.dart 同理修改
对 `novels_tab.dart` 中 `SliverAppBar.large`(第 244 行)做相同的紧凑化处理:
```dart
// novels_tab.dart 修改
SliverAppBar(
pinned: true,
title: Text(
selectionMode ? '已选 ${selectedEntryIds.length} 项' : '系列书架',
style: const TextStyle(fontWeight: FontWeight.w700, fontSize: 20),
),
bottom: PreferredSize(
preferredSize: Size.fromHeight(selectionMode ? 174 : 118), // 原 212/126 → 压缩
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 12),
child: Column(
children: [
SearchBar(
controller: search,
hintText: '搜索书名、作者或章节名',
leading: const Icon(Icons.search),
trailing: [
if (!selectionMode)
IconButton(
tooltip: '管理',
onPressed: () => setState(() { selectionMode = true; }),
icon: const Icon(Icons.checklist_rounded),
),
IconButton(
tooltip: '刷新',
onPressed: _refresh,
icon: const Icon(Icons.refresh),
),
],
onSubmitted: (_) => _refresh(),
),
if (selectionMode) ...[
const SizedBox(height: 8),
_NovelSelectionPanel(
message: selectedEntryIds.isEmpty
? '长按书架卡片开始多选,支持批量删除。'
: '已选 ${selectedEntryIds.length} 项,可以继续点选调整。',
onCancel: _clearSelection,
onDelete: selectedEntryIds.isEmpty
? null
: () => _deleteSelectedEntries(entries),
),
],
const SizedBox(height: 8),
],
),
),
),
),
```
### 4.5 修改涉及文件汇总
| 文件 | 修改内容 | 预计工时 |
|------|----------|----------|
| `sakura_mobile/lib/src/pages/login_page.dart` | 蓝色→粉色配色替换、TabBar 指示器改为 underline | 1h |
| `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | `SliverAppBar.large` → `SliverAppBar` 紧凑化、合并 Chips 行、新增 `_CompactToggle` | 1.5h |
| `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` | `SliverAppBar.large` → `SliverAppBar` 紧凑化 | 0.5h |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 检查是否也有标题过高问题 | 0.5h |
---
## 五、实施优先级与排期建议
| 优先级 | 任务 | 预计工时 | 依赖 |
|--------|------|----------|------|
| **P0** | WEB 端认证修复(方案 A + B + D) | 2-3h | 无 |
| **P0** | Nginx 生产部署配置(方案 C) | 1h | 方案 B |
| **P0** | 登录页蓝→粉配色替换 | 1h | 无 |
| **P0** | TabBar 指示器改为 underline 风格 | 0.5h | 无 |
| **P1** | SliverAppBar.large → 紧凑化(gallery + novels) | 2h | 无 |
| **P1** | Legado 规则引擎(RuleParser + Engine) | 8-12h | 无 |
| **P1** | 源管理器(SourceManager + 预置源导入 + 用户自定义导入) | 3-4h | 规则引擎 |
| **P1** | 源管理页面 UI(预置源列表 + 导入 + 启用/禁用) | 3-4h | 源管理器 |
| **P2** | OnlineMangaReaderPage(纯内存漫画阅读器) | 2-3h | 规则引擎 |
| **P2** | OnlineNovelReaderPage(纯内存小说阅读器) | 1-2h | 规则引擎 |
| **P2** | 统一搜索页 ExplorePage(跨源聚合搜索) | 3-4h | 规则引擎 + 源管理器 |
| **P2** | GalleryTab/NovelsTab 添加"在线"Tab 切换 | 2-3h | 以上全部 |
| **P3** | 订阅源自动更新(后台定时拉取) | 1-2h | 源管理器 |
| **P3** | 源校验/速度测试工具 | 2h | 规则引擎 |
---
> **建议执行顺序**:
> 1. **P0(半天)**:WEB 端认证修复 + 登录页配色/TabBar → 立即可见改进
> 2. **P1(2-3 天)**:SliverAppBar 紧凑化 + Legado 规则引擎 + 源管理器 → 基础设施就绪
> 3. **P2(2-3 天)**:在线阅读器 + 跨源搜索页 + Tab 切换 → 功能闭环
> 4. **P3(按需)**:订阅更新 + 源校验工具
>
> **关键里程碑:**
> - P1 完成后:APP 即可导入 6000+ 条 Legado 源,在源管理页查看
> - P2 完成后:用户可跨源搜索 + 在线浏览任意源的内容,不下载不留痕
> - 整个方案无需手写任何单个源的解析器,完全依赖 Legado 社区生态