# 定时任务配置示例（治理批消费 + 采集 Cron）

> 用途：上线后 **Python 定时写 raw** + **Java 定时消费 raw** 的参考配置。频率请按《数据源上线清单》中的授权与 SLA 调整。

---

## 1. Java：治理定时（`RawGovernanceScheduler`）

### 1.1 方式 A — 直接写在 `application.yml`

在现有 `fao.governance` 下覆盖（示例：**开启**、首次延迟 2 分钟、**上次跑完后**间隔 5 分钟、每批最多 50 条）：

```yaml
fao:
  governance:
    token: ${FAO_GOVERNANCE_TOKEN:}
    # 建议生产填写白名单，避免误处理未就绪的 source
    source-codes: []   # 例: ["XFD", "DEMO"]
    scheduled:
      enabled: true
      initial-delay-ms: 120000
      fixed-delay-ms: 300000
      batch-limit: 50
```

说明：

- **`fixed-delay-ms`**：`fixedDelay`，**上一轮执行结束**后再等待该毫秒数；适合治理批任务避免重叠。
- **`batch-limit`**：单次 `consume` 最多处理条数；代码中还会限制在 **1～200**。
- **`source-codes`**：非空时，定时任务与未带 `sourceCodes` 的 HTTP 治理请求都只处理列出的 `source_code`。

### 1.2 方式 B — Spring Profile（推荐与默认配置分离）

1. 将 `server/src/main/resources/application-scheduled.yml.example` **复制为** `application-scheduled.yml`（后者可加入 `.gitignore` 若含环境专有值）。
2. 启动时增加：**`--spring.profiles.active=scheduled`**（或与 `default` 并列：`default,scheduled`）。

仅 profile 文件存在、未激活时，**不会**打开定时任务。

### 1.3 方式 C — 环境变量（容器 / systemd）

与 `fao.governance.scheduled.*` 对应的环境变量示例（Spring Boot 宽松绑定，以实际运行镜像为准）：

| 配置项 | 环境变量示例 |
|--------|----------------|
| `scheduled.enabled` | `FAO_GOVERNANCE_SCHEDULED_ENABLED=true` |
| `scheduled.initial-delay-ms` | `FAO_GOVERNANCE_SCHEDULED_INITIALDELAYMS=120000` |
| `scheduled.fixed-delay-ms` | `FAO_GOVERNANCE_SCHEDULED_FIXEDDELAYMS=300000` |
| `scheduled.batch-limit` | `FAO_GOVERNANCE_SCHEDULED_BATCHLIMIT=50` |

---

## 2. 与采集频率的配合（建议）

| 环节 | 典型节奏（示例） | 说明 |
|------|------------------|------|
| **Python 写 raw** | 每 15～60 分钟（视源站授权） | 外网抓取；**仓库内无内置调度**，靠 Cron / K8s CronJob。 |
| **Java 消费 raw** | `fixed-delay` 5～15 分钟 | 应 **不显著快于** 单次治理耗时，避免空转；可略快于采集，以便积压尽快消化。 |

若 raw 积压大，可临时提高 `batch-limit` 或缩短 `fixed-delay-ms`，并观察 DB 与 CPU。

---

## 3. Cron 示例（采集）

见仓库 **`scripts/cron/fao-ingest.crontab.example`**。安装示例：

```bash
# 编辑后安装到当前用户 crontab（路径、适配器、.env 务必按环境修改）
crontab scripts/cron/fao-ingest.crontab.example
```

生产更推荐 **K8s CronJob** 或统一调度平台，思路相同：定时执行 `scripts/run_ingest.sh --adapter <name>`，并注入 `FAO_MYSQL_*` / `FAO_HTTP_JSON_URL` 等环境变量。

---

## 4. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-04-23 | 初稿：application 片段、Profile 样例、Cron 引用 |