Files
SakuraHub/docs/Web端小说与漫画页面优化方案.md
T
2026-11-16 20:45:22 +08:00

17 KiB
Raw Blame History

小说与漫画三级层级展示 —— 前端改造方案

Context

当前 sakura_admin_web 的小说和漫画展示是 2 级扁平结构:列表页将同一部作品的章节折叠为一张"作品卡片",点击直接跳转到单章阅读器。用户无法浏览"一本书下面有哪些章节"这个中间层。

本方案将漫画和小说改为 3 级层级导航:

Level 1 (系列列表)  →  Level 2 (章节列表)  →  Level 3 (内容阅读)

后端 API 现状与数据模型

Novel(小说)

  • 有专用 series API:GET /novels/series(列表)、GET /novels/series/{series_id}(单系列含全部章节)
  • NovelSeriesGroup 包含:series_id, series_title, author, chapter_count, cover_path, chapters[]
  • 每个 chapter(NovelOut)有:id, title, chapter_title, chapter_order, updated_at
  • 当前前端调的是 GET /me/novels(扁平 rows),客户端自己 groupNovels()

Manga/Comic(漫画)

  • 无专用 series API,漫画存储为 Artwork 行(content_type="manga")
  • 系列分组依赖 JSON 字段 artwork_metadata.series_id / artwork_metadata.series_title
  • 当前前端调用 GET /me/gallery?content_type=manga,客户端 groupManga() 分组
  • 需要在客户端缓存分组数据,供 Level 2 页面使用

关键设计决策(必读)

1. 漫画 seriesKey 稳定性规则

seriesKey 是 Level 1 跳 Level 2 的路由参数,也是缓存的索引,必须稳定且防冲突。

构造规则(优先级从高到低):

seriesKey = series_id
  ? `manga-${series_id}`
  : `manga-title-${series_title || title}`

说明:

  • 优先用 artwork_metadata.series_id,它最稳定
  • series_id 缺失时用 series_title || title 回退,加 manga-title- 前缀避免与 manga- 冲突
  • 所有来源的值都要 trim()
  • URL 传递时使用 encodeURIComponent(seriesKey),接收端用 Vue Router 自动解码后的值

2. 小说 series_id 类型统一

后端可能返回数字或字符串类型的 series_id。所有地方必须统一转成字符串:

seriesId: String(item.series_id)

原因:Vue Router 的 :seriesId 参数总是字符串,如果缓存 key 或比较逻辑里混了数字类型,会导致匹配失败。

3. 漫画缓存缺失回退流程(明确)

当用户直接访问 /app/manga/series/:seriesKey 而缓存为空时,按以下步骤回退:

  1. 调用 GET /me/gallery?content_type=manga&limit=200
  2. 对返回的 rows 执行与 UserListPage.groupManga() 完全一致的分组逻辑
  3. 在所有分组结果中查找 seriesKey 匹配的组(匹配规则同构造规则)
  4. 找到后填充页面
  5. 未找到则显示错误:"未找到该系列的章节"

这样保证了不管是从 Level 1 正常导航进来,还是直接访问 URL,显示结果一致。

4. Level 3 返回逻辑的 fallback

阅读器中通过 fromSeries query 参数构建"返回章节列表"链接:

if (fromSeries) → /app/${kind}/series/${fromSeries}
else            → /app/${kind}  (返回系列列表)

面包屑中间的"章节列表"链接同理——没有 fromSeries 时不渲染该级面包屑,直接从 Level 1 跳到 Level 3。

5. 路由顺序严格要求

/app 下的漫画和小说子路由必须按以下顺序注册(顺序错会导致路由匹配错误):

1.  manga                           ← Level 1
2.  manga/series/:seriesKey         ← Level 2(固定路径段优先)
3.  manga/read/:id                  ← Level 3(固定路径段优先)
4.  manga/:id  → redirect           ← 旧路由兼容,放最后
5.  novels                          ← Level 1
6.  novels/series/:seriesId         ← Level 2(固定路径段优先)
7.  novels/read/:id                 ← Level 3(固定路径段优先)
8.  novels/:id  → redirect          ← 旧路由兼容,放最后

原理:manga/series/:seriesKey 有固定前缀 series/,如果放在 manga/:id 之后,Vue Router 会把 series 当成 :id 的值匹配进去。固定路径段必须排在动态 :id 前面。

