mint/api-v13/app/Services/PaliContentService.php

<?php

// api-v8/app/Services/PaliContentService.php

namespace App\Services;

use App\Facades\RedisCache;
use App\Http\Api\ChannelApi;
use App\Http\Api\MdRender;
use App\Http\Api\StudioApi;
use App\Http\Api\SuggestionApi;
use App\Http\Api\UserApi;
use App\Models\Channel;
use App\Models\Discussion;
use App\Models\PaliSentence;
use App\Models\PaliText;
use App\Models\Sentence;
use App\Models\SentSimIndex;
use App\Models\Wbw;
use App\Models\WbwBlock;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;

class PaliContentService
{
    protected $result = [
        'uid' => '',
        'title' => '',
        'path' => [],
        'sub_title' => '',
        'summary' => '',
        'content' => '',
        'content_type' => 'html',
        'toc' => [],
        'status' => 30,
        'lang' => '',
        'created_at' => '',
        'updated_at' => '',
    ];

    protected $wbwChannels = [];

    // 句子需要查询的列
    protected $selectCol = [
        'uid',
        'book_id',
        'paragraph',
        'word_start',
        'word_end',
        'channel_uid',
        'content',
        'content_type',
        'editor_uid',
        'acceptor_uid',
        'pr_edit_at',
        'fork_at',
        'create_time',
        'modify_time',
        'created_at',
        'updated_at',
    ];

    protected $userUuid = null;

    protected $debug = [];

    public static function _sentCanReadCount($book, $para, $start, $end, $userUuid = null)
    {
        $keyCanRead = '/channel/can-read/';
        if ($userUuid) {
            $keyCanRead .= $userUuid;
        } else {
            $keyCanRead .= 'guest';
        }
        $channelCanRead = RedisCache::remember(
            $keyCanRead,
            config('mint.cache.expire'),
            function () use ($userUuid) {
                return ChannelApi::getCanReadByUser($userUuid);
            }
        );
        $channels = Sentence::where('book_id', $book)
            ->where('paragraph', $para)
            ->where('word_start', $start)
            ->where('word_end', $end)
            ->where('strlen', '<>', 0)
            ->whereIn('channel_uid', $channelCanRead)
            ->select('channel_uid')
            ->groupBy('channel_uid')
            ->get();
        $channelList = [];
        foreach ($channels as $key => $value) {
            // code...
            if (Str::isUuid($value->channel_uid)) {
                $channelList[] = $value->channel_uid;
            }
        }
        $simId = PaliSentence::where('book', $book)
            ->where('paragraph', $para)
            ->where('word_begin', $start)
            ->where('word_end', $end)
            ->value('id');
        if ($simId) {
            $output['simNum'] = SentSimIndex::where('sent_id', $simId)->value('count');
        } else {
            $output['simNum'] = 0;
        }
        $channelInfo = Channel::whereIn('uid', $channelList)->select('type')->get();
        $output['tranNum'] = 0;
        $output['nissayaNum'] = 0;
        $output['commNum'] = 0;
        $output['originNum'] = 0;

        foreach ($channelInfo as $key => $value) {
            // code...
            switch ($value->type) {
                case 'translation':
                    $output['tranNum']++;
                    break;
                case 'nissaya':
                    $output['nissayaNum']++;
                    break;
                case 'commentary':
                    $output['commNum']++;
                    break;
                case 'original':
                    $output['originNum']++;
                    break;
            }
        }

        return $output;
    }

    private function newSent($book, $para, $word_start, $word_end)
    {
        $sent = [
            'id' => "{$book}-{$para}-{$word_start}-{$word_end}",
            'book' => $book,
            'para' => $para,
            'wordStart' => $word_start,
            'wordEnd' => $word_end,
            'origin' => [],
            'translation' => [],
            'commentaries' => [],
        ];

        if ($book < 1000) {
            // 生成channel 数量列表
            $sentId = "{$book}-{$para}-{$word_start}-{$word_end}";
            $channelCount = self::_sentCanReadCount($book, $para, $word_start, $word_end, $this->userUuid);
            $path = json_decode(PaliText::where('book', $book)->where('paragraph', $para)->value('path'), true);
            $sent['path'] = [];
            foreach ($path as $key => $value) {
                // code...
                $value['paliTitle'] = $value['title'];
                $sent['path'][] = $value;
            }
            $sent['tranNum'] = $channelCount['tranNum'];
            $sent['nissayaNum'] = $channelCount['nissayaNum'];
            $sent['commNum'] = $channelCount['commNum'];
            $sent['originNum'] = $channelCount['originNum'];
            $sent['simNum'] = $channelCount['simNum'];
        }

        return $sent;
    }

