17 KiB
小说与漫画三级层级展示 —— 前端改造方案
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 而缓存为空时,按以下步骤回退:
- 调用
GET /me/gallery?content_type=manga&limit=200 - 对返回的 rows 执行与
UserListPage.groupManga()完全一致的分组逻辑 - 在所有分组结果中查找
seriesKey匹配的组(匹配规则同构造规则) - 找到后填充页面
- 未找到则显示错误:"未找到该系列的章节"
这样保证了不管是从 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 执行 normalizekind="manga":- 优先读
mangaSeriesCache[seriesKey] - 缓存命中且 chapters 不为空 → 直接展示
- 缓存未命中或 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/seriesparams()对 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 后不再需要前端分页(后端一次返回所有系列),因此:
supportsPaginationcomputed 对 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 缺失时省略中间级
验证方案
- Level 1 → Level 2 导航:访问
/app/novels,点击任意作品卡片,确认跳转到/app/novels/series/:seriesId,且显示正确的章节列表 - Level 2 → Level 3 导航:在章节列表页点击某一章,确认跳转到
/app/novels/read/:id?fromSeries=:seriesId,正文正常显示 - 面包屑返回:在阅读器中点击面包屑"章节列表",确认返回 Level 2;点击"← 返回",确认能正常回退
- 面包屑 fallback:直接访问
/app/novels/read/:id(无 fromSeries),确认面包屑不显示中间级,返回按钮回到/app/novels - 漫画缓存链路:从 Level 1 → Level 2 → Level 3 完整走通漫画导航
- 漫画缓存缺失回退:清除缓存后直接访问
/app/manga/series/:seriesKey,确认自动回退到 API 拉取并正确展示 - 漫画 series_id 缺失:对没有
artwork_metadata.series_id的漫画数据,确认 seriesKey 回退到manga-title-{series_title}且导航正常 - Level 2 空状态:对章节数为 0 的系列(理论上不应出现,但做防御),确认显示"暂无章节"
- Level 2 错误状态:模拟 API 失败,确认显示错误信息 + 重试按钮
- 不受影响的功能:图片(gallery)、提醒(alerts)、个人资料(profile)页面仍正常运作
- 旧路由兼容:访问
/app/novels/旧id确认重定向到/app/novels/read/旧id - 管理后台不受影响:
/admin/novels、/admin/gallery表格正常