6. 章节数据 normalize

不同来源的章节字段命名不一致(漫画在 artwork_metadata 里嵌套、小说是顶层字段),建议统一写一个 normalize 函数,不要在各处散着取字段。

小说章节 normalize(输入:NovelOut):

要取的字段 取值路径
id String(item.id)
title item.chapter_title || item.title || "未命名章节"
order Number(item.chapter_order || 0)
updated_at item.updated_at || ""

漫画章节 normalize(输入:ArtworkOut 单行):

要取的字段 取值路径
id String(item.id)
title item.title || item.artwork_metadata?.chapter_title || "未命名章节"
order Number(item.artwork_metadata?.chapter_order || 0)
page_count Number(item.page_count || 1)
thumbnail_url item.thumbnail_url || ""
updated_at item.updated_at || ""

在 UserListPage.groupManga() 和 UserChapterListPage.loadMangaSeries() 中都应使用同一套 normalize。

7. Level 2 的状态覆盖

UserChapterListPage 必须覆盖以下四种状态,否则直接访问 URL 时体验差:

状态 条件 UI
加载中 loading === true "正在加载章节..."
加载失败 error !== "" 显示错误信息,带"重试"按钮
空章节 !loading && !error && chapters.length === 0 "暂无章节"
缓存失效重载 manga 缓存命空 → 自动触发 API 回退 "正在重新加载..."(过渡态)

路由改造

新路由结构

文件: src/router/index.ts —— 修改

修改前(2 级)                       修改后(3 级)
─────────────────                   ─────────────────
/app/novels                         /app/novels                    ← Level 1 系列列表
/app/novels/:id                     /app/novels/series/:seriesId   ← Level 2 章节列表(新)
                                    /app/novels/read/:id           ← Level 3 阅读器(原 /novels/:id)

/app/manga                          /app/manga                     ← Level 1 系列列表
/app/manga/:id                      /app/manga/series/:seriesKey   ← Level 2 章节列表(新)
                                    /app/manga/read/:id            ← Level 3 详情(原 /manga/:id)

路由注册顺序(严格):

// 漫画
{ path: "manga", component: UserListPage, props: { kind: "manga" } },
{ path: "manga/series/:seriesKey", component: UserChapterListPage, props: (route) => ({ kind: "manga", seriesKey: route.params.seriesKey }) },
{ path: "manga/read/:id", component: UserDetailPage, props: (route) => ({ kind: "manga", id: route.params.id }) },
// 小说
{ path: "novels", component: UserListPage, props: { kind: "novels" } },
{ path: "novels/series/:seriesId", component: UserChapterListPage, props: (route) => ({ kind: "novels", seriesId: route.params.seriesId }) },
{ path: "novels/read/:id", component: UserDetailPage, props: (route) => ({ kind: "novels", id: route.params.id }) },
// 旧路由重定向(必须放最后)
{ path: "manga/:id", redirect: (to) => `/app/manga/read/${to.params.id}` },
{ path: "novels/:id", redirect: (to) => `/app/novels/read/${to.params.id}` },

改造清单

一、新建文件

1. src/stores/seriesCache.ts —— 漫画系列缓存

为何需要: 后端没有 manga series 端点。Level 1 页面做完客户端分组后,需要把分组数据传给 Level 2 页面。使用 Vue reactive() 对象做跨组件共享缓存。

// 核心结构
interface MangaChapterCacheEntry {
  id: string            // gallery item id
  title: string         // 章节标题(normalize 后)
  page_count: number    // 页数
  thumbnail_url: string // 缩略图
  updated_at: string    // 更新时间
}

interface MangaSeriesCacheEntry {
  seriesKey: string                 // 唯一标识(按"关键设计决策 1"构造)
  seriesTitle: string               // 系列标题
  coverUrl: string                  // 封面图
  author: string                    // 作者
  chapters: MangaChapterCacheEntry[] // 该系列下所有章节(已 normalize 且按 order 排序)
}
// 导出 mangaSeriesCache: reactive<Record<string, MangaSeriesCacheEntry>>
// 导出 clearMangaCache(): void

2. src/views/app/UserChapterListPage.vue —— 章节列表页(Level 2)

复用项目 pattern: 通过 kind prop 同时支持 novels 和 manga。

