长文沉浸式阅读与段评

AGENTS.md

@@ -103,6 +103,8 @@
 - 首页两列对齐约束：`getIndexRecentArticles` 的第一页会插入全部置顶且不截断；第二页起需按第一页“置顶占位数”补偿 `fetchSize` 与分页偏移，并基于已排除置顶 ID 的普通文章序列取数，保证两列等高、不重复、不丢中间文章。
 - 首页右侧排行补偿（无前端延迟）：由 `IndexProcessor#loadIndexData` 按两列最新文章的最大行数计算 `rankCompensateRows`，先换算“右栏总补偿行数”再分摊到 `checkinVisibleCount/onlineVisibleCount`，Freemarker 直接按该数量渲染，不再依赖 JS 运行时增删行。
 - 专栏封面链路：封面字段是 `long_article_column.columnCoverURL`；默认封面在 `LongArticleColumnQueryService` 填充；作者管理页为 `/column/manage`，编辑长篇页的弹窗脚本是 `long-article-cover-dialog.js`，新建长篇封面随 `/article` 请求的 `columnCoverURL` 写入；封面保存接口为 `POST /api/columns/{columnId}/cover`，处理器是 `LongArticleColumnProcessor`。
+- 长文阅读页以 `articleType=6` 区分，PC/移动模板均为 `skins/classic/*/article.ftl`，样式在 `index.scss`/`mobile-base.scss`，交互在 `long-article.js`/`m-long-article.js`；模板通过 `hidePageChrome` 不渲染顶部与底部视觉内容，但 footer 的公共脚本仍需加载；桌面宽度和两端字号统一保存在 `localStorage.longArticleSettings`，宽度仅在 PC 生效；PC 评论按钮控制居中的“正文 + 评论”阅读舞台，移动端使用右侧抽屉，现有评论列表、筛选、分页和编辑器均复用。
+- 长文段评链路：`LongArticleParagraphService` 根据服务端清洗后的正文生成段落锚点并给 HTML 添加 `data-long-paragraph-*`；段评字段存于 `comment`（`commentType=1`），新增接口位于 `CommentProcessor` 的 `/comment/paragraph*`；评论编辑事务调用段落迁移，无法匹配的段评标记为失效但保留快照。PC/移动均加载 `long-article-paragraph.js`，段评列表复用现有评论线程与编辑器能力。
 - 管理员文章页编辑长文专栏时，`admin/article.ftl` 会随文章表单提交 `columnCoverURL`，后端在 `ArticleMgmtService` 的文章事务内复用 `ColumnCoverMgmtService` 校验并更新或清空专栏封面。
 - 路由总入口：`Router#requestMapping` + 各 Processor `register()`；新增路由先决定使用 `loginCheck` / `apiCheck` / `permission` / `anonymousViewCheck` 哪条链路。
 - Latke 路由存在静态段被相邻动态段截获的风险（如 `/article/{id}/revisions/list` 可能进入 `/article/{id}/revisions/{revisionId}`）；新增相邻路由时需避免路径歧义，或在处理方法中显式识别保留字。

API.md

@@ -2318,6 +2318,107 @@ curl --location --request POST 'https://fishpi.cn/comment/thread/replies' \
 | commentContent           | 评论原文（Markdown格式）                                          | hello world                      |
 | commentOriginalCommentId | （选填）如果是回复某个评论，传递此参数并填写值为要回复的评论的oId | 1646216549324                    |
 