    /**
     * 根据句子库数据生成以段落为单位的文章内容
     * $record 句子数据
     * $mode read | edit | wbw
     * $indexChannel channel索引
     * $indexedHeading 标题索引 用于给段落加标题标签 <h1> ect.
     */
    public function makeContentObj($record, $mode, $indexChannel, $format = 'react')
    {
        $content = [];

        // 逐词解析（wbw）默认使用第一个 translation channel 的数据。
        // 系统原文 channel 固定在末尾（见 CorpusController / ChapterContentController 的约定），
        // 这里从 indexChannel 挑出 translation channel 作为 wbw 的读写目标；
        // 没有 translation channel 时（如直接编辑系统原文）保持为空，回落到系统原文。
        $this->wbwChannels = [];
        foreach ($indexChannel as $channelId => $info) {
            if ($info->type === 'translation') {
                $this->wbwChannels[] = $channelId;
                break;
            }
        }

        // 获取句子编号列表
        $paraIndex = [];
        foreach ($record as $value) {
            $currSentId = "{$value->book_id}-{$value->paragraph}-{$value->word_start}-{$value->word_end}";
            $value->sid = "{$currSentId}_{$value->channel_uid}";

            $currParaId = "{$value->book_id}-{$value->paragraph}";
            if (! isset($paraIndex[$currParaId])) {
                $paraIndex[$currParaId] = [];
            }
            $paraIndex[$currParaId][] = $value;
        }
        $channelsId = [];
        foreach ($indexChannel as $channelId => $info) {
            $channelsId[] = $channelId;
        }
        array_pop($channelsId);
        // 遍历列表查找每个句子的所有channel的数据，并填充
        $paragraphs = [];
        foreach ($paraIndex as $currParaId => $sentData) {
            $arrParaId = explode('-', $currParaId);
            $sentIndex = [];
            foreach ($sentData as $sent) {
                $currSentId = "{$sent->book_id}-{$sent->paragraph}-{$sent->word_start}-{$sent->word_end}";
                $sentIndex[$currSentId] = [$sent->book_id, $sent->paragraph, $sent->word_start, $sent->word_end];
            }
            $sentInPara = array_values($sentIndex);
            $paraProps = [
                'book' => $arrParaId[0],
                'para' => $arrParaId[1],
                'channels' => $channelsId,
                'sentences' => $sentInPara,
                'mode' => $mode,
                'children' => [],
            ];
            // 建立段落里面的句子列表
            foreach ($sentIndex as $ids => $arrSentId) {
                $sentNode = $this->newSent($arrSentId[0], $arrSentId[1], $arrSentId[2], $arrSentId[3]);
                foreach ($indexChannel as $channelId => $info) {
                    // code...
                    $sid = "{$ids}_{$channelId}";
                    if (isset($info->studio)) {
                        $studioInfo = $info->studio;
                    } else {
                        $studioInfo = null;
                    }
                    $newSent = [
                        'content' => '',
                        'html' => '',
                        'book' => $arrSentId[0],
                        'para' => $arrSentId[1],
                        'wordStart' => $arrSentId[2],
                        'wordEnd' => $arrSentId[3],
                        'channel' => [
                            'name' => $info->name,
                            'type' => $info->type,
                            'id' => $info->uid,
                            'lang' => $info->lang,
                        ],
                        'studio' => $studioInfo,
                        'updateAt' => '',
                        'suggestionCount' => SuggestionApi::getCountBySent($arrSentId[0], $arrSentId[1], $arrSentId[2], $arrSentId[3], $channelId),
                    ];

                    $row = Arr::first($sentData, function ($value, $key) use ($sid) {
                        return $value->sid === $sid;
                    });
                    if ($row) {
                        $newSent['id'] = $row->uid;
                        $newSent['content'] = $row->content;
                        $newSent['contentType'] = $row->content_type;
                        $newSent['html'] = '';
                        $newSent['editor'] = UserApi::getByUuid($row->editor_uid);
                        /**
                         * TODO 刷库改数据
                         * 旧版api没有更新updated_at所以造成旧版的数据updated_at数据比modify_time 要晚
                         */
                        $newSent['forkAt'] = $row->fork_at; //
                        $newSent['updateAt'] = $row->updated_at; //
                        $newSent['updateAt'] = date('Y-m-d H:i:s.', $row->modify_time / 1000).($row->modify_time % 1000).' UTC';

                        $newSent['createdAt'] = $row->created_at;
                        if ($mode !== 'read') {
                            if (isset($row->acceptor_uid) && ! empty($row->acceptor_uid)) {
                                $newSent['acceptor'] = UserApi::getByUuid($row->acceptor_uid);
                                $newSent['prEditAt'] = $row->pr_edit_at;
                            }
                        }
                        switch ($info->type) {
                            case 'wbw':
                            case 'original':
                                //
                                // 在编辑模式下。
                                // 如果是原文，查看是否有逐词解析数据，
                                // 有的话优先显示。
                                // 阅读模式直接显示html原文
                                // 传过来的数据一定有一个原文channel
                                //
                                if ($mode === 'read') {
                                    $newSent['content'] = '';
                                    $newSent['html'] = MdRender::render(
                                        $row->content,
                                        [$row->channel_uid],
                                        null,
                                        $mode,
                                        'translation',
                                        $row->content_type,
                                        $format
                                    );
                                } else {
                                    if ($row->content_type === 'json') {
                                        $newSent['channel']['type'] = 'wbw';
                                        if (isset($this->wbwChannels[0])) {
                                            $newSent['channel']['name'] = $indexChannel[$this->wbwChannels[0]]->name;
                                            $newSent['channel']['lang'] = $indexChannel[$this->wbwChannels[0]]->lang;
                                            $newSent['channel']['id'] = $this->wbwChannels[0];
                                            // 存在一个translation channel
                                            // 尝试查找逐词解析数据。找到，替换现有数据
                                            $wbwData = $this->getWbw(
                                                $arrSentId[0],
                                                $arrSentId[1],
                                                $arrSentId[2],
                                                $arrSentId[3],
                                                $this->wbwChannels[0]
                                            );
                                            if ($wbwData) {
                                                $newSent['content'] = $wbwData;
                                                $newSent['contentType'] = 'json';
                                                $newSent['html'] = '';
                                                $newSent['studio'] = $indexChannel[$this->wbwChannels[0]]->studio;
                                            }
                                        }
                                    } else {
                                        $newSent['content'] = $row->content;
                                        $newSent['html'] = MdRender::render(
                                            $row->content,
                                            [$row->channel_uid],
                                            null,
                                            $mode,
                                            'translation',
                                            $row->content_type,
                                            $format
                                        );
                                    }
                                }

                                break;
                            case 'nissaya':
                                $newSent['html'] = RedisCache::remember(
                                    "/sent/{$channelId}/{$ids}/{$format}",
                                    config('mint.cache.expire'),
                                    function () use ($row, $mode, $format) {
                                        return MdRender::render(
                                            $row->content,
                                            [$row->channel_uid],
                                            null,
                                            $mode,
                                            'nissaya',
                                            $row->content_type,
                                            $format
                                        );
                                    }
                                );
                                break;
                            case 'commentary':
                                $options = [
                                    'debug' => $this->debug,
                                    'format' => $format,
                                    'mode' => $mode,
                                    'channelType' => 'translation',
                                    'contentType' => $row->content_type,
                                ];
                                $mdRender = new MdRender($options);
                                $newSent['html'] = $mdRender->convert($row->content, $channelsId);
                                break;
                            default:
                                $options = [
                                    'debug' => $this->debug,
                                    'format' => $format,
                                    'mode' => $mode,
                                    'channelType' => 'translation',
                                    'contentType' => $row->content_type,
                                ];
                                $mdRender = new MdRender($options);
                                $newSent['html'] = $mdRender->convert($row->content, [$row->channel_uid]);
                                // Log::debug('md render', ['content' => $row->content, 'options' => $options, 'render' => $newSent['html']]);
                                break;
                        }
                    } else {
                        Log::warning('no sentence record');
                    }
                    switch ($info->type) {
                        case 'wbw':
                        case 'original':
                            array_push($sentNode['origin'], $newSent);
                            break;
                        case 'commentary':
                            array_push($sentNode['commentaries'], $newSent);
                            break;
                        default:
                            array_push($sentNode['translation'], $newSent);
                            break;
                    }
                }
                $paraProps['children'][] = $sentNode;
            }
            $paragraphs[] = $paraProps;
        }

        return $paragraphs;
    }