Props:

{
  kind: "novels" | "manga"
  seriesId?: string    // novels: 后端 series_id(统一 String 类型)
  seriesKey?: string   // manga: 客户端分组 key
}

模板结构:

  • 面包屑导航:小说/漫画 > 系列标题
  • "← 返回" 按钮(router.back())
  • 四种状态覆盖:
    • 加载中 → "正在加载章节..."
    • 加载失败 → error 文本 + 重试按钮
    • 空章节 → "暂无章节"(加载成功但 chapters 为空)
    • 缓存失效重载 → manga 缓存命中但 chapters 为空时,自动切到 API 回退
  • 系列信息头:封面 + 标题 + 作者 + 章节数
  • 章节列表:每行显示序号 | 章节标题 | 页数/更新时间 | →

数据加载:

  • kind="novels":调用 GET /novels/series/{seriesId},对返回的 chapters 执行 normalize
  • kind="manga":
    1. 优先读 mangaSeriesCache[seriesKey]
    2. 缓存命中且 chapters 不为空 → 直接展示
    3. 缓存未命中或 chapters 为空 → 按"关键设计决策 3"执行 API 回退

跳转到 Level 3: /app/{kind}/read/{id}?fromSeries={encodedSeriesRef}


二、修改现有文件

3. src/views/app/UserListPage.vue —— 系列列表页(Level 1)

3.1 novels 加载改为 /novels/series

当前 load() → GET /me/novels → groupNovels()。改为:

  • endpoint() 对 novels 返回 /novels/series
  • params() 对 novels 传 { include_chapters: false }(后端返回轻量 series 摘要)
  • groupNovels() 直接从 series 数据映射 WorkGroup,不再做客户端分组
  • WorkGroup 新增 seriesId: String(series.series_id) 字段
3.2 manga 加载保持 /me/gallery,增强分组逻辑
  • 按照"关键设计决策 1"构造稳定的 seriesKey
  • 构建 WorkGroup 时同步写入 mangaSeriesCache[seriesKey]
  • 缓存中的 chapters 按"关键设计决策 6"的 normalize 规则统一格式,并已按 order 排序
  • WorkGroup 新增 seriesKey 字段
3.3 detailUrl 修改
// 修改前:直接跳阅读器
function detailUrl(id: string) { return `/app/${props.kind}/${id}` }

// 修改后:跳章节列表页
function detailUrl(group: WorkGroup): string {
  if (kind === "novels") return `/app/novels/series/${group.seriesId}`
  if (kind === "manga")  return `/app/manga/series/${encodeURIComponent(group.seriesKey!)}`
  ...
}

// 为 gallery / alerts 保留原始逻辑
function detailUrlById(id: string): string {
  return `/app/${props.kind}/${id}`
}
3.4 WorkGroup 类型扩展
type WorkGroup = {
  // ... 原有字段
  seriesKey?: string   // manga 用(稳定构造)
  seriesId?: string    // novels 用(统一 String)
}
3.5 分页调整

novels 改用 /novels/series 后不再需要前端分页(后端一次返回所有系列),因此:

  • supportsPagination computed 对 novels 返回 false
  • 隐藏分页控件

4. src/views/app/UserDetailPage.vue —— 阅读器页(Level 3)

  • 新增面包屑导航(仅 novels/manga):
    • 始终显示:小说/漫画 > 当前章节标题
    • fromSeries 存在时插入中间级:小说/漫画 > [章节列表] > 当前章节标题
  • 新增返回按钮:"← 返回"($router.back())
  • fromSeries 参数处理(按"关键设计决策 4"):
    const fromSeries = computed(() => String(route.query.fromSeries || ""))
    const backToListRoute = computed(() => {
      if (fromSeries.value) return `/app/${props.kind}/series/${fromSeries.value}`
      return `/app/${props.kind}`  // fallback 到系列列表
    })
    
  • 原有阅读器/详情逻辑不变

5. src/router/index.ts —— 路由配置

  • 新增 UserChapterListPage 导入
  • 新增 4 条路由(novels/manga 的 series 和 read),严格按照"关键设计决策 5"的顺序排列
  • 末尾添加 2 条旧路由重定向

三、CSS 新增样式

文件: src/styles.css —— 追加