+### 长篇段评
+
+`POST /comment/paragraph`
+
+为长篇正文指定段落发表评论或回复。旧的 `POST /comment` 继续创建章评。
+
+请求：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| apiKey | 通用密钥，可选 | oXTQTD4ljryXoIxa1lySgEl6aObrIhSS |
+| articleId | 长篇文章 Id | 1645002736006 |
+| paragraphId | 服务端生成的段落 Id | `64 位小写 SHA-256` |
+| commentContent | 评论原文（Markdown 格式） | 这一段写得很好 |
+| commentAnonymous | 是否匿名评论 | false |
+| commentVisible | 是否仅楼主可见 | false |
+| commentOriginalCommentId | 回复时填写段评 Id，可选 | 1646216549324 |
+
+请求示例：
+
+```bash
+curl -X POST "https://fishpi.cn/comment/paragraph" \
+  -H "Content-Type: application/json" \
+  -d '{"apiKey":"你的 apiKey","articleId":"1645002736006","paragraphId":"64 位小写 SHA-256","commentContent":"这一段写得很好","commentAnonymous":false,"commentVisible":false}'
+```
+
+响应：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| code | `0` 表示成功 | 0 |
+| commentId | 新评论 Id | 1646216549324 |
+
+> 仅支持 `articleType=6`。段落类型、顺序和文本快照由服务端校验并保存，客户端不能伪造。新增根评论必须关联当前有效段落；回复必须属于同一文章和同一段评线程，原段落已修改的线程仍可继续回复。
+
+### 获取长篇段评摘要
+
+`POST /comment/paragraph/summary`
+
+获取长篇当前有效段落的评论数量，数量包含根评论和回复。
+
+请求：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| apiKey | 访问受限文章时填写 | oXTQTD4ljryXoIxa1lySgEl6aObrIhSS |
+| articleId | 长篇文章 Id | 1645002736006 |
+
+请求示例：
+
+```bash
+curl -X POST "https://fishpi.cn/comment/paragraph/summary" \
+  -H "Content-Type: application/json" \
+  -d '{"articleId":"1645002736006"}'
+```
+
+响应：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| code | `0` 表示成功 | 0 |
+| paragraphComments | 段落评论数量 | `[...]` |
+| - paragraphId | 段落 Id | `64 位小写 SHA-256` |
+| - commentCount | 段评总数 | 3 |
+
+### 获取长篇段评线程
+
+`POST /comment/paragraph/thread/parents`
+
+获取指定段落的评论线程根评论。
+
+请求：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| apiKey | 访问受限文章时填写 | oXTQTD4ljryXoIxa1lySgEl6aObrIhSS |
+| articleId | 长篇文章 Id | 1645002736006 |
+| paragraphId | 段落 Id | `64 位小写 SHA-256` |
+| paginationCurrentPageNum | 页码，默认 1 | 1 |
+| sort | `hot` 表示热门排序 | hot |
+
+请求示例：
+
+```bash
+curl -X POST "https://fishpi.cn/comment/paragraph/thread/parents" \
+  -H "Content-Type: application/json" \
+  -d '{"articleId":"1645002736006","paragraphId":"64 位小写 SHA-256","paginationCurrentPageNum":1,"sort":"hot"}'
+```
+
+响应：
+
+| Key | 说明 | 示例 |
+| --- | --- | --- |
+| code | `0` 表示成功 | 0 |
+| commentThreadParents | 段评线程根评论，字段与线程接口一致 | `[...]` |
+| paragraphId | 当前段落 Id | `64 位小写 SHA-256` |
+| paragraphSnapshot | 当前段落摘要 | 这一段写得很好 |
+| pagination | 分页信息 | `{...}` |
+
+> 段评接口遵循文章匿名访问、讨论帖权限和评论可见性校验；响应不返回评论 IP、UA、联系方式、密钥或完整用户对象。文章编辑后无法匹配的段评会保留为“原段落已修改”，不会丢失。
+
 ### 更新评论
 
 `PUT /comment/{评论oId}`

sql/20260719_long_article_paragraph_comment.sql

@@ -0,0 +1,9 @@
+ALTER TABLE `symphony_comment`
+  ADD COLUMN `commentType` INT NOT NULL DEFAULT 0,
+  ADD COLUMN `commentParagraphId` VARCHAR(64) NOT NULL DEFAULT '',
+  ADD COLUMN `commentParagraphKind` VARCHAR(16) NOT NULL DEFAULT '',
+  ADD COLUMN `commentParagraphIndex` INT NOT NULL DEFAULT -1,
+  ADD COLUMN `commentParagraphSnapshot` VARCHAR(1024) NOT NULL DEFAULT '',
+  ADD COLUMN `commentParagraphStatus` INT NOT NULL DEFAULT 0,
+  ADD INDEX `idx_cmt_article_type_paragraph_status_oid`
+    (`commentOnArticleId`, `commentType`, `commentParagraphId`, `commentParagraphStatus`, `commentCreateTime`, `oId`);

