first commit

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kunkunxiaomaoandClaude committed 2026-11-16 20:45:22 +08:00
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` 表格正常