    public function getWbw($book, $para, $start, $end, $channel)
    {
        /**
         * 非阅读模式下。原文使用逐词解析数据。
         * 优先加载第一个translation channel 如果没有。加载默认逐词解析。
         */

        // 获取逐词解析数据
        $wbwBlock = WbwBlock::where('channel_uid', $channel)
            ->where('book_id', $book)
            ->where('paragraph', $para)
            ->select('uid')
            ->first();
        if (! $wbwBlock) {
            return false;
        }
        // 找到逐词解析数据
        $wbwData = Wbw::where('block_uid', $wbwBlock->uid)
            ->whereBetween('wid', [$start, $end])
            ->select(['book_id', 'paragraph', 'wid', 'data', 'uid', 'editor_id', 'created_at', 'updated_at'])
            ->orderBy('wid')
            ->get();
        $wbwContent = [];
        foreach ($wbwData as $wbwrow) {
            $wbw = str_replace('&nbsp;', ' ', $wbwrow->data);
            $wbw = str_replace('<br>', ' ', $wbw);

            $xmlString = '<root>'.$wbw.'</root>';
            try {
                $xmlWord = simplexml_load_string($xmlString);
            } catch (\Exception $e) {
                Log::error('corpus', ['error' => $e]);

                continue;
            }
            $wordsList = $xmlWord->xpath('//word');
            foreach ($wordsList as $word) {
                $case = \str_replace(['#', '.'], ['$', ''], $word->case->__toString());
                $case = \str_replace('$$', '$', $case);
                $case = trim($case);
                $case = trim($case, '$');
                $wbwId = explode('-', $word->id->__toString());

                $wbwData = [
                    'uid' => $wbwrow->uid,
                    'book' => $wbwrow->book_id,
                    'para' => $wbwrow->paragraph,
                    'sn' => array_slice($wbwId, 2),
                    'word' => ['value' => $word->pali->__toString(), 'status' => 0],
                    'real' => ['value' => $word->real->__toString(), 'status' => 0],
                    'meaning' => ['value' => $word->mean->__toString(), 'status' => 0],
                    'type' => ['value' => $word->type->__toString(), 'status' => 0],
                    'grammar' => ['value' => $word->gramma->__toString(), 'status' => 0],
                    'case' => ['value' => $word->case->__toString(), 'status' => 0],
                    'parent' => ['value' => $word->parent->__toString(), 'status' => 0],
                    'style' => ['value' => $word->style->__toString(), 'status' => 0],
                    'factors' => ['value' => $word->org->__toString(), 'status' => 0],
                    'factorMeaning' => ['value' => $word->om->__toString(), 'status' => 0],
                    'confidence' => $word->cf->__toString(),
                    'created_at' => $wbwrow->created_at,
                    'updated_at' => $wbwrow->updated_at,
                    'hasComment' => Discussion::where('res_id', $wbwrow->uid)->exists(),
                ];
                if (isset($word->parent2)) {
                    $wbwData['parent2']['value'] = $word->parent2->__toString();
                    if (isset($word->parent2['status'])) {
                        $wbwData['parent2']['status'] = (int) $word->parent2['status'];
                    } else {
                        $wbwData['parent2']['status'] = 0;
                    }
                }
                if (isset($word->pg)) {
                    $wbwData['grammar2']['value'] = $word->pg->__toString();
                    if (isset($word->pg['status'])) {
                        $wbwData['grammar2']['status'] = (int) $word->pg['status'];
                    } else {
                        $wbwData['grammar2']['status'] = 0;
                    }
                }
                if (isset($word->rela)) {
                    $wbwData['relation']['value'] = $word->rela->__toString();
                    if (isset($word->rela['status'])) {
                        $wbwData['relation']['status'] = (int) $word->rela['status'];
                    } else {
                        $wbwData['relation']['status'] = 7;
                    }
                }
                if (isset($word->bmt)) {
                    $wbwData['bookMarkText']['value'] = $word->bmt->__toString();
                    if (isset($word->bmt['status'])) {
                        $wbwData['bookMarkText']['status'] = (int) $word->bmt['status'];
                    } else {
                        $wbwData['bookMarkText']['status'] = 7;
                    }
                }
                if (isset($word->bmc)) {
                    $wbwData['bookMarkColor']['value'] = $word->bmc->__toString();
                    if (isset($word->bmc['status'])) {
                        $wbwData['bookMarkColor']['status'] = (int) $word->bmc['status'];
                    } else {
                        $wbwData['bookMarkColor']['status'] = 7;
                    }
                }
                if (isset($word->note)) {
                    $wbwData['note']['value'] = $word->note->__toString();
                    if (isset($word->note['status'])) {
                        $wbwData['note']['status'] = (int) $word->note['status'];
                    } else {
                        $wbwData['note']['status'] = 7;
                    }
                }
                if (isset($word->cf)) {
                    $wbwData['confidence'] = (float) $word->cf->__toString();
                }
                if (isset($word->attachments)) {
                    $wbwData['attachments'] = json_decode($word->attachments->__toString());
                }
                if (isset($word->pali['status'])) {
                    $wbwData['word']['status'] = (int) $word->pali['status'];
                }
                if (isset($word->real['status'])) {
                    $wbwData['real']['status'] = (int) $word->real['status'];
                }
                if (isset($word->mean['status'])) {
                    $wbwData['meaning']['status'] = (int) $word->mean['status'];
                }
                if (isset($word->type['status'])) {
                    $wbwData['type']['status'] = (int) $word->type['status'];
                }
                if (isset($word->gramma['status'])) {
                    $wbwData['grammar']['status'] = (int) $word->gramma['status'];
                }
                if (isset($word->case['status'])) {
                    $wbwData['case']['status'] = (int) $word->case['status'];
                }
                if (isset($word->parent['status'])) {
                    $wbwData['parent']['status'] = (int) $word->parent['status'];
                }
                if (isset($word->org['status'])) {
                    $wbwData['factors']['status'] = (int) $word->org['status'];
                }
                if (isset($word->om['status'])) {
                    $wbwData['factorMeaning']['status'] = (int) $word->om['status'];
                }

                $wbwContent[] = $wbwData;
            }
        }
        if (count($wbwContent) === 0) {
            return false;
        }

        return \json_encode($wbwContent, JSON_UNESCAPED_UNICODE);
    }

