# 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
```
**缺失的关键要素:**
- ❌ 没有 `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 | null>(null);
async function load() {
const response = await http.get(`/admin/users/${route.params.id}`);
user.value = apiData>(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
概览
图片
小说
提醒
我的
```
侧边栏没有"漫画"导航项。
#### 根因 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
漫画
```
**步骤 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 = {};
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(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(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
```
**问题:**
- 用户按 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. 在 `