docs re-org

docs/20-API/PLANNER-ENDPOINTS.md

@@ -0,0 +1,62 @@
+# Planner Endpoints
+
+## Purpose
+Document planner API endpoints for keywords, clusters, and content ideas, including filters, bulk actions, and validation rules.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/planner/urls.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+
+## High-Level Responsibilities
+- CRUD for planner entities scoped by account/site/sector with search, filtering, ordering, and bulk operations.
+- Enforce site/sector requirements and seed keyword alignment on creation.
+
+## Detailed Behavior
+- Base path: `/api/v1/planner/`
+- Viewsets (all inherit `SiteSectorModelViewSet`, scoped by account/site/sector, throttled with scope `planner`, paginated):
+  - `KeywordViewSet` (`/keywords/`):
+    - Search: `seed_keyword__keyword`.
+    - Filters: status, cluster_id, seed_keyword intent/id; custom difficulty_min/max and volume_min/max (uses overrides or seed values).
+    - Ordering: created_at, seed volume/difficulty.
+    - Bulk: `bulk_delete`, `bulk_update` (status), `bulk_add_from_seed` (create Keywords from SeedKeywords after validating site/sector).
+    - Create requires site_id and sector_id; validates site/sector existence and alignment.
+  - `ClusterViewSet` (`/clusters/`):
+    - Filters: status; standard CRUD; site/sector required on create.
+  - `ContentIdeasViewSet` (`/ideas/`):
+    - Filters: status, cluster; standard CRUD; site/sector required on create.
+- Serializers enforce required fields on create (`KeywordSerializer` requires seed_keyword_id; site/sector write-only), expose read-only seed-derived fields and cluster/sector names.
+- Error handling: unified responses; validation errors for missing site/sector/seed; bulk actions return 400 when IDs/status missing.
+
+## Data Structures / Models Involved (no code)
+- `Keywords`, `Clusters`, `ContentIdeas`, `SeedKeyword`, plus `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filters (account/site/sector) → serializer validation → model save → unified response; bulk actions operate on filtered queryset.
+
+## Cross-Module Interactions
+- Feeds automation Stage 1–3 and writer tasks/content generation.
+- Billing credits may be checked upstream when AI clustering/idea generation is invoked.
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+
+## Error Handling
+- Missing required IDs or validation failures return 400; unified 500 on unhandled errors.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector via base viewset; admin/developer/system roles can bypass filtering, but data retains tenant/site/sector fields.
+
+## Billing Rules
+- No direct deductions in these endpoints; AI clustering/idea generation costs enforced where services are called.
+
+## Background Tasks / Schedulers
+- None in planner endpoints; automation handles async flows.
+
+## Key Design Considerations
+- Strict site/sector requirements prevent cross-site contamination.
+- Seed linkage keeps keyword metadata consistent; overrides allow site-specific tuning.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes; extend filters/search/order as needed while respecting base scoping.
+