From 6310ef2d3201bf3100c404833142b9142f059f1e Mon Sep 17 00:00:00 2001
From: wangqifan <wangqifan@zhiyun.com>
Date: Fri, 28 Nov 2025 17:37:56 +0800
Subject: [PATCH] first commit

---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..601e0be
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# API Scheduler Platform
+
+Flask + MySQL 示例项目，实现登录、API 配置管理、定时调用与日志查看。APScheduler 被选用作为定时调度器，因其 API 简洁、支持 cron/interval/daily 场景，并与 Flask-APScheduler 集成方便。
+
+## 主要特性
+- 用户登录后才能访问（Flask-Login）。
+- API 配置 CRUD，启用/停用自动同步调度。
+- APScheduler 后台定时调用外部 API，支持重试、超时。
+- 调用日志记录与过滤分页查看。
+- Jinja2 + Bootstrap 简易界面。
+
+## 环境准备
+1. 安装依赖
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Windows: venv\Scripts\activate
+   pip install -r requirements.txt
+   ```
+2. 配置环境变量（示例）
+   ```bash
+   set DATABASE_URL=mysql+pymysql://user:password@localhost:3306/api_scheduler
+   set SECRET_KEY=replace-me
+   set FLASK_ENV=development  # 或 production
+   ```
+
+## 数据库初始化
+- 使用 Flask-Migrate：
+  ```bash
+  flask db init
+  flask db migrate -m "init"
+  flask db upgrade
+  ```
+- 或手动建表（简化示例）：
+  ```sql
+  CREATE TABLE users (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    username VARCHAR(64) UNIQUE NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    email VARCHAR(128),
+    role VARCHAR(32),
+    is_active BOOLEAN DEFAULT TRUE,
+    created_at DATETIME,
+    updated_at DATETIME
+  );
+  CREATE TABLE api_configs (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    name VARCHAR(128) NOT NULL,
+    description TEXT,
+    url VARCHAR(512) NOT NULL,
+    http_method VARCHAR(10) NOT NULL,
+    headers TEXT,
+    query_params TEXT,
+    body TEXT,
+    enabled BOOLEAN DEFAULT TRUE,
+    schedule_type VARCHAR(32) NOT NULL,
+    schedule_expression VARCHAR(128) NOT NULL,
+    timeout_seconds INT,
+    retry_times INT,
+    retry_interval_seconds INT,
+    created_by INT,
+    created_at DATETIME,
+    updated_at DATETIME
+  );
+  CREATE TABLE api_call_logs (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    api_id INT NOT NULL,
+    request_time DATETIME NOT NULL,
+    response_time DATETIME,
+    success BOOLEAN,
+    http_status_code INT,
+    error_message TEXT,
+    response_body TEXT,
+    duration_ms INT,
+    created_at DATETIME,
+    updated_at DATETIME
+  );
+  ```
+
+## 创建初始管理员
+在 Python shell 中：
+```python
+from app import create_app
+from app.extensions import db
+from app.models import User
+
+app = create_app()
+with app.app_context():
+    admin = User(username="admin", is_active=True)
+    admin.set_password("admin123")
+    db.session.add(admin)
+    db.session.commit()
+```
+
+## 运行
+- 开发模式：
+  ```bash
+  flask --app run.py --debug run
+  ```
+- 简易生产（示例）：
+  ```bash
+  gunicorn "run:app" -w 4 -b 0.0.0.0:8000
+  ```
+- 若在执行 `flask db ...` 迁移命令时数据库还未建表，可先禁用调度器避免表不存在报错：
+  ```bash
+  set FLASK_SKIP_SCHEDULER=1
+  flask db upgrade
+  ```
+  迁移完成后删除该变量或设为 0。
+
+## 调度说明
+- 任务 ID: `api_job_<api_id>`.
+- schedule_type:
+  - `cron`: 使用 `schedule_expression` 的 crontab 表达式。
+  - `interval`: `schedule_expression` 为秒数。
+  - `daily`: `schedule_expression` 形如 `HH:MM`.
+- 新增/编辑/启用 会创建或替换任务；停用/删除 会移除任务。
+- 默认时区为中国标准时间（Asia/Shanghai），可通过环境变量 `APP_TIMEZONE` 修改。
+
+## 其他
+- 日志表目前只记录最终一次尝试结果，减少噪音。需要每次尝试都记录时，可在 `execute_api` 中调整。
+- 响应体截断到前 2000 字符。