样式类 用途
.breadcrumb 面包屑导航容器(flex, 小字号 muted)
.breadcrumb a 面包屑链接(pink-strong, hover opacity)
.breadcrumb .current 当前页名(ink, bold)
.series-header 章节列表页的系列信息头(flex, 封面+标题+作者+统计)
.series-cover 系列封面图(110px 宽, 3:4 比例)
.series-cover.placeholder 封面色块占位(粉色背景, 居中文字)
.series-info 系列元信息容器
.series-info h2 系列标题(ellipsis 溢出省略)
.chapter-list 章节列表网格(gap 8px)
.chapter-row 单行章节(flex, hover 阴影+边框变色)
.chapter-row .chapter-index 圆形粉色序号标识(36px 圆, number)
.chapter-row .chapter-info 章节标题与元信息(flex 收缩, ellipsis)
.chapter-row .chapter-info strong 章节标题
.chapter-row .chapter-info .muted 页数 / 更新时间的灰色副文本

数据流示意

小说

UserListPage ──GET /novels/series?include_chapters=false──→ [{ series_id, chapter_count, cover_path }]
     │  seriesId = String(series_id)
     │  点击卡片 → /app/novels/series/:seriesId
     ▼
UserChapterListPage ──GET /novels/series/:id──→ { chapters: [{id, chapter_title, ...}] }
     │  对 chapters 执行 normalize
     │  点击章节 → /app/novels/read/:id?fromSeries=:seriesId
     ▼
UserDetailPage ──GET /novels/:id/content──→ 正文阅读
     │  面包屑:小说 > [章节列表] > 当前章名
     │  fromSeries 缺失时省略中间级

漫画

UserListPage ──GET /me/gallery?content_type=manga──→ client groupManga()
     │  seriesKey 按稳定规则构造(series_id 优先)
     │  章节按 normalize 统一格式、排序
     │  └→ 写入 mangaSeriesCache[seriesKey]
     │  点击卡片 → /app/manga/series/:seriesKey(encoded)
     ▼
UserChapterListPage ──读 mangaSeriesCache[seriesKey]──→ 展示
     │  缓存未命中或 chapters 为空:
     │    ① GET /me/gallery?content_type=manga&limit=200
     │    ② 执行同一套 groupManga() 分组逻辑
     │    ③ 查找匹配 seriesKey 的组
     │    ④ 找到 → 填充;未找到 → 显示错误
     │  点击章节 → /app/manga/read/:id?fromSeries=:seriesKey(encoded)
     ▼
UserDetailPage ──GET /gallery/:id──→ 详情展示
     │  面包屑:漫画 > [章节列表] > 当前章名
     │  fromSeries 缺失时省略中间级

验证方案

  1. Level 1 → Level 2 导航:访问 /app/novels,点击任意作品卡片,确认跳转到 /app/novels/series/:seriesId,且显示正确的章节列表
  2. Level 2 → Level 3 导航:在章节列表页点击某一章,确认跳转到 /app/novels/read/:id?fromSeries=:seriesId,正文正常显示
  3. 面包屑返回:在阅读器中点击面包屑"章节列表",确认返回 Level 2;点击"← 返回",确认能正常回退
  4. 面包屑 fallback:直接访问 /app/novels/read/:id(无 fromSeries),确认面包屑不显示中间级,返回按钮回到 /app/novels
  5. 漫画缓存链路:从 Level 1 → Level 2 → Level 3 完整走通漫画导航
  6. 漫画缓存缺失回退:清除缓存后直接访问 /app/manga/series/:seriesKey,确认自动回退到 API 拉取并正确展示
  7. 漫画 series_id 缺失:对没有 artwork_metadata.series_id 的漫画数据,确认 seriesKey 回退到 manga-title-{series_title} 且导航正常
  8. Level 2 空状态:对章节数为 0 的系列(理论上不应出现,但做防御),确认显示"暂无章节"
  9. Level 2 错误状态:模拟 API 失败,确认显示错误信息 + 重试按钮
  10. 不受影响的功能:图片(gallery)、提醒(alerts)、个人资料(profile)页面仍正常运作
  11. 旧路由兼容:访问 /app/novels/旧id 确认重定向到 /app/novels/read/旧id
  12. 管理后台不受影响:/admin/novels、/admin/gallery 表格正常