Files

1042 lines
54 KiB
Python
Raw Permalink Normal View History

2026-11-16 20:45:22 +08:00
#!/usr/bin/env python3
"""Generate comprehensive project documentation DOCX for Sakura Downloader."""
from docx import Document
from docx.shared import Inches, Pt, Cm, RGBColor, Emu
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.section import WD_ORIENT
from docx.enum.style import WD_STYLE_TYPE
from docx.oxml.ns import qn
from docx.oxml import OxmlElement
import os
from datetime import date
doc = Document()
# ============================================================
# 页面设置
# ============================================================
section = doc.sections[0]
section.page_width = Cm(21)
section.page_height = Cm(29.7)
section.left_margin = Cm(2.0)
section.right_margin = Cm(2.0)
section.top_margin = Cm(2.0)
section.bottom_margin = Cm(2.0)
# ============================================================
# 样式定义
# ============================================================
style = doc.styles['Normal']
font = style.font
font.name = 'Arial'
font.size = Pt(11)
style.paragraph_format.space_after = Pt(6)
style.paragraph_format.line_spacing = 1.4
# 设置中文字体
rPr = style.element.get_or_add_rPr()
rFonts = OxmlElement('w:rFonts')
rFonts.set(qn('w:eastAsia'), '微软雅黑')
rPr.append(rFonts)
for level in range(1, 5):
heading_style = doc.styles[f'Heading {level}']
heading_font = heading_style.font
heading_font.color.rgb = RGBColor(0x4A, 0x20, 0x40)
hRpr = heading_style.element.get_or_add_rPr()
hFonts = OxmlElement('w:rFonts')
hFonts.set(qn('w:eastAsia'), '微软雅黑')
hRpr.append(hFonts)
# Helper functions
def add_heading(text, level=1):
"""Add heading and set spacing."""
h = doc.add_heading(text, level=level)
h.paragraph_format.space_before = Pt(16 if level == 1 else 12)
return h
def add_para(text, bold=False, size=None, color=None, indent=False):
"""Add a paragraph with formatting."""
p = doc.add_paragraph()
if indent:
p.paragraph_format.left_indent = Cm(1)
run = p.add_run(text)
if bold:
run.bold = True
if size:
run.font.size = Pt(size)
if color:
run.font.color.rgb = color
return p
def add_bullet(text, level=0):
"""Add a bullet point."""
p = doc.add_paragraph(text, style='List Bullet')
if level > 0:
p.paragraph_format.left_indent = Cm(1.5 * (level + 1))
return p
def add_table(headers, rows):
"""Add a formatted table."""
table = doc.add_table(rows=1 + len(rows), cols=len(headers))
table.style = 'Light Grid Accent 1'
# Header
for i, header in enumerate(headers):
cell = table.rows[0].cells[i]
cell.text = header
for paragraph in cell.paragraphs:
for run in paragraph.runs:
run.bold = True
run.font.size = Pt(9)
# Data
for r, row in enumerate(rows):
for c, val in enumerate(row):
cell = table.rows[r + 1].cells[c]
cell.text = str(val)
for paragraph in cell.paragraphs:
for run in paragraph.runs:
run.font.size = Pt(9)
doc.add_paragraph() # spacing
return table
def add_code_block(text):
"""Add a code-style block."""
p = doc.add_paragraph()
p.paragraph_format.left_indent = Cm(1)
p.paragraph_format.space_before = Pt(4)
p.paragraph_format.space_after = Pt(4)
run = p.add_run(text)
run.font.name = 'Consolas'
run.font.size = Pt(9)
run.font.color.rgb = RGBColor(0x33, 0x33, 0x33)
return p
# ============================================================
# 封面
# ============================================================
for _ in range(6):
doc.add_paragraph()
title_p = doc.add_paragraph()
title_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
title_run = title_p.add_run('樱云下载器\nSakura Downloader')
title_run.bold = True
title_run.font.size = Pt(28)
title_run.font.color.rgb = RGBColor(0xD9, 0x5A, 0x83)
doc.add_paragraph()
subtitle_p = doc.add_paragraph()
subtitle_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
sub_run = subtitle_p.add_run('完整项目文档\n项目结构 · 功能说明 · 使用手册 · 三端特点')
sub_run.font.size = Pt(14)
sub_run.font.color.rgb = RGBColor(0x7B, 0x65, 0x70)
doc.add_paragraph()
doc.add_paragraph()
date_p = doc.add_paragraph()
date_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
date_run = date_p.add_run(f'文档版本: 1.0\n生成日期: {date.today().strftime("%Y年%m月%d日")}')
date_run.font.size = Pt(11)
date_run.font.color.rgb = RGBColor(0x99, 0x99, 0x99)
doc.add_page_break()
# ============================================================
# 目录页
# ============================================================
add_heading('目 录', 1)
doc.add_paragraph()
toc_items = [
('第一部分', '项目概述与架构总览', ''),
('', '1.1 项目简介', ''),
('', '1.2 三端架构总览', ''),
('', '1.3 技术栈总表', ''),
('第二部分', '完整项目结构', ''),
('', '2.1 项目根目录结构', ''),
('', '2.2 桌面端 (pixiv_app) 结构', ''),
('', '2.3 云端后端 (sakura_cloud) 结构', ''),
('', '2.4 移动端 (sakura_mobile) 结构', ''),
('', '2.5 管理后台 (sakura_admin_web) 结构', ''),
('', '2.6 插件系统 (plugins) 结构', ''),
('', '2.7 分布式爬虫 (distributed_crawler) 结构', ''),
('第三部分', '项目内容与功能说明', ''),
('', '3.1 桌面端核心功能', ''),
('', '3.2 Sakura Cloud 后端功能', ''),
('', '3.3 移动端 APP 功能', ''),
('', '3.4 管理后台功能', ''),
('', '3.5 插件系统功能', ''),
('', '3.6 Legado 在线书源引擎', ''),
('第四部分', '使用手册', ''),
('', '4.1 桌面端使用指南', ''),
('', '4.2 移动端 APP 使用指南', ''),
('', '4.3 管理后台使用指南', ''),
('', '4.4 云端部署指南', ''),
('', '4.5 常见问题 (FAQ)', ''),
('第五部分', '三端特点与对比', ''),
('', '5.1 桌面端特点', ''),
('', '5.2 移动端特点', ''),
('', '5.3 管理后台特点', ''),
('', '5.4 三端对比表', ''),
('附录', '关键文件索引与技术参考', ''),
]
for part, title, _ in toc_items:
if part:
p = doc.add_paragraph()
run = p.add_run(f'{part} {title}')
run.bold = True
run.font.size = Pt(12)
else:
p = doc.add_paragraph()
p.paragraph_format.left_indent = Cm(1.5)
run = p.add_run(title)
run.font.size = Pt(10)
doc.add_page_break()
# ============================================================
# 第一部分:项目概述与架构总览
# ============================================================
add_heading('第一部分 项目概述与架构总览', 1)
# ---- 1.1 ----
add_heading('1.1 项目简介', 2)
add_para('樱云下载器 (Sakura Downloader) 是一套完整的三端个人媒体管理与跨设备同步系统。'
'用户可以下载 Pixiv、Twitter/X、小红书、AO3、笔趣阁等平台的插画、漫画、小说内容,'
'通过 Sakura Cloud 云端同步到手机 APP 上随时阅读,并可通过 Web 管理后台进行数据管理。')
add_para('项目由以下四个核心组件构成:')
add_bullet('桌面端 (Windows):Python + CustomTkinter GUI — 负责内容下载、本地管理、云端同步')
add_bullet('Sakura Cloud 后端:FastAPI + PostgreSQL — 提供用户认证、数据存储、API 服务')
add_bullet('Android 移动端:Flutter + Riverpod — 云端内容浏览、在线阅读、推送通知')
add_bullet('Web 管理后台:Vue 3 + TypeScript + Vite — 用户自管理 + 管理员仪表盘')
add_para('此外还有两个辅助系统:')
add_bullet('插件系统:5 个内容源插件 (Pixiv / X / 小红书 / 笔趣阁 / AO3),支持扩展')
add_bullet('分布式爬虫:Master + Worker 架构,Redis 消息队列,用于大规模内容采集')
# ---- 1.2 ----
add_heading('1.2 三端架构总览', 2)
add_para('以下是项目的整体架构关系:')
arch_text = """┌─────────────────────────────────────────────────────────────────┐
│ 樱云下载器 (Sakura Downloader) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ 同步上传 ┌──────────────────┐ │
│ │ 桌面端 (Windows) │ ───────→ │ Sakura Cloud │ │
│ │ │ │ (FastAPI + PG) │ │
│ │ · Pixiv 下载 │ │ │ │
│ │ · 多平台插件 │ │ · 用户认证 │ │
│ │ · 本地画廊 │ │ · 文件存储 │ │
│ │ · SQLite 图书馆 │ │ · 画廊/小说 API │ │
│ └─────────────────┘ │ · OCR 索引 │ │
│ │ · 推送通知 │ │
│ ┌─────────────────┐ └────────┬─────────┘ │
│ │ 插件系统 │ │ │
│ │ Pixiv/X/小红书 │ ┌────────▼─────────┐ │
│ │ 笔趣阁/AO3 │ │ │ │
│ └─────────────────┘ │ ┌──────────────┐ │ │
│ │ │ Android APP │ │ │
│ ┌─────────────────┐ │ │ (Flutter) │ │ │
│ │ Web 管理后台 │ 管理API │ │ │ │ │
│ │ (Vue 3) │ ←──────→ │ │ · 云库浏览 │ │ │
│ │ │ │ │ · 在线阅读 │ │ │
│ │ · 用户面板 │ │ │ · Legado 书源 │ │ │
│ │ · 管理员仪表盘 │ │ │ · 推送通知 │ │ │
│ └─────────────────┘ │ └──────────────┘ │ │
│ └──────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 分布式爬虫 (可选) │ │
│ │ Master + Worker · Redis 队列 · 代理池 · 断点续传 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘"""
add_code_block(arch_text)
# ---- 1.3 ----
add_heading('1.3 技术栈总表', 2)
add_table(
['层级', '桌面端', '云端后端', '移动端', '管理后台'],
[
['语言', 'Python 3.8+', 'Python 3.11+', 'Dart 3.12', 'TypeScript 5.7'],
['框架', 'CustomTkinter', 'FastAPI', 'Flutter 3.44', 'Vue 3.5 + Vite 6'],
['数据库', 'SQLite', 'PostgreSQL 15', 'SharedPreferences', 'N/A (API)'],
['HTTP', 'requests / httpx', 'uvicorn', 'Dio 5.7', 'Axios 1.7'],
['状态管理', '内置', 'N/A', 'Riverpod 2.6', 'sessionStorage'],
['认证', 'Cookie / Session', 'JWT (HS256)', 'Bearer Token', 'Bearer Token'],
['自动化', 'Playwright', 'N/A', 'N/A', 'N/A'],
['推送', 'N/A', 'Firebase FCM', 'Firebase Msg', 'N/A'],
['OCR', 'PaddleOCR', 'PaddleOCR', 'N/A', 'N/A'],
['JS引擎', 'N/A', 'N/A', 'flutter_js (QuickJS)', 'N/A'],
['打包', 'PyInstaller', 'Docker', 'Gradle (APK)', 'Vite Build'],
]
)
doc.add_page_break()
# ============================================================
# 第二部分:完整项目结构
# ============================================================
add_heading('第二部分 完整项目结构', 1)
# ---- 2.1 ----
add_heading('2.1 项目根目录结构', 2)
add_code_block("""Pixiv/
├── main.py # 桌面端入口
├── README.md # 项目说明
├── requirements.txt # 桌面端 Python 依赖
├── .gitignore
├── .env.cloud.example # 云端环境变量模板
│
├── pixiv_app/ # ★ 桌面端核心 (Python/CustomTkinter)
│ ├── gui/ # 图形界面 (3 个文件)
│ ├── core/ # 核心业务逻辑 (17 个文件 + plugin 子包)
│ ├── runtime/ # 任务执行引擎 (3 个文件)
│ ├── services/ # 本地 API 服务 (4 个文件)
│ ├── tasks/ # 任务队列模型 (4 个文件)
│ └── webui/ # 本地画廊 Web 界面 (3 个非 Python 文件)
│
├── sakura_cloud/ # ★ 云端后端 (FastAPI + PostgreSQL)
│ ├── main.py # FastAPI 应用入口
│ ├── api/ # API 路由 (deps + middleware + v1/)
│ │ └── v1/endpoints/ # 14 个端点模块
│ ├── models/ # SQLAlchemy 数据模型 (12 张表)
│ ├── schemas/ # Pydantic 序列化模式 (12 个模块)
│ ├── services/ # 业务服务 (8 个模块)
│ ├── core/ # 核心配置 (config, security, safety, logging)
│ ├── db/ # 数据库连接 (session, base)
│ ├── migrations/ # Alembic 迁移 (12 个版本)
│ ├── scripts/ # 工具脚本 (init_db, create_admin)
│ ├── docker-compose.yml # Docker 编排 (PostgreSQL + Redis)
│ └── requirements.txt # 云端 Python 依赖
│
├── sakura_mobile/ # ★ Android 移动端 (Flutter/Dart)
│ ├── pubspec.yaml # Flutter 依赖配置
│ ├── lib/
│ │ ├── main.dart # 应用入口
│ │ └── src/
│ │ ├── app.dart # 主题 + 根组件
│ │ ├── core/ # 核心引擎 (13 个文件)
│ │ ├── models/ # 数据模型 (2 个文件)
│ │ └── pages/ # UI 页面 (16 个文件)
│ ├── android/ # Android 原生配置
│ └── test/ # 测试文件 (5 个)
│
├── sakura_admin_web/ # ★ Web 管理后台 (Vue 3 + TypeScript)
│ ├── package.json # Node.js 依赖
│ ├── vite.config.ts # Vite 构建配置
│ ├── index.html # SPA 入口
│ └── src/
│ ├── router/index.ts # 路由配置 (25+ 路由)
│ ├── views/ # 视图组件 (12 个)
│ ├── stores/ # 状态管理 (3 个 store)
│ ├── api/http.ts # Axios HTTP 客户端
│ └── styles.css # 全局样式
│
├── plugins/ # ★ 插件系统 (Python)
│ ├── pixiv/ # Pixiv 插件 (250 行)
│ ├── biquge/ # 笔趣阁插件 (1134 行)
│ ├── x/ # X/Twitter 插件 (497 + 891 行)
│ ├── xiaohongshu/ # 小红书插件 (995 行)
│ └── ao3/ # AO3 插件 (1029 行)
│
├── distributed_crawler/ # 分布式爬虫 (Python asyncio)
├── docs/ # 项目文档 (12 个 .md 文件)
├── scripts/ # 构建脚本 (7 个 .bat 文件)
├── tools/ # 工具链 (Android SDK, Flutter SDK)
└── releases/ # 构建产物 (APK, EXE)""")
# ---- 2.2 ----
add_heading('2.2 桌面端 (pixiv_app) 结构', 2)
add_para('桌面端采用分层架构,共 41 个 Python 文件:', bold=True)
add_table(
['子目录', '文件数', '核心职责'],
[
['gui/', '3', 'CustomTkinter 图形界面:主窗口 (2707 行)、插件面板、代理配置'],
['core/', '17+4', '核心业务:下载引擎、SQLite 数据库层、认证、代理池、云端同步、画廊服务、OCR、缩略图、指纹管理、插件系统'],
['runtime/', '3', '任务执行:任务入队、执行器、Worker 循环'],
['services/', '4', '本地服务:画廊 API 服务器、X 登录管理、X 认证管理'],
['tasks/', '4', '任务模型:任务规格、队列、批量解析、水印'],
['webui/', '3', '本地画廊 Web 界面(HTML + JavaScript + CSS)'],
]
)
add_para('关键模块说明:', bold=True)
add_bullet('pixiv_app/core/downloader.py (37KB) — 核心下载引擎:支持单图、用户批量、小说、关键词搜索下载,带速率限制和重试机制')
add_bullet('pixiv_app/core/library.py (30KB) — PixivLibrary:10+ 张 SQLite 表,管理 artworks/artists/tags/files/tasks/follows/ocr_texts')
add_bullet('pixiv_app/core/gallery_service.py (31KB) — LocalGalleryService:本地媒体库搜索、筛选、浏览')
add_bullet('pixiv_app/gui/app.py (125KB/2707 行) — 主 GUI 窗口:五大内容平台 + 完整下载工作流')
add_bullet('pixiv_app/core/cloud_sync.py (10KB) — Sakura Cloud 同步:自动上传、重试队列、账户管理')
add_bullet('pixiv_app/core/plugin/ — 插件系统:ABC 基类、管理器、生成器(Jinja2 模板)、市场客户端')
# ---- 2.3 ----
add_heading('2.3 云端后端 (sakura_cloud) 结构', 2)
add_para('Sakura Cloud 是一个 FastAPI 后端服务,采用典型的分层架构:', bold=True)
add_table(
['层级', '文件数', '说明'],
[
['API 端点 (endpoints/)', '14', 'health, auth, admin, users, me, devices, upload, files, gallery, novels, follows, push, sync, tags'],
['数据模型 (models/)', '12', 'User, Device, FileBlob, UserFile, UploadSession, Artwork, Novel, CreatorFollow, UpdateAlert, PushDeviceToken, ArtworkOcrText, AdminAuditLog, FeedCache'],
['Pydantic 模式 (schemas/)', '12', 'common, auth, user, device, upload, gallery, novel, follow, push, ocr, admin'],
['业务服务 (services/)', '8', '文件存储、缩略图生成、数据库迁移、FCM 推送、定时提醒、PaddleOCR、审计日志'],
['数据库迁移', '12 版本', '从初始建表到 P2 查询优化索引的完整演化历史'],
]
)
add_para('全部 API 端点统计:60+ 个 REST 接口', bold=True)
add_para('核心 API 分类:')
add_bullet('Auth: 注册/登录/登出/刷新 — JWT HS256,token_version 即时吊销')
add_bullet('Gallery: 画廊 CRUD + 分页搜索 + 内容类型筛选 + Feed + 收藏 + 标签 + OCR + 在线导入')
add_bullet('Novels: 小说 CRUD + 全文搜索 + 系列分组 + 阅读进度 + 书签 + 在线导入')
add_bullet('Files: 分块上传 (init/chunk/complete) + SHA256 去重 + 缩略图')
add_bullet('Follows: 创作者关注 + 批量同步 + 更新提醒 (含 FCM 推送)')
add_bullet('Admin: 仪表盘统计 + 用户/文件/画廊/小说 CRUD + 系统健康检查 + 审计日志')
add_bullet('Push: FCM 设备令牌注册/注销 + 推送历史查询')
# ---- 2.4 ----
add_heading('2.4 移动端 (sakura_mobile) 结构', 2)
add_para('移动端是一个 Flutter 3.44 应用,采用 Riverpod 状态管理,共 31 个 Dart 文件:', bold=True)
add_table(
['目录', '文件数', '内容'],
[
['core/', '13', 'API 客户端、会话管理、书源管理、Legado 搜索引擎、规则解析器、规则执行器 (8 级)、JS 执行器、统一搜索、漫画合集、在线缓存、阅读历史、推送通知、Provider 注入'],
['pages/', '12', '主页 (5 Tab)、登录、详情/阅读器 (artwork/novel/online manga/online novel/online book)、搜索、收藏、提醒中心、书源管理'],
['pages/tabs/', '4', '发现 Feed、图片画廊、漫画画廊、小说书架、个人中心'],
['models/', '2', 'Artwork 模型 (含漫画合集)、Novel 模型 (含系列)'],
]
)
add_para('核心 Flutter 依赖:', bold=True)
add_bullet('flutter_riverpod — 状态管理 (Provider + ChangeNotifier)')
add_bullet('dio — HTTP 客户端 (支持 GBK 编码拦截器)')
add_bullet('cached_network_image — 图片缓存与展示')
add_bullet('photo_view — 图片缩放浏览')
add_bullet('firebase_messaging — FCM 推送通知')
add_bullet('gbk_codec — GBK 字符编码支持')
add_bullet('flutter_js — QuickJS JavaScript 引擎 (用于 Legado 规则 @js/<js> 执行)')
# ---- 2.5 ----
add_heading('2.5 管理后台 (sakura_admin_web) 结构', 2)
add_para('Web 管理后台是一个 Vue 3 + TypeScript + Vite 单页应用,共 25+ 路由:', bold=True)
add_table(
['路由分组', '页面数', '功能'],
[
['用户面板 (/app)', '7', '仪表盘、图片列表、漫画列表 (含系列)、小说列表 (含系列)、提醒列表、个人资料、各内容详情/阅读页'],
['管理员面板 (/admin)', '11', '仪表盘统计、用户管理、文件管理、画廊管理、小说管理、OCR 任务、推送设备、提醒管理、审计日志、系统健康'],
['公共页面', '5', '登录、注册、忘记密码、403、404'],
]
)
add_para('特点:Vue Router + Axios 拦截器 (自动 Token 刷新)、sessionStorage 持久化、漫画系列分组缓存、无第三方 UI 框架的手写 CSS 响应式布局')
# ---- 2.6 ----
add_heading('2.6 插件系统 (plugins) 结构', 2)
add_para('插件系统基于抽象基类 BasePlugin (ABC),每个插件位于独立子目录,包含 plugin.py 和 manifest.json。'
'PluginManager 从文件系统自动发现和加载插件,支持热重载和配置持久化。')
add_table(
['插件', '代码量', '下载目标', '技术方式'],
[
['Pixiv', '250 行', '插画 / 漫画 / 小说 / 用户批量', 'requests API + Cookie 认证'],
['笔趣阁 (Biquge)', '1134 行', '中文网络小说 (章节下载)', 'apibi.cc API (AES 加密) + HTML 回退 + Playwright 反爬'],
['X / Twitter', '497+891 行', '推文图片 / 视频 / 用户媒体', 'Playwright 浏览器自动化 + httpx 下载'],
['小红书 (Xiaohongshu)', '995 行', '笔记图片 / 搜索采集', 'Playwright + 代理池 + 指纹轮换'],
['AO3', '1029 行', '同人小说 (全本/EPUB)', 'HTML 解析 + EPUB 解包 + Cookie 认证'],
]
)
# ---- 2.7 ----
add_heading('2.7 分布式爬虫 (distributed_crawler) 结构', 2)
add_para('独立的 Python asyncio 分布式爬虫框架,用于大规模内容采集:')
add_table(
['组件', '功能'],
[
['Master', '任务分发 API + Worker 心跳管理 + 仪表盘'],
['Worker', '异步任务消费 + 代理轮换 + 会话共享'],
['Queue', 'Redis 优先级队列 + 死信队列'],
['Dedupe', 'Bloom Filter 任务去重'],
['Proxy', '代理池 + 加权随机选择 + 健康评分'],
['Circuit Breaker', '域名级熔断器 + 半开恢复探测'],
['Rate Limit', '域名感知漏桶限流'],
['Scheduler', 'APScheduler 定时任务提交'],
['Sink', '结果输出 (JSONL / MongoDB / PostgreSQL)'],
]
)
doc.add_page_break()
# ============================================================
# 第三部分:项目内容与功能说明
# ============================================================
add_heading('第三部分 项目内容与功能说明', 1)
# ---- 3.1 ----
add_heading('3.1 桌面端核心功能', 2)
add_para('桌面端是内容采集和管理的中心枢纽,提供以下核心功能:', bold=True)
add_heading('3.1.1 多平台内容下载', 3)
add_bullet('Pixiv:支持插画 (含多页)、漫画、小说、用户全部作品、关键词搜索下载')
add_bullet('Twitter/X:支持单条推文媒体、用户媒体栏、搜索采集、视频下载 (MP4 + HLS)')
add_bullet('小红书:支持单篇笔记、关键词搜索采集')
add_bullet('笔趣阁:支持搜索书籍、章节列表解析、全书章节下载')
add_bullet('AO3:支持作品元数据提取、全文 HTML 下载、EPUB 解析')
add_heading('3.1.2 认证系统', 3)
add_bullet('Pixiv:Cookie 导入 (Netscape/JSON 格式) + 密码登录 + Session 持久化')
add_bullet('X:Playwright 持久化浏览器 Profile + 交互式登录')
add_bullet('小红书:Playwright 浏览器 + 交互式登录')
add_bullet('跨平台 Cookie 导入:单文件自动识别 Pixiv / X / 小红书')
add_heading('3.1.3 任务队列系统', 3)
add_bullet('SQLite 持久化队列:pending → running → done/failed 状态流转')
add_bullet('线程安全:lease/reclaim 机制支持并发 Worker')
add_bullet('指纹去重:INSERT OR IGNORE 避免重复下载')
add_bullet('自动重试:可配置 max_attempts (默认 4),区分可重试错误 (429/408/5xx)')
add_heading('3.1.4 本地媒体库', 3)
add_bullet('PixivLibrary:10+ 张 SQLite 表管理全部本地内容')
add_bullet('本地画廊 Web 界面:HTML+JS+CSS 画廊墙,支持搜索和浏览')
add_bullet('缩略图缓存:自动生成和管理缩略图')
add_bullet('已有下载导入:LegacyDownloadImporter 扫描已下载文件')
add_heading('3.1.5 云端同步', 3)
add_bullet('Sakura Cloud 自动同步:下载完成后自动上传')
add_bullet('失败重试队列:同步失败的文件进入重试队列')
add_bullet('创作者关注同步:Pixiv/X 关注的创作者自动同步到云端')
add_bullet('增量水印:避免重复同步已处理内容')
add_heading('3.1.6 辅助功能', 3)
add_bullet('代理池:手动代理 + Quake 360 自动获取,支持国家过滤')
add_bullet('浏览器代理池:Playwright 专用代理,支持轮换策略')
add_bullet('OCR 索引:PaddleOCR 对下载图片进行文字识别和索引')
add_bullet('指纹管理:多套浏览器指纹 Profile 自动切换')
# ---- 3.2 ----
add_heading('3.2 Sakura Cloud 后端功能', 2)
add_para('Sakura Cloud 是整个系统的数据中心,提供以下功能:', bold=True)
add_heading('3.2.1 用户系统', 3)
add_bullet('注册/登录:用户名 + 邮箱 + 密码,JWT HS256 双 Token (24h access + 30d refresh)')
add_bullet('角色管理:USER / ADMIN / SUPER_ADMIN 三级权限')
add_bullet('Token 版本吊销:即时全局登出')
add_bullet('存储配额:默认 5GB/用户,可配置')
add_heading('3.2.2 文件存储', 3)
add_bullet('分块上传:init → append chunk → complete 三步流程')
add_bullet('内容寻址:按 SHA256 存储,跨用户自动去重')
add_bullet('缩略图生成:WebP 格式,最大 640px,质量 82')
add_bullet('安全校验:MIME 白名单 + 外部 URL 域名白名单 + 路径遍历防护')
add_heading('3.2.3 画廊 & 小说 API', 3)
add_bullet('画廊:CRUD + 内容类型筛选 (illust/manga/ugoira) + 标签 + 收藏')
add_bullet('小说:CRUD + 系列分组 + 阅读进度 + 书签 + 全文搜索 (PostgreSQL GIN)')
add_bullet('Feed 缓存:5 分钟 TTL 缓存画廊 Feed 查询')
add_bullet('在线导入:支持从 Legado 书源 URL 导入漫画/小说内容')
add_heading('3.2.4 推送与提醒', 3)
add_bullet('FCM 推送:设备令牌注册 + 更新提醒推送 + 令牌失效检测')
add_bullet('定时提醒:用户级时区感知的每日摘要 (检查是否有新内容提醒)')
add_heading('3.2.5 OCR 服务', 3)
add_bullet('PaddleOCR 集成:支持中英文识别,可配置并发度和重试次数')
add_bullet('GIN 全文索引:OCR 文本可搜索')
add_heading('3.2.6 管理员功能', 3)
add_bullet('仪表盘:总用户数 / 作品数 / 文件数 / 存储量 / OCR / 推送统计')
add_bullet('用户管理:启用/禁用、角色变更 (管理员/超级管理员)、密码重置')
add_bullet('审计日志:记录所有管理员操作 (含 IP、UA、详情 JSON)')
add_bullet('系统健康:数据库连接、存储状态、版本信息')
# ---- 3.3 ----
add_heading('3.3 移动端 APP 功能', 2)
add_para('Android APP 提供两大内容来源的阅读体验:', bold=True)
add_heading('3.3.1 云库阅读 (Sakura Cloud)', 3)
add_bullet('发现页 (Feed):统计卡片 + 最近更新 + 今日新增 + 最近小说 + 未读提醒')
add_bullet('图片画廊:网格浏览 + 搜索 + 收藏筛选 + PhotoView 大图浏览')
add_bullet('漫画画廊:系列分组 + 封面展示 + PageView 翻页阅读')
add_bullet('小说书架:系列分组 + 继续阅读 + 分页阅读器 + 字体缩放 + 翻译')
add_bullet('收藏:图片/小说双类型收藏管理')
add_bullet('提醒中心:创作者更新推送 + 关注管理 + 推送偏好设置')
add_heading('3.3.2 在线书源阅读 (Legado 引擎)', 3)
add_bullet('书源管理:导入/启用/禁用 Legado 标准 JSON 书源 + 订阅自动更新')
add_bullet('统一搜索:云库 + 在线源并行搜索 + 漫画/小说模式切换')
add_bullet('在线书籍详情:BookInfo + TOC 合并在同一页面 + 分段异步加载')
add_bullet('在线阅读器:章节驱动 + 上一章/下一章/目录导航 + 预加载 + 阅读记录')
add_bullet('8 级规则执行器:@tag → @text/@attr → index → fallback → && → ##净化 → @put/@get → @js')
add_bullet('JS 执行:QuickJS 引擎支持 @js/<js> 规则 + JS 变量特判 (newImgs 等)')
add_bullet('编码适配:GBK/UTF-8 自动检测 + GBK URL 编码')
add_bullet('分页目录:支持 {{page}} 占位符 + tocNextPageRule + 最多 20 页上限')
add_bullet('书源兼容度检测:导入时自动分析规则语法并打标签')
# ---- 3.4 ----
add_heading('3.4 管理后台功能', 2)
add_para('Web 管理后台分为用户面板和管理员面板两个模块:', bold=True)
add_heading('用户面板 (/app)', 3)
add_bullet('仪表盘:用户概览 (用户名/邮箱/存储用量) + 快速入口')
add_bullet('图片管理:分页浏览 + 搜索 + 详情查看')
add_bullet('漫画管理:系列自动分组 + 封面展示 + 章节列表 + 画面浏览')
add_bullet('小说管理:系列分组 + 章节列表 + 正文阅读')
add_bullet('提醒中心:更新提醒列表')
add_bullet('个人资料:查看个人信息')
add_heading('管理员面板 (/admin)', 3)
add_bullet('仪表盘:12 项核心指标卡片 (用户/作品/文件/存储/OCR/推送/关注/提醒)')
add_bullet('用户管理:表格 + 搜索 + 启用/禁用 + 角色变更 + 密码重置')
add_bullet('文件管理:表格 + MIME 类型筛选 + 统计')
add_bullet('画廊/小说管理:表格 + 搜索')
add_bullet('OCR 任务管理:状态筛选 + 重试')
add_bullet('推送管理:设备列表 + 测试推送')
add_bullet('审计日志:管理员操作记录')
add_bullet('系统健康:数据库/存储/版本信息 JSON 展示')
# ---- 3.5 ----
add_heading('3.5 插件系统功能', 2)
add_para('插件系统是桌面端可扩展内容源的核心架构:', bold=True)
add_bullet('统一接口:BasePlugin ABC 定义 parse() / download() / can_handle() / get_headers()')
add_bullet('自动发现:PluginManager 扫描 plugins/ 目录,通过 plugin_class 属性加载')
add_bullet('热重载:支持运行时加载/卸载/重载插件')
add_bullet('配置持久化:每个插件的 get_config_schema() / load_config() / save_config()')
add_bullet('骨架生成:PluginGenerator 基于 Jinja2 模板快速生成新插件')
add_bullet('事件钩子:before_load / after_load 等生命周期回调')
# ---- 3.6 ----
add_heading('3.6 Legado 在线书源引擎', 2)
add_para('移动端集成了完整的 Legado 兼容书源引擎(Legado 是 Android 平台最流行的开源阅读器),'
'支持数千个社区维护的书源规则 JSON。引擎核心能力:', bold=True)
add_table(
['功能', '实现方式', '状态'],
[
['搜索规则 (ruleSearch)', 'URL 模板 + CSS/JSON/Regex 选择器 + 12 种占位符', '✅ 完整'],
['详情规则 (ruleBookInfo)', '从详情页提取书名/作者/封面/简介/目录URL', '✅ 完整'],
['目录规则 (ruleToc)', '分页加载 + 章节识别器回退 + 正序/倒序', '✅ 完整'],
['正文规则 (ruleContent)', '文本提取 / 图片提取 + JS 脚本执行', '✅ 完整'],
['链式语法 (@tag/@src/@text)', '8 级管道执行器', '✅ 已实现'],
['净化替换 (##/###)', '正则替换 + 删除', '✅ 已实现'],
['备选/拼接 (||/&&)', '多规则备选 + 串联拼接', '✅ 已实现'],
['JS 规则 (@js/<js>)', 'QuickJS 引擎 + JS 变量特判', '✅ 已实现'],
['上下文变量 (@put/@get)', '规则内传值 + {{$.key}} 模板替换', '✅ 已实现'],
['编码处理', 'GBK/UTF-8 自动检测 + GBK URL 编码', '✅ 已实现'],
['HTTP 请求', 'GET/POST + 自定义 Headers/Cookie + 重定向跟踪', '✅ 已实现'],
['兼容度检测', '导入时自动分析规则语法 + UI 标签', '✅ 已实现'],
]
)
doc.add_page_break()
# ============================================================
# 第四部分:使用手册
# ============================================================
add_heading('第四部分 使用手册', 1)
# ---- 4.1 ----
add_heading('4.1 桌面端使用指南', 2)
add_heading('4.1.1 安装与启动', 3)
add_bullet('运行 scripts/install_desktop_dependencies.bat 安装 Python 依赖')
add_bullet('运行 scripts/install_playwright_browsers.bat 安装浏览器自动化环境')
add_bullet('执行 python main.py 启动桌面端 GUI')
add_bullet('或运行 scripts/build_desktop_exe.bat 打包为独立 EXE 文件')
add_heading('4.1.2 配置认证', 3)
add_para('Pixiv 认证(二选一):')
add_bullet('方式一:从浏览器导出 Cookies (推荐使用 Get cookies.txt 扩展),粘贴到认证卡片')
add_bullet('方式二:输入 Pixiv 用户名和密码,点击登录')
add_para('其他平台认证:', bold=True)
add_bullet('X/Twitter:在插件面板中启动交互式登录,在弹出浏览器中手动登录')
add_bullet('小红书:同上,启动交互式登录')
add_bullet('AO3:在配置中粘贴 AO3 登录后的 Cookie')
add_heading('4.1.3 下载流程', 3)
add_para('步骤 1:选择平台 — 通过顶部下拉菜单选择 Pixiv / X / 小红书 / 笔趣阁 / 插件自动检测')
add_para('步骤 2:输入目标 — 支持多种格式:')
add_bullet('Pixiv:作品 URL、作者 URL、作品 ID、关键词 (需以 # 开头)')
add_bullet('X:推文 URL、用户主页 URL、搜索关键词')
add_bullet('小红书:笔记 URL、搜索关键词')
add_bullet('笔趣阁:书名、作者、书籍 URL、章节 URL')
add_bullet('批量模式:多行输入,每行一个目标,支持逗号分隔')
add_para('步骤 3:配置选项 — 设置下载路径、代理、并发数、重试次数等')
add_para('步骤 4:开始下载 — 点击"开始"按钮,观察进度条和日志输出')
add_heading('4.1.4 云端同步', 3)
add_bullet('在"云同步"卡片中点击"登录/注册"')
add_bullet('输入云端服务器地址 (默认 http://api.kunkunxiaomao.top:8000)')
add_bullet('登录后,每次下载完成的内容会自动上传到云端')
add_bullet('可在同步设置中开启/关闭自动同步')
add_heading('4.1.5 插件管理', 3)
add_bullet('通过 文件 → 插件管理 或底部插件面板进入')
add_bullet('支持导入新插件、创建插件骨架、重载插件、卸载插件')
# ---- 4.2 ----
add_heading('4.2 移动端 APP 使用指南', 2)
add_heading('4.2.1 安装', 3)
add_bullet('从 releases/ 目录获取 app-release.apk (约 67MB)')
add_bullet('在 Android 手机上安装,允许"安装未知来源应用"')
add_bullet('首次启动需授予通知权限和文件存储权限')
add_heading('4.2.2 登录与配置', 3)
add_bullet('启动 APP 后,在登录页输入用户名和密码 (需先在桌面端或管理后台注册)')
add_bullet('服务器地址默认为云端 API 地址,一般无需修改')
add_bullet('登录成功后进入主页,底部有 5 个标签页')
add_heading('4.2.3 浏览云库内容', 3)
add_bullet('发现 (Tab 0):查看统计数据和最近更新')
add_bullet('图片 (Tab 1):浏览云端插画,支持搜索和收藏筛选')
add_bullet('漫画 (Tab 2):浏览云端漫画,按系列分组,点击进入翻页阅读')
add_bullet('书架 (Tab 3):浏览云端小说,支持系列分组和继续阅读')
add_bullet('我的 (Tab 4):个人中心,包括收藏、提醒、书源管理')
add_heading('4.2.4 在线搜索与阅读 (Legado 书源)', 3)
add_para('导入书源:', bold=True)
add_bullet('进入"我的" → "书源管理"')
add_bullet('点击导入按钮,输入书源仓库 URL 或粘贴书源 JSON')
add_bullet('推荐使用 Legado 社区维护的书源仓库 (可在 GitHub 搜索 legado 书源)')
add_bullet('导入后可在书源列表中启用/禁用各个书源')
add_para('在线搜索:', bold=True)
add_bullet('在漫画或小说标签页中,点击搜索图标进入在线搜索页')
add_bullet('输入书名/作者,可选择漫画或小说模式')
add_bullet('搜索结果分为"我的云库"和"在线源"两个区域')
add_bullet('在线源结果点击后进入书籍详情页')
add_para('在线阅读:', bold=True)
add_bullet('详情页上半部分展示书籍信息 (封面/书名/作者/简介)')
add_bullet('详情页下半部分展示章节目录 (支持正序/倒序切换)')
add_bullet('点击章节进入阅读器,支持上一章/下一章/目录导航')
add_bullet('阅读记录自动保存,下次进入详情页显示"继续阅读"')
add_bullet('可将在线内容保存到云端书架')
# ---- 4.3 ----
add_heading('4.3 管理后台使用指南', 2)
add_heading('4.3.1 访问', 3)
add_bullet('管理后台部署在云端服务器上,通常与 API 同域名')
add_bullet('访问 http://<服务器地址>/admin 进入后台')
add_heading('4.3.2 用户面板', 3)
add_bullet('登录后默认进入用户面板首页 (仪表盘)')
add_bullet('左侧导航可浏览图片、漫画、小说、提醒')
add_bullet('漫画和小说支持系列分组查看和章节阅读')
add_heading('4.3.3 管理员面板', 3)
add_bullet('如果账号具有 ADMIN 或 SUPER_ADMIN 角色,左侧会出现"管理面板"链接')
add_bullet('管理员仪表盘展示全部用户的聚合统计数据')
add_bullet('用户管理:可搜索、启用/禁用用户、修改角色')
add_bullet('系统健康:查看数据库连接、存储状态')
add_bullet('审计日志:追踪所有管理员操作')
add_heading('4.3.4 创建管理员账号', 3)
add_bullet('在服务器上执行:python -m sakura_cloud.scripts.create_admin --username admin --email admin@example.com --password YourPassword')
add_bullet('该账号将被赋予 SUPER_ADMIN 角色')
add_bullet('后续可通过管理后台上创建更多管理员')
# ---- 4.4 ----
add_heading('4.4 云端部署指南', 2)
add_heading('4.4.1 环境要求', 3)
add_bullet('Python 3.11+')
add_bullet('PostgreSQL 15+')
add_bullet('Redis (可选,用于未来扩展)')
add_heading('4.4.2 部署步骤', 3)
add_bullet('步骤 1:克隆项目到服务器')
add_bullet('步骤 2:安装 Python 依赖:pip install -r sakura_cloud/requirements.txt')
add_bullet('步骤 3:启动依赖服务:docker-compose up -d (启动 PostgreSQL + Redis)')
add_bullet('步骤 4:配置环境变量:复制 .env.cloud.example 为 .env.cloud 并填写生产环境配置')
add_bullet('步骤 5:初始化数据库:python -m sakura_cloud.scripts.init_db')
add_bullet('步骤 6:运行数据库迁移:alembic upgrade head')
add_bullet('步骤 7:创建管理员:python -m sakura_cloud.scripts.create_admin --username admin --email admin@example.com --password YOUR_PASSWORD')
add_bullet('步骤 8:启动服务:uvicorn sakura_cloud.main:app --host 0.0.0.0 --port 8000')
add_bullet('步骤 9 (可选):配置 Nginx 反向代理 + 管理后台静态文件部署')
add_heading('4.4.3 生产环境注意事项', 3)
add_bullet('务必修改 JWT_SECRET (默认值仅用于开发)')
add_bullet('务必修改数据库密码 (默认 sakura/sakura)')
add_bullet('设置 SAKURA_ENV=production 启用生产安全检查')
add_bullet('建议配置 HTTPS (Nginx + Let\'s Encrypt)')
add_bullet('建议配置防火墙,仅开放 80/443 端口')
# ---- 4.5 ----
add_heading('4.5 常见问题 (FAQ)', 2)
add_para('Q: 桌面端下载 Pixiv 时提示"认证失败"?', bold=True)
add_para('A: Cookie 可能已过期。重新从浏览器导出 Cookie,或使用密码登录方式。建议使用隐私窗口登录 Pixiv 后导出 Cookie。')
add_para('Q: 移动端搜索在线书源返回空结果?', bold=True)
add_para('A: 检查是否已导入并启用书源。进入"书源管理"确认至少有一个已启用的书源。部分书源可能需要特定网络环境。')
add_para('Q: 在线漫画阅读提示"这一章还没有找到漫画页面"?', bold=True)
add_para('A: 该书源的正文规则可能使用了不被支持的语法。尝试更换其他书源。该问题在最新版本中已通过 JS 特判和 rawHtml 兜底扫描大幅改善。')
add_para('Q: 云端同步失败?', bold=True)
add_para('A: 检查网络连接和服务器地址配置。确认桌面端已正确登录云端账号。失败的内容会自动进入重试队列。')
add_para('Q: 管理后台显示"详情数据由现有 API 按需加载"而不显示内容?', bold=True)
add_para('A: 这是早期版本的占位问题,最新版本已修复。请重新构建管理后台前端:cd sakura_admin_web && npm run build。')
add_para('Q: 如何添加新的内容源插件?', bold=True)
add_para('A: 在桌面端的插件管理面板中点击"创建插件",输入名称和模板信息即可生成插件骨架。实现 BasePlugin 的 parse() 和 download() 方法即可。')
doc.add_page_break()
# ============================================================
# 第五部分:三端特点与对比
# ============================================================
add_heading('第五部分 三端特点与对比', 1)
# ---- 5.1 ----
add_heading('5.1 桌面端特点', 2)
add_para('定位:内容采集和管理中心', bold=True)
add_heading('优势', 3)
add_bullet('强大的下载能力:支持 5 大内容平台,批量下载,自动重试,代理轮换')
add_bullet('完善的本地管理:SQLite 数据库 + 画廊 Web 界面 + 缩略图缓存 + OCR 索引')
add_bullet('可扩展插件系统:ABC 基类 + 自动发现 + 热重载 + 骨架生成')
add_bullet('反爬虫能力:Playwright 浏览器自动化 + 代理池 + 指纹管理 + 行为模拟')
add_bullet('任务队列保障:SQLite 持久化 + 断点续传 + 失败重试 + 并发控制')
add_bullet('云端同步集成:自动上传 + 关注同步 + 重试队列')
add_heading('局限性', 3)
add_bullet('仅支持 Windows 平台 (CustomTkinter 限制)')
add_bullet('需要 Python 运行环境或较大的 EXE 打包文件')
add_bullet('部分平台 (X/小红书) 需要安装 Chromium 浏览器')
add_bullet('不支持在线阅读 (需要移动端或 Web 管理后台)')
add_heading('技术亮点', 3)
add_bullet('CustomTkinter 现代 UI:粉色主题、卡片式布局、实时进度条、线程安全 UI 更新')
add_bullet('SQLite 数据层:10+ 表、触发器、索引、全文搜索 (FTS)')
add_bullet('内容寻址:SHA256 去重 + 路径规范化')
add_bullet('插件市场架构:预留 PluginMarketClient 接口,未来支持在线插件商店')
# ---- 5.2 ----
add_heading('5.2 移动端特点', 2)
add_para('定位:跨设备阅读和通知中心', bold=True)
add_heading('优势', 3)
add_bullet('双内容来源:云端个人库 + Legado 在线书源 (数千个社区维护的网站规则)')
add_bullet('完整的在线阅读体验:漫画 PageView 翻页、小说分页阅读、字体缩放、阅读记录')
add_bullet('Legado 规则引擎:8 级管道执行器支持 CSS/JSON/Regex/JS 四种规则 + 链式语法')
add_bullet('书源兼容度检测:导入时自动分析,UI 标签显示 (完全兼容/需要JS/需要POST 等)')
add_bullet('GBK 编码支持:中国大陆网站常用编码的自动检测和转换')
add_bullet('FCM 推送通知:创作者更新提醒 + 定时摘要')
add_bullet('离线友好:图片缓存 + 阅读记录持久化')
add_bullet('粉色 Material 3 主题:统一的品牌视觉')
add_heading('局限性', 3)
add_bullet('仅支持 Android 平台')
add_bullet('需要稳定的网络连接访问云端内容')
add_bullet('在线书源依赖第三方网站稳定性')
add_bullet('不支持内容下载到本地 (依赖云端同步)')
add_heading('技术亮点', 3)
add_bullet('Riverpod 状态管理:Provider 依赖注入 + ChangeNotifier + 自动释放')
add_bullet('Legado 规则执行器:8 级管道 (Tag → Text → Attr → Index → Fallback → && → 净化 → JS)')
add_bullet('QuickJS 集成:flutter_js 支持 @js/<js> 规则,JS 特判覆盖常见漫画解密模式')
add_bullet('三级导航流程:搜索 → 书籍详情(BookInfo+TOC合并) → 章节阅读器')
add_bullet('会话级缓存:BookInfo / TOC / Chapter 三级内存缓存,减少重复请求')
add_bullet('Dio 响应拦截:ResponseType.bytes + 编码检测 + GBK 解码')
# ---- 5.3 ----
add_heading('5.3 管理后台特点', 2)
add_para('定位:数据管理和系统运维面板', bold=True)
add_heading('优势', 3)
add_bullet('完整的管理功能:用户管理、内容管理、文件管理、审计日志')
add_bullet('漫画系列分组:自动按系列 ID 或标题智能分组 + 封面展示 + 章节排序')
add_bullet('小说系列浏览:系列级目录 + 在线正文阅读')
add_bullet('系统监控:仪表盘统计、系统健康检查、OCR 任务管理、推送管理')
add_bullet('安全设计:JWT Token 刷新 + 角色权限控制 + 审计日志 + 生产环境安全检查')
add_bullet('响应式布局:适配桌面和移动端浏览器')
add_bullet('TypeScript 类型安全:Vue 3 + TypeScript + Axios 拦截器')
add_heading('局限性', 3)
add_bullet('需要独立构建和部署 (Vite build → 静态文件 + Nginx)')
add_bullet('不支持内容上传和下载 (需要桌面端)')
add_bullet('漫画/小说查看功能不如移动端 APP 丰富')
add_heading('技术亮点', 3)
add_bullet('Vue Router 路由守卫:自动 Token 刷新、角色检测、登录重定向')
add_bullet('漫画系列缓存:客户端 buildMangaSeriesGroups() 智能分组算法')
add_bullet('无 UI 框架依赖:手写 CSS 响应式布局 + 粉色品牌色系')
add_bullet('SPA 嵌入 FastAPI:Vite 构建产物直接由 FastAPI 静态文件服务托管')
# ---- 5.4 ----
add_heading('5.4 三端对比表', 2)
add_table(
['特性', '桌面端 (Windows)', '移动端 (Android)', '管理后台 (Web)'],
[
['技术栈', 'Python + CustomTkinter', 'Flutter + Riverpod', 'Vue 3 + TypeScript + Vite'],
['数据库', 'SQLite (本地)', '无 (依赖云端API)', '无 (依赖云端API)'],
['内容下载', '✅ 5 大平台完整支持', '❌', '❌'],
['批量下载', '✅ 多行输入 + 任务队列', '❌', '❌'],
['云端同步', '✅ 自动上传', '✅ 浏览云库', '✅ 浏览云库'],
['云库浏览', '✅ 本地画廊 Web 界面', '✅ 完整的画廊/书架', '✅ 列表 + 详情'],
['在线书源搜索', '✅ (笔趣阁)', '✅ Legado 引擎 (数千书源)', '❌'],
['在线阅读', '❌', '✅ 漫画 + 小说阅读器', '✅ 基础阅读'],
['阅读记录', '❌', '✅ 自动保存 + 继续阅读', '❌'],
['JS 规则执行', '❌', '✅ QuickJS 引擎', '❌'],
['推送通知', '❌', '✅ FCM 推送', '❌'],
['代理支持', '✅ HTTP 代理池', '❌', '❌'],
['反爬虫', '✅ Playwright + 指纹轮换', '❌', '❌'],
['用户管理', '❌', '❌', '✅ 完整 CRUD + 角色管理'],
['审计日志', '❌', '❌', '✅ 管理员操作记录'],
['系统监控', '❌', '❌', '✅ 仪表盘 + 健康检查'],
['插件扩展', '✅ ABC 插件系统', '✅ Legado 书源导入', '❌'],
['离线使用', '✅ SQLite 本地库', '部分 (缓存)', '❌'],
]
)
doc.add_page_break()
# ============================================================
# 附录
# ============================================================
add_heading('附录 关键文件索引与技术参考', 1)
add_heading('A.1 桌面端关键文件', 2)
add_table(
['文件', '行数', '说明'],
[
['main.py', '~10', '桌面端入口'],
['pixiv_app/gui/app.py', '2707', '主 GUI 窗口'],
['pixiv_app/core/downloader.py', '~1000', 'Pixiv 下载引擎'],
['pixiv_app/core/library.py', '~800', 'SQLite 数据层'],
['pixiv_app/core/gallery_service.py', '~800', '本地画廊服务'],
['pixiv_app/core/cloud_sync.py', '~250', '云端同步'],
['pixiv_app/core/plugin/base.py', '~80', '插件基类'],
['pixiv_app/core/plugin/manager.py', '~200', '插件管理器'],
['pixiv_app/tasks/queue.py', '~250', 'SQLite 任务队列'],
]
)
add_heading('A.2 云端关键文件', 2)
add_table(
['文件', '说明'],
[
['sakura_cloud/main.py', 'FastAPI 应用工厂 + 生命周期管理'],
['sakura_cloud/api/v1/router.py', 'API 路由聚合 (14 个端点模块)'],
['sakura_cloud/api/v1/endpoints/gallery.py', '画廊 API (25+ 端点)'],
['sakura_cloud/api/v1/endpoints/novels.py', '小说 API (15+ 端点)'],
['sakura_cloud/api/v1/endpoints/admin.py', '管理员 API (20+ 端点)'],
['sakura_cloud/models/artwork.py', 'Artwork 数据模型 + 12 个复合索引'],
['sakura_cloud/core/config.py', 'Settings (Pydantic) — 所有配置项'],
['sakura_cloud/core/security.py', 'JWT 令牌 + 密码哈希'],
['sakura_cloud/services/storage.py', '分块上传 + SHA256 去重'],
['sakura_cloud/migrations/', '12 个 Alembic 数据库迁移版本'],
]
)
add_heading('A.3 移动端关键文件', 2)
add_table(
['文件', '行数', '说明'],
[
['lib/main.dart', '~20', '应用入口 + ProviderScope 包装'],
['lib/src/app.dart', '~80', 'Material 3 主题 + 全局配置'],
['lib/src/core/legado_engine.dart', '956', 'Legado 搜索引擎 — 搜索/详情/目录/内容'],
['lib/src/core/legado_rule_executor.dart', '~200', '8 级规则执行器'],
['lib/src/core/legado_rule_parser.dart', '262', 'CSS/JSON/Regex 规则解析器'],
['lib/src/core/source_manager.dart', '368', '书源生命周期管理'],
['lib/src/core/unified_search.dart', '173', '云库 + 在线源统一搜索'],
['lib/src/pages/explore_page.dart', '503', '在线搜索页'],
['lib/src/pages/online_book_detail_page.dart', '338', '在线书籍详情 (BookInfo+TOC)'],
['lib/src/pages/online_manga_reader_page.dart', '208', '漫画阅读器'],
['lib/src/pages/online_novel_reader_page.dart', '195', '小说阅读器'],
]
)
add_heading('A.4 管理后台关键文件', 2)
add_table(
['文件', '说明'],
[
['src/router/index.ts', '25+ 路由定义 + 认证守卫'],
['src/api/http.ts', 'Axios 客户端 + Token 刷新拦截器'],
['src/stores/auth.ts', '认证状态 (login/register/logout/loadMe)'],
['src/stores/seriesCache.ts', '漫画系列分组缓存算法'],
['src/views/app/AppLayout.vue', '用户面板侧边栏布局'],
['src/views/app/UserListPage.vue', '通用列表页 (画廊/漫画/小说/提醒)'],
['src/views/app/UserChapterListPage.vue', '漫画/小说系列章节列表'],
['src/views/admin/AdminDashboard.vue', '管理员仪表盘 (12 项指标)'],
['src/views/admin/AdminTablePage.vue', '通用管理表格'],
['src/views/admin/AdminUserDetail.vue', '用户管理详情 (角色/密码)'],
]
)
add_heading('A.5 文档索引', 2)
add_table(
['文档', '内容'],
[
['项目方案书.md', '原始项目方案设计'],
['Sakura_Downloader_完整文档.md', '项目完整技术文档'],
['在线搜索与阅读-源码架构总结.md', '在线搜索和阅读流程的源码级总结'],
['Legado规则引擎重构-分阶段实施方案.md', '8 阶段规则引擎重构方案'],
['在线搜索-书本章节导航-完整解决方案.md', '搜索→详情→目录→阅读流程方案'],
['书源在线搜索-问题分析与改进方案.md', '桌面端+移动端 12 个具体 Bug 分析'],
['Web端详情加载与手机端搜索优化方案.md', 'Web 端和移动端性能优化'],
['APP端问题分析与解决方案.md', 'APP 端问题排查和修复方案'],
['代码审计报告.md', '代码质量审计'],
]
)
add_heading('A.6 技术栈速查表', 2)
add_table(
['类别', '桌面端', '云端', '移动端', '管理后台'],
[
['语言', 'Python 3.8+', 'Python 3.11+', 'Dart 3.12', 'TypeScript 5.7'],
['框架', 'CustomTkinter', 'FastAPI', 'Flutter 3.44', 'Vue 3.5'],
['构建', 'PyInstaller', 'uvicorn', 'Gradle', 'Vite 6'],
['数据库', 'SQLite', 'PostgreSQL 15', 'SharedPreferences', 'N/A'],
['ORM', '原始 SQL', 'SQLAlchemy 2.0', 'N/A', 'N/A'],
['HTTP', 'requests/httpx', '内置 (Starlette)', 'Dio 5.7', 'Axios 1.7'],
['认证', 'Cookie/Session', 'JWT HS256', 'Bearer Token', 'Bearer Token'],
['状态管理', '-', '-', 'Riverpod 2.6', 'sessionStorage'],
['UI 组件', 'CustomTkinter Widgets', '-', 'Material 3 Widgets', '手写 CSS'],
['自动化', 'Playwright', '-', '-', '-'],
['JS 引擎', '-', '-', 'flutter_js (QuickJS)', '-'],
['推送', '-', 'Firebase Admin', 'Firebase Msg', '-'],
['OCR', 'PaddleOCR', 'PaddleOCR', '-', '-'],
]
)
# ---- Save ----
output_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'docs', 'Sakura_Downloader_完整项目文档.docx')
doc.save(output_path)
print(f'Document saved to: {output_path}')
print(f'File size: {os.path.getsize(output_path) / 1024:.1f} KB')