rssWorkFlow/docs/dev-plan.md

# RSS 信息处理平台：开发步骤文档

> 版本：v1.0
> 日期：2026-06-15
> 配套文档：`rss-platform-design.md`

---

## 一、总体策略

### 1.1 开发原则

| 原则 | 说明 |
|------|------|
| **渐进式重构** | 不是一次性推翻重写，而是逐步迁移现有能力 |
| **先跑通再优化** | 先让核心流程（抓取→清洗→AI→存储）跑起来，再扩展高级功能 |
| **数据先行** | 先确定数据模型和迁移方案，再写业务逻辑 |
| **可回滚** | 每个阶段都保留回退到旧系统的能力 |
| **测试护航** | 关键模块必须有单元测试和接口测试 |

### 1.2 阶段划分

```
阶段一：基础骨架（4-5 周）
  → 技术选型确认、项目结构、PostgreSQL 迁移、Docker 环境、基础 API

阶段二：核心流程（4-5 周）
  → RSS 抓取、清洗流水线、去重插件、AI 摘要/分类/Tag/打分、任务调度

阶段三：产出与聊天（3-4 周）
  → Skill 系统、日报任务、聊天窗口、引用链接

阶段四：自优化与工业化（3-4 周）
  → 自优化调度器、去重算法自优化、监控、日志、备份

阶段五：规模化与优化（持续）
  → 性能优化、OpenSearch、分库分表、服务拆分
```

---

## 二、阶段一：基础骨架（Week 1-5）

### 目标
搭建可运行的基础平台，完成数据库迁移、Docker 环境、用户鉴权、基础 API。

### 任务清单

#### Week 1：项目初始化与技术选型确认

| 任务 | 说明 | 产出 |
|------|------|------|
| 2.1.1 创建 monorepo | 在 `/home/congsh/workspace/dev/rss-platform` 初始化项目 | `README.md`、`Makefile`、`docker-compose.yml` |
| 2.1.2 确定目录结构 | 按模块划分目录 | 见下方目录结构 |
| 2.1.3 选择并锁定依赖版本 | Python 3.12、FastAPI、SQLAlchemy 2.0、Celery、PostgreSQL、Redis | `backend/requirements.txt` |
| 2.1.4 配置代码质量工具 | ruff、black、pytest、pre-commit | `.pre-commit-config.yaml`、`pyproject.toml` |
| 2.1.5 创建 Docker 基础镜像 | 后端、前端、PostgreSQL、Redis、MinIO | `Dockerfile`、`docker-compose.dev.yml` |

**推荐目录结构：**
```
rss-platform/
├── backend/
│   ├── app/
│   │   ├── core/           # 配置、日志、异常、鉴权
│   │   ├── models/         # SQLAlchemy 模型
│   │   ├── schemas/        # Pydantic 模型
│   │   ├── api/            # API 路由
│   │   ├── services/       # 业务服务
│   │   ├── tasks/          # Celery 任务
│   │   ├── plugins/        # 插件接口与加载器
│   │   ├── ai/             # AI 调用、Provider 路由
│   │   ├── skills/         # Skill 加载与执行
│   │   ├── search/         # 检索服务
│   │   ├── chat/           # 聊天引擎
│   │   └── optimization/   # 自优化
│   ├── alembic/            # 数据库迁移
│   ├── tests/
│   └── main.py
├── frontend/
│   ├── src/
│   │   ├── views/
│   │   ├── components/
│   │   ├── api/
│   │   ├── stores/
│   │   └── router/
│   └── package.json
├── plugins/
│   └── deduplication/
├── docker/
│   ├── backend.Dockerfile
│   ├── frontend.Dockerfile
│   └── docker-compose.yml
├── docs/
└── scripts/
    ├── migrate_from_sqlite.py
    └── init_dev_env.sh
```

#### Week 2：PostgreSQL 数据模型与迁移

| 任务 | 说明 | 产出 |
|------|------|------|
| 2.2.1 设计并创建核心表 | users、feeds、raw_articles、cleaned_articles、article_references、skills 等 | `backend/app/models/` |
| 2.2.2 配置 Alembic | 初始化迁移工具 | `alembic.ini`、baseline migration |
| 2.2.3 编写 SQLite → PostgreSQL 迁移脚本 | 从 rssKeeper + dataClean 导出并导入 | `scripts/migrate_from_sqlite.py` |
| 2.2.4 验证迁移数据完整性 | 对比条数、关键字段抽样 | 迁移报告 |
| 2.2.5 配置 pgvector 扩展 | 安装并创建向量表 | `article_embeddings` 表 |

