Metadata-Version: 2.4
Name: django-simpletask5
Version: 0.1.1
Summary: Lightweight async task execution framework for Django
Author-email: rRR0VrFP <rrr0vrfp@qq.com>
Maintainer-email: rRR0VrFP <rrr0vrfp@qq.com>
License: MIT
Project-URL: homepage, https://gitee.com/rRR0VrFP/django-simpletask5
Keywords: django,async,task,queue,cron,background
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: globallock>=0.1.4
Requires-Dist: django-safe-fields>=0.2.3
Requires-Dist: django-app-requires>=0.3.6
Requires-Dist: django-admin-dashboards>=0.1.1
Requires-Dist: cryptography>=48.0.0
Requires-Dist: croniter>=6.2.2
Requires-Dist: requests>=2.34.2
Requires-Dist: kombu>=5.6.2
Requires-Dist: redis>=7.4.0
Requires-Dist: pyyaml>=6.0.3
Dynamic: license-file

# django-simpletask5

> 本项目由 opencode + deepseek-v4-flash 生成

一个轻量级的 Django 异步任务执行框架，提供声明式的任务模型、信号驱动的自动发布、Worker 进程异步执行，以及内置的 Cron 定时调度。

## 特性

- **声明式任务模型** — 继承 `Task` 模型即可定义任务，自动处理创建/更新/删除事件
- **信号驱动** — Django 信号自动拦截模型变更，发布 `TaskExecution` 到消息队列
- **自定义事件** — 通过 `task.trigger('event_name')` 触发任意事件
- **灵活的执行器映射** — 不同事件可绑定不同的执行器类
- **队列路由** — 不同事件可路由到不同优先级队列
- **重试与超时** — 失败自动重试（指数退避），支持超时检测
- **加密字段** — 敏感数据自动加密存储
- **Cron 调度** — 内置 crontab 守护进程，支持代码注册与数据库覆盖
- **归档统计** — 已完成执行记录自动归档为加密 JSONL，并生成日统计
- **Worker 注册中心** — 基于 Redis 的 Worker 心跳与状态追踪
- **Django Admin 集成** — 完整的后台管理界面

## 依赖

- Python >= 3.8
- Django >= 3.2（兼容至 5.2.x）
- Kombu >= 5.3.0（消息队列，支持 RabbitMQ/Redis/内存）
- Redis >= 4.0.0（分布式锁、Worker 注册中心）
- 详见 `pyproject.toml`

## 安装

```bash
pip install django-simpletask5
```