    public function getChannelIndex($channels, $type = null)
    {
        // 获取channel索引表
        $channelInfo = Channel::whereIn('uid', $channels)
            ->select(['uid', 'type', 'name', 'lang', 'owner_uid'])
            ->get();
        $indexChannel = [];
        foreach ($channels as $key => $channelId) {
            $channelInfo = Channel::where('uid', $channelId)
                ->select(['uid', 'type', 'name', 'lang', 'owner_uid'])->first();
            if (! $channelInfo) {
                Log::error('no channel id'.$channelId);

                continue;
            }
            if ($type !== null && $channelInfo->type !== $type) {
                continue;
            }
            $indexChannel[$channelId] = $channelInfo;
            $indexChannel[$channelId]->studio = StudioApi::getById($channelInfo->owner_uid);
        }

        return $indexChannel;
    }

    public function sentences(array $sentenceIds, array $channelIds, string $mode)
    {
        $query = [];
        foreach ($sentenceIds as $id) {
            // code...
            $query[] = explode('-', $id);
        }
        $record = Sentence::select($this->selectCol)
            ->whereIns(['book_id', 'paragraph', 'word_start', 'word_end'], $query)
            ->whereIn('channel_uid', $channelIds)
            ->get();
        $indexChannel = $this->getChannelIndex($channelIds);
        $result = $this->makeContentObj($record, $mode, $indexChannel);

        return $result;
    }