#### Week 3：FastAPI 基础与鉴权

| 任务 | 说明 | 产出 |
|------|------|------|
| 2.3.1 FastAPI 项目骨架 | lifespan、中间件、异常处理、日志 | `backend/main.py` |
| 2.3.2 JWT 鉴权 | 登录、注册、Token 刷新、API Key | `backend/app/core/auth.py` |
| 2.3.3 简单 RBAC | admin / member 角色 | `backend/app/core/rbac.py` |
| 2.3.4 CORS 安全配置 | 白名单、关闭 credentials | `backend/main.py` |
| 2.3.5 健康检查与 OpenAPI | `/health`、`/openapi.json` | API 文档 |

#### Week 4：配置中心与锁服务

| 任务 | 说明 | 产出 |
|------|------|------|
| 2.4.1 配置中心 | 环境变量 + DB 覆盖 + 版本化 | `backend/app/core/settings.py` |
| 2.4.2 Redis 连接 | 缓存、锁、消息队列 | `backend/app/core/redis.py` |
| 2.4.3 分布式锁服务 | 任务锁、文章锁 | `backend/app/services/lock_service.py` |
| 2.4.4 任务运行时状态 | 进度追踪、任务日志 | `backend/app/services/task_runtime.py` |
| 2.4.5 日志与请求 ID | 结构化日志、request_id | `backend/app/core/logging.py` |

#### Week 5：前端基础与管理后台

| 任务 | 说明 | 产出 |
|------|------|------|
| 2.5.1 Vue 3 + TS 项目初始化 | Vite、Element Plus、Pinia、Vue Router | `frontend/` |
| 2.5.2 登录页 | JWT 登录、API Key 管理 | `LoginView.vue` |
| 2.5.3 RSS 源管理页 | 列表、添加、编辑、删除 | `FeedsView.vue` |
| 2.5.4 文章列表页 | 分页、筛选 | `ArticlesView.vue` |
| 2.5.5 Docker Compose 联调 | 全栈本地启动 | `docker-compose.yml` |

### 阶段一交付物
- [ ] 可本地 `docker-compose up` 运行的基础平台
- [ ] PostgreSQL 数据库 + 迁移脚本
- [ ] JWT 鉴权 + 简单 RBAC
- [ ] RSS 源 CRUD + 文章列表
- [ ] 分布式锁服务

### 阶段一里程碑
**M1：基础平台骨架完成，可管理 RSS 源和查看文章列表。**

---

## 三、阶段二：核心流程（Week 6-10）

### 目标
实现抓取→清洗→去重→AI 处理→存储的完整流水线。

### 任务清单

#### Week 6：RSS 抓取迁移与增强

| 任务 | 说明 | 产出 |
|------|------|------|
| 3.6.1 迁移抓取逻辑 | 从 rssKeeper `rss_fetcher.py` 迁移 | `backend/app/services/feed_fetcher.py` |
| 3.6.2 Celery 抓取任务 | `fetch_feed_task`、`fetch_all_feeds_task` | `backend/app/tasks/feeds.py` |
| 3.6.3 Celery Beat 调度 | 按 Feed 间隔注册定时任务 | `backend/app/tasks/scheduler.py` |
| 3.6.4 抓取失败重试 | 指数退避、死信队列 | 重试装饰器 |
| 3.6.5 Feed 健康度统计 | 复用 rssKeeper 逻辑 | `backend/app/services/health_checker.py` |

#### Week 7：清洗流水线

| 任务 | 说明 | 产出 |
|------|------|------|
| 3.7.1 数据标准化 | URL 规范化、HTML 清洗、时间标准化 | `backend/app/services/normalizer.py` |
| 3.7.2 正文提取 | 优先 RSS content，fallback 原文页 | `backend/app/services/content_extractor.py` |
| 3.7.3 清洗任务 Celery 化 | `process_raw_article_task` | `backend/app/tasks/pipeline.py` |
| 3.7.4 内容 hash 与语言检测 | 用于后续去重 | 辅助字段 |
| 3.7.5 清洗状态机 | pending → processing → cleaned / failed | `processing_status` |

