Files
SakuraHub/docs/Web端详情加载与手机端搜索优化方案.md
T
2026-11-16 20:45:22 +08:00

1246 lines
49 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.
# Web 端详情加载、手机端搜索与加载性能优化方案
> 更新日期:2026-06-15
> 范围:Sakura Admin Web (Vue.js) + Sakura Mobile (Flutter) + Sakura Cloud (FastAPI)
> 说明:本文档提供问题分析与优化方案,不包含实际代码改动。
---
## 目录
1. [管理员账号密码](#一管理员账号密码)
2. [Web 端详情数据按需加载问题](#二web-端详情数据按需加载问题)
3. [Web 端缺少漫画板块问题](#三web-端缺少漫画板块问题)
4. [Web 端列表加载性能问题](#四web-端列表加载性能问题)
5. [手机端搜索不到图书问题](#五手机端搜索不到图书问题)
6. [手机端加载过慢问题](#六手机端加载过慢问题)
7. [实施优先级与排期建议](#七实施优先级与排期建议)
---
## 一、管理员账号密码
### 1.1 现状
本项目**没有预设的默认管理员账号密码**。数据库初始化脚本(`sakura_cloud/scripts/init_db.py`)仅创建空表结构,不插入任何种子数据。
管理员账号需要**部署后手动创建**,使用后端提供的 CLI 脚本。
### 1.2 创建管理员账号的方法
**脚本位置:** `sakura_cloud/scripts/create_admin.py`
**使用方法:**
```bash
# 在后端服务器上执行(需在 sakura_cloud 可导入的环境下)
python -m sakura_cloud.scripts.create_admin \
--username admin \
--email admin@example.com \
--password YourPassword123
```
**参数说明:**
| 参数 | 必填 | 说明 |
|------|------|------|
| `--username` | 是 | 管理员用户名 |
| `--email` | 是 | 管理员邮箱 |
| `--password` | 否 | 密码(最少 8 位)。如不传,运行时会交互式提示输入(不显示在终端) |
**脚本逻辑:**
1. 检查是否已存在 `SUPER_ADMIN` 角色的用户
2. 如果数据库中没有匹配用户名/邮箱的用户 → 创建新的 SUPER_ADMIN
3. 如果已存在该用户但角色不是 SUPER_ADMIN,且已有其他 SUPER_ADMIN → 拒绝提升(防止越权)
4. 如果已存在该用户且尚无 SUPER_ADMIN → 将其提升为 SUPER_ADMIN 并更新密码
### 1.3 基础设施凭证(仅供参考,非管理员登录)
以下凭证出现在配置文件和 `docker-compose.yml` 中,但这些是**基础设施组件**的凭证,**不能用于 Web/APP 登录**:
| 组件 | 用户名 | 密码 | 用途 |
|------|--------|------|------|
| PostgreSQL | `sakura` | `sakura` | 数据库连接 |
| MinIO | `minioadmin` | `minioadmin` | 对象存储 |
| JWT Secret | - | `change-this-secret-in-production` | JWT 签名密钥(生产环境务必修改) |
> ⚠️ **安全提醒:** 以上均为默认值,生产部署前务必修改,特别是 JWT Secret 和数据库密码。
### 1.4 如果忘记了管理员密码
由于没有预设账号,如果忘记密码:
1. **方法一(推荐):** 重新运行 `create_admin.py` 脚本,指定相同的 `--username` 和 `--email`,输入新密码即可覆盖。
2. **方法二:** 直接在数据库中修改 `password_hash` 字段(需要先用 Python 生成 bcrypt/pbkdf2_sha256 哈希)。
3. **方法三:** 如果数据库中有其他管理员账号,可以用该账号登录后在管理后台重置密码。
---
## 二、Web 端详情数据按需加载问题
### 2.1 问题现象
在 Web 管理前端(`sakura_admin_web`)中,用户点击列表中的画廊(gallery)或小说(novels)项目后,跳转到详情页面,但页面只显示:
```
详情数据由现有 API 按需加载。
```
页面不会展示任何实际内容,用户无法看到作品详情。
### 2.2 根因分析
问题出在 **`UserDetailPage.vue` 是一个未实现的占位组件**,它从始至终没有发起任何 API 请求来获取详情数据。
#### 根因 1:`UserDetailPage.vue` 未调用任何 API
**文件位置:** `sakura_admin_web/src/views/app/UserDetailPage.vue`
当前完整代码:
```vue
<template>
<main class="content">
<header class="page-head">
<div>
<p class="eyebrow">详情</p>
<h1>{{ title }}</h1>
</div>
</header>
<section class="panel">
<pre>{{ content }}</pre>
</section>
</main>
</template>
<script setup lang="ts">
import { computed } from "vue";
import { authState } from "../../stores/auth";
const props = defineProps<{ kind: string }>();
const title = computed(() => (props.kind === "profile" ? "我的资料" : "作品详情"));
const content = computed(() =>
props.kind === "profile"
? JSON.stringify(authState.user, null, 2)
: "详情数据由现有 API 按需加载。"
);
</script>
```
**缺失的关键要素:**
- ❌ 没有 `import { http, apiData } from "../../api/http"` — 未导入 HTTP 客户端
- ❌ 没有 `import { useRoute } from "vue-router"` — 未获取路由参数
- ❌ 没有 `onMounted` 生命周期钩子 — 不会在组件挂载时加载数据
- ❌ 没有任何 `ref()` 存储数据 — 没有响应式数据容器
- ❌ 当 `kind === "gallery"` 或 `kind === "novels"` 时,`content` 只是一段固定死的中文字符串
> 注:`kind === "profile"` 能显示用户资料,仅因为 `authState.user` 已在路由守卫 `router.beforeEach` 中通过 `loadMe()` 提前加载了。这是"碰巧能用",并非设计意图。
#### 根因 2:路由未传递 `id` 参数给组件
**文件位置:** `sakura_admin_web/src/router/index.ts` 第 30-32 行
```typescript
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
```
`props` 被设置为**静态对象** `{ kind: "gallery" }`,这意味着:
- `props.id` 始终为 `undefined`
- 即便组件内部添加了 API 调用,也无法知道要请求哪个 ID 的作品
正确做法应使用以下之一:
```typescript
// 方式一:自动传递所有 params
props: true
// 方式二:函数合并 params 与自定义 props
props: (route) => ({ kind: "gallery", id: route.params.id })
```
#### 根因 3:后端其实已有详情 API(但前端没调用)
后端已经实现了详情接口:
| 方法 | 路径 | 文件 | 行号 |
|------|------|------|------|
| GET | `/api/v1/gallery/{artwork_id}` | `sakura_cloud/api/v1/endpoints/gallery.py` | 230 |
| GET | `/api/v1/novels/{novel_id}` | `sakura_cloud/api/v1/endpoints/novels.py` | 222 |
但是:
- 这些接口在 **`/api/v1/gallery/{id}`** 路径下,而非 `/api/v1/me/gallery/{id}`
- 前端 `UserListPage.vue` 列表调用的是 `GET /me/gallery` 和 `GET /me/novels`
- 详情页如果想保持和列表页一致的 `/me/` 前缀,后端缺少 `GET /me/gallery/{id}` 和 `GET /me/novels/{id}` 路由
- 但这不影响功能——直接调用 `/api/v1/gallery/{id}` 和 `/api/v1/novels/{id}` 即可
#### 对比:相同模式的 `AdminUserDetail.vue` 工作正常
```typescript
import { onMounted, ref } from "vue";
import { useRoute } from "vue-router";
import { apiData, http } from "../../api/http";
const route = useRoute();
const user = ref<Record<string, any> | null>(null);
async function load() {
const response = await http.get(`/admin/users/${route.params.id}`);
user.value = apiData<Record<string, any>>(response);
}
onMounted(load);
```
这说明代码库中**已有正确的详情加载模式**,`UserDetailPage.vue` 只需要参照 `AdminUserDetail.vue` 的模式来实现即可。
### 2.3 修复方案
#### 方案(推荐):按 AdminUserDetail 模式实现 UserDetailPage
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_admin_web/src/views/app/UserDetailPage.vue` | 完整重写,添加数据加载逻辑和详情展示模板 |
| `sakura_admin_web/src/router/index.ts` 第 30、32 行 | 修改 `props` 配置,传递 `id` 参数 |
| (可选)`sakura_cloud/api/v1/endpoints/me.py` | 新增 `GET /me/gallery/{id}` 和 `GET /me/novels/{id}` 路由 |
**具体做法:**
**步骤 1:修复路由传参**(`router/index.ts`)
```typescript
// 将:
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
// 改为(推荐方式一,保持简洁):
{ path: "gallery/:id", component: UserDetailPage, props: (route) => ({ kind: "gallery", id: route.params.id }) },
{ path: "novels/:id", component: UserDetailPage, props: (route) => ({ kind: "novels", id: route.params.id }) },
```
**步骤 2:重写 UserDetailPage.vue**(参照 `AdminUserDetail.vue` 模式)
1. 导入 `onMounted`、`ref`、`http`、`apiData`
2. 在 `props` 类型中增加 `id?: string`
3. 在 `onMounted` 中根据 `props.kind` 调用不同的 API:
- `kind === "gallery"` → `GET /api/v1/gallery/${props.id}`
- `kind === "novels"` → `GET /api/v1/novels/${props.id}`
- `kind === "profile"` → 保持现有逻辑(使用 `authState.user`)
4. 添加 loading 和 error 状态
5. 更新模板,将 `{{ content }}` 替换为结构化展示(标题、作者、标签、缩略图等)
**步骤 3(可选):在后端添加 `/me/` 前缀的详情路由**
在 `sakura_cloud/api/v1/endpoints/me.py` 中添加:
```python
@router.get("/gallery/{artwork_id}")
def my_gallery_detail(artwork_id: str, current_user: CurrentUser, db: DbSession):
"""获取当前用户的单个画廊作品详情"""
from sakura_cloud.api.v1.endpoints.gallery import get_artwork
return get_artwork(artwork_id, current_user, db)
@router.get("/novels/{novel_id}")
def my_novel_detail(novel_id: str, current_user: CurrentUser, db: DbSession):
"""获取当前用户的单个小说作品详情"""
from sakura_cloud.api.v1.endpoints.novels import get_novel
return get_novel(novel_id, current_user, db)
```
### 2.4 预期效果
- 用户从列表页点击任意画廊/小说作品,详情页**正常展示作品信息**(标题、作者、标签、图片、描述等)
- 加载过程中显示 loading 状态,加载失败显示错误提示
- `kind === "profile"` 的个人资料页不受影响
---
## 三、Web 端缺少漫画板块问题
### 3.1 问题现象
在 Web 管理前端(`sakura_admin_web`)中,侧边栏导航只有以下入口:
- 概览(`/app`)
- 图片(`/app/gallery`)
- 小说(`/app/novels`)
- 提醒(`/app/alerts`)
- 我的(`/app/profile`)
**缺少"漫画"板块**,用户无法在 Web 端独立浏览、搜索漫画类型的内容。漫画作品即使已同步到云端,也只能混在"图片"板块中与其他插画(illust)混合展示,无法单独筛选。
### 3.2 根因分析
#### 根因 1:前端路由和侧边栏缺少 manga 入口
**文件位置:** `sakura_admin_web/src/router/index.ts` 第 27-35 行
当前 `/app` 路由子节点:
```typescript
children: [
{ path: "", component: UserDashboard },
{ path: "gallery", component: UserListPage, props: { kind: "gallery" } },
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels", component: UserListPage, props: { kind: "novels" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
{ path: "alerts", component: UserListPage, props: { kind: "alerts" } },
{ path: "profile", component: UserDetailPage, props: { kind: "profile" } }
]
```
**没有 `manga` 路由**,也没有对应的列表页和详情页路由。
**文件位置:** `sakura_admin_web/src/views/app/AppLayout.vue` 第 4-9 行
```vue
<RouterLink to="/app">概览</RouterLink>
<RouterLink to="/app/gallery">图片</RouterLink>
<RouterLink to="/app/novels">小说</RouterLink>
<RouterLink to="/app/alerts">提醒</RouterLink>
<RouterLink to="/app/profile">我的</RouterLink>
```
侧边栏没有"漫画"导航项。
#### 根因 2:UserListPage 的 `kind` 类型不包含 manga
**文件位置:** `sakura_admin_web/src/views/app/UserListPage.vue` 第 27 行
```typescript
const props = defineProps<{ kind: "gallery" | "novels" | "alerts" }>();
```
`kind` 的 TypeScript 类型仅为 `"gallery" | "novels" | "alerts"`,不包含 `"manga"`。
第 31 行的标题映射也缺少 manga:
```typescript
const title = computed(() => ({ gallery: "图片", novels: "小说", alerts: "提醒中心" }[props.kind]));
```
第 41 行的 API 调用路径硬编码了 `kind`:
```typescript
const response = await http.get(`/me/${props.kind}`, { params });
```
如果 `kind === "manga"`,会请求 `/me/manga`,但后端 `me.py` 中没有这个路由。
#### 根因 3:后端其实已支持按 content_type 筛选漫画
**关键事实:后端不区分 gallery 和 manga,它们共用同一张 `artworks` 表。**
- `Artwork.content_type` 字段默认值为 `"illust"`,但也支持 `"manga"`(漫画)等值
- `/api/v1/gallery` 接口已支持 `content_type` 查询参数(`gallery.py` 第 35 行)
- `/api/v1/me/gallery` 透传了 `content_type` 参数(`me.py` 第 39-50 行)
这意味着**为 Web 端增加漫画板块,后端几乎不需要改动**——只需要在调用 `/me/gallery` 时传入 `content_type=manga` 即可。
#### 根因 4:UserDetailPage 同样不支持 manga 类型
`UserDetailPage.vue` 的 `kind` prop 类型(第 26 行)和路由传参同样缺少 manga 支持。即使添加了列表页路由,详情页也会因 `kind === "manga"` 时 `content` 返回固定字符串 "详情数据由现有 API 按需加载。" 而无法显示内容。
### 3.3 修复方案
#### 方案(推荐):前端 4 处修改即可新增漫画板块
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_admin_web/src/router/index.ts` | 新增 `/app/manga` 和 `/app/manga/:id` 路由 |
| `sakura_admin_web/src/views/app/AppLayout.vue` | 侧边栏新增"漫画"导航项 |
| `sakura_admin_web/src/views/app/UserListPage.vue` | `kind` 类型和标题映射增加 `manga` |
| `sakura_admin_web/src/views/app/UserDetailPage.vue` | 详情加载逻辑增加 `manga` 分支 |
**具体做法:**
**步骤 1:新增路由**(`router/index.ts`)
```typescript
// 在 /app 的 children 数组中增加两条新路由
{ path: "manga", component: UserListPage, props: { kind: "manga" } },
{ path: "manga/:id", component: UserDetailPage, props: (route) => ({ kind: "manga", id: route.params.id }) },
```
**步骤 2:侧边栏增加入口**(`AppLayout.vue`)
```vue
<RouterLink to="/app/manga">漫画</RouterLink>
<!-- 插入在"图片"和"小说"之间 -->
```
**步骤 3:UserListPage 增加 manga 支持**
```typescript
// 将 kind 类型扩展为:
const props = defineProps<{ kind: "gallery" | "manga" | "novels" | "alerts" }>();
// 标题映射增加:
const title = computed(() => ({
gallery: "图片",
manga: "漫画", // ← 新增
novels: "小说",
alerts: "提醒中心"
}[props.kind]));
// API 调用逻辑修改(第 38-48 行):
async function load() {
loading.value = true;
try {
const params: Record<string, any> = {};
if (props.kind === "alerts") {
// 提醒列表保持不变
} else {
if (search.value) params.search = search.value;
// 关键:manga 和 gallery 共用同一个后端接口,通过 content_type 区分
if (props.kind === "manga") params.content_type = "manga";
else if (props.kind === "gallery") params.content_type = "illust";
}
const apiPath = props.kind === "manga" ? "/me/gallery" : `/me/${props.kind}`;
const response = await http.get(apiPath, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
} finally {
loading.value = false;
}
}
```
**步骤 4:UserDetailPage 增加 manga 详情加载**(与方案二中详情页修复合并实施)
在 `loadDetail()` 逻辑中增加:
```typescript
if (props.kind === "manga") {
const response = await http.get(`/gallery/${props.id}`);
item.value = apiData(response);
}
```
> **设计说明:** 漫画和图片在后端共用 `gallery` API(同一张 `artworks` 表),只是 `content_type` 字段值不同(`"illust"` vs `"manga"`)。因此前端通过传入 `content_type=manga` 参数来筛选漫画类型,无需新增后端接口。这与移动端 APP 的处理方式一致。
### 3.4 预期效果
- Web 端侧边栏新增"漫画"入口,与"图片""小说"并列
- 点击进入后展示所有 `content_type=manga` 的作品
- 支持搜索漫画标题/作者/标签
- 漫画详情页正常展示作品信息
- "图片"板块默认展示 `content_type=illust` 的内容,与漫画分离
- 如果以后需要更多内容类型(如 `ugoira` 动图),按相同模式扩展即可
---
## 四、Web 端列表加载性能问题
### 4.1 问题现象
Web 管理前端在浏览图片列表时,用户感知加载较慢:
- 打开"图片"或"小说"列表页时,页面需要等待数秒才显示内容
- 搜索时每次输入都触发后端请求,响应不够即时
- 列表没有分页控件,所有数据一次性加载,数据量大时尤其慢
- 缩略图使用后端 `/api/v1/files/{id}/thumbnail` 接口,未使用 CDN 或缓存策略
### 4.2 根因分析
#### 根因 1:列表页没有前端分页(🔴 最直接影响)
**文件位置:** `sakura_admin_web/src/views/app/UserListPage.vue` 第 38-48 行
```typescript
async function load() {
loading.value = true;
try {
const params = props.kind === "alerts" ? {} : { search: search.value || undefined };
const response = await http.get(`/me/${props.kind}`, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
} finally {
loading.value = false;
}
}
```
**问题:**
- 请求**未传入 `page` 和 `limit` 参数**
- 后端 `/api/v1/me/gallery` 的默认 limit 是 30(`gallery.py` 第 31 行),但如果后端默认值被修改或数据量大,前端仍会慢
- 更关键的是:**后端每次都会执行 `COUNT(*)` 查询**(`gallery.py` 第 100 行),数据量大时 `COUNT` 本身就是慢查询
- UI 层面**没有分页控件**(上一页/下一页按钮),用户无法翻页浏览更多内容
- 搜索框在每次 `@keyup.enter` 时触发请求,但没有防抖(debounce)机制
#### 根因 2:后端 COUNT 查询每次都是全表扫描(🔴 核心性能瓶颈)
**文件位置:** `sakura_cloud/api/v1/endpoints/gallery.py` 第 43-100 行
```python
count_query = select(func.count()).select_from(Artwork).where(Artwork.user_id == current_user.id)
# ... 应用相同的 filters ...
total = int(db.scalar(count_query) or 0)
```
**问题:**
- 每次列表请求都执行 `COUNT(*)` 查询
- `COUNT(*)` 在有大量数据时需要进行全表或索引扫描
- 虽然 `gallery.py` 第 46-47 行使用了 `ILIKE`(`ilike(f"%{search_text}%")`),但带通配符的 `ILIKE` 无法利用 B-tree 索引,需要全表遍历每一行进行模式匹配
- 搜索 + COUNT 组合是 O(n) 复杂度,数据量上万条后耗时明显增加
- 即使是不搜索的普通列表请求,COUNT 也需要扫描用户的所有作品
#### 根因 3:列表和搜索没有防抖(🟡)
**文件位置:** `sakura_admin_web/src/views/app/UserListPage.vue` 第 8 行
```vue
<input v-if="kind !== 'alerts'" v-model.trim="search" placeholder="搜索" @keyup.enter="load" />
```
**问题:**
- 用户按 Enter 才触发搜索,看似没问题
- 但如果用户快速输入后多次按 Enter,或配合其他筛选条件多次修改,会发起多次后端请求
- 没有防抖/节流机制,连续快速操作会产生冗余请求
#### 根因 4:缩略图加载策略未优化(🟡)
**文件位置:** `sakura_admin_web/src/views/app/UserListPage.vue` — 模板中完全没有图片
当前列表页只显示作品的 `title` 和 `author` 文本,没有缩略图展示,所以缩略图加载不是 Web 端的瓶颈。但如果未来改进详情页展示缩略图(当前详情页是占位组件),需要注意:
- 后端缩略图接口 `/api/v1/files/{id}/thumbnail` 是**同步读取 MinIO + 实时返回**,没有 CDN 缓存
- 如果列表页展示 30 张缩略图,就是 30 次后端文件读取请求
#### 根因 5:Axios 超时 15 秒可能不够(🟢)
**文件位置:** `sakura_admin_web/src/api/http.ts` 第 8 行
```typescript
export const http = axios.create({
baseURL: API_BASE,
timeout: 15000,
withCredentials: false
});
```
15 秒超时对于慢速服务器场景来说偏紧张,但影响相对较小。
### 4.3 修复方案
#### 方案 A:前端增加分页控件(🔴 最重要,直接解决加载慢)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_admin_web/src/views/app/UserListPage.vue` | 增加分页状态、分页 UI 控件、分页加载逻辑 |
**具体做法:**
1. 在 `<script setup>` 中增加分页状态:
```typescript
const page = ref(1);
const limit = 30;
const total = ref(0);
const totalPages = ref(0);
```
2. 修改 `load()` 方法,传入分页参数:
```typescript
async function load() {
loading.value = true;
try {
const params: Record<string, any> = { page: page.value, limit };
if (props.kind !== "alerts" && search.value) params.search = search.value;
if (props.kind === "manga") params.content_type = "manga";
else if (props.kind === "gallery") params.content_type = "illust";
const apiPath = props.kind === "manga" ? "/me/gallery" : `/me/${props.kind}`;
const response = await http.get(apiPath, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
total.value = data.pagination?.total || data.total || items.value.length;
totalPages.value = data.pagination?.pages || Math.ceil(total.value / limit);
} finally {
loading.value = false;
}
}
```
3. 在模板底部增加分页控件:
```vue
<div v-if="totalPages > 1" class="pagination">
<button :disabled="page <= 1" @click="page--; load()">上一页</button>
<span>第 {{ page }} / {{ totalPages }} 页(共 {{ total }} 条)</span>
<button :disabled="page >= totalPages" @click="page++; load()">下一页</button>
</div>
```
4. 搜索或切换 `kind` 时重置 `page` 为 1:
```typescript
watch(() => props.kind, () => { page.value = 1; load(); });
// 搜索时也重置页码
function onSearch() { page.value = 1; load(); }
```
#### 方案 B:后端 COUNT 查询优化(🔴 解决根本性能瓶颈)
**修改位置:** `sakura_cloud/api/v1/endpoints/gallery.py` 第 100 行
**具体做法:**
**选项 1:使用估算计数(推荐,适用于"大概有多少条"的场景)**
```python
# 对于 PostgreSQL,使用 pg_stat_user_tables 的估算值替代精确 COUNT
# 仅在不搜索且不需要精确 total 时使用
if not search_text and not any([source_platform, author, tag, content_type, is_favorite]):
# 快速估算
total = int(db.scalar(
select(func.reltuples).select_from(func.pg_class).where(
func.pg_class.c.relname == 'artworks'
)
) or 0)
else:
total = int(db.scalar(count_query) or 0)
```
**选项 2:去掉 COUNT 查询,改为"是否有下一页"模式**
```python
# 查询 limit+1 条,如果有第 limit+1 条则说明有下一页
rows = db.scalars(query.limit(limit + 1)).all()
has_next = len(rows) > limit
data = PageResponse(
items=[ArtworkOut.model_validate(row) for row in rows[:limit]],
pagination=Pagination(page=page, limit=limit, total=None, has_next=has_next),
)
```
这种方式完全避免了 COUNT 查询,大幅降低数据库负载。
**选项 3:对 COUNT 查询添加超时保护**
```python
# 设置 statement_timeout 防止 COUNT 查询拖垮整个请求
db.execute(text("SET LOCAL statement_timeout = '2000ms'"))
total = int(db.scalar(count_query) or 0)
db.execute(text("RESET statement_timeout"))
```
#### 方案 C:搜索增加防抖(🟡 改善交互体验)
**修改位置:** `sakura_admin_web/src/views/app/UserListPage.vue` 第 8 行
**具体做法:**
1. 增加防抖逻辑:
```typescript
let debounceTimer: ReturnType<typeof setTimeout> | null = null;
function onSearchInput() {
if (debounceTimer) clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => {
page.value = 1;
load();
}, 400); // 400ms 防抖
}
```
2. 修改模板,从 `@keyup.enter` 改为实时防抖:
```vue
<input v-model.trim="search" placeholder="搜索..." @input="onSearchInput" />
```
#### 方案 D:缩略图使用 CDN / 缓存策略(🟡 前瞻性优化)
**修改位置:** 后端 `sakura_cloud/api/v1/endpoints/files.py`
**具体做法:**
1. 在 Nginx 或 MinIO 前面加一层**缩略图缓存**
2. 缩略图生成后保存到 MinIO 的 `thumbnails/` bucket,设置公开读权限
3. 前端直接使用 MinIO 的公开 URL 而非后端代理 URL
4. 为缩略图响应添加 `Cache-Control: public, max-age=86400` 头
#### 方案 E:后端查询结果缓存(🟢 锦上添花)
**修改位置:** 后端 `sakura_cloud/api/v1/endpoints/gallery.py`
**具体做法:**
1. 使用 Redis 缓存(如项目已有 Redis)或内存 LRU 缓存
2. 缓存 key = `gallery_list:{user_id}:{page}:{limit}:{search}:{filters_hash}`
3. 缓存有效期 1-2 分钟
4. 用户上传新作品或修改作品时,清除该用户的列表缓存
### 4.4 预期效果
- 列表页首屏加载时间从 2-5 秒降到 **500ms 以内**(分页 + 去掉 COUNT)
- 搜索响应从"按 Enter 等待"变为**输入即搜(防抖 400ms)**
- 分页控件使用户可以浏览全部数据,而非仅前 30 条
- 后端 COUNT 查询优化后,`galleryStat()` 和列表请求的数据库负载显著降低
---
## 五、手机端搜索不到图书问题
### 3.1 问题现象
用户在手机 APP 中搜索中文图书/漫画/小说时:
- 搜索**中文关键词**(如"樱花"、"海贼王"),返回结果为空或极少
- 同一关键词在英文搜索中可能有结果
- 自建云库中的内容搜索也可能不命中
### 3.2 根因分析
手机端搜索有**两条独立路径**,各有不同的问题。以下按影响程度从大到小排列。
---
#### 路径 A:第三方在线源搜索(Legado Engine)—— 最可能出问题
**涉及文件:**
- `sakura_mobile/lib/src/core/legado_engine.dart`(搜索引擎主逻辑)
- `sakura_mobile/lib/src/core/legado_rule_parser.dart`(HTML/JSON 解析器)
- `sakura_mobile/lib/src/core/source_manager.dart`(源管理)
#### 根因 1:HTTP 响应编码不匹配(🔴 最可能的原因)
**文件位置:** `sakura_mobile/lib/src/core/legado_engine.dart` 第 11-17 行(Dio 实例)和第 40-52 行(search 方法)
```dart
static final Dio _http = Dio(BaseOptions(
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 10),
));
// search 方法中:
final response = await _http.get<String>(
url,
options: Options(
responseType: ResponseType.plain,
headers: {...source.headers ?? {}},
),
);
```
**问题详解:**
Dio 的 `ResponseType.plain` 默认以 **UTF-8** 解码响应体。然而大量中国漫画/小说网站(如笔趣阁、包子漫画、全本玄幻小说等)的服务端返回的是 **GBK/GB2312** 编码的 HTML 页面。
当 Dio 用 UTF-8 解码 GBK 编码的中文内容时,会产生大量的**乱码**(如 `ä½ å¥½` 代替 `你好`)。随后 `RuleParser` 使用 CSS 选择器、正则表达式或 JSONPath 解析这些乱码内容时:
- CSS 选择器匹配不到任何元素(因为实际的 HTML 结构在乱码后仍然存在,但**文本节点的内容已损坏**)
- 正则表达式无法匹配中文关键词
- 搜索结果被过滤掉(因为 `searchNameRule` 提取到的标题是乱码)
**证据:**
- `LegadoEngine.search()` 有 `.catchError((_) => <UnifiedSearchResult>[])` 的静默错误吞没逻辑(第 86 行),用户看不到任何编码错误的提示
- 默认启用的 6 个精选源(笔趣阁、全本玄幻小说、妙笔阁、包子漫画、古风漫画网、COCO漫画)全部是中国大陆网站,大概率使用 GBK 编码
#### 根因 2:URL 百分号编码可能不匹配目标网站(🟡)
**文件位置:** `sakura_mobile/lib/src/core/legado_engine.dart` 第 38 行
```dart
final url = searchUrl
.replaceAll('{{key}}', Uri.encodeComponent(keyword))
```
`Uri.encodeComponent()` 始终使用 **UTF-8** 进行百分号编码。例如 `你好` → `%E4%BD%A0%E5%A5%BD`。
部分老式中国网站的搜索接口基于 GBK 后端,期望收到 **GBK 百分号编码**的查询参数(`你好` → `%C4%E3%BA%C3`)。编码不匹配时,服务端收到乱码查询词,返回空结果。
#### 根因 3:错误静默吞没,用户看不到诊断信息(🟡)
**文件位置:** `sakura_mobile/lib/src/core/legado_engine.dart` 第 76-89 行
```dart
Future<List<UnifiedSearchResult>> searchAll(...) async {
final futures = <Future<List<UnifiedSearchResult>>>[];
for (final source in enabledSources.take(maxConcurrency)) {
futures.add(
search(keyword, source: source, page: page)
.catchError((_) => <UnifiedSearchResult>[]), // ← 静默丢弃所有错误
);
}
// ...
}
```
每个源的搜索错误都被**静默丢弃**,返回空列表。用户无法区分:
- "该源确实没有这个关键词的结果"
- "该源搜索失败了(编码错误/超时/网络不通)"
#### 根因 4:默认种子源使用占位 URL(🟡)
**文件位置:** `sakura_mobile/lib/src/core/source_manager.dart` 第 274-317 行
```dart
// 预置的 6 个精选源使用 example.invalid 占位 URL
const _seedSources = [
_SeedSource(name: '全本玄幻小说', ...),
_SeedSource(name: '笔趣阁', ...),
// ...
];
```
这些内置源的 URL 是 `https://example.invalid/...`(不可访问的占位地址)。它们的作用仅仅是**预留名称和 ID**,真正的 URL 需要从在线源仓库导入后才能获得。如果用户没有手动导入源仓库,这 6 个默认源将永远返回空结果。
#### 根因 5:5 秒超时可能不够(🟢)
```dart
static const perSourceTimeout = Duration(seconds: 5);
```
中国小说/漫画网站服务器响应可能很慢(尤其是免费站点),5 秒超时后搜索被中断。
---
#### 路径 B:自建云库搜索(Sakura Cloud API)—— 后端工作正常
**涉及文件:**
- `sakura_mobile/lib/src/core/api_client.dart`(移动端 API 客户端)
- `sakura_cloud/api/v1/endpoints/gallery.py`(画廊搜索)
- `sakura_cloud/api/v1/endpoints/novels.py`(小说搜索)
#### 后端分析结论:云库搜索的中文处理是**正确的**
后端(FastAPI + PostgreSQL)的搜索全部使用 `ILIKE`(不区分大小写的 LIKE),这是完全 Unicode 感知的匹配方式。中文搜索在后端层面**不应该有问题**。
```python
# gallery.py 中的搜索逻辑
condition = Artwork.title.ilike(f"%{search_text}%")
```
如果云库搜索不到中文内容,更可能是:
- 云库中确实没有该关键词的内容(数据未同步或上传)
- 移动端的 API 调用参数传递问题(下面分析)
#### 根因 6:移动端 API 客户端未显式设置编码(🟡)
**文件位置:** `sakura_mobile/lib/src/core/api_client.dart` 第 13-19 行
```dart
static Dio _dio(String baseUrl) => Dio(BaseOptions(
baseUrl: baseUrl,
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 15),
));
```
Dio 默认使用 UTF-8 处理查询参数。FastAPI 也默认使用 UTF-8 解析查询参数。只要两端都是默认配置,编码应该保持一致。但如果:
- 云服务器前面有 Nginx 做了编码转换
- 或 `baseUrl` 配置的值与实际后端不一致
- 这些都可能导致请求未到达正确的后端
#### 根因 7:搜索参数条件性发送(🟢)
**文件位置:** `sakura_mobile/lib/src/core/api_client.dart` 第 98-106 行
```dart
if (search != null && search.trim().isNotEmpty) 'search': search.trim(),
if (search != null && search.trim().isNotEmpty) 'search_scope': searchScope,
```
`search_scope` 只在 `search` 非空时才发送。这意味着不能单独按 `search_scope` 过滤(如只看有 OCR 文本的作品),但这并非搜索不到的问题。
---
### 3.3 修复方案
#### 方案 A:修复 Legado Engine 编码检测(🔴 最重要,解决第三方源搜索)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/legado_engine.dart` | 添加响应编码检测和 GBK 解码支持 |
**具体做法:**
1. **为 Dio 实例添加 `responseDecoder`**:检测 HTTP 响应头中的 `Content-Type` charset 字段,如果指定了 `gbk`/`gb2312`/`gb18030`,使用对应编码解码;如果没有指定 charset,尝试用 UTF-8 解码,失败则回退到 GBK。
2. **代码位置参考(legado_engine.dart ~第 11-14 行)**:
```dart
// 当前 Dio 实例配置应增加 responseDecoder
static final Dio _http = Dio(BaseOptions(
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 10),
// 新增:响应解码器
responseDecoder: _decodeResponse,
));
// 新增:智能编码检测函数
static String _decodeResponse(List<int> bytes, Headers headers, String contentType) {
// 1. 从 Content-Type header 提取 charset
final charset = _extractCharset(contentType);
if (charset != null) {
return _decodeWithCharset(bytes, charset);
}
// 2. 尝试 UTF-8 解码
try {
return utf8.decode(bytes);
} catch (_) {
// 3. UTF-8 失败 → 尝试 GBK
try {
return gbk.decode(bytes);
} catch (_) {
return latin1.decode(bytes); // 保底:按字节原样保留
}
}
}
```
3. **添加 `gbk` 或 `gbk_codec` 依赖**:Flutter 的 `dart:convert` 不包含 GBK 编解码器。需要在 `pubspec.yaml` 中添加 `gbk_codec` 或其他 GBK 解码包。
#### 方案 B:增加源级别的编码配置(🟡 补充方案 A)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/legado_models.dart` | `LegadoSource` 增加 `charset` 字段 |
| `sakura_mobile/lib/src/core/legado_engine.dart` | 搜索时根据源的 `charset` 选择解码器 |
**具体做法:**
1. 在 `LegadoSource` 模型中增加可选字段 `charset?: string`(值为 `utf-8`、`gbk`、`gb2312`、`auto` 等)
2. 在线源仓库(如 legado.aoaostar.com)的 JSON 中许多已包含 `charset` 字段,导入时保留
3. 搜索时如果源指定了 charset,直接使用对应编码;未指定则使用方案 A 的自动检测
#### 方案 C:增加 URL 编码选项(🟡 补充方案 A)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/legado_engine.dart` 第 38 行 | 搜索 URL 构建支持 GBK 百分号编码 |
**具体做法:**
根据源的 `charset` 配置选择 URL 编码方式:
- `utf-8` 或未指定 → 使用 `Uri.encodeComponent()`(当前行为)
- `gbk` / `gb2312` / `gb18030` → 使用 GBK 编码后再百分号编码
#### 方案 D:增加错误诊断信息(🟡 改善用户体验)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/legado_engine.dart` 第 86 行 | 不再静默丢弃错误 |
**具体做法:**
1. `searchAll()` 中的 `.catchError()` 不再返回空列表,而是返回带有错误标记的结果
2. 在 `UnifiedSearchResult` 中增加 `errorMessage?: string` 字段
3. UI 层(`explore_page.dart`)对有错误的源显示灰色提示(如"搜索失败:编码错误")而非静默消失
#### 方案 E:延长超时时间(🟢 简单调整)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/legado_engine.dart` 第 12-13 行 | 增加超时时间 |
将 `perSourceTimeout` 从 5 秒增加到 10-15 秒,适应慢速中网站点。
#### 方案 F:确认云库搜索正常(🟢 排查步骤)
如果用户反馈云库("我的云库"板块)搜索也失败,请排查:
1. **确认 baseUrl 配置正确**:在 APP 设置中检查服务器地址是否为实际运行的云端 API(默认 `http://api.kunkunxiaomao.top:8000`)
2. **检查网络连通性**:在手机浏览器中访问 `http://api.kunkunxiaomao.top:8000/api/v1/health` 确认可访问
3. **确认数据已同步**:在桌面端检查是否已将作品同步到云端
4. **查看后端日志**:检查 FastAPI 的请求日志,确认搜索请求是否到达后端、参数是否正确
### 3.4 预期效果
- 第三方在线源(笔趣阁、包子漫画等)搜索中文关键词能正常返回结果
- 搜索"海贼王"、"斗罗大陆"、"三体"等常见中文书名能命中
- 搜索失败的源在 UI 上有提示,而非静默显示"无结果"
- 自建云库搜索保持不变(本身已支持中文)
---
## 六、手机端加载过慢问题
### 6.1 问题现象
手机 APP 多个页面加载缓慢,用户感知明显:
- **发现页(FeedTab):** 打开后长时间转圈,白屏等待
- **画廊页(GalleryTab):** 浏览图片列表时响应慢,尤其是翻页后
- **小说书架(NovelsTab):** 首次进入时等待明显
- **图片缩略图:** 列表中的图片逐个缓慢出现
### 6.2 根因分析
#### 6.2.1 发现页(FeedTab)—— 5 个 API 全部完成才渲染(已部分优化,仍有问题)
**文件位置:** `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 22-41 行
当前代码已经做了初步优化(拆分为独立 Future + stat 3 秒超时),但仍存在问题:
```dart
_statFuture ??= api.galleryStat().timeout(const Duration(seconds: 3),
onTimeout: () => <String, dynamic>{});
_todayFuture ??= api.galleryFeed(mode: 'created', limit: 36)...;
_recentFuture ??= api.galleryFeed(mode: 'recent', limit: 24)...;
_novelFuture ??= api.recentNovels(limit: 12)...;
_alertFuture ??= api.unreadAlerts(limit: 12)...;
```
**问题:**
- `galleryFeed` 两个模式(created/recent)都调用同一个后端接口,只是排序不同,后端可能做了全表扫描
- 5 个请求首次触发时同时发出,没有任何优先级排序,会造成服务端瞬时压力
- `_ensureFutures()` 在 `build()` 中调用,但有 `??=` 缓存机制,切换 tab 后回来不会刷新(除非手动下拉)
#### 6.2.2 画廊页(GalleryTab)—— 单次全量拉取,无分页预加载
**文件位置:** `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` 第 98-110 行
```dart
Future<List<Artwork>> _load() async {
final rows = await ref.read(apiClientProvider).gallery(
search: search.text.trim().isEmpty ? null : search.text.trim(),
searchScope: searchScope,
isFavorite: favoritesOnly ? true : null,
contentType: _effectiveContentType,
);
final items = rows
.map((item) => Artwork.fromJson(item as Map<String, dynamic>))
.toList();
items.sort(_compareArtworkNewestFirst);
return items;
}
```
**问题:**
- **没有分页参数传入** —— 检查 `api_client.dart` 中 `gallery()` 方法(第 88-109 行),虽有 `page` 和 `limit` 参数,但 `_load()` 调用时**未传入**,导致默认拉取全部数据
- 如果云库中有上千张图片,一次请求拉全部数据 + JSON 解析 + 客户端排序,会非常慢
- 默认 `limit` 在后端只设了 60 条,但如果后端分页参数默认值较高,仍可能拉到大量数据
- 每次切换搜索/筛选条件都触发全量重新加载
#### 6.2.3 小说书架(NovelsTab)—— 3 个请求串行等待全部完成
**文件位置:** `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` 第 30-52 行
```dart
Future<_NovelShelfData> _load() async {
final api = ref.read(apiClientProvider);
final query = search.text.trim();
final results = await Future.wait<List<dynamic>>([
api.novels(search: query.isEmpty ? null : query),
query.isEmpty
? api.novelSeries(includeChapters: false)
: Future.value(<dynamic>[]),
query.isEmpty ? api.continueReadingNovels() : Future.value(<dynamic>[]),
]);
```
**问题:**
- 使用 `Future.wait` 阻塞等待 3 个请求**全部完成**才渲染
- `novelSeries` 和 `continueReadingNovels` 的返回速度决定了整个页面的渲染速度
- 搜索模式下虽跳过了后两个请求,但搜索本身可能返回大量结果
#### 6.2.4 图片缩略图加载拥塞
**涉及文件:**
- `sakura_mobile/lib/src/pages/tabs/feed_tab.dart`
- `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart`
两个页面都在 `ListView` / 横向滚动列表中使用 `CachedNetworkImage` 加载缩略图。Flutter 的 `ListView` 会预构建视口外一定数量的 item,导致:
- 几十张缩略图同时发起网络请求
- 带宽争抢,每张图都很慢
- `CachedNetworkImage` 虽然缓存了磁盘,但首次加载仍需网络
#### 6.2.5 后端 `galleryStat()` 可能全表 COUNT
后端 `/api/v1/gallery/stat` 接口如果对 `artworks` 表做全表 `COUNT(*)`,数据量上万后单次查询就需要数百毫秒甚至数秒。虽然 FeedTab 已经加了 3 秒超时,但这只是掩盖问题而非解决。
#### 6.2.6 后端复合索引可能缺失
`artworks` 表可能存在以下慢查询场景:
- 按 `created_at DESC` 排序但没有复合索引
- `galleryFeed` 可能需要 JOIN 多表(文件表、OCR 表、标签表等)
- 每次请求都做全表排序再 LIMIT
### 6.3 修复方案
#### 方案 A:画廊页分页加载 + 无限滚动(🔴 最重要)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | 改为分页加载,滚动到底部自动加载下一页 |
**具体做法:**
1. 在 `_GalleryTabState` 中增加 `_page`、`_hasMore`、`_isLoadingMore` 状态
2. 首次加载只拉 20-30 条
3. 给 `ListView` 添加 `ScrollController`,滚动到接近底部时自动加载下一页
4. 搜索/筛选条件变化时重置为第 1 页
5. 使用 `_allItems` 列表累加各页数据
#### 方案 B:小说书架渐进式加载(🔴 重要)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` 第 30-38 行 | 拆散 `Future.wait`,各区块独立加载 |
**具体做法:**
1. 将 `Future.wait` 拆为 3 个独立的 `FutureBuilder`
2. 小说列表(`api.novels`)优先渲染
3. 系列分组(`api.novelSeries`)和继续阅读(`api.continueReadingNovels`)各自独立加载
4. 每个区域有独立的骨架屏/loading 指示器
5. 某个区域加载失败不影响其他区域
#### 方案 C:发现页 API 优先级排序(🟡 重要)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` 第 28-41 行 | 按优先级分批发请求 |
**具体做法:**
1. 第一批(立即):统计卡片 + 最近更新(用户最关心的内容)
2. 第二批(200ms 后):今日新增
3. 第三批(500ms 后):最近小说 + 未读提醒
4. 这样首屏在第一批返回后就能展示,而非等 5 个全部完成
#### 方案 D:后端增加 feed 缓存(🟡 解决根本问题)
**修改位置:** 后端 `sakura_cloud/`
**具体做法:**
1. 新增 `feed_cache` 表缓存 feed 查询结果
2. 上传新作品 / 同步后异步刷新缓存
3. 缓存有效期 5-10 分钟,过期后后台刷新
4. 首次无缓存时降级直接查询
#### 方案 E:缩略图懒加载优化(🟡 简单有效)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | GridView 使用 `addRepaintBoundaries` + 更激进的懒加载 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 横向滚动列表限制同时可见的图片数量 |
**具体做法:**
1. 使用 `ListView.builder` 的 `addRepaintBoundaries: true`(默认已开启)
2. 为 `CachedNetworkImage` 增加 `placeholder` 和低分辨率占位图
3. 将 `cacheWidth` / `cacheHeight` 限制为实际显示尺寸(如缩略图只需 300px 宽),避免下载原图再缩放
4. 横向滚动条限制预加载数量(`cacheExtent` 调小)
#### 方案 F:后端优化数据库索引(🟢 性能增强)
**修改位置:** 后端数据库迁移
**具体做法:**
1. 为 `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);
CREATE INDEX idx_artworks_content_type ON artworks(user_id, content_type, created_at DESC);
```
2. 为 `novels` 表添加索引:
```sql
CREATE INDEX idx_novels_user_updated ON novels(user_id, updated_at DESC);
CREATE INDEX idx_novels_series ON novels(series_id, chapter_order);
```
3. `galleryStat()` 使用估算而非精确 COUNT(如 PostgreSQL 的 `pg_stat_user_tables.n_live_tup`),或缓存统计结果
#### 方案 G:本地缓存优先(🟢 移动端离线方案)
**修改位置:**
| 文件 | 修改内容 |
|------|----------|
| `sakura_mobile/lib/src/core/api_client.dart` | 新增本地缓存读写方法 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | 优先读本地缓存,后台静默刷新 |
**具体做法:**
1. 使用 `sqflite` 或 `hive` 存储首页 / 画廊列表的缓存数据
2. 打开页面时先展示缓存(秒开),同时后台请求新数据
3. 新数据到达后平滑替换
4. 缓存有效期 30 分钟
### 6.4 预期效果
- 发现页首屏从 3-5 秒降到 **1 秒以内**(缓存命中时秒开)
- 画廊页从一次性加载全部变为**分页 20-30 条**,首屏加载时间减半
- 小说书架各区块**独立呈现**,不再互相阻塞
- 缩略图加载拥塞缓解,滚动时图片更快出现
---
## 七、实施优先级与排期建议
| 优先级 | 问题 | 推荐方案 | 改动范围 | 预期效果 |
|--------|------|----------|----------|----------|
| 🔴 P0 紧急 | Web 端详情不显示 | 重写 UserDetailPage.vue + 修复路由 | Web 前端 2 个文件 | 详情页正常展示内容 |
| 🔴 P0 紧急 | Web 端缺少漫画板块 | 新增 manga 路由 + 侧边栏入口 + content_type 筛选 | Web 前端 3 个文件 | 漫画内容独立展示和搜索 |
| 🔴 P0 紧急 | Web 端列表页无分页 + COUNT 慢 | 方案 A + B:前端分页控件 + 后端去掉 COUNT | Web 前端 1 文件 + 后端 1 文件 | 列表加载从 2-5s 降到 <500ms |
| 🔴 P0 紧急 | 第三方源中文搜索失败 | 方案 A:Legado Engine 编码修复 | 移动端 1-2 个文件 + 新增依赖 | 搜索中文返回正确结果 |
| 🔴 P0 紧急 | 画廊页全量加载过慢 | 方案 A:分页加载 + 无限滚动 | 移动端 1 个文件 | 首屏加载从秒级降到毫秒级 |
| 🔴 P0 紧急 | 小说书架阻塞等待 | 方案 B:渐进式加载 | 移动端 1 个文件 | 各区块独立渲染不阻塞 |
| 🟡 P1 高 | Web 端搜索无防抖 | 方案 C:搜索 400ms 防抖 | Web 前端 1 个文件 | 输入即搜,减少冗余请求 |
| 🟡 P1 高 | URL 编码不匹配旧站点 | 方案 C(搜索):源级别编码配置 | 移动端 2-3 个文件 | 兼容 GBK 后端的老网站 |
| 🟡 P1 高 | 搜索错误无提示 | 方案 D(搜索):错误诊断信息 | 移动端 3-4 个文件 | 用户能区分"无结果"和"搜索失败" |
| 🟡 P1 高 | 发现页 API 无优先级 | 方案 C(加载):API 优先级排序 | 移动端 1 个文件 | 首屏更快展示核心内容 |
| 🟡 P1 高 | 后端 feed 查询慢 | 方案 D(加载):feed_cache 表 | 后端新增表 + 定时刷新 | 发现页加速 50%+ |
| 🟢 P2 中 | 缩略图拥塞 | 方案 E:缩略图懒加载优化 | 移动端 2 个文件 | 图片加载更流畅 |
| 🟢 P2 中 | 数据库索引缺失 | 方案 F:后端优化索引 | 后端 migration | 查询耗时降低 50%+ |
| 🟢 P2 中 | 超时太短 | 方案 E(搜索):延长超时 | 移动端 1 行 | 慢速站点有足够时间响应 |
| 🟢 P2 中 | 本地缓存 | 方案 G:移动端本地缓存 | 移动端新增缓存层 | 二次打开秒开 |
| 🟢 P2 中 | Web 端缩略图缓存 | 方案 D(加载):CDN/MinIO 公开 URL + Cache-Control | 后端 1 文件 | 缩略图加载更快 |
---
## 附录:关键文件索引
| 文件 | 用途 |
|------|------|
| `sakura_admin_web/src/views/app/UserDetailPage.vue` | **Web 详情页(占位组件需重写)** |
| `sakura_admin_web/src/views/app/UserListPage.vue` | **Web 列表页(无分页、无防抖、无漫画筛选)** |
| `sakura_admin_web/src/views/app/AppLayout.vue` | **Web 侧边栏(缺少漫画入口)** |
| `sakura_admin_web/src/router/index.ts` | **Web 路由配置(缺少 manga 路由、id 未传递)** |
| `sakura_admin_web/src/api/http.ts` | Web 端 HTTP 客户端(Axios 配置) |
| `sakura_admin_web/src/views/admin/AdminUserDetail.vue` | **参考实现——正确的详情加载模式** |
| `sakura_mobile/lib/src/core/legado_engine.dart` | **移动端第三方搜索引擎(编码问题)** |
| `sakura_mobile/lib/src/core/legado_rule_parser.dart` | HTML/JSON 解析器 |
| `sakura_mobile/lib/src/core/api_client.dart` | 移动端云 API 客户端 |
| `sakura_mobile/lib/src/core/source_manager.dart` | 第三方源管理 |
| `sakura_mobile/lib/src/pages/tabs/feed_tab.dart` | **发现页(加载性能问题)** |
| `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | **画廊页(全量加载/分页缺失)** |
| `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` | **小说书架(阻塞等待)** |
| `sakura_cloud/api/v1/endpoints/gallery.py` | **后端画廊 API(COUNT 慢查询、content_type 筛选)** |
| `sakura_cloud/api/v1/endpoints/novels.py` | 后端小说 API(含详情和搜索) |
| `sakura_cloud/api/v1/endpoints/me.py` | 后端用户个人 API(缺少详情路由) |
| `sakura_cloud/api/v1/endpoints/files.py` | **后端文件 API(缩略图无缓存策略)** |
| `sakura_cloud/models/artwork.py` | **Artwork 模型(content_type 已支持 manga)** |
| `sakura_cloud/scripts/create_admin.py` | 管理员账号创建脚本 |
| `sakura_cloud/core/config.py` | 后端配置(含数据库/MinIO/JWT 凭证) |