# DESIGN — qcwy_signature_refactor

1) 整体架构图
```mermaid
flowchart TD
  A[JobCrawler 调用层] --> B[签名生成 generate_qcwy_signature]
  A --> C[property 构建 build_qcwy_property]
  A --> D[httpx.Client 请求发送]
  D --> E[51job API]
  A --> F[RemoteReporter 数据上报]
```

2) 分层设计与核心组件
- Crawler 层：JobCrawler（业务编排、参数组装、headers签名与property、调试打印、调用 _make_request）
- Signature 层：generate_qcwy_signature（独立函数，HMAC-SHA256签名）+ SignatureGenerator（兼容旧接口）
- Property 层：build_qcwy_property（独立函数，URL编码后的JSON）
- Transport 层：httpx.Client（保留，会话与代理切换）
- Reporter 层：RemoteReporter（上报到后端 universal data）

3) 模块依赖关系图
```mermaid
flowchart LR
  JobCrawler --> SignatureGenerator --> generate_qcwy_signature
  JobCrawler --> build_qcwy_property
  JobCrawler --> httpxClient
  JobCrawler --> RemoteReporter
```

4) 接口契约定义
- generate_qcwy_signature(sign_key: str, url_path: str, data: Optional[Dict]) -> str
- build_qcwy_property(manual_login_method: str = "", page_code: str = "home|hotjob|jobfxlist") -> str
- SignatureGenerator.generate_signature(url_path: str, data: Optional[Dict]) -> str

5) 数据流向图
```mermaid
sequenceDiagram
  participant J as JobCrawler
  participant S as Signature
  participant P as Property
  participant X as httpx.Client
  participant API as 51job API
  participant R as RemoteReporter

  J->>S: 生成签名
  J->>P: 构建 property
  J->>X: 发送请求(headers含签名与property)
  X->>API: HTTP 请求
  API-->>J: 返回 JSON 响应
  J->>R: 上报数据(批量)
```

6) 异常处理策略
- 代理异常：在 _make_request 中检测典型错误码/异常关键字，触发 _switch_proxy_and_reinit。
- 网络异常：指数退避重试，最多3次；返回 None 时上层做空值兜底。
- 解析异常：捕获并记录日志，返回空集合/空字典，避免中断流水线。

7) 设计原则
- 任务范围内的最小改动：仅替换爬虫相关签名与property构建逻辑。
- 保持对外契约不变：保留 JobCrawler 与 Reporter 行为接口。
- 与 boss_api 风格对齐：日志配置、调试输出统一。