63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# 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.
|
||
|