Files

1976 lines
80 KiB
Markdown
Raw Permalink Normal View History

2026-11-16 20:45:22 +08:00
# 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 社区生态