#### Week 8：去重插件系统

| 任务 | 说明 | 产出 |
|------|------|------|
| 3.8.1 定义插件接口 | `DeduplicationPlugin` | `backend/app/plugins/base.py` |
| 3.8.2 实现默认去重插件 | URL + 标题 exact + TF-IDF 内容相似 | `plugins/deduplication/current.py` |
| 3.8.3 插件加载器 | 动态 import + 热加载 | `backend/app/plugins/loader.py` |
| 3.8.4 引用关系写入 | `article_references` + `reference_links` | 去重服务 |
| 3.8.5 去重任务接口 | 手动触发、查看结果 | `/api/tasks/deduplicate` |
| 3.8.6 插件版本元数据 | `metadata.json` | 版本管理 |

#### Week 9：AI 处理中心

| 任务 | 说明 | 产出 |
|------|------|------|
| 3.9.1 AI Provider 配置模型 | openai / anthropic / gemini / local | `backend/app/models/ai_provider_config.py` |
| 3.9.2 AI 任务配置模型 | 每个任务独立配置 | `backend/app/models/ai_task_config.py` |
| 3.9.3 LiteLLM/自封装多供应商路由 | 统一调用接口 | `backend/app/ai/client.py` |
| 3.9.4 AI 摘要任务 | 复用 dataClean `summarizer.py` | `backend/app/tasks/ai_tasks.py` |
| 3.9.5 AI 分类任务 | 从规则分类迁移到 AI 分类 | `backend/app/tasks/ai_tasks.py` |
| 3.9.6 AI Tag 任务 | AI 打标签 | `backend/app/tasks/ai_tasks.py` |
| 3.9.7 AI 打分任务 | heat/importance/composite | `backend/app/tasks/ai_tasks.py` |

#### Week 10：流水线编排与任务调度

| 任务 | 说明 | 产出 |
|------|------|------|
| 3.10.1 流水线编排器 | 组合抓取→清洗→去重→AI 处理 | `backend/app/services/pipeline_orchestrator.py` |
| 3.10.2 任务进度追踪 | 复用 dataClean `task_progress.py` | `backend/app/services/task_progress.py` |
| 3.10.3 手动/定时任务互斥 | Redis 锁 + Celery | 调度服务 |
| 3.10.4 仪表盘统计 API | 文章数、分类分布、任务状态 | `/api/stats` |
| 3.10.5 前端仪表盘 | 统计卡片、任务进度 | `DashboardView.vue` |

### 阶段二交付物
- [ ] RSS 自动抓取 + Celery 调度
- [ ] 清洗流水线
- [ ] 去重插件系统（默认实现 + 热加载）
- [ ] AI 摘要/分类/Tag/打分
- [ ] 流水线编排与任务进度

### 阶段二里程碑
**M2：核心流程跑通，一篇文章从 RSS 抓取到 AI 处理完成可自动化执行。**

---

## 四、阶段三：产出与聊天（Week 11-14）

### 目标
实现 Skill 系统、日报任务、聊天窗口、引用链接。

### 任务清单

#### Week 11：Skill 系统基础

| 任务 | 说明 | 产出 |
|------|------|------|
| 4.11.1 Skill 数据模型 | skills、skill_versions | 数据库表 |
| 4.11.2 Skill 加载与执行 | 解析 prompt、schema、tools | `backend/app/skills/loader.py` |
| 4.11.3 内置默认 Skills | 摘要、分类、Tag、打分、日报、聊天 | `backend/app/skills/defaults/` |
| 4.11.4 Skill CRUD API | 创建、修改、导入、导出、恢复默认 | `/api/skills/*` |
| 4.11.5 Skill 管理前端 | 编辑器、导入导出 | `SkillsView.vue` |

#### Week 12：日报任务系统

