Files
SakuraHub/docs/APP端问题分析与解决方案.md
T
2026-11-16 20:45:22 +08:00

493 lines
20 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.
# APP 端问题分析与解决方案
> 更新日期:2026-06-14
> 范围:Sakura Mobile (Flutter) + Sakura Cloud (FastAPI 后端) + Sakura Downloader (Python 桌面端)
> 说明:本文档仅提供问题分析和修改方案,不包含实际代码改动。
---
## 问题一:APP 莫名其妙跳转到 "dakura" 用户
### 问题现象
APP 在使用过程中会突然切换到 "dakura" 用户身份,导致看到的是其他用户的数据而并非自己的内容。
### 根因分析
经过对全部代码的排查,问题出在 **Session 持久化缺少用户隔离机制**。涉及以下关键位置:
#### 1. 移动端 Session 存储无用户绑定 (`sakura_mobile/lib/src/core/session.dart`)
**文件位置:** `sakura_mobile/lib/src/core/session.dart` 第 44-52 行
```dart
static const _baseUrlKey = 'sakura.baseUrl';
static const _accessTokenKey = 'sakura.accessToken';
Future<void> _load() async {
final prefs = await SharedPreferences.getInstance();
state = SessionState(
baseUrl: prefs.getString(_baseUrlKey) ?? defaultCloudApi,
accessToken: prefs.getString(_accessTokenKey) ?? '',
);
```
**问题:** `SharedPreferences` 使用固定 key `sakura.accessToken` 存储 token,不绑定任何用户标识。当存在以下情况时会发生串号:
- 同一设备上先后登录过不同账号(如 "dakura" 和当前用户)
- SharedPreferences 中的旧 token 未完全清除
- App 从后台恢复时读取了旧的/缓存的 token
- 多进程/多任务环境下 SharedPreferences 跨进程同步延迟
#### 2. 登录流程缺少旧 Session 清理 (`sakura_mobile/lib/src/core/session.dart` 第 70-86 行)
```dart
Future<void> login(String usernameOrEmail, String password) async {
state = state.copyWith(loading: true, error: null);
try {
final api = SakuraApiClient(baseUrl: state.baseUrl);
final tokens = await api.login(usernameOrEmail, password);
final accessToken = tokens['access_token']?.toString() ?? '';
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_accessTokenKey, accessToken);
```
**问题:** 登录时直接覆盖 `_accessTokenKey`,但如果 SharedPreferences 写入失败或未完全刷盘,旧 token 仍然存在。没有先清除旧 token 再写入新 token 的原子操作。
#### 3. Web 端使用 sessionStorage 同样缺少隔离 (`sakura_admin_web/src/stores/session.ts` 第 15-30 行)
```typescript
const ACCESS_KEY = "sakura_access_token";
const REFRESH_KEY = "sakura_refresh_token";
export const authState = reactive({
accessToken: sessionStorage.getItem(ACCESS_KEY) || "",
refreshToken: sessionStorage.getItem(REFRESH_KEY) || "",
user: null as CurrentUser | null,
loading: false
});
```
**问题:** sessionStorage 的 key 是固定的,同一浏览器不同标签页可能共享或冲突。
#### 4. 桌面端 Session 文件共享 (`pixiv_app/core/paths.py` 和 `pixiv_app/core/auth.py`)
Session 文件 `pixiv_app_session.json` 保存的是单一的 cookie 和 cloud_sync 配置,没有对应用户上下文。如果云端切换了用户但本地 session 文件未同步更新,可能导致不一致。
### 解决方案
#### 方案 A:Token 绑定用户名校验(推荐)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/session.dart` | 第 44-52 行 | 在 `_load()` 后调用 `/api/v1/users/me` 校验 token 归属用户 |
| `sakura_mobile/lib/src/core/session.dart` | 第 70-86 行 | `login()` 时先清除旧 token,写入后立即验证 |
| `sakura_mobile/lib/src/core/session.dart` | 新增方法 | 添加 `_validateAndFixSession()` 方法,对比登录用户名与 token 归属 |
**具体做法:**
1. 在 `SessionController._load()` 中,加载 token 后立即调用 `api.me()` 获取当前 token 对应的用户名
2. 将用户名也存入 SharedPreferences,key 使用 `sakura.username`
3. 每次 `_load()` 后比对 `sakura.username` 与 `me()` 返回的 username,不一致则清除旧 token 强制重新登录
4. `login()` 成功后立即存储用户名,防止与旧数据混淆
#### 方案 B:增加 Token 失效主动检测
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/api_client.dart` | 第 12-47 行 | 在 `SakuraApiClient` 中增加 401 拦截器 |
| `sakura_mobile/lib/src/core/session.dart` | 第 100-108 行 | `logout()` 时增加确认清理 SharedPreferences 全部 key |
**具体做法:**
1. 通过 Dio 拦截器全局捕获 401/403 响应,自动清除 token 并跳转登录页
2. 在 `logout()` 中不单删除 `_accessTokenKey`,同时清理所有 sakura 相关 key
3. 增加 `clearAllSakuraData()` 方法用于完全重置
#### 方案 C:服务端 Token 版本号机制
**修改位置:** 后端 `sakura_cloud/` (FastAPI) 相关认证模块
**具体做法:**
1. 在用户表增加 `token_version` 字段
2. 每次重新登录时 token_version +1
3. JWT payload 中嵌入 token_version
4. 验证 token 时比对版本号,旧版本 token 直接拒绝
5. 确保用户登出后旧 token 彻底失效
---
## 问题二:发现页查询过慢,需要加载缓冲或优化
### 问题现象
APP 打开"发现"页(FeedTab)时,整个页面长时间白屏/转圈,用户体验差。
### 根因分析
#### 1. 五个 API 串行阻塞全部内容 (`sakura_mobile/lib/src/pages/tabs/feed_tab.dart`)
**文件位置:** `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 20-26 行
```dart
return FutureBuilder<List<Object?>>(
future: Future.wait([
api.galleryStat(), // 统计总数
api.galleryFeed(mode: 'created', limit: 36), // 今日新增
api.galleryFeed(mode: 'recent', limit: 24), // 最近更新
api.recentNovels(limit: 12), // 最近小说
api.unreadAlerts(limit: 12), // 未读提醒
]),
```
**问题:**
- `Future.wait` 等待所有 5 个请求完成才渲染页面
- 任一接口慢(尤其是 `galleryStat()` 和 `galleryFeed()`),整个发现页都会卡住
- `galleryStat()` 可能后端做了全表 COUNT,数据量大时耗时数秒
#### 2. 后端 gallery/feed 查询可能缺少优化
**文件位置:** 后端 API(`sakura_cloud/` 目录下的 gallery/feed 路由)
`galleryFeed` 接口通常对应:
- `mode: 'created'` → 按创建时间排序的最近作品
- `mode: 'recent'` → 按更新时间排序
如果后端 SQL 查询缺少合适的复合索引,或者做了全表扫描 + JOIN 多表,在数据量上千条后就会明显变慢。典型慢查询模式:
```sql
-- 可能的慢查询(缺少索引或 JOIN 过多)
SELECT a.*, ar.name, tc.thumbnail_path, ...
FROM artworks a
LEFT JOIN artists ar ON ...
LEFT JOIN thumbnail_cache tc ON ...
LEFT JOIN artwork_files af ON ...
LEFT JOIN favorites fav ON ...
ORDER BY a.created_at DESC
LIMIT 36
```
**对比本地库查询** (`pixiv_app/core/gallery_service.py` 第 96-134 行) 同样有类似的多表 LEFT JOIN + GROUP BY + 复合搜索条件,这在 SQLite 上尤其慢:
```python
total = library.connection.execute(
f"SELECT COUNT(DISTINCT a.artwork_id) AS total FROM artworks a {joins} {where_sql}",
params,
).fetchone()["total"]
```
先 COUNT 再 SELECT,等于两次大查询。
#### 3. 图片缩略图同步加载阻塞渲染
**文件位置:** `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 385-389 行
```dart
CachedNetworkImage(
imageUrl: thumbUrl,
httpHeaders: api.authHeaders(),
fit: BoxFit.cover,
),
```
**问题:** 虽然使用了 `CachedNetworkImage` 做缓存,但如果后端 `thumbnail_url` 指向的是需要实时生成或大文件的原图,加载会很慢;且横向滚动的 `ListView` 会一次性构建多个图片 widget,造成网络拥塞。
### 解决方案
#### 方案 A:渐进式加载 + 骨架屏(推荐,前端改动最小)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 20-26 行 | 将 `Future.wait` 拆分为独立请求,每个区块独立加载 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 62-137 行 | 为每个 `_ArtworkStrip`、`_NovelStrip`、`_AlertStrip` 增加独立的 loading/skeleton 状态 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 新增组件 | 增加 `_SkeletonStrip` 骨架屏组件 |
**具体做法:**
1. 不再使用单个 `FutureBuilder` + `Future.wait`,改为每个 section 独立使用 `FutureBuilder`
2. 统计卡片(`_TodayUpdateCard` 和 `_StatCard`)优先加载
3. 各内容条(插画、漫画、小说、提醒)各自独立加载,失败的只影响自己
4. 加载中的条显示 shimmer 骨架屏而非空白
5. `galleryStat()` 如果慢,可设置 3 秒超时,超时则降级显示 "--"
#### 方案 B:后端增加 feed 缓存表(推荐,解决根本问题)
**修改位置:** 后端 `sakura_cloud/`
**具体做法:**
1. 新增 `feed_cache` 表:
```sql
CREATE TABLE feed_cache (
user_id UUID NOT NULL,
feed_type VARCHAR(32) NOT NULL, -- 'created', 'recent', 'stat'
payload_json JSONB NOT NULL,
generated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (user_id, feed_type)
);
```
2. 在每次上传新作品、同步关注的定时任务完成后,异步刷新 feed_cache
3. `/api/v1/gallery/feed` 和 `/api/v1/gallery/stat` 优先从 `feed_cache` 读取
4. 缓存有效期设为 5-10 分钟,过期后后台异步刷新,当前请求仍返回旧缓存
5. 如果缓存不存在,降级为直接查询(首次慢但后续快)
#### 方案 C:本地 SQLite 缓存 + 增量同步(移动端离线方案)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/core/api_client.dart` | 新增方法 | 增加本地缓存读写方法 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 第 20 行 | 优先读本地缓存,后台静默刷新 |
**具体做法:**
1. 移动端使用 `sqflite` 或 `drift` 建立轻量本地库
2. 发现页数据缓存到本地,设置 30 分钟有效期
3. 打开发现页时先展示缓存数据(秒开),同时后台请求新数据
4. 新数据到达后平滑替换(`AnimatedSwitcher` 已就位)
5. 支持下拉强制刷新(`RefreshIndicator` 已就位)
#### 方案 D:优化后端 gallery/feed 查询语句
**修改位置:** 后端 `sakura_cloud/api/v1/` 中 gallery/feed 相关路由
**具体做法:**
1. 分析慢查询日志,定位具体慢的 SQL
2. 为 `artworks` 表增加复合索引:
```sql
CREATE INDEX idx_artworks_user_created ON artworks(user_id, created_at DESC);
CREATE INDEX idx_artworks_user_updated ON artworks(user_id, updated_at DESC);
```
3. 将 COUNT + SELECT 两次查询合并为一次(用窗口函数或子查询)
4. 限制 `galleryStat()` 的统计精度,超过 10000 条时显示 "10000+"
5. 对缩略图 URL 确保使用 CDN 或 Nginx 静态文件服务,而非 Django/FastAPI 流式响应
---
## 问题三:提醒中心用户更新检测问题
### 问题现象
1. **最近提醒显示的并非实际关注的作者名字**,而是作者 ID 数字
2. **已关注的作者有更新但未检测到**,提醒中心未生成新提醒
### 根因分析
#### 1. 提醒标题使用 author_id 而非 author_name
**文件位置:** `pixiv_app/core/gallery_service.py` 第 588-613 行
```python
def _create_cloud_pixiv_update_alerts(self, artist_id: int, work_ids: list[int]) -> int:
...
for work_id in work_ids:
try:
manager.client.create_alert(
{
"platform": "pixiv",
"creator_id": str(int(artist_id)),
"title": f"Pixiv 作者 {int(artist_id)} 更新了作品 {int(work_id)}",
# ↑↑↑ 问题在这里:用的是 author_id 数字,而非 author name
"body": "你关注的 Pixiv 作者有新作品了",
...
}
)
```
**问题详解:**
- `_create_cloud_pixiv_update_alerts` 没有接收 `artist_name` 参数
- 调用它的 `sync_followed_artists`(第 505-586 行)虽然能从 `library` 查到作者信息,但没传给 alert 创建函数
- 导致提醒标题变成 "Pixiv 作者 123456 更新了作品 789012",用户看到的是一串数字
- 移动端 `reminder_center_page.dart` 直接展示 `alert['title']`,所以显示的是数字 ID
#### 2. 关注作者有更新但未检测到
**文件位置:** `pixiv_app/core/gallery_service.py` 第 505-586 行
```python
def sync_followed_artists(self, *, cookie, max_new_per_artist=20, download=True, save_root="Sakura_Downloads"):
...
for row in followed:
artist_id = int(row["artist_id"])
# 获取已存在的作品 ID
existing = {
int(item["artwork_id"])
for item in library.connection.execute(
"SELECT artwork_id FROM artworks WHERE artist_id = ? AND type IN ('illust', 'manga')",
(artist_id,),
).fetchall()
}
# 获取远程作品 ID
_, work_ids = fetch_user_work_ids(user_id=artist_id, cookie=cookie)
# 只取本地没有的
new_ids = [work_id for work_id in work_ids if work_id not in existing][:max_new_per_artist]
```
**问题详解:**
- `fetch_user_work_ids` 需要有效的 Pixiv Cookie,如果 Cookie 已过期,API 调用静默失败
- 对比逻辑只看 `existing` 中的 artwork_id,但如果作品之前下载失败、入库未完成,可能漏掉
- `mark_artist_synced(artist_id, error=str(exc))` 在异常时记录了错误但未区分错误类型(Cookie 过期 vs 网络错误 vs 限流)
- 没有"最近检查时间"的限流机制 —— 如果短时间内多次同步同一个作者,每次都做全量对比
#### 3. 检查完成后未更新 `last_checked_at`
**文件位置:** `pixiv_app/core/library.py` 第 592-603 行
```python
def mark_artist_synced(self, artist_id: int, *, error: str = "") -> None:
with self.connection:
self.connection.execute(
"""
INSERT INTO followed_artists (artist_id, enabled, last_synced_at, last_error)
VALUES (?, 1, CURRENT_TIMESTAMP, ?)
ON CONFLICT(artist_id) DO UPDATE SET
last_synced_at = CURRENT_TIMESTAMP,
last_error = excluded.last_error
""",
(artist_id, error),
)
```
**问题:** `last_synced_at` 只在本地 SQLite 更新,**没有同步到云端** follows 表的 `last_checked_at`。移动端提醒中心展示的是云端 follows 数据:
**文件位置:** `sakura_mobile/lib/src/pages/reminder_center_page.dart` 第 22-27 行
```dart
Future<_ReminderCenterData> _load() async {
final api = ref.read(apiClientProvider);
final results = await Future.wait<Object?>([
api.me(),
api.follows(enabled: true), // ← 从云端读取 follows
api.alerts(limit: 50), // ← 从云端读取 alerts
]);
```
**问题详解:**
- 移动端显示的 `last_checked_at` 来自云端 follows 表
- 桌面端 `_upsert_cloud_follow` 只更新了 creator 基本信息,**没有更新 `last_checked_at`**
- 所以云端看到的"最近检查"时间永远是旧的甚至为空
- 用户无法判断哪个作者实际上被检查过
#### 4. Alert 创建没有去重
**文件位置:** `pixiv_app/core/gallery_service.py` 第 588-613 行
```python
for work_id in work_ids:
try:
manager.client.create_alert({...})
created += 1
except Exception:
continue
```
**问题:**
- 每次同步都会为同一个 work_id 创建新的 alert
- 如果多次同步同一批作品,会产生大量重复提醒
- 没有检查 "这个 work_id 是否已经发过 alert"
### 解决方案
#### 方案 A:修复 Alert 标题——传入作者名(推荐,最小改动)
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 588 行 | `_create_cloud_pixiv_update_alerts` 增加 `artist_name` 参数 |
| `pixiv_app/core/gallery_service.py` | 第 562-565 行 | `sync_followed_artists` 传入作者名 |
| `pixiv_app/core/gallery_service.py` | 第 599 行 | 修改 title 使用作者名 |
**具体做法:**
在 `sync_followed_artists` 方法中,从 followed_artists 或 artists 表获取作者名:
```python
# 第 527-538 行之间,获取 followed 列表时同时获取 name
followed = library.connection.execute(
"SELECT fa.artist_id, COALESCE(NULLIF(fa.name,''), NULLIF(ar.name,''), '') AS name "
"FROM followed_artists fa "
"LEFT JOIN artists ar ON ar.artist_id = fa.artist_id "
"WHERE fa.enabled = 1 ORDER BY fa.artist_id"
).fetchall()
```
然后修改 `_create_cloud_pixiv_update_alerts` 签名:
```python
def _create_cloud_pixiv_update_alerts(
self, artist_id: int, work_ids: list[int], artist_name: str = ""
) -> int:
```
title 改为:
```python
"title": f"Pixiv 作者 {artist_name or str(artist_id)} 更新了 {len(work_ids)} 个新作品"
```
#### 方案 B:同步云端 follows 的检查状态
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 556-559 行 | `mark_artist_synced` 之后同步更新云端 follows 的 `last_checked_at` |
| `pixiv_app/core/cloud_sync.py` | 第 167-168 行 | `upsert_follow` 增加 `last_checked_at` 和 `latest_published_at` 字段 |
| `pixiv_app/core/gallery_service.py` | 第 415-447 行 | `_upsert_cloud_follow` 增加更新时间戳参数 |
**具体做法:**
1. 在 `_upsert_cloud_follow` 方法中增加 `last_checked_at` 和 `latest_published_at` 参数
2. 每次同步完一个作者后,调用 `_upsert_cloud_follow` 更新云端状态
3. 在云端 follows API 的 upsert 逻辑中接受并存储这些时间字段
4. 移动端 `reminder_center_page.dart` 中 `_FollowTile` 就能显示正确的"最近检查"时间
#### 方案 C:Alert 去重 & 按作者聚合
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `pixiv_app/core/gallery_service.py` | 第 588-613 行 | 重构 `_create_cloud_pixiv_update_alerts` 逻辑 |
| 后端 `sakura_cloud/api/v1/follows.py` | alert 创建路由 | 增加去重逻辑 |
**具体做法:**
1. 将每个作者的多个新作品合并为**一条聚合 alert**,而非每个作品一条
2. Alert 的 `source_id` 使用 `f"{artist_id}:{min(work_ids)}:{max(work_ids)}"` 生成唯一标识
3. 创建 alert 前先检查是否存在相似 alert(同一作者 + 同一天内)
4. 如果存在则更新而非新建
5. title 格式改为:`"你关注的 {作者名} 更新了 {N} 个新作品"`
#### 方案 D:增加关注作者更新状态页面
**修改位置:**
| 文件 | 行号 | 修改内容 |
|------|------|----------|
| `sakura_mobile/lib/src/pages/reminder_center_page.dart` | 第 350-371 行 | 已关注作者列表增加"手动检查更新"按钮 |
| 后端新增接口 | - | `POST /api/v1/follows/{follow_id}/check` 触发单作者更新检测 |
**具体做法:**
1. 在已关注作者列表中为每个作者增加状态标识:
- 🟢 最近 24h 内检查过
- 🟡 24h-7d 内检查过
- 🔴 超过 7 天未检查
2. 增加"手动检查"按钮,调用后端触发单个作者的更新检测
3. 检查完成后自动刷新提醒列表
---
## 总结优先级
| 优先级 | 问题 | 推荐方案 | 改动范围 | 预期效果 |
|--------|------|----------|----------|----------|
| P0 紧急 | 跳转到 dakura 用户 | 方案 A:Token 绑定用户名 | 移动端 session.dart | 根除串号问题 |
| P0 紧急 | Alert 显示数字而非作者名 | 方案 A:传入作者名 | gallery_service.py | 提醒可读 |
| P1 高 | 发现页加载慢 | 方案 A + B:渐进加载 + feed_cache | feed_tab.dart + 后端 | 首屏从 3-5s 降到 <1s |
| P1 高 | 关注作者未检测更新 | 方案 B:同步检查状态到云端 | gallery_service.py + cloud_sync.py | 状态准确可追溯 |
| P2 中 | Alert 重复创建 | 方案 C:去重 + 聚合 | gallery_service.py + 后端 | 减少重复提醒 |
| P2 中 | 查询性能优化 | 方案 D:SQL 索引 | 后端数据库 | 查询耗时降低 50%+ |