# 产教数据连接器运行时

本目录实现厂商端 9 个目标来源的统一采集骨架。所有外部来源默认禁止网络访问，只有完成书面授权、robots、域名白名单、技术联系人和请求限额配置后，命令行才允许发起请求。

逐来源决策见 [`../../docs/crawler-source-implementation.md`](../../docs/crawler-source-implementation.md)，统一字段见 [`../demo/schemas/`](../demo/schemas/)。

## 能力

- 7 个外部来源的具体连接器类；
- 2 个校内来源的租户隔离文件连接器；
- 官方 API / 授权 JSON、NDJSON、CSV 数据包接入；
- 获准公开页面的 robots、域名、重定向、限速、响应大小和 DNS 重绑定保护；
- Schema.org `JobPosting` 与结构化 feed 解析；
- `JOB-SIGNAL V3.0`、`SCHOOL-EMPLOYMENT V2.2`、`SCHOOL-INTERNSHIP V2.1` 校验；
- Raw 快照、标准记录、隔离记录和运行摘要输出；
- URL 密钥脱敏、敏感校内字段拒绝和确定性幂等标识。

不支持验证码、登录自动化、Cookie 复用、代理池、浏览器指纹伪装、私有接口逆向或任何访问限制绕过。

## 安装与测试

```bash
cd admin-tools/crawler
python -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/pytest
```

当前环境已安装依赖时，也可直接运行：

```bash
PYTHONPATH=src python -m edu_crawler list-sources
PYTHONPATH=src python -m pytest
```

## 离线授权数据包

商业来源推荐先使用离线授权数据包验证字段映射：

```bash
PYTHONPATH=src python -m edu_crawler run \
  --source BOSS \
  --input /secure/inbox/boss-authorized.ndjson \
  --authorization-ref CONTRACT-2026-001 \
  --task-id JOB-20260824-BOSS-001 \
  --data-version V2026.08.24 \
  --output ./output
```

本地输入不会发起网络请求，但 7 个外部来源仍要求授权编号。

## 获准网络来源

只有部署审批完成后才能显式增加 `--allow-network`：

```bash
PYTHONPATH=src python -m edu_crawler run \
  --source BRZP \
  --input 'https://approved.example/jobs-feed.json' \
  --approved-host approved.example \
  --authorization-ref AUTH-BRZP-2026-001 \
  --contact crawler-ops@example.edu.cn \
  --allow-network \
  --task-id JOB-20260824-BRZP-001 \
  --data-version V2026.08.24 \
  --max-pages 5 \
  --max-records 1000 \
  --output ./output
```

- `--approved-host` 必须来自来源审批配置，不能使用 IP；
- `--approved-host` 还必须存在于对应连接器的版本化 allowlist；新增合作 API 域名需要代码评审；
- API Bearer Token 通过 `--bearer-token-env ENV_NAME` 引用环境变量；
- Bearer Token 任务只允许一个审批主机，Token 不发送给 robots.txt；
- 命令输出、任务摘要和 Raw 元数据均不保存 Token；
- 实际请求间隔不会低于来源策略的最低值。

## 校内来源

校内文件必须先在学校侧完成学生令牌化：

```bash
PYTHONPATH=src python -m edu_crawler run \
  --source SCHOOL_EMPLOYMENT \
  --input /secure/inbox/employment.ndjson \
  --authorization-ref DPA-TENANT-HZVTC-2026-001 \
  --tenant-id TENANT-HZVTC \
  --task-id JOB-20260824-SCHOOL-EMP-001 \
  --data-version SCH-EMP-20260824-01 \
  --output ./output
```

如果输入包含 `student_name`、`student_id`、身份证、手机号、邮箱等禁止字段，任务会将记录写入隔离区，不会进入标准层。

## 输出

```text
外部来源：output/<SOURCE>/<TASK-ID>/
校内来源：output/<SOURCE>/<TENANT-ID>/<TASK-ID>/
├── raw/
│   ├── <sha256>.<json|html|bin>
│   └── <sha256>.metadata.json
├── standard.ndjson
├── quarantine.ndjson
└── summary.json
```

任务目录不可覆盖。重跑必须使用新任务号，业务记录的 `record_id` 和 `content_hash` 保持确定性。