| 任务 | 说明 | 产出 |
|------|------|------|
| 4.12.1 OutputTask 模型 | task + skill + filter + schedule | 数据库表 |
| 4.12.2 日报生成任务 | 复用 dataClean `brief.py`，改为 Skill 驱动 | `backend/app/tasks/output_tasks.py` |
| 4.12.3 数据筛选 DSL | 时间、分类、Tag、分数过滤 | Filter builder |
| 4.12.4 多种日报类型 | 科技观察、综合日报等 | 多个 OutputTask |
| 4.12.5 日报前端 | 列表、详情、重新生成 | `BriefsView.vue` |

#### Week 13：聊天引擎

| 任务 | 说明 | 产出 |
|------|------|------|
| 4.13.1 聊天数据模型 | sessions、messages | 数据库表 |
| 4.13.2 聊天 API | 创建会话、发送消息、历史记录 | `/api/chat/*` |
| 4.13.3 Tool 调用框架 | 搜索文章、获取文章详情、调用外部 API | `backend/app/chat/tools.py` |
| 4.13.4 引用链接解析 | 从 AI 输出提取标记并映射链接 | `backend/app/chat/references.py` |
| 4.13.5 聊天前端 | 对话界面、引用渲染 | `ChatView.vue` |

#### Week 14：工具与产出集成

| 任务 | 说明 | 产出 |
|------|------|------|
| 4.14.1 外部 API Tool | 调用用户配置的 HTTP API | `fetch_external_api` tool |
| 4.14.2 产出导出 | Markdown、JSON、邮件 | `backend/app/services/exporters.py` |
| 4.14.3 聊天中运行 Skill | 用户选择 Skill 进行专项对话 | Skill selector |
| 4.14.4 会话上下文管理 | 窗口大小、历史摘要 | Context manager |
| 4.14.5 集成测试 | 端到端聊天流程 | `tests/test_chat.py` |

### 阶段三交付物
- [ ] Skill 系统（CRUD + 默认 Skills）
- [ ] 可配置的日报任务系统
- [ ] 聊天窗口（支持 Tool 调用和引用链接）
- [ ] 外部 API Tool

### 阶段三里程碑
**M3：平台具备 AI 产出能力，日报和聊天均可调用 Skills 生成带引用链接的内容。**

---

## 五、阶段四：自优化与工业化（Week 15-18）

### 目标
实现每日凌晨 2 点自优化、去重算法自优化、监控、备份、日志。

### 任务清单

#### Week 15：自优化调度器

| 任务 | 说明 | 产出 |
|------|------|------|
| 5.15.1 自优化数据收集 | 收集最近执行样例、历史优化记录 | `backend/app/optimization/collector.py` |
| 5.15.2 Prompt/Skill 优化器 | 用 AI 评审并生成候选 Prompt | `backend/app/optimization/prompt_optimizer.py` |
| 5.15.3 优化器自评逻辑 | 候选 vs 当前版本评分 | 评估服务 |
| 5.15.4 自动发布机制 | 保存新版本、自动生效 | 发布服务 |
| 5.15.5 优化日志 | `optimization_logs` 表 + API | 留痕 |

#### Week 16：去重算法自优化

| 任务 | 说明 | 产出 |
|------|------|------|
| 5.16.1 去重算法优化器 | 分析样例生成候选算法代码 | `backend/app/optimization/dedup_optimizer.py` |
| 5.16.2 算法版本备份 | 自动生成 `.bak` | 版本管理 |
| 5.16.3 算法热加载与回滚 | 失败自动回滚 | 插件加载器增强 |
| 5.16.4 算法性能评估 | 运行时间、内存、误判漏判 | 评估服务 |
| 5.16.5 手动回滚 API | `/api/admin/deduplication/rollback` | 管理接口 |

#### Week 17：监控与可观测性

| 任务 | 说明 | 产出 |
|------|------|------|
| 5.17.1 Prometheus 指标 | 任务数、AI 调用数、延迟、失败率 | `/metrics` |
| 5.17.2 Grafana 仪表盘 | 系统状态、任务状态、AI 成本 | `docker/grafana/` |
| 5.17.3 Sentry 集成 | 错误追踪 | 配置 |
| 5.17.4 日志聚合 | Loki 或文件日志 | 日志配置 |
| 5.17.5 告警规则 | 任务失败、AI 调用异常 | Alert rules |

#### Week 18：备份、安全与部署

