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

394 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 小说与漫画三级层级展示 —— 前端改造方案
## 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)
```
**路由注册顺序(严格):**
```ts
// 漫画
{ 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()` 对象做跨组件共享缓存。
```ts
// 核心结构
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:**
```ts
{
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 修改
```ts
// 修改前:直接跳阅读器
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 类型扩展
```ts
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"):
```ts
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` 表格正常