101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# Phase 1: 共享核心包 - Context
|
||
|
||
**Gathered:** 2026-03-21
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
提取 crawler_core/ 为独立可安装共享包，包含签名算法、HTTP 客户端封装、基类定义和数据模型。三个平台（Boss/前程无忧/智联）的后续重写全部基于此包展开。本阶段不改造任何平台的具体爬虫实现，旧爬虫保持运行不受影响。
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### 包结构和安装方式
|
||
- **D-01:** 包放在项目根目录 `crawler_core/`，与 `app/` 和 `spiderJobs/` 平级
|
||
- **D-02:** 使用 `pyproject.toml` 管理包元数据，支持 `pip install -e ./crawler_core`
|
||
- **D-03:** 最小依赖范围 — 只依赖 `requests_go` + `tenacity` + Python 标准库，不拉入 FastAPI/Tortoise/loguru
|
||
- **D-04:** 包名为 `crawler_core`
|
||
|
||
### 基类接口设计
|
||
- **D-05:** 保持两个基类：`BaseFetcher`（单条详情获取）和 `BaseSearcher`（列表搜索）
|
||
- **D-06:** 模板方法包含 4 个：`_build_params()`（必须）、`_parse_response()`（必须）、`_build_headers()`（可选覆写）、`_check_blocked()`（可选覆写，判断是否被封）
|
||
- **D-07:** 返回值使用类型化 `Result[T]` dataclass，取代现有的松散 `ApiResult`
|
||
|
||
### 核心模块分层
|
||
- **D-08:** 签名算法保持各平台独立类（BossSign、Job51Sign、ZhilianSign），不强制统一 BaseSigner 接口
|
||
- **D-09:** HTTP 客户端统一封装为一个 `HTTPClient` 类，内置代理、重试、日志功能
|
||
- **D-10:** 内部目录按平台分层：`crawler_core/boss/`、`crawler_core/qcwy/`、`crawler_core/zhilian/` + `crawler_core/base/`
|
||
|
||
### Claude's Discretion
|
||
- `pyproject.toml` 的具体配置（build-system、版本号等）
|
||
- `Result[T]` dataclass 的具体字段设计
|
||
- HTTPClient 的重试策略参数（次数、间隔等）
|
||
- 测试文件的组织方式
|
||
|
||
</decisions>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- 现有 `spiderJobs/core/base.py`（154行）比 `app/services/crawler/_base.py`（111行）更完整，以前者为基础提取
|
||
- 现有 `spiderJobs/core/http_client.py` 已有 `TLS_CHROME_LATEST + random_ja3=True` 反爬配置，直接复用
|
||
- 签名模块已有 6 个副本（`app/services/crawler/_*_sign.py` + `spiderJobs/platforms/*/sign.py`），内容一致，取一份即可
|
||
- `spiderJobs/platforms/boss/sign.py` 的注释 "复制自" 已经标明了源和副本的关系
|
||
|
||
</specifics>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
### 架构研究
|
||
- `.planning/research/ARCHITECTURE.md` — 共享包提取方案、同步/异步边界设计、构建顺序
|
||
- `.planning/research/STACK.md` — HTTP 客户端选择（requests_go vs httpx）、测试栈推荐
|
||
|
||
### 风险规避
|
||
- `.planning/research/PITFALLS.md` — Pitfall 1（重构期间打断在线爬虫）、Pitfall 2（签名代码复制粘贴）
|
||
|
||
### 现有代码
|
||
- `spiderJobs/core/base.py` — 现有 BaseFetcher/BaseSearcher 实现，提取基础
|
||
- `spiderJobs/core/http_client.py` — 现有 HTTPClient 实现，TLS 指纹配置
|
||
- `spiderJobs/platforms/boss/sign.py` — Boss 签名算法参考实现
|
||
- `spiderJobs/platforms/job51/sign.py` — Job51 签名算法参考实现
|
||
- `spiderJobs/platforms/zhilian/sign.py` — 智联签名算法参考实现
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `spiderJobs/core/base.py` — BaseFetcher/BaseSearcher 模板方法基类，直接迁移到 crawler_core/base/
|
||
- `spiderJobs/core/http_client.py` — HTTPClient 封装，含 TLS 指纹、代理、重试逻辑
|
||
- `spiderJobs/platforms/*/sign.py` — 三个平台的签名算法，纯函数，可直接迁移并加测试
|
||
|
||
### Established Patterns
|
||
- 模板方法模式：基类调 `_build_params()` → HTTP 请求 → `_parse_response()`
|
||
- ApiResult dataclass：`success`, `data`, `error`, `list`, `is_end_page` 字段
|
||
- 签名类独立实例化，注入到 Client/Fetcher 中
|
||
|
||
### Integration Points
|
||
- Phase 2/3 的平台重写将 `from crawler_core.boss import BossSign, BossClient` 导入
|
||
- Phase 4 的后端 facade 将通过 `asyncio.to_thread()` 调用 crawler_core 的同步方法
|
||
- 现有 `app/services/crawler/_*.py` 文件在 Phase 4 之前保持不变，旧代码继续运行
|
||
|
||
</code_context>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
- loguru 是否应该作为 crawler_core 的可选依赖 — Phase 5 统一日志时再决定
|
||
- 是否需要 BaseSigner 统一接口 — 如果 Phase 2/3 发现需要，再回来加
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 01-shared-core*
|
||
*Context gathered: 2026-03-21*
|