# mocra 重构文档
> 本目录是 mocra 从「企业级采集平台」重构为「可嵌入的分布式爬虫库」的设计与实施文档。
> 面向维护者与实现者,非最终用户指南。语言:中文。
## 这是什么
mocra 的引擎内核是可靠的——队列驱动、单机↔分布式零改动扩展、DAG 编排清晰。真正挡在「简单易用」面前的,是它的**使用模型**:一套以数据库为中心的多租户 RPA 抽象(`account × platform × module` 三元组,全部由数据库表驱动)。
本次重构的目标:
1. **让它像一个库** —— 三行代码写个 `Spider` 就能跑,数据库和重型依赖变为可选。
2. **让它能快速起集群** —— 去掉 Redis 依赖,控制面用内嵌的 **redb + Raft** 自组网、强一致;数据面保留**多消息队列可插拔**,用户自选 Kafka / NATS / Redis 搬运与消费数据。
3. **保留强内核** —— 现有管线、DAG 引擎、协调层、代理池是资产,以「抽取 / 加薄层」为主,不推倒重写。
## 一句话判断
> **这主要是 API 与工程封装问题,不是重写。** 分阶段推进,Phase 0+1 就能交付「简单 API」这个最大卖点,且几乎不触碰核心管线。
## 文档索引
| [01 · 现状评估](01-assessment.md) | mocra 今天是什么、核心问题(DB 耦合)、阻碍清单、子系统质量地图 |
| [02 · 目标 API](02-target-api.md) | `Spider` trait、`Mocra` 构建器、分层 API(L0/L1/L2)、`DataSink` 出口 |
| [03 · 集群架构](03-cluster-architecture.md) | redb+Raft 控制面 / 可插拔 MQ 数据面、分区归属、拓扑(方案 A)、组网与故障接管、Rust 选型 |
| [04 · 实施路线](04-roadmap.md) | 分阶段路线图、workspace/crate 布局、任务拆解、发布与兼容策略 |
## 路线图速览
| **Phase 0** | 地基止血:workspace + CI、特性门控、去除 `process::exit`、修文档漂移 | 低 | ✅ |
| **Phase 1** | 门面 API:`Spider` + `Mocra::builder()` + `on_item`/`DataSink`(薄层加在现引擎之上) | 低 | ✅ |
| **Phase 2** | 解耦内核:拆 `State` 上帝对象、DB 变可选、收敛 `pub` 边界 | 中 | ✅ |
| **Phase 3** | 集群化:`mocra-cluster`(redb+Raft 控制面)替 Redis 协调;合并 DAG;抽取子 crate | 较高 | ✅ 分步 |
| **Phase 4** | 发布打磨:docs.rs、MSRV、语义版本、基准 | 低 | ✅ |
## 关键决策记录(ADR 摘要)
| 1 | 控制面存储/共识 | **redb + openraft** | 纯 Rust、无 C++ 工具链、可嵌入;避开 RocksDB 的重型 native 构建 |
| 2 | 数据面传输 | **保留 `MqBackend` 多实现**(Kafka/NATS/Redis/…) | 高吞吐扇出不该走共识;用户自选 MQ 消费数据 |
| 3 | 控制面 / 数据面 | **物理分离,分区归属表衔接** | 共识只管小体量强一致元数据;消息流不进 Raft 日志(Kafka-KRaft 同款思路) |
| 4 | 集群拓扑 | **方案 A:小 Raft 投票核心(3~5)+ 多 worker** | etcd/TiKV 成熟模型;避免上百节点塞进一个 Raft 组 |
| 5 | 去重/会话/限流的归处 | **owner 节点本地 redb,按分区授权** | 高频,既不进 MQ 也不进 Raft;爬虫容忍近似 |
| 6 | 用户 API 主入口 | **`Spider` trait + `Mocra::builder()`** | `ModuleTrait`+DAG 保留给多阶段进阶场景 |
## 可视化设计稿
- 重构总览(平台 → 库):现状/目标 API 前后对比、路线图
- 集群架构:两平面全景图、职责划分、组网时序
> 上述可视化稿在设计讨论中产出,内容已固化进本目录 01–04 文档。