| 任务 | 说明 | 产出 |
|------|------|------|
| 5.18.1 PostgreSQL 自动备份 | 每日备份、保留策略 | `scripts/backup_db.sh` |
| 5.18.2 对象存储备份 | 插件、导出产物备份 | 备份脚本 |
| 5.18.3 安全加固 | API 限流、密码策略、敏感配置加密 | 安全文档 |
| 5.18.4 生产 Docker Compose | 多 Worker 配置 | `docker-compose.prod.yml` |
| 5.18.5 部署文档 | 完整部署步骤 | `docs/deployment.md` |

### 阶段四交付物
- [ ] 每日 2:00 自优化调度器
- [ ] 去重算法自优化 + 版本回滚
- [ ] Prometheus + Grafana 监控
- [ ] 自动备份方案
- [ ] 生产部署文档

### 阶段四里程碑
**M4：平台具备工业化能力，可无人值守运行并自动优化。**

---

## 六、阶段五：规模化与持续优化（Week 19+）

### 目标
根据实际数据量和负载进行性能优化和架构扩展。

### 任务清单

| 任务 | 说明 | 时机 |
|------|------|------|
| 6.1 迁移到 OpenSearch | 当 PG tsvector 性能不足时 | 10万+ 文章 |
| 6.2 向量检索优化 | 使用专用向量库（Qdrant/Milvus） | 需要语义检索时 |
| 6.3 去重算法升级 | LSH/MinHash/Embedding | 日增 5000+ 时 |
| 6.4 数据库读写分离 | 主从复制 | 读压力高时 |
| 6.5 按时间分库 | 历史数据归档 | 50万+ 文章 |
| 6.6 服务拆分 | 拆分为 feed-service、ai-service 等 | 团队扩大时 |
| 6.7 缓存层优化 | Redis 缓存热门查询、文章 | 读压力大时 |
| 6.8 AI 调用成本优化 | 缓存 Embedding、批量调用、模型降级 | AI 成本高时 |

---

## 七、关键依赖清单

### 7.1 Python 后端

```txt
fastapi==0.115.0
uvicorn[standard]==0.30.0
sqlalchemy[asyncio]==2.0.31
asyncpg==0.29.0
alembic==1.13.2
psycopg2-binary==2.9.9
celery==5.4.0
redis==5.0.7
pydantic==2.8.2
pydantic-settings==2.3.4
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.9
httpx==0.27.0
feedparser==6.0.11
beautifulsoup4==4.12.3
lxml==5.2.2
scikit-learn==1.5.1
numpy==1.26.4
openai==1.35.0
litellm==1.41.0
langdetect==1.0.9
watchdog==4.0.1
prometheus-client==0.20.0
sentry-sdk==2.7.0
pytest==8.2.2
pytest-asyncio==0.23.7
```

### 7.2 前端

```json
{
  "vue": "^3.4.0",
  "vue-router": "^4.3.0",
  "pinia": "^2.1.0",
  "element-plus": "^2.7.0",
  "axios": "^1.7.0",
  "typescript": "^5.4.0",
  "marked": "^13.0.0",
  "dompurify": "^3.1.0"
}
```

### 7.3 基础设施

| 组件 | 版本 | 用途 |
|------|------|------|
| PostgreSQL | 16+ | 主数据库 |
| Redis | 7+ | 缓存、锁、消息队列 |
| MinIO | latest | 对象存储 |
| Prometheus | latest | 指标采集 |
| Grafana | latest | 监控仪表盘 |

---

## 八、测试策略

### 8.1 单元测试

| 模块 | 测试重点 |
|------|----------|
| `plugins/deduplication` | URL/标题/内容去重、代表文章选择 |
| `app/services/normalizer` | URL 规范化、HTML 清洗 |
| `app/ai/client` | 多 Provider 路由、Fallback |
| `app/skills/loader` | Skill 解析、Schema 校验 |
| `app/chat/references` | 引用标记解析与链接映射 |
| `app/services/lock_service` | 锁获取/释放/超时 |

### 8.2 集成测试

| 模块 | 测试重点 |
|------|----------|
| `/api/feeds` | CRUD、抓取触发 |
| `/api/tasks/deduplicate` | 去重任务全流程 |
| `/api/chat/sessions` | 创建会话、发送消息 |
| `/api/output-tasks` | 创建任务、手动运行 |
| `/api/admin/deduplication/rollback` | 算法回滚 |

