Files
SakuraHub/产品说明文档.md
T
2026-11-16 20:45:22 +08:00

162 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 樱云下载器(Sakura Downloader)产品说明文档
版本:V1.0
更新日期:2026-11-05
文档类型:产品说明
---
## 1. 产品概述
### 1.1 产品名称
樱云下载器(Sakura Downloader)
### 1.2 产品定位
一款面向个人创作者与插画/漫画/小说爱好者的**个人媒体采集、本地图库管理与跨设备云同步系统**。
产品覆盖从「内容采集 → 本地整理 → 云端存储 → 多端阅读」的完整链路,解决用户在 Pixiv、X(Twitter)等平台收藏作品后"散落各处、难以管理、换设备看不了"的问题。
### 1.3 一句话描述
桌面端是"采集与整理中枢",云端是"数据与账号中心",手机端是"个人阅读器"。
---
## 2. 产品架构
| 端 | 载体 | 角色 |
|----|------|------|
| Windows 桌面端 | `sakuradownloader.exe` | 登录、抓取、下载、本地图库管理、云同步 |
| Sakura Cloud 云端 | FastAPI 服务 | 账号体系、媒体存储、关注与提醒数据 |
| Android 移动端 | `app-release.apk` | 跨设备浏览、阅读、收藏、提醒查看 |
数据流向:
```
Pixiv / X 平台
│ (桌面端抓取下载)
▼
本地图库(SQLite + 本地文件)
│ (云同步上传)
▼
Sakura Cloud(媒体 + 账号 + 关注/提醒数据)
│ (同账号拉取)
▼
Android 客户端(图片 / 漫画 / 小说 / 收藏 / 提醒)
```
---
## 3. 核心功能
### 3.1 桌面端(采集与整理中枢)
#### 3.1.1 账号登录
- 支持 **Cookie 登录**(推荐,稳定)与 **账号密码登录** 两种方式。
- 支持导入 `cookies.txt` / `json` 格式的会话文件,可一键检测与保存会话。
#### 3.1.2 内容抓取下载
通过「平台 + 模式 + 目标」三项配置发起抓取:
| 模式 | 目标输入 |
|------|----------|
| 作者全部作品 | 作者 ID 或任意该作者的作品链接(自动反查作者) |
| 作品 / 漫画 | 作品 ID 或作品链接 |
| 文章 / 小说 | 小说 ID、小说链接或小说系列链接 |
| 关键词 | 关键词(先搜索后下载) |
下载内容自动进入本地图库并写入数据库。
#### 3.1.3 缩略图墙(本地图库)
程序在本机启动本地服务(默认 `http://127.0.0.1:8765`,端口占用时自动切换 8766/8767),在浏览器中提供:
- 本地图片/漫画浏览(默认不含小说)
- 标题、作者、简介搜索;按标签筛选
- 作者主页、收藏功能
- 「关注同步」页:维护 Pixiv 关注作者、导入 Cookie、一键同步关注作者新作品
- 「X 关注」页:手动添加 X 用户名并同步时间线新动态
#### 3.1.4 云同步
- 勾选启用 Sakura Cloud 同步,登录/注册云端账号后自动保存凭证。
- 登录成功后,新下载内容**自动上传云端**,手机端同账号即可查看。
- 关注作者的新作品会写入云端 follow / alert 记录,作为提醒数据来源。
### 3.2 云端(数据与账号中心)
- 账号注册/登录(JWT 鉴权)、媒体存储与访问。
- 关注(follow)与更新 alert 数据管理。
- **每日提醒摘要**:每 5 分钟检查一次,对已开启提醒的用户,将当日未读更新汇总为一条应用内"每日摘要提醒",同一天不重复生成。
### 3.3 Android 端(个人阅读器)
| 页签 | 功能 |
|------|------|
| 发现 | 最近浏览的图片/漫画/小说、更新提醒摘要展示 |
| 图片 | 云端插画列表、详情、收藏、下载、编辑、删除 |
| 漫画 | 按漫画分组进入,整组连续浏览、整组下载 |
| 书架 | 三列彩色方块,系列小说按书名归档,章节选择,按阅读记录排序 |
| 我的 | 用户资料、云端空间占用、收藏、每日提醒设置、退出登录 |
#### 小说阅读器
- 自动分页、进度记忆、收藏/取消收藏
- 当前页翻译、原文/译文切换
- 字体大小、行高、背景色、章节切换等阅读设置
- 系列小说章节列表直接切换
#### 每日更新提醒
- 开关位于「我的」页,可设置提醒时间(默认时区 Asia/Shanghai)。
- 形式为**云端汇总的应用内提醒**,展示在「发现」页"更新提醒"区域,不是系统级推送通知。
- 生效前提:桌面端已维护关注作者并启用云同步,双端使用同一账号,且关注作者有新内容进入云端。
---
## 4. 技术栈
| 模块 | 技术 |
|------|------|
| 桌面端 | Python 3.8+、CustomTkinter、SQLite、Playwright(X 插件) |
| 云端 | FastAPI、PostgreSQL、JWT、Docker Compose、Alembic |
| 移动端 | Flutter、Riverpod、Dio |
---
## 5. 分发成品
| 文件 | 说明 | 大小(约) |
|------|------|------------|
| `releases/sakuradownloader.exe` | Windows 桌面端,双击即用 | ~68 MB |
| `releases/app-release.apk` | Android 客户端(调试签名,适合自测) | ~54 MB |
---
## 6. 用户价值
1. **集中管理**:Pixiv / X 的插画、漫画、小说统一采集入库,告别散落收藏。
2. **本地资产**:下载内容落在本地图库,带搜索、标签、作者、收藏体系。
3. **多端同步**:桌面采集,手机阅读,进度、收藏、提醒全端同步。
4. **追更提醒**:关注作者有新作,每日定时汇总提醒,不再手动刷动态。
5. **离线阅读**:小说自动分页、进度记忆,适合长期追更连载。
---
## 7. 已知限制
- Android APK 当前为**调试签名**,仅供个人测试与自用,不宜正式上架分发。
- 「账号密码登录」在遇到 Pixiv 额外验证、二步验证或风控时成功率较低,推荐 Cookie 登录。
- 每日提醒为云端应用内摘要提醒,非手机系统级推送,不会弹系统通知。
- 提醒数据链路目前主要落在 Pixiv 侧;X 关注已有同步入口,判新依赖作者时间线,稳定性相对更好,但整体仍建议以"Pixiv / X 关注作者更新摘要"的预期使用。
- 使用 X 插件前需安装 Playwright Chromium(见 `项目文件/BUILD.md`)。
- 会话与图库数据默认保存在 `%LOCALAPPDATA%\PixivDownloader`(打包版)。
---
## 8. 配套文档
| 文档 | 面向读者 |
|------|----------|
| [使用说明-桌面版与安卓版.md](使用说明-桌面版与安卓版.md) | 终端用户:登录、下载、云同步、手机端操作 |
| [docs/项目功能交付书.md](docs/项目功能交付书.md) | 产品 / 验收:功能模块、架构、API、代码索引 |
| [docs/项目文档.md](docs/项目文档.md) | 开发者:环境、目录、构建、部署 |
| [项目文件/BUILD.md](项目文件/BUILD.md) | 开发者:EXE / APK 打包细节与排错 |
| [README.md](README.md) | 项目总览与快速开始 |