66 lines
3.8 KiB
Markdown
66 lines
3.8 KiB
Markdown
# Automation Endpoints
|
||
|
||
## Purpose
|
||
Describe automation API endpoints that configure, trigger, monitor, and control automation runs.
|
||
|
||
## Code Locations (exact paths)
|
||
- Routing: `backend/igny8_core/business/automation/urls.py`
|
||
- Views: `backend/igny8_core/business/automation/views.py`
|
||
- Services/Tasks: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`, `backend/igny8_core/business/automation/tasks.py`
|
||
|
||
## High-Level Responsibilities
|
||
- Expose configuration CRUD (get/update) and operational controls (run, pause, resume, cancel).
|
||
- Provide run history, status, logs, pipeline overview, credit estimate, and current processing state.
|
||
- Enforce site/account scoping and authentication.
|
||
|
||
## Detailed Behavior
|
||
- Base path: `/api/v1/automation/`
|
||
- Key endpoints (actions on `AutomationViewSet`):
|
||
- `GET config?site_id=` → get/create `AutomationConfig` for site (includes batch sizes, delays, schedule, flags, last/next run).
|
||
- `PUT update_config?site_id=` → update config fields (enable, frequency, scheduled_time, batch sizes, delays).
|
||
- `POST run_now?site_id=` → start a run (checks locks/credits) and enqueue Celery `run_automation_task`.
|
||
- `GET current_run?site_id=` → current running/paused run details with per-stage results and totals.
|
||
- `GET history?site_id=` → last 20 runs with status and timestamps.
|
||
- `GET logs?run_id=&lines=` → tail of automation log file for run.
|
||
- `GET estimate?site_id=` → estimated credits required plus current balance and sufficiency flag (1.2× buffer).
|
||
- `GET pipeline_overview?site_id=` → counts/pending by stage across planner/writer models.
|
||
- `GET current_processing?site_id=&run_id=` → live processing state for active run.
|
||
- `POST pause?run_id=` / `POST resume?run_id=` / `POST cancel?run_id=` → control run state (pause/resume/cancel).
|
||
- Permissions/tenancy: `IsAuthenticated`; site fetched with `account=request.user.account`; automation lock is per site; `request.account` set by middleware.
|
||
|
||
## Data Structures / Models Involved (no code)
|
||
- `AutomationConfig`, `AutomationRun`, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images).
|
||
|
||
## Execution Flow
|
||
- View actions call `AutomationService` to start/control runs; long-running work executed by Celery tasks (`run_automation_task`, `resume_automation_task`).
|
||
- Config updates persist to DB; run state and logs updated as stages progress.
|
||
|
||
## Cross-Module Interactions
|
||
- Uses planner/writer data for counts and processing; AI functions run inside service; billing credits checked via account balance before start and inferred from AI task logs during execution.
|
||
|
||
## State Transitions
|
||
- Run status: running ↔ paused → completed/failed/cancelled; `current_stage` advances per stage; per-stage results stored in `AutomationRun`.
|
||
- Config `last_run_at`/`next_run_at` updated on scheduled runs.
|
||
|
||
## Error Handling
|
||
- Missing site_id/run_id → 400; run not found → 404; insufficient credits or concurrent run → 400; server errors → 500.
|
||
- Logs endpoint 404s when run missing.
|
||
|
||
## Tenancy Rules
|
||
- All operations scoped to the authenticated user’s account/site; no cross-tenant access; locks are per site.
|
||
|
||
## Billing Rules
|
||
- Start requires credits ≥ estimated * 1.2; credits consumed by AI tasks are recorded via AI task logs and aggregated per stage.
|
||
|
||
## Background Tasks / Schedulers
|
||
- Celery tasks for scheduled runs (`check_scheduled_automations`) and pipeline execution/resume.
|
||
|
||
## Key Design Considerations
|
||
- Cooperative pause/resume/cancel with persisted partial results.
|
||
- Log access via filesystem tail; structured per-stage results stored in DB for quick status reads.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Trigger runs via `run_now`; avoid bypassing locks/credit checks.
|
||
- Extend actions by reusing `AutomationService` and Celery tasks; keep site scoping and error handling consistent.
|
||
|