2
0

AnnotationLayout.php 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368
  1. <?php
  2. namespace App\Services;
  3. /**
  4. * 阅读页批注排版:把锚定在一句译文上的几种批注一次性排进句子的原始 content(markdown)。
  5. *
  6. * 纯计算,不查库、不渲染——输入 content 与已解析好的批注,输出改写后的 content。
  7. * 调用方是 {@see PaliContentService::injectAnnotationNotes()},改写后的 content 再交给 App\Services\Markup 渲染。
  8. * 插入点写什么由 {@see AnnotationMarkup} 策略决定:阅读页写结构化标记({@see Markup\Annotation\AnnotationSet}),
  9. * 能渲染成任意格式;缺省写 HTML。
  10. *
  11. * 三种东西,排法各不相同:
  12. * - glossary:区间 [start, end) 的原文换成 `[[title#原文]]`,渲染成术语;
  13. * - issue:区间外包一层 `<span class="anno-issue …" data-discussion-ids="…">`(高亮,点击看内容);
  14. * 没有位置的 issue 合成一个三角叹号图标,放在句尾;
  15. * - note / commentary:在插入点插入调用方预先渲染好的 `{{note|…}}` 模板;
  16. * - assessment:句子最末尾一个对勾图标(在 issue 的三角之后),颜色按分数分档({@see self::assessmentLevel()})。
  17. *
  18. * 交叠的处理(核心约束:任何时候都不能切断一个标记):
  19. * - 受保护区间:content 里本来就有的标记(`[[…]]`、`{{…}}`、`` `…` ``、`**…**`、HTML 标签),
  20. * 谁都不能切断;
  21. * - glossary 碰到受保护区间就放弃;两个 glossary 交叠时,包含关系留外层,交叉关系留靠前的,
  22. * 另一条放弃(`[[…]]` 不能嵌套,也不能交叉);
  23. * - issue 与 glossary / 受保护区间部分交叠时,把 issue 扩展到完整包住对方;
  24. * issue 之间交叠或包含就合并成一个 span,id 取并集、severity 取最重的;
  25. * 扩展可能引出新的交叠,反复处理直到稳定。仅仅首尾相接的不合并;
  26. * - note 的插入点落在 glossary 或受保护区间内部时,挪到该区间的末尾;落在 issue 内部则原地插入
  27. * (行内元素嵌套是合法的);
  28. * - 同一位置上的输出顺序:先收尾的 issue `</span>`,再 note,再开头的 issue `<span>`——
  29. * note 锚定的是位置之前的文字,应当跟在结束的高亮之后、开始的高亮之前。
  30. */
  31. class AnnotationLayout
  32. {
  33. /** 严重程度由轻到重;合并时取最重的,没有 severity 的最轻 */
  34. private const SEVERITY_RANK = ['suggestion' => 1, 'warning' => 2, 'error' => 3];
  35. /** 评估分档的下限(含):由高到低,都不够就是 low */
  36. private const ASSESSMENT_LEVELS = ['high' => 80, 'medium' => 60];
  37. /** glossary 的原文或词头里不能有这些字符,否则 `[[title#原文]]` 会被拆坏 */
  38. private const GLOSSARY_FORBIDDEN = '/[\[\]{}|#\r\n]/u';
  39. /**
  40. * 受保护区间:已有的模板、术语、行内注释、粗体与 HTML 标签。
  41. */
  42. private const PROTECTED_PATTERN = '/\[\[.*?\]\]|\{\{.*?\}\}|`[^`]*`|\*\*.+?\*\*|<[^<>]+>/us';
  43. /**
  44. * 按选择器在 content 里定位一段文字,返回 [start, end)(字符偏移),定位不到返回 null。
  45. *
  46. * 先信位置:pos 合法且(没有摘录或摘录对得上)就用 pos。对不上说明正文改过,按摘录重新找:
  47. * 有前后缀就优先选前后缀也吻合的那一处,同分取离原位置最近的。
  48. *
  49. * @return array{0: int, 1: int}|null
  50. */
  51. public static function locate(
  52. string $content,
  53. ?int $start,
  54. ?int $end,
  55. ?string $exact = null,
  56. ?string $prefix = null,
  57. ?string $suffix = null,
  58. ): ?array {
  59. $len = mb_strlen($content, 'UTF-8');
  60. $exact = (string) $exact;
  61. $posValid = $start !== null && $end !== null && $start >= 0 && $start < $end && $end <= $len;
  62. if ($posValid && ($exact === '' || mb_substr($content, $start, $end - $start, 'UTF-8') === $exact)) {
  63. return [$start, $end];
  64. }
  65. if ($exact === '') {
  66. return null;
  67. }
  68. $exactLen = mb_strlen($exact, 'UTF-8');
  69. $prefix = (string) $prefix;
  70. $suffix = (string) $suffix;
  71. $best = null;
  72. $bestScore = null;
  73. $offset = 0;
  74. while (($found = mb_strpos($content, $exact, $offset, 'UTF-8')) !== false) {
  75. // 前缀:紧挨在前面的文字是前缀的结尾(句首附近可能不够长,比能比的那部分)
  76. $n = min($found, mb_strlen($prefix, 'UTF-8'));
  77. $before = mb_substr($content, $found - $n, $n, 'UTF-8');
  78. $matchPrefix = $n > 0 && str_ends_with($prefix, $before);
  79. // 后缀:紧跟在后面的文字是后缀的开头
  80. $after = mb_substr($content, $found + $exactLen, mb_strlen($suffix, 'UTF-8'), 'UTF-8');
  81. $matchSuffix = $after !== '' && str_starts_with($suffix, $after);
  82. $distance = $start === null ? $found : abs($found - $start);
  83. // 分数:前后缀吻合得越多越好,其次离原位置越近越好
  84. $score = [(int) $matchPrefix + (int) $matchSuffix, -$distance];
  85. if ($bestScore === null || $score > $bestScore) {
  86. $best = $found;
  87. $bestScore = $score;
  88. }
  89. $offset = $found + 1;
  90. }
  91. return $best === null ? null : [$best, $best + $exactLen];
  92. }
  93. /**
  94. * 排版。
  95. *
  96. * @param list<array{id: string, start: int, end: int, title: string}> $glossaries 已定位的术语
  97. * @param list<array{id: string, start: int|null, end: int|null, severity: string|null}> $issues start/end 为 null 表示没有位置
  98. * @param list<array{id: string, at: int, order: array<int, int>, html: string}> $notes at 是插入点,order 是同一插入点上的先后
  99. * @param bool $withIssues 是否输出 issue 的高亮与图标、评估的对勾(只有 html 格式需要)
  100. * @param array{id: string, score: int}|null $assessment 这句的评估,没有为 null
  101. * @param AnnotationMarkup|null $markup 插入点写什么,缺省写 HTML({@see HtmlAnnotationMarkup})
  102. * @return array{content: string, notes: list<string>, glossaries: list<string>, issues: list<array{ids: list<string>, severity: string|null, start: int|null, end: int|null}>}
  103. *
  104. * 返回值里 notes 是 note id 的阅读顺序,glossaries 是实际替换了的术语 id,
  105. * issues 是合并后的高亮(没有位置的合成一条,start / end 为 null)。
  106. */
  107. public static function apply(string $content, array $glossaries, array $issues, array $notes, bool $withIssues = true, ?array $assessment = null, ?AnnotationMarkup $markup = null): array
  108. {
  109. $markup ??= new HtmlAnnotationMarkup;
  110. $len = mb_strlen($content, 'UTF-8');
  111. $protected = self::protectedRanges($content);
  112. // ---- glossary:放弃碰到受保护区间的、字符不合法的,然后贪心取不交叠的
  113. $glossaries = array_values(array_filter($glossaries, function (array $g) use ($content, $len, $protected) {
  114. if ($g['start'] < 0 || $g['start'] >= $g['end'] || $g['end'] > $len) {
  115. return false;
  116. }
  117. $text = mb_substr($content, $g['start'], $g['end'] - $g['start'], 'UTF-8');
  118. if (trim($g['title']) === '' || preg_match(self::GLOSSARY_FORBIDDEN, $text.$g['title'])) {
  119. return false;
  120. }
  121. foreach ($protected as $p) {
  122. if (self::intersects($g, $p)) {
  123. return false;
  124. }
  125. }
  126. return true;
  127. }));
  128. // 开头靠前的优先;开头相同的,长的(外层)优先
  129. usort($glossaries, fn ($a, $b) => [$a['start'], $b['end'], $a['id']] <=> [$b['start'], $a['end'], $b['id']]);
  130. $kept = [];
  131. foreach ($glossaries as $g) {
  132. foreach ($kept as $k) {
  133. if (self::intersects($g, $k)) {
  134. continue 2;
  135. }
  136. }
  137. $kept[] = $g;
  138. }
  139. $glossaries = $kept;
  140. // ---- issue:扩展到不切断任何 glossary / 受保护区间,再合并交叠的,直到稳定
  141. $spans = [];
  142. $unanchored = [];
  143. foreach ($issues as $issue) {
  144. $s = $issue['start'];
  145. $e = $issue['end'];
  146. if ($s === null || $e === null || $s < 0 || $s >= $e || $e > $len) {
  147. $unanchored[] = $issue;
  148. continue;
  149. }
  150. $spans[] = ['start' => $s, 'end' => $e, 'ids' => [$issue['id']], 'severity' => $issue['severity']];
  151. }
  152. $spans = self::settleSpans($spans, [...$glossaries, ...$protected]);
  153. // ---- note:插入点不能落在 glossary / 受保护区间内部
  154. $blockers = [...$glossaries, ...$protected];
  155. foreach ($notes as &$note) {
  156. $at = min(max($note['at'], 0), $len);
  157. do {
  158. $moved = false;
  159. foreach ($blockers as $b) {
  160. if ($b['start'] < $at && $at < $b['end']) {
  161. $at = $b['end'];
  162. $moved = true;
  163. }
  164. }
  165. } while ($moved);
  166. $note['at'] = $at;
  167. }
  168. unset($note);
  169. usort($notes, fn ($a, $b) => [$a['at'], ...$a['order']] <=> [$b['at'], ...$b['order']]);
  170. // ---- 按位置从左到右输出
  171. $opens = [];
  172. $closes = [];
  173. if ($withIssues) {
  174. foreach ($spans as $span) {
  175. $opens[$span['start']][] = $span;
  176. $closes[$span['end']][] = $span;
  177. }
  178. }
  179. $notesAt = [];
  180. foreach ($notes as $note) {
  181. $notesAt[$note['at']][] = $note['html'];
  182. }
  183. $glossaryAt = [];
  184. foreach ($glossaries as $g) {
  185. $glossaryAt[$g['start']] = $g;
  186. }
  187. $points = array_unique([0, $len, ...array_keys($opens), ...array_keys($closes), ...array_keys($notesAt), ...array_keys($glossaryAt)]);
  188. sort($points);
  189. $out = '';
  190. $cursor = 0;
  191. foreach ($points as $x) {
  192. if ($x < $cursor) {
  193. continue; // 落在已整段输出的 glossary 内部:构造上不会出现,只是防御
  194. }
  195. $out .= mb_substr($content, $cursor, $x - $cursor, 'UTF-8');
  196. $cursor = $x;
  197. // 合并后 issue 之间互不交叠,同一点上至多一个收尾、一个开头
  198. foreach ($closes[$x] ?? [] as $span) {
  199. $out .= $markup->issueClose($span);
  200. }
  201. foreach ($notesAt[$x] ?? [] as $html) {
  202. $out .= $html;
  203. }
  204. foreach ($opens[$x] ?? [] as $span) {
  205. $out .= $markup->issueOpen($span);
  206. }
  207. if (isset($glossaryAt[$x])) {
  208. $g = $glossaryAt[$x];
  209. $text = mb_substr($content, $g['start'], $g['end'] - $g['start'], 'UTF-8');
  210. $out .= '[['.trim($g['title']).'#'.$text.']]';
  211. $cursor = $g['end'];
  212. }
  213. }
  214. $out .= mb_substr($content, $cursor, null, 'UTF-8');
  215. if ($withIssues && $unanchored !== []) {
  216. $out .= $markup->issueMark(
  217. array_column($unanchored, 'id'),
  218. self::maxSeverity(array_column($unanchored, 'severity')),
  219. );
  220. }
  221. if ($withIssues && $assessment !== null) {
  222. $out .= $markup->assessmentMark($assessment['id'], $assessment['score']);
  223. }
  224. $report = array_map(fn ($s) => [
  225. 'ids' => $s['ids'], 'severity' => $s['severity'], 'start' => $s['start'], 'end' => $s['end'],
  226. ], $spans);
  227. if ($unanchored !== []) {
  228. $report[] = [
  229. 'ids' => array_column($unanchored, 'id'),
  230. 'severity' => self::maxSeverity(array_column($unanchored, 'severity')),
  231. 'start' => null,
  232. 'end' => null,
  233. ];
  234. }
  235. return [
  236. 'content' => $out,
  237. 'notes' => array_column($notes, 'id'),
  238. 'glossaries' => array_column($glossaries, 'id'),
  239. 'issues' => $report,
  240. ];
  241. }
  242. /**
  243. * content 里已有的标记占据的区间(字符偏移)。
  244. *
  245. * @return list<array{start: int, end: int}>
  246. */
  247. public static function protectedRanges(string $content): array
  248. {
  249. preg_match_all(self::PROTECTED_PATTERN, $content, $matches, PREG_OFFSET_CAPTURE);
  250. $ranges = [];
  251. foreach ($matches[0] as [$text, $byteOffset]) {
  252. $start = mb_strlen(substr($content, 0, $byteOffset), 'UTF-8');
  253. $ranges[] = ['start' => $start, 'end' => $start + mb_strlen($text, 'UTF-8')];
  254. }
  255. return $ranges;
  256. }
  257. /**
  258. * 把 issue 区间扩展到不切断任何障碍物,并合并交叠的 issue,反复直到稳定。
  259. *
  260. * @param list<array{start: int, end: int, ids: list<string>, severity: string|null}> $spans
  261. * @param list<array{start: int, end: int}> $blockers
  262. * @return list<array{start: int, end: int, ids: list<string>, severity: string|null}>
  263. */
  264. private static function settleSpans(array $spans, array $blockers): array
  265. {
  266. do {
  267. $changed = false;
  268. // 扩展:与障碍物交叠但没有完整包住它,就把它包进来
  269. foreach ($spans as &$span) {
  270. foreach ($blockers as $b) {
  271. if (self::intersects($span, $b) && ($b['start'] < $span['start'] || $b['end'] > $span['end'])) {
  272. $span['start'] = min($span['start'], $b['start']);
  273. $span['end'] = max($span['end'], $b['end']);
  274. $changed = true;
  275. }
  276. }
  277. }
  278. unset($span);
  279. // 合并:按开头排序后,与上一个交叠(含包含)的并进去
  280. usort($spans, fn ($a, $b) => [$a['start'], $a['end']] <=> [$b['start'], $b['end']]);
  281. $merged = [];
  282. foreach ($spans as $span) {
  283. $last = count($merged) - 1;
  284. if ($last >= 0 && self::intersects($merged[$last], $span)) {
  285. $merged[$last]['end'] = max($merged[$last]['end'], $span['end']);
  286. $merged[$last]['ids'] = [...$merged[$last]['ids'], ...$span['ids']];
  287. $merged[$last]['severity'] = self::maxSeverity([$merged[$last]['severity'], $span['severity']]);
  288. $changed = true;
  289. } else {
  290. $merged[] = $span;
  291. }
  292. }
  293. $spans = $merged;
  294. } while ($changed);
  295. return $spans;
  296. }
  297. /**
  298. * 两个半开区间是否有公共部分(首尾相接不算)。
  299. *
  300. * @param array{start: int, end: int} $a
  301. * @param array{start: int, end: int} $b
  302. */
  303. private static function intersects(array $a, array $b): bool
  304. {
  305. return $a['start'] < $b['end'] && $b['start'] < $a['end'];
  306. }
  307. /**
  308. * @param array<int, string|null> $severities
  309. */
  310. private static function maxSeverity(array $severities): ?string
  311. {
  312. $max = null;
  313. foreach ($severities as $severity) {
  314. if ((self::SEVERITY_RANK[$severity] ?? 0) > (self::SEVERITY_RANK[$max] ?? 0)) {
  315. $max = $severity;
  316. }
  317. }
  318. return $max;
  319. }
  320. /**
  321. * 评估分数的档位:high(≥80)/ medium(≥60)/ low。阅读器按档位着色(绿 / 橙 / 红)。
  322. */
  323. public static function assessmentLevel(int $score): string
  324. {
  325. foreach (self::ASSESSMENT_LEVELS as $level => $min) {
  326. if ($score >= $min) {
  327. return $level;
  328. }
  329. }
  330. return 'low';
  331. }
  332. /**
  333. * 没有评估的句子的灰色对勾(HTML)。只在同段有别的句子评估过时补上,标出句子的边界。
  334. */
  335. public static function unassessedMark(): string
  336. {
  337. return HtmlAnnotationMarkup::unassessedMark();
  338. }
  339. }