Metadata-Version: 2.5
Name: pulse-task
Version: 0.1.0
Summary: PulseTask — FastAPI task scheduler backed by SQLite and APScheduler
Requires-Python: >=3.10
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.30
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# PulseTask

轻量级、跨平台（Linux / Windows）的任务调度系统：Web 界面 + REST API + CLI 三种使用方式。

通过 Web 界面配置脚本任务的运行规则，支持按时间间隔、Crontab 触发或手动执行，提供任务管理、运行历史、日志查看等能力。

## 技术栈

| 层级 | 选型 |
|------|------|
| 前端 | 原生 HTML + Tailwind CSS + JS（无构建依赖，随包分发） |
| 后端 | Python 3.10+ / FastAPI |
| 调度 | APScheduler（interval / cron / manual） |
| 存储 | SQLite（WAL 模式，零配置） |

## 功能特性

- **触发方式**：固定间隔 / Crontab 表达式（UTC）/ 手动执行
- **执行控制**：超时强制终止整个进程树、失败自动重试、按任务并发锁（同一任务不重复执行，不同任务并行运行）
- **Web 界面**：仪表盘统计、任务列表（搜索/筛选）、弹窗式新建/编辑任务、运行历史分页、终端风格日志查看（自动滚动到底部）
- **REST API**：完整任务生命周期管理，内置 Swagger 文档（`/docs`）
- **CLI 启动**：支持 `--host` / `--port` / `--db` / `--reload` 等参数
- **单 wheel 分发**：`pip install` 后前端随包携带，开箱即用

## 快速开始

```bash
# 安装（任选其一；Python 包导入名为 pulsetask）
pip install pulse-task                      # pip
uv tool install pulse-task                  # uv，作为全局命令安装

# 从源码安装（开发模式）
uv venv .venv && uv pip install -e ".[dev]"

# 启动服务（默认 http://127.0.0.1:8000）
pulse-task
```

浏览器打开 <http://127.0.0.1:8000> 即可使用；API 文档在 <http://127.0.0.1:8000/docs>。

免安装直接运行：`uvx pulse-task`。

## CLI 参数

```bash
pulse-task [--host HOST] [--port PORT] [--db PATH] [--ui DIR] [--reload] [--log-level LEVEL] [--version]
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--host` | `127.0.0.1` | 监听地址（环境变量 `HOST` 可改默认值） |
| `--port` | `8000` | 监听端口（环境变量 `PORT` 可改默认值） |
| `--db` | `<项目根>/pulsetask.db` | SQLite 数据库路径（等价于 `PULSETASK_DB`） |
| `--ui` | 包内 `ui/` 目录 | 前端静态页面目录（等价于 `PULSETASK_UI`） |
| `--reload` | 关闭 | 开发模式：代码变更自动重启 |
| `--log-level` | `info` | critical / error / warning / info / debug / trace |
| `--version` | — | 查看版本 |

等价入口：`python -m pulsetask`。也可 `uvicorn pulsetask.app:app` 直接启动（此时 `--db` / `--ui` 需用环境变量）。

## API 概览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/dashboard` | 仪表盘统计 |
| GET | `/api/tasks` | 任务列表（`search` / `enabled` / `trigger_type` 过滤） |
| POST | `/api/tasks` | 创建任务 |
| GET / PATCH / DELETE | `/api/tasks/{id}` | 任务详情 / 部分更新 / 删除 |
| POST | `/api/tasks/{id}/enable` `/disable` `/run` | 启用 / 禁用 / 立即执行 |
| GET | `/api/tasks/{id}/history?limit=&offset=` | 运行历史（分页） |
| GET | `/api/tasks/{id}/logs?run_id=` | 运行日志 |
| GET | `/api/runs?limit=&offset=` | 全局运行记录（分页） |

## 项目结构

```
PulseTask/
├── README.md                # 本文档
├── DESIGN.md                # 设计文档（架构 / 数据库 / API / 页面）
├── pyproject.toml
├── docs/ui-design/          # UI 设计阶段产物存档（不参与运行）
├── src/pulsetask/
│   ├── app.py               # FastAPI 应用组装
│   ├── cli.py               # 命令行入口
│   ├── api.py               # /api 路由
│   ├── config.py            # 配置解析
│   ├── schemas.py           # 请求模型
│   ├── database.py          # SQLite 数据访问层
│   ├── scheduler.py         # 调度与命令执行
│   └── ui/pages/            # 前端静态页面 + 共享弹窗组件
└── pulsetask.db             # SQLite 数据库（首次运行自动创建）
```

## 开发

```bash
.venv/Scripts/ruff.exe check src        # 代码检查
.venv/Scripts/python.exe -m mypy        # 类型检查（strict）
uv build                                # 构建 wheel / sdist 到 dist/
```
