commit
9c5fef1a4d
412 files changed
+94582
No files matched your search
@@ -0,0 +1,393 @@
|
||||
# 小说与漫画三级层级展示 —— 前端改造方案
|
||||
|
||||
## 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` 表格正常
|
||||
Reference in new issue
Block a user