social-app/docs/protocols/models/automation-jobs.md

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 (引导配置键，用于标识预设任务模板)
• is_system: boolean (bootstrap_key != null 时为 true，只读派生字段)
• config: object
  • input_template: string
  • enabled_skills: string[] (calendar | contacts | memory)
  • 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.