feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 39af400fc8
472 changed files with 36277 additions and 0 deletions
@@ -0,0 +1,159 @@
+# 文章模块功能完善计划
+
+## Summary
+修复文章模块的功能缺陷，并添加搜索、相关推荐、阅读进度等核心新功能，提升用户体验。
+
+## Current State Analysis
+
+### 已有功能
+- ✅ 文章列表（网格/列表视图）
+- ✅ 分类筛选 + 排序 + 分页
+- ✅ 文章详情页（含封面、作者信息、标签）
+- ✅ 点赞 / 收藏 / 评论 / 回复
+- ✅ @用户提及功能
+- ✅ 评论点赞
+- ✅ 分享（复制链接）
+- ✅ 文章管理后台（基础版）
+
+### 功能缺陷
+1. **关注按钮无实际功能** - `ArticleDetail.tsx:392-399` 只切换本地状态；`UserHome.tsx:543-546` 只显示"即将开放"
+2. **无文章种子数据** - `article/management/commands/` 下没有 `seed_articles.py`
+3. **点击标签无法筛选** - `Articles.tsx` 中标签没有点击事件，无法按标签筛选
+
+### 缺失的核心功能
+- 文章搜索（按标题/摘要/标签）
+- 相关推荐（同分类或同标签）
+- 阅读进度条
+- 评论分页加载
+
+---
+
+## Proposed Changes
+
+### Phase 1: 修复功能缺陷
+
+#### 1.1 添加 Follow 模型（后端）
+**文件**: `user/models.py`
+- 添加 `Follow` 模型：
+  ```python
+  class Follow(models.Model):
+      follower = models.ForeignKey(FUser, on_delete=models.CASCADE, related_name='following')
+      following = models.ForeignKey(FUser, on_delete=models.CASCADE, related_name='followers')
+      created_at = models.DateTimeField(auto_now_add=True)
+
+      class Meta:
+          unique_together = ('follower', 'following')
+          ordering = ['-created_at']
+  ```
+
+#### 1.2 添加关注 API（后端）
+**文件**: `user/views/user.py`
+- `FollowToggleView` - 关注/取消关注
+  - POST /api/users/<user_id>/follow/
+  - 返回: { is_following: bool, follower_count: int, following_count: int }
+
+**文件**: `user/urls.py`
+- 添加路由: `path('<int:user_id>/follow/', FollowToggleView.as_view())`
+
+#### 1.3 添加种子数据命令
+**文件**: `article/management/commands/seed_articles.py`
+- 创建 6-8 篇示例文章
+- 覆盖不同分类：tech, design, productivity, industry, React, Python
+- 包含封面图 URL、标签、摘要、内容
+
+#### 1.4 前端关注按钮接入真实 API
+**文件**: `ArticleDetail.tsx`
+- 修改 `handleFollow` 函数调用真实 API
+- 加载时检查当前关注状态
+- 关注/取消关注后更新本地状态和计数
+
+**文件**: `utils/request.ts`
+- 添加 `user.follow(userId)` API 调用
+
+#### 1.5 标签点击筛选
+**文件**: `Articles.tsx`
+- 标签添加点击事件，跳转到文章列表并筛选该标签
+- 支持通过 URL 参数 `?tag=xxx` 筛选
+- 后端 `ArticleListCreateView.get_queryset()` 支持 `tag` 参数
+
+---
+
+### Phase 2: 核心新功能
+
+#### 2.1 文章搜索
+**文件**: `article/views.py`
+- `ArticleListCreateView.get_queryset()` 支持 `search` 参数
+- 搜索范围：title, excerpt, tags（使用 Q 对象）
+
+**文件**: `Articles.tsx`
+- 在分类筛选栏添加搜索输入框
+- 输入时实时搜索（防抖 300ms）
+- 支持回车触发搜索
+
+#### 2.2 相关推荐
+**文件**: `article/views.py`
+- `ArticleDetailView.get()` 返回 `related_articles` 字段
+- 逻辑：同分类 4 篇 + 同标签 4 篇，排除当前文章，按 views 排序取前 4
+
+**文件**: `ArticleDetail.tsx`
+- 详情页底部添加"相关推荐"区域
+- 显示文章卡片（封面、标题、浏览量）
+
+#### 2.3 阅读进度条
+**文件**: `ArticleDetail.tsx`
+- 页面顶部添加固定进度条
+- 监听 scroll 事件，根据文章区域计算阅读百分比
+
+#### 2.4 评论分页
+**文件**: `article/views.py`
+- `ArticleCommentListCreateView` 添加分页支持
+- 支持 `page` 和 `page_size` 参数
+
+**文件**: `ArticleDetail.tsx`
+- 评论列表底部添加"加载更多"按钮
+- 或使用无限滚动加载
+
+---
+
+### Phase 3: 增强功能（可选）
+
+#### 3.1 文章目录（TOC）
+- 从文章内容解析 h2/h3 标题生成目录
+- 固定侧边栏显示，点击跳转到对应位置
+- 高亮当前阅读位置
+
+#### 3.2 文章管理页分类筛选
+**文件**: `ArticleManage.tsx`
+- 在状态筛选旁添加分类筛选下拉框
+
+#### 3.3 社交分享增强
+- 微信分享生成二维码
+- 微博分享链接
+
+---
+
+## Assumptions & Decisions
+
+1. **关注关系设计**: 单向关注（类似 Twitter），非双向好友
+2. **搜索范围**: 标题 + 摘要 + 标签，暂不搜索正文（性能考虑）
+3. **相关推荐优先级**: 同分类优先，其次同标签
+4. **评论分页**: 每页 10 条，支持"加载更多"
+5. **种子文章**: 使用外部图片 URL（Unsplash），不依赖本地上传
+
+## Verification
+
+### 功能缺陷修复验证
+- [ ] 关注按钮能正确显示关注状态，点击后状态切换
+- [ ] 种子数据命令成功执行，创建 6-8 篇文章
+- [ ] 点击文章标签能跳转到列表页并筛选该标签
+
+### 新功能验证
+- [ ] 搜索框输入关键词能实时显示匹配文章
+- [ ] 文章详情页底部显示相关推荐
+- [ ] 阅读时顶部进度条正确显示百分比
+- [ ] 评论超过 10 条时显示"加载更多"按钮
+
+### API 验证
+- [ ] POST /api/users/<id>/follow/ 返回正确状态
+- [ ] GET /api/articles/?search=xxx 返回搜索结果
+- [ ] GET /api/articles/<id>/ 返回 related_articles 字段