# ScopeHarvest

ScopeHarvest 是一个授权优先的本地快照采集框架。当前版本故意只支持客户确认授权的本地 HTML 快照，默认拒绝网络采集。这样可以在不访问生产站点的情况下完成解析器、去重、状态恢复、输出与故障演练。

## 授权边界

运行前必须在配置中确认客户、合法用途、允许来源前缀和字段范围。`authorization_confirmed=false`、用途含“待确认”、来源不在允许前缀内或配置不是 `source_type=snapshot` 时，CLI 会停止。任何新增网站、字段、频率或用途都必须重新评估授权、robots、服务条款、API 政策、版权、隐私和对对方服务器的影响。

本工具不绕过登录、付费墙、验证码、访问控制或反自动化保护；不采集非业务必需的个人信息；不把 Cookie、令牌或敏感原文写入日志。

## 安装与质量检查

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
ruff format --check src tests
ruff check src tests
mypy src
pytest -q
```

## 本地演练

复制 `authorization.example.json` 为授权测试配置，将 `authorization_confirmed` 改为 `true`，并把 `legal_purpose` 改为已经确认的用途。然后运行：

```powershell
python -m scope_harvest --config authorized-test.json --dry-run --max-pages 3 --max-runtime-seconds 60
```

正式本地快照写出：

```powershell
python -m scope_harvest --config authorized-test.json --output outputs\records.json --state outputs\state.json --report outputs\run-report.json
```

`--dry-run` 只生成报告，不写记录与状态。`--stop-file STOP` 可在任务开始或循环中触发安全停止。状态文件保存稳定唯一键，重跑时不会重复写入。

## 输出与恢复

- 记录：JSON 或 CSV，取决于配置的 `output_format`
- 状态：已处理稳定键，用于断点续跑与去重
- 报告：状态、页面数、请求数、记录数、重复、解析失败与耗时

写出使用临时文件和原子替换。若进程中断，未完成临时文件不会伪装成最终结果。检查报告与状态文件后可以安全重跑。

## 调度示例

Windows 任务计划程序、cron 或企业调度器可每天调用同一条 CLI 命令。上线调度前必须确认每次运行仍在已授权范围内，并设置最大运行时间、停止文件和运行日志归档。

## 已知限制

当前版本是离线授权快照框架，不是通用互联网爬虫。真实网络源、API、分页、AutoThrottle、robots 抓取和并发请求模块必须在每个具体目标的授权与政策检查后单独实现并评审，不能仅靠修改 URL 启用。