Files
SakuraHub/产品说明文档.md
T

161 lines
6.6 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 樱云下载器(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) | 项目总览与快速开始 |