### 8.3 端到端测试

- 发布 RSS → 抓取 → 清洗 → 去重 → AI 处理 → 日报生成
- 聊天中提问 → 检索文章 → AI 回答 → 验证引用链接

---

## 九、里程碑与验收标准

| 里程碑 | 时间 | 验收标准 |
|--------|------|----------|
| M1 基础骨架 | Week 5 | `docker-compose up` 可运行；可管理 Feed；可查看文章列表；JWT 鉴权可用 |
| M2 核心流程 | Week 10 | 一条 RSS 文章能自动完成：抓取→清洗→去重→AI 摘要/分类/Tag/打分 |
| M3 产出与聊天 | Week 14 | 可创建日报任务并生成日报；可在聊天中提问并获得带引用链接的回答 |
| M4 自优化与工业化 | Week 18 | 每日 2:00 自优化成功执行并留痕；去重算法可热加载和回滚；监控可用 |
| M5 规模化 | 持续 | 根据数据量完成 OpenSearch/分库等扩展 |

---

## 十、风险与应对

| 风险 | 阶段 | 影响 | 应对 |
|------|------|------|------|
| SQLite → PostgreSQL 迁移复杂 | 阶段一 | 高 | 编写迁移脚本 + 数据校验 + 保留旧系统 |
| Celery 任务状态丢失 | 阶段二 | 中 | 使用 Redis 持久化 + 任务结果 backend |
| 去重插件热加载失败 | 阶段二/四 | 高 | 失败自动回滚上一个 `.bak` |
| AI 自优化产生劣质结果 | 阶段四 | 中 | 优化器自评 + 版本化 + 不自动删除旧版本 |
| AI 调用成本高 | 全程 | 中 | 多供应商路由 + Fallback + 结果缓存 |
| 前端 TypeScript 迁移成本 | 阶段一 | 低 | 新平台前端直接用 TS，旧前端代码逐步重写 |
| 数据量增长超预期 | 阶段五 | 中 | 分区表 + 预留 OpenSearch/向量库扩展路径 |

---

## 十一、交付文档清单

| 文档 | 负责阶段 | 状态 |
|------|----------|------|
| 本开发步骤文档 | 全程 | ✅ |
| 架构设计文档 | 全程 | ✅ `rss-platform-design.md` |
| API 接口详细文档 | 阶段一~三 | 待编写 |
| Skill 开发指南 | 阶段三 | 待编写 |
| 自优化机制说明 | 阶段四 | 待编写 |
| Docker 部署手册 | 阶段一/四 | 待编写 |
| 数据迁移手册 | 阶段一 | 待编写 |
| 运维监控手册 | 阶段四 | 待编写 |

---

## 十二、后续建议

1. **先验证核心假设**：在阶段二结束前，用真实 RSS 源跑一周，观察去重效果和 AI 输出质量。
2. **Prompt 工程优先于自优化**：初期先人工调优 Prompt，阶段四再引入自优化。
3. **保留旧系统并行运行**：直到阶段三结束，旧 rssKeeper + dataClean 可继续服务，降低切换风险。
4. **建立反馈闭环**：即使不自优化，也要先收集用户对 AI 产出的反馈数据。
5. **控制 AI 成本**：为每个任务设置预算上限和模型降级策略。

---

## 十三、快速启动命令（预期）

```bash
# 1. 克隆项目
cd /home/congsh/workspace/dev
git clone <new-repo-url> rss-platform
cd rss-platform

# 2. 启动基础设施
docker-compose -f docker-compose.dev.yml up -d postgres redis minio

# 3. 初始化数据库
cd backend
alembic upgrade head
python scripts/migrate_from_sqlite.py \
  --rsskeeper-db /path/to/rsskeeper.db \
  --dataclean-db /path/to/dataclean.db

# 4. 启动后端
uvicorn main:app --reload --port 8000

# 5. 启动前端
cd ../frontend
npm install
npm run dev

# 6. 启动 Celery Worker
cd ../backend
celery -A app.tasks worker -Q default,fetch,ai -l info
celery -A app.tasks beat -l info
```

---

*本文档与 `rss-platform-design.md` 配套使用，开发过程中应根据实际情况迭代更新。*