    public function paragraphs(int $book, int $start, int $end, array $channelIds, array $param)
    {

        $channels = [];
        foreach ($channelIds as $key => $channel) {
            if (Str::isUuid($channel)) {
                $channels[] = $channel;
            }
        }
        $channelId = false;
        if ($param['original']) {
            if ($param['mode'] === 'read') {
                // 阅读模式加载html格式原文
                $channelId = ChannelApi::getSysChannel('_System_Pali_VRI_');
            } else {
                // 翻译模式加载json格式原文
                $channelId = ChannelApi::getSysChannel('_System_Wbw_VRI_');
            }
        }

        if ($channelId !== false) {
            $channels[] = $channelId;
        }
        // 获取channel索引表
        $tranChannels = [];
        $channelInfo = Channel::whereIn('uid', $channels)
            ->select(['uid', 'type', 'lang', 'name'])->get();
        foreach ($channelInfo as $key => $value) {
            // code...
            if ($value->type === 'translation') {
                $tranChannels[] = $value->uid;
            }
        }
        $indexChannel = [];
        $paliService = app(PaliContentService::class);
        $indexChannel = $paliService->getChannelIndex($channels);
        // the end of channel

        // content
        $record = Sentence::select($this->selectCol)
            ->where('book_id', $book)
            ->whereBetween('paragraph', [$start, $end])
            ->whereIn('channel_uid', $channels)
            ->orderBy('paragraph')
            ->orderBy('word_start')
            ->get();

        $result = $paliService->makeContentObj($record, $param['mode'], $indexChannel, $param['format']);

        return $result;
    }

