# 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.