docs(docs): archive comment-system-upgrade to changes/archive

- Phase 1-3, 5.1, 6 completed (17/31 tasks)
- Phase 4 skipped (depends on md-parser)
- Phase 5.2-5.4 deferred (comment like needs full-stack work)

Author: juwenzhang

openspec/changes/archive/2026-04-06-comment-system-upgrade/design.md

@@ -0,0 +1,210 @@
+## Context
+
+当前评论系统前端组件位于 `apps/main/src/pages/post/pages/detail/` 中（嵌套在文章详情页），后端在 `services/svc-content/handlers/comment/`。评论使用二级嵌套结构，通过 `parent_id` 关联。
+
+Proto 定义在 `proto/luhanxin/community/v1/comment.proto`，已有 `ListComments` RPC，使用 offset-based 分页。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+1. 评论列表无限滚动 + 骨架屏
+2. 评论排序（最新/最热）
+3. 乐观点赞体验
+4. 评论 Markdown 渲染
+5. @提及跳转链接
+6. 文章列表评论数量预览
+
+**Non-Goals:**
+
+- 三级嵌套
+- 评论审核
+- 评论富媒体上传
+- 评论 Markdown 编辑器
+
+## Decisions
+
+### Decision 1: 无限滚动方案
+
+使用 `IntersectionObserver` + 游标分页（cursor-based），替代当前的 offset 分页。
+
+```typescript
+// 游标分页请求
+interface ListCommentsRequest {
+  article_id: string;
+  page_size: number;
+  cursor?: string;  // 基于时间戳的游标
+  sort: 'latest' | 'popular';
+}
+```
+
+后端游标方案：使用 `created_at` 或 `(like_count, created_at)` 作为游标。
+
+### Decision 2: 排序实现
+
+| 排序 | SQL | 说明 |
+|------|-----|------|
+| 最新 | `ORDER BY created_at DESC` | 默认 |
+| 最热 | `ORDER BY like_count DESC, created_at DESC` | 24h 内点赞权重更高 |
+
+Proto 新增：
+```protobuf
+enum CommentSort {
+  COMMENT_SORT_LATEST = 0;
+  COMMENT_SORT_POPULAR = 1;
+}
+
+message ListCommentsRequest {
+  // ...existing fields...
+  CommentSort sort = 5;
+  string cursor = 6;  // 游标分页
+}
+```
+
+### Decision 3: 乐观点赞
+
+```typescript
+// 乐观更新流程
+function handleLike(commentId: string) {
+  // 1. 立即更新 UI（无需等待 API）
+  setComments(prev => toggleLike(prev, commentId));
+  // 2. 后台发送请求
+  likeComment(commentId).catch(() => {
+    // 3. 失败时回滚
+    setComments(prev => toggleLike(prev, commentId));
+  });
+}
+```
+
+### Decision 4: 评论 Markdown 渲染
+
+评论使用 `@luhanxin/md-parser` 的简化渲染模式：
+- 支持 GFM 基础语法（加粗、斜体、代码块、链接、列表）
+- 不加载 Mermaid/KaTeX/自定义语法（减少评论区域包体积）
+- XSS 防护使用 md-parser 内置的 sanitize
+
+### Decision 5: 文章评论数量预览
+
+Proto 修改：
+```protobuf
+message Article {
+  // ...existing fields...
+  int32 comment_count = 16;  // 新增评论数量
+}
+```
+
+后端在文章列表查询时 JOIN comments 表统计数量（或使用 Redis 缓存）。
+
+### Decision 6: 子评论折叠策略
+
+**问题**：热门评论可能有数百条子评论，全量加载影响性能。
+
+**折叠策略**：
+
+| 规则 | 折叠行为 |
+|------|---------|
+| 子评论 ≤ 3 条 | 全部展开 |
+| 子评论 4-10 条 | 显示前 2 条 + "展开查看 X 条回复" |
+| 子评论 > 10 条 | 显示前 2 条 + "展开查看 X 条回复" + 分页加载 |
+
+**实现**：
+
+```typescript
+interface CommentWithReplies {
+  id: string;
+  content: string;
+  replies: Comment[];
+  reply_count: number;     // 总回复数
+  visible_replies: number; // 当前显示的回复数
+  has_more: boolean;       // 是否有更多
+}
+
+// 前端折叠逻辑
+function getVisibleReplies(comment: Comment): Comment[] {
+  if (comment.replies.length <= 3) {
+    return comment.replies;
+  }
+  return comment.replies.slice(0, 2); // 只显示前 2 条
+}
+```
+
+**后端分页加载子评论**：
+
+```protobuf
+message ListRepliesRequest {
+  string comment_id = 1;
+  string cursor = 2;
+  int32 page_size = 3;
+}
+```
+
+### Decision 7: 反垃圾措施
+
+| 措施 | 实现方式 |
+|------|---------|
+| **频率限制** | 同一用户 1 分钟内最多发表 5 条评论 |
+| **内容长度限制** | 评论长度 1-5000 字符 |
+| **敏感词过滤** | 使用 DFA 算法检测敏感词，自动替换为 `***` |
+| **链接限制** | 评论中最多包含 3 个链接 |
+| **举报机制** | 用户可举报评论，管理员审核后删除 |
+| **自动标记** | 5 次举报自动隐藏，等待管理员审核 |
+
+**敏感词过滤实现**：
+
+```rust
+// services/svc-content/src/utils/sensitive_words.rs
+use dfa::DFA;
+
+lazy_static! {
+    static ref SENSITIVE_WORDS_DFA: DFA = {
+        let words = load_sensitive_words_from_db();
+        DFA::new(words)
+    };
+}
+
+pub fn filter_sensitive_words(content: &str) -> String {
+    SENSITIVE_WORDS_DFA.replace_all(content, "***")
+}
+```
+
+**频率限制实现**：
+
+```rust
+// services/gateway/src/middleware/comment_rate_limit.rs
+pub async fn check_comment_rate_limit(user_id: &str, redis: &RedisClient) -> Result<()> {
+    let key = format!("luhanxin:comment_rate:{}", user_id);
+    let count = redis.incr(&key).await?;
+    
+    if count == 1 {
+        redis.expire(&key, 60).await?; // 1 分钟窗口
+    }
+    
+    if count > 5 {
+        return Err(ErrorCode::RateLimitExceeded);
+    }
+    
+    Ok(())
+}
+```
+
+## Risks / Trade-offs
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 游标分页与嵌套评论冲突 | 嵌套评论的父级可能跨页 | 一级评论游标分页，子评论全量加载 |
+| 乐观更新与实际不一致 | 网络差时回滚闪烁 | debounce + 静默重试 |
+| 评论 Markdown XSS | 评论内容被注入 | 复用 md-parser sanitize |
+
+## Open Questions（已解决）
+
+1. **评论「最热」排序的时间窗口？**
+   - ✅ 选择：**30 天窗口**
+   - 理由：平衡时效性和热度，避免旧评论长期霸榜，符合社区活跃度期望
+
+2. **子评论是否也支持无限滚动？**
+   - ✅ 选择：**全量加载（≤50 条）+ 分页加载（>50 条）**
+   - 理由：子评论通常不多，全量加载用户体验更好；超过 50 条时分页，避免性能问题
+
+3. **评论数量是否需要 Redis 缓存？**
+   - ✅ 选择：**需要**
+   - 理由：高并发场景下避免 COUNT 查询，提升性能；使用 `luhanxin:article:comment_count:{id}` 缓存

