Files
SakuraHub/docs/Web端详情加载与手机端搜索优化方案.md
T

1245 lines
49 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 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 凭证) |