    /**
     * 阅读模式渲染单个段落。
     * 直接从 sentences 表取单个 channel 的记录，渲染成 html。
     * 与 paragraphs() 不同：没有译文的句子不保留占位，有多少句子输出多少句子。
     *
     * @return array{para: int, display: string, sentences: array<int, array{sid: string, html: string}>}
     */
    public function readParagraph(int $book, int $para, string $channelUid, string $format = 'html'): array
    {
        $level = $this->paragraphLevel($book, $para);
        // 缓存句子，段落外壳与标题级别有关，不进缓存
        $key = self::paragraphCacheKey($book, $para, $channelUid, $format);
        $cached = RedisCache::remember(
            $key,
            config('mint.cache.expire'),
            function () use ($book, $para, $channelUid, $format) {
                return $this->renderReadSentences($book, $para, $channelUid, $format);
            }
        );

        $result = [
            'para' => $para,
            'display' => '',
            'sentences' => $cached['sentences'],
        ];
        if (count($cached['display']) === 0) {
            return $result;
        }

        $pClass = PaliText::where('book', $book)
            ->where('paragraph', $para)
            ->value('class');

        if ($format === 'html') {
            // html 格式加段落外壳；段后追加段落脚注列表（本段义注/复注条目）
            $content = implode('', $cached['display']);
            $inner = $level > 0 ? "<h{$level}>{$content}</h{$level}>" : "<div class='para-block'>{$content}</div>";
            $footnoteList = $this->renderFootnoteList($cached['notes'] ?? []);
            $result['display'] = "<div id='para-{$para}' class='{$cached['area']} {$pClass}' data-para='{$para}'>{$inner}{$footnoteList}</div>";
        } else {
            // 其他格式一行一句
            $result['display'] = implode("\n", $cached['display']);
        }

        return $result;
    }

    /**
     * 段落是章节标题时返回标题级别，否则 0
     */
    public function paragraphLevel(int $book, int $para): int
    {
        $level = PaliText::where('book', $book)
            ->where('paragraph', $para)
            ->where('level', '<', 8)
            ->value('level');

        return $level ? (int) $level : 0;
    }

    /**
     * 阅读模式支持的全部格式。forgetParagraph 需要逐格式清除缓存 key。
     *
     * @var array<int, string>
     */
    private const FORMATS = ['html', 'markdown', 'react', 'text'];

    /**
     * 义注对应（commentary）批注最多渲染几句。
     * 一条批注可能挂着十几句义注，全铺进边注会把正文挤没，只取前几句。
     */
    private const MAX_COMMENTARY_SENTENCES = 3;

    /**
     * 段落阅读模式缓存的 key
     */
    public static function paragraphCacheKey(int $book, int $para, string $channelUid, string $format): string
    {
        return "/read-para/{$book}-{$para}/{$channelUid}/{$format}";
    }

    /**
     * 删除某个段落的阅读模式缓存。句子有增改删时调用，下次 readParagraph 自动重建。
     */
    public static function forgetParagraph(int $book, int $para, string $channelUid): void
    {
        foreach (self::FORMATS as $format) {
            RedisCache::forget(self::paragraphCacheKey($book, $para, $channelUid, $format));
        }
    }