openspec/changes/archive/2026-04-06-comment-system-upgrade/proposal.md

@@ -0,0 +1,92 @@
+## Why
+
+当前评论系统已实现基础功能（二级嵌套 + @提及），但用户体验和性能存在明显短板：
+
+1. **无限滚动缺失** — 当前使用简单的一次性加载，长评论列表需要翻页，移动端体验差
+2. **无排序能力** — 只能按时间排序，无法按热度/点赞数排序
+3. **评论点赞体验差** — 点赞交互反馈慢，且缺少点赞动画
+4. **Markdown 渲染不支持** — 评论内容纯文本展示，技术讨论中无法展示代码片段
+5. **@提及无跳转** — @用户名没有链接到用户主页
+6. **评论预览缺失** — 文章列表页无法看到评论数量/最新评论摘要
+7. **评论加载性能** — 嵌套评论的数据获取策略不够高效
+
+## What Changes
+
+### 评论列表无限滚动
+
+- 使用 `IntersectionObserver` 实现滚动加载更多评论
+- 骨架屏 loading 状态
+- 后端游标分页（cursor-based pagination）
+
+### 评论排序
+
+- 支持按「最新」和「最热」（点赞数）排序
+- 后端新增排序参数
+
+### 评论点赞增强
+
+- 乐观更新（Optimistic Update）— 点击立即反馈，后台同步
+- 点赞动画效果
+- 点赞状态持久化
+
+### 评论 Markdown 渲染
+
+- 评论内容使用 `@luhanxin/md-parser` 渲染（依赖 `markdown-parser-package` change）
+- 支持 GFM 基础语法（代码片段、链接、加粗等）
+- 不支持 Mermaid/KaTeX 等重量级功能
+
+### @提及跳转
+
+- @用户名渲染为链接，跳转到用户主页
+
+### 评论计数预览
+
+- 文章列表页显示评论数量
+- 文章详情页顶部显示评论摘要（最新 N 条评论预览）
+
+## 非目标 (Non-goals)
+
+- **不做评论结构变更** — 不引入三级或更深层嵌套
+- **不做评论审核系统** — 内容审核不在本次范围
+- **不做评论富媒体** — 不支持图片/视频上传
+- **不做 Markdown 编辑器** — 评论输入仍使用简单 textarea + 快捷工具栏
+- **不涉及后端架构变更** — 微服务结构不变
+
+## 与现有设计文档的关系
+
+- **`docs/design/2026-03-20/06-feature-modules.md`** — 评论系统属于核心功能模块
+- **`openspec/changes/markdown-parser-package/`** — 评论 Markdown 渲染依赖此包
+
+## Capabilities
+
+### New Capabilities
+
+- `comment-infinite-scroll`: 评论无限滚动 — IntersectionObserver + 骨架屏 + 游标分页
+- `comment-sort`: 评论排序 — 最新/最热切换
+- `comment-optimistic-like`: 评论乐观点赞 — 立即反馈 + 后台同步
+
+### Modified Capabilities
+
+- `comment-display`: 评论展示升级 — Markdown 渲染 + @提及跳转
+- `article-list`: 文章列表增强 — 评论数量预览
+
+## Impact
+
+### 代码影响
+
+| 范围 | 变更类型 |
+|------|---------|
+| 评论前端组件 | 重构（无限滚动 + Markdown + 点赞） |
+| 评论 store | 修改（新增排序状态、游标分页） |
+| 文章列表页 | 修改（评论数量预览） |
+| Proto（comment.proto） | 修改（新增排序参数、游标分页） |
+| svc-content | 修改（排序逻辑、游标分页） |
+
+### API 影响
+
+- `ListComments` RPC 新增 `sort` 排序参数和游标分页参数
+- `GetArticle` Response 新增 `comment_count` 字段
+
+### 依赖影响
+
+- 依赖 `@luhanxin/md-parser` 包

