70 lines
4.8 KiB
Markdown
70 lines
4.8 KiB
Markdown
# Planner Models and Flow
|
||
|
||
## Purpose
|
||
Provide a detailed view of planner models, their constraints, and how planner CRUD/bulk operations move data toward the writer pipeline.
|
||
|
||
## Code Locations (exact paths)
|
||
- Models: `backend/igny8_core/business/planning/models.py`
|
||
- Serializers: `backend/igny8_core/modules/planner/serializers.py`
|
||
- Views: `backend/igny8_core/modules/planner/views.py`
|
||
- Services: `backend/igny8_core/business/planning/services/clustering_service.py`, `ideas_service.py`
|
||
|
||
## High-Level Responsibilities
|
||
- Maintain tenant/site/sector-scoped planner entities (Keywords, Clusters, ContentIdeas) backed by global SeedKeywords.
|
||
- Enforce industry/sector alignment and uniqueness within site/sector.
|
||
- Support search, filtering, ordering, and bulk operations for planner data.
|
||
- Feed automation and writer tasks with curated ideas and clusters.
|
||
|
||
## Detailed Behavior
|
||
- Models:
|
||
- `Keywords`: links to `SeedKeyword`; overrides for volume/difficulty; optional cluster; status `new/mapped`; disabled flag; validation ensures seed keyword industry matches site industry and seed sector matches site sector’s industry sector; unique per site/sector and seed keyword; soft-delete enabled.
|
||
- `Clusters`: topic groups with counts, volume, mapped_pages, status `new/mapped`; unique per site/sector by name; soft-delete enabled.
|
||
- `ContentIdeas`: status `new/queued/completed`, content_type/structure choices, estimated word count, optional keyword objects M2M, keyword_cluster FK; soft-delete enabled.
|
||
- Viewsets:
|
||
- `KeywordViewSet`: search by seed_keyword.keyword; filter by status, cluster, seed intent; ordering by created_at, seed volume/difficulty; custom range filters for difficulty/volume; requires site_id/sector_id on create; bulk_delete; two `bulk_update` actions (status); `bulk_add_from_seed` to create Keywords from SeedKeywords with site/sector validation.
|
||
- `ClusterViewSet`: site/sector filtered; CRUD; status updates; inherits filtering from base with developer/admin/system override.
|
||
- `ContentIdeasViewSet`: CRUD; filters by status/cluster; requires site_id/sector_id on create.
|
||
- Serializers:
|
||
- `KeywordSerializer` demands `seed_keyword_id` on create; derives read-only keyword/volume/difficulty/intent from seed; supports volume/difficulty overrides; exposes cluster/sector names; write-only site_id/sector_id.
|
||
- `ClusterSerializer` exposes sector name; write-only site_id/sector_id; counts/volume/mapped_pages read-only.
|
||
- `ContentIdeasSerializer` exposes cluster/sector names; write-only site_id/sector_id.
|
||
- Services:
|
||
- `ClusteringService` and `IdeasService` (not expanded here) are used by automation/AI flows for clustering and idea generation.
|
||
|
||
## Execution Flow
|
||
- Planner CRUD/bulk requests → DRF auth → `SiteSectorModelViewSet` filtering → serializer validation (seed/site/sector) → model save → unified response.
|
||
- Bulk operations act on the filtered queryset (account/site/sector scoped).
|
||
- Automation stages 1–3 consume planner data and advance statuses.
|
||
|
||
## Cross-Module Interactions
|
||
- Writer tasks and content reference clusters/ideas; automation transforms planner data into tasks/content/images.
|
||
- Billing credit checks occur in automation/AI calls that process planner entities.
|
||
|
||
## State Transitions
|
||
- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
|
||
- Disabled flag excludes records from automation queries.
|
||
|
||
## Error Handling
|
||
- Validation errors for missing site/sector or seed keyword; industry/sector mismatch raises validation errors in `Keywords`.
|
||
- Bulk operations return 400 when IDs/status missing; generic errors return unified 500 responses.
|
||
|
||
## Tenancy Rules
|
||
- All planner models inherit tenant/site/sector fields; base viewsets filter accordingly. Admin/developer/system accounts can bypass filtering; persisted data retains tenant/site/sector ownership.
|
||
- Create paths require explicit site/sector; account set from site/user/middleware.
|
||
|
||
## Billing Rules
|
||
- Planner endpoints do not directly deduct credits; AI-based clustering/idea generation uses billing when invoked via services/automation.
|
||
|
||
## Background Tasks / Schedulers
|
||
- None in planner endpoints; automation runs stages asynchronously using planner data.
|
||
|
||
## Key Design Considerations
|
||
- Strict site/sector + seed alignment prevents cross-site contamination.
|
||
- Read-only seed-derived fields avoid drift while allowing per-site overrides.
|
||
- Bulk endpoints and range filters support large keyword sets efficiently.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Use existing serializers/viewsets to add fields or validations; keep site/sector required on create.
|
||
- When adding AI-powered planner actions, ensure credit checks go through billing services and queries respect tenant/site/sector scoping.
|
||
- Clean up duplicate `bulk_update` definitions if extending bulk behaviors to avoid route collisions.
|