1043 lines
54 KiB
Python
1043 lines
54 KiB
Python
#!/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')
|