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

49 KiB
Raw Permalink Blame History

Web 端详情加载、手机端搜索与加载性能优化方案

更新日期:2026-06-15 范围:Sakura Admin Web (Vue.js) + Sakura Mobile (Flutter) + Sakura Cloud (FastAPI) 说明:本文档提供问题分析与优化方案,不包含实际代码改动。


目录

  1. 管理员账号密码
  2. Web 端详情数据按需加载问题
  3. Web 端缺少漫画板块问题
  4. Web 端列表加载性能问题
  5. 手机端搜索不到图书问题
  6. 手机端加载过慢问题
  7. 实施优先级与排期建议

一、管理员账号密码

1.1 现状

本项目没有预设的默认管理员账号密码。数据库初始化脚本(sakura_cloud/scripts/init_db.py)仅创建空表结构,不插入任何种子数据。

管理员账号需要部署后手动创建,使用后端提供的 CLI 脚本。

1.2 创建管理员账号的方法

脚本位置: sakura_cloud/scripts/create_admin.py

使用方法:

# 在后端服务器上执行(需在 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

当前完整代码:

<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 行

{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels/:id",  component: UserDetailPage, props: { kind: "novels" } },

props 被设置为静态对象 { kind: "gallery" },这意味着:

  • props.id 始终为 undefined
  • 即便组件内部添加了 API 调用,也无法知道要请求哪个 ID 的作品

正确做法应使用以下之一:

// 方式一:自动传递所有 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 工作正常

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)

// 将:
{ 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 中添加:

@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 路由子节点:

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 行

<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 行

const props = defineProps<{ kind: "gallery" | "novels" | "alerts" }>();

kind 的 TypeScript 类型仅为 "gallery" | "novels" | "alerts",不包含 "manga"。

第 31 行的标题映射也缺少 manga:

const title = computed(() => ({ gallery: "图片", novels: "小说", alerts: "提醒中心" }[props.kind]));

第 41 行的 API 调用路径硬编码了 kind:

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)

// 在 /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)

<RouterLink to="/app/manga">漫画</RouterLink>
<!-- 插入在"图片"和"小说"之间 -->

步骤 3:UserListPage 增加 manga 支持

// 将 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() 逻辑中增加:

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 行

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 行

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 行

<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 行

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> 中增加分页状态:
const page = ref(1);
const limit = 30;
const total = ref(0);
const totalPages = ref(0);
  1. 修改 load() 方法,传入分页参数:
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;
  }
}
  1. 在模板底部增加分页控件:
<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>
  1. 搜索或切换 kind 时重置 page 为 1:
watch(() => props.kind, () => { page.value = 1; load(); });
// 搜索时也重置页码
function onSearch() { page.value = 1; load(); }

方案 B:后端 COUNT 查询优化(🔴 解决根本性能瓶颈)

修改位置: sakura_cloud/api/v1/endpoints/gallery.py 第 100 行

具体做法:

选项 1:使用估算计数(推荐,适用于"大概有多少条"的场景)

# 对于 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 查询,改为"是否有下一页"模式

# 查询 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 查询添加超时保护

# 设置 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. 增加防抖逻辑:
let debounceTimer: ReturnType<typeof setTimeout> | null = null;

function onSearchInput() {
  if (debounceTimer) clearTimeout(debounceTimer);
  debounceTimer = setTimeout(() => {
    page.value = 1;
    load();
  }, 400); // 400ms 防抖
}
  1. 修改模板,从 @keyup.enter 改为实时防抖:
<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 方法)

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 行

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 行

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 行

// 预置的 6 个精选源使用 example.invalid 占位 URL
const _seedSources = [
  _SeedSource(name: '全本玄幻小说', ...),
  _SeedSource(name: '笔趣阁', ...),
  // ...
];

这些内置源的 URL 是 https://example.invalid/...(不可访问的占位地址)。它们的作用仅仅是预留名称和 ID,真正的 URL 需要从在线源仓库导入后才能获得。如果用户没有手动导入源仓库,这 6 个默认源将永远返回空结果。

根因 5:5 秒超时可能不够(🟢)

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 感知的匹配方式。中文搜索在后端层面不应该有问题。

# gallery.py 中的搜索逻辑
condition = Artwork.title.ilike(f"%{search_text}%")

如果云库搜索不到中文内容,更可能是:

  • 云库中确实没有该关键词的内容(数据未同步或上传)
  • 移动端的 API 调用参数传递问题(下面分析)

根因 6:移动端 API 客户端未显式设置编码(🟡)

文件位置: sakura_mobile/lib/src/core/api_client.dart 第 13-19 行

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 行

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 行):

// 当前 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); // 保底:按字节原样保留
    }
  }
}
  1. 添加 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 秒超时),但仍存在问题:

_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 行

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 行

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 表添加复合索引:
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);
  1. 为 novels 表添加索引:
CREATE INDEX idx_novels_user_updated ON novels(user_id, updated_at DESC);
CREATE INDEX idx_novels_series ON novels(series_id, chapter_order);
  1. 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 凭证)