# ALIGNMENT — qcwy_signature_refactor

阶段: Align（对齐阶段）

任务名称: 前程无忧 qcwy_api 签名函数提取与爬虫代码重构（风格对齐 boss_api.py）

1. 项目上下文分析
- 技术栈: Python, httpx/requests, FastAPI（服务端），前端 Vue3（web）
- 相关文件: new2025/boss/boss_api.py（风格参考）、new2025/qcwy/qcwy_api.py（待重构）
- 现有模式: qcwy_api.py 内部包含 ProxyConfig/ProxyManager/RemoteReporter/SignatureGenerator/JobCrawler 等类，使用 httpx.Client 进行请求；boss_api.py 使用 requests.Session 并提供统一日志/调试输出风格。
- 业务域: 爬取 51job 小程序接口的职位数据，并将职位与公司详情按约定上报至后端 universal data 接口。

2. 原始需求与边界确认
- 需求: 在 qcwy_api.py 中“提取爬虫的签名函数”，并进行“qcwy_api 重构”，使“代码风格和 boss_api 一致”，且“只需要替换爬虫相关的代码”。
- 边界: 不改动非爬虫相关的逻辑（如数据结构、业务上报接口契约），尽量避免引入新的外部依赖；维持 httpx 客户端使用与现有方法签名一致性。

3. 需求理解
- 提取签名函数: 将签名生成逻辑抽到独立函数 generate_qcwy_signature，支持 url_path + 请求体签名；布尔值需转 "true"/"false"；HMAC-SHA256 hexdigest。
- 提取 property 构建函数: 独立函数 build_qcwy_property，输出 URL 编码的 JSON；JobCrawler.build_property 调用该函数。
- 风格对齐: 顶部打印 [DEBUG] 模块加载提示；logging.basicConfig 增加 StreamHandler；函数注释采用 boss_api.py 风格。

4. 智能决策策略
- 参考 boss_api.py 的结构与日志风格，不强行将 httpx 改成 requests，以减少改动面与风险；仅在签名与 property 构建、日志风格上进行统一。
- 复用现有接口调用流程，确保对外契约不变。

5. 疑问澄清（需确认）
- 是否需要将 httpx.Client 改为 requests.Session 以进一步风格一致？当前按“只替换爬虫相关代码”理解为保持 httpx。
- 签名 key 是否固定由调用方维护？目前保留原始默认值并通过依赖注入传入。

6. 验收标准
- qcwy_api.py 中存在可复用的 generate_qcwy_signature 与 build_qcwy_property 函数，并在 JobCrawler 内部调用。
- 日志与 debug 输出风格与 boss_api.py 保持一致。
- 现有功能（如 get_recommend_jobs）保持原有行为，不破坏接口契约与上报逻辑。