# 定时调度与手动触发使用指南

## ⏰ 定时调度配置

### 当前设置
- **执行时间**: 每天北京时间 11:00（UTC 03:00）
- **Cron表达式**: `0 3 * * *`
- **配置位置**: 数据库 `system_config` 表

### 修改定时时间

#### 方法1：通过DMS修改数据库（推荐）

```sql
-- 修改为每天北京时间 15:00（UTC 07:00）
UPDATE system_config
SET config_value = '0 7 * * *', updated_by = 'your_name'
WHERE config_key = 'cron_schedule';

-- 查看当前配置
SELECT config_value FROM system_config WHERE config_key = 'cron_schedule';
```

#### 方法2：通过Python修改

```python
from db import update_system_config

# 修改为每天北京时间 09:00（UTC 01:00）
update_system_config('cron_schedule', '0 1 * * *', updated_by='admin')
```

#### 常用Cron表达式

| 说明 | Cron表达式 | UTC时间 | 北京时间 |
|------|-----------|---------|---------|
| 每天上午9点 | `0 1 * * *` | 01:00 | 09:00 |
| 每天上午11点 | `0 3 * * *` | 03:00 | 11:00 ✅ (当前) |
| 每天下午3点 | `0 7 * * *` | 07:00 | 15:00 |
| 每天晚上9点 | `0 13 * * *` | 13:00 | 21:00 |
| 每12小时 | `0 */12 * * *` | 00:00, 12:00 | 08:00, 20:00 |

---

## 🚀 手动触发任务

### API端点

**URL**: `POST http://localhost:8080/trigger`

**说明**: 手动触发一次决策流程，不影响定时任务

### 使用方法

#### 方法1：curl命令行

```bash
# 本地触发
curl -X POST http://localhost:8080/trigger

# 远程触发（如果部署在Kubernetes）
kubectl port-forward -n ad-automation svc/auto-put-ad-mini 8080:8080
curl -X POST http://localhost:8080/trigger
```

#### 方法2：Python脚本

```python
import requests

response = requests.post('http://localhost:8080/trigger')
print(response.json())

# 输出示例：
# {
#   "status": "triggered",
#   "message": "任务已添加到队列"
# }
```

#### 方法3：在Kubernetes Pod内触发

```bash
# 进入Pod
kubectl exec -it -n ad-automation <pod-name> -- bash

# 在Pod内执行
curl -X POST http://localhost:8080/trigger
```

### 响应说明

**成功响应**：
```json
{
  "status": "triggered",
  "message": "任务已添加到队列"
}
```

**任务已在运行**：
```json
{
  "status": "scheduled",
  "message": "任务已在队列中",
  "next_run": "2026-04-23T03:00:00Z"
}
```

---

## 📊 查看任务状态

### 健康检查端点

**URL**: `GET http://localhost:8080/health`

```bash
curl http://localhost:8080/health | jq .
```

**响应示例**：
```json
{
  "status": "healthy",
  "timestamp": "2026-04-23T15:50:00Z",
  "scheduler_running": true,
  "latest_report": "llm_decisions_20260423_030000.csv",
  "jobs": [
    {
      "id": "decision_pipeline",
      "name": "广告决策流程",
      "next_run": "2026-04-24T03:00:00Z"
    }
  ]
}
```

---

## 🔧 服务启动

### 本地启动

```bash
cd /Users/liulidong/project/agent/Agent/examples/auto_put_ad_mini

# 激活虚拟环境
source .venv/bin/activate

# 启动服务器
python server.py

# 或使用 uvicorn（生产环境）
uvicorn server:app --host 0.0.0.0 --port 8080 --reload
```

### Docker启动

```bash
# 构建镜像
docker build -t auto-put-ad-mini:latest .

# 运行容器
docker run -d \
  --name auto-put-ad-mini \
  --env-file .env \
  -p 8080:8080 \
  -v $(pwd)/outputs:/app/outputs \
  auto-put-ad-mini:latest
```

### Kubernetes部署

```bash
# 部署
kubectl apply -f k8s/deployment.yaml

# 查看Pod
kubectl get pods -n ad-automation

# 查看日志
kubectl logs -f -n ad-automation <pod-name>

# 端口转发（本地访问）
kubectl port-forward -n ad-automation svc/auto-put-ad-mini 8080:8080
```

---

## ⚙️ 高级配置

### 启动时立即执行

在数据库中设置 `run_on_startup = true`：

```sql
UPDATE system_config
SET config_value = 'true'
WHERE config_key = 'run_on_startup';
```

**效果**: 服务启动后立即执行一次决策流程（不等待定时任务触发）

### 禁用定时任务

方法1：暂停调度器（不推荐，会影响手动触发）

方法2：设置一个很晚的时间（如凌晨4点）
```sql
UPDATE system_config
SET config_value = '0 20 * * *'  -- UTC 20:00 = 北京时间 04:00
WHERE config_key = 'cron_schedule';
```

---

## 📝 日志查看

### 查看定时任务日志

```bash
# Docker容器
docker logs -f auto-put-ad-mini

# Kubernetes
kubectl logs -f -n ad-automation <pod-name>

# 查看特定时间的日志
kubectl logs -n ad-automation <pod-name> --since=1h
```

### 日志输出示例

```
2026-04-23 03:00:00 - INFO - [定时任务] 开始执行决策流程
2026-04-23 03:00:01 - INFO - ✅ 从数据库读取白名单配置：2 个账户
2026-04-23 03:00:05 - INFO - 拉取广告数据完成：100 个广告
2026-04-23 03:02:30 - INFO - AI决策完成：pause(10), bid_down(5), observe(85)
2026-04-23 03:02:35 - INFO - [定时任务] 决策流程执行完成
```

---

## ⚠️ 注意事项

1. **时区问题**
   - 服务器使用UTC时区
   - 数据库Cron表达式使用UTC时间
   - 北京时间 = UTC + 8小时

2. **并发控制**
   - 定时任务和手动触发不会并发执行
   - 如果任务正在运行，手动触发会返回"任务已在队列中"

3. **执行开关**
   - `execution_enabled = false`: 只分析不执行（安全模式）
   - `execution_enabled = true`: 真实执行广告操作（谨慎开启）

4. **配置修改生效**
   - 定时调度配置修改后，需要重启服务才能生效
   - 白名单和其他配置修改后，5分钟内自动生效（有缓存）

---

## 🆘 故障排查

### 问题1：定时任务没有执行

**检查步骤**：
1. 查看健康检查：`curl http://localhost:8080/health`
2. 确认调度器状态：`"scheduler_running": true`
3. 查看下次执行时间：`"next_run": "..."`
4. 检查数据库配置：`SELECT config_value FROM system_config WHERE config_key='cron_schedule'`

### 问题2：手动触发失败

**检查步骤**：
1. 确认服务正在运行：`curl http://localhost:8080/health`
2. 查看Pod日志：`kubectl logs -f <pod-name>`
3. 检查数据库连接：确认`.env`文件中的数据库配置正确

### 问题3：时间不对

**解决方法**：
1. 确认时区设置：Cron表达式使用UTC时间
2. 转换公式：北京时间 - 8 = UTC时间
3. 示例：北京时间11:00 → UTC 03:00 → Cron `0 3 * * *`

---

**最后更新**: 2026-04-23
**配置状态**: 每天北京时间11:00自动执行 ✅