    /**
     * 段落批注内嵌：把锚定到该句子的批注排进句子 content，再交给 MdRender 渲染。
     *
     * 四种批注，显示方式不同（排版规则与交叠处理见 {@see AnnotationLayout}）：
     * - `commentary`（注释书对应）：content 是义注 / 复注的句子模板 `{{book-para-start-end}}`，
     *   渲染成这几句的译文，作为 {{note}} 边注插在锚点末尾，并追加 <cite> 跳转出处；
     * - `note`（普通边注）：content 就是注解正文（markdown），同样插成 {{note}}，没有出处；
     * - `glossary`（术语讨论）：锚点处的原文换成 `[[title#原文]]`，渲染成术语（title 是词头）；
     * - `issue`：锚点处的原文包一层高亮 span，带 discussion id，阅读器点击看内容；
     *   没有位置的合成一个三角叹号图标放在句尾。只在 html 格式输出。
     * issue / glossary 只注入未关闭的；批注没有开关状态。
     *
     * 位置按 pos_* 定位，与 quote_exact 对不上（正文改过）时按摘录重新定位。
     *
     * @return array{content: string, notes: list<array{fnId: string, noteHtml: string, citeHtml: string}>}
     */
    protected function injectAnnotationNotes(Sentence $row, string $channelType, string $format = 'html'): array
    {
        $content = (string) $row->content;
        $result = ['content' => $content, 'notes' => []];
        $records = Discussion::where('res_type', 'sentence')
            ->where('res_id', $row->uid)
            ->whereIn('type', Discussion::READING_TYPES)
            // 只注入话题本身；回复（类型跟随话题）不进阅读页
            ->whereNull('parent')
            ->where(fn ($q) => $q->whereIn('type', Discussion::INJECTED_TYPES)->orWhere('status', 'active'))
            ->orderBy('created_at')
            ->get();

        if ($records->isEmpty()) {
            return $result;
        }

        $len = mb_strlen($content, 'UTF-8');
        $locate = fn (Discussion $d) => AnnotationLayout::locate(
            $content, $d->pos_start, $d->pos_end, $d->quote_exact, $d->quote_prefix, $d->quote_suffix
        );
        $glossaries = [];
        $issues = [];
        $notes = [];
        $footnotes = [];
        foreach ($records as $record) {
            if ($record->type === Discussion::TYPE_GLOSSARY) {
                $range = $locate($record);
                if ($range !== null) {
                    $glossaries[] = ['id' => $record->id, 'start' => $range[0], 'end' => $range[1], 'title' => (string) $record->title];
                }

                continue;
            }
            if ($record->type === 'issue') {
                $range = $locate($record);
                $issues[] = ['id' => $record->id, 'start' => $range[0] ?? null, 'end' => $range[1] ?? null, 'severity' => $record->severity];

                continue;
            }
            $note = $this->renderAnnotationNote($record, $row, $channelType);
            if ($note === null) {
                continue;
            }
            // 插入点：锚点末尾；定位不到时沿用 pos_end，null / 越界都算句尾
            $range = $locate($record);
            $at = $range[1] ?? $record->pos_end;
            if ($at === null || $at < 0 || $at > $len) {
                $at = $len;
            }
            $notes[] = ['id' => $record->id, 'at' => $at, 'order' => $note['order'], 'html' => $note['template']];
            $footnotes[$record->id] = [
                'fnId' => 'fn-'.$record->id,
                'noteHtml' => $note['noteHtml'],
                'citeHtml' => $note['citeHtml'],
            ];
        }

        $layout = AnnotationLayout::apply($content, $glossaries, $issues, $notes, $format === 'html');
        $result['content'] = $layout['content'];
        $result['notes'] = array_map(fn ($id) => $footnotes[$id], $layout['notes']);

        Log::info('reading-annotations: inject', [
            'sid' => "{$row->book_id}-{$row->paragraph}-{$row->word_start}-{$row->word_end}",
            'count' => $records->count(),
            'content' => $result['content'],
        ]);

        return $result;
    }

    /**
     * 把一条批注（commentary / note）渲染成要插入正文的 {{note}} 模板与段后脚注条目。
     * 不合格的（正文为空、commentary 不是句子模板）返回 null，不插角标也不进脚注列表。
     *
     * @return array{template: string, noteHtml: string, citeHtml: string, order: array<int, int>}|null
     */
    protected function renderAnnotationNote(Discussion $note, Sentence $row, string $channelType): ?array
    {
        $noteContent = trim((string) $note->content);
        if ($noteContent === '') {
            return null;
        }
        $sents = [];
        if ($note->type === Discussion::TYPE_COMMENTARY) {
            // content 是一个或多个义注句子模板 {{book-para-start-end}}（一个词可能由义注
            // 多句解释，按顺序并列，如 {{135-404-50-54}}{{135-404-55-65}}）。
            if (! preg_match(Discussion::COMMENTARY_PATTERN, $noteContent)) {
                return null;
            }
            preg_match_all('/\{\{(\d+)-(\d+)-(\d+)-(\d+)\}\}/', $noteContent, $sents, PREG_SET_ORDER);
            // 义注正文只需译文（不要巴利原文）：把每个裸句模板 {{book-para-start-end}}
            // 转成 {{sent|id=…|text=translation}}，让 sent 模板只输出 translation。
            // 句子可能有很多条，只渲染前 MAX_COMMENTARY_SENTENCES 句；
            // 跳转锚点仍指向第一句，点进去能看到完整义注。
            $source = implode(' ', array_map(
                fn ($s) => '{{sent|id='.$s[1].'-'.$s[2].'-'.$s[3].'-'.$s[4].'|text=translation}}',
                array_slice($sents, 0, self::MAX_COMMENTARY_SENTENCES)
            ));
        } else {
            // 普通边注：content 就是注解正文，照原样渲染。
            $source = $noteContent;
        }
        // 边注实际内容：先用 MdRender 渲染出来，再放进 {{note|text=…}} ——
        // 直接嵌套 {{…}} 会被 wiki2xml 的平铺替换破坏。
        // 用 text 格式渲染：避免「1.」被 markdown 解释成有序列表，
        // 产生 <ol></p></p> 这类坏 HTML 把 sidenote 的闭合结构破坏、吞掉后续正文。
        $noteHtml = MdRender::render(
            $source,
            [$row->channel_uid],
            null,
            'read',
            $channelType,
            'markdown',
            'text'
        );
        // 义注被截断时补省略号，提示后面还有；想看全文点 <cite> 跳过去。
        if (count($sents) > self::MAX_COMMENTARY_SENTENCES) {
            $noteHtml = rtrim($noteHtml).'...';
        }
        // 出处只有 commentary 有。跳转目标（义注书-段-起-止）同时挂在 <cite> 和角标
        // <label> 上，前者用于「点链接跳页」，后者用于平板双栏「点角标跨栏高亮」。
        // 多句时跳转到第一句（义注对这个词的解释从那里开始）。
        $citeHtml = '';
        $citeParam = '';
        if ($sents) {
            $m = $sents[0];
            $target = ' data-book="'.$m[1].'" data-para="'.$m[2].'" data-start="'.$m[3].'" data-end="'.$m[4].'"';
            $citeHtml = '<cite class="anno-jump"'.$target.'>义注</cite>';
            $citeParam = '|cite=义注'
                .'|citelink='.$m[1].'-'.$m[2].'-'.$m[3].'-'.$m[4];
        }

        return [
            // 用 {{note}} 模板渲染 tufte sidenote（label + input + span.sidenote），复用 render_note()。
            // text 传已预渲染的纯文本（嵌套 {{…}} 会被 wiki2xml 平铺替换破坏）。
            'template' => '{{note|text='.$noteHtml.$citeParam.'}}',
            'noteHtml' => $noteHtml,
            'citeHtml' => $citeHtml,
            // 同一插入点上的先后：按义注原文的先后；普通 note 没有坐标，取 0，排在义注对应之前
            'order' => $sents ? [(int) $sents[0][1], (int) $sents[0][2], (int) $sents[0][3]] : [0, 0, 0],
        ];
    }

