feat: 阅读页聚合显示嵌套 chapter 并修正分页与目录高亮

ES 中每个 chapter 节点仅保存「本节点→下一节点」之间的正文，选中含子
chapter 的父节点时只显示标题。改为：

- 新增 resolveDisplayRange()，按 chapter_strlen(阈值 30000)解析实际显示
  区间，过大则下钻到第一个不超过阈值的子 chapter；
- 新增 fetchRangeContent()，聚合区间内全部 chapter 节点的 ES display；
- read() 改用上述逻辑，comm 注释范围同步为整个显示区间；
- pagination() 复用同一区间解析，next/prev 改为以区间 end/start 为边界
  取相邻可导航段落(nextChapter/prevChapter)，修正章节边界处跳过标题页
  或落入子节点的问题；
- getBookToc() 支持 activeRange，聚合显示时高亮区间内所有 chapter。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

api-v13/app/Http/Controllers/Library/BookController.php

@@ -13,10 +13,19 @@ use App\Services\ChapterService;
 use App\Services\OpenSearchService;
 use App\Services\PaliTextService;
 use Illuminate\Http\Request;
+use Illuminate\Support\Collection;
 
 class BookController extends Controller
 {
-    protected $maxChapterLen = 50000;
+    /**
+     * chapter 聚合显示的字符数阈值。
+     *
+     * ES 中每个 chapter 节点只保存「本节点 → 下一节点」之间的正文，选中含子
+     * chapter 的父节点时其自身文档往往只有标题。显示时按本阈值决定聚合粒度：
+     * chapter_strlen 小于该值的节点，连同其覆盖区间内的所有子 chapter 一并展示；
+     * 超过该值则向下钻取第一个不超过阈值的子 chapter。
+     */
+    protected $maxChapterStrlen = 30000;
 
     protected $minChapterLen = 100;
 
@@ -95,23 +104,19 @@ class BookController extends Controller
     {
 
         $channelId = $request->input('channel');
-        $openSearchId = "tipitaka_chapter_{$id}_{$channelId}";
 
-        try {
-            $chapter = HitItemDTO::fromArray($this->searchService->get($openSearchId))->toArray();
-        } catch (\Throwable $th) {
-            $chapter = [
-                'category' => [],
-                'title' => '',
-                'display' => '',
+        [$bookId, $paraId] = explode('-', $id);
+        $bookId = (int) $bookId;
+        $paraId = (int) $paraId;
 
-            ];
-        }
+        // 解析选中 chapter 的实际显示区间，并聚合区间内全部 chapter 节点的 ES 内容，
+        // 避免选中父 chapter 时仅显示一个标题。
+        $range = $this->resolveDisplayRange($bookId, $paraId);
+        $chapter = $this->fetchRangeContent($bookId, $channelId, $range['chapters'], $id);
 
-        [$bookId, $paraId] = explode('-', $id);
         if ($request->has('comm')) {
-            $currChapter = $this->paliTextService->getCurrChapter($bookId, $paraId);
-            $commentaries = $this->fetchCommentary($bookId, $paraId, $paraId + $currChapter->chapter_len - 1, $request->input('comm'));
+            // 注释范围与显示区间保持一致（聚合后可能跨多个段落）
+            $commentaries = $this->fetchCommentary($bookId, $range['start'], $range['end'], $request->input('comm'));
             // sid 格式：{book_id}-{paragraph}-{word_start}-{word_end}
             $notesMap = collect($commentaries)->keyBy(function ($note) {
                 return "{$note['book_id']}-{$note['paragraph']}-{$note['word_start']}-{$note['word_end']}";
@@ -122,7 +127,7 @@ class BookController extends Controller
 
         $book = [];
 
-        $book['toc'] = $this->getBookToc((int) $bookId, (int) $paraId, $channelId, 2, 7);
+        $book['toc'] = $this->getBookToc($bookId, $paraId, $channelId, 2, 7, [$range['start'], $range['end']]);
         $channel = ChannelApi::getById($channelId);
         $studio = StudioApi::getById($channel['studio_id']);
         $book['categories'] = $chapter['category'];
@@ -130,9 +135,9 @@ class BookController extends Controller
         $book['author'] = $channel['name'];
         $book['studio'] = $studio;
         $book['tags'] = [];
-        $book['book_title'] = $this->getBookTitle((int) $bookId, (int) $paraId, $channelId);
+        $book['book_title'] = $this->getBookTitle($bookId, $paraId, $channelId);
 
-        $book['pagination'] = $this->pagination((int) $bookId, (int) $paraId, $channelId);
+        $book['pagination'] = $this->pagination($bookId, $paraId, $channelId);
 
         if (isset($notesMap)) {
             $book['content'] = $this->injectNoteMarkers($chapter['display'], $notesMap);
@@ -155,6 +160,103 @@ class BookController extends Controller
         return $view;
     }
 
+    /**
+     * 解析选中 chapter 的实际显示区间。
+     *
+     * ES 中每个 chapter 节点仅保存「本节点 → 下一节点」之间的正文，因此选中含
+     * 子 chapter 的父节点时其自身文档往往只有标题。为完整呈现内容，这里把选中
+     * chapter 覆盖区间内的所有 chapter 节点聚合为一个显示单元：
+     *  - 选中节点 chapter_strlen 不超过阈值：直接使用其覆盖区间
+     *    [paragraph, paragraph + chapter_len - 1]；
+     *  - 否则向后下钻，找到第一个不超过阈值的子 chapter，以该子 chapter 的结束
+     *    段落作为区间终点（起点仍为选中段落，保留上层标题作为阅读上下文）。
+     *
+     * @return array{current: PaliText, start: int, end: int, chapters: Collection<int, PaliText>}
+     */
+    private function resolveDisplayRange(int $book, int $para): array
+    {
+        $currBook = $this->bookStart($book, $para);
+        $bookStart = $currBook->paragraph;
+        $bookEnd = $currBook->paragraph + $currBook->chapter_len - 1;
+
+        // 本书内全部 chapter 节点（level < 8，即 book/chapter/subhead 等可导航节点）
+        $paragraphs = PaliText::where('book', $book)
+            ->whereBetween('paragraph', [$bookStart, $bookEnd])
+            ->where('level', '<', 8)
+            ->orderBy('paragraph')
+            ->get();
+
+        $curr = $paragraphs->firstWhere('paragraph', $para);
+        $current = $curr;
+        $endParagraph = $curr->paragraph + $curr->chapter_len - 1;
+
+        if ($curr->chapter_strlen > $this->maxChapterStrlen) {
+            // 选中节点过大：向后下钻，找到第一个不超过阈值的子 chapter
+            foreach ($paragraphs as $key => $paragraph) {
+                if ($paragraph->paragraph <= $curr->paragraph) {
+                    continue;
+                }
+                if ($paragraph->chapter_strlen <= $this->maxChapterStrlen) {
+                    $endParagraph = $paragraph->paragraph + $paragraph->chapter_len - 1;
+                    $current = $paragraph;
+                    break;
+                }
+                if ($paragraph->level <= $curr->level) {
+                    // 已离开选中节点的子树，无法继续下钻，止步于上一个节点
+                    $endParagraph = $paragraphs[$key - 1]->paragraph + $paragraphs[$key - 1]->chapter_len - 1;
+                    $current = $paragraph;
+                    break;
+                }
+            }
+        }
+
+        $start = $curr->paragraph;
+        $end = $endParagraph;
+
+        // 区间内的全部 chapter 节点，用于聚合 ES 内容
+        $chapters = $paragraphs->filter(function ($paragraph) use ($start, $end) {
+            return $paragraph->paragraph >= $start && $paragraph->paragraph <= $end;
+        })->values();
+
+        return compact('current', 'start', 'end', 'chapters');
+    }
+
+    /**
+     * 聚合区间内全部 chapter 节点的 ES 内容。
+     *
+     * 逐个按 ES 文档 id（tipitaka_chapter_{book}-{paragraph}_{channel}）获取并按段落
+     * 顺序拼接 display；缺失或获取失败的节点跳过。选中（即传入 $selectedId 的）
+     * 节点同时提供页面标题与分类。
+     *
+     * @param  Collection<int, PaliText>  $chapters
+     * @return array{display: string, title: string, category: array}
+     */
+    private function fetchRangeContent(int $book, string $channelId, $chapters, string $selectedId): array
+    {
+        $display = '';
+        $title = '';
+        $category = [];
+
+        foreach ($chapters as $chapter) {
+            $openSearchId = "tipitaka_chapter_{$book}-{$chapter->paragraph}_{$channelId}";
+
+            try {
+                $doc = HitItemDTO::fromArray($this->searchService->get($openSearchId))->toArray();
+            } catch (\Throwable $th) {
+                continue;
+            }
+
+            $display .= $doc['display'] ?? '';
+
+            if ("{$book}-{$chapter->paragraph}" === $selectedId) {
+                $title = $doc['title'] ?? '';
+                $category = $doc['category'] ?? [];
+            }
+        }
+
+        return compact('display', 'title', 'category');
+    }
+
     private function loadBook(string $id)
     {
         $book = ProgressChapter::with('channel.owner')->find($id);
@@ -207,7 +309,12 @@ class BookController extends Controller
         return $title;
     }
 
-    private function getBookToc(int $book, int $paragraph, string $channelId, $minLevel = 2, $maxLevel = 2): array
+    /**
+     * @param  array{0: int, 1: int}|null  $activeRange  实际显示的段落区间 [start, end]；
+     *                                                   传入时区间内的所有 chapter 均高亮（active），
+     *                                                   用于聚合显示多个 chapter 的场景。不传则仅高亮选中段落。
+     */
+    private function getBookToc(int $book, int $paragraph, string $channelId, $minLevel = 2, $maxLevel = 2, ?array $activeRange = null): array
     {
         $currBook = $this->bookStart($book, $paragraph);
 
@@ -265,7 +372,7 @@ class BookController extends Controller
         // 顶层 level（列表中最浅的一层，折叠模式下始终可见）
         $topLevel = (int) $paliTexts->min('level');
 
-        return $paliTexts->map(function ($paliText) use ($chaptersIndexed, $channelId, $currentId, $parents, $expandParentSet, $topLevel) {
+        return $paliTexts->map(function ($paliText) use ($chaptersIndexed, $channelId, $currentId, $parents, $expandParentSet, $topLevel, $activeRange) {
             $id = "{$paliText->book}-{$paliText->paragraph}";
             $level = (int) $paliText->level;
             $title = $paliText->toc;
@@ -291,6 +398,11 @@ class BookController extends Controller
             $visible = $level === $topLevel
                 || ($parentId !== null && isset($expandParentSet[$parentId]));
 
+            // 聚合显示时高亮区间内所有 chapter，否则仅高亮选中段落
+            $active = $activeRange !== null
+                ? ($paliText->paragraph >= $activeRange[0] && $paliText->paragraph <= $activeRange[1])
+                : ($id === $currentId);
+
             return [
                 'id' => $id,
                 'channel' => $channelId,
@@ -299,7 +411,7 @@ class BookController extends Controller
                 'progress' => $progress,
                 'level' => $level,
                 'disabled' => $disabled,
-                'active' => $id === $currentId,
+                'active' => $active,
                 'hide' => ! $visible,
             ];
         })->all();
@@ -330,40 +442,17 @@ class BookController extends Controller
 
     public function pagination(int $book, int $para, string $channelId)
     {
-        $currBook = $this->bookStart($book, $para);
-        $start = $currBook->paragraph;
-        $end = $currBook->paragraph + $currBook->chapter_len - 1;
-        // 查询起始段落
-        $paragraphs = PaliText::where('book', $book)
-            ->whereBetween('paragraph', [$start, $end])
-            ->where('level', '<', 8)
-            ->orderBy('paragraph')
-            ->get();
-        $curr = $paragraphs->firstWhere('paragraph', $para);
-        $current = $curr; // 实际显示的段落
-        $endParagraph = $curr->paragraph + $curr->chapter_len - 1;
-        if ($curr->chapter_strlen > $this->maxChapterLen) {
-            // 太大了，修改结束位置 找到下一级
-            foreach ($paragraphs as $key => $paragraph) {
-                if ($paragraph->paragraph > $curr->paragraph) {
-                    if ($paragraph->chapter_strlen <= $this->maxChapterLen) {
-                        $endParagraph = $paragraph->paragraph + $paragraph->chapter_len - 1;
-                        $current = $paragraph;
-                        break;
-                    }
-                    if ($paragraph->level <= $curr->level) {
-                        // 不能往下走了，就是它了
-                        $endParagraph = $paragraphs[$key - 1]->paragraph + $paragraphs[$key - 1]->chapter_len - 1;
-                        $current = $paragraph;
-                        break;
-                    }
-                }
-            }
-        }
-        $start = $curr->paragraph;
-        $end = $endParagraph;
-        $nextPali = $this->next($current->book, $current->paragraph, $current->level);
-        $prevPali = $this->prev($current->book, $current->paragraph, $current->level);
+        // 与正文显示共用同一区间解析，保证分页边界与实际展示内容一致
+        $range = $this->resolveDisplayRange($book, $para);
+        $start = $range['start'];
+        $end = $range['end'];
+
+        // next/prev 以显示区间为边界，而非某个节点的层级：
+        // 聚合显示子 chapter 时，下一页应是区间 end 之后的第一个可导航段落，
+        // 上一页应是区间 start 之前最近的可导航段落。若按 current 的 level 取同级节点，
+        // 会在章节边界处跳过父级标题页或落入子节点。
+        $nextPali = $this->nextChapter($book, $end);
+        $prevPali = $this->prevChapter($book, $start);
 
         $next = null;
         if ($nextPali) {
@@ -402,26 +491,28 @@ class BookController extends Controller
         return compact('start', 'end', 'next', 'prev');
     }
 
-    public function next($book, $paragraph, $level)
+    /**
+     * 显示区间之后的第一个可导航 chapter 节点（level < 8）。
+     */
+    public function nextChapter(int $book, int $endParagraph): ?PaliText
     {
-        $next = PaliText::where('book', $book)
-            ->where('paragraph', '>', $paragraph)
-            ->where('level', $level)
+        return PaliText::where('book', $book)
+            ->where('paragraph', '>', $endParagraph)
+            ->where('level', '<', 8)
             ->orderBy('paragraph')
             ->first();
-
-        return $next ?? null;
     }
 
-    public function prev($book, $paragraph, $level)
+    /**
+     * 显示区间之前最近的一个可导航 chapter 节点（level < 8）。
+     */
+    public function prevChapter(int $book, int $startParagraph): ?PaliText
     {
-        $prev = PaliText::where('book', $book)
-            ->where('paragraph', '<', $paragraph)
-            ->where('level', $level)
+        return PaliText::where('book', $book)
+            ->where('paragraph', '<', $startParagraph)
+            ->where('level', '<', 8)
             ->orderBy('paragraph', 'desc')
             ->first();
-
-        return $prev ?? null;
     }
 
     public function show2($id)