69 lines
4.1 KiB
Markdown
69 lines
4.1 KiB
Markdown
# Writer Endpoints
|
||
|
||
## Purpose
|
||
Document writer API endpoints for tasks, content, images, and taxonomies, including bulk actions and AI content generation triggers.
|
||
|
||
## Code Locations (exact paths)
|
||
- Routing: `backend/igny8_core/modules/writer/urls.py`
|
||
- Views: `backend/igny8_core/modules/writer/views.py`
|
||
- Serializers: `backend/igny8_core/modules/writer/serializers.py`
|
||
- Services: `backend/igny8_core/business/content/services/content_generation_service.py`
|
||
|
||
## High-Level Responsibilities
|
||
- CRUD for writer entities scoped by account/site/sector.
|
||
- Provide bulk operations and AI content generation for tasks.
|
||
- Manage images and taxonomy terms linked to content/tasks.
|
||
|
||
## Detailed Behavior
|
||
- Base path: `/api/v1/writer/`
|
||
- Viewsets (inherit `SiteSectorModelViewSet`, throttled `writer`, paginated):
|
||
- `TasksViewSet` (`/tasks/`):
|
||
- Filters: status, cluster_id, content_type, content_structure; search title/keywords; ordering by title/created_at/status.
|
||
- Bulk: `bulk_delete`, `bulk_update` (status).
|
||
- `auto_generate_content`: accepts task IDs (max 10), requires account, enforces credit checks via `ContentGenerationService`, returns async task_id or synchronous result; 402 on insufficient credits.
|
||
- Create requires site_id/sector_id; validates site/sector alignment; sets account/site/sector explicitly.
|
||
- `ImagesViewSet` (`/images/`):
|
||
- Filters: task_id, content_id, image_type, status; ordering by created_at/position/id.
|
||
- perform_create enforces site/sector presence (from request or defaults), sets account/site/sector; serves local files via `file` action with existence checks.
|
||
- `ContentViewSet` (`/content/`):
|
||
- Filters/order/search defined in viewset (titles, status, etc.); manages taxonomy relationships; exposes status, SEO fields, cluster link, external IDs/URLs.
|
||
- `ContentTaxonomyViewSet` (`/taxonomies/`):
|
||
- CRUD for taxonomy terms (category/tag) scoped to site/sector.
|
||
- Serializers enforce required fields on create (e.g., cluster/content_type/content_structure for tasks; site/sector for content) and expose read-only derived fields (cluster/sector names, image/taxonomy info).
|
||
- Error handling: unified responses; validation errors return 400; missing resources return 404; `auto_generate_content` can return 402/500 on credits/other errors.
|
||
|
||
## Data Structures / Models Involved (no code)
|
||
- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, and related domain models; `Account`, `Site`, `Sector`.
|
||
|
||
## Execution Flow
|
||
- Requests → DRF auth → base viewset filtering (account/site/sector) → serializer validation → model save → unified response; bulk/AI actions invoke services.
|
||
|
||
## Cross-Module Interactions
|
||
- Planner clusters/ideas feed tasks; automation stages 3–6 operate on writer data; publishing/integration uses content/taxonomies/images.
|
||
- Billing credits enforced during AI content generation via `ContentGenerationService`.
|
||
|
||
## State Transitions
|
||
- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`.
|
||
|
||
## Error Handling
|
||
- Standard unified responses; credit errors mapped to 402 in `auto_generate_content`; file serving returns 404 for missing images.
|
||
|
||
## Tenancy Rules
|
||
- All endpoints scoped to account/site/sector; base viewset and permissions enforce access; admin/developer/system may bypass filtering but records retain tenant/site/sector fields.
|
||
|
||
## Billing Rules
|
||
- AI generation actions check/deduct credits via billing services; other CRUD does not alter credits.
|
||
|
||
## Background Tasks / Schedulers
|
||
- `auto_generate_content` may enqueue Celery AI tasks when returning task_id; automation uses writer endpoints indirectly via services.
|
||
|
||
## Key Design Considerations
|
||
- Strict site/sector validation on create; max 10 tasks per auto_generate_content to manage load/credits.
|
||
- Image file serving is permissive but guarded by existence checks.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Supply site_id/sector_id on create; use bulk actions for batch changes.
|
||
- When extending AI flows, keep credit checks and account/site scoping intact.
|
||
- Reuse existing viewsets/serializers for new fields; ensure filters/throttles stay aligned with module scope.
|
||
|