# BD 手册：scheduled_tasks 新增字段（P16 最小运行间隔）

## 概述

P16 为 `public.scheduled_tasks` 表新增 3 个字段，支持调度任务最小运行间隔机制。调度器轮询时检查并发状态和间隔约束，避免任务重复执行。

所有变更位于 `zqyy_app` / `test_zqyy_app` 数据库，`public` Schema。

## 变更原因

- P16 调度任务最小运行间隔需求：管理员可为每个任务配置最小间隔，任务即使调度到期也不会在间隔内重复执行
- 新增 `last_success_at` 字段区分"最后执行时间"和"最后成功时间"，支持更精确的间隔计算

## 变更说明

| 库 | Schema | 表 | 变更类型 | 说明 |
|----|--------|---|---------|------|
| zqyy_app | public | scheduled_tasks | 新增字段 ×4 | min_run_interval_value, min_run_interval_unit, last_success_at, min_run_intervals |

---

## 新增字段明细

| 列名 | 类型 | 约束 | 默认值 | 说明 |
|------|------|------|--------|------|
| min_run_interval_value | INTEGER | NOT NULL | 0 | 最小间隔数值（0=无限制，与现有行为完全一致） |
| min_run_interval_unit | VARCHAR(20) | NOT NULL | 'minutes' | 间隔单位：`minutes` / `hours` / `days` |
| last_success_at | TIMESTAMPTZ | — | NULL | 最后一次成功执行的时间 |
| min_run_intervals | JSONB | NOT NULL | '{}' | 每任务子代码级别的最小运行间隔配置（key=task_code, value=interval_seconds） |

### DDL

```sql
ALTER TABLE scheduled_tasks ADD COLUMN min_run_interval_value INTEGER NOT NULL DEFAULT 0;
ALTER TABLE scheduled_tasks ADD COLUMN min_run_interval_unit VARCHAR(20) NOT NULL DEFAULT 'minutes';
ALTER TABLE scheduled_tasks ADD COLUMN last_success_at TIMESTAMPTZ;

COMMENT ON COLUMN scheduled_tasks.min_run_interval_value IS '最小间隔数值（0=无限制）';
COMMENT ON COLUMN scheduled_tasks.min_run_interval_unit IS '间隔单位：minutes/hours/days';
COMMENT ON COLUMN scheduled_tasks.last_success_at IS '最后一次成功执行的时间';
```

---

## 业务逻辑

调度器（`scheduler.py`）轮询时对每个到期任务执行以下检查：

1. **并发检查**：`last_status = 'running'` → 跳过本次入队，日志记录 `skipped_concurrent`
2. **间隔检查**：`min_run_interval_value > 0` 且 `now() - last_run_at < min_interval_seconds` → 跳过本次执行，推进 `next_run_at`，日志记录 `skipped_interval`
3. **首次执行**：`last_run_at IS NULL`（从未执行）→ 跳过间隔检查，正常执行
4. **强制执行**：`force=true` 参数绕过所有检查（并发 + 间隔），直接入队

### 间隔转换

```python
def _convert_interval_to_seconds(value: int, unit: str) -> int:
    multipliers = {"minutes": 60, "hours": 3600, "days": 86400}
    return value * multipliers.get(unit, 60)
```

### last_success_at 更新规则

- 任务成功完成时：`last_status='completed'`, `last_success_at=NOW()`
- 任务失败时：`last_status='failed'`，`last_success_at` 不变

---

## 兼容性

| 组件 | 影响 |
|------|------|
| 后端 API | `POST /api/schedules` 和 `PUT /api/schedules/{id}` 请求体新增 `min_run_interval_value`、`min_run_interval_unit`。`GET /api/schedules` 响应新增 3 个字段。`POST /api/schedules/{id}/run` 新增 `force` 查询参数 |
| 前端 ScheduleTab | 创建/编辑表单新增「最小运行间隔」配置行。列表新增「最小间隔」和「上次成功」列。手动执行确认框新增「强制执行」Checkbox |
| ETL | 无影响。ETL 任务调度由 `scheduled_tasks` 表驱动，新增字段默认值 0 表示无限制，向后兼容 |
| 小程序 | 无影响 |
| 调度器 | `scheduler.py` 的 `check_and_enqueue()` 新增并发检查和间隔检查逻辑 |

## 回滚策略

```sql
BEGIN;
ALTER TABLE scheduled_tasks DROP COLUMN IF EXISTS min_run_interval_value;
ALTER TABLE scheduled_tasks DROP COLUMN IF EXISTS min_run_interval_unit;
ALTER TABLE scheduled_tasks DROP COLUMN IF EXISTS last_success_at;
COMMIT;
```

注意：
- 回滚后所有任务恢复为无间隔限制的行为
- 回滚前需确认后端代码已移除对这 3 个字段的引用
- `last_success_at` 数据丢失不可恢复

## 验证 SQL

```sql
-- 1. 验证新增字段存在且类型正确
SELECT column_name, data_type, column_default
FROM information_schema.columns
WHERE table_name = 'scheduled_tasks'
  AND column_name IN ('min_run_interval_value', 'min_run_interval_unit', 'last_success_at');
-- 预期：3 行
--   min_run_interval_value | integer      | 0
--   min_run_interval_unit  | character varying | 'minutes'::character varying
--   last_success_at        | timestamp with time zone | NULL

-- 2. 验证现有任务的新字段默认值
SELECT id, name, min_run_interval_value, min_run_interval_unit, last_success_at
FROM scheduled_tasks
LIMIT 5;
-- 预期：min_run_interval_value=0, min_run_interval_unit='minutes', last_success_at=NULL（除非已手动配置）

-- 3. 验证已配置间隔的任务数量
SELECT COUNT(*) FROM scheduled_tasks WHERE min_run_interval_value > 0;
-- 预期：≥ 0（初始状态为 0，配置后递增）

-- 4. 验证字段注释
SELECT col_description(
  (SELECT oid FROM pg_class WHERE relname = 'scheduled_tasks'),
  (SELECT attnum FROM pg_attribute WHERE attrelid = 'scheduled_tasks'::regclass AND attname = 'min_run_interval_value')
);
-- 预期：'最小间隔数值（0=无限制）'
```

## 关联文件

- DDL 基线（public）：`docs/database/ddl/zqyy_app__public.sql`
- 迁移脚本：`db/zqyy_app/migrations/2026-03-22__p16_min_run_interval.sql`
- 调度器逻辑：`apps/backend/app/services/scheduler.py`
- 后端路由：`apps/backend/app/routers/schedules.py`
- 后端 Schema：`apps/backend/app/schemas/schedules.py`
- 前端组件：`apps/admin-web/src/components/ScheduleTab.tsx`
- Spec：`.kiro/specs/admin-web-enhancement/`
- PRD：`docs/prd/specs/P16-task-min-run-interval.md`