openspec/changes/archive/2026-04-06-comment-system-upgrade/tasks.md

@@ -0,0 +1,74 @@
+## 1. Proto 定义更新
+
+- [x] 1.1 在 `proto/luhanxin/community/v1/comment.proto` 中新增 `CommentSort` 枚举（LATEST/POPULAR）
+- [x] 1.2 修改 `ListCommentsRequest` — 新增 `CommentSort sort` 和 `string cursor` 字段
+- [x] 1.3 在 `proto/luhanxin/community/v1/article.proto` 的 `Article` message 中新增 `int32 comment_count = 16`
+- [x] 1.4 执行 `make proto` 生成代码
+
+> **依赖**：无前置依赖。Proto 优先。
+
+## 2. 后端排序与游标分页
+
+- [x] 2.1 修改 `svc-content/handlers/comment/` — `ListComments` handler 支持 sort 参数
+- [x] 2.2 实现游标分页查询 — 基于 `created_at` 游标（POPULAR 排序 TODO 待加 like_count 列）
+- [x] 2.3 修改 comment handler — `list_by_cursor()` 逻辑内联到 list_comments
+- [x] 2.4 实现文章评论数量统计 — Gateway BFF 并发聚合 `enrich_articles`
+- [ ] 2.5 后端测试
+
+> **依赖**：依赖 Phase 1（Proto 定义）。
+
+## 3. 评论前端组件重构
+
+- [x] 3.1 IntersectionObserver 无限滚动 — sentinelRef + rootMargin 200px
+- [x] 3.2 创建 `CommentSkeleton` 骨架屏组件
+- [x] 3.3 重构 `CommentSection` — 集成无限滚动 + 骨架屏 + 折叠/展开 + refreshing 过渡
+- [x] 3.4 创建排序切换组件 — 最新(SortAscendingOutlined) / 最热(FireOutlined) Tab
+- [x] 3.5 修改评论 store — sort/cursor/hasMore/refreshing + loadMore + setSort
+
+> **依赖**：依赖 Phase 2（后端接口就绪）。
+
+## 4. 评论 Markdown 渲染（跳过 — 依赖 md-parser）
+
+- [ ] 4.1 安装 `@luhanxin/md-parser` 依赖
+- [ ] 4.2 创建 `CommentMarkdownRenderer` 组件 — 使用 md-parser 的简化渲染模式
+- [ ] 4.3 配置简化渲染 — 仅启用 GFM + sanitize，禁用 Mermaid/KaTeX/自定义语法
+- [ ] 4.4 替换评论内容渲染 — 从纯文本切换到 CommentMarkdownRenderer
+- [ ] 4.5 编写渲染测试
+
+> **依赖**：依赖 `markdown-parser-package` change 完成。⚠️ md-parser theme 未完善，暂不接入。
+
+## 5. @提及跳转与乐观点赞
+
+- [x] 5.1 实现 @提及链接渲染 — @用户名 → `<Link to="/user/{username}">` 跳转
+- [ ] 5.2 实现乐观点赞 hook — `useOptimisticLike` 乐观更新逻辑
+- [ ] 5.3 实现点赞动画 — CSS transition + 状态变化动画
+- [ ] 5.4 错误回滚处理 — API 失败时恢复点赞状态
+
+> **依赖**：评论点赞需要 Proto + DB migration + 后端 handler 全链路，工作量大。
+> ⚠️ 评论 Proto 尚无 `like_count` 字段，DB 无 `comment_likes` 表，属于全新全栈功能。
+
+## 6. 文章列表评论预览
+
+- [x] 6.1 修改文章列表 store — 使用 comment_count 字段
+- [x] 6.2 修改 `ArticleCard` 组件 — 显示评论数量 + 收藏数量 + 分享按钮
+- [x] 6.3 修改文章详情页顶部 — 显示评论数量 + 收藏数量
+
+> **依赖**：依赖 Phase 1（Proto 新增 comment_count）。
+
+## 6+ 额外完成（超出原 tasks.md 规划）
+
+- [x] Article Proto 新增 `favorite_count = 17`
+- [x] Gateway BFF `enrich_articles` 并发聚合 author + comment_count + favorite_count（tokio::join!）
+- [x] ArticleCard 显示 ⭐ 收藏数 + 🔗 分享按钮（Web Share + clipboard）
+- [x] ArticleActions 悬浮栏新增分享按钮
+- [x] 文章详情页 meta 显示收藏数
+- [x] 排序切换 refreshing 过渡（opacity 0.5，不闪缩）
+- [x] 子评论默认折叠，点击展开/收起
+
+## 7. 验证
+
+- [ ] 7.1 无限滚动测试 — 滚动加载更多评论，骨架屏显示正确
+- [ ] 7.2 排序切换测试 — 最新/最热切换正常
+- [ ] 7.3 点赞交互测试 — 乐观更新 + 错误回滚（依赖 Phase 5）
+- [ ] 7.4 Markdown 渲染测试 — 代码块/链接/加粗等渲染正确（依赖 Phase 4）
+- [ ] 7.5 XSS 测试 — 评论中注入脚本被 sanitize（依赖 Phase 4）