`django-simpletask5` 使用 [django-app-requires](https://pypi.org/project/django-app-requires/) 自动管理依赖的 app（如 `django_safe_fields`），无需手动添加到 `INSTALLED_APPS`。只需在 `settings.py` 中调用一次 patch：

```python
from django_app_requires import patch_all as django_app_requires_patch_all
django_app_requires_patch_all()
```

然后在 `INSTALLED_APPS` 中添加：

```python
INSTALLED_APPS = [
    ...
    'django_simpletask5',
]
```

配置分布式锁：

```python
DJANGO_SIMPLETASK_LOCK_CONFIG = {
    'global_lock_engine_class': 'globallock.redis_global_lock.RedisGlobalLock',
    'global_lock_engine_options': {
        'host': '127.0.0.1',
        'port': 6379,
        'db': 0,
    },
}
```

运行迁移：

```bash
python manage.py migrate django_simpletask5
```

## 快速开始

### 1. 定义任务模型

```python
from django.db import models
from django_simpletask5.models import Task

class OrderTask(Task):
    order_id = models.CharField(max_length=64, unique=True)
    customer_name = models.CharField(max_length=128)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    status = models.CharField(max_length=32, default='pending')

    executor_class = {
        'create': 'myapp.executors.OrderCreateExecutor',
        'update': 'myapp.executors.OrderUpdateExecutor',
        'delete': 'myapp.executors.OrderDeleteExecutor',
    }

    simpletask_queue = {
        'create': 'django_simpletask5.queue.high_priority',
        'update': 'django_simpletask5.queue.default',
        'delete': 'django_simpletask5.queue.default',
    }

    trigger_update_fields = ['customer_name', 'amount', 'status']
```

### 2. 编写执行器

```python
# myapp/executors.py
from django_simpletask5.executors.base import BaseExecutor
from django_simpletask5.models import TaskExecution

class OrderCreateExecutor(BaseExecutor):
    def execute(self, execution: TaskExecution) -> str | None:
        context = execution.get_context_dict()
        # 业务逻辑...
        return 'ok'
```

### 3. 启动 Worker

默认只监听 `default` 队列，`high_priority` 队列需要单独启动 Worker 处理。

```bash
# 启动 4 个 Worker 处理 default 队列
python manage.py django_simpletask_executor --workers 4

# 单独启动 Worker 处理 high_priority 队列
python manage.py django_simpletask_executor --queue django_simpletask5.queue.high_priority

# 指定执行器
python manage.py django_simpletask_executor --workers 2 --service myapp.executors.OrderCreateExecutor
```

### 4. 启动 Cron 调度

```bash
python manage.py django_simpletask_crontab
```

### 5. 触发自定义事件

```python
order = OrderTask.objects.get(order_id='ORD-001')
order.trigger('refund', extra_context={'refund_amount': '50.00'})
```

## Cron 任务

### 在代码中定义 Cron 任务

在任意 app 的 `cronjobs.py` 文件中使用 `register_cronjob` 注册：

```python
# myapp/cronjobs.py
from django_simpletask5.cronjob_registry import register_cronjob

register_cronjob(
    name='health_check',
    cron_expression='*/5 * * * *',
    executor_class='django_simpletask5.executors.simple_request.SimpleRequestExecutor',
    context={
        'url': 'https://example.com/health',
        'method': 'GET',
        'timeout': 10,
    },
    description='定期健康检查',
)
```

### 从代码同步到数据库

注册的 Cron 任务需要同步到数据库才会生效。框架默认在 `django_simpletask_crontab` 启动时自动同步（可通过 `DJANGO_SIMPLETASK_CRONJOB_AUTO_SYNC = False` 关闭），也可以手动执行：

```bash
python manage.py django_simpletask_sync_cronjobs
```

同步后，用户可以在 Django Admin 中查看和修改 Cron 任务，被手动修改过的任务不会在后续同步中被覆盖（`is_modified_by_user` 标记保护）。

## 内置执行器

| 执行器 | 说明 |
|---|---|
| `PingPongExecutor` | 健康检查，返回 `'pong'` |
| `BashScriptExecutor` | 执行 Shell 脚本 |
| `PythonScriptExecutor` | 执行 Python 代码 |
| `SimpleRequestExecutor` | 发起 HTTP 请求 |
| `StatusCheckExecutor` | 检测卡住的执行并标记超时（每 5 分钟） |
| `RetryTimeoutExecutor` | 重试超时的执行（每 10 分钟） |
| `ArchiveExecutor` | 归档已完成执行并生成统计（每天凌晨 2 点） |

## 架构

```
Task 模型变更 → Django 信号 → 创建 TaskExecution 并发布到消息队列
                                                    ↓
Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保存结果
                                                    ↓
失败时自动重试，完成后归档
```

## Releases

### 0.1.0

这是 django-simpletask5 的首个正式版本。核心功能包括：

- **声明式任务模型** — 继承 `Task` 模型即可定义任务，自动处理创建/更新/删除事件
- **信号驱动自动发布** — Django 信号自动拦截模型变更，发布 `TaskExecution` 到消息队列
- **Worker 异步执行** — 多 Worker 进程消费消息队列，支持队列路由和优先级
- **Cron 定时调度** — 内置 crontab 守护进程，支持代码注册与数据库覆盖
- **重试与超时** — 失败自动重试（指数退避），支持超时检测
- **加密字段** — 敏感数据自动加密存储
- **归档统计** — 已完成执行记录自动归档为加密 JSONL，并生成日统计
- **Worker 注册中心** — 基于 Redis 的 Worker 心跳与状态追踪
- **Django Admin 集成** — 完整的后台管理界面与仪表盘

### 0.1.1

- **修复**: 修复 `DjangoSimpletask5Config` 缺少 `ready()` 方法导致信号监听未注册的问题

## 许可证

MIT