    /**
     * 段落脚注列表：把本段的注释条目逐条列在段后，每条默认收起为可配置行数（见阅读器 CSS）。
     */
    protected function renderFootnoteList(array $notes): string
    {
        if (empty($notes)) {
            return '';
        }
        $html = '<div class="anno-footnotes">';
        foreach ($notes as $note) {
            $html .= '<div class="anno-footnote">'
                .'<input type="checkbox" id="'.$note['fnId'].'" class="anno-fn-toggle"/>'
                .'<label for="'.$note['fnId'].'" class="anno-fn-label">'
                .'<span class="anno-fn-body">'.e($note['noteHtml']).'</span>'
                .'</label>'
                .$note['citeHtml']
                .'</div>';
        }
        $html .= '</div>';

        return $html;
    }

    /**
     * 渲染段落里的句子。不含段落外壳，可直接缓存。
     *
     * @return array{area: string, display: array<int, string>, sentences: array<int, array{sid: string, html: string}>}
     */
    protected function renderReadSentences(int $book, int $para, string $channelUid, string $format): array
    {
        $result = ['area' => 'translation', 'display' => [], 'sentences' => []];
        $channel = Channel::where('uid', $channelUid)
            ->select(['uid', 'type', 'lang', 'name'])->first();
        if (! $channel) {
            return $result;
        }
        $isOrigin = $channel->type === 'original' || $channel->type === 'wbw';
        $channelType = $channel->type === 'nissaya' ? 'nissaya' : 'translation';
        $result['area'] = $isOrigin ? 'original' : 'translation';

        $records = Sentence::select($this->selectCol)
            ->where('book_id', $book)
            ->where('paragraph', $para)
            ->where('channel_uid', $channelUid)
            ->orderBy('word_start')
            ->get();

        $allNotes = [];
        foreach ($records as $row) {
            $injected = $this->injectAnnotationNotes($row, $channelType, $format);
            $content = $injected['content'];
            $allNotes = array_merge($allNotes, $injected['notes']);
            $html = MdRender::render(
                $content,
                [$row->channel_uid],
                null,
                'read',
                $channelType,
                $row->content_type,
                $format
            );
            if (empty($html)) {
                continue;
            }
            $sid = "{$row->book_id}-{$row->paragraph}-{$row->word_start}-{$row->word_end}";
            $result['sentences'][] = ['sid' => $sid, 'html' => $html];
            if ($format === 'html') {
                $class = $isOrigin ? 'sentence origin' : 'sentence';
                $result['display'][] = "<div class='{$class}' lang='{$channel->lang}' data-sid='{$sid}'>{$html}</div>";
            } else {
                $result['display'][] = $html;
            }
        }
        $result['notes'] = $allNotes;

        return $result;
    }
}