docs re-org

docs/20-API/AUTOMATION-ENDPOINTS.md

@@ -0,0 +1,65 @@
+# 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.
+