# 小说与漫画三级层级展示 —— 前端改造方案 ## 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> // 导出 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` 表格正常