# Automation Jobs Model Protocol

## Scope

This document defines the `automation_jobs` data contract used by backend API payloads,
scheduler computation, and Flutter settings pages.

## Canonical Fields

- `id`: UUID
- `owner_id`: UUID
- `title`: string
- `bootstrap_key`: string | null (引导配置键，用于标识预设任务模板)
- `config`: object
  - `input_template`: string
  - `enabled_tools`: string[]
  - `context`: object
    - `source`: `latest_chat`
    - `window_mode`: `day | number`
    - `window_count`: int
  - `schedule`: object
    - `type`: `daily | weekly`
    - `run_at`: object
      - `hour`: int (0-23)
      - `minute`: int (0-59)
    - `weekdays`: int[] (only for weekly; Monday=1 ... Sunday=7)
- `timezone`: IANA timezone string
- `next_run_at`: timestamptz (UTC), scheduler due cursor
- `last_run_at`: timestamptz | null
- `status`: `active | disabled`
- `created_at`: timestamptz
- `updated_at`: timestamptz

## Scheduling Semantics

- Scheduler scans only by `next_run_at <= now_utc`.
- Scheduler calculates subsequent `next_run_at` from `config.schedule + timezone`.
- `run_at` and `schedule_type` top-level columns are deprecated and removed.

## Compatibility Strategy

- Strategy: **migration-required change**.
- Existing rows must be migrated by backfilling `config.schedule` from legacy
  `run_at/schedule_type` before dropping those columns.
- Clients must send schedule data through `config.schedule` only.