src/main/java/org/b3log/symphony/model/Comment.java

@@ -132,6 +132,18 @@ public final class Comment {
      */
     public static final String COMMENT_VISIBLE = "commentVisible";
 
+    public static final String COMMENT_TYPE = "commentType";
+
+    public static final String COMMENT_PARAGRAPH_ID = "commentParagraphId";
+
+    public static final String COMMENT_PARAGRAPH_KIND = "commentParagraphKind";
+
+    public static final String COMMENT_PARAGRAPH_INDEX = "commentParagraphIndex";
+
+    public static final String COMMENT_PARAGRAPH_SNAPSHOT = "commentParagraphSnapshot";
+
+    public static final String COMMENT_PARAGRAPH_STATUS = "commentParagraphStatus";
+
     //// Transient ////
     /**
      * Key of comment revision count.
@@ -292,6 +304,14 @@ public final class Comment {
      */
     public static final int COMMENT_VISIBLE_C_AUTHOR = 1;
 
+    public static final int COMMENT_TYPE_C_ARTICLE = 0;
+
+    public static final int COMMENT_TYPE_C_PARAGRAPH = 1;
+
+    public static final int COMMENT_PARAGRAPH_STATUS_C_ACTIVE = 0;
+
+    public static final int COMMENT_PARAGRAPH_STATUS_C_ORPHANED = 1;
+
     //// Validation constants
     /**
      * Max comment content length.

src/main/java/org/b3log/symphony/processor/ArticleProcessor.java

@@ -162,6 +162,9 @@ public class ArticleProcessor {
     @Inject
     private LongArticleColumnQueryService longArticleColumnQueryService;
 
+    @Inject
+    private LongArticleParagraphService longArticleParagraphService;
+
     /**
      * Comment query service.
      */
@@ -534,6 +537,9 @@ public void showArticleApi(final RequestContext context) {
         articleQueryService.processArticleContent(article);
 
         if (Article.ARTICLE_TYPE_C_LONG == article.optInt(Article.ARTICLE_TYPE)) {
+            final JSONObject paragraphContent = longArticleParagraphService.annotateRenderedContent(
+                    articleId, article.optString(Article.ARTICLE_CONTENT));
+            article.put(Article.ARTICLE_CONTENT, paragraphContent.optString("html"));
             final JSONObject readStat = longArticleReadService.getStat(articleId);
             article.put("longArticleReadStat", readStat);
             dataModel.put("longArticleReadStat", readStat);
@@ -1418,6 +1424,9 @@ public void showArticle(final RequestContext context) {
         articleQueryService.processArticleContent(article);
 
         if (Article.ARTICLE_TYPE_C_LONG == article.optInt(Article.ARTICLE_TYPE)) {
+            final JSONObject paragraphContent = longArticleParagraphService.annotateRenderedContent(
+                    articleId, article.optString(Article.ARTICLE_CONTENT));
+            article.put(Article.ARTICLE_CONTENT, paragraphContent.optString("html"));
             final JSONObject readStat = longArticleReadService.getStat(articleId);
             article.put("longArticleReadStat", readStat);
             dataModel.put("longArticleReadStat", readStat);
@@ -1640,6 +1649,11 @@ public void showArticle(final RequestContext context) {
         // Load comments
         final List<JSONObject> articleComments = commentQueryService.getArticleThreadParentComments(commentThreadOptions);
         article.put(Article.ARTICLE_T_COMMENTS, (Object) articleComments);
+        if (Article.ARTICLE_TYPE_C_LONG == article.optInt(Article.ARTICLE_TYPE)) {
+            article.put("articleOrphanedParagraphComments", (Object)
+                    commentQueryService.getOrphanedParagraphThreadParentComments(
+                            articleId, currentUserId, articleAuthorId));
+        }
         article.put("commentors", (Object) commentQueryService.getArticleCommentors(articleId));
 
         // Fill comment thank