# BookFlow — Layer 2: 范围层 (Scope)

> 文档版本：v3.0
> 日期：2026-04-29
> 设计框架：Jesse James Garrett《用户体验要素》五层模型
> 前置文档：bookflow-L1-strategy.md v3.0
> v3.0 变更：每个子服务增加成果物追踪；可扩展维度列表化；系统B 增加管理后台和 SEO

---

## 2.1 两套子系统功能总览

```
┌─────────────────────────────────────────────────────────────────┐
│  子系统A：内部自动化管线                                         │
│                                                                 │
│  设计核心：每个服务/子服务的 运行状态 + 成果物追踪 + 可扩展     │
│                                                                 │
│  仪表盘（上帝视角）                                              │
│    └── 聚合所有主服务的关键指标和成果物计数                      │
│                                                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ S1 发现   │ │ S2 下载   │ │ S3 OCR   │ │ S4 翻译   │          │
│  │ ┌────────┐│ │ ┌────────┐│ │          │ │ ┌────────┐│          │
│  │ │多数据源││ │ │多存储  ││ │          │ │ │多供应商││          │
│  │ │·Anna's ││ │ │·本地   ││ │          │ │ │·OpenAI ││          │
│  │ │·LibGen ││ │ │·R2     ││ │          │ │ │·DeepSeek│          │
│  │ │·...    ││ │ │·IPFS   ││ │          │ │ │·...    ││          │
│  │ └────────┘│ │ └────────┘│ │          │ │ └────────┘│          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                       │
│  │ S5 管道   │ │ S6 闲鱼   │ │ S7 存储   │                       │
│  │          │ │ ┌────────┐│ │          │                       │
│  │          │ │ │多店铺  ││ │          │                       │
│  │          │ │ │·店#1   ││ │          │                       │
│  │          │ │ │·店#2   ││ │          │                       │
│  │          │ │ └────────┘│ │          │                       │
│  └──────────┘ └──────────┘ └──────────┘                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  子系统B：外部用户服务                                           │
│                                                                 │
│  用户侧：搜索 → 下载/翻译 → 查看（原文/译文/对比）→ 文件管理   │
│  管理侧：用户管理 · 业务统计 · 异常追踪 · SEO运营 · 内容管理   │
│                                                                 │
│  用户分层：Free → Pro → Max → API（限额递增）                   │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2.2 子系统A：服务层级 + 成果物追踪

### S1: 书籍发现（主服务）

**可扩展维度：数据源（列表）**
当前只有 Anna's Archive，未来增加 LibGen、Google Reader 等。每个数据源是列表中独立的一项。

| 数据源 | 状态 | 说明 |
|--------|------|------|
| Anna's Archive | ✅ 已接入 | 当前主力 |
| Library Genesis | 📋 计划中 | 学术书籍为主 |
| Google Books Reader | 📋 计划中 | 预览版书籍 |
| Standard Ebooks | 📋 计划中 | 公版书精校版 |
| [＋ 添加数据源] | — | 未来任意扩展 |

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S1.1 Amazon 爬虫 | 爬取排行榜 | 爬取任务 | 待运行 / 运行中 / 完成 / 失败 |
| S1.2 元数据提取 | 提取书名/作者/ISBN | 元数据记录 | 已提取 / 格式异常 / 已入库 |
| S1.3 数据源匹配 | 在各数据源查找可用性 | 匹配结果 | 已找到 / 未找到 / 多源可用 |
| S1.4 去重检查 | 与已入库书籍比对 | 去重判定 | 新书 / 已存在 / 已处理 |
| S1.5 发现入队 | 确认后进入管道 | 管道任务 | 已入队 |

**Dashboard 展示：**
- 数据源列表（每个源的状态 + 今日发现数）
- 成果物统计：今日发现 / 总发现 / 已匹配 / 未匹配 / 已入队
- 最近发现的书列表

---

### S2: 书籍下载（主服务）

**可扩展维度：存储目标（列表）**

| 存储目标 | 状态 | 说明 |
|----------|------|------|
| 本地磁盘 | ✅ 已接入 | `/data/downloads/` |
| Cloudflare R2 | ✅ 已接入 | 对象存储 |
| IPFS (Pinata) | ✅ 已接入 | 去中心化存储 |
| [＋ 添加存储目标] | — | 未来可扩展 |

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S2.1 多源下载 | 从各数据源下载文件 | 下载文件 | 排队中 / 下载中 / 已完成 / 失败 |
| S2.2 本地存储 | 保存到本地磁盘 | 本地文件 | 已保存 / 保存失败 / 磁盘不足 |
| S2.3 云端上传 | 上传到 R2/IPFS | 云端文件 | 待上传 / 上传中 / 已上传 / 上传失败 |
| S2.4 断点续传 | 大文件续传 | 续传状态 | 续传中 / 续传完成 |
| S2.5 多源回退 | 主源失败切换备用 | 回退记录 | 主源成功 / 已回退到备源 / 全部失败 |
| S2.6 格式识别 | 识别 PDF/EPUB 等 | 格式标签 | 已识别 / 待识别 |

**成果物状态流转：**
```
未下载 → 下载中 → 已下载到本地 → 正在上传到云端 → 已上传到云端
                                                    │
                                              上传失败（重试）
```

**Dashboard 展示：**
- 下载队列列表（状态 + 进度 + 速度）
- 成果物统计：排队 / 下载中 / 已下载（本地） / 已上传（云端） / 失败
- 存储分布：本地多少 / R2 多少 / IPFS 多少
- 来源统计：Anna's / Gutenberg / 其他各多少

---

### S3: PDF 转换 / OCR（主服务）

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S3.1 格式分析 | 判断文字/图片 PDF | 分析结果 | 文字型 / 图片型 / 混合型 |
| S3.2 MinerU OCR | OCR 识别 | Markdown/DOCX | 排队中 / 处理中（页进度） / 完成 / 失败 |
| S3.3 文本提取 | 直接提取文字 | 提取文本 | 已提取 / 提取异常 |
| S3.4 质量校验 | 检测乱码/空页 | 质量报告 | 合格 / 有瑕疵 / 不合格 |

**成果物状态流转：**
```
待分析 → 已分析（文字型跳过OCR / 图片型需OCR）→ OCR排队 → OCR处理中 → OCR完成 → 质量校验 → 合格/不合格
```

---

### S4: 翻译服务（主服务）

**可扩展维度：翻译供应商（列表） × 每供应商多账号（列表）**

| 供应商 | 账号数 | 状态 | 说明 |
|--------|--------|------|------|
| OpenAI | 1 | ✅ | GPT-4o |
| DeepSeek | 1 | ✅ | DeepSeek-V3 |
| Anthropic | 0 | 📋 计划中 | Claude |
| Ollama (本地) | 1 | ✅ | Qwen2 |
| [＋ 添加供应商] | — | — | 未来任意扩展 |

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S4.1 多引擎调度 | 选择最优引擎执行翻译 | 翻译任务 | 排队中 / 翻译中 / 完成 / 失败 |
| S4.2 密钥池管理 | 多供应商×多账号轮换 | 密钥状态 | 可用 / 额度低 / 已耗尽 / 已禁用 |
| S4.3 Token 追踪 | 记录每次翻译消耗 | Token 记录 | 已记录 |
| S4.4 章节级翻译 | 分批翻译，断点续翻 | 章节进度 | 待翻译 / 翻译中 / 已完成 |
| S4.5 双语输出 | 生成中英对照文件 | 翻译文件 | 已生成 / 生成失败 |

**成果物状态流转：**
```
待翻译 → 章节排队 → 翻译中（按章节）→ 全部章节完成 → 生成双语文件 → 完成
```

**Dashboard 展示：**
- 翻译队列 + 每个任务的章节进度
- 供应商列表（每个供应商的账号数、可用率、额度状态）
- Token 消耗统计（今日/本周/本月）
- 翻译历史

---

### S5: 管道编排（主服务）

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S5.1 状态机 | 13 状态驱动 | 书籍状态 | discovered → ... → published |
| S5.2 三队列调度 | 下载/OCR/翻译独立队列 | 队列条目 | 排队中 / 执行中 / 已完成 / 失败 |
| S5.3 活动日志 | 每步操作记录 | 日志条目 | 已记录 |
| S5.4 批量操作 | 批量入队/重试 | 批次结果 | 处理中 / 完成 / 部分失败 |

**Dashboard 展示：**
- 六阶段看板（每阶段的书籍数和列表）
- 每本书的详情面板（完整时间线 + 各阶段成果物状态）

---

### S6: 闲鱼电商（主服务）

**可扩展维度：店铺（列表）**

| 店铺 | 状态 | 说明 |
|------|------|------|
| 闲鱼店铺 #1 | ✅ 运营中 | 当前唯一 |
| 闲鱼店铺 #2 | 📋 计划中 | 未来扩展 |
| [＋ 添加店铺] | — | 最多支持 10+ 店铺 |

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S6.1 自动发布 | 就绪书籍上架为商品 | 商品条目 | 待发布 / 已发布 / 发布失败 / 已下架 |
| S6.2 店铺管理 | 管理商品上下架 | 商品状态 | 在售 / 已售 / 已下架 |
| S6.3 自动发货 | 下单后发下载链接 | 发货记录 | 待发货 / 已发货 / 发货失败 |
| S6.4 AI 客服 | LLM 自动回复 | 对话记录 | 进行中 / 已结束 |
| S6.5 CS 保护 | 反风控策略 | 安全状态 | 正常 / 风险告警 / 已触发保护 |
| S6.6 Cookie 管理 | 维持登录态 | Cookie 状态 | 有效 / 即将过期 / 已过期 |

**Dashboard 展示：**
- 店铺列表（每个店铺的商品数、订单数、Cookie 状态）
- 每个店铺可展开查看：商品列表、订单摘要、客服对话、CS 状态

---

### S7: 云存储管理（主服务）

**可扩展维度：存储提供商（列表）**

| 提供商 | 状态 | 说明 |
|--------|------|------|
| Cloudflare R2 | ✅ | 主存储 |
| IPFS (Pinata) | ✅ | 去中心化存储 |
| [＋ 添加提供商] | — | 未来可扩展（如 S3、OSS） |

**子服务与成果物追踪：**

| 子服务 | 功能 | 成果物 | 成果物状态 |
|--------|------|--------|-----------|
| S7.1 R2 管理 | bucket 操作 | 文件条目 | 已存储 / 上传中 / 已删除 |
| S7.2 IPFS 管理 | pin 操作 | Pin 条目 | 已 pin / pin 中 / 已 unpin |
| S7.3 用量监控 | 容量和流量 | 用量数据 | 正常 / 接近上限 / 已超限 |
| S7.4 文件清理 | 过期/重复清理 | 清理任务 | 待清理 / 清理中 / 已清理 |

---

## 2.3 子系统A：微服务架构预留

### 界面中的微服务模式

每个可扩展维度在界面中都遵循相同的交互模式：

```
┌───────────────────────────────────────────────────┐
│  📋 数据源管理                          [＋ 添加] │
├───────────────────────────────────────────────────┤
│                                                   │
│  ┌─────────────────────────────────────────────┐ │
│  │ ✅ Anna's Archive            在线 · 今日+12 │ │
│  │    最后运行: 10 分钟前 · 下次: 6 小时后     │ │
│  │    [编辑] [暂停] [查看日志]                  │ │
│  └─────────────────────────────────────────────┘ │
│                                                   │
│  ┌─────────────────────────────────────────────┐ │
│  │ 📋 Library Genesis          未接入          │ │
│  │    [配置] [启用]                            │ │
│  └─────────────────────────────────────────────┘ │
│                                                   │
│  ┌─────────────────────────────────────────────┐ │
│  │ [＋ 添加新数据源]                            │ │
│  └─────────────────────────────────────────────┘ │
│                                                   │
└───────────────────────────────────────────────────┘
```

**统一的可扩展项模式：**
- 每个扩展维度（数据源/存储/供应商/店铺）都是列表
- 列表中的每项有：名称 + 状态指示灯 + 关键指标 + 操作按钮
- 底部有「添加」按钮，点击弹出配置表单
- 每项可独立启停、编辑、查看日志

---

## 2.4 子系统B：外部用户服务 — 功能规格

### 用户侧功能

#### F-E1: 搜索入口

| 功能项 | 描述 | 分层限制 |
|--------|------|---------|
| 搜索框 | 输入书名/作者/ISBN | Free: 50 次/日；Pro+: 无限 |
| 搜索结果 | 书名、作者、封面、可用格式 | 通用 |
| 状态标记 | ✅ 可下载 / 🌐 可翻译 / 📋 需处理 | 通用 |
| 筛选标签 | 语言、格式 | 通用 |

#### F-E2: 下载原文

| 功能项 | 描述 | 分层限制 |
|--------|------|---------|
| 下载按钮 | 直接下载原始文件 | Free: 3 次/日；Pro: 20；Max+: 无限 |
| 格式选择 | PDF / EPUB / Markdown | 通用 |
| 文件大小限制 | 单文件最大 | Free: 50MB；Pro: 200MB；Max: 500MB |

#### F-E3: 翻译书籍

| 功能项 | 描述 | 分层限制 |
|--------|------|---------|
| 翻译按钮 | 提交翻译任务 | Free: 10 页/月；Pro: 500 页/月；Max: 3000 页/月 |
| 进度条 | 整体进度 0-100% | 通用 |
| 下载译文 | Markdown / DOCX / 双语对照 | 通用 |

#### F-E4: 在线查看（新增）

| 功能项 | 描述 | 分层限制 |
|--------|------|---------|
| 原文查看 | 浏览器内加载 PDF 显示原文 | Free: 仅查看；Pro+: 可复制文字 |
| 译文查看 | 浏览器内显示翻译结果 | 通用 |
| 左右对照 | 左原文右译文，同步滚动 | Free: 仅看模式；Pro+: 可交互 |
| 单页/双页切换 | 切换查看模式 | Pro+ |

#### F-E5: 文件管理（新增）

| 功能项 | 描述 | 分层限制 |
|--------|------|---------|
| 我的文件列表 | 所有已下载/已翻译的文件 | 通用 |
| 文件操作 | 下载、删除、复制分享链接 | 通用 |
| 存储空间 | 已用/总额度 | Free: 100MB；Pro: 5GB；Max: 50GB |
| 文件保留期 | 文件保留时间 | Free: 7天；Pro: 90天；Max: 1年 |

#### 用户分层限额总表

| 维度 | Free | Pro | Max | API |
|------|------|-----|-----|-----|
| 搜索次数/日 | 50 | 无限 | 无限 | 无限 |
| 下载次数/日 | 3 | 20 | 无限 | 无限 |
| 翻译页数/月 | 10 | 500 | 3,000 | 5,000 |
| 单文件大小 | 50 MB | 200 MB | 500 MB | 500 MB |
| 存储空间 | 100 MB | 5 GB | 50 GB | 无限 |
| 文件保留 | 7 天 | 90 天 | 1 年 | 永久 |
| 对照查看 | 仅看 | 全功能 | 全功能 | API |
| API 访问 | ❌ | ❌ | ❌ | ✅ |
| Webhook | ❌ | ❌ | ❌ | ✅ |

---

### 管理员侧功能（新增）

#### F-E6: 用户管理

| 功能项 | 描述 |
|--------|------|
| 用户列表 | 注册时间、层级、状态、最近活跃 |
| 用户搜索 | 按邮箱/用户名搜索 |
| 层级管理 | 查看各层级用户数量、手动升降级 |
| 用量统计 | 每个用户的搜索/下载/翻译次数 |

#### F-E7: 业务统计

| 功能项 | 描述 |
|--------|------|
| 概览统计 | 今日注册/搜索/翻译/下载数量 |
| 趋势图 | 近 30 天的各指标趋势 |
| 搜索分析 | 热门搜索词、无结果搜索词 |
| 翻译分析 | 翻译完成率、平均耗时、失败原因分布 |
| 下载分析 | 下载完成率、热门下载文件 |

#### F-E8: 异常追踪

| 功能项 | 描述 |
|--------|------|
| 失败任务列表 | 所有失败的翻译/下载任务 |
| 按类型筛选 | 翻译失败 / 下载失败 / 搜索失败 |
| 按用户筛选 | 某个用户的所有失败任务 |
| 搜索无结果追踪 | 用户搜索了但没找到的关键词列表 |
| 处理状态 | 未处理 / 已处理 / 已忽略 |

#### F-E9: 系统服务状态

| 功能项 | 描述 |
|--------|------|
| 后端服务状态 | 各模块对外部用户的可用性 |
| API 响应时间 | 各接口的平均响应时间 |
| 错误率 | 近 1 小时/24 小时的错误率 |

#### F-E10: SEO 与内容管理

| 功能项 | 描述 |
|--------|------|
| 文章列表 | 所有已发布/草稿状态的博客文章 |
| 文章编辑 | 标题、正文、分类、标签 |
| 关键词标注 | 每篇文章的目标关键词 |
| 内链管理 | 文章间的内部链接 |
| 外链管理 | 文章中的外部链接 |
| 热门榜单解读 | 图书销售排行数据 → 生成解读文章 |
| SEO 分析 | 每篇文章的收录状态、排名、流量 |
| 发布/下架 | 控制文章的发布状态 |

---

## 2.5 不做清单

| 不做 | 原因 |
|------|------|
| 两套子系统混合在一个界面 | 用户、场景、目标完全不同 |
| 子系统A 的手动搜索 | 数据发现由爬虫驱动，不需要手动搜索 |
| 子系统B 暴露内部架构 | 用户不需要知道下载/OCR/翻译/存储 |
| 子系统B 管理员看到子系统A 的内部细节 | 管理员看的是业务数据，不是后端服务状态 |
| 移动端优先适配 | 子系统A 桌面专用；子系统B 后续可扩展 |
| 实时 WebSocket 推送 | 刷新页面足够（MVP） |
| 主题切换 | 子系统A 深色；子系统B 浅色，各自固定 |

---

*L2 范围层 v3.0 完成。核心变更：① 每个子服务增加成果物名称和成果物状态流转；② 所有可扩展维度（数据源/存储/供应商/店铺）用列表模式设计；③ 子系统B 增加在线查看（原文/译文/对照）和文件管理；④ 子系统B 增加完整管理员后台（用户管理/业务统计/异常追踪/SEO内容管理）；⑤ 用户分层限额体系。*