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

80 KiB
Raw Blame History

APK 端漫画/小说第三方源集成 + WEB 端认证修复方案

更新日期:2026-06-15 范围:Sakura Mobile (Flutter APK) + Sakura Cloud (FastAPI) + Sakura Admin Web (Vue.js) 说明:本文档提供完整的问题分析与实现方案,按模块划分,方便逐步实施。


目录

  1. APK 端:漫画与小说第三方来源网站集成
  2. APK 端:未保存内容的在线搜索与实时浏览
  3. WEB 端:认证失败与登录页缺失修复
  4. 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 对象,核心字段:

{
  "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 源数据模型:

// 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 预处理(高级,可延后支持)
}

规则引擎核心逻辑:

// 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)—— 支持四种语法:

// 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:源管理器 —— 三层漏斗 + 默认精选

// 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 个

搜索限流器:

// 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:搜索 —— 跨源聚合搜索引擎

// 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(),不写入任何本地文件。

// 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:

// 类似 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 后,访问页面始终返回:

{"detail": "Not authenticated"}

没有出现登录页面,直接报错,无法正常使用。

3.2 根因分析

经过对全部相关代码的排查,问题涉及以下多个层面:

根因 1:CSP(内容安全策略)过于严格 —— 核心问题

文件位置: sakura_cloud/api/middleware.py 第 37-41 行

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 行

@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 行

const path = admin ? "/admin/login" : "/auth/login";
const response = await http.post(path, { ... });

文件位置: sakura_admin_web/src/api/http.ts 第 4 行

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 行

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:

# 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 静态文件服务:

# 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:

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 页面不需要认证检查:

// 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(新建):

# sakura_admin_web/.env.production
VITE_API_BASE_URL=/api/v1

修改 sakura_admin_web/vite.config.ts,添加生产构建选项:

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 行:

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 修改方案

将登录页所有硬编码蓝色替换为主题粉色系:

// 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 行

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 风格选项卡

// 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 包裹文字:

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 风格的大标题:

// 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 内部

// 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 行)做相同的紧凑化